Notice
This project is an unoffical fork of the deprecated @shopify/shopify-express
shopify-express
A small set of abstractions that will help you quickly build an Express.js app that consumes the Shopify API.
Installation
npm install --save shopify-express
Example
const express = ;const shopifyExpress = ;const session = ; const app = ; const SHOPIFY_APP_KEY SHOPIFY_APP_HOST SHOPIFY_APP_SECRET NODE_ENV = processenv; // session is necessary for api proxy and auth verificationapp; const routes withShop = ; // mounts '/auth' and '/api' off of '/shopify'app; // shields myAppMiddleware from being accessed without sessionapp
Shopify routes
const routes = ; app;
Provides mountable routes for authentication and API proxying. The authentication endpoint also handles shop session storage using a configurable storage strategy (defaults to SQLite).
/auth/shopify
Serves a login endpoint so merchants can access your app with a shop session.
/api
Proxies requests to the api for the currently logged in shop. Useful to securely use api endpoints from a client application without having to worry about CORS.
shopStore
shopifyExpress
's config takes an optional shopStore
key, You can use this to define a strategy for how the module will store your persistent data for user sessions.
Strategies
By default the package comes with MemoryStrategy
, RedisStrategy
, and SqliteStrategy
. If none are specified, the default is MemoryStrategy
.
MemoryStrategy
Simple javascript object based memory store for development purposes. Do not use this in production!
const shopifyExpress = ;const MemoryStrategy = ; const shopify = ;
RedisStrategy
Uses redis under the hood, so you can pass it any configuration that's valid for the library.
const shopifyExpress = ;const RedisStrategy = ; const redisConfig = // your config here; const shopify = ;
SQLStrategy
Uses knex under the hood, so you can pass it any configuration that's valid for the library. By default it uses sqlite3
so you'll need to run yarn add sqlite3
to use it. Knex also supports postgreSQL
and mySQL
.
const shopifyExpress = ;const SQLStrategy = ; // uses sqlite3 if no settings are specifiedconst knexConfig = // your config here; const shopify = ;
SQLStrategy expects a table named shops
with a primary key id
, and string
fields for shopify_domain
and access_token
. It's recommended you index shopify_domain
since it is used to look up tokens.
If you do not have a table already created for your store, you can generate one with new SQLStrategy(myConfig).initialize()
. This returns a promise so you can finish setting up your app after it if you like, but we suggest you make a separate db initialization script, or keep track of your schema yourself.
Custom Strategy
shopifyExpress
accepts any javascript class matching the following interface:
// shop refers to the shop's domain name : Promise<accessToken: string> // shop refers to the shop's domain name : Promise<accessToken: string>
Helper middleware
const {middleware: {withShop, withWebhook}} = shopifyExpress(config);
withShop
app.use('/someProtectedPath', withShop({authBaseUrl: '/shopify'}), someHandler);
Express middleware that validates the presence of your shop session. The parameter you pass to it should match the base URL for where you've mounted the shopify routes.
withWebhook
app.use('/someProtectedPath', withWebhook, someHandler);
Express middleware that validates the presence of a valid HMAC signature to allow webhook requests from shopify to your app.
Example app
You can look at shopify-node-app for a complete working example.
Gotchas
Install route
For the moment the app expects you to mount your install route at /install
. See shopify-node-app for details.
Express Session
This library expects express-session or a compatible library to be installed and set up for much of it's functionality. Api Proxy and auth verification functions won't work without something putting a session
key on request
.
It is possible to use auth without a session key on your request, but not recommended.
Body Parser
This library handles body parsing on it's own for webhooks. If you're using webhooks you should make sure to follow express best-practices by only adding your body parsing middleware to specific routes that need it.
Good
app; app; app;
Bad
app; app; app; app;
Contributing
Contributions are welcome. Please refer to the contributing guide for more details.