CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-surge

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/surge@0.24.x
Publish Source
CLI
Badge
tessl/npm-surge badge