Skip to content

Docs: Mention Vite publicDir interference #33438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonniebigodes merged 3 commits into from
Jan 4, 2026
Merged

Docs: Mention Vite publicDir interference #33438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
18a16a1
Docs: Mention Vite publicDir interference
Sidnioulz Dec 29, 2025
a93ebeb
Docs: Mention Vite publicDir interference
Sidnioulz Dec 30, 2025
3eb4a07
Merge branch 'next' into sidnioulz/issue-24627-short-term
jonniebigodes Jan 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/api/main-config/main-config-static-dirs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ Sets a list of directories of [static files](../../configure/integration/images-

{/* prettier-ignore-end */}

<Callout variant="info">
When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior.
</Callout>
Comment thread
Sidnioulz marked this conversation as resolved.
Comment on lines +20 to +22

@coderabbitai coderabbitai Bot Dec 30, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 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:

🌐 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]
  1. 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.


## With configuration objects

You can also use a configuration object to define the directories:
Expand All @@ -25,4 +29,4 @@ You can also use a configuration object to define the directories:

<CodeSnippets path="main-config-static-dirs-with-object.md" />

{/* prettier-ignore-end */}
{/* prettier-ignore-end */}
4 changes: 4 additions & 0 deletions docs/configure/integration/images-and-assets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ Or even use a configuration object to define the directories:

{/* prettier-ignore-end */}

<Callout variant="info">
When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior.
</Callout>

## Reference assets from a CDN

Upload your files to an online CDN and reference them. In this example, we’re using a placeholder image service.
Expand Down