{"id":16903,"library":"simple-koa-shopify-auth","title":"Koa Shopify Authentication Middleware","description":"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.","status":"deprecated","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/TheSecurityDev/simple-koa-shopify-auth","tags":["javascript","shopify","koa","middleware","auth","typescript"],"install":[{"cmd":"npm install simple-koa-shopify-auth","lang":"bash","label":"npm"},{"cmd":"yarn add simple-koa-shopify-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-koa-shopify-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the Shopify Admin API; only v5.x.x is supported.","package":"@shopify/shopify-api","optional":false}],"imports":[{"note":"Unlike the official Shopify library it replaces, `createShopifyAuth` is a named export, not a default export. Ensure you use destructuring.","wrong":"import createShopifyAuth from 'simple-koa-shopify-auth';","symbol":"createShopifyAuth","correct":"import { createShopifyAuth } from 'simple-koa-shopify-auth';"},{"note":"This library primarily targets ES Modules (ESM) environments. While CommonJS might work via transpilation, direct `require` is not the recommended or tested import method.","wrong":"const { verifyRequest } = require('simple-koa-shopify-auth');","symbol":"verifyRequest","correct":"import { verifyRequest } from 'simple-koa-shopify-auth';"},{"note":"The library ships with TypeScript types. Import types explicitly for type checking.","symbol":"AuthOptions","correct":"import type { AuthOptions } from 'simple-koa-shopify-auth';"}],"quickstart":{"code":"import Koa from 'koa';\nimport Router from '@koa/router';\nimport dotenv from 'dotenv';\nimport { createShopifyAuth, verifyRequest } from 'simple-koa-shopify-auth';\nimport '@shopify/shopify-api/adapters/node'; // Must be imported before initializing Shopify API\nimport { shopifyApi, LATEST_API_VERSION } from '@shopify/shopify-api';\n\ndotenv.config();\n\nconst app = new Koa();\nconst router = new Router();\n\nconst { SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES, HOST } = process.env;\n\nif (!SHOPIFY_API_KEY || !SHOPIFY_API_SECRET || !SCOPES || !HOST) {\n  throw new Error('Missing Shopify API environment variables. Please check your .env file.');\n}\n\nconst shopify = shopifyApi({\n  apiKey: SHOPIFY_API_KEY,\n  apiSecretKey: SHOPIFY_API_SECRET,\n  scopes: SCOPES.split(','),\n  hostName: HOST.replace(/https?:\\/\\//, ''),\n  apiVersion: LATEST_API_VERSION,\n  is</div>Online: true // crucial for online sessions with simple-koa-shopify-auth\n});\n\n// Register authentication routes\nrouter.get('/auth', createShopifyAuth({\n  async afterAuth(ctx) {\n    const { shop, accessToken } = ctx.state.shopify;\n    console.log(`Authenticated shop: ${shop} with access token: ${accessToken}`);\n    // Redirect to your app's main page or dashboard\n    ctx.redirect(`https://${shop}/admin/apps/${shopify.config.apiKey}`);\n  }\n}));\n\n// Middleware to verify requests for authenticated routes\nconst verifyPageRequest = verifyRequest();\nconst verifyApiRequest = verifyRequest({ returnHeader: true });\n\n// Example protected route for app pages\nrouter.get('/', verifyPageRequest, async (ctx) => {\n  ctx.body = 'Welcome to your Shopify App!';\n});\n\n// Example protected route for API endpoints\nrouter.get('/api/data', verifyApiRequest, async (ctx) => {\n  const { shop, accessToken } = ctx.state.shopify;\n  ctx.body = { message: `Data for ${shop}`, token: accessToken };\n});\n\napp.use(shopify.validateAuthenticatedSession()); // Necessary for session management with shopify-api v5\napp.use(router.routes()).use(router.allowedMethods());\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Server running on port ${PORT}`);\n  console.log(`Shopify API Key: ${SHOPIFY_API_KEY}`);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Update client-side logic that handles authentication failures to expect and properly respond to HTTP 401 status codes instead of 403.","message":"The `verifyRequest` middleware now returns a `401 Unauthorized` status code for invalid sessions, instead of the `403 Forbidden` returned by the original `@shopify/koa-shopify-auth` library. Client-side handling must be updated accordingly.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"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.","message":"This package is officially considered DEPRECATED by its maintainer. Shopify's own authentication mechanisms (like token exchange) are evolving, which will make this library unnecessary in the future.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"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`.","message":"This library only supports `@shopify/shopify-api` v5. There are no plans to support v6+ currently, which means upgrading your `@shopify/shopify-api` dependency beyond v5 will break `simple-koa-shopify-auth`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to version 2.1.4 or higher to avoid critical bugs.","message":"Versions 2.1.0 through 2.1.3 of `simple-koa-shopify-auth` are known to be broken and should not be used.","severity":"gotcha","affected_versions":"2.1.0 - 2.1.3"},{"fix":"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.","message":"As of v3.0.0, the `verifyRequest` middleware attempts to use the Shopify token exchange API to get a new online session if the current one is invalid. This changes the authentication flow for online sessions.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"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`.","cause":"The `simple-koa-shopify-auth` middleware (or `@shopify/shopify-api`'s `validateAuthenticatedSession`) was not correctly applied or executed before accessing `ctx.state.shopify`.","error":"TypeError: Cannot destructure property 'shopify' of 'ctx.state' as it is undefined."},{"fix":"Create a `.env` file in your project root with the necessary variables and ensure `dotenv.config();` is called at the start of your application.","cause":"Required environment variables (SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES, HOST) are not set or loaded.","error":"Error: Missing Shopify API environment variables. Please check your .env file."},{"fix":"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`).","cause":"`simple-koa-shopify-auth` is an ES Module (ESM) but is being imported using CommonJS `require()` syntax.","error":"ERR_REQUIRE_ESM: require() of ES Module [path] from [path] not supported. Instead, change the require of [path] to a dynamic import() or top-level await."},{"fix":"Install the correct version: `npm uninstall @shopify/shopify-api && npm install @shopify/shopify-api@^5.3.0`.","cause":"Your project's `@shopify/shopify-api` dependency is not version 5.x.x, which is a strict requirement for `simple-koa-shopify-auth`.","error":"Error: Shopify API v5 is required but current version is not 5.x.x."}],"ecosystem":"npm","meta_description":null}