Installation
npm install @shopify/shopify-app-express
shopifyApp()
Creates middleware and utilities for building Shopify apps with Express.
Function Signature
function shopifyApp<Params extends AppConfigParams>(
config: Params
): ShopifyApp<Params>
Configuration
Configuration object for the Express app
api
ExpressApiConfigParams
required
Shopify API configuration
The version of Shopify’s Admin API to use
Your app’s API key. Defaults to process.env.SHOPIFY_API_KEY
Your app’s API secret key. Defaults to process.env.SHOPIFY_API_SECRET
The access scopes your app needs. Defaults to process.env.SCOPES?.split(',')
Your app’s host name. Defaults to process.env.HOST without protocol
The protocol for your app. Defaults to extracted from process.env.HOST
Whether your app renders embedded inside the Shopify Admin
REST API resource configurations
auth
AuthConfigInterface
required
Authentication configuration
The URL path for initiating OAuth
The URL path for the OAuth callback
Array of billing plan names to check during authentication
webhooks
WebhooksConfigInterface
required
Webhook configuration
The URL path for receiving webhooks
Session storage adapter. Defaults to MemorySessionStorage
Whether to use online access tokens
exitIframePath
string
default:"/exitiframe"
Path for breaking out of iframe
Return Value
Returns a ShopifyApp object with the following properties:
The validated and processed configuration
The Shopify API instance for making direct API calls
Express middleware for handling OAuth authenticationUsage:app.get(shopify.config.auth.path, shopify.auth.begin());
app.get(shopify.config.auth.callbackPath, shopify.auth.callback());
begin() - Returns middleware to start the OAuth flowcallback() - Returns middleware to handle the OAuth callback
processWebhooks
ProcessWebhooksMiddleware
Express middleware for processing webhook requestsFunction Signature:(options: ProcessWebhooksOptions) => RequestHandler
app.post(
shopify.config.webhooks.path,
shopify.processWebhooks({ webhookHandlers })
);
validateAuthenticatedSession
ValidateAuthenticatedSessionMiddleware
Express middleware that validates the session and redirects to auth if invalidFunction Signature:Usage:app.get('/protected-route',
shopify.validateAuthenticatedSession(),
async (req, res) => {
const session = res.locals.shopify.session;
// Use authenticated session
}
);
res.locals.shopify.session: Session - The validated session
Express middleware that adds Content Security Policy headers for embedded appsFunction Signature:Usage:app.use(shopify.cspHeaders());
ensureInstalledOnShop
EnsureInstalledMiddleware
Express middleware that ensures the app is installed on the shopFunction Signature:Usage:app.use('/app/*', shopify.ensureInstalledOnShop());
redirectToShopifyOrAppRoot
RedirectToShopifyOrAppRootMiddleware
Express middleware that redirects to Shopify or app root based on contextFunction Signature:Usage:app.get('/', shopify.redirectToShopifyOrAppRoot());
Function to redirect users out of the embedded app contextFunction Signature:(params: {
req: Request;
res: Response;
redirectUri: string;
shop: string;
}) => void
shopify.redirectOutOfApp({
req,
res,
redirectUri: 'https://example.com/external-page',
shop: 'my-shop.myshopify.com'
});
Example Usage
import express from 'express';
import { shopifyApp } from '@shopify/shopify-app-express';
import { MemorySessionStorage } from '@shopify/shopify-app-session-storage-memory';
import { ApiVersion } from '@shopify/shopify-api';
const app = express();
const shopify = shopifyApp({
api: {
apiVersion: ApiVersion.October24,
// apiKey, apiSecretKey, scopes, hostName defaults from env vars
},
auth: {
path: '/api/auth',
callbackPath: '/api/auth/callback',
},
webhooks: {
path: '/api/webhooks',
},
sessionStorage: new MemorySessionStorage(),
});
// Apply CSP headers
app.use(shopify.cspHeaders());
// OAuth routes
app.get(shopify.config.auth.path, shopify.auth.begin());
app.get(shopify.config.auth.callbackPath, shopify.auth.callback());
// Webhook endpoint
app.post(
shopify.config.webhooks.path,
express.text({ type: '*/*' }),
shopify.processWebhooks({ webhookHandlers })
);
app.listen(3000);
Exported Types
export {
ApiVersion,
} from '@shopify/shopify-app-express';
export type {
AppConfigParams,
ExpressApiConfigParams,
AuthConfigInterface,
WebhooksConfigInterface,
ShopifyApp,
AuthMiddleware,
ProcessWebhooksMiddleware,
ValidateAuthenticatedSessionMiddleware,
CspHeadersMiddleware,
EnsureInstalledMiddleware,
RedirectToShopifyOrAppRootMiddleware,
RedirectOutOfAppFunction,
} from '@shopify/shopify-app-express';
Response Locals
When using authentication middleware, the following data is attached to res.locals.shopify:
res.locals.shopify = {
session: Session; // The validated Shopify session
};
See Also