Custom Domains

Every project on Surge can live at your own domain, free. Once the domain points at Surge, publishing to it is identical to publishing to a subdomain:

surge ./dist example.com

There are two ways to point a domain at Surge.

Option 1: Delegate to Surge's name servers (recommended)

Set your domain's name servers, at your registrar, to:

ns1.surge.world
ns2.surge.world
ns3.surge.world
ns4.surge.world

Surge then answers DNS for the domain with geo-aware routing—visitors resolve to the nearest edge. The records for your project (including the wildcard that makes subdomains work) are managed automatically, and anything extra—mail records, verification strings, subdomains pointed elsewhere—you manage from the CLI with the dns commands:

surge example.com dns add MX 10 mail.example.com

Option 2: CNAME at your current DNS provider

If you'd rather keep DNS where it is, add records at your provider pointing your hostnames at Surge's CNAME target:

  1. Add a CNAME record for www (and any other subdomains) pointing to na-west1.surge.sh.
  2. For the apex/root domain, use your provider's ALIAS/ANAME/flattened-CNAME record type if available. Providers without one can't CNAME an apex—delegating to Surge's name servers (option 1) is the clean solution.
  3. Optionally add a wildcard (*) record to make all subdomains publishable.

Every publish prints the current set of valid targets in its server table, and surge <domain> debug status will confirm your domain is resolving to Surge correctly.

DNS changes can take time to propagate depending on the provider—Surge is ready the moment the records are.

Remembering the domain

Publish to the domain once and Surge records it in a CNAME file in your project (the same convention GitHub Pages uses)—from then on, surge publish needs no arguments:

surge ./dist example.com     # first publish writes dist/CNAME
surge publish                # every publish after: no domain to type

Subdomains

Each subdomain is its own independent project—own revisions, own settings, own collaborators:

surge ./www  example.com
surge ./docs docs.example.com
surge ./app  app.example.com

www and the root domain

You don't need to publish to both. Surge redirects the www form of your domain to the root automatically—or vice versa, if you publish to the www form. Either way there's exactly one canonical URL for every page, which is what search engines want to see. See Clean URLs.

HTTPS for your domain

Once the domain resolves to Surge, a free managed certificate is provisioned automatically—watch it happen with:

surge example.com debug status

See SSL & HTTPS.