Registry / devops / vite-plugin-serve-static

vite-plugin-serve-static

library2.2.0jsnpmunverified

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.

devops

npm install vite-plugin-serve-static

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-SERVE-

vite-plugin-serve-static

devopsjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serveStatic

✓ import serveStatic from 'vite-plugin-serve-static'

✗ import { serveStatic } from 'vite-plugin-serve-static'

Default export, not named.

vite-plugin-serve-static

✓ import serveStatic from 'vite-plugin-serve-static'

✗ require('vite-plugin-serve-static')

Package is ESM-only as of v2.

ViteServeStaticOptions

✓ import type { ViteServeStaticOptions } from 'vite-plugin-serve-static'

✗ import { ViteServeStaticOptions } from 'vite-plugin-serve-static'

Type import. Only available in TypeScript.

Configures serve-static plugin with two rules: static file via string path and dynamic file via resolver function.

import path from 'path'; import { defineConfig } from 'vite'; import serveStatic from 'vite-plugin-serve-static'; export default defineConfig({ plugins: [ serveStatic({ rules: [ { pattern: /^\/metadata\.json$/, resolve: path.resolve(__dirname, 'metadata.json'), }, { pattern: /^\/photos\/(.*)/, resolve: (groups) => path.join(__dirname, '..', 'photos', groups[1]), }, ], contentType: 'application/json', }), ], });

Debug

Known issues

breakingMinimum Node.js version increased to 20.

fix

Upgrade Node.js to 20 or later, or pin to v1.x.

affects: >=2.0.0

breakingVite peer dependency updated to >=5.0.0 <9.0.0.

fix

Ensure Vite version is at least 5.0.0.

affects: >=2.0.0

deprecatedv1.x used CommonJS exports; v2 is ESM-only.

fix

Migrate to ESM imports (no require()).

affects: >=2.0.0

gotchaThe plugin only applies during dev server, not in production builds.

fix

Use separate static file serving in production (e.g., nginx, express).

affects: all

gotchaResolve paths must be absolute; relative paths can misbehave.

fix

Use path.resolve or path.join with __dirname.

affects: all

Errors

Common errors & fixes

Error: Dynamic require of "vite-plugin-serve-static" is not supported

Using CommonJS require() with ESM-only package v2+.

fix

Switch to import statement or use dynamic import().

ERR_PNPM_PEER_DEP_INSTALL_FAIL Cannot install with --frozen-lockfile due to peer dependency mismatch on vite

Incompatible Vite version (e.g., <5.0.0 or >=9.0.0).

fix

Update Vite to >=5.0.0 <9.0.0 (latest Vite 7 is supported).

[vite] http proxy error: /metadata.json: Error: ENOENT: no such file or directory

The resolve path is relative but Vite's working directory is not project root.

fix

Use absolute paths (e.g., path.resolve(__dirname, 'metadata.json')).

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

viterequiredpeer dependency for Vite plugin integration

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/typeparameter/vite-plugin-serve-static ↗

packagehttps://www.npmjs.com/package/vite-plugin-serve-static ↗