0
# Build System
1

2
Production build system with asset optimization, code splitting, server-side rendering support, and deployment target configuration.
3

4
## Capabilities
5

6
### Compiler Build
7

8
Main build function for creating production bundles using the Remix compiler.
9

10
```typescript { .api }
11
/**
12
 * Build production bundles using Remix compiler
13
 * @param config - Resolved Remix configuration
14
 * @param options - Compilation options
15
 * @returns Promise that resolves when build completes
16
 */
17
namespace compiler {
18
  function build(config: RemixConfig, options?: CompileOptions): Promise<void>;
19
}
20

21
interface CompileOptions {
22
  /** Server mode for build (development/production) */
23
  mode?: ServerMode;
24
  
25
  /** Node.js target version */
26
  target?: "node14" | "node16" | "node18";
27
  
28
  /** Callback called when build starts */
29
  onBuildStart?: () => void;
30
  
31
  /** Callback called when build finishes */
32
  onBuildFinish?: (durationMs: number, okay?: boolean) => void;
33
  
34
  /** Callback called when file is created */
35
  onFileCreated?: (file: string) => void;
36
  
37
  /** Callback called when file is deleted */
38
  onFileDeleted?: (file: string) => void;
39
}
40

41
type ServerMode = "development" | "production" | "test";
42
```
43

44
### Watch Mode
45

46
Continuous compilation during development with file watching and incremental builds.
47

48
```typescript { .api }
49
/**
50
 * Start watch mode for continuous compilation
51
 * @param config - Resolved Remix configuration
52
 * @param options - Watch options
53
 * @returns Promise that resolves when watch stops
54
 */
55
namespace compiler {
56
  function watch(config: RemixConfig, options?: WatchOptions): Promise<void>;
57
}
58

59
interface WatchOptions {
60
  /** Server mode for watch builds */
61
  mode?: ServerMode;
62
  
63
  /** Callback called when build starts */
64
  onBuildStart?: () => void;
65
  
66
  /** Callback called when build finishes */
67
  onBuildFinish?: (durationMs: number, okay?: boolean) => void;
68
  
69
  /** Callback called when file is created */
70
  onFileCreated?: (file: string) => void;
71
  
72
  /** Callback called when file is deleted */
73
  onFileDeleted?: (file: string) => void;
74
  
75
  /** Callback called on initial build complete */
76
  onInitialBuild?: () => void;
77
  
78
  /** Callback called when rebuild starts */
79
  onRebuildStart?: () => void;
80
  
81
  /** Enable/disable file watching */
82
  watch?: boolean;
83
}
84
```
85

86
### CSS Compilation
87

88
CSS processing and bundling capabilities for Remix applications.
89

90
```typescript { .api }
91
/**
92
 * Create CSS compiler instance
93
 * @param options - CSS compiler options
94
 * @returns CSS compiler instance
95
 */
96
namespace css {
97
  function createCompiler(options: CSSCompilerOptions): CSSCompiler;
98
  
99
  /**
100
   * Write CSS bundle to filesystem
101
   * @param compiler - CSS compiler instance
102
   * @param manifest - Asset manifest
103
   * @param outputPath - Output path for CSS bundle
104
   * @returns Promise that resolves when bundle is written
105
   */
106
  function writeBundle(
107
    compiler: CSSCompiler, 
108
    manifest: AssetsManifest, 
109
    outputPath: string
110
  ): Promise<void>;
111
}
112

113
interface CSSCompilerOptions {
114
  /** Remix configuration */
115
  config: RemixConfig;
116
  
117
  /** CSS processing mode */
118
  mode: ServerMode;
119
  
120
  /** Enable source maps */
121
  sourcemap?: boolean;
122
}
123

124
interface CSSCompiler {
125
  /** Compile CSS from source */
126
  compile(source: string, filename: string): Promise<CSSCompileResult>;
127
  
128
  /** Process CSS bundle */
129
  bundle(files: string[]): Promise<string>;
130
}
131

132
interface CSSCompileResult {
133
  /** Compiled CSS code */
134
  code: string;
135
  
136
  /** Source map if enabled */
137
  map?: string;
138
  
139
  /** Dependencies discovered during compilation */
140
  dependencies: string[];
141
}
142
```
143

144
### Manifest Generation
145

146
Asset manifest creation and management for tracking build outputs.
147

148
```typescript { .api }
149
/**
150
 * Create asset manifest from build results
151
 * @param options - Manifest creation options
152
 * @returns Promise resolving to asset manifest
153
 */
154
namespace manifest {
155
  function create(options: ManifestCreateOptions): Promise<AssetsManifest>;
156
  
157
  /**
158
   * Write manifest to filesystem
159
   * @param config - Remix configuration
160
   * @param manifest - Asset manifest to write
161
   * @returns Promise that resolves when manifest is written
162
   */
163
  function write(config: RemixConfig, manifest: AssetsManifest): Promise<void>;
164
}
165

166
interface ManifestCreateOptions {
167
  /** Remix configuration */
168
  config: RemixConfig;
169
  
170
  /** Metafile from esbuild */
171
  metafile: Metafile;
172
  
173
  /** HMR information */
174
  hmr?: {
175
    timestamp: number;
176
    runtime: string;
177
  };
178
}
179
```
180

181
### Build Utilities
182

183
Utility functions for build processes and error handling.
184

