0
# Configuration
1

2
Project and platform configuration management for customizing Surge deployments, managing project settings, and configuring platform behavior.
3

4
## Capabilities
5

6
### Configuration Management
7

8
View and modify project and platform configuration settings.
9

10
```javascript { .api }
11
/**
12
 * View and change project configuration settings
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function config(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# View project configuration
22
surge config example.surge.sh
23

24
# Interactive configuration menu
25
surge config
26

27
# Set specific configuration value
28
surge config example.surge.sh --set ssl.enabled true
29

30
# View global platform settings
31
surge config --global
32
```
33

34
**Configuration Options:**
35
- Project-specific settings
36
- Global platform defaults
37
- User preferences
38
- Team-wide configurations
39
- Environment-specific settings
40

41
**Library Usage:**
42
```javascript
43
surge.config({})(process.argv.slice(2));
44
```
45

46
## Project Configuration
47

48
### Basic Project Settings
49

50
**Project Metadata:**
51
```bash
52
# Set project name
53
surge config example.surge.sh --name "My Website"
54

55
# Set project description
56
surge config example.surge.sh --description "Company marketing site"
57

58
# Set project tags
59
surge config example.surge.sh --tags "production,marketing,website"
60
```
61

62
**Deployment Settings:**
63
```bash
64
# Set default deployment directory
65
surge config example.surge.sh --build-dir ./dist
66

67
# Set deployment branch
68
surge config example.surge.sh --branch main
69

70
# Enable/disable automatic deployments
71
surge config example.surge.sh --auto-deploy true
72
```
73

74
### Advanced Project Configuration
75

76
**Custom Domains:**
77
```bash
78
# Set custom domain
79
surge config example.surge.sh --domain example.com
80

81
# Configure domain aliases
82
surge config example.surge.sh --aliases www.example.com,app.example.com
83

84
# Set apex domain redirect
85
surge config example.surge.sh --apex-redirect www.example.com
86
```
87

88
**SSL Configuration:**
89
```bash
90
# Enable SSL
91
surge config example.surge.sh --ssl enabled
92

93
# Set SSL provider
94
surge config example.surge.sh --ssl-provider letsencrypt
95

96
# Configure SSL enforcement
97
surge config example.surge.sh --ssl-enforce true
98

99
# Set custom SSL certificate
100
surge config example.surge.sh --ssl-cert ./cert.pem --ssl-key ./key.pem
101
```
102

103
### Build Configuration
104

105
**Build Settings:**
106
```bash
107
# Set build command
108
surge config example.surge.sh --build-command "npm run build"
109

110
# Set build directory
111
surge config example.surge.sh --build-output "./dist"
112

113
# Configure environment variables
114
surge config example.surge.sh --env NODE_ENV=production --env API_URL=https://api.example.com
115

116
# Set build timeout
117
surge config example.surge.sh --build-timeout 300
118
```
119

120
**File Processing:**
121
```bash
122
# Configure ignore patterns
123
surge config example.surge.sh --ignore "*.log,node_modules/*,src/*"
124

125
# Set compression options
126
surge config example.surge.sh --compression gzip,brotli
127

128
# Configure cache headers
129
surge config example.surge.sh --cache-control "public, max-age=31536000"
130
```
131

132
## Platform Configuration
133

134
### User Preferences
135

136
**CLI Defaults:**
137
```bash
138
# Set default project directory
139
surge config --global --default-project ./build
140

141
# Set default domain pattern
142
surge config --global --domain-pattern "%s.surge.sh"
143

144
# Configure authentication preferences
145
surge config --global --auth-method token
146
```
147

148
**Display Settings:**
149
```bash
150
# Set output format
151
surge config --global --output-format table
152

153
# Configure color scheme
154
surge config --global --colors auto
155

156
# Set verbosity level
157
surge config --global --verbose 2
158
```
159

160
### Team Configuration
161

162
**Organization Settings:**
163
```bash
164
# Set organization name
165
surge config --org --name "Acme Corp"
166

167
# Configure team defaults
168
surge config --org --default-ssl enabled
169

170
# Set billing preferences
171
surge config --org --billing-email finance@acme.com
172
```
173

