0
# Configuration
1

2
Flexible configuration system supporting TypeScript with comprehensive options for app structure, build settings, routing, and future flags.
3

4
## Capabilities
5

6
### App Configuration
7

8
User-provided configuration interface for customizing Remix application behavior.
9

10
```typescript { .api }
11
/**
12
 * User-provided configuration for Remix applications
13
 */
14
interface AppConfig {
15
  /** Path to app directory relative to remix.config.js (default: "app") */
16
  appDirectory?: string;
17
  
18
  /** Path to assets build directory relative to remix.config.js (default: "public/build") */
19
  assetsBuildDirectory?: string;
20
  
21
  /** Path to cache directory relative to remix.config.js (default: ".cache") */
22
  cacheDirectory?: string;
23
  
24
  /** URL prefix for browser build with trailing slash (default: "/build/") */
25
  publicPath?: string;
26
  
27
  /** Function for defining custom routes in addition to filesystem routes */
28
  routes?: (
29
    defineRoutes: DefineRoutesFunction
30
  ) => ReturnType<DefineRoutesFunction> | Promise<ReturnType<DefineRoutesFunction>>;
31
  
32
  /** Path to server build output relative to remix.config.js */
33
  serverBuildPath?: string;
34
  
35
  /** Conditions to use when resolving server dependencies */
36
  serverConditions?: string[];
37
  
38
  /** Dependencies to bundle with server build */
39
  serverDependenciesToBundle?: "all" | Array<string | RegExp>;
40
  
41
  /** Fields to use when resolving server dependencies */
42
  serverMainFields?: string[];
43
  
44
  /** Whether to minify server build */
45
  serverMinify?: boolean;
46
  
47
  /** Server module format */
48
  serverModuleFormat?: ServerModuleFormat;
49
  
50
  /** Node.js polyfills for server build when targeting non-Node.js platforms */
51
  serverNodeBuiltinsPolyfill?: NodeBuiltinsPolyfillOptions;
52
  
53
  /** Node.js polyfills for browser build */
54
  browserNodeBuiltinsPolyfill?: NodeBuiltinsPolyfillOptions;
55
  
56
  /** Server platform target */
57
  serverPlatform?: ServerPlatform;
58
  
59
  /** Server entrypoint file relative to root directory */
60
  server?: string;
61
  
62
  /** Enable Tailwind CSS support */
63
  tailwind?: boolean;
64
  
65
  /** Enable PostCSS support */
66
  postcss?: boolean;
67
  
68
  /** Patterns for ignored route files in app/routes directory */
69
  ignoredRouteFiles?: string[];
70
  
71
  /** Custom directories to watch during development */
72
  watchPaths?: string | string[] | (() => Promise<string | string[]> | string | string[]);
73
  
74
  /** Development server options */
75
  dev?: DevConfig;
76
  
77
  /** Future feature flags */
78
  future?: Partial<FutureConfig>;
79
  
80
  /** MDX configuration */
81
  mdx?: RemixMdxConfig | RemixMdxConfigFunction;
82
}
83

84
type ServerModuleFormat = "esm" | "cjs";
85
type ServerPlatform = "node" | "neutral";
86

87
interface DevConfig {
88
  /** Command to run for manual development mode */
89
  command?: string;
90
  /** Manual mode - don't start dev server automatically */
91
  manual?: boolean;
92
  /** Development server port */
93
  port?: number;
94
  /** TLS key file for HTTPS */
95
  tlsKey?: string;
96
  /** TLS certificate file for HTTPS */
97
  tlsCert?: string;
98
}
99

100
interface NodeBuiltinsPolyfillOptions {
101
  /** Node.js modules to polyfill */
102
  modules?: Record<string, string | false>;
103
  /** Node.js globals to polyfill */
104
  globals?: Record<string, string | false>;
105
}
106
```
107

108
### Resolved Configuration
109

110
Fully resolved configuration with all defaults applied and computed properties.
111

