Using Surge for deploying static sites (2018 Update)


Static Site Generators have become increasingly popular over the past several years. They’re great for any projects not requiring server-side processing. There’s been an emergence of services such as and others for handling server endpoints. This has no doubt contributed to the growth of static sites and “serverless” web applications. Many see this as a major new direction for web app development. One such tool for dealing with static sites is Surge.

Of the many draws for using static site generators, the relative ease of building and deploying is significant. These types of deployments simplify the oft-involved and tedious process of setting up and managing a production server. This blog post will give an introduction to using Surge. It is an easy-to-use tool for deploying a production-ready static sites in a matter of minutes.

What is Surge?

Surge is a service for deploying and hosting static websites and applications. You can use it to host projects built with static-site generators such as Gatsby.js, Jekyll. Any custom project built with HTML, CSS and client-side JavaScript will work as well. Its free plan is optimal for just about any static site. There is a premium version available that adds some additional features such as Custom SSL, password protection and more.

Installing Surge

Installing Surge and setting up an account is extremely simple. Open up a new terminal window and type the following command:

npm install --global surge 


(Note: this step assumes Node and npm are already installed on your system. If not, you can install the latest version of both from the official Node.js website.)

Upon your first time setting up, Surge will ask you to set up an account. The only requirements are is providing an email address and password, and verifying your email afterwards. Upon completing this step, you’ll now be setup with a Surge account and ready to deploy to their service.

Deploying your site

To deploy your static site to Surge, first find the file path of the project directory you want to deploy. As an example, I’m going to deploy a project located at /Users/air/surge-test.

Once you know the file path of the directory to deploy, run the following command in a terminal window:



Your username (i.e. email address) will then display. Afterwards, you’ll just need to provide the file path for the project:


Enter the full file path, then hit enter.

Surge will automatically provide a domain name using random words. You can also create any custom domain if it is not already taken. Enter your chosen domain name, then hit enter.

(Note: If the custom domain name you input is already taken, you’ll see an error message.

Aborted - you do not have permission to publish to [<>]


Once deployment is complete, you’ll see a success message displayed in your terminal. The domain name and IP address for the project will show you where you can access the live deployment.


Enter the domain name into your web browser and you should now see your site live:


Adding a custom domain name for your site

Using a CNAME record

By default, Surge will provide a custom subdomain for any site that you deploy to their service. It will look something like You can customize and select what the subdomain is (provided it’s not already taken). Chances are, though, that you’ll want to use your own custom domain for any professional project.

To do so, you’ll want to add two new CNAME records in the DNS panel of your domain provider. One will be with a hostname of @, and the other will be with a hostname of www. Both CNAME records will point to the following IP address:

Using an A record

If for some reason your domain provider doesn’t allow CNAME records, you can set an A record as an alternative. Have the A record point to an IP address of

Using custom subdomains

You can also use any custom subdomain to point to Surge, such as To do so, you’ll want to set up a new CNAME record. This should point to the same IP address above, but this time the hostname will be *. The * hostname is a wildcard. This means that any subdomain apart of the primary domain will be valid and allowed.

Surge will recognize these DNS changes immediately. It can take take time to propagate elsewhere, however, typically no more than 24 – 48 hours.

Deploying your project using a custom domain

Once the DNS settings have taken effect, you can now deploy your project. You’ll just need to indicate the domain that you’d like to use. To do so, run the surge command in your terminal. Indicate the file path to your project first, then the custom domain afterwards, like so:

surge filepath/of/project


Bind your custom domain to the project

You may want to bind your domain to the project so you don’t have to enter it whenever you deploy. You can do so using the echo command, directing it to a CNAME file, like so:

echo > CNAME


Create a .surgeignore file

Much like the .gitignore file in the Git ecosystem, Surge offers its own ignore file. You can set up a list of files and directories that Surge will ignore at the time of deployment. This is useful for leaving out files that may only be relevant during the development process. Anything that you might want to keep entirely private is good to include here as well.

To set this up, create a new file called .surgeignore in the root of your project folder. Inside of this file, you can list any files and directories you’d like to to ignore. Some common examples might include node_modules, bower_components, and others. You can also ignore specific file types that aren’t relevant to the production version of a site. Adding * (the wildcard symbol) before the extension (i.e. *.swp, *.psd, etc.) will accomplish this.

Take down your site from Surge

If for some reason you’d like to take down your site, you can do this easily with the surge teardown command.

surge teardown


Post a Comment

Comments are moderated. Your email is kept private. Required fields are marked *

© 2019 Sunlight Media LLC