Surge Usage Documentation | A Powerful CLI Tool for Effortless Frontend Deployments

Archit Jain — Fri, 16 May 2025 11:45:59 +0000

Hello, I'm Archit, and today I'm presenting a comprehensive guide on Surge—a tool I rely on extensively for its effortless, zero-configuration deployments. This article isn’t written arbitrarily; it encapsulates my practical experiences and insights, making it an invaluable resource for new users. I aim to help you quickly master everything from installing the Surge CLI and hosting basic sites to automating deployments with GitHub Actions and configuring custom domains. Enjoy the read and happy deploying!

What is Surge?

Surge is a command-line tool designed for frictionless, zero-configuration publishing of static websites and single-page applications. In just a few seconds, you can deploy your project to Surge's global CDN, take advantage of free SSL/TLS provisioning for surge.sh subdomains, custom domain support, caching controls, and advanced features such as CORS configuration, redirects, and access management (with Surge Plus).

This guide covers:

Prerequisites
Installing Surge CLI
Basic Hosting with Surge
Hosting a React Web App with Surge
GitHub Actions Workflow for Auto-Deploy React App
Surge with Custom Domain
Advanced Features
Why Surge?
Troubleshooting
Best Practices
Credits

01. Prerequisites

Node.js (v14+) and npm installed.
A Surge account; sign up at https://surge.sh via cli.
(Optional) Cloudflare account for free SSL on custom domains.
I'm using npm throughout this guide, but you can opt for your preferred package manager if needed.
I'm considering ./dist as the output path for Vite. Feel free to adjust it as needed.

02. Installing Surge CLI

First, install Surge globally using npm or Yarn:

npm install --global surge

After installation, verify by running:

surge --version

03. Basic Hosting with Surge

i. Build or prepare your static site

Ensure your static files (HTML, CSS, JS) are in a local folder, e.g., public/ or dist/.

ii. Login to Surge

   surge login
   # Enter your email and password when prompted

iii. Publish your site

   surge ./dist your-subdomain.surge.sh

./dist is the local folder containing static assets
your-subdomain.surge.sh is your chosen subdomain

iv. Update or remove deployments

To update, run the same surge command with updated folder contents.

To remove, use the CLI command:

 surge teardown your-subdomain.surge.sh

GitHub Actions Deployment for Static Sites

Automate your HTML/CSS/JS site deployment with this workflow. Adjust project if your assets live elsewhere.

name: Deploy Static Site to Surge

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Surge CLI
        run: npm install --global surge

      - name: Deploy to Surge
        env:
          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
        run: surge --project ./ --domain <your-prefered-surge-subdomain>.surge.sh --token $SURGE_TOKEN

Change path and domain accordingly*
For custom domain (dns updated) use
surge --project ./ --domain xyz.com --token $SURGE_TOKEN

04. Hosting a React Web App with Surge

React apps built with Create React App output static files ready for Surge.

i. Create a production build

   npm run build

This generates a dist/ folder with optimized production assets.

ii. Deploy to Surge

   surge ./dist my-react-app.surge.sh

Pro Tip: Add a deploy script to your package.json to simplify deployment:
// package.json
{
  "scripts": {
    // ...other scripts...
    "deploy": "npm run build && surge ./dist my-react-app.surge.sh"
  }
}
Now you can deploy with:
npm run deploy

iii. Enable SPA routing (single-page application)

Add a 200.html fallback so all client-side routes resolve:

   cd dist
   cp index.html 200.html
   surge . my-react-app.surge.sh

05. GitHub Actions Workflow for Auto-Deploy React App

Automate your deployments on every push to the main branch.

Create .github/workflows/deploy-react-surge.yml in your repo:

name: Deploy React App to Surge

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Build and Deploy
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Copy fallback for SPA
        run: |
          cd dist
          cp index.html 200.html

      - name: Deploy to Surge
        env:
          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
        run: |
          npm install --global surge
          surge --project ./dist --domain <your-prefered-surge-subdomain>.surge.sh --token $SURGE_TOKEN

Getting your Surge token

First, you’ll need your token from the Surge CLI. This secret key lets services like GitHub Actions authenticate and publish projects on your behalf. Get your Surge token by running the following command in your terminal:

surge token

You’ll be asked to log in again, and afterwards your token will be displayed like this:

token: ar892djio57hd......

Finally, add this token as a secret named SURGE_TOKEN in your GitHub repository settings.

06. Surge with Custom Domain