112
```typescript { .api }
113
/**
114
 * Fully resolved Remix configuration with defaults applied
115
 */
116
interface RemixConfig extends Required<AppConfig> {
117
  /** Root directory of the project */
118
  rootDirectory: string;
119
  
120
  /** Absolute path to app directory */
121
  appDirectory: string;
122
  
123
  /** Absolute path to cache directory */
124
  cacheDirectory: string;
125
  
126
  /** Absolute path to assets build directory */
127
  assetsBuildDirectory: string;
128
  
129
  /** Relative path to assets build directory */
130
  relativeAssetsBuildDirectory: string;
131
  
132
  /** Public path for assets */
133
  publicPath: string;
134
  
135
  /** Resolved route manifest */
136
  routes: RouteManifest;
137
  
138
  /** Absolute path to server build output */
139
  serverBuildPath: string;
140
  
141
  /** Entry client file path */
142
  entryClientFile: string;
143
  
144
  /** Entry server file path */
145
  entryServerFile: string;
146
  
147
  /** Path to tsconfig.json if present */
148
  tsconfigPath: string | undefined;
149
  
150
  /** Future feature flags with all defaults */
151
  future: FutureConfig;
152
}
153
```
154

155
### Configuration Functions
156

157
Functions for reading, resolving, and finding configuration files.
158

159
```typescript { .api }
160
/**
161
 * Read and parse Remix configuration file
162
 * @param remixRoot - Root directory to search for config (default: process.cwd())
163
 * @param serverMode - Server mode for configuration
164
 * @returns Promise resolving to resolved configuration
165
 */
166
function readConfig(
167
  remixRoot?: string, 
168
  serverMode?: ServerMode
169
): Promise<RemixConfig>;
170

171
/**
172
 * Resolve configuration by applying defaults and computing derived values
173
 * @param appConfig - User-provided app configuration
174
 * @param options - Configuration resolution options
175
 * @returns Promise resolving to resolved configuration
176
 */
177
function resolveConfig(
178
  appConfig: AppConfig, 
179
  options: ResolveConfigOptions
180
): Promise<RemixConfig>;
181

182
interface ResolveConfigOptions {
183
  /** Root directory */
184
  rootDirectory: string;
185
  /** Server mode */
186
  serverMode?: ServerMode;
187
  /** App directory */
188
  appDirectory?: string;
189
  /** Cache directory */
190
  cacheDirectory?: string;
191
  /** Assets build directory */
192
  assetsBuildDirectory?: string;
193
  /** Public path */
194
  publicPath?: string;
195
  /** Entry client file */
196
  entryClientFile?: string;
197
  /** Entry server file */
198
  entryServerFile?: string;
199
  /** Server build path */
200
  serverBuildPath?: string;
201
  /** TypeScript config path */
202
  tsconfigPath?: string;
203
}
204

205
/**
206
 * Find configuration file in directory
207
 * @param dir - Directory to search
208
 * @param basename - Base name of config file (e.g., "remix.config")
209
 * @param extensions - File extensions to try
210
 * @returns Path to config file or undefined if not found
211
 */
212
function findConfig(
213
  dir: string,
214
  basename: string,
215
  extensions: string[]
216
): string | undefined;
217
```
218

219
### Future Configuration
220

221
Feature flags for upcoming Remix features and breaking changes.
222

223
```typescript { .api }
224
/**
225
 * Future feature flags configuration
226
 */
227
interface FutureConfig {
228
  /** Enable fetcher persistence across navigations */
229
  v3_fetcherPersist: boolean;
230
  
231
  /** Enable relative path resolution for splat routes */
232
  v3_relativeSplatPath: boolean;
233
  
234
  /** Enable throwing abort reasons in loaders/actions */
235
  v3_throwAbortReason: boolean;
236
  
237
  /** Enable route configuration API */
238
  v3_routeConfig: boolean;
239
  
240
  /** Enable single fetch optimization */
241
  v3_singleFetch: boolean;
242
  
243
  /** Enable lazy route discovery */
244
  v3_lazyRouteDiscovery: boolean;
245
  
246
  /** Enable unstable dependency optimization */
247
  unstable_optimizeDeps: boolean;
248
}
249

250
/**
251
 * Log warnings for future flags that will become defaults
252
 * @param future - Future configuration to check
253
 */
254
function logFutureFlagWarnings(future: Partial<FutureConfig>): void;
255
```
256

