or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account.mdanalytics.mdauthentication.mdcollaboration.mdconfiguration.mddns.mdindex.mdpublishing.mdrevisions.mdssl.md
tile.json

tessl/npm-surge

Static web publishing CLI tool for deploying web applications to a CDN with a single command

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/surge@0.24.x

To install, run

npx @tessl/cli install tessl/npm-surge@0.24.0

index.mddocs/

Surge

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.

Package Information

  • Package Name: surge
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install -g surge (global) or npm install surge (local)

Core Imports

Library usage:

const surge = require('surge');

With configuration:

const surge = require('surge')({
  endpoint: 'https://surge.surge.sh',
  platform: 'surge.sh',
  name: 'surge',
  default: 'publish'
});

Basic Usage

CLI Usage

# Install globally
npm install -g surge

# Basic publishing (interactive)
surge

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

# Login first
surge login

# List projects
surge list

# Teardown a project
surge teardown example.surge.sh

Library Usage

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

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

// With hooks
surge.publish({
  preAuth: (req, next) => {
    console.log('Before authentication');
    next();
  },
  postPublish: (req, next) => {
    console.log('Deploy complete!');
    next();
  }
})(process.argv.slice(2));

Architecture

Surge is built around several key components:

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

Capabilities

Authentication & User Management

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

// Authentication commands
function login(hooks?: HookConfig): CommandFunction;
function logout(hooks?: HookConfig): CommandFunction;
function whoami(hooks?: HookConfig): CommandFunction;
function token(hooks?: HookConfig): CommandFunction;

Authentication

Publishing & Deployment

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

// Main publishing command
function publish(hooks?: HookConfig): CommandFunction;

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

// Project listing
function list(hooks?: HookConfig): CommandFunction;
function files(hooks?: HookConfig): CommandFunction;

Publishing

Revision Management

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

// Revision commands
function rollback(hooks?: HookConfig): CommandFunction;
function rollfore(hooks?: HookConfig): CommandFunction;
function cutover(hooks?: HookConfig): CommandFunction;
function discard(hooks?: HookConfig): CommandFunction;
function select(hooks?: HookConfig): CommandFunction;

Revisions

SSL & Security

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

// SSL commands
function ssl(hooks?: HookConfig): CommandFunction;
function encrypt(hooks?: HookConfig): CommandFunction;  
function certs(hooks?: HookConfig): CommandFunction;

SSL & Security

DNS Management

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

// DNS commands
function dns(hooks?: HookConfig): CommandFunction;
function zone(hooks?: HookConfig): CommandFunction;

DNS Management

Analytics & Monitoring

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

// Analytics commands
function analytics(hooks?: HookConfig): CommandFunction;
function traffic(hooks?: HookConfig): CommandFunction;
function load(hooks?: HookConfig): CommandFunction;  
function audience(hooks?: HookConfig): CommandFunction;
function usage(hooks?: HookConfig): CommandFunction;
function audit(hooks?: HookConfig): CommandFunction;
function bust(hooks?: HookConfig): CommandFunction;

Analytics

Account Management

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

// Account commands  
function plan(hooks?: HookConfig): CommandFunction;
function card(hooks?: HookConfig): CommandFunction;
function plus(hooks?: HookConfig): CommandFunction;
function nuke(hooks?: HookConfig): CommandFunction;

Account Management

Collaboration

User collaboration features for managing project access and team permissions.

// Collaboration commands
function invite(hooks?: HookConfig): CommandFunction;
function revoke(hooks?: HookConfig): CommandFunction;

Collaboration

Configuration

Project and platform configuration management.

// Configuration command
function config(hooks?: HookConfig): CommandFunction;

Configuration

Types

// Factory configuration options
interface SurgeConfiguration {
  endpoint?: string;     // API endpoint (default: 'https://surge.surge.sh')
  platform?: string;    // Platform domain (default: 'surge.sh')  
  name?: string;         // CLI name (default: 'surge')
  default?: string;      // Default command (default: 'publish')
}

// Hook configuration for lifecycle customization
interface HookConfig {
  preAuth?: MiddlewareFunction;
  postAuth?: MiddlewareFunction;
  preProject?: MiddlewareFunction;
  postProject?: MiddlewareFunction;
  preSize?: MiddlewareFunction;
  postSize?: MiddlewareFunction;
  preDomain?: MiddlewareFunction;
  postDomain?: MiddlewareFunction;
  prePublish?: MiddlewareFunction;
  postPublish?: MiddlewareFunction;
}

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

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

// Request object passed through middleware
interface RequestObject {
  argv: ParsedArguments;
  configuration: SurgeConfiguration;
  endpoint: EndpointInfo;
  creds: Credentials;
  account: AccountInfo;
  domain?: string;
  project?: string;
  fileCount?: number;
  projectSize?: number;
}

// Parsed command line arguments
interface ParsedArguments {
  _: string[];           // Positional arguments
  project?: string;      // -p, --project
  domain?: string;       // -d, --domain
  endpoint?: string;     // -e, --endpoint
  add?: string;          // -a, --add
  remove?: string;       // -r, --remove
  stage?: boolean;       // -s, --stage, --preview
  message?: string;      // -m, --message
  [key: string]: any;
}