How to use a custom domain for your app

Every hosted app starts with a technical address, something like myapp.example-host.app. It works, but nobody wants to send that link to a customer. A custom domain swaps that address for mysite.com or app.mysite.com, and the app stays the same.

The process always involves three pieces: the domain, registered at your registrar; DNS, where you say where each name points; and the host, which has to recognize the name so it can serve the app and issue the certificate. If one piece does not match the others, the domain will not load.

What do I need before I start?#

• A registered domain in your name, at any registrar (Namecheap, GoDaddy, Porkbun and others).
• Access to the domain's DNS panel. If DNS was delegated to another provider, such as Cloudflare, you edit it there.
• A web app already running on the host, answering at its technical address.
• A plan that allows custom domains. Not every host offers this on every plan, so check before you start.

If the difference between buying a domain and buying hosting is still fuzzy, see domain vs. hosting.

Root, www or subdomain: which one should I use?#

To DNS, all three are different names:

• Root (mysite.com): the name with no prefix, also called the apex.
• www (www.mysite.com): a subdomain like any other.
• Another subdomain (app.mysite.com, api.mysite.com): good for keeping the app apart from a marketing site.

The practical difference is the record type. Per RFC 1034, a CNAME cannot coexist with other data at the same name, and the root always carries NS and SOA records. So the root usually uses an A record (or AAAA for IPv6), while www and other subdomains use CNAME. Some DNS providers offer CNAME flattening, which lets the root point to a name; others call similar features ALIAS or ANAME.

When in doubt, start with a subdomain: it has the fewest restrictions.

How do I add the domain, step by step?#

1. Add the domain on your host. In the app's panel, enter exactly the name people will type, for example app.mysite.com.

2. Copy the records the host shows. It gives you the type (A or CNAME) and the target value. Always use those values, never the ones from another tutorial.

3. Create the records in DNS. A generic example for a subdomain:

   Type	Name (host)	Value	TTL
   CNAME	app	host-target.example	300

   And for the root and www:

   Type	Name (host)	Value	TTL
   A	@	203.0.113.10	300
   CNAME	www	mysite.com.	300

   The values host-target.example and 203.0.113.10 are placeholders.

4. Remove conflicts. An old A or AAAA record at the same name as a CNAME usually makes the panel refuse the record.

5. Wait for DNS and validation. Once the host sees the record, it accepts the domain.

If your DNS panel appends the domain automatically, type only the prefix (app). If you type the full name, you end up with app.mysite.com.mysite.com, a very common mistake. The DNS steps in more detail are in how to point a domain to your hosting.

How do I know the domain is working?#

Query DNS directly, bypassing the browser cache:

dig app.mysite.com CNAME +short
dig mysite.com A +short

The answer should be the target your host gave you. Then check HTTP and the certificate:

curl -I https://app.mysite.com

A 200 status (or an expected redirect) with the certificate accepted means everything is fine. If dig already returns the right answer but the browser shows the old address, the cause is caching: try a private window.

How long the change takes depends on the TTL of the previous record, which resolvers keep in cache. A brand-new name usually resolves in minutes; replacing an existing record with a 3600 TTL can take up to an hour. Before migrating a domain in use, lower the TTL to 300 and wait for the old value to expire.

What about HTTPS?#

The certificate can only be issued after the domain resolves to the host, because you have to prove to the certificate authority that you control the name. On hosts with automatic TLS, issuance happens on its own right after. To understand the mechanism, see how Let's Encrypt works.

CAA records restrict which authorities may issue certificates for your domain (RFC 8659). With no CAA at all, any authority may issue. If you have one, include the authority your host uses. For Let's Encrypt, the value is letsencrypt.org, per its documentation:

mysite.com.  CAA  0 issue "letsencrypt.org"

Confirm with your host which authority it uses before creating a CAA record.

What are the most common errors?#

• CNAME at the root: the panel refuses it. Use A or a provider with CNAME flattening.
• Conflicting record: an old A record at the same name as the CNAME.
• Wrong nameservers: you edit DNS at the registrar, but the domain is delegated to another provider. Check with dig NS mysite.com +short.
• Only one name set up: mysite.com opens and www.mysite.com does not. Add both.
• Cloudflare proxy on during validation: a proxied record hides the real target and can interfere with validation. Try DNS only.
• CAA blocking issuance: see the previous section.
• Nonexistent domain error: see DNS_PROBE_FINISHED_NXDOMAIN.

If the browser shows a certificate error, the guide to SSL certificate errors walks through the causes.

How to do this on Square Cloud#

On Square Cloud, the three pieces of this guide stay clearly separate. The domain stays registered in your name at your registrar, the DNS zone stays at the registrar or the DNS provider you chose, and the platform recognizes the name and serves HTTPS. Custom domains are available from the Standard plan (starting at R$44.99 per month). Hobby does not include them and uses the *.squareweb.app subdomain, which every web application gets with HTTPS on every plan.

The steps are the ones in the section above, with fixed values. In the application's dashboard, you add the domain and see the two records to create: a CNAME to cname.squareweb.app and a TXT record for validation. Validation status shows up in real time, and the certificate is issued and renewed automatically once DNS resolves. To use the root, your DNS provider must support a CNAME at the apex (flattening or ALIAS); for www, the recommended setup is a redirect to the main domain. Accented domains (Punycode) are supported, and the dashboard offers cache purge.

Once the domain is live, the same name can serve more than one application with load balancing. See the details in custom domains and compare plans on pricing.