vite-syntax-plugin-api

vite-syntax-plugin-api

Quick Reference

Plugin Structure

A Vite plugin is a factory function returning an object with a required name property:

export default function myPlugin(options = {}) {
  return {
    name: 'vite-plugin-my-feature',
    // hooks...
  }
}

Naming Conventions

Type	Prefix	npm Keywords
Vite-only plugin	vite-plugin-	vite-plugin
Rolldown plugin	rolldown-plugin-	rolldown-plugin, vite-plugin
Framework-specific	vite-plugin-vue-, vite-plugin-react-, vite-plugin-svelte-	framework + vite-plugin

Plugin Execution Order

Plugins execute in this EXACT order:

1. Alias (internal)
2. User plugins with enforce: 'pre'
3. Vite core plugins (internal)
4. User plugins with no enforce value
5. Vite build plugins (internal)
6. User plugins with enforce: 'post'
7. Vite post-build plugins (internal)

Conditional Application (apply)

// String form: 'build' or 'serve'
apply: 'build',

// Function form: precise control
apply(config, { command }) {
  return command === 'build' && !config.build.ssr
}

Plugin Arrays and Falsy Values

Falsy plugins are ignored. Arrays are flattened. This enables conditional plugins:

plugins: [
  myPlugin(),
  condition ? optionalPlugin() : null,
  [pluginA(), pluginB()],
]

---

Critical Warnings

NEVER inject plugins inside the config hook -- user plugins resolve BEFORE the config hook runs, so injected plugins have no effect.

NEVER rely on the moduleParsed hook during dev -- Vite does NOT call it for performance reasons. It only runs during production builds.

ALWAYS prefix virtual module IDs with \0 internally -- this prevents other plugins from processing them. The virtual: prefix is for user-facing imports only.

ALWAYS use normalizePath() on file paths in plugins -- Vite uses forward slashes internally, even on Windows.

ALWAYS return null from resolveId and load hooks when a module is NOT handled by your plugin -- returning undefined silently breaks the plugin chain.