Docs: Mention Vite publicDir interference

[Sidnioulz]

What I did

Short term fix for #24627 until the issue can be addressed, as it could involve breaking changes.

Checklist for Contributors

Testing

N/A

Manual testing

N/A, docs. Visit http://localhost:3000/docs/api/main-config/main-config-static-dirs for outcome:

Documentation

N/A

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Documentation
  • Clarified how Vite-based frameworks may copy extra static directories into build output and added informational callouts explaining this behavior.
  • Explained how to disable the behavior by setting Vite's publicDir to false, and preserved existing configuration guidance for static assets.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Added informational callouts to documentation explaining that Vite-based frameworks may copy extra directories to build output due to Vite's static asset handling, and that disabling this behavior is possible by setting Vite's publicDir to false.

Changes

Cohort / File(s)	Summary
Documentation - static dirs guidance docs/api/main-config/main-config-static-dirs.mdx, docs/configure/integration/images-and-assets.mdx	Inserted informational Callout blocks after static asset examples describing Vite-specific behavior (extra directories copied to build) and how to disable it by setting Vite's publicDir to false. Minor formatting adjustments preserved existing content structure.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jonniebigodes]

@Sidnioulz thanks for taking the time to put together this pull request and helping us improve the documentation with this interesting caveat. Appreciate it 🙏 ! I left one small item for you to look into when you can.

Let me know once you've addressed it and will be more than glad to merge this and get the docs updated.

Have a great day

Stay safe

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4403440 and a93ebeb.

📒 Files selected for processing (2)

• docs/api/main-config/main-config-static-dirs.mdx
• docs/configure/integration/images-and-assets.mdx

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-12-22T22:03:40.123Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-22T22:03:40.123Z
Learning: Applies to {code/addons,code/frameworks}/**/README.md : Update README files for significant changes and include code examples in addon/framework documentation

Applied to files:

• docs/api/main-config/main-config-static-dirs.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Core Unit Tests, windows-latest

🔇 Additional comments (1)

docs/configure/integration/images-and-assets.mdx (1)

58-60: Good placement for visibility.

The duplicate callout here improves discoverability, as requested in the previous review discussion. Same verification concerns apply as noted in docs/api/main-config/main-config-static-dirs.mdx.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

Vite publicDir option documentation behavior

💡 Result:

Summary — Vite publicDir behavior (concise)

• What it is: publicDir (type string | false, default "public") points to a directory of plain static assets. Files there are served at / during dev and copied as-is to the root of outDir during build. They are not transformed. (v3.vitejs.dev)

• Config values: a path (absolute or relative to project root) or false to disable the feature. (v3.vitejs.dev)

• Usage notes/quirk: public assets must be referenced with root-absolute paths (e.g. /favicon.ico). Also note that in dev mode Vite historically serves files from the project root as well (so files outside publicDir can be reachable in dev), which can mask missing/incorrect references and has been discussed in the Vite repo. (v3.vitejs.dev)

If you want specific examples or how to set publicDir in vite.config.ts, tell me which format (JS/TS) you use.

Citations:

• 1: https://v3.vitejs.dev/config/shared-options.html?utm_source=openai
• 2: https://v3.vitejs.dev/config/shared-options.html?utm_source=openai
• 3: https://v3.vitejs.dev/guide/assets.html?utm_source=openai

---

🌐 Web query:

Vite static asset handling public directory

💡 Result:

Summary — Vite public directory (static assets)

• Purpose: place files that should be served/copied as-is (robots.txt, favicons, executables) or must keep exact filenames (no hashing). [1][2]
• Location: defaults to /public. Configurable with the publicDir option (string | false). [2]
• Dev vs build: served at root (/) in dev and copied to the dist root during build without transforms or hashing. Reference them with a root-absolute path (e.g. /icon.png). [1][2]
• Import behavior: assets in public cannot be imported from JS/CSS. To get hashed/optimized URLs you must import the asset from source (e.g. import img from './img.png'). [1][3]
• Notes: set the Vite base option when deploying to a subpath so absolute public paths resolve correctly. [3]

Sources: Vite docs — Static Asset Handling and config (publicDir). [1][2][3]

---

🌐 Web query:

Storybook Vite static directories configuration publicDir

💡 Result:

Short answer: Use Storybook's staticDirs in .storybook/main.js|ts for static assets (served at /path), and — if you need Vite's publicDir behavior — set Vite's publicDir inside the Vite config that Storybook uses (via core.builder.viteConfigPath or viteFinal). Example patterns:

1. Simple Storybook staticDirs (recommended for Storybook-only assets)

• .storybook/main.ts
  • staticDirs: ['../public', '../static']
  • or object form: staticDirs: [{ from: '../my-assets', to: '/assets' }].
    (Storybook serves files at the given "to" path; reference assets with absolute paths like /image.png). [1][2]

2. If you need Vite's publicDir (serve/copy as Vite does), set publicDir in Vite config and tell Storybook to use it:

• Option A — point Storybook to a custom Vite config:
  • core: { builder: { name: '@storybook/builder-vite', options: { viteConfigPath: '../vite.config.js' } } }
  • In ../vite.config.js export defineConfig({ publicDir: 'public-vite' })
• Option B — modify Vite config via viteFinal in .storybook/main.ts:
  • async viteFinal(config) { config.publicDir = path.resolve(__dirname, '../public-vite'); return config; }
    This uses Vite's publicDir semantics (served at / and copied to dist) so assets behave like Vite's public directory. [3][2]

References:

• Storybook staticDirs docs. [1]
• Storybook Vite builder / viteFinal docs. [2]
• Vite publicDir docs. [3]

If you want, tell me which behavior you need (Storybook-only staticDirs vs full Vite publicDir) and I’ll give the exact file snippets for your project.

---

Add context on how to configure Vite's publicDir option in Storybook.

The technical information is accurate—setting publicDir: false does prevent Vite's automatic directory copying. However, readers need clarification on where to apply this configuration. In Storybook, this must be set via viteFinal in .storybook/main.ts (or the Vite config Storybook uses). Consider extending the callout to include a brief example: async viteFinal(config) { config.publicDir = false; return config; } or a link to Storybook's Vite builder documentation.

🤖 Prompt for AI Agents

In docs/api/main-config/main-config-static-dirs.mdx around lines 20 to 22, the
callout about disabling Vite's publicDir needs guidance on where to set this in
Storybook; update the text to say that you must set publicDir via Storybook's
Vite config (e.g., in .storybook/main.ts using the viteFinal hook) and include a
brief inline example snippet of the viteFinal function showing publicDir =
false, or alternatively add a link to Storybook's Vite builder docs for
configuration details.