257
### MDX Configuration
258

259
Configuration for MDX file processing in Remix applications.
260

261
```typescript { .api }
262
/**
263
 * MDX configuration for Remix
264
 */
265
interface RemixMdxConfig {
266
  /** Rehype plugins for MDX processing */
267
  rehypePlugins?: any[];
268
  
269
  /** Remark plugins for MDX processing */
270
  remarkPlugins?: any[];
271
}
272

273
/**
274
 * Function that returns MDX configuration
275
 * @param filename - Path to MDX file being processed
276
 * @returns MDX configuration or undefined
277
 */
278
type RemixMdxConfigFunction = (
279
  filename: string
280
) => Promise<RemixMdxConfig | undefined> | RemixMdxConfig | undefined;
281
```
282

283
## Usage Examples
284

285
### Basic Configuration
286

287
```typescript
288
// remix.config.js
289
import type { AppConfig } from "@remix-run/dev";
290

291
export default {
292
  appDirectory: "app",
293
  assetsBuildDirectory: "public/build",
294
  publicPath: "/build/",
295
  serverBuildPath: "build/index.js",
296
  ignoredRouteFiles: ["**/.*"],
297
} satisfies AppConfig;
298
```
299

300
### Advanced Configuration with Custom Routes
301

302
```typescript
303
// remix.config.js
304
import type { AppConfig } from "@remix-run/dev";
305

306
export default {
307
  appDirectory: "app",
308
  routes(defineRoutes) {
309
    return defineRoutes((route) => {
310
      route("/", "routes/home.tsx");
311
      route("/admin", "routes/admin.tsx", () => {
312
        route("/users", "routes/admin/users.tsx");
313
        route("/settings", "routes/admin/settings.tsx");
314
      });
315
    });
316
  },
317
  future: {
318
    v3_singleFetch: true,
319
    v3_lazyRouteDiscovery: true,
320
    v3_fetcherPersist: true,
321
  },
322
  serverDependenciesToBundle: [
323
    /^remix-utils.*/,
324
    "marked",
325
  ],
326
  mdx: {
327
    remarkPlugins: [remarkGfm],
328
    rehypePlugins: [rehypeHighlight],
329
  },
330
} satisfies AppConfig;
331
```
332

333
### TypeScript Configuration
334

335
```typescript
336
// remix.config.ts
337
import type { AppConfig } from "@remix-run/dev";
338

339
const config: AppConfig = {
340
  appDirectory: "app",
341
  assetsBuildDirectory: "public/build",
342
  publicPath: "/build/",
343
  serverModuleFormat: "esm",
344
  serverPlatform: "node",
345
  serverMinify: true,
346
  tailwind: true,
347
  postcss: true,
348
  future: {
349
    v3_routeConfig: true,
350
    v3_singleFetch: true,
351
    v3_lazyRouteDiscovery: true,
352
    v3_relativeSplatPath: true,
353
    v3_throwAbortReason: true,
354
    v3_fetcherPersist: true,
355
    unstable_optimizeDeps: true,
356
  },
357
};
358

359
export default config;
360
```
361

362
### Reading Configuration Programmatically
363

364
```typescript
365
import { readConfig, resolveConfig } from "@remix-run/dev";
366

367
// Read configuration from remix.config.js
368
const config = await readConfig("./my-remix-app");
369

370
// Resolve configuration with custom options
371
const resolvedConfig = await resolveConfig(
372
  {
373
    appDirectory: "src",
374
    publicPath: "/assets/",
375
  },
376
  {
377
    rootDirectory: process.cwd(),
378
    serverMode: "production",
379
  }
380
);
381

382
console.log("Routes:", Object.keys(config.routes));
383
console.log("Build directory:", config.assetsBuildDirectory);
384
```