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.

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 Partner Dashboard if building a Shopify app.

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 Partners 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 Partner 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 an apex domain however, you can't use DNS A records that resolve to an IP address, as this is not supported by Gadget's network infrastructure for security reasons. You must use a CNAME record, and only some DNS providers support this.

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 records, like Cloudflare

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.