Getting started

Supacharger is a reusable Next.js and Supabase application core. It includes authentication, account management, internationalisation, a subscription billing foundation, email integration, and a CLI-managed update boundary.

Requirements

• Node.js 22 or later
• npm 11 as declared by the core package
• Docker for the local Supabase stack
• Supabase CLI
• Stripe CLI when testing billing webhooks

Install

npm install
cp .env.local.example .env.local
npx supabase start
npm run dev

Fill every required value in .env.local; placeholders and blank values are rejected. Keep secret/service-role Supabase keys and all Stripe secrets server-only.

Apply database migrations

Link the intended Supabase project, review pending migrations, then apply them:

npm run supabase:link
npx supabase db push --linked --dry-run
npm run migration:up

The internal billing projection is stored in app; browser reads use narrowly scoped api functions and Stripe ingestion uses service-only api_edge functions. Grants and row-level security are explicit. Regenerate database types after a schema change.

Configure the hosted application

After the application and migrations work against local Supabase, follow the hosted setup wizard. It covers the linked Supabase project, Vercel environment variables, first production deployment, Auth URLs and policy, SMTP, email templates, and end-to-end production verification in dependency order.

Do not assume that supabase/config.toml, local email templates, or an authenticated MCP connection configured the hosted project. Each hosted Supabase environment has its own Dashboard settings, secrets, hooks, providers, templates, and rate limits.

Configure billing

The current supported Stripe tuple is Node SDK 22.5.0 and API 2026-07-29.dahlia. Follow the complete Stripe setup before enabling subscription enforcement.

Required server environment variables are:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_EVENT_PROCESSOR_SECRET=<long-random-value>
STRIPE_RECONCILIATION_SECRET=<different-long-random-value>

The hosted Checkout integration does not use Stripe.js, so it does not require a browser publishable key. It uses billing accounts, multiple Subscriptions and Items, Dynamic Payment Methods, flexible billing mode, and a local entitlement projection; see the billing guide before adding product access rules.

Core updates

The Supacharger CLI preserves developer-owned configuration, localisation messages, and project styling. When a core update changes dependencies, the CLI installs them. When it contains Supabase migrations, the CLI runs a linked-project dry run and asks separately before applying them. It does not advance the core lock when migration application is declined.

Read the CLI documentation and Anatomy ownership guide before modifying protected core files.

Attribution

Parts of Supacharger's original billing implementation were inspired by next-supabase-stripe-starter and Vercel's archived nextjs-subscription-payments example. Retained third-party notices belong in the source repository's formal notice file; copied product branding and obsolete upstream setup instructions are not part of the Supacharger documentation.