174
**Access Control:**
175
```bash
176
# Configure IP whitelist
177
surge config --org --ip-whitelist 192.168.1.0/24,10.0.0.0/8
178

179
# Set 2FA requirements
180
surge config --org --require-2fa true
181

182
# Configure session timeout
183
surge config --org --session-timeout 8h
184
```
185

186
## Configuration Files
187

188
### Local Configuration
189

190
**`.surge` Directory:**
191
```
192
project-root/
193
├── .surge/
194
│   ├── config.json       # Project configuration
195
│   ├── secrets.json      # Environment variables (gitignored)
196
│   ├── hooks/            # Custom deployment hooks
197
│   └── templates/        # Deployment templates
198
├── CNAME                 # Domain configuration
199
├── .surgeignore          # File ignore patterns
200
└── surge.json           # Alternative config file
201
```
202

203
**Project Config (`config.json`):**
204
```json
205
{
206
  "domain": "example.surge.sh",
207
  "buildCommand": "npm run build",
208
  "buildDir": "./dist",
209
  "ssl": {
210
    "enabled": true,
211
    "provider": "letsencrypt",
212
    "enforce": true
213
  },
214
  "redirects": {
215
    "/old-page": "/new-page",
216
    "/api/*": "https://api.example.com/$1"
217
  },
218
  "headers": {
219
    "/*": {
220
      "Cache-Control": "public, max-age=31536000",
221
      "X-Frame-Options": "DENY"
222
    }
223
  }
224
}
225
```
226

227
### Global Configuration
228

229
**User Config (`~/.surge/config.json`):**
230
```json
231
{
232
  "email": "user@example.com",
233
  "defaultProject": "./build",
234
  "domainPattern": "%s.surge.sh",
235
  "outputFormat": "table",
236
  "colors": true,
237
  "verbose": 1
238
}
239
```
240

241
**Credentials (`~/.netrc`):**
242
```
243
machine surge.surge.sh
244
  login user@example.com
245
  password api-token-here
246
```
247

248
## Environment Variables
249

250
### Surge Environment Variables
251

252
**Authentication:**
253
- `SURGE_TOKEN`: API token for authentication
254
- `SURGE_LOGIN`: Email address for login
255
- `SURGE_PASSWORD`: Password for login (not recommended)
256

257
**Configuration:**
258
- `SURGE_DOMAIN`: Default domain for deployments
259
- `SURGE_PROJECT`: Default project directory
260
- `SURGE_ENDPOINT`: Custom API endpoint
261
- `SURGE_PLATFORM`: Platform identifier
262

263
**Build Environment:**
264
- `NODE_ENV`: Node.js environment
265
- `BUILD_ENV`: Build environment identifier
266
- `API_URL`: API endpoint URL
267
- `CDN_URL`: CDN base URL
268

269
### Project Environment Variables
270

271
**Setting Variables:**
272
```bash
273
# Set environment variable
274
surge config example.surge.sh --env API_KEY=secret123
275

276
# Set multiple variables
277
surge config example.surge.sh --env API_KEY=secret123 --env DEBUG=true
278

279
# Load from file
280
surge config example.surge.sh --env-file .env.production
281
```
282

283
**Using Variables:**
284
```javascript
285
// In your application
286
const apiKey = process.env.API_KEY;
287
const apiUrl = process.env.API_URL || 'https://api.example.com';
288
```
289

290
## Advanced Configuration
291

292
### Custom Headers
293

294
**Security Headers:**
295
```bash
296
# Set security headers
297
surge config example.surge.sh --header "X-Frame-Options: DENY"
298
surge config example.surge.sh --header "X-Content-Type-Options: nosniff"
299
surge config example.surge.sh --header "X-XSS-Protection: 1; mode=block"
300
```
301

