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
Overview
Eval results
Files

configuration.mddocs/

Configuration

Project and platform configuration management for customizing Surge deployments, managing project settings, and configuring platform behavior.

Capabilities

Configuration Management

View and modify project and platform configuration settings.

/**
 * View and change project configuration settings
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function config(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View project configuration
surge config example.surge.sh

# Interactive configuration menu
surge config

# Set specific configuration value
surge config example.surge.sh --set ssl.enabled true

# View global platform settings
surge config --global

Configuration Options:

  • Project-specific settings
  • Global platform defaults
  • User preferences
  • Team-wide configurations
  • Environment-specific settings

Library Usage:

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

Project Configuration

Basic Project Settings

Project Metadata:

# Set project name
surge config example.surge.sh --name "My Website"

# Set project description
surge config example.surge.sh --description "Company marketing site"

# Set project tags
surge config example.surge.sh --tags "production,marketing,website"

Deployment Settings:

# Set default deployment directory
surge config example.surge.sh --build-dir ./dist

# Set deployment branch
surge config example.surge.sh --branch main

# Enable/disable automatic deployments
surge config example.surge.sh --auto-deploy true

Advanced Project Configuration

Custom Domains:

# Set custom domain
surge config example.surge.sh --domain example.com

# Configure domain aliases
surge config example.surge.sh --aliases www.example.com,app.example.com

# Set apex domain redirect
surge config example.surge.sh --apex-redirect www.example.com

SSL Configuration:

# Enable SSL
surge config example.surge.sh --ssl enabled

# Set SSL provider
surge config example.surge.sh --ssl-provider letsencrypt

# Configure SSL enforcement
surge config example.surge.sh --ssl-enforce true

# Set custom SSL certificate
surge config example.surge.sh --ssl-cert ./cert.pem --ssl-key ./key.pem

Build Configuration

Build Settings:

# Set build command
surge config example.surge.sh --build-command "npm run build"

# Set build directory
surge config example.surge.sh --build-output "./dist"

# Configure environment variables
surge config example.surge.sh --env NODE_ENV=production --env API_URL=https://api.example.com

# Set build timeout
surge config example.surge.sh --build-timeout 300

File Processing:

# Configure ignore patterns
surge config example.surge.sh --ignore "*.log,node_modules/*,src/*"

# Set compression options
surge config example.surge.sh --compression gzip,brotli

# Configure cache headers
surge config example.surge.sh --cache-control "public, max-age=31536000"

Platform Configuration

User Preferences

CLI Defaults:

# Set default project directory
surge config --global --default-project ./build

# Set default domain pattern
surge config --global --domain-pattern "%s.surge.sh"

# Configure authentication preferences
surge config --global --auth-method token

Display Settings:

# Set output format
surge config --global --output-format table

# Configure color scheme
surge config --global --colors auto

# Set verbosity level
surge config --global --verbose 2

Team Configuration

Organization Settings:

# Set organization name
surge config --org --name "Acme Corp"

# Configure team defaults
surge config --org --default-ssl enabled

# Set billing preferences
surge config --org --billing-email finance@acme.com

Access Control:

# Configure IP whitelist
surge config --org --ip-whitelist 192.168.1.0/24,10.0.0.0/8

# Set 2FA requirements
surge config --org --require-2fa true

# Configure session timeout
surge config --org --session-timeout 8h

Configuration Files

Local Configuration

.surge Directory:

project-root/
├── .surge/
│   ├── config.json       # Project configuration
│   ├── secrets.json      # Environment variables (gitignored)
│   ├── hooks/            # Custom deployment hooks
│   └── templates/        # Deployment templates
├── CNAME                 # Domain configuration
├── .surgeignore          # File ignore patterns
└── surge.json           # Alternative config file

Project Config (config.json):

{
  "domain": "example.surge.sh",
  "buildCommand": "npm run build",
  "buildDir": "./dist",
  "ssl": {
    "enabled": true,
    "provider": "letsencrypt",
    "enforce": true
  },
  "redirects": {
    "/old-page": "/new-page",
    "/api/*": "https://api.example.com/$1"
  },
  "headers": {
    "/*": {
      "Cache-Control": "public, max-age=31536000",
      "X-Frame-Options": "DENY"
    }
  }
}

Global Configuration

User Config (~/.surge/config.json):

{
  "email": "user@example.com",
  "defaultProject": "./build",
  "domainPattern": "%s.surge.sh",
  "outputFormat": "table",
  "colors": true,
  "verbose": 1
}

Credentials (~/.netrc):

machine surge.surge.sh
  login user@example.com
  password api-token-here

Environment Variables

Surge Environment Variables

Authentication:

  • SURGE_TOKEN: API token for authentication
  • SURGE_LOGIN: Email address for login
  • SURGE_PASSWORD: Password for login (not recommended)

Configuration:

  • SURGE_DOMAIN: Default domain for deployments
  • SURGE_PROJECT: Default project directory
  • SURGE_ENDPOINT: Custom API endpoint
  • SURGE_PLATFORM: Platform identifier

Build Environment:

  • NODE_ENV: Node.js environment
  • BUILD_ENV: Build environment identifier
  • API_URL: API endpoint URL
  • CDN_URL: CDN base URL

Project Environment Variables

Setting Variables:

# Set environment variable
surge config example.surge.sh --env API_KEY=secret123

# Set multiple variables
surge config example.surge.sh --env API_KEY=secret123 --env DEBUG=true

# Load from file
surge config example.surge.sh --env-file .env.production

Using Variables:

// In your application
const apiKey = process.env.API_KEY;
const apiUrl = process.env.API_URL || 'https://api.example.com';

Advanced Configuration

Custom Headers

Security Headers:

# Set security headers
surge config example.surge.sh --header "X-Frame-Options: DENY"
surge config example.surge.sh --header "X-Content-Type-Options: nosniff"
surge config example.surge.sh --header "X-XSS-Protection: 1; mode=block"

Cache Control:

# Set cache headers for different file types
surge config example.surge.sh --header "*.css: Cache-Control: public, max-age=31536000"
surge config example.surge.sh --header "*.js: Cache-Control: public, max-age=31536000"
surge config example.surge.sh --header "*.html: Cache-Control: no-cache"

URL Redirects

Redirect Configuration:

# Simple redirect
surge config example.surge.sh --redirect "/old-url /new-url"

# Pattern redirects
surge config example.surge.sh --redirect "/blog/* /articles/$1"

# External redirects
surge config example.surge.sh --redirect "/external https://external-site.com"

SPA Configuration:

# Configure single-page application
surge config example.surge.sh --spa true

# Custom 404 page
surge config example.surge.sh --404 custom-404.html

# Fallback for client-side routing
surge config example.surge.sh --fallback 200.html

Custom Error Pages

Error Page Configuration:

# Set custom 404 page
surge config example.surge.sh --error-page 404 ./404.html

# Set custom 500 page
surge config example.surge.sh --error-page 500 ./500.html

# Set maintenance page
surge config example.surge.sh --maintenance-page ./maintenance.html

Configuration Management

Configuration Backup

Export Configuration:

# Export project configuration
surge config example.surge.sh --export > config-backup.json

# Export global configuration
surge config --global --export > global-config.json

# Export all configurations
surge config --export-all > all-configs.json

Import Configuration:

# Import project configuration
surge config example.surge.sh --import config-backup.json

# Import global configuration
surge config --global --import global-config.json

Configuration Versioning

Version Control:

# Track configuration changes
surge config example.surge.sh --version-control enable

# View configuration history
surge config example.surge.sh --history

# Revert to previous configuration
surge config example.surge.sh --revert v1.2.3

Configuration Templates

Create Templates:

# Create configuration template
surge config --template spa-template --spa true --ssl enabled

# Apply template to project
surge config example.surge.sh --apply-template spa-template

# List available templates
surge config --list-templates

Troubleshooting

Configuration Issues

Invalid Configuration:

# Validate configuration
surge config example.surge.sh --validate

# Fix configuration errors
surge config example.surge.sh --fix-errors

# Reset to defaults
surge config example.surge.sh --reset

Missing Configuration:

# Check required settings
surge config example.surge.sh --check-required

# Set missing defaults
surge config example.surge.sh --set-defaults

# Interactive configuration setup
surge config example.surge.sh --setup

Environment Problems

Variable Not Available:

  • Check environment variable spelling
  • Verify variable is set in configuration
  • Confirm build process has access
  • Check for environment-specific overrides

Configuration Conflicts:

# Check configuration hierarchy
surge config example.surge.sh --show-hierarchy

# Resolve conflicts
surge config example.surge.sh --resolve-conflicts

# Debug configuration loading
surge config example.surge.sh --debug

Deployment Configuration Issues

Build Failures:

  • Verify build command is correct
  • Check build directory exists
  • Confirm environment variables are set
  • Review build timeout settings

SSL Configuration Problems:

  • Verify domain ownership
  • Check certificate validity
  • Confirm DNS configuration
  • Test SSL provider connectivity

Install with Tessl CLI

npx tessl i tessl/npm-surge

docs

account.md

analytics.md

authentication.md

collaboration.md

configuration.md

dns.md

index.md

publishing.md

revisions.md

ssl.md

tile.json