What happens when you publish.

Upload

The CLI packs the directory you name, or a single HTML file, which it publishes as index.html. Dotfiles and node_modules stay behind, plus anything in a .surgeignore.

Files the domain already has are carried over instead of sent again, so republishing a large project after a small change uploads only what changed.

$ surge ./dist my-app.surge.sh

A project can be up to 450 MB and 10,100 files. The CLI checks before uploading, so an oversized project fails in a second, not after the upload.

Revision

Every publish becomes a revision with its own id, a millisecond timestamp. A revision is complete and immutable: the files, the config files (200.html, 404.html, CNAME, AUTH, ROUTER, CORS) and a message if you passed one.

A preview stops here. It gets its own address and production doesn't move.

$ surge ./dist my-app.surge.sh --preview

Preview hosts look like 1785787164375--my-app.surge.sh, or 1785787164375--example--com.surge.sh for a custom domain, and latest--my-app.surge.sh always shows the newest. The domain keeps its last 100 revisions.

Cutover

Production is a pointer to one revision. A normal publish moves it to the new revision in one step, so visitors see either the old project or the new one, never a mix.

Moving the pointer doesn't upload anything, which is why rollback is instant.

$ surge my-app.surge.sh revs
$ surge my-app.surge.sh cutover 1785787164375
$ surge my-app.surge.sh rollback

See Revisions for rollfore and discard.

The network

Ten regions serve every project: San Francisco, New York, Toronto, London, Amsterdam, Frankfurt, Bangalore, Singapore, Tokyo and Sydney. For surge.sh names, CNAMEs and delegated domains, DNS answers with the region nearest the visitor.

A publish tells every region to drop its cached copy of the domain, so the next request anywhere serves the new revision. The CLI prints each region's status as part of the publish.

Live status and uptime for each region: the network page.

Domains and certificates

Every project can use a *.surge.sh name, which already has a certificate. For your own domain, point a CNAME at geo.surge.world, add an A record, or delegate the domain to Surge's name servers.

Once the domain points at Surge, a certificate is issued and from then on renewed automatically. Free on every plan.

Check any domain with surge my-app.surge.sh status. Custom domains has the records.

Limits, stated up front

Publishing is rate limited per domain, per account and per address, and the limits are published. A limited publish answers with how long to wait.

Limits apply to publishing only. A project that's live keeps serving; nothing is metered and there are no overage charges.

New accounts publish at half these limits until the email is verified. Need more? Email us.