Vite Plugin List Directory Contents

1.4.5 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.4.5) that generates a directory listing index page during development. Ideal for projects with multiple HTML entry points: it scans the base directory, filters common files (node_modules, .env, etc.), and injects the listing into a template using the {%DIRECTORY%} tag. Only active in serve mode; no-op on build. Minimal configuration: requires baseDir and optional filterList. Unlike general-purpose directory listing tools, it integrates seamlessly with Vite's dev server, allowing you to click through HTML files that are compiled on-the-fly. Maintained by Wes Bos, updated irregularly.

Common errors

error TypeError: directoryPlugin is not a function ↓

cause Using default import instead of named import.

fix

Change to: import { directoryPlugin } from 'vite-plugin-list-directory-contents'

error Error: The argument 'baseDir' is required ↓

cause Missing baseDir in plugin options.

fix

Add baseDir: __dirname (or your desired path) to the plugin options.

Warnings

gotcha Plugin only works in serve mode; it is a no-op during build. ↓

fix No fix needed; it's by design. If you need directory listing in production, consider other solutions.

gotcha The filterList default excludes many common files; custom filterList overrides defaults entirely. ↓

fix If you set a filterList, include all files you want to filter; defaults are not merged.

gotcha The plugin creates an index.html file in baseDir if it doesn't exist; this file is processed by Vite. ↓

fix Ensure you have no custom index.html you want to preserve, or modify the template carefully.

gotcha Security: listing directory contents exposes file structure to local network; Vite's server.fs.deny still applies. ↓

fix Run only on trusted networks or use Vite's server.host to restrict access.

Install

npm install vite-plugin-list-directory-contents

yarn add vite-plugin-list-directory-contents

pnpm add vite-plugin-list-directory-contents

Imports

directoryPlugin

wrong

import directoryPlugin from 'vite-plugin-list-directory-contents'

correct

import { directoryPlugin } from 'vite-plugin-list-directory-contents'

Named export only; default import is not available.

plugin (via require)

wrong

const directoryPlugin = require('vite-plugin-list-directory-contents')

correct

const { directoryPlugin } = require('vite-plugin-list-directory-contents')

CommonJS destructuring required; plugin is not a default export.

Config type

import type { DirectoryPluginOptions } from 'vite-plugin-list-directory-contents'

TypeScript type for plugin options; useful for typed config.

Quickstart

Basic setup: import the plugin, pass baseDir, and use it in Vite config. The plugin will create an index.html with {%DIRECTORY%} tag.

// vite.config.ts
import { defineConfig } from 'vite';
import { directoryPlugin } from 'vite-plugin-list-directory-contents';

export default defineConfig({
  plugins: [
    directoryPlugin({ baseDir: __dirname }),
  ],
});