name: create-vite-plugin description: Create a new Vite plugin in the @taucad/vite package following project conventions and Vite 8 best practices. Use when adding a Vite plugin, creating dev server middleware, implementing build transforms, or extending Vite configuration for the Tau monorepo.

Create Vite Plugin

Add a new Vite plugin to libs/vite/ (@taucad/vite) following project conventions and Vite 8 best practices.

Definition of Done

1. Plugin file at libs/vite/src/<name>.vite-plugin.ts
2. Subpath export added to libs/vite/package.json
3. Plugin wired into consumer vite.config.ts (typically apps/ui/vite.config.ts)
4. Lint passes: pnpm nx lint vite

1) Create the Plugin File

File: libs/vite/src/<name>.vite-plugin.ts

Convention: kebab-case name, .vite-plugin.ts suffix. Export a named function (not default) that returns Plugin.

import type { Plugin } from 'vite';

/**
 * JSDoc describing what the plugin does and why it exists.
 */
export function myPluginName(): Plugin {
  return {
    name: 'vite:<name>',

    config(config, env) {
      // Return partial config to deep-merge (recommended over mutation)
      return {
        /* ... */
      };
    },
  };
}

Plugin naming rules

• name field: prefix with vite: (e.g. vite:optimize-deps-from-cache)
• Export name: camelCase matching the plugin purpose (e.g. optimizeDepsFromCache)
• File name: kebab-case + .vite-plugin.ts (e.g. optimize-deps-from-cache.vite-plugin.ts)

When returning multiple plugins

Export a function returning Plugin[] and spread in the consumer:

export function myPlugins(): Plugin[] {
  return [pluginA(), pluginB()];
}
// Consumer: ...myPlugins()

See ts-module-url.vite-plugin.ts for a real example.

2) Add Subpath Export

File: libs/vite/package.json

Add a new entry to exports — all three conditions point to the .ts source file (no build step):

"./<name>": {
  "types": "./src/<name>.vite-plugin.ts",
  "import": "./src/<name>.vite-plugin.ts",
  "default": "./src/<name>.vite-plugin.ts"
}

3) Wire into Consumer

File: apps/ui/vite.config.ts (or whichever app uses it)

import { myPluginName } from '@taucad/vite/<name>';

// In the plugins array:
plugins: [
  myPluginName(),
  // ...
],

Existing Plugins Reference

Vite 8 Best Practices

Hook selection guide

Prefer returning partial config over mutation

// Good: return partial config (deep-merged automatically)
config() {
  return { resolve: { alias: { foo: 'bar' } } };
}

// Avoid: direct mutation (only when merging can't achieve the result)
config(config) {
  config.root = 'foo';
}

Use enforce for ordering

return {
  name: 'vite:<name>',
  enforce: 'pre', // run before core plugins (alias resolution phase)
  // enforce: 'post' — run after core plugins (minify/manifest phase)
};

Plugin execution order: enforce: 'pre' → core plugins → no enforce → enforce: 'post'.

Use apply for conditional activation

return {
  name: 'vite:<name>',
  apply: 'serve', // only during dev (or 'build' for build-only)
};

// Or use a function for complex conditions:
return {
  apply: (config, { command }) => command === 'build' && !config.build.ssr,
};

Hook filters for transform/resolveId/load (Vite 6.3+ / Rolldown)

Reduces Rust-JS boundary overhead by filtering before the hook is called:

transform: {
  filter: { id: /\.custom$/ },
  handler(code, id) {
    if (!/\.custom$/.test(id)) return null; // backward compat guard
    return { code: transformCode(code), map: null };
  },
},

Environment API (RC in Vite 6+)

Access environment-specific config via this.environment instead of the deprecated ssr boolean:

transform(code, id) {
  const conditions = this.environment.config.resolve.conditions;
  const envName = this.environment.name; // 'client', 'ssr', or custom
}

Use configEnvironment to configure specific environments:

configEnvironment(name, options) {
  if (name === 'ssr') {
    return { resolve: { conditions: ['workerd'] } };
  }
}

Per-environment state

Key plugin state by this.environment using a Map<Environment, T>:

function myPlugin(): Plugin {
  const state = new Map<Environment, { count: number }>();
  return {
    name: 'vite:<name>',
    perEnvironmentStartEndDuringDev: true,
    buildStart() {
      state.set(this.environment, { count: 0 });
    },
    transform() {
      state.get(this.environment)!.count++;
    },
  };
}

Virtual modules

Prefix resolved IDs with \0 to prevent other plugins from processing them:

const virtualId = 'virtual:my-module';
const resolvedId = '\0' + virtualId;

return {
  resolveId(id) {
    if (id === virtualId) return resolvedId;
  },
  load(id) {
    if (id === resolvedId) return 'export const x = 1';
  },
};

Rolldown-specific (Vite 8)

When transforming modules to JavaScript, specify moduleType:

transform(code, id) {
  return { code: compiled, map: null, moduleType: 'js' };
}

optimizeDeps.esbuildOptions is deprecated — use optimizeDeps.rolldownOptions for dep optimization config.

Common Patterns

Dev-only plugin

Guard with env.command in config hook:

config(config, env) {
  if (env.command !== 'serve') return;
}

Reading/patching other plugins

Use configResolved to access the final plugin array:

configResolved(config) {
  for (const plugin of config.plugins) {
    if (plugin.name === 'target-plugin') {
      // patch plugin properties
    }
  }
}

Dev server middleware

Use configureServer. Return a function for post-middleware (after Vite internals):

configureServer(server) {
  // Pre-middleware (runs before Vite internals)
  server.middlewares.use((req, res, next) => {
    res.setHeader('X-Custom', 'value');
    next();
  });

  // Return function for post-middleware (runs after Vite internals)
  return () => {
    server.middlewares.use((req, res, next) => { /* ... */ });
  };
}

Storing server reference for other hooks

function myPlugin(): Plugin {
  let server: ViteDevServer;
  return {
    name: 'vite:<name>',
    configureServer(_server) {
      server = _server;
    },
    transform(code, id) {
      if (server) {
        /* use server.moduleGraph, server.ws, etc. */
      }
    },
  };
}

Path normalization

Use normalizePath from vite when comparing resolved paths:

import { normalizePath } from 'vite';
// normalizePath('foo\\bar') → 'foo/bar'