0
# Surge
1

2
Surge is a command-line interface (CLI) tool for static web publishing that enables developers to deploy web applications to a CDN with a single command and no setup required. It provides a simple workflow for publishing static sites, single-page applications, and compiled web assets to the surge.sh hosted service.
3

4
## Package Information
5

6
- **Package Name**: surge
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g surge` (global) or `npm install surge` (local)
10

11
## Core Imports
12

13
Library usage:
14

15
```javascript
16
const surge = require('surge');
17
```
18

19
With configuration:
20

21
```javascript
22
const surge = require('surge')({
23
  endpoint: 'https://surge.surge.sh',
24
  platform: 'surge.sh',
25
  name: 'surge',
26
  default: 'publish'
27
});
28
```
29

30
## Basic Usage
31

32
### CLI Usage
33

34
```bash
35
# Install globally
36
npm install -g surge
37

38
# Basic publishing (interactive)
39
surge
40

41
# Publish specific directory to domain
42
surge ./build example.surge.sh
43

44
# Login first
45
surge login
46

47
# List projects
48
surge list
49

50
# Teardown a project
51
surge teardown example.surge.sh
52
```
53

54
### Library Usage
55

56
```javascript
57
const surge = require('surge')();
58

59
// Programmatic publishing
60
surge.publish({})(process.argv.slice(2));
61

62
// With hooks
63
surge.publish({
64
  preAuth: (req, next) => {
65
    console.log('Before authentication');
66
    next();
67
  },
68
  postPublish: (req, next) => {
69
    console.log('Deploy complete!');
70
    next();
71
  }
72
})(process.argv.slice(2));
73
```
74

75
## Architecture
76

77
Surge is built around several key components:
78

79
- **Factory Pattern**: Main module exports a factory function that returns a configured surge object
80
- **Middleware Architecture**: Uses an "onion skin" middleware pattern for request processing
81
- **Command System**: Each command (login, publish, etc.) is a separate method with its own middleware stack
82
- **Hook System**: Extensible lifecycle hooks for customizing command behavior
83
- **CLI Integration**: Seamless command-line interface with argument parsing and interactive prompts
84

85
## Capabilities
86

87
### Authentication & User Management
88

89
Core authentication functionality for managing user credentials and account access. Essential for all publishing operations.
90

91
```javascript { .api }
92
// Authentication commands
93
function login(hooks?: HookConfig): CommandFunction;
94
function logout(hooks?: HookConfig): CommandFunction;
95
function whoami(hooks?: HookConfig): CommandFunction;
96
function token(hooks?: HookConfig): CommandFunction;
97
```
98

99
[Authentication](./authentication.md)
100

101
### Publishing & Deployment
102

103
Primary publishing functionality for deploying static sites to the Surge CDN. Includes project detection, domain management, and file upload.
104

105
```javascript { .api }
106
// Main publishing command
107
function publish(hooks?: HookConfig): CommandFunction;
108

109
// Project teardown
110
function teardown(hooks?: HookConfig): CommandFunction;
111

