Add a paywall to an Express and React app
To add a paywall to an Express and React app, create a monemee-node instance whose getRef returns the logged-in user ID, mount webhook() before express.json() and routes() after your login, protect paid routes with requireAccess() and wrap paid UI in <AccessGate>. npx monemee init does most of this for you.
Prerequisites
- An Express server with a login (sessions, Passport, a token check) and a React frontend.
- Node.js 18.17 or newer.
- A Monemee account. The setup creates the product and a test secret.
Steps
1. Run the setup
npx monemee init
init detects Express and React (also in server/ and client/ subfolders), writes MONEMEE_APP_SECRET and MONEMEE_PRODUCT_ID to the server’s .env, adds .env to .gitignore, patches your server file and creates src/components/MonemeeUpgrade.jsx in the React app. Check the result against the next steps.
By hand: npm install monemee-node on the server, npm install monemee-react in the frontend, and a test secret from the dashboard under License keys > App connection.
2. Load the .env file
monemee-node reads process.env. It does not load .env itself:
node --env-file=.env server.js # Node.js 20.6 or newer
or require('dotenv').config() at the top of the server file.
3. Mount Monemee in the right order
// server.js
const express = require('express');
const session = require('express-session');
const createMonemee = require('monemee-node');
const app = express();
const monemee = createMonemee({
getRef: (req) => req.user?.id, // stable user ID from your login
loginUrl: (back) => `/login?next=${encodeURIComponent(back)}`, // buyers who return logged out
successPath: '/pro' // where buyers land after paying
});
app.use(monemee.webhook()); // 1. before express.json(): needs the raw body
app.use(express.json()); // 2. body parser
app.use(session({ /* ... */ })); // 3. your login, sets req.user
app.use(monemee.routes()); // 4. /monemee/buy, /return, /access, /unlock, /test-buy
app.get('/api/pro', monemee.requireAccess(), (req, res) => {
res.json({ plan: req.monemee.plan });
});
app.listen(3001);
getRef must return the same stable ID every time, never an email address. requireAccess() puts the access result on req.monemee.
4. Add the paywall in React
// src/Pro.jsx
import { MonemeeProvider, AccessGate, BuyButton, LicenseForm, useAccess } from 'monemee-react';
function Offer() {
const { mode, testBuy } = useAccess();
return (
<div>
<BuyButton>Unlock Pro</BuyButton>
{mode === 'test' && <button type="button" onClick={() => testBuy()}>Test purchase</button>}
<details>
<summary>Already bought? Enter your license key</summary>
<LicenseForm />
</details>
</div>
);
}
export default function Pro() {
return (
<MonemeeProvider>
<AccessGate loading={<p>Loading...</p>} fallback={<Offer />}>
<ProFeature />
</AccessGate>
</MonemeeProvider>
);
}
The provider calls /monemee/access on your server with cookies included. If the frontend dev server runs on another port, proxy /monemee and /api to Express. With Vite:
// vite.config.js
export default { server: { proxy: { '/api': 'http://localhost:3001', '/monemee': 'http://localhost:3001' } } };
5. Token login (Firebase, Supabase, Auth0)
If the browser sends a login token instead of a cookie, verify it in getRef on the server and pass it from the provider:
<MonemeeProvider getHeaders={async () => ({ Authorization: `Bearer ${await auth.currentUser.getIdToken()}` })}>
Set the return URL to a page of your app (for example /pro) instead of /monemee/return. The provider redeems ?monemee_claim=... on load and removes it from the address bar.
6. Test and go live
npx monemee test-buy # free test purchase while logged in
npx monemee live --url https://your-app.com # return URL, live secret, webhook
Put the values that live prints into the production environment. MONEMEE_WEBHOOK_SECRET enables /monemee/webhook, so refunds take effect immediately instead of after the five-minute cache.
How it works
BuyButton asks /monemee/buy-url for the checkout link with the logged-in user attached (falling back to the /monemee/buy redirect). After payment, Monemee sends the buyer to /monemee/return?monemee_claim=.... The server redeems the one-time token with the app secret, binds the license to the user and redirects to successPath. requireAccess() and /monemee/access then report access until a refund or expiry. The app secret stays on the server; the React package only talks to your routes.
FAQ
Why must monemee.webhook() come before express.json()?
Webhook signatures are computed over the raw request body. Once express.json() has parsed the body, the original bytes are gone and the signature cannot be verified, so the webhook middleware has to run first.
What does requireAccess() send when the user has not paid?
401 with error login_required when getRef returns nothing, 402 with error payment_required and a buy_url when there is no valid license, and 503 when Monemee cannot be reached. It never grants access on errors.
Does npx monemee init change my server code?
Yes, if it finds exactly one express() call and a first route after it. It adds the Monemee instance, app.use(monemee.webhook()) right after express() and app.use(monemee.routes()) before your first route. Otherwise it prints the snippet for you to paste.
Next steps
- Web apps reference
- Runnable Express and React template
- Test the purchase flow without paying
- All guides
Last updated: