Domains & DNS

Custom domains are free on Surge. Publish to one the same way you'd publish to a subdomain:

surge ./dist example.com

For the domain to resolve, it has to point at Surge. There are two ways to do that, covered in detail in Custom Domains on the platform:

  1. Delegate the domain to Surge's name servers (recommended). This turns on geo-routing across the CDN and lets you manage DNS records right from the CLI.
  2. Add a CNAME record at your existing DNS provider. Simpler if you need to keep your current provider; DNS stays managed there.

Surge's name servers

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

Set these at your domain registrar (they're also printed by surge --help, and every publish prints the records for your project). Once the domain is delegated, Surge answers DNS for it—your site records are handled automatically, and anything extra is yours to manage with surge dns.

Managing DNS records

Once a domain is delegated, the dns command manages your custom records—no dashboard needed. This is how you keep email, subdomains, and verification records working on a domain that Surge serves:

surge dns example.com                                # view records
surge dns example.com add <type> <name> <value>      # add a record
surge dns example.com rem <id>                       # remove a record

For example:

# Point a subdomain somewhere else
surge dns example.com add CNAME app app.example.dev

# Site verification for a search console
surge dns example.com add TXT @ "google-site-verification=…"

# Mail — MX records take a priority before the value
surge dns example.com add MX 10 mail.example.com
surge dns example.com add MX @ 10 mail.example.com   # explicit host form

Adding or removing a record prints the resulting record set along with a Success confirmation. Each record has an id, shown in the listing, which is what rem takes.

DNS management applies to apex domains (example.com, not sub.example.com) that are delegated to Surge's name servers.

Viewing the full zone

surge dns shows the records you've added. To see everything Surge is answering for the domain—including the records it manages automatically—use zone:

surge zone example.com

This prints the domain's complete zone in BIND format: SOA, NS, and all records. zone also supports add and rem with the same syntax as dns, for the rare case where you need to override a managed record.

Subdomains

With a wildcard pointed at Surge (automatic when delegated to Surge's name servers), every subdomain of your domain is publishable, each as its own independent project:

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