Deploying with Vercel

This page explains how to deploy a companion frontend application, for your backend Gadget application, to Vercel. 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 a Vercel account.

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 Vercel project

First, we need to ensure that Vercel will be able to install your @gadget-client package by adding the Gadget NPM registry. 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

Next, we can log in to Vercel and create a new project. To do so, click on the Add New... dropdown on the right side and select "Project".

Vercel create new project image

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

Vercel import repository image

Clicking Import will bring you to the next page where we can configure the project. From here you can apply build and output settings as well as environment variables.

To ensure Vercel connects to the Production environment of your Gadget application, set the NODE_ENV environment variable to production in the Vercel configuration:

Vercel configure NODE_ENV environment variable

If you need to modify the build settings or environment variables in the future, you can do so on the Settings page.

Embedded Shopify Apps

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

First, open the Environment Variables dropdown and add your SHOPIFY_API_KEY and value for your Production Shopify application. 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.

Vercel environment variables section image

For your Vercel front-end to access your Gadget backend, you must also ensure the App URL value on the Shopify Partner Dashboard and the Gadget Connections page reflect your new Vercel application's URL. In the Vercel dashboard for your deployed project, copy the URL beside the site preview, under the header "DOMAINS".

Vercel domain location image

In Gadget navigate to your active Shopify connection. Click on the pencil icon to the right of the Shopify Apps section to edit your connection, and 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. Replace the current App URL with your deployed application's domain and click save to confirm your changes.

Shopify app URLs section in App setup

next.js

If you're using next.js to build your front-end, you need to take one extra step if you intend to deploy to the Shopify App Store. Shopify requires that each Shopify App returns security headers when rendering the application for the iframe Shopify embeds it in. To ensure your next.js app replies with the correct Content-Security-Policy header, add a middleware.js file to your next.js application root:

/middleware.js
JavaScript
1import { NextResponse } from "next/server";
2
3export function middleware(request) {
4 const shop = request.nextUrl.searchParams.get("shop");
5
6 const response = NextResponse.next();
7 response.headers.set(
8 "content-security-policy",
9 `frame-ancestors https://${shop}/ https://admin.shopify.com;`
10 );
11 return response;
12}

Read more about Shopify's iframe security requirements in Shopify's docs.

Shopify CLI 3.X

If you're using the Shopify CLI to build and deploy a Shopify application, you need to take some extra steps for it to deploy correctly to Vercel. 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

First, we need to tell Vercel what command to run to build this app. We need to add the vercel-build script within web/package.json:

web/package.json
json
{
"scripts": {
"vercel-build": "cd frontend && npm install && npm run build"
}
}

This script instructs Vercel to install dependencies for both the node.js file server application and frontend vite application, and then build the production assets for the frontend.

Second, add a new file to the web directory of your Shopify app called vercel.json with the following contents.

web/vercel.json
json
1{
2 "version": 2,
3 "outputDirectory": ".",
4 "builds": [
5 {
6 "src": "index.js",
7 "use": "@vercel/node",
8 "config": {
9 "includeFiles": ["./frontend/dist/**"]
10 }
11 }
12 ],
13 "routes": [{ "src": "/(.*)", "dest": "/" }]
14}

This file instructs Vercel to:

  • copy the built production assets for the vite app into the serverless function for serving the application
  • run the index.js file as a node.js application to serve all the static files with correct headers

In the Configure Project section, edit the Root Directory option to read web/. This will direct Vercel to build and deploy the front-end for your Shopify app, and ignore any extensions or other files in your repo.

Vercel output directory section image

Once this is complete, commit your changes to your repo and push to Vercel. Watch the logs to make sure that the deployment was successful.

Once deployment is complete, you should see a congratulations page with a preview of your live site to the left.

Vercel deployment success page image

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