# Getting started

> <FreeTrialWelcome />

# 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

```bash
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:

```bash
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](./guides/setup-wizard.md). 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](./Billing/stripe.md) before enabling subscription enforcement.

Required server environment variables are:

```dotenv
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](./cli/index.md) and [Anatomy ownership guide](./Application%20Development/folderstructure.mdx) 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.