{"id":22826,"library":"vite-plugin-serve-static","title":"vite-plugin-serve-static","description":"A Vite plugin (v2.2.0, stable, MIT) for serving arbitrary static files outside the standard `public` directory during local development. Unlike the built-in `publicDir` or `server.fs.allow`, this plugin supports regex-based URL-to-file mapping with flexible resolver functions, making it ideal for monorepos or projects where static files live in external directories. Requires Node >=20 and Vite >=5.0.0 <9.0.0. Note: does not handle production builds or serve.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/typeparameter/vite-plugin-serve-static","tags":["javascript","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-serve-static","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-serve-static","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-serve-static","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for Vite plugin integration","package":"vite","optional":false}],"imports":[{"note":"Default export, not named.","wrong":"import { serveStatic } from 'vite-plugin-serve-static'","symbol":"serveStatic","correct":"import serveStatic from 'vite-plugin-serve-static'"},{"note":"Package is ESM-only as of v2.","wrong":"require('vite-plugin-serve-static')","symbol":"vite-plugin-serve-static","correct":"import serveStatic from 'vite-plugin-serve-static'"},{"note":"Type import. Only available in TypeScript.","wrong":"import { ViteServeStaticOptions } from 'vite-plugin-serve-static'","symbol":"ViteServeStaticOptions","correct":"import type { ViteServeStaticOptions } from 'vite-plugin-serve-static'"}],"quickstart":{"code":"import path from 'path';\nimport { defineConfig } from 'vite';\nimport serveStatic from 'vite-plugin-serve-static';\n\nexport default defineConfig({\n  plugins: [\n    serveStatic({\n      rules: [\n        {\n          pattern: /^\\/metadata\\.json$/,\n          resolve: path.resolve(__dirname, 'metadata.json'),\n        },\n        {\n          pattern: /^\\/photos\\/(.*)/,\n          resolve: (groups) => path.join(__dirname, '..', 'photos', groups[1]),\n        },\n      ],\n      contentType: 'application/json',\n    }),\n  ],\n});","lang":"typescript","description":"Configures serve-static plugin with two rules: static file via string path and dynamic file via resolver function."},"warnings":[{"fix":"Upgrade Node.js to 20 or later, or pin to v1.x.","message":"Minimum Node.js version increased to 20.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure Vite version is at least 5.0.0.","message":"Vite peer dependency updated to >=5.0.0 <9.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate to ESM imports (no require()).","message":"v1.x used CommonJS exports; v2 is ESM-only.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use separate static file serving in production (e.g., nginx, express).","message":"The plugin only applies during dev server, not in production builds.","severity":"gotcha","affected_versions":"all"},{"fix":"Use path.resolve or path.join with __dirname.","message":"Resolve paths must be absolute; relative paths can misbehave.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Switch to import statement or use dynamic import().","cause":"Using CommonJS require() with ESM-only package v2+.","error":"Error: Dynamic require of \"vite-plugin-serve-static\" is not supported"},{"fix":"Update Vite to >=5.0.0 <9.0.0 (latest Vite 7 is supported).","cause":"Incompatible Vite version (e.g., <5.0.0 or >=9.0.0).","error":"ERR_PNPM_PEER_DEP_INSTALL_FAIL  Cannot install with --frozen-lockfile due to peer dependency mismatch on vite"},{"fix":"Use absolute paths (e.g., path.resolve(__dirname, 'metadata.json')).","cause":"The resolve path is relative but Vite's working directory is not project root.","error":"[vite] http proxy error: /metadata.json: Error: ENOENT: no such file or directory"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}