Deploying with Heroku

This page explains how to deploy a companion frontend application, for your backend Gadget application, to Heroku. The front-end will serve the user interface that your users interact with and communicate to your Gadget backend app via your app's API.

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".

Heroku create new app button

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

Heroku app naming page

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 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.

Example of the SHOPIFY API KEY environment variable

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.

Heroku repository selection section

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".

Heroku manual deploy section

To connect your front-end 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.

Heroku 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.

Section in Gadget that displays Shopify app connections

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 app URLs section in App setup

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:

zsh
heroku 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:

zsh
heroku 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:

zsh
heroku 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.yml
yml
1build:
2 docker:
3 web: Dockerfile
4 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.