Nouvelles Solutions
← The journal

Deploying with surge.sh: A Simple Static Site Solution

Exploring how Surge.sh is used for deploying static websites, with real examples from n-so.com

As the developer of n-so.com, I wanted to share my experience using Surge.sh for deploying this website. Surge.sh is a simple, single-command publishing platform for static websites that has become an integral part of our deployment process.

⚠️ Update: I have since moved to Netlify as Surge.sh proved not to be reliable enough for production use.

What is Surge.sh?

Surge.sh is a cloud platform designed specifically for deploying static websites. It provides developers with a straightforward way to publish HTML, CSS, and JavaScript files to a custom domain or a Surge subdomain.

How We Use Surge.sh

For n-so.com, our deployment process is remarkably simple. After building our React application, we use Surge.sh to deploy the static files.

To get started, you'll need to install Surge.sh using npm:

npm install -g surge

Here's a basic example of our deployment command:

surge dist/apps/n-so.com n-so.com

In more details the full bash script looks like this:

pnpm exec nx run n-so.com:build
# Copying index.html to 200.html allows for page reload to work on all routes
cp dist/apps/n-so.com/index.html dist/apps/n-so.com/200.html
# Custom domain
cp surge/CNAME dist/apps/n-so.com
# Sitemap
cp apps/n-so.com/sitemap.xml dist/apps/n-so.com
# Robots
cp apps/n-so.com/src/assets/robots.txt dist/apps/n-so.com
# Deploy
surge dist/apps/n-so.com n-so.com
  • I use the pro plan so I could use their routing feature, for now I just copy the index.html to 200.html to make page reload work on all routes.
  • CNAME is used to setup the custom domain. You can start by using the surge subdomain which the surge command will randomly generate or you can pick your own.

Other usages

For a customer I've created a deploy script that deploys the current branch to a surge subdomain named after the company and the branch name. This allows for fast design feedback even before an PR is created.

Free vs Pro tier

surge.sh plan

Automated Github deploys

The following github action can be used to deploy to surge.sh:

    - name: Deploy to n-so.com
    uses: dswistowski/surge-sh-action@v1
    with:
        domain: 'n-so.com'
        project: 'dist/apps/n-so.com'
        login: ${{ secrets.surge_login }}
        token: ${{ secrets.surge_token }}

More info here: https://github.com/marketplace/actions/publish-to-surge-sh

Surge.sh Commands

Surge.sh ⚡ Static Web Publishing 0.24.6

Deploy

  surge                             (opt --preview)  publish with prompts
  surge <path>   <domain>           (opt --preview)  publish without prompts (recommended)
  surge config   <domain>                            view/change project configuration
  surge list     <domain>                            list all project revisions
  surge files    <domain>                            list all project files
  surge teardown <domain>                            tear down a published project

Analytics & Stats

  surge traffic  <domain>                            analytics showing project traffic

surge.sh traffic

  surge usage    <domain>                            analytics showing bandwidth usage
surge.sh usage 
  surge load     <domain>                            analytics showing global network load

surge.sh load

Other commands:

  surge audit    <domain>                            audit edgenode state
  surge audience <domain>                            analytics showing audience device

DNS

  surge dns|zone <domain>                            view DNS records
  surge dns|zone <domain> add <type> <name> <value>  add DNS record
  surge dns|zone <domain> rem <id>                   remove DNS record

Version management

surge list     <domain>                            list all project revisions
surge rollfore <domain>                            change to next revision
surge rollback <domain>                            change to previous revision
surge cutover  <domain>                            change to latest revision
surge discard  <revision>                          remove revision from system
surge bust     <domain>                            busts cache on all edgenodes

Authentication

surge whoami                                       show who you are logged in as
surge login                                        only performs authentication step
surge logout                                       expire local token
surge token                                        create token for automation purposes
surge plan                                         upgrade or downgrade account plan
surge nuke                                         permanently removes account

General info

surge list                                         list all projects
surge --version                                    outputs version
surge --help

Issues with Surge.sh

Surge.sh is a simple tool for deploying static websites, but it has some issues that we've encountered:

  • As I'm writing this, the surge.sh domain is down. Deploys still work but this gives a bad first impression.
  • 504's - Sometime the page doesn't load. Few month ago it was down for 2 days. This is enough to not concider using it for critical production websites. This said it's adequate enough for my tiny corner of the web.
  • No status page. Let me know if there is one!
  • Issues can be reported here: https://github.com/sintaxi/surge/issues
  • Netlify is more feature rich. The free tier is enought to get started with. If your website is critical the $19/month Pro tier is more than enough.

Conclusion

Play with it and see if it works for you. If you have any feedback or questions, please let me know!

Enjoy!

Daniel Wanja.

← Back to the journal