# Adding a custom domain to an environment 

Gadget provisions a free `gadget.app` subdomain for each app you create, and supports routing your own domains (like `my-cool-app.com`) to your Gadget app.

Configuring a custom domain is done by messaging Gadget support on [Discord](https://ggt.link/discord).

## How custom domains work 

Custom domains are routed to your Gadget app via DNS records. You'll configure your domain to resolve to Gadget's IP address via a `CNAME` DNS record, and then Gadget will route incoming requests to your app. You can have multiple domains point to the same Gadget app, including your original `.gadget.app` domain, but only one domain will be identified as the "primary" domain. Requests to domains other than the primary domain will be redirected to the primary domain.

## Custom domain requirements 

To route a custom domain to your Gadget app, you will require:

*   a Gadget app with a Production environment
*   purchasing a domain name from a domain registrar
*   DNS records that point your domain name to your Gadget app

Gadget doesn't provide domain registration services or DNS resolution. Gadget only supports custom domains for the Production environment of an application, but reach out to Gadget support if you'd like a more advanced configuration.

## Adding a custom domain to an environment 

To add a custom domain to an environment, you will need to:

1.  Create a CNAME record that points your custom domain name to your original `gadget.app` domain.
2.  Message Gadget support to add the custom domain to your environment. Please include the following information:
    *   The domain name you're adding
    *   The `.gadget.app` subdomain of your Gadget app
    *   which DNS provider you're using
3.  Update any external URLs that point to your Gadget app to use the new custom domain, which includes URLs in the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard) if building a Shopify app.

*   The domain name you're adding
*   The `.gadget.app` subdomain of your Gadget app
*   which DNS provider you're using

For example, if you have a Gadget app at `my-cool-app.gadget.app`, and you have a custom domain of `app.super-company.com`, you must create a `CNAME` DNS record that points `app.super-company.com` to `my-cool-app.gadget.app`. In Cloudflare, this DNS record looks like this:

Once you and the Gadget staff are satisfied that the DNS records are correctly configured, the Gadget team will update your app to mark your new custom domain as the primary domain. All requests to any active domain for your app will be redirected to the primary domain.

### Updating external URLs 

After adopting a custom domain, you should update any URLs in other systems that point to your Gadget app to use the new custom domain. Without doing this, traffic will keep going to the old `gadget.app` domain, and getting redirected to the new one, which reduces performance and can break systems if they don't follow redirects.

Examples of other system URLs that you may need to update:

*   the App URLs and/ OAuth Redirect URL for a Shopify App in Shopify's systems
*   the Auth callback URL and Load callback URL for a BigCommerce app in BigCommerce's systems
*   the authorized domains and redirect URLs for a Google SSO OAuth setup
*   incoming webhook URLs from other systems like Stripe within that system

#### Updating Shopify URLs after adopting a custom domain 

If you're building a Shopify app, you'll need to update the App URL and OAuth redirect URLs for your app to use the new custom domain. You can use the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard) to do this, or update them in your `shopify.app.toml` if you're making use of the Shopify CLI.

For example, if you're old Shopify App URL was `https://my-cool-app.gadget.app/api/shopify/install-or-render`, and you've adopted a custom domain of `app.super-company.com`, you'll need to update the App URL to `https://app.super-company.com/api/shopify/install-or-render`. If your App URL was `https://my-cool-app.gadget.app` before adopting the custom domain, you'd update it to `https://app.super-company.com`.

Gadget handles automatically re-registering Shopify webhooks that Gadget had previously registered for your old `gadget.app` domain, so you don't need to take action to update these. If you are making use of the Shopify GDPR webhooks, you must manually update these in the Shopify Dev Dashboard or your `shopify.app.toml` file.

### Apex domain support 

Gadget supports custom domains that use subdomains, like `platform.my-company.com`, as well as apex domains, like `my-cool-app.com`.

When using subdomains, you can use DNS `CNAME` records to point your subdomain to your Gadget app. However, some DNS providers don't support `CNAME` records for apex domains. DNS providers that do support `CNAME` records for apex domains often call this "CNAME flattening" or "ALIAS records".

If you want to use an apex domain, but your DNS provider doesn't support `CNAME` records, you can:

*   use a subdomain instead
*   switch to a different DNS provider that supports `CNAME` apex records, like [Cloudflare](https://www.cloudflare.com/dns/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/records-overview#alias-records)

Gadget doesn't support using DNS `A` records that resolve to an IP address for apex domains for network security reasons. Don't try to use `A` records for apex domains.

### HTTPS support 

Gadget automatically provisions a free SSL certificate for your custom domain and routes requests to your app using the same high-performance global network that powers Gadget's own `gadget.app` domains.