0
# @remix-run/dev
1

2
@remix-run/dev provides essential development tools and CLI for Remix, a full stack web framework focused on user interface and web fundamentals. It includes build tools, development server, bundling capabilities, and command-line utilities that enable developers to create, develop, and deploy Remix applications with TypeScript support, Hot Module Replacement (HMR), and integration with various deployment targets.
3

4
## Package Information
5

6
- **Package Name**: @remix-run/dev
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install -D @remix-run/dev`
10

11
## Core Imports
12

13
```typescript
14
import { vitePlugin, cloudflareDevProxyVitePlugin, getDependenciesToBundle } from "@remix-run/dev";
15
import type { AppConfig, RemixConfig, VitePluginConfig, AssetsManifest } from "@remix-run/dev";
16
import * as cli from "@remix-run/dev";
17
```
18

19
For CLI access:
20
```bash
21
npx remix --help
22
```
23

24
CommonJS:
25
```javascript
26
const { vitePlugin, cloudflareDevProxyVitePlugin, getDependenciesToBundle } = require("@remix-run/dev");
27
```
28

29
## Basic Usage
30

31
```typescript
32
// vite.config.ts
33
import { defineConfig } from "vite";
34
import { vitePlugin } from "@remix-run/dev";
35

36
export default defineConfig({
37
  plugins: [vitePlugin()],
38
});
39
```
40

41
```typescript
42
// remix.config.js
43
import type { AppConfig } from "@remix-run/dev";
44

45
export default {
46
  appDirectory: "app",
47
  assetsBuildDirectory: "public/build", 
48
  publicPath: "/build/",
49
  routes(defineRoutes) {
50
    return defineRoutes((route) => {
51
      route("/", "routes/home.tsx");
52
    });
53
  }
54
} satisfies AppConfig;
55
```
56

57
## Architecture
58

59
@remix-run/dev is built around several key systems:
60

61
- **Vite Integration**: Modern build tooling with the Remix Vite plugin for development and production builds
62
- **CLI System**: Command-line interface providing `init`, `build`, `dev`, and `routes` commands
63
- **Configuration System**: Flexible configuration with TypeScript support and future flags
64
- **Route Management**: Advanced routing with flat routes, custom route definitions, and manifest generation
65
- **Development Server**: Live reload, HMR, and development-time features
66
- **Compiler System**: Legacy esbuild-based compilation system (being replaced by Vite)
67

68
## Capabilities
69

70
### Vite Integration
71

72
Modern build system integration with Vite providing fast development experience, optimized production builds, and plugin ecosystem support.
73

74
```typescript { .api }
75
function vitePlugin(config?: Partial<VitePluginConfig>): RemixVitePlugin;
76

77
interface VitePluginConfig {
78
  appDirectory?: string;
79
  assetsBuildDirectory?: string;
80
  buildDirectory?: string;
81
  entryClientFile?: string;
82
  entryServerFile?: string;
83
  publicPath?: string;
84
  routes?: AppConfig["routes"];
85
  ssr?: boolean;
86
  serverBuildFile?: string;
87
  ignoredRouteFiles?: string[];
88
  future?: Partial<FutureConfig>;
89
  basename?: string;
90
  buildEnd?: (args: { viteConfig: ResolvedViteConfig }) => void | Promise<void>;
91
  presets?: Preset[];
92
  serverBundles?: ServerBundlesFunction;
93
}
94

95
type RemixVitePlugin = (config?: VitePluginConfig) => Plugin[];
96

97
interface Preset {
98
  name: string;
99
  remixConfig?: () => AppConfig | Promise<AppConfig>;
100
  remixConfigResolved?: (remixConfig: RemixConfig) => void | Promise<void>;
101
  viteConfig?: (env: { mode: string; command: string }) => ViteUserConfig | Promise<ViteUserConfig>;
102
}
103

104
type ServerBundlesFunction = (args: {
105
  branch: RouteManifestEntry[];
106
}) => string;
107

