Previews
A preview uploads a new revision without changing what production serves. You get a URL to check, share, and test against—and production stays exactly as it was until you decide otherwise.
surge publish --preview
$ surge ./dist publish --preview Running as you@example.com (Free) project: ./dist domain: lucid-example.surge.sh size: 4 files, 695 bytes upload: [=========================] 100% CDN: [=========================] 100% encryption: [=========================] 100% ┌──────────┬────────────────────────────────────────────────────────────────┬───────────────────────┐ │ CERT │ *.surge.sh, surge.sh │ auto-renew │ ├──────────┼────────────────────────────────────────────────────────────────┼───────────────────────┤ │ DNS │ using Surge Name Servers │ geo-aware │ └──────────┴────────────────────────────────────────────────────────────────┴───────────────────────┘ ┌──────────┬──────────────────┬───────────────────────┬─────────────────────┬─────────────┬─────────┐ │ HTTP │ sfo.surge.sh │ US, San Francisco │ 138.197.235.123 │ D.Ocean │ ✔ ◍ │ │ HTTP │ lhr.surge.sh │ GB, London │ 46.101.67.123 │ D.Ocean │ ✔ ◍ │ │ HTTP │ yyz.surge.sh │ CA, Toronto │ 159.203.50.177 │ D.Ocean │ ✔ ◍ │ │ HTTP │ jfk.surge.sh │ US, New York │ 159.203.159.100 │ D.Ocean │ ✔ ◍ │ │ HTTP │ ams.surge.sh │ NL, Amsterdam │ 188.166.132.94 │ D.Ocean │ ✔ ◍ │ │ HTTP │ fra.surge.sh │ DE, Frankfurt │ 138.68.112.220 │ D.Ocean │ ✔ ◍ │ │ HTTP │ sgp.surge.sh │ SG, Singapore │ 139.59.195.30 │ D.Ocean │ ✔ ◍ │ │ HTTP │ blr.surge.sh │ IN, Bangalore │ 139.59.50.135 │ D.Ocean │ ✔ ◍ │ │ HTTP │ syd.surge.sh │ AU, Sydney │ 45.76.126.95 │ Vultr │ ✔ ◍ │ │ HTTP │ nrt.surge.sh │ JP, Tokyo │ 172.104.96.133 │ Linode │ ✔ ◍ │ └──────────┴──────────────────┴───────────────────────┴─────────────────────┴─────────────┴─────────┘ Live preview ................................................. 1785787164375-lucid-example.surge.sh Success! - Preview available at 1785787164375-lucid-example.surge.sh
(--stage and -s are aliases for --preview.)
The preview URL
Every revision—previewed or published—gets a permanent URL of its own, served over the same CDN as production: the preview propagates to every edge node just like a real publish, so what you're checking is exactly what production will be, served exactly how production serves. That URL is stable for the life of the revision, so it works for:
- Review: send the link to a teammate or client before shipping.
- Testing: point integration tests at the exact bits that will go live.
- History: every past revision remains viewable at its own URL, listed by
surge <domain> revs.
Shipping a preview
When the preview looks right, cut it over to production:
surge example.com cutover
cutover points production at the latest revision—the one you just previewed. Nothing is re-uploaded; the switch is atomic. If you previewed several candidates, pass the specific revision to ship:
surge example.com cutover 1719852000000
If the preview isn't right, discard it and production never knew it existed:
surge example.com discard 1719852000000
A typical flow
surge publish --preview -m "redesigned pricing page" # upload a candidate
# …check the preview URL, share it, run tests…
surge cutover # ship it
This is also the natural shape for CI: every branch build publishes a preview, and merging to the main branch runs a plain publish (or a cutover). See CI & Automation.
For the full picture of how revisions work—rollback, rollfore, discard—see Revisions.