{"id":22949,"library":"vite-static-assets-plugin","title":"Vite Static Assets Plugin","description":"A Vite plugin (v1.2.2) that automatically scans a static assets directory (default: public), generates a TypeScript module with type-safe asset paths, directory-aware types, and a helper function for URLs. Supports recursive scanning, live HMR updates, and build-time validation. Differentiators: zero-config type generation, directory-aware generics (FilesInFolder<Dir>), and minimal overhead. Alternatives like vite-plugin-static-assets lack TypeScript-first design. Release cadence: initial release, active development.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/MartinBspheroid/vite-static-assets-plugin","tags":["javascript","vite","plugin","static","typescript"],"install":[{"cmd":"npm install vite-static-assets-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add vite-static-assets-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-static-assets-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for type generation; plugin requires TypeScript >=5.0","package":"typescript","optional":false},{"reason":"Peer dependency; requires Vite >=6.2","package":"vite","optional":false}],"imports":[{"note":"Plugin is exported as default export only. Named import will be undefined.","wrong":"import { staticAssetsPlugin } from 'vite-static-assets-plugin'","symbol":"staticAssetsPlugin (default)","correct":"import staticAssetsPlugin from 'vite-static-assets-plugin'"},{"note":"staticAssets is generated by the plugin in the output file, not exported by the package itself.","wrong":"import { staticAssets } from 'vite-static-assets-plugin'","symbol":"staticAssets","correct":"import { staticAssets } from './static-assets'"},{"note":"Type is generated by the plugin, not from the package. Path must match output file.","wrong":"import { StaticAssetPath } from 'vite-static-assets-plugin'","symbol":"StaticAssetPath (type)","correct":"import { StaticAssetPath } from './static-assets'"},{"note":"Must provide a string literal directory path as generic parameter, e.g. FilesInFolder<'images/'>.","wrong":"","symbol":"FilesInFolder (generic)","correct":"import { FilesInFolder } from './static-assets'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport staticAssetsPlugin from 'vite-static-assets-plugin';\n\nexport default defineConfig({\n  plugins: [\n    staticAssetsPlugin({\n      directory: 'public',      // default\n      outputFile: 'static-assets.ts', // default\n      include: ['**\\/*'],       // default: all files\n      exclude: [],              // default: none\n      debounceMs: 100,          // default: 100\n      scanDepth: 10,            // default: 10\n      emptyDirBehaviour: 'skip', // default: skip\n      leadingSlash: true,       // default: true\n    })\n  ]\n});\n\n// After running Vite dev/build, import from generated file:\nimport { staticAssets, StaticAssetPath, FilesInFolder } from './static-assets';\n\nconst url = staticAssets('images/logo.svg'); // returns '/images/logo.svg'\nconst path: StaticAssetPath = 'fonts/roboto.woff2';\ntype SvgIcons = FilesInFolder<'icons/'>; // union of paths like 'icons/circle.svg' | 'icons/square.svg'","lang":"typescript","description":"Configures the plugin in vite.config.ts and imports generated types/functions."},"warnings":[{"fix":"Upgrade Vite to 6.2+ and TypeScript to 5.0+","message":"Requires Vite >=6.2.0 and TypeScript >=5.0.0","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Keep outputFile default or set a unique path, and add it to .gitignore if dynamic.","message":"Generated file path is relative to project root. Ensure the output is not overwritten by other tooling.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Restart dev server or trigger a manual scan if needed (not currently supported).","message":"Plugin only processes files present during initial scan and HMR updates. Files added outside Vite's watch scope may not be picked up.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"","message":"No known deprecated features yet; this is an initial release.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'vite' or 'vite build' once to generate the file, then check the output path matches your import.","cause":"The generated file may not exist (forgot to run Vite dev/build) or the path is incorrect.","error":"Cannot find module './static-assets' or its corresponding type declarations."},{"fix":"Import { staticAssets } from './static-assets' (or your configured output file).","cause":"Importing from the wrong module (e.g., from 'vite-static-assets-plugin' instead of generated file).","error":"TypeError: staticAssets is not a function"},{"fix":"Add import type { StaticAssetPath } from './static-assets'; and ensure the generated file is in your tsconfig includes.","cause":"Type import path is incorrect or missing generated file.","error":"TS2582: Cannot find name 'StaticAssetPath'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}