0
# Local Development
1

2
Local development server functionality that provides Netlify's proxy, redirect rules, serverless function support, and edge function capabilities in a local environment that mirrors production.
3

4
## Capabilities
5

6
### Dev Command
7

8
Starts a local development server with Netlify's full feature set including functions, redirects, and edge functions.
9

10
```typescript { .api }
11
/**
12
 * Start local development server with Netlify features
13
 * Command: netlify dev [options]
14
 */
15
interface DevOptions {
16
  /** Command to run for the application server */
17
  command?: string;
18
  /** Deploy context for environment variables (default: dev) */
19
  context?: string;
20
  /** Port for Netlify dev server */
21
  port?: number;
22
  /** Skip waiting for target port to be available */
23
  skipWaitPort?: boolean;
24
  /** Disable automatic browser opening */
25
  noOpen?: boolean;
26
  /** Target application server port */
27
  targetPort?: number;
28
  /** Framework to use (#auto for auto-detection) */
29
  framework?: string;
30
  /** Static files directory */
31
  dir?: string;
32
  /** Functions folder */
33
  functions?: string;
34
  /** Disable network-dependent features */
35
  offline?: boolean;
36
  /** Disable fetching environment variables from Netlify */
37
  offlineEnv?: boolean;
38
  /** Disable edge functions */
39
  internalDisableEdgeFunctions?: boolean;
40
  /** Start public live session with optional subdomain */
41
  live?: string | boolean;
42
  /** Functions server port */
43
  functionsPort?: number;
44
  /** Geolocation mode: cache, mock, or update */
45
  geo?: 'cache' | 'mock' | 'update';
46
  /** Two-letter country code for mock geolocation */
47
  country?: string;
48
  /** Static server port */
49
  staticServerPort?: number;
50
  /** Enable V8 Inspector for Edge Functions with optional address */
51
  edgeInspect?: string | boolean;
52
  /** Enable V8 Inspector for Edge Functions with break on start */
53
  edgeInspectBrk?: string | boolean;
54
  /** Skip adding .netlify to .gitignore */
55
  skipGitignore?: boolean;
56
}
57
```
58

59
**Usage Examples:**
60

61
```bash
62
# Basic dev server
63
netlify dev
64

65
# Dev server with custom port
66
netlify dev --port 8080
67

68
# Dev server with specific framework detection
69
netlify dev --framework react
70

71
# Dev server with custom command
72
netlify dev --command "npm run start:custom"
73

74
# Dev server with functions in custom directory
75
netlify dev --functions ./my-functions
76

77
# Dev server with live tunneling
78
netlify dev --live
79

80
# Dev server with custom live subdomain
81
netlify dev --live my-project
82

83
# Dev server with geolocation mocking
84
netlify dev --geo mock --country US
85

86
# Dev server with edge function debugging
87
netlify dev --edge-inspect
88

89
# Offline development mode
90
netlify dev --offline
91
```
92

93
### Dev Exec Command
94

95
Executes commands in the development environment context with access to environment variables and Netlify configuration.
96

97
```typescript { .api }
98
/**
99
 * Execute command in development context
100
 * Command: netlify dev-exec <command...>
101
 */
102
interface DevExecOptions {
103
  /** Deploy context for environment variables */
104
  context?: string;
105
}
106
```
107

108
**Usage Examples:**
109

110
```bash
111
# Run tests in dev context
112
netlify dev-exec npm test
113

114
# Run database migrations with dev environment
115
netlify dev-exec npm run migrate
116

117
# Execute custom script with Netlify environment
118
netlify dev-exec node scripts/seed-db.js
119

120
# Run with specific context
121
netlify dev-exec --context production npm run check
122
```
123

124
### Framework Detection
125

126
The dev server automatically detects popular frameworks and configures appropriate settings:
127

128
```typescript { .api }
129
type SupportedFrameworks = 
130
  | 'gatsby'
131
  | 'create-react-app' 
132
  | 'vue-cli'
133
  | 'nuxt'
134
  | 'next'
135
  | 'angular'
136
  | 'ember'
137
  | 'hugo'
138
  | 'jekyll'
139
  | 'eleventy'
140
  | 'svelte'
141
  | 'vite'
142
  | 'remix'
143
  | 'astro'
144
  | '#auto'     // Auto-detection
145
  | '#static'   // Static files only
146
  | '#custom';  // Custom configuration
147

148
interface FrameworkConfig {
149
  command?: string;        // Development command
150
  port?: number;          // Default development port
151
  env?: Record<string, string>; // Framework-specific environment variables
152
  pollingStrategies?: string[]; // File watching strategies
153
  dist?: string;          // Build output directory
154
}
155
```
156

