diff --git a/docs/latest/concepts/static-files.md b/docs/latest/concepts/static-files.md index 45791833835..d44d68fe9ef 100644 --- a/docs/latest/concepts/static-files.md +++ b/docs/latest/concepts/static-files.md @@ -16,6 +16,32 @@ const app = new App() .use(staticFiles()); ``` +## Imported assets vs static files + +When using Fresh with Vite (now the default), **files that you import in your +JavaScript/TypeScript code should not be placed in the `static/` folder**. This +prevents file duplication during the build process. + +```tsx client.ts +// ❌ Don't import from static/ +import "./static/styles.css"; + +// ✅ Import from outside static/ (e.g., assets/) +import "./assets/styles.css"; +``` + +**Rule of thumb:** + +- Files **imported in code** (CSS, icons, etc.) → Place outside `static/` (e.g., + in an `assets/` folder) +- Files **referenced by URL path** (favicon.ico, fonts, robots.txt, PDFs, etc.) + → Place in `static/` + +When you import a file in your code, Vite processes it through its build +pipeline, optimizes it, and adds a content hash to the filename for cache +busting. Keeping these files outside `static/` ensures they're only included +once in your build output. + ## Caching headers By default, Fresh adds caching headers for the `src` and `srcset` attributes on