112
// Project listing
113
function list(hooks?: HookConfig): CommandFunction;
114
function files(hooks?: HookConfig): CommandFunction;
115
```
116

117
[Publishing](./publishing.md)
118

119
### Revision Management
120

121
Version control functionality for managing different revisions of deployed projects, enabling rollbacks and staged deployments.
122

123
```javascript { .api }
124
// Revision commands
125
function rollback(hooks?: HookConfig): CommandFunction;
126
function rollfore(hooks?: HookConfig): CommandFunction;
127
function cutover(hooks?: HookConfig): CommandFunction;
128
function discard(hooks?: HookConfig): CommandFunction;
129
function select(hooks?: HookConfig): CommandFunction;
130
```
131

132
[Revisions](./revisions.md)
133

134
### SSL & Security
135

136
SSL certificate management including Let's Encrypt integration and custom certificate upload for secure HTTPS deployments.
137

138
```javascript { .api }
139
// SSL commands
140
function ssl(hooks?: HookConfig): CommandFunction;
141
function encrypt(hooks?: HookConfig): CommandFunction;  
142
function certs(hooks?: HookConfig): CommandFunction;
143
```
144

145
[SSL & Security](./ssl.md)
146

147
### DNS Management
148

149
Comprehensive DNS management for custom domains, including zone management and record manipulation.
150

151
```javascript { .api }
152
// DNS commands
153
function dns(hooks?: HookConfig): CommandFunction;
154
function zone(hooks?: HookConfig): CommandFunction;
155
```
156

157
[DNS Management](./dns.md)
158

159
### Analytics & Monitoring
160

161
Analytics and monitoring capabilities for tracking traffic, performance, and usage metrics of deployed projects.
162

163
```javascript { .api }
164
// Analytics commands
165
function analytics(hooks?: HookConfig): CommandFunction;
166
function traffic(hooks?: HookConfig): CommandFunction;
167
function load(hooks?: HookConfig): CommandFunction;  
168
function audience(hooks?: HookConfig): CommandFunction;
169
function usage(hooks?: HookConfig): CommandFunction;
170
function audit(hooks?: HookConfig): CommandFunction;
171
function bust(hooks?: HookConfig): CommandFunction;
172
```
173

174
[Analytics](./analytics.md)
175

176
### Account Management
177

178
Account and billing management including plan upgrades, payment methods, and account deletion.
179

180
```javascript { .api }
181
// Account commands  
182
function plan(hooks?: HookConfig): CommandFunction;
183
function card(hooks?: HookConfig): CommandFunction;
184
function plus(hooks?: HookConfig): CommandFunction;
185
function nuke(hooks?: HookConfig): CommandFunction;
186
```
187

188
[Account Management](./account.md)
189

190
### Collaboration
191

192
User collaboration features for managing project access and team permissions.
193

194
```javascript { .api }
195
// Collaboration commands
196
function invite(hooks?: HookConfig): CommandFunction;
197
function revoke(hooks?: HookConfig): CommandFunction;
198
```
199

200
[Collaboration](./collaboration.md)
201

202
### Configuration
203

204
Project and platform configuration management.
205

206
```javascript { .api }
207
// Configuration command
208
function config(hooks?: HookConfig): CommandFunction;
209
```
210

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

213
## Types
214

215
```javascript { .api }
216
// Factory configuration options
217
interface SurgeConfiguration {
218
  endpoint?: string;     // API endpoint (default: 'https://surge.surge.sh')
219
  platform?: string;    // Platform domain (default: 'surge.sh')  
220
  name?: string;         // CLI name (default: 'surge')
221
  default?: string;      // Default command (default: 'publish')
222
}
223

224
// Hook configuration for lifecycle customization
225
interface HookConfig {
226
  preAuth?: MiddlewareFunction;
227
  postAuth?: MiddlewareFunction;
228
  preProject?: MiddlewareFunction;
229
  postProject?: MiddlewareFunction;
230
  preSize?: MiddlewareFunction;
231
  postSize?: MiddlewareFunction;
232
  preDomain?: MiddlewareFunction;
233
  postDomain?: MiddlewareFunction;
234
  prePublish?: MiddlewareFunction;
235
  postPublish?: MiddlewareFunction;
236
}
237

238
// Middleware function signature
239
type MiddlewareFunction = (req: RequestObject, next: NextFunction, abort?: AbortFunction) => void;
240
type NextFunction = (error?: Error) => void;
241
type AbortFunction = (message?: string) => void;
242

243
// Command function signature
244
type CommandFunction = (argv: ParsedArguments) => void;
245

246
// Request object passed through middleware
247
interface RequestObject {
248
  argv: ParsedArguments;
249
  configuration: SurgeConfiguration;
250
  endpoint: EndpointInfo;
251
  creds: Credentials;
252
  account: AccountInfo;
253
  domain?: string;
254
  project?: string;
255
  fileCount?: number;
256
  projectSize?: number;
257
}
258

259
// Parsed command line arguments
260
interface ParsedArguments {
261
  _: string[];           // Positional arguments
262
  project?: string;      // -p, --project
263
  domain?: string;       // -d, --domain
264
  endpoint?: string;     // -e, --endpoint
265
  add?: string;          // -a, --add
266
  remove?: string;       // -r, --remove
267
  stage?: boolean;       // -s, --stage, --preview
268
  message?: string;      // -m, --message
269
  [key: string]: any;
270
}
271
```