Оффлайн
- Регистрация
- 1 Мар 2015
- Сообщения
- 1,481
- Баллы
- 155
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:
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
iv. Update or remove deployments
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
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
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
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.
You can deploy the same folder to multiple domains in one command:
surge ./dist 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/*
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:
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
Happy deploying with Surge!
Authored By:
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
- Node.js (v14+) and npm installed.
- A Surge account; sign up at 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.
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
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
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
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.
v. Managing multiple domains
You can deploy the same folder to multiple domains in one command:
surge ./dist 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/*
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.
- 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.
- My personal experience in using Surge
- Official Surge.sh documentation:
- DNS configuration insights from
- Additional insights from various articles on Medium and Dev.to
- ChatGPT for Markdown formatting, language improvements, and fixations
Happy deploying with Surge!
Authored By: