Registry / auth-security / simple-koa-shopify-auth

simple-koa-shopify-auth

JSON →
library3.0.0jsnpmunverified

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-auth
INSTALL
IMPORT
SIG · SIMPLE-KOA-SHOPIFY
S
simple-koa-shopify-auth
auth-securityjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createShopifyAuth
import { createShopifyAuth } from 'simple-koa-shopify-auth';
import createShopifyAuth from 'simple-koa-shopify-auth';
Unlike the official Shopify library it replaces, `createShopifyAuth` is a named export, not a default export. Ensure you use destructuring.
verifyRequest
import { verifyRequest } from 'simple-koa-shopify-auth';
const { verifyRequest } = require('simple-koa-shopify-auth');
This library primarily targets ES Modules (ESM) environments. While CommonJS might work via transpilation, direct `require` is not the recommended or tested import method.
AuthOptions
import type { AuthOptions } from 'simple-koa-shopify-auth';
The library ships with TypeScript types. Import types explicitly for type checking.

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}`); });
Debug
Known issues
breakingThe `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.
fix
Update client-side logic that handles authentication failures to expect and properly respond to HTTP 401 status codes instead of 403.
affects: >=2.0.0
deprecatedThis 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.
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.
affects: >=2.0.0
breakingThis 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`.
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`.
affects: >=2.0.0
gotchaVersions 2.1.0 through 2.1.3 of `simple-koa-shopify-auth` are known to be broken and should not be used.
fix
Upgrade to version 2.1.4 or higher to avoid critical bugs.
affects: 2.1.0 - 2.1.3
breakingAs 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.
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.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: Cannot destructure property 'shopify' of 'ctx.state' as it is undefined.
The `simple-koa-shopify-auth` middleware (or `@shopify/shopify-api`'s `validateAuthenticatedSession`) was not correctly applied or executed before accessing `ctx.state.shopify`.
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`.
Error: Missing Shopify API environment variables. Please check your .env file.
Required environment variables (SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES, HOST) are not set or loaded.
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.
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.
`simple-koa-shopify-auth` is an ES Module (ESM) but is being imported using CommonJS `require()` syntax.
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`).
Error: Shopify API v5 is required but current version is not 5.x.x.
Your project's `@shopify/shopify-api` dependency is not version 5.x.x, which is a strict requirement for `simple-koa-shopify-auth`.
fix
Install the correct version: `npm uninstall @shopify/shopify-api && npm install @shopify/shopify-api@^5.3.0`.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
@shopify/shopify-apirequiredRequired for interacting with the Shopify Admin API; only v5.x.x is supported.
Agent activity
15 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
simple-koa-shopify-auth — npm install simple-koa-shopify-auth · libregistry