157
### Live Tunneling
158

159
Creates public URLs for local development, enabling sharing and testing of local sites.
160

161
```typescript { .api }
162
/**
163
 * Live session configuration for public access to local development
164
 */
165
interface LiveSession {
166
  /** Custom subdomain for the live session */
167
  subdomain?: string;
168
  /** Generated public URL */
169
  url: string;
170
  /** Session expiration time */
171
  expiresAt: Date;
172
  /** Whether HTTPS is enabled */
173
  https: boolean;
174
}
175
```
176

177
**Usage Examples:**
178

179
```bash
180
# Start live session with auto-generated subdomain
181
netlify dev --live
182

183
# Start live session with custom subdomain
184
netlify dev --live my-awesome-project
185

186
# Live session outputs:
187
# ◈ Server now ready on http://localhost:8888
188
# ◈ Live session: https://my-awesome-project.netlify.live
189
```
190

191
### Geolocation Support
192

193
Provides geolocation context for testing location-based features locally.
194

195
```typescript { .api }
196
/**
197
 * Geolocation configuration for local development
198
 */
199
interface GeoConfig {
200
  /** Geolocation mode */
201
  mode: 'cache' | 'mock' | 'update';
202
  /** Country code for mock mode */
203
  country?: string;
204
  /** Cached geolocation data */
205
  cache?: {
206
    country: string;
207
    subdivision: string;
208
    city: string;
209
    timezone: string;
210
  };
211
}
212
```
213

214
**Usage Examples:**
215

216
```bash
217
# Mock geolocation for US
218
netlify dev --geo mock --country US
219

220
# Mock geolocation for UK
221
netlify dev --geo mock --country GB
222

223
# Cache geolocation data
224
netlify dev --geo cache
225

226
# Update geolocation cache
227
netlify dev --geo update
228
```
229

230
### Edge Function Debugging
231

232
Provides V8 Inspector integration for debugging Edge Functions locally.
233

234
```typescript { .api }
235
/**
236
 * Edge function debugging configuration
237
 */
238
interface EdgeInspectorConfig {
239
  /** Inspector address (default: 127.0.0.1:9229) */
240
  address?: string;
241
  /** Break on start */
242
  breakOnStart?: boolean;
243
  /** Inspector port */
244
  port?: number;
245
}
246
```
247

248
**Usage Examples:**
249

250
```bash
251
# Enable edge function debugging
252
netlify dev --edge-inspect
253

254
# Debug with custom address
255
netlify dev --edge-inspect 0.0.0.0:9230
256

257
# Debug with break on start
258
netlify dev --edge-inspect-brk
259

260
# Then connect Chrome DevTools to chrome://inspect
261
```
262

263
### Configuration Files
264

265
The dev server respects various configuration files for customization:
266

267
```typescript { .api }
268
/**
269
 * Development configuration sources
270
 */
271
interface DevConfigSources {
272
  /** netlify.toml configuration */
273
  netlifyToml?: {
274
    dev?: {
275
      command?: string;
276
      port?: number;
277
      targetPort?: number;
278
      framework?: string;
279
      autoLaunch?: boolean;
280
    };
281
  };
282
  /** package.json scripts and netlify key */
283
  packageJson?: {
284
    scripts?: Record<string, string>;
285
    netlify?: {
286
      dev?: DevOptions;
287
    };
288
  };
289
  /** .netlify/state.json for site linking */
290
  siteState?: {
291
    siteId: string;
292
    adminUrl: string;
293
    url: string;
294
  };
295
}
296
```
297

298
### Environment Integration
299

300
Automatic environment variable loading and context switching:
301

302
```typescript { .api }
303
/**
304
 * Environment variable sources in development
305
 */
306
interface DevEnvironment {
307
  /** Local .env files (in priority order) */
308
  localEnvFiles: [
309
    '.env.local',
310
    '.env.development',
311
    '.env'
312
  ];
313
  /** Netlify environment variables from the dashboard */
314
  netlifyEnv?: Record<string, string>;
315
  /** Context-specific variables */
316
  contextEnv?: Record<string, string>;
317
  /** Injected Netlify-specific variables */
318
  netlifyVars: {
319
    NETLIFY: 'true';
320
    NETLIFY_DEV: 'true';
321
    NETLIFY_LOCAL: 'true';
322
    URL: string;
323
    DEPLOY_URL: string;
324
    CONTEXT: string;
325
    BRANCH: string;
326
    HEAD: string;
327
    COMMIT_REF: string;
328
    REPOSITORY_URL: string;
329
  };
330
}
331
```