0
# Publishing & Deployment
1

2
Primary publishing functionality for deploying static sites to the Surge CDN. Handles project detection, domain management, file upload, and deployment lifecycle.
3

4
## Capabilities
5

6
### Publish
7

8
Main deployment command that publishes a local directory to the Surge CDN.
9

10
```javascript { .api }
11
/**
12
 * Publish static files to Surge CDN
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function publish(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# Interactive mode (prompts for path and domain)
22
surge
23

24
# Specify path and domain
25
surge ./build example.surge.sh
26

27
# With options
28
surge --project ./dist --domain mysite.surge.sh
29

30
# Preview mode (staging)
31
surge --stage
32
surge --preview
33
```
34

35
**CLI Options:**
36
- `-p, --project`: Project directory path
37
- `-d, --domain`: Target domain name
38
- `-s, --stage, --preview`: Deploy to preview/staging environment
39

40
**Library Usage:**
41
```javascript
42
const surge = require('surge')();
43

44
// Basic publish
45
surge.publish({})(process.argv.slice(2));
46

47
// With hooks
48
surge.publish({
49
  preAuth: (req, next) => {
50
    console.log(`Publishing to ${req.domain}`);
51
    next();
52
  },
53
  postPublish: (req, next) => {
54
    console.log('Deploy successful!');
55
    next();
56
  }
57
})(process.argv.slice(2));
58
```
59

60
**Publishing Process:**
61
1. Authentication verification
62
2. Project path detection/validation
63
3. Domain resolution (CNAME file, generator, or prompt)
64
4. File size calculation and validation
65
5. File upload with progress indication
66
6. DNS configuration
67
7. Success confirmation with URLs
68

69
### Teardown
70

71
Remove a published project from the Surge platform.
72

73
```javascript { .api }
74
/**
75
 * Remove published project from platform
76
 * @param hooks - Optional lifecycle hooks
77
 * @returns Command function
78
 */
79
function teardown(hooks?: HookConfig): CommandFunction;
80
```
81

82
**CLI Usage:**
83
```bash
84
# Interactive domain selection
85
surge teardown
86

87
# Specify domain
88
surge teardown example.surge.sh
89
```
90

91
**Library Usage:**
92
```javascript
93
surge.teardown({})(process.argv.slice(2));
94
```
95

96
Permanently removes the project and all its files from the Surge CDN. The domain becomes available for reuse.
97

98
### List Projects
99

100
Display all published projects or revisions for a specific project.
101

102
```javascript { .api }
103
/**
104
 * List all projects or project revisions
105
 * @param hooks - Optional lifecycle hooks
106
 * @returns Command function
107
 */
108
function list(hooks?: HookConfig): CommandFunction;
109
```
110

111
**CLI Usage:**
112
```bash
113
# List all projects
114
surge list
115

116
# List revisions for specific project
117
surge list example.surge.sh
118
```
119

120
Displays projects in a formatted table with domain names, file counts, and deployment dates.
121

122
**Library Usage:**
123
```javascript
124
surge.list({})(process.argv.slice(2));
125
```
126

127
### List Files
128

129
Display all files in a specific published project.
130

131
```javascript { .api }
132
/**
133
 * List all files in a published project
134
 * @param hooks - Optional lifecycle hooks
135
 * @returns Command function
136
 */
137
function files(hooks?: HookConfig): CommandFunction;
138
```
139

140
**CLI Usage:**
141
```bash
142
# List files in project
143
surge files example.surge.sh
144
```
145

146
Shows all files in the project with paths, sizes, and modification times.
147

148
**Library Usage:**
149
```javascript
150
surge.files({})(process.argv.slice(2));
151
```
152

153
## Domain Management
154

155
### Automatic Domain Discovery
156

157
Surge automatically discovers domains through several methods:
158

159
1. **CNAME File**: Reads domain from `CNAME` file in project root
160
2. **Command Arguments**: Domain specified via CLI arguments
161
3. **Random Generation**: Generates random subdomain if none specified
162
4. **Interactive Prompt**: Prompts user if domain cannot be determined
163

164
### Domain Validation
165

166
- Validates domain format and availability
167
- Checks DNS configuration
168
- Handles custom domains and surge.sh subdomains
169
- Supports both apex domains and subdomains
170

171
## File Processing
172

173
### Supported File Types
174

175
Surge supports all static file types including:
176
- HTML, CSS, JavaScript
177
- Images (PNG, JPG, GIF, SVG, WebP)
178
- Fonts (WOFF, WOFF2, TTF, OTF)
179
- Documents (PDF, TXT, JSON, XML)
180
- Archives and other static assets
181

182
### Special Files
183

184
- **`CNAME`**: Domain configuration (not uploaded)
185
- **`200.html`**: SPA fallback for client-side routing
186
- **`404.html`**: Custom 404 error page
187
- **`.surgeignore`**: File ignore patterns (similar to .gitignore)
188

189
### File Size Limits
190

191
- Maximum project size varies by plan
192
- Individual file size limits apply
193
- Progress indication during upload
194
- Compression optimization for text files
195

196
## Deployment Features
197

198
### Custom SSL Support
199

200
- Automatic HTTPS for all domains
201
- Custom SSL certificate upload
202
- Let's Encrypt integration
203
- SSL enforcement options
204

205
### CDN Distribution
206

207
- Global CDN with edge locations worldwide
208
- Automatic caching optimization
209
- Cache invalidation support
210
- GZip compression
211

212
### HTML5 History API Support
213

214
Use `200.html` file for single-page applications with client-side routing:
215

216
```html
217
<!-- 200.html -->
218
<!DOCTYPE html>
219
<html>
220
<head>
221
  <title>My SPA</title>
222
</head>
223
<body>
224
  <div id="app"></div>
225
  <script src="/app.js"></script>
226
</body>
227
</html>
228
```
229

230
## Environment Integration
231

232
### CI/CD Integration
233

234
```bash
235
# Travis CI example
236
script:
237
  - npm run build
238
  - surge --project ./build --domain $SURGE_DOMAIN
239
```
240

241
### Build Tool Integration
242

243
```javascript
244
// Gulp example
245
gulp.task('deploy', function() {
246
  return surge({
247
    project: './build',
248
    domain: 'example.surge.sh'
249
  });
250
});
251
```
252

253
## Error Handling
254

255
### Common Publishing Errors
256

257
- **Authentication Required**: User not logged in
258
- **Domain Unavailable**: Domain already taken or reserved
259
- **File Size Exceeded**: Project too large for current plan
260
- **Network Errors**: Upload interrupted or connection issues
261
- **Validation Errors**: Invalid project structure or files
262

263
All publishing commands provide detailed error messages and suggested resolutions.