Publishing & Deployment

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

Capabilities

Publish

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

/**
 * Publish static files to Surge CDN
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function publish(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Interactive mode (prompts for path and domain)
surge

# Specify path and domain
surge ./build example.surge.sh

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

# Preview mode (staging)
surge --stage
surge --preview

CLI Options:

• -p, --project: Project directory path
• -d, --domain: Target domain name
• -s, --stage, --preview: Deploy to preview/staging environment

Library Usage:

const surge = require('surge')();

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

// With hooks
surge.publish({
  preAuth: (req, next) => {
    console.log(`Publishing to ${req.domain}`);
    next();
  },
  postPublish: (req, next) => {
    console.log('Deploy successful!');
    next();
  }
})(process.argv.slice(2));

Publishing Process:

1. Authentication verification
2. Project path detection/validation
3. Domain resolution (CNAME file, generator, or prompt)
4. File size calculation and validation
5. File upload with progress indication
6. DNS configuration
7. Success confirmation with URLs

Teardown

Remove a published project from the Surge platform.

/**
 * Remove published project from platform
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function teardown(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Interactive domain selection
surge teardown

# Specify domain
surge teardown example.surge.sh

Library Usage:

surge.teardown({})(process.argv.slice(2));

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

List Projects

Display all published projects or revisions for a specific project.

/**
 * List all projects or project revisions
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function list(hooks?: HookConfig): CommandFunction;

CLI Usage:

# List all projects
surge list

# List revisions for specific project
surge list example.surge.sh

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

Library Usage:

surge.list({})(process.argv.slice(2));

List Files

Display all files in a specific published project.

/**
 * List all files in a published project
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function files(hooks?: HookConfig): CommandFunction;

CLI Usage:

# List files in project
surge files example.surge.sh

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

Library Usage:

surge.files({})(process.argv.slice(2));

Domain Management

Automatic Domain Discovery

Surge automatically discovers domains through several methods:

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

Domain Validation

• Validates domain format and availability
• Checks DNS configuration
• Handles custom domains and surge.sh subdomains
• Supports both apex domains and subdomains

File Processing

Supported File Types

Surge supports all static file types including:

• HTML, CSS, JavaScript
• Images (PNG, JPG, GIF, SVG, WebP)
• Fonts (WOFF, WOFF2, TTF, OTF)
• Documents (PDF, TXT, JSON, XML)
• Archives and other static assets

Special Files

• CNAME: Domain configuration (not uploaded)
• 200.html: SPA fallback for client-side routing
• 404.html: Custom 404 error page
• .surgeignore: File ignore patterns (similar to .gitignore)

File Size Limits

• Maximum project size varies by plan
• Individual file size limits apply
• Progress indication during upload
• Compression optimization for text files

Deployment Features

Custom SSL Support

• Automatic HTTPS for all domains
• Custom SSL certificate upload
• Let's Encrypt integration
• SSL enforcement options

CDN Distribution

• Global CDN with edge locations worldwide
• Automatic caching optimization
• Cache invalidation support
• GZip compression

HTML5 History API Support

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

<!-- 200.html -->
<!DOCTYPE html>
<html>
<head>
  <title>My SPA</title>
</head>
<body>
  <div id="app"></div>
  <script src="/app.js"></script>
</body>
</html>

Environment Integration

CI/CD Integration

# Travis CI example
script:
  - npm run build
  - surge --project ./build --domain $SURGE_DOMAIN

Build Tool Integration

// Gulp example
gulp.task('deploy', function() {
  return surge({
    project: './build',
    domain: 'example.surge.sh'
  });
});

Error Handling

Common Publishing Errors

• Authentication Required: User not logged in
• Domain Unavailable: Domain already taken or reserved
• File Size Exceeded: Project too large for current plan
• Network Errors: Upload interrupted or connection issues
• Validation Errors: Invalid project structure or files

All publishing commands provide detailed error messages and suggested resolutions.