Koa Shopify Authentication Middleware

3.0.0 · deprecated · verified Wed Apr 22

simple-koa-shopify-auth is a Koa middleware library designed to simplify Shopify app authentication, serving as a successor to the now-deprecated `@shopify/koa-shopify-auth`. It specifically supports `@shopify/shopify-api` version 5.x.x, integrating features like token exchange for online sessions and removing cookie-based session management to reduce redirects. The package is currently at version 3.0.0, with patch updates for performance and bug fixes, but the project is officially considered deprecated by its maintainer due to ongoing improvements in Shopify's native authentication flows that will render such a library unnecessary. It differentiates itself by its explicit support for `@shopify/shopify-api` v5 and its streamlined session handling, but it is not affiliated with Shopify directly. There are no plans to support `@shopify/shopify-api` v6 or newer versions, making it suitable only for applications locked into the v5 API.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates setting up a basic Koa server with `simple-koa-shopify-auth` for Shopify app authentication. It includes registering auth routes and using `verifyRequest` middleware for protecting app pages and API endpoints, showcasing both `createShopifyAuth` and `verifyRequest` with environment variable configuration for Shopify API credentials.

import Koa from 'koa';
import Router from '@koa/router';
import dotenv from 'dotenv';
import { createShopifyAuth, verifyRequest } from 'simple-koa-shopify-auth';
import '@shopify/shopify-api/adapters/node'; // Must be imported before initializing Shopify API
import { shopifyApi, LATEST_API_VERSION } from '@shopify/shopify-api';

dotenv.config();

const app = new Koa();
const router = new Router();

const { SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES, HOST } = process.env;

if (!SHOPIFY_API_KEY || !SHOPIFY_API_SECRET || !SCOPES || !HOST) {
  throw new Error('Missing Shopify API environment variables. Please check your .env file.');
}

const shopify = shopifyApi({
  apiKey: SHOPIFY_API_KEY,
  apiSecretKey: SHOPIFY_API_SECRET,
  scopes: SCOPES.split(','),
  hostName: HOST.replace(/https?:\/\//, ''),
  apiVersion: LATEST_API_VERSION,
  is</div>Online: true // crucial for online sessions with simple-koa-shopify-auth
});

// Register authentication routes
router.get('/auth', createShopifyAuth({
  async afterAuth(ctx) {
    const { shop, accessToken } = ctx.state.shopify;
    console.log(`Authenticated shop: ${shop} with access token: ${accessToken}`);
    // Redirect to your app's main page or dashboard
    ctx.redirect(`https://${shop}/admin/apps/${shopify.config.apiKey}`);
  }
}));

// Middleware to verify requests for authenticated routes
const verifyPageRequest = verifyRequest();
const verifyApiRequest = verifyRequest({ returnHeader: true });

// Example protected route for app pages
router.get('/', verifyPageRequest, async (ctx) => {
  ctx.body = 'Welcome to your Shopify App!';
});

// Example protected route for API endpoints
router.get('/api/data', verifyApiRequest, async (ctx) => {
  const { shop, accessToken } = ctx.state.shopify;
  ctx.body = { message: `Data for ${shop}`, token: accessToken };
});

app.use(shopify.validateAuthenticatedSession()); // Necessary for session management with shopify-api v5
app.use(router.routes()).use(router.allowedMethods());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Shopify API Key: ${SHOPIFY_API_KEY}`);
});

view raw JSON →