coal
coal

Migrating from coal-react to coal-payments

coal-react (v0.4.1) was the original npm package: React checkout components, a Next.js manifest helper, and a catalog publisher. coal-payments (v0.5.0) is the rename — it keeps every existing export and adds the merchant integration surfaces (withCoalPaywall, Express / Hono / Fastify middleware).

coal-react@0.4.1 keeps working unchanged. Migrate on your own schedule.

What changed

Old (coal-react@0.4.1)New (coal-payments@0.5.0)
coal-react (root) → React componentscoal-payments/react
coal-react/server → catalog publishercoal-payments/server (unchanged)
coal-react/next → manifest routescoal-payments/next (manifest routes + withCoalPaywall)
—coal-payments (root) → withCoalPaywall (framework-agnostic)
—coal-payments/express → Express middleware
—coal-payments/hono → Hono middleware
—coal-payments/fastify → Fastify plugin

Nothing was removed. Every existing import has a 1:1 successor.

Migration recipes

1. React components

ts
1// before
2import { CoalProvider, CoalProducts, CoalCheckoutButton } from 'coal-react';
3

4// after
5import { CoalProvider, CoalProducts, CoalCheckoutButton } from 'coal-payments/react';

2. Catalog publisher

ts
1// before
2import { publishCoalCatalog } from 'coal-react/server';
3

4// after
5import { publishCoalCatalog } from 'coal-payments/server';

3. Next.js manifest routes

ts
1// before
2import { createAgentCardRoute } from 'coal-react/next';
3

4// after
5import { createAgentCardRoute } from 'coal-payments/next';

4. New: API gating

The reason to upgrade. Adds the merchant integration surface that did not exist in coal-react:

ts
1import { withCoalPaywall } from 'coal-payments/next';
2

3export const GET = withCoalPaywall(
4    { paywallId: 'pw_xxx' },
5    async (req) => Response.json(await search(req)),
6);

See Integration → SDK for the full reference.

Find-and-replace

A blanket regex works for most projects:

bash
1# replace import sources
2grep -rln "from 'coal-react'" src | xargs sed -i '' "s/from 'coal-react'/from 'coal-payments\/react'/g"
3grep -rln "from 'coal-react\/server'" src | xargs sed -i '' "s/from 'coal-react\/server'/from 'coal-payments\/server'/g"
4grep -rln "from 'coal-react\/next'" src | xargs sed -i '' "s/from 'coal-react\/next'/from 'coal-payments\/next'/g"

Then:

bash
1npm uninstall coal-react
2npm install coal-payments

Why not just keep coal-react?

coal-react is React-only by name. The withCoalPaywall middleware is framework-agnostic and ships per-runtime adapters for Express, Hono, Fastify — none of which belong under a react prefix. The rename is a one-time event so future readers do not have to memorize a misnomer.

coal-react will keep receiving security fixes for at least 6 months. New features (proxy mode helpers, OpenAPI imports, batch settle) land in coal-payments only.