Vite Static Assets Plugin

A Vite plugin that automatically scans your static assets directory, generates a type-safe TypeScript module with all asset paths, directory-aware types, and a helper function to get asset URLs. It validates asset references during build and updates live during development.

Features

• 🚀 Automatic Recursive Scanning: Scans a directory (default: public) for all static assets.
• 🛡 Type-Safe API: Generates a union type StaticAssetPath of all valid asset paths.
• 📁 Directory-Aware Types: Generates StaticAssetDirectory and a powerful FilesInFolder<Dir> generic for directory-specific asset typing.
• 🔗 Helper Function: Provides staticAssets() to get the URL for an asset, with runtime validation.
• 🛠 Highly Configurable: Customize directory, output file, ignore patterns, debounce, directory depth, empty directory handling, leading slash, and more.
• 🔄 Live Updates: Watches the directory in development mode and regenerates types on changes.
• 🧭 Validation: Validates asset references and directory references during build, with detailed error messages.
• ⚡ Fast: Minimal overhead, optimized for large projects.

Usage

Import the generated function and types:

import { staticAssets, StaticAssetPath, StaticAssetDirectory, FilesInFolder } from './static-assets';

// Use the helper function
const logoUrl = staticAssets('images/logo.svg');

// Type-safe variables
const assetPath: StaticAssetPath = 'fonts/roboto.woff2';

const dir: StaticAssetDirectory = 'images/';


// Type-safe list of files directly inside 'icons/brands/'
type  Icons = FilesInFolder<'icons/brands/'>;
// use Icons type in your code
type Brands = {
  icon: Icons,
  name: string
}
// Create a list of brands with their icons and names
// get autocompletion and type checking!
const brands: Brands[] = [
  {
    icon: "icons/brands/coke.svg",
    name: "Coke"
  },
  {
    icon: "icons/brands/pepsi.svg",
    name: "Pepsi"
  },
  {
    icon: "icons/brands/rc-cola.svg",
    name: "RC Cola"
  },
  {
    icon: "icons/brands/dr-pepper.svg",
    name: "Dr Pepper"
  },
]

Installation

# npm
npm install --save-dev vite-static-assets-plugin

# yarn
yarn add -D vite-static-assets-plugin

# bun
bun add -d vite-static-assets-plugin

# pnpm
pnpm add -D vite-static-assets-plugin

Setup and Configuration

Add the plugin to your Vite config:

vite.config.ts

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

export default defineConfig({
  plugins: [
    staticAssetsPlugin({
      // Optional configuration (defaults shown):
      directory: 'public',
      outputFile: 'src/static-assets.ts',
      ignore: ['.DS_Store'],
      debounce: 200,
      enableDirectoryTypes: true,
      maxDirectoryDepth: 5,
      allowEmptyDirectories: false,
      addLeadingSlash: true,
    })
  ]
});

Generated TypeScript Module

The plugin generates a TypeScript file (default: src/static-assets.ts) containing:

StaticAssetPath

A union of all asset paths:

export type StaticAssetPath =
  'images/logo.svg' |
  'images/banner.jpg' |
  'fonts/roboto.woff2';

StaticAssetDirectory

A union of all directories containing assets, including '.' for the root:

export type StaticAssetDirectory =
  '.' |
  'fonts/' |
  'images/' ;

FilesInFolder<Dir>

A generic type representing only the files directly inside a directory:

// Example: all files directly inside 'images/' (not nested)
type ImageFiles = FilesInFolder<'images/'>;
// 'logo.svg' | 'banner.jpg'

staticAssets(path)

A function that returns the URL for an asset, with validation:

export function staticAssets(path: StaticAssetPath): string;

If you pass an invalid path, it throws an error at runtime and TypeScript will catch it at compile time.

Use it in your components:

<img src={staticAssets('images/logo.svg')} alt="Logo" />

Framework Agnostic

Works with any frontend framework that uses Vite: React, Vue, Svelte, Angular, Solid, Lit, and more.

Plugin Options

| Option | Type | Default | Description | |--------------------------|-----------------|---------------------------|--------------------------------------------------------------------------------------------------| | directory | string | 'public' | Directory to scan for static assets | | outputFile | string | 'src/static-assets.ts' | Path to generate the TypeScript module | | ignore | string[] | ['.DS_Store'] | Glob patterns to ignore | | debounce | number | 200 | Debounce time (ms) for file watcher events | | enableDirectoryTypes | boolean | true | Generate directory-aware types (StaticAssetDirectory, FilesInFolder) | | maxDirectoryDepth | number | 5 | Maximum directory nesting level for directory type generation | | allowEmptyDirectories | boolean | false | Allow referencing empty directories in validation | | addLeadingSlash | boolean | true | Add a leading slash to generated asset URLs |

How It Works

1. Scans the specified directory recursively, ignoring patterns.
2. Generates a TypeScript file with:
   • StaticAssetPath union of all asset paths.
   • StaticAssetDirectory union of directories.
   • FilesInFolder<Dir> generic.
   • staticAssets() function.
3. Watches the directory in development mode, regenerating on changes.
4. Validates asset references and directory references during build.
5. Throws errors with detailed info if assets or directories are missing.

Error Handling

• If you reference a missing asset in staticAssets(), the plugin throws a build-time error with details (even if you're skipping TS typechecking before build).
• If you reference a directory (via FilesInFolder or in code) that is empty or missing, it throws an error unless allowEmptyDirectories: true.
• Errors include the file path, missing asset/directory, and suggestions.

• Please note that this message is shown in case you actually skip TS typechecking before build. In case you're not typechecking before build (which is recommended), the error will be thrown at build time and you'll see the full error message in the terminal.

TypeScript Integration

• The generated file is TypeScript-ready (as long as you set outputFile in your vite.config.ts to folder that is visible to your project).
• Enjoy auto-completion, type checking, and refactoring support for your static assets.

Development

Testing

This project uses Vitest:

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

Tests are in packages/plugin/tests/ and cover core functions and plugin behavior.

License

MIT

Contributing

Contributions, issues, and feature requests are welcome! Please open an issue or pull request.