Surge.sh is a free static website host which you interact with from your command line. It makes it quick and easy to get new sites and apps online, either manually or as part of your CI build process. Here’s how to get started using the service.
We’ll assume you’ve already got a directory of files you want to deploy to the web. If you haven’t, create a new folder, add an
index.html, and some simple starter content.
npm install --global surge
Installing Surge globally means you can use the
surge command anywhere, even if your working directory lacks a
package.json file. Omitting the
--global flag will add the package as a project dependency instead, letting you lock the Surge version used for individual sites.
Now change directory into your website’s repository. Run the
surge command to start the deployment process. A series of interactive prompts will be displayed, starting with your email address to setup a Surge account.
Next, confirm the filesystem path to your project. This defaults to your working directory so you can usually press return to continue.
The following prompt asks for a domain name. A random
.surge.sh subdomain is selected automatically. You can choose a different subdomain, or one of your own domains, by entering it here. If you’re using your own domain, the following sections explain how to finish setting it up.
After you’ve supplied a domain name, press enter to begin the deployment. The progress will be displayed in your terminal as the Surge CLI uploads your files and makes them available on the web. Visit your domain in your browser to see your content live!
Site updates are applied by running the
surge command again. The contents of your project directory will be synced up to your live website.
Everything in your folder is uploaded by default. You can exclude specific paths by creating a
.surgeignore file. This has the same syntax as
.gitignore. Files and folders commonly created by other developer tools, such as Git and npm, are automatically omitted.
Using Your Own Domain Name
Surge offers custom domain support via
CNAME records. This comes at no extra cost over the standard service. Add a
CNAME record in your domain provider’s control panel. Point the
www hostnames to
na-west1.surge.sh. Supply your domain name when running
surge to deploy your site.
You’ll be prompted for your domain each time you run the
surge command. You can avoid this by adding the
--domain flag to
surge commands. Alternatively, create a
CNAME file in your project directory. Write your domain name into this file.
surge --domain example.com echo "example.com" > CNAME
Managing HTTPS Redirects
Surge has automatic HTTPS support but this does not handle HTTP to HTTPS redirects by default. Explicitly deploy to the
https variant of your domain to force all visitors to use a secured connection. Enabling redirects is advisable for all publicly accessible websites.
surge --domain https://example.com
You’ll need to supply an SSL certificate if you’re using your own domain. This feature is only available as part of the paid Surge Plus plan.
Surge also gives you control of bare domain to
www redirects. The default behavior sees
www.example.com redirect to
example.com. You can reverse this by explicitly including the
www portion in your deployment domain.
surge --domain https://www.example.com
Configuring Your Site
Surge offers several built-in convenience functions which help it stand out against other similar platforms. You can add a 404 page, password protection, and CORS support, all using special files in your project.
The 404 page is enabled by creating a
404.html file. That’s all there is to it – Surge will serve the file when there’s no direct match for the requested URI.
Password protection is enabled by an
AUTH file. This accepts a simple list of usernames and passwords.
You’ll be prompted to enter a username and password using HTTP Basic Authentication each time you access your site. This feature is only available on the paid Surge Plus plan.
Another Surge Plus feature is manual routing rules. You can create a
ROUTER file to define custom redirects, either within your site or externally.
301 /moved-page /new-link
301 (moved permanently) and
307 (moved temporarily) status codes for the first column. The last column can be a relative link within your site, or an absolute link to another domain (
One final configuration file is
CORS. This lets you permit cross-origin access to your site. Add a
* to the file to accept cross-origin requests from any origin. You can write individual domains instead to limit the allowed origins.
Automating Surge Deployments
Surge is entirely controlled by text files and terminal commands. It’s easy to integrate into CI pipelines to deploy websites automatically on each commit.
Automating Surge requires use of API tokens. This lets you avoid the interactive login prompts. First, login to Surge on your development machine. Run
surge token to get your API token.
In your CI pipeline, set the
SURGE_TOKEN environment variables. The former should be your email address while the latter takes your API token. Now you can deploy non-interactively using the
surge --project $PWD --domain example.com
Surge makes it simple to get static websites live on the web. The basic service is free to use. Upgrading to the Plus plan gives you authentication, redirects and more configurable HTTPS.
Unlike other contenders, Surge is fully terminal-driven. This makes it ideal for quick developer-centric sites managed via Git repositories and CI pipelines. It cuts out the server configuration so you can focus on building your site’s content.
For more advanced use cases, Surge even lets you add multiple contributors. Run
surge --add firstname.lastname@example.org to give friends, guests, and colleagues access to your site. They’ll be able to deploy by running
surge and supplying the same domain name you’ve been using.