108
function cloudflareDevProxyVitePlugin<Env = {}, Cf extends CfProperties = {}>(
109
  options: CloudflareDevProxyOptions<Env, Cf>
110
): Plugin;
111
```
112

113
[Vite Integration](./vite-integration.md)
114

115
### CLI Commands
116

117
Complete command-line interface for Remix project management including project initialization, development server, build system, and route inspection.
118

119
```typescript { .api }
120
// CLI module exports (import * as cli from "@remix-run/dev")
121
function init(projectDir: string, options?: InitFlags): Promise<void>;
122
function routes(remixRoot?: string, flags?: RoutesFlags): Promise<void>;
123
function build(remixRoot: string, mode?: string, sourcemap?: boolean): Promise<void>;
124
function viteBuild(root?: string, options?: ViteBuildOptions): Promise<void>;
125
function watch(remixRootOrConfig: string | RemixConfig, mode?: string): Promise<void>;
126
function dev(remixRoot: string, flags?: DevFlags): Promise<void>;
127
function viteDev(root: string, options?: ViteDevOptions): Promise<void>;
128
function generateEntry(entry: string, remixRoot: string, flags?: GenerateEntryFlags): Promise<void>;
129
function setup(): void; // deprecated
130

131
interface InitFlags {
132
  deleteScript?: boolean;
133
}
134

135
interface RoutesFlags {
136
  config?: string;
137
  json?: boolean;
138
}
139

140
interface DevFlags {
141
  command?: string;
142
  manual?: boolean;
143
  port?: number;
144
  tlsKey?: string;
145
  tlsCert?: string;
146
}
147

148
interface GenerateEntryFlags {
149
  typescript?: boolean;
150
  config?: string;
151
}
152

153
interface ViteBuildOptions {
154
  assetsInlineLimit?: number;
155
  clearScreen?: boolean;
156
  config?: string;
157
  emptyOutDir?: boolean;
158
  logLevel?: "info" | "warn" | "error" | "silent";
159
  minify?: boolean | "terser" | "esbuild";
160
  mode?: string;
161
  profile?: boolean;
162
  sourcemap?: boolean | "inline" | "hidden";
163
  target?: string | string[];
164
  watch?: object;
165
}
166

167
interface ViteDevOptions {
168
  clearScreen?: boolean;
169
  config?: string;
170
  cors?: boolean;
171
  force?: boolean;
172
  host?: string | boolean;
173
  logLevel?: "info" | "warn" | "error" | "silent";
174
  mode?: string;
175
  open?: boolean | string;
176
  port?: number;
177
  profile?: boolean;
178
  strictPort?: boolean;
179
}
180
```
181

182
[CLI Commands](./cli-commands.md)
183

184
### Configuration System
185

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

188
```typescript { .api }
189
interface AppConfig {
190
  appDirectory?: string;
191
  assetsBuildDirectory?: string;
192
  cacheDirectory?: string;
193
  publicPath?: string;
194
  routes?: (defineRoutes: DefineRoutesFunction) => ReturnType<DefineRoutesFunction> | Promise<ReturnType<DefineRoutesFunction>>;
195
  serverBuildPath?: string;
196
  serverConditions?: string[];
197
  serverDependenciesToBundle?: string[] | RegExp | ((id: string) => boolean);
198
  serverMainFields?: string[];
199
  serverMinify?: boolean;
200
  serverModuleFormat?: ServerModuleFormat;
201
  serverPlatform?: ServerPlatform;
202
  tailwind?: boolean;
203
  postcss?: boolean;
204
  future?: Partial<FutureConfig>;
205
  mdx?: RemixMdxConfig | RemixMdxConfigFunction;
206
}
207

208
function readConfig(remixRoot?: string, serverMode?: ServerMode): Promise<RemixConfig>;
209
function resolveConfig(appConfig: AppConfig, options: ResolveConfigOptions): Promise<RemixConfig>;
210
```
211

212
[Configuration](./configuration.md)
213

214
### Route Management
215

216
Advanced routing system supporting flat routes, custom route definitions, nested routes, and dynamic route generation with TypeScript support.
217

218
```typescript { .api }
219
function UNSAFE_defineRoutes(callback: (defineRoutes: DefineRouteFunction) => void): RouteManifest;
220

221
interface DefineRouteFunction {
222
  (
223
    path: string | undefined,
224
    file: string,
225
    optionsOrChildren?: DefineRouteOptions | (() => void),
226
    children?: () => void
227
  ): void;
228
}
229

230
function UNSAFE_flatRoutes(
231
  appDirectory: string,
232
  ignoredFilePatterns?: string[],
233
  prefix?: string
234
): RouteManifest;
235
```
236

237
[Route Management](./route-management.md)
238

239
### Build System
240

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

243
```typescript { .api }
244
// Build-related functions from CLI
245
function build(remixRoot: string, mode?: string, sourcemap?: boolean): Promise<void>;
246
function viteBuild(root?: string, options?: ViteBuildOptions): Promise<void>;
247
function watch(remixRootOrConfig: string | RemixConfig, mode?: string): Promise<void>;
248
```
249

250
[Build System](./build-system.md)
251

252
### Development Server
253

254
Development server with live reload, Hot Module Replacement (HMR), and development-time optimizations.
255

256
```typescript { .api }
257
// Development server functions
258
function dev(remixRoot: string, flags?: DevFlags): Promise<void>;
259
function viteDev(root: string, options?: ViteDevOptions): Promise<void>;
260
```
261

262
[Development Server](./development-server.md)
263

264
### Utility Functions
265

266
Helper functions for dependency management and configuration.
267

268
```typescript { .api }
269
function getDependenciesToBundle(...pkg: string[]): string[];
270
```
271

272
## Types
273

274
```typescript { .api }
275
type ServerModuleFormat = "esm" | "cjs";
276
type ServerPlatform = "node" | "neutral";
277

278
interface RemixConfig extends Required<AppConfig> {
279
  rootDirectory: string;
280
  appDirectory: string;
281
  cacheDirectory: string;
282
  assetsBuildDirectory: string;
283
  relativeAssetsBuildDirectory: string;
284
  publicPath: string;
285
  routes: RouteManifest;
286
  serverBuildPath: string;
287
  entryClientFile: string;
288
  entryServerFile: string;
289
  tsconfigPath: string | undefined;
290
  future: FutureConfig;
291
}
292

293
interface FutureConfig {
294
  v3_fetcherPersist: boolean;
295
  v3_relativeSplatPath: boolean;
296
  v3_throwAbortReason: boolean;
297
  v3_routeConfig: boolean;
298
  v3_singleFetch: boolean;
299
  v3_lazyRouteDiscovery: boolean;
300
  unstable_optimizeDeps: boolean;
301
}
302

303
type AssetsManifest = {
304
  version: string;
305
  url?: string;
306
  entry: {
307
    module: string;
308
    imports: string[];
309
  };
310
  routes: {
311
    [routeId: string]: {
312
      id: string;
313
      parentId?: string;
314
      path?: string;
315
      index?: boolean;
316
      caseSensitive?: boolean;
317
      module: string;
318
      imports?: string[];
319
      hasAction: boolean;
320
      hasLoader: boolean;
321
      hasClientAction: boolean;
322
      hasClientLoader: boolean;
323
      hasErrorBoundary: boolean;
324
    };
325
  };
326
  hmr?: {
327
    timestamp?: number;
328
    runtime: string;
329
  };
330
};
331

332
interface RouteManifest {
333
  [routeId: string]: RouteManifestEntry;
334
}
335

336
interface RouteManifestEntry {
337
  id: string;
338
  parentId?: string;
339
  path?: string;
340
  index?: boolean;
341
  caseSensitive?: boolean;
342
  file: string;
343
  hasAction: boolean;
344
  hasLoader: boolean;
345
  hasClientAction: boolean;
346
  hasClientLoader: boolean;
347
  hasErrorBoundary: boolean;
348
  imports?: string[];
349
}
350
```