The Surge Platform

Surge is a web publishing platform built for front-end developers. You hand it a directory of HTML, CSS, and JavaScript; it hands you back a production site on a global CDN. The CLI is how you drive it—this section documents what the platform itself does with your project once it's up.

What every project gets

Publish anything to Surge—free—and it comes with:

  • A global edge network. Your files propagate to ten regions worldwide during the publish—every node confirms before the CLI says Success!—and visitors are served from the nearest one, with aggressive-but-correct caching applied automatically.
  • Custom domain support. Publish to your own domain at no cost, with DNS managed by Surge or by your existing provider.
  • SSL. Every surge.sh subdomain is HTTPS out of the box; custom domains get free managed certificates, provisioned automatically.
  • Clean URLs. /about serves about.html, canonical redirects are handled, and www folds into your root domain automatically.
  • Revisions. Every publish is kept, previewable, and instantly restorable.
  • Client-side routing for single-page apps, and custom 404 pages.
  • Gzip, ETags, and far-future caching—applied for you, never configured.

Configuration is files in your project

The platform's conventions follow one idea: your project directory is the configuration. Behavior is controlled by files that publish with your code:

File Purpose
CNAME Sets the project's domain.
.surgeignore Excludes files from publishing.
200.html Serves your app shell for unmatched URLs (SPA routing).
404.html The not-found page (custom 404s).
ROUTER Redirect rules (redirects).
AUTH Password protection & protected paths—a password on the project, or Google sign-in on specific paths.
CORS Cross-origin access (CORS).

Because these travel with every publish, each revision carries its own complete configuration—roll back the code and you roll back the behavior with it. The control files themselves (ROUTER, AUTH, CORS) are never served to visitors.

Free and paid

Publishing, custom domains, managed SSL, revisions, and the CDN are free. A paid plan adds the server-side features—password protection, redirects, CORS, custom certificates. See Plans.