0
# Server Building
1

2
Server-side build pipeline for SSR support, optimized for Node.js runtime with external dependency handling and development server integration.
3

4
## Capabilities
5

6
### Build Server Function
7

8
Creates Node.js-optimized builds for server-side rendering with proper external dependency handling.
9

10
```typescript { .api }
11
/**
12
 * Build server-side assets for SSR
13
 * Handles Node.js-specific configuration, external dependencies, and SSR optimization
14
 * @param nuxt - Nuxt instance with server configuration
15
 * @param ctx - Vite build context containing entry and config
16
 */
17
function buildServer(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { buildServer } from "@nuxt/vite-builder/server";
24
import type { ViteBuildContext } from "@nuxt/vite-builder";
25

26
// Called internally by bundle(), but can be used directly
27
const ctx: ViteBuildContext = {
28
  nuxt,
29
  config: viteConfig,
30
  entry: './app/entry.server.ts'
31
};
32

33
await buildServer(nuxt, ctx);
34
```
35

36
### Server Configuration
37

38
The buildServer function applies Node.js-specific Vite configuration for SSR.
39

40
**Key Configuration Areas:**
41

42
```typescript
43
// Server-specific configuration applied
44
const serverConfig = {
45
  define: {
46
    'process.server': true,
47
    'process.client': false,
48
    'process.browser': false,
49
    'import.meta.server': true,
50
    'import.meta.client': false,
51
    'import.meta.browser': false,
52
    // Browser globals undefined in Node.js
53
    'window': 'undefined',
54
    'document': 'undefined',
55
    'navigator': 'undefined',
56
    'location': 'undefined',
57
    'XMLHttpRequest': 'undefined',
58
  },
59
  ssr: {
60
    external: [
61
      'nitro/runtime',
62
      '#internal/nitro',
63
      '#internal/nitro/utils',
64
    ],
65
    noExternal: [
66
      // Transpile these packages for server use
67
      ...transpile({ isServer: true, isDev: nuxt.options.dev }),
68
      '/__vue-jsx',
69
      '#app',
70
      /^nuxt(\/|$)/,
71
      /(nuxt|nuxt3|nuxt-nightly)\/(dist|src|app)/,
72
    ]
73
  },
74
  build: {
75
    ssr: true,
76
    outDir: resolve(nuxt.options.buildDir, 'dist/server'),
77
    rollupOptions: {
78
      input: { server: serverEntry },
79
      output: {
80
        entryFileNames: '[name].mjs',
81
        format: 'module'
82
      }
83
    }
84
  }
85
};
86
```
87

88
### Entry Point Resolution
89

90
Server builds use different entry points based on SSR configuration.
91

92
```typescript { .api }
93
/**
94
 * Resolve server entry point based on SSR settings
95
 * @param nuxt - Nuxt instance
96
 * @param ctx - Build context  
97
 * @returns Resolved server entry path
98
 */
99
function resolveServerEntry(nuxt: Nuxt, ctx: ViteBuildContext): Promise<string>;
100
```
101

102
**Entry Point Logic:**
103

104
```typescript
105
// Entry point selection
106
const serverEntry = nuxt.options.ssr 
107
  ? ctx.entry  // Full SSR entry
108
  : await resolvePath(resolve(nuxt.options.appDir, 'entry-spa')); // SPA mode entry
109
```
110

111
### External Dependencies
112

113
Server builds carefully manage external vs bundled dependencies.
114

115
**External Dependencies:**
116
- `nitro/runtime` - Nitro server runtime
117
- `#internal/nitro` - Internal Nitro utilities  
118
- `#internal/nuxt/paths` - Path resolution utilities
119
- `#app-manifest` - Application manifest
120
- Node.js built-ins
121

122
**Bundled Dependencies:**
123
- Vue ecosystem packages that need transpilation
124
- Nuxt framework code
125
- User application code
126
- Dependencies requiring server-side processing
127

128
```typescript { .api }
129
/**
130
 * Transpile configuration for server builds
131
 * @param options - Transpilation options
132
 * @returns Array of packages to transpile
133
 */
134
function transpile(options: { 
135
  isServer: boolean; 
136
  isDev: boolean; 
137
}): string[];
138
```
139

140
### Development SSR Server
141

142
In development mode, buildServer creates a Vite SSR development server.
143

144
```typescript { .api }
145
/**
146
 * SSR development server for server-side rendering
147
 * Provides module transformation and hot updates for SSR code
148
 */
149
interface ViteSSRServer extends ViteDevServer {
150
  /** Plugin container for server-side transformations */
151
  pluginContainer: PluginContainer;
152
  /** Transform modules for SSR execution */
153
  ssrTransform(code: string, url: string): Promise<SSRTransformResult>;
154
}
155
```
156

157
**SSR Development Features:**
158

159
- **Module Transformation**: Real-time server code transformation
160
- **Dependency Tracking**: Proper invalidation of server modules
161
- **Hot Updates**: Server-side hot module replacement
162
- **Plugin Integration**: Full plugin support for SSR
163

164
### Production Server Build
165

166
In production mode, buildServer generates optimized server bundles.
167

168
```typescript
169
// Production server build output
170
// .nuxt/dist/server/
171
//   ├── server.mjs            // Main server entry
172
//   ├── chunks/[hash].mjs     // Code-split chunks  
173
//   └── manifest.json         // Server manifest
174
```
175

176
**Production Optimizations:**
177

178
- **Code Splitting**: Separate chunks for better caching
179
- **Tree Shaking**: Remove unused server-side code
180
- **External Optimization**: Proper external dependency handling
181
- **Source Maps**: Optional sourcemaps for server debugging
182

183
### Server-Specific Plugins
184

185
The buildServer function registers server-specific Vite plugins.
186

187
```typescript { .api }
188
/**
189
 * Vue feature flags plugin for server builds
190
 * @param nuxt - Nuxt instance
191
 * @returns Vite plugin instance
192
 */
193
function VueFeatureFlagsPlugin(nuxt: Nuxt): Plugin;
194

195
/**
196
 * Sourcemap preserver plugin for build pipeline integration
197
 * @param nuxt - Nuxt instance  
198
 * @returns Vite plugin instance
199
 */
200
function SourcemapPreserverPlugin(nuxt: Nuxt): Plugin;
201
```
202

203
### Nitro Integration
204

205
Server builds integrate closely with Nitro, Nuxt's server engine.
206

207
```typescript { .api }
208
/**
209
 * Write development server configuration for Nitro integration
210
 * @param nuxt - Nuxt instance
211
 */
212
function writeDevServer(nuxt: Nuxt): Promise<void>;
213

214
/**
215
 * Write manifest files for server bundle resolution
216
 * @param ctx - Build context with server information
217
 */
218
function writeManifest(ctx: ViteBuildContext): Promise<void>;
219
```
220

221
**Nitro Integration Features:**
222

223
- **Runtime Compatibility**: Ensures compatibility with Nitro runtime
224
- **Route Generation**: Supports Nitro's file-based routing
225
- **Middleware Integration**: Seamless server middleware support
226
- **API Routes**: Automatic API route compilation
227

228
### SSR vs SPA Mode
229

230
Server builds adapt based on Nuxt's rendering mode.
231

232
**SSR Mode (nuxt.options.ssr = true):**
233
- Full server-side rendering
234
- Hydration support
235
- SEO optimization
236
- Initial page load performance
237

238
**SPA Mode (nuxt.options.ssr = false):**
239
- Client-side only rendering
240
- Simplified server bundle
241
- Faster build times
242
- Reduced server complexity
243

244
### Module Resolution
245

246
Server builds use specialized module resolution for Node.js environments.
247

248
```typescript
249
// Module resolution configuration
250
const resolveConfig = {
251
  conditions: nitro.options.exportConditions, // Node.js export conditions
252
  alias: {
253
    // Server-specific aliases
254
    'nitro/runtime': join(nuxt.options.buildDir, 'nitro.server.mjs'),
255
  }
256
};
257
```
258

259
### Error Handling
260

261
Server builds include specialized error handling for SSR scenarios.
262

263
**Error Handling Features:**
264

265
- **SSR Error Recovery**: Graceful handling of server-side errors
266
- **Module Resolution Errors**: Clear error messages for missing dependencies
267
- **Build Validation**: Ensures server bundle integrity
268
- **Performance Monitoring**: Tracks server build performance