Getting started

stripekit turns your Stripe catalog into a file in your repo and reconciles your own Stripe account to match it — then drops correct billing code into your app. No hosted service, no merchant of record, no revenue share.

Requirements

• Node.js 20+
• A Stripe test secret key (sk_test_…) — create one in the Stripe Dashboard if you don't have it yet
• For the full scaffold path: a Next.js App Router project (other stacks can still use plan/push/pull with a hand-written config)

Fastest path: init (Next.js)

From your app root:

npx stripekit init

init will:

1. Detect the framework and auth setup (Clerk / Auth.js / better-auth / none)
2. Ask for your sk_test_… key (or reuse one already in .env.local)
3. Write stripe.config.ts plus billing routes and sync helpers
4. Optionally run the first push so products, prices, webhook, and portal exist in test mode

Then locally:

npx stripekit plan    # preview — never mutates
npx stripekit push    # apply if you skipped it during init
npx stripekit dev     # forward webhooks (wraps `stripe listen`)

Open checkout with a test card (4242…) and confirm customer state syncs via the webhook.

Alternative: config-only (any stack)

1. Install

npm install -D stripekit
# or: pnpm add -D stripekit / yarn add -D stripekit

2. Create a config

Create stripe.config.ts in your project root:

import { defineConfig } from 'stripekit'

export default defineConfig({
  products: {
    pro: {
      name: 'Pro',
      prices: {
        monthly: { amount: 2000, currency: 'usd', interval: 'month' },
        yearly: { amount: 19200, currency: 'usd', interval: 'year' },
      },
      features: { seats: 5, projects: 'unlimited' },
    },
  },
  portal: { cancellations: true, planSwitching: true },
  webhooks: { path: '/api/stripe/webhook' },
})

Already have products in Stripe? Generate the config from your account instead:

npx stripekit pull

3. Point stripekit at your account

# .env.local
STRIPE_SECRET_KEY=sk_test_...

stripekit reads STRIPE_SECRET_KEY from your environment, then .env.local, then .env. The sk_test_/sk_live_ prefix decides which mode it targets.

4. Preview and apply

npx stripekit plan   # terraform-style diff — nothing is changed
npx stripekit push   # create/update products, prices, webhook, portal

plan prints exactly what push will do:

stripekit — reconciling test mode

  + product "pro" — Pro
  + price "pro_monthly" — 20.00 USD / month
  + price "pro_yearly" — 192.00 USD / year
  + customer portal configuration

Plan: 4 to create.

Run push again and you'll get No changes. — the reconciler is idempotent.

Promote to live

The same config targets both modes. When you're ready:

STRIPE_SECRET_KEY=sk_live_... npx stripekit push --live

Live mode asks for confirmation before touching anything (use --yes in CI).

Next steps

• How it works — immutability, tagging, and convergence
• vs other tools — tool vs platform vs merchant of record
• Generated code — what init drops into your repo
• Config reference — every field in stripe.config.ts