Deploying frontends to Heroku
This page explains how to deploy an external frontend for your Gadget backend to Heorku. This frontend will serve your app's user interface and communicate to your Gadget backend via your app's API.
Gadget includes built-in frontend hosting that doesn't require an extra deployment step. Gadget recommends using the built-in frontend hosting when possible for the best experience.
Read more about the built-in frontend in the Building Frontends guide.
Requirements
You will need an account with Heroku. We also recommend using GitHub to host your Git repository.
Are you trying to connect your existing Shopify CLI 3.X app to Gadget? Check out our Shopify CLI Connection tutorial.
For more CLI-specific docs, scroll down to the Shopify CLI 3.X section.
Setting up your Heroku App
First, we need to make sure that Heroku's node buildpacks can find the @gadget-client
package for your application. If you haven't already, ensure that you have a .npmrc
file your repo next to the package.json
referring to the @gadget-client
repo. For example, if your frontend resides in the web/frontend
folder of your repo, create the file web/frontend/.npmrc
with these contents:
.npmrc next to your frontend package.json@gadget-client:registry=https://registry.gadget.dev/npm
This configuration ensures that npm install
or yarn install
will correctly fetch your Gadget API client package from the Gadget registry.
Next, we must log in to Heroku and create an app. To do so, click on the "New" dropdown on the right side and select "Create new app".

From here you can name your app as desired and select the region in which to deploy your app.

Once the app is created you can add environment variables by going to the Settings page and scrolling down to the Config Vars section and clicking "Reveal Config Vars".
Embedded Shopify Apps
To deploy Shopify applications using external frontends to Heroku, some more set-up is required.
Add the SHOPIFY_API_KEY
to your Heroku app's environment variables. The SHOPIFY_API_KEY
can be found in your Shopify Partners Dashboard on the "Overview" or "Client credentials" pages under the header Client ID. The environment variable should look something like the below image.

To deploy the application navigate to the "Deploy" tab. Click on the GitHub deployment method. From here you can select the repository you wish to deploy from. Type in the name of your repository and click enter, then connect that repository with Heroku.

Now that the repository is connected to Heroku, scroll down to the Manual deploy section, choose the branch you want to deploy from and click on "Deploy Branch".

To connect your frontend with your Gadget backend, you must first change the app URL on the Shopify Partner Dashboard and the Gadget Connections page. Copy the URL of the deployed app on Heroku under the "Settings" tab and Domains section.

In Gadget navigate to your active Shopify connection. From here we can click on the pencil icon to the right of the Shopify Apps section. Replace the App URL with your deployed application's domain.

On the Partners Dashboard in Shopify, navigate to the App setup page, then to the URLs section. From here replace the current URL with your deployed application's domain and click save to confirm your changes.

Shopify CLI 3.X
Before deploying your site you will need to add a couple of files to conform with the Shopify Content Security Policy (CSP) header requirements. You can follow the Shopify iFrame protection example to test that you are setting the CSP header correctly.
You will need the Heroku CLI and Docker installed on your machine to follow these steps.
Ensure you have completed all the steps to set up your Shopify CLI application for Gadget backends in the Shopify CLI Connection tutorial before deploying to Vercel
Log in to Heroku using the CLI:
zshheroku login
Once the login process is complete, you will need to log in to the Heroku container registry from the root folder of your application:
zshheroku container:login
You now need to set your existing Heroku app to act as a docker container. Make sure to modify the app name to match Heroku:
zshheroku apps:stacks:set -a <heroku-app-name> container
Now that the Heroku deployment configurations are set up, you will need to add a heroku.yml
file at the root of your application. Replace <SHOPIFY_API_KEY>
with your Shopify API key:
heroku.ymlyml1build:2 docker:3 web: Dockerfile4 config:5 SHOPIFY_API_KEY: <SHOPIFY_API_KEY>6
Once all these prior steps have been completed and you have committed your changes to the linked repository, you are ready to deploy!
Congrats, your app should now be deployed on Heroku! You can now install your app on a store or view your app in a store admin on which it has previously been installed.
Related topics
- The Shopify CLI Connection tutorial
- The Heroku hosting platform