Vite Static Assets Plugin

1.2.2 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Cannot find module './static-assets' or its corresponding type declarations. ↓

cause The generated file may not exist (forgot to run Vite dev/build) or the path is incorrect.

fix

Run 'vite' or 'vite build' once to generate the file, then check the output path matches your import.

error TypeError: staticAssets is not a function ↓

cause Importing from the wrong module (e.g., from 'vite-static-assets-plugin' instead of generated file).

fix

Import { staticAssets } from './static-assets' (or your configured output file).

error TS2582: Cannot find name 'StaticAssetPath'. ↓

cause Type import path is incorrect or missing generated file.

fix

Add import type { StaticAssetPath } from './static-assets'; and ensure the generated file is in your tsconfig includes.

Warnings

breaking Requires Vite >=6.2.0 and TypeScript >=5.0.0 ↓

fix Upgrade Vite to 6.2+ and TypeScript to 5.0+

gotcha Generated file path is relative to project root. Ensure the output is not overwritten by other tooling. ↓

fix Keep outputFile default or set a unique path, and add it to .gitignore if dynamic.

gotcha Plugin only processes files present during initial scan and HMR updates. Files added outside Vite's watch scope may not be picked up. ↓

fix Restart dev server or trigger a manual scan if needed (not currently supported).

deprecated No known deprecated features yet; this is an initial release.

Install

npm install vite-static-assets-plugin

yarn add vite-static-assets-plugin

pnpm add vite-static-assets-plugin

Imports

staticAssetsPlugin (default)

wrong

import { staticAssetsPlugin } from 'vite-static-assets-plugin'

correct

import staticAssetsPlugin from 'vite-static-assets-plugin'

Plugin is exported as default export only. Named import will be undefined.

staticAssets
wrong
```
import { staticAssets } from 'vite-static-assets-plugin'
```
correct
```
import { staticAssets } from './static-assets'
```
staticAssets is generated by the plugin in the output file, not exported by the package itself.
StaticAssetPath (type)
wrong
```
import { StaticAssetPath } from 'vite-static-assets-plugin'
```
correct
```
import { StaticAssetPath } from './static-assets'
```
Type is generated by the plugin, not from the package. Path must match output file.
FilesInFolder (generic)
```
import { FilesInFolder } from './static-assets'
```
Must provide a string literal directory path as generic parameter, e.g. FilesInFolder<'images/'>.

Quickstart

Configures the plugin in vite.config.ts and imports generated types/functions.

// vite.config.ts
import { defineConfig } from 'vite';
import staticAssetsPlugin from 'vite-static-assets-plugin';

export default defineConfig({
  plugins: [
    staticAssetsPlugin({
      directory: 'public',      // default
      outputFile: 'static-assets.ts', // default
      include: ['**\/*'],       // default: all files
      exclude: [],              // default: none
      debounceMs: 100,          // default: 100
      scanDepth: 10,            // default: 10
      emptyDirBehaviour: 'skip', // default: skip
      leadingSlash: true,       // default: true
    })
  ]
});

// After running Vite dev/build, import from generated file:
import { staticAssets, StaticAssetPath, FilesInFolder } from './static-assets';

const url = staticAssets('images/logo.svg'); // returns '/images/logo.svg'
const path: StaticAssetPath = 'fonts/roboto.woff2';
type SvgIcons = FilesInFolder<'icons/'>; // union of paths like 'icons/circle.svg' | 'icons/square.svg'