To use a custom domain with Surge:

i. Add your domain to the project

   surge ./dist your-domain.com

ii. Configure DNS

Create a CNAME record for your domain (e.g., www or @) pointing to geo.surge.world (or other appropriate Surge endpoint but this is new and it automatically routes traffic to the most optimal Surge datacenter based on location).
If using an apex/naked domain, add an ALIAS/ANAME record pointing to 45.55.110.124.

iii. Verify SSL

Surge provides automatic SSL/TLS via Let’s Encrypt for surge.sh subdomains. For custom domains, SSL requires Surge Plus or a third-party service like Cloudflare. It may take a few minutes for certificates to be issued with Surge Plus.

iv. Free SSL with Cloudflare

Surge's free plan does not include SSL for custom domains. However, you can use Cloudflare's free tier to enable HTTPS:

a. Create a Cloudflare account and add your domain.
b. Update your domain's nameservers to the ones provided by Cloudflare.
c. In the Cloudflare dashboard, navigate to SSL/TLS settings and set the encryption mode to Flexible.

d. Ensure your DNS records (CNAME or ALIAS) point to your Surge endpoint (e.g., geo.surge.world).

With Flexible mode, Cloudflare will serve HTTPS to your visitors while connecting to Surge over HTTP, providing free SSL encryption.

Cloudflare ssl setup can take anywhere between 15 minutes to 24 hours.

v. Managing multiple domains

You can deploy the same folder to multiple domains in one command:

   surge ./dist www.example.com example.net hello.example.org

07. Advanced Features

Advanced features like CORS, redirects, and password protection require Surge Plus.

i. CORS Configuration

Add a CORS file in your project root to control cross-origin requests (requires Surge Plus). For example:

   Access-Control-Allow-Origin: *

ii. Redirects and Rewrites

Use a ROUTER file to manage redirects and clean URLs. For example:

   301 /old-path /new-path
   301 /contact /about
   200 /api/* https://api.example.com/:splat

iii. Access Control

Password-protect your site with an AUTH file (requires Surge Plus):

   username:password

iv. Ignore File and Directories

Just like .gitignore, if you want to exclude specific files or directories from deployment, create a .surgeignore file and list them inside.
To override something on the default ignore list or make it must include, add it to your own .surgeignore file with an exclamation mark (!) in front.

.git
.vscode
!src/

v. Version Management

Surge does not support direct rollbacks. To revert to a previous version, manually redeploy the desired build:

   surge ./previous-build my-site.surge.sh

To remove a deployment:

   surge teardown my-site.surge.sh

08. Why To Choose Surge?

Surge shines in specific use cases:

Simplicity & Speed: Surge excels at pure simplicity and speed with its zero-configuration approach and lightning-fast deployments.
CLI-Native Workflow: If you prefer command-line workflows over GUI interfaces and git-based deployments, Surge offers the most streamlined experience.
Quick Prototyping: For rapid prototyping and sharing static builds, nothing beats the speed and ease of surge ./folder my-project.surge.sh.
Low Overhead: No need for repository setup, build configurations, or web interfaces - just deploy directly from any directory.
Multiple Domain Support: The ability to deploy to multiple domains in a single command is uniquely powerful.

Surge is ideal when you need the fastest path from local files to live website with minimal configuration. While platforms like Netlify, vercel and Cloudflare Pages offer more features (continuous integration, server-side functions, etc.), Surge's focused approach makes it the perfect tool for developers who value simplicity and speed.

09. Troubleshooting

Authentication errors: Run surge logout && surge login.
DNS propagation delays: Wait up to 24 hours; verify using dig or nslookup.
SSL issues: Check case-sensitive CNAME records and ensure Cloudflare's SSL mode is set correctly.
Build failures: Confirm local build works (npm run build) before deploying.

10. Best Practices

Keep your build or dist directory clean and up to date.
Version control your Surge configuration files (CORS, ROUTER, AUTH) in the project root.
Automate deployments on pull request previews using branches and surge subdomains.
Monitor performance using Lighthouse or a CDN analytics tool.
Regularly audit and update security headers.

11. Credits

My personal experience in using Surge
Official Surge.sh documentation: https://surge.sh/help/
DNS configuration insights from https://geo.surge.world/
Additional insights from various articles on Medium and Dev.to
ChatGPT for Markdown formatting, language improvements, and fixations

Happy deploying with Surge!

Authored By: 0xArchit

DEV Community: Archit Jain