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.
npm install simple-koa-shopify-authVerified import paths — ran on the pinned version, not inferred.
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.
Update client-side logic that handles authentication failures to expect and properly respond to HTTP 401 status codes instead of 403.
For new projects, consider adopting Shopify's latest authentication flows directly. For existing projects, understand that future Shopify API changes may break this library without updates.
Ensure your project explicitly uses `@shopify/shopify-api@^5.3.0`. Do not upgrade `@shopify/shopify-api` to v6 or newer if you rely on `simple-koa-shopify-auth`.
Upgrade to version 2.1.4 or higher to avoid critical bugs.
Review the Shopify token exchange API documentation to understand the new flow. Ensure your application handles potential redirects or API responses from token exchange gracefully.
Ensure `app.use(shopify.validateAuthenticatedSession());` and the `createShopifyAuth` middleware are correctly registered and executed in the Koa application's middleware stack. The `shopify` object from `@shopify/shopify-api` must also be correctly initialized with `isOnline: true`.
Create a `.env` file in your project root with the necessary variables and ensure `dotenv.config();` is called at the start of your application.
Change your import statements from `const { createShopifyAuth } = require('simple-koa-shopify-auth');` to `import { createShopifyAuth } from 'simple-koa-shopify-auth';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).Install the correct version: `npm uninstall @shopify/shopify-api && npm install @shopify/shopify-api@^5.3.0`.