1---
2name: vite-plugin-api
3description: Vite plugin authoring with Vite-specific hooks
4---
5 
6# Vite Plugin API
7 
8Vite plugins extend Rolldown's plugin interface with Vite-specific hooks.
9 
10## Basic Structure
11 
12```ts
13function myPlugin(): Plugin {
14  return {
15    name: 'my-plugin',
16    // hooks...
17  }
18}
19```
20 
21## Vite-Specific Hooks
22 
23### config
24 
25Modify config before resolution:
26 
27```ts
28const plugin = () => ({
29  name: 'add-alias',
30  config: () => ({
31    resolve: {
32      alias: { foo: 'bar' },
33    },
34  }),
35})
36```
37 
38### configResolved
39 
40Access final resolved config:
41 
42```ts
43const plugin = () => {
44  let config: ResolvedConfig
45  return {
46    name: 'read-config',
47    configResolved(resolvedConfig) {
48      config = resolvedConfig
49    },
50    transform(code, id) {
51      if (config.command === 'serve') { /* dev */ }
52    },
53  }
54}
55```
56 
57### configureServer
58 
59Add custom middleware to dev server:
60 
61```ts
62const plugin = () => ({
63  name: 'custom-middleware',
64  configureServer(server) {
65    server.middlewares.use((req, res, next) => {
66      // handle request
67      next()
68    })
69  },
70})
71```
72 
73Return function to run **after** internal middlewares:
74 
75```ts
76configureServer(server) {
77  return () => {
78    server.middlewares.use((req, res, next) => {
79      // runs after Vite's middlewares
80    })
81  }
82}
83```
84 
85### transformIndexHtml
86 
87Transform HTML entry files:
88 
89```ts
90const plugin = () => ({
91  name: 'html-transform',
92  transformIndexHtml(html) {
93    return html.replace(/<title>(.*?)<\/title>/, '<title>New Title</title>')
94  },
95})
96```
97 
98Inject tags:
99 
100```ts
101transformIndexHtml() {
102  return [
103    { tag: 'script', attrs: { src: '/inject.js' }, injectTo: 'body' },
104  ]
105}
106```
107 
108### handleHotUpdate
109 
110Custom HMR handling:
111 
112```ts
113handleHotUpdate({ server, modules, timestamp }) {
114  server.ws.send({ type: 'custom', event: 'special-update', data: {} })
115  return [] // empty = skip default HMR
116}
117```
118 
119## Virtual Modules
120 
121Serve virtual content without files on disk:
122 
123```ts
124const plugin = () => {
125  const virtualModuleId = 'virtual:my-module'
126  const resolvedId = '\0' + virtualModuleId
127 
128  return {
129    name: 'virtual-module',
130    resolveId(id) {
131      if (id === virtualModuleId) return resolvedId
132    },
133    load(id) {
134      if (id === resolvedId) {
135        return `export const msg = "from virtual module"`
136      }
137    },
138  }
139}
140```
141 
142Usage:
143 
144```ts
145import { msg } from 'virtual:my-module'
146```
147 
148Convention: prefix user-facing path with `virtual:`, prefix resolved id with `\0`.
149 
150## Plugin Ordering
151 
152Use `enforce` to control execution order:
153 
154```ts
155{
156  name: 'pre-plugin',
157  enforce: 'pre',  // runs before core plugins
158}
159 
160{
161  name: 'post-plugin',
162  enforce: 'post', // runs after build plugins
163}
164```
165 
166Order: Alias → `enforce: 'pre'` → Core → User (no enforce) → Build → `enforce: 'post'` → Post-build
167 
168## Conditional Application
169 
170```ts
171{
172  name: 'build-only',
173  apply: 'build',  // or 'serve'
174}
175 
176// Function form:
177{
178  apply(config, { command }) {
179    return command === 'build' && !config.build.ssr
180  }
181}
182```
183 
184## Universal Hooks (from Rolldown)
185 
186These work in both dev and build:
187 
188- `resolveId(id, importer)` - Resolve import paths
189- `load(id)` - Load module content
190- `transform(code, id)` - Transform module code
191 
192```ts
193transform(code, id) {
194  if (id.endsWith('.custom')) {
195    return { code: compile(code), map: null }
196  }
197}
198```
199 
200## Client-Server Communication
201 
202Server to client:
203 
204```ts
205configureServer(server) {
206  server.ws.send('my:event', { msg: 'hello' })
207}
208```
209 
210Client side:
211 
212```ts
213if (import.meta.hot) {
214  import.meta.hot.on('my:event', (data) => {
215    console.log(data.msg)
216  })
217}
218```
219 
220Client to server:
221 
222```ts
223// Client
224import.meta.hot.send('my:from-client', { msg: 'Hey!' })
225 
226// Server
227server.ws.on('my:from-client', (data, client) => {
228  client.send('my:ack', { msg: 'Got it!' })
229})
230```
231 
232<!--
233Source references:
234- https://vite.dev/guide/api-plugin
235-->
236