0
# Plugin System
1

2
Comprehensive Vite plugin system providing specialized functionality for Nuxt applications, including SSR styles, asset handling, and development tools.
3

4
## Capabilities
5

6
### SSR Styles Plugin
7

8
Manages CSS extraction and inlining for server-side rendering with sophisticated style optimization.
9

10
```typescript { .api }
11
/**
12
 * SSR styles plugin for CSS extraction and inlining
13
 * Handles CSS processing for both server and client builds with style optimization
14
 * @param options - Plugin configuration options
15
 * @returns Vite plugin instance for SSR style handling
16
 */
17
function SSRStylesPlugin(options: SSRStylesPluginOptions): Plugin;
18

19
interface SSRStylesPluginOptions {
20
  /** Source directory path for relative path resolution */
21
  srcDir: string;
22
  /** Set of chunk IDs that should have CSS inlined */
23
  chunksWithInlinedCSS: Set<string>;
24
  /** Function or boolean determining if styles should be inlined */
25
  shouldInline?: ((id?: string) => boolean) | boolean;
26
  /** Array of Nuxt component definitions */
27
  components: Component[];
28
  /** Mapping of CSS files to client chunks */
29
  clientCSSMap: Record<string, Set<string>>;
30
  /** Application entry point file */
31
  entry: string;
32
  /** Global CSS file paths */
33
  globalCSS: string[];
34
  /** Build mode: server or client */
35
  mode: 'server' | 'client';
36
}
37
```
38

39
**Usage Example:**
40

41
```typescript
42
import { SSRStylesPlugin } from "@nuxt/vite-builder/plugins/ssr-styles";
43

44
// Used internally by Nuxt's build process
45
const plugin = SSRStylesPlugin({
46
  srcDir: nuxt.options.srcDir,
47
  chunksWithInlinedCSS: new Set(),
48
  shouldInline: nuxt.options.features.inlineStyles,
49
  components: nuxt.apps.default!.components || [],
50
  globalCSS: nuxt.options.css,
51
  mode: 'client',
52
  entry: ctx.entry,
53
  clientCSSMap: {}
54
});
55
```
56

57
### Public Directories Plugin
58

59
Handles public asset resolution and URL rewriting for different deployment environments.
60

61
```typescript { .api }
62
/**
63
 * Public directories plugin for asset resolution
64
 * Manages public asset serving and URL resolution in development and production
65
 * @param options - Plugin configuration options
66
 * @returns Array of Vite plugin instances for public asset handling
67
 */
68
function PublicDirsPlugin(options: VitePublicDirsPluginOptions): Plugin[];
69

70
interface VitePublicDirsPluginOptions {
71
  /** Development mode flag */
72
  dev?: boolean;
73
  /** Base URL for public assets */
74
  baseURL?: string;
75
}
76
```
77

78
**Plugin Features:**
79

80
- **Development URL Rewriting**: Rewrites asset URLs during development
81
- **Public Asset Resolution**: Resolves assets from public directories
82
- **Base URL Handling**: Manages base URL prefixes for different environments
83
- **CSS URL Processing**: Processes CSS url() references to public assets
84

85
### Development Style SSR Plugin
86

87
Specialized plugin for handling styles during SSR development with hot updates.
88

89
```typescript { .api }
90
/**
91
 * Development style SSR plugin for client builds
92
 * Handles style processing during development with hot module replacement
93
 * @param options - Plugin configuration
94
 * @returns Vite plugin instance
95
 */
96
function DevStyleSSRPlugin(options: {
97
  /** Source directory path */
98
  srcDir: string;
99
  /** Build assets URL for CSS references */
100
  buildAssetsURL: string;
101
}): Plugin;
102
```
103

104
### Runtime Paths Plugin
105

106
Manages runtime path resolution for assets and modules in different environments.
107

108
```typescript { .api }
109
/**
110
 * Runtime paths plugin for asset URL resolution
111
 * Provides runtime path resolution for assets and modules
112
 * @returns Vite plugin instance
113
 */
114
function RuntimePathsPlugin(): Plugin;
115
```
116

117
**Path Resolution Features:**
118

119
- **Asset URL Generation**: Generates correct asset URLs at runtime
120
- **Environment Adaptation**: Adapts paths for different deployment environments
121
- **Module Resolution**: Handles module path resolution in different contexts
122

123
### Type Check Plugin
124

125
Integrates TypeScript type checking into the build process with configurable options.
126

127
```typescript { .api }
128
/**
129
 * TypeScript type checking plugin
130
 * Integrates TypeScript type checking into Vite build process
131
 * @param nuxt - Nuxt instance with TypeScript configuration
132
 * @returns Vite plugin instance
133
 */
134
function TypeCheckPlugin(nuxt: Nuxt): Plugin;
135
```
136

137
**Type Checking Features:**
138

139
- **Build Integration**: Runs type checking during build process
140
- **IDE Integration**: Provides type checking feedback in development
141
- **Configuration Respect**: Uses project's TypeScript configuration
142
- **Error Reporting**: Provides clear type error messages
143

144
### Module Preload Polyfill Plugin
145

146
Adds polyfill support for module preloading in browsers that don't support it natively.
147

