Publishing

Publishing takes a directory and puts it on the web at a domain:

surge <path> <domain>

Both arguments are optional. Run surge with no arguments and it prompts for each—project path defaulting to the current directory, domain defaulting to a generated .surge.sh subdomain:

$ surge

   Running as you@example.com (Standard)

        project: ./
         domain: shiny-example.surge.sh
         upload: [====================] 100%, eta: 0.0s
   propagation: [====================] 100%
           plan: Standard

   Success! - Published to shiny-example.surge.sh

Some useful forms:

surge                          # publish cwd, prompt for domain
surge ./dist                   # publish ./dist
surge ./dist example.com       # publish ./dist to example.com — no prompts
surge -p ./dist -d example.com # same, using flags

At the domain prompt, accept the suggestion, type any domain you own, or type _ to get a fresh randomly-generated subdomain.

Choosing a domain

You can publish to two kinds of domain:

  • A surge.sh subdomain — free, instant, no setup: anything-you-like.surge.sh, as long as it's not taken.
  • Your own domain — also free; point it at Surge first. See Domains & DNS.

Prefixing the domain with a protocol controls HTTPS behavior: publish to https://example.com and the platform will redirect all HTTP traffic to HTTPS. See SSL Certificates.

The CNAME file

Typing the domain on every deploy gets old. Put it in a file named CNAME at the root of the directory you publish:

echo example.com > CNAME
surge

From then on, surge publishes straight to that domain with no prompt. The convention is shared with GitHub Pages, so a project can move between the two without changes. Other domain-taking commands (teardown, ssl) also use the CNAME file as their default suggestion.

Ignoring files

By default, Surge excludes things that don't belong on a web server:

.git  .*  *.*~  node_modules  bower_components

To exclude more, add a .surgeignore file to your project root. It uses the same syntax as .gitignore:

# .surgeignore
src/
*.map
drafts/

Everything else in the directory is published. Before uploading, the CLI prints a size: line with the file count and total size, so you'll notice if something unexpected is being included. Projects are limited to 10,100 files and 450 MB.

Deploy messages

Attach a message to a deploy the way you would to a git commit. Messages show up in the revision list, which makes surge list <domain> read like a deploy log:

surge -m "fix nav on mobile"

Managing collaborators while publishing

Add or remove collaborators as part of a deploy:

surge --add jacob@example.com     # invite jacob as you publish
surge --remove jacob@example.com  # revoke as you publish

What happens on publish

Each surge run uploads your files, propagates them across Surge's CDN, handles any certificate work, and prints the edge nodes now serving your project. Every publish creates a new revision—production cuts over atomically at the end, so a failed or interrupted upload never leaves your site half-updated. To deploy without cutting over production at all, use a preview deploy.