DEV Community

Cover image for Surge Usage Documentation | A Powerful CLI Tool for Effortless Frontend Deployments
Archit Jain
Archit Jain

Posted on • Edited on

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

#frontend #staticwebapps #opensource #beginners

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:

  1. Prerequisites
  2. Installing Surge CLI
  3. Basic Hosting with Surge
  4. Hosting a React Web App with Surge
  5. GitHub Actions Workflow for Auto-Deploy React App
  6. Surge with Custom Domain
  7. Advanced Features
  8. Why Surge?
  9. Troubleshooting
  10. Best Practices
  11. 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
Enter fullscreen mode Exit fullscreen mode

After installation, verify by running:

surge --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

iii. Publish your site

   surge ./dist your-subdomain.surge.sh
Enter fullscreen mode Exit fullscreen mode
  • ./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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

This generates a dist/ folder with optimized production assets.

ii. Deploy to Surge

   surge ./dist my-react-app.surge.sh
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

token: ar892djio57hd......
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Cloudflare dashboard ssl config screenshot

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
Enter fullscreen mode Exit fullscreen mode

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: *
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

iii. Access Control

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

   username:password
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

To remove a deployment:

   surge teardown my-site.surge.sh
Enter fullscreen mode Exit fullscreen mode

08. Why To Choose Surge?

Surge shines in specific use cases:

  1. Simplicity & Speed: Surge excels at pure simplicity and speed with its zero-configuration approach and lightning-fast deployments.

  2. CLI-Native Workflow: If you prefer command-line workflows over GUI interfaces and git-based deployments, Surge offers the most streamlined experience.

  3. Quick Prototyping: For rapid prototyping and sharing static builds, nothing beats the speed and ease of surge ./folder my-project.surge.sh.

  4. Low Overhead: No need for repository setup, build configurations, or web interfaces - just deploy directly from any directory.

  5. 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

Top comments (0)