148
```typescript { .api }
149
/**
150
 * Module preload polyfill for older browsers
151
 * Adds polyfill for module preloading in unsupported browsers
152
 * @returns Vite plugin instance
153
 */
154
function ModulePreloadPolyfillPlugin(): Plugin;
155
```
156

157
### Stable Entry Plugin
158

159
Ensures stable entry point hashing for better caching and deployment consistency.
160

161
```typescript { .api }
162
/**
163
 * Stable entry plugin for consistent chunk hashing
164
 * Provides stable hashing for entry points to improve caching
165
 * @param nuxt - Nuxt instance
166
 * @returns Vite plugin instance
167
 */
168
function StableEntryPlugin(nuxt: Nuxt): Plugin;
169
```
170

171
### Sourcemap Preserver Plugin
172

173
Preserves sourcemap information through the build pipeline for debugging.
174

175
```typescript { .api }
176
/**
177
 * Sourcemap preserver plugin for build pipeline integration
178
 * Preserves sourcemap information through Nitro build process
179
 * @param nuxt - Nuxt instance
180
 * @returns Vite plugin instance
181
 */
182
function SourcemapPreserverPlugin(nuxt: Nuxt): Plugin;
183
```
184

185
### Vue Feature Flags Plugin
186

187
Manages Vue-specific feature flags and compilation options.
188

189
```typescript { .api }
190
/**
191
 * Vue feature flags plugin for server builds
192
 * Manages Vue compilation feature flags and optimization
193
 * @param nuxt - Nuxt instance
194
 * @returns Vite plugin instance
195
 */
196
function VueFeatureFlagsPlugin(nuxt: Nuxt): Plugin;
197
```
198

199
### Analyze Plugin
200

201
Provides bundle analysis and visualization capabilities for production builds.
202

203
```typescript { .api }
204
/**
205
 * Analyze plugin for bundle visualization
206
 * Generates bundle analysis reports for optimization insights
207
 * @param nuxt - Nuxt instance with analysis configuration
208
 * @returns Promise resolving to array of Vite plugins
209
 */
210
function AnalyzePlugin(nuxt: Nuxt): Promise<Plugin[]>;
211
```
212

213
**Analysis Features:**
214

215
- **Bundle Size Analysis**: Detailed breakdown of bundle sizes
216
- **Dependency Visualization**: Visual representation of dependencies
217
- **Chunk Analysis**: Analysis of code splitting effectiveness
218
- **Performance Insights**: Recommendations for optimization
219

220
### Vite-Node Plugin
221

222
Integrates vite-node for seamless SSR development with hot updates.
223

224
```typescript { .api }
225
/**
226
 * Vite-node plugin for SSR development
227
 * Provides seamless SSR development with hot module replacement
228
 * @param nuxt - Nuxt instance
229
 * @returns Vite plugin instance
230
 */
231
function ViteNodePlugin(nuxt: Nuxt): Plugin;
232
```
233

234
**Vite-Node Features:**
235

236
- **SSR Hot Updates**: Hot module replacement for server-side code
237
- **Module Transformation**: Real-time server code transformation
238
- **Dependency Tracking**: Proper invalidation of server dependencies
239
- **Development Performance**: Fast SSR development experience
240

241
### Plugin Utilities
242

243
Common utilities used across multiple plugins for consistent behavior.
244

245
```typescript { .api }
246
/**
247
 * Check if file is a Vue component
248
 * @param file - File path to check
249
 * @returns Boolean indicating if file is Vue component
250
 */
251
function isVue(file: string): boolean;
252

253
/**
254
 * Check if file is a CSS file
255
 * @param file - File path to check
256
 * @returns Boolean indicating if file is CSS
257
 */
258
function isCSS(file: string): boolean;
259

260
/**
261
 * Convert value to array format
262
 * @param value - Value to convert
263
 * @returns Array containing the value(s)
264
 */
265
function toArray<T>(value: T | T[]): T[];
266
```
267

268
### Plugin Configuration
269

270
Standard configuration patterns used across Nuxt Vite plugins.
271

272
```typescript { .api }
273
/**
274
 * Base plugin configuration interface
275
 */
276
interface BasePluginOptions {
277
  /** Development mode flag */
278
  dev?: boolean;
279
  /** Source directory path */
280
  srcDir?: string;
281
  /** Build directory path */
282
  buildDir?: string;
283
}
284
```
285

286
### Plugin Registration
287

288
Plugins are automatically registered by the build system with proper ordering.
289

290
**Plugin Registration Order:**
291

292
1. **Core Vue Plugins**: Vue SFC and JSX compilation
293
2. **Nuxt Infrastructure**: Public dirs, runtime paths
294
3. **Development Tools**: Type checking, HMR support
295
4. **Style Processing**: CSS extraction, SSR styles
296
5. **Production Optimization**: Bundle analysis, stable entry
297
6. **Build Integration**: Sourcemap preservation, feature flags
298

299
### Error Handling
300

301
Plugins include comprehensive error handling and recovery mechanisms.
302

303
**Error Handling Features:**
304

305
- **Plugin Initialization**: Graceful handling of plugin setup failures
306
- **Transform Errors**: Clear error messages for code transformation issues
307
- **Asset Resolution**: Helpful messages for missing assets or dependencies
308
- **Development Recovery**: Automatic recovery from development-time errors