302
**Cache Control:**
303
```bash
304
# Set cache headers for different file types
305
surge config example.surge.sh --header "*.css: Cache-Control: public, max-age=31536000"
306
surge config example.surge.sh --header "*.js: Cache-Control: public, max-age=31536000"
307
surge config example.surge.sh --header "*.html: Cache-Control: no-cache"
308
```
309

310
### URL Redirects
311

312
**Redirect Configuration:**
313
```bash
314
# Simple redirect
315
surge config example.surge.sh --redirect "/old-url /new-url"
316

317
# Pattern redirects
318
surge config example.surge.sh --redirect "/blog/* /articles/$1"
319

320
# External redirects
321
surge config example.surge.sh --redirect "/external https://external-site.com"
322
```
323

324
**SPA Configuration:**
325
```bash
326
# Configure single-page application
327
surge config example.surge.sh --spa true
328

329
# Custom 404 page
330
surge config example.surge.sh --404 custom-404.html
331

332
# Fallback for client-side routing
333
surge config example.surge.sh --fallback 200.html
334
```
335

336
### Custom Error Pages
337

338
**Error Page Configuration:**
339
```bash
340
# Set custom 404 page
341
surge config example.surge.sh --error-page 404 ./404.html
342

343
# Set custom 500 page
344
surge config example.surge.sh --error-page 500 ./500.html
345

346
# Set maintenance page
347
surge config example.surge.sh --maintenance-page ./maintenance.html
348
```
349

350
## Configuration Management
351

352
### Configuration Backup
353

354
**Export Configuration:**
355
```bash
356
# Export project configuration
357
surge config example.surge.sh --export > config-backup.json
358

359
# Export global configuration
360
surge config --global --export > global-config.json
361

362
# Export all configurations
363
surge config --export-all > all-configs.json
364
```
365

366
**Import Configuration:**
367
```bash
368
# Import project configuration
369
surge config example.surge.sh --import config-backup.json
370

371
# Import global configuration
372
surge config --global --import global-config.json
373
```
374

375
### Configuration Versioning
376

377
**Version Control:**
378
```bash
379
# Track configuration changes
380
surge config example.surge.sh --version-control enable
381

382
# View configuration history
383
surge config example.surge.sh --history
384

385
# Revert to previous configuration
386
surge config example.surge.sh --revert v1.2.3
387
```
388

389
### Configuration Templates
390

391
**Create Templates:**
392
```bash
393
# Create configuration template
394
surge config --template spa-template --spa true --ssl enabled
395

396
# Apply template to project
397
surge config example.surge.sh --apply-template spa-template
398

399
# List available templates
400
surge config --list-templates
401
```
402

403
## Troubleshooting
404

405
### Configuration Issues
406

407
**Invalid Configuration:**
408
```bash
409
# Validate configuration
410
surge config example.surge.sh --validate
411

412
# Fix configuration errors
413
surge config example.surge.sh --fix-errors
414

415
# Reset to defaults
416
surge config example.surge.sh --reset
417
```
418

419
**Missing Configuration:**
420
```bash
421
# Check required settings
422
surge config example.surge.sh --check-required
423

424
# Set missing defaults
425
surge config example.surge.sh --set-defaults
426

427
# Interactive configuration setup
428
surge config example.surge.sh --setup
429
```
430

431
### Environment Problems
432

433
**Variable Not Available:**
434
- Check environment variable spelling
435
- Verify variable is set in configuration
436
- Confirm build process has access
437
- Check for environment-specific overrides
438

439
**Configuration Conflicts:**
440
```bash
441
# Check configuration hierarchy
442
surge config example.surge.sh --show-hierarchy
443

444
# Resolve conflicts
445
surge config example.surge.sh --resolve-conflicts
446

447
# Debug configuration loading
448
surge config example.surge.sh --debug
449
```
450

451
### Deployment Configuration Issues
452

453
**Build Failures:**
454
- Verify build command is correct
455
- Check build directory exists
456
- Confirm environment variables are set
457
- Review build timeout settings
458

459
**SSL Configuration Problems:**
460
- Verify domain ownership
461
- Check certificate validity
462
- Confirm DNS configuration
463
- Test SSL provider connectivity