185
```typescript { .api }
186
/**
187
 * Log thrown errors with proper formatting
188
 * @param thrown - Error or unknown value that was thrown
189
 */
190
function logThrown(thrown: unknown): void;
191

192
/**
193
 * Create lazy value for deferred computation
194
 * @param args - Lazy value creation arguments
195
 * @returns Lazy value instance
196
 */
197
function createLazyValue<T>(args: {
198
  /** Function to compute the value */
199
  get: () => T | Promise<T>;
200
  
201
  /** Optional function to dispose the value */
202
  dispose?: (value: T) => void | Promise<void>;
203
}): LazyValue<T>;
204

205
interface LazyValue<T> {
206
  /** Get the computed value */
207
  get(): Promise<T>;
208
  
209
  /** Dispose the value */
210
  dispose(): Promise<void>;
211
}
212
```
213

214
### Dependency Management
215

216
Functions for determining which dependencies should be bundled with the application.
217

218
```typescript { .api }
219
/**
220
 * Get application dependencies from package.json
221
 * @param config - Remix configuration
222
 * @returns Array of dependency names
223
 */
224
function getAppDependencies(config: RemixConfig): string[];
225

226
/**
227
 * Get dependencies that should be bundled with the server
228
 * @param pkg - Package names to check
229
 * @returns Array of dependencies to bundle
230
 */
231
function getDependenciesToBundle(...pkg: string[]): string[];
232
```
233

234
## Usage Examples
235

236
### Basic Production Build
237

238
```typescript
239
import { compiler, readConfig } from "@remix-run/dev";
240

241
async function buildApp() {
242
  const config = await readConfig();
243
  
244
  await compiler.build(config, {
245
    mode: "production",
246
    target: "node18",
247
    onBuildStart: () => console.log("Build started..."),
248
    onBuildFinish: (duration, success) => {
249
      if (success) {
250
        console.log(`Build completed in ${duration}ms`);
251
      } else {
252
        console.error("Build failed");
253
      }
254
    },
255
  });
256
}
257

258
buildApp().catch(console.error);
259
```
260

261
### Development Watch Mode
262

263
```typescript
264
import { compiler, readConfig } from "@remix-run/dev";
265

266
async function watchApp() {
267
  const config = await readConfig();
268
  
269
  await compiler.watch(config, {
270
    mode: "development", 
271
    onInitialBuild: () => console.log("Initial build complete"),
272
    onRebuildStart: () => console.log("Rebuilding..."),
273
    onBuildFinish: (duration, success) => {
274
      console.log(`Rebuild ${success ? 'completed' : 'failed'} in ${duration}ms`);
275
    },
276
    onFileCreated: (file) => console.log(`Created: ${file}`),
277
    onFileDeleted: (file) => console.log(`Deleted: ${file}`),
278
  });
279
}
280

281
watchApp().catch(console.error);
282
```
283

284
### Custom CSS Processing
285

286
```typescript
287
import { css, readConfig } from "@remix-run/dev";
288

289
async function processCss() {
290
  const config = await readConfig();
291
  
292
  const cssCompiler = css.createCompiler({
293
    config,
294
    mode: "production",
295
    sourcemap: true,
296
  });
297
  
298
  const result = await cssCompiler.compile(
299
    `
300
    .button {
301
      background: blue;
302
      color: white;
303
      padding: 10px;
304
    }
305
    `,
306
    "styles.css"
307
  );
308
  
309
  console.log("Compiled CSS:", result.code);
310
  console.log("Dependencies:", result.dependencies);
311
}
312

313
processCss().catch(console.error);
314
```
315

316
### Manifest Generation
317

318
```typescript
319
import { manifest, readConfig } from "@remix-run/dev";
320

321
async function createManifest() {
322
  const config = await readConfig();
323
  
324
  // This would typically be provided by esbuild after compilation
325
  const mockMetafile = {
326
    inputs: {},
327
    outputs: {
328
      "build/assets/entry.client-HASH.js": {
329
        bytes: 1000,
330
        imports: [],
331
        exports: [],
332
      },
333
    },
334
  };
335
  
336
  const assetManifest = await manifest.create({
337
    config,
338
    metafile: mockMetafile,
339
    hmr: {
340
      timestamp: Date.now(),
341
      runtime: "build/assets/hmr-runtime-HASH.js",
342
    },
343
  });
344
  
345
  await manifest.write(config, assetManifest);
346
  console.log("Manifest created:", assetManifest);
347
}
348

349
createManifest().catch(console.error);
350
```
351

352
### Build with Dependencies
353

354
```typescript
355
import { compiler, readConfig, getDependenciesToBundle } from "@remix-run/dev";
356

357
async function buildWithDeps() {
358
  const config = await readConfig();
359
  
360
  // Get dependencies to bundle
361
  const depsToBundle = getDependenciesToBundle(
362
    "lodash",
363
    "date-fns",
364
    /^@my-org\/.*/
365
  );
366
  
367
  console.log("Bundling dependencies:", depsToBundle);
368
  
369
  // Update config with dependencies to bundle
370
  const buildConfig = {
371
    ...config,
372
    serverDependenciesToBundle: depsToBundle,
373
  };
374
  
375
  await compiler.build(buildConfig, {
376
    mode: "production",
377
    target: "node18",
378
  });
379
}
380

381
buildWithDeps().catch(console.error);
382
```
383

384
### Error Handling and Logging
385

386
```typescript
387
import { compiler, logThrown, readConfig } from "@remix-run/dev";
388

389
async function buildWithErrorHandling() {
390
  try {
391
    const config = await readConfig();
392
    
393
    await compiler.build(config, {
394
      mode: "production",
395
      onBuildFinish: (duration, success) => {
396
        if (!success) {
397
          console.error("Build failed");
398
        }
399
      },
400
    });
401
  } catch (error) {
402
    logThrown(error);
403
    process.exit(1);
404
  }
405
}
406

407
buildWithErrorHandling();
408
```