@shopify/shopify-app-express

This package makes it easy for Express.js apps to integrate with Shopify. It builds on the @shopify/shopify-api package and creates a middleware layer that allows the app to communicate with and authenticate requests from Shopify.

Note: this package will enable your app's backend to work with Shopify APIs, and by default it will behave as an embedded app. You'll need to use Shopify App Bridge in your frontend to authenticate requests to the backend.

Requirements

To follow these usage guides, you will need to:

• have a Shopify Partner account and development store
• have an app already set up on your partner account
• have a JavaScript package manager such as yarn installed
• have Express.js v5 or later installed (express@^5.0.0)

Getting started

To install this package, you can run this on your terminal:

# Create your project folder
mkdir /my/project/path
# Set up a new yarn project
yarn init .
# You can use your preferred Node package manager
yarn add @shopify/shopify-app-express

Then, you can import the package in your app by creating an index.js file containing:

const express = require('express');
const {shopifyApp} = require('@shopify/shopify-app-express');

const PORT = 8080;

const shopify = shopifyApp({
  api: {
    apiKey: 'ApiKeyFromPartnersDashboard',
    apiSecretKey: 'ApiSecretKeyFromPartnersDashboard',
    scopes: ['your_scopes'],
    hostScheme: 'http',
    hostName: `localhost:${PORT}`,
  },
  auth: {
    path: '/api/auth',
    callbackPath: '/api/auth/callback',
  },
  webhooks: {
    path: '/api/webhooks',
  },
});

const app = express();

app.get(shopify.config.auth.path, shopify.auth.begin());
app.get(
  shopify.config.auth.callbackPath,
  shopify.auth.callback(),
  shopify.redirectToShopifyOrAppRoot(),
);
// Shop-specific webhook subscriptions — see the Webhooks section below.
// For most apps, app-specific subscriptions configured in shopify.app.toml are recommended instead.
// https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions
app.post(
  shopify.config.webhooks.path,
  shopify.processWebhooks({webhookHandlers}),
);

app.get('/', shopify.ensureInstalledOnShop(), (req, res) => {
  res.send('Hello world!');
});

app.listen(PORT, () => console.log('Server started'));

Once you set the appropriate configuration values, you can then run your Express app as usual, for instance using:

node ./index.js

To load your app within the Shopify Admin app, you need to:

1. Update your app's URL in your Partners Dashboard app setup page to http://localhost:8080
2. Update your app's callback URL to http://localhost:8080/api/auth/callback in that same page
3. Go to Test your app in Partners Dashboard and select your development store

Environment variables

The following environment variables are automatically read as defaults when they are not explicitly provided in the api config object passed to shopifyApp():

| Variable | Maps to config field | Description | | ------------------ | -------------------------- | ------------------------------------------------------------ | | SHOPIFY_API_KEY | apiKey | Your app's API key from the Partners Dashboard | | SHOPIFY_API_SECRET | apiSecretKey | Your app's API secret from the Partners Dashboard | | HOST | hostScheme / hostName | Your app's public URL (e.g. https://my-app.example.com) | | SCOPES | scopes | Comma-separated list of OAuth scopes (e.g. read_products,write_orders) |

For example, if you set these environment variables:

SHOPIFY_API_KEY=mykey
SHOPIFY_API_SECRET=mysecret
HOST=https://my-app.example.com
SCOPES=read_products,write_orders

Then you can omit them from the config:

const shopify = shopifyApp({
  auth: {
    path: '/api/auth',
    callbackPath: '/api/auth/callback',
  },
  webhooks: {
    path: '/api/webhooks',
  },
});

Any values explicitly passed in the api config will take precedence over the environment variables.

Webhooks

Shopify supports two ways to subscribe to webhooks: app-specific and shop-specific. For most apps, app-specific subscriptions are the recommended approach. See App-specific vs shop-specific subscriptions for a full comparison.

Shop-specific reconciliation behavior

When shopify.auth.callback() completes an offline OAuth session, it automatically calls register() to reconcile the store's shop-specific webhook subscriptions with the handlers declared in webhookHandlers.

register() will delete any shop-specific webhook subscriptions that are not present in webhookHandlers. App-specific subscriptions (configured in shopify.app.toml) are not affected.

This means all shop-specific webhook topics your app relies on must be declared in webhookHandlers:

const webhookHandlers = {
  PRODUCTS_UPDATE: [{
    deliveryMethod: DeliveryMethod.Http,
    callbackUrl: '/api/webhooks',
    callback: handleProductsUpdate,
  }],
  // All other shop-specific topics your app uses must be listed here.
  // Any topic not listed will be unsubscribed from the store on next OAuth.
};

app.post(
  shopify.config.webhooks.path,
  shopify.processWebhooks({webhookHandlers}),
);

If you are migrating from a custom implementation or another library, make sure to declare all of your existing webhook topics in webhookHandlers before your app goes through OAuth, or those subscriptions will be deleted.

Migrating from shop-specific to app-specific

If you are switching from shop-specific to app-specific subscriptions, remove existing shop-specific subscriptions for the same topics first. Having both types subscribed to the same topic will result in duplicate webhook deliveries. See the Shopify documentation for more details.

Next steps

Now that your app is up and running, you can learn more about the shopifyApp object in the reference docs.