Deploying with Netlify

This page explains how to deploy a front-end application to Netlify. 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 Netlify.

Need 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 Netlify Site

First, we need to make sure that Netlify's build process can find the @gadget-client package for your application. If you haven't already, ensure that you have a .npmrc file in your repo next to the package.json that manages the @gadget-client dependency. 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 need to log in to Netlify and add a new site. To do so, click on the "Add new site" dropdown on the right side of the sites section and select "Import an existing project".

Netlify add a new site image

From here we can click on "GitHub" and search for the repository we want to deploy from.

Netlify repository import page image

Clicking on the repository name will bring you to the next page where we can configure the project. From here you can modify Build settings and add environment variables to your site.

Embedded Shopify Apps

To deploy Shopify applications to Netlify, some more set-up is required.

Add the environment variable SHOPIFY_API_KEY by clicking on Show advanced and New variable. You can find the value for SHOPIFY_API_KEY either on the "Overview" or "Client credentials" pages of your Shopify Partners Dashboard under the Client ID header.

Netlify environment variables section image

If you forget to add environment variables or need to modify the build settings, you can do so again on the "Site settings" page later on.

Once this is complete you can click on "Deploy site" and watch the logs, by clicking on the yellow 'Site deploy in progress' link, to make sure that the deployment was successful.

Netlify build logs link image

Once deployment is successful, you should see the text "Site is live" at the bottom of the build logs and a site preview on the "Site overview" page next to your site's domain.

For your application to be accessed by users, you must first change the app URL on the Shopify Partner Dashboard and the Gadget Connections page. In the Netlify "Site overview" page for your deployed site, copy the URL beside the site preview.

Netlify domain location image

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 submitting your app to Shopify for review, you will need to add a couple of files to conform with Shopify's Content Security Policy (CSP) header requirements. You can follow the Shopify iFrame protection example to test that you are setting the CSP header correctly.

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

You need to create a Netlify Edge function. Edge functions are serverless functions that are hosted on AWS Lambda.

Create a new folder at the root of your project, netlify/edge-functions, and add a file named csp.ts. In this file, add the following code snippet:

netlify/edge-functions/csp.ts
JavaScript
1// @ts-ignore
2import type { Context } from "https://edge.netlify.com";
3
4export default async (request: Request, context: Context) => {
5 const url = new URL(request.url);
6 const shop = url.searchParams.get("shop");
7
8 if (shop) {
9 const response = await context.next();
10 response.headers.set(
11 "Content-Security-Policy",
12 `frame-ancestors https://${shop} https://admin.shopify.com;`
13 );
14 return response;
15 }
16};

To make sure that this Netlify Edge function deploys, you will need to add a netlify.toml at the root directory with the following configurations:

netlify.toml
toml
[[edge_functions]]
path = "/*"
function = "csp"

You also need to navigate to the build settings and change the Publish directory input field to web/frontend/dist.

Netlify publish directory section image

Once a new deployment is triggered, you're all finished.

Congrats, your app should now be deployed on Netlify! You can now install your app on a store or view your app in a store admin on which it has previously been installed.