Project Setup and Your First Payment

Configure your product, sign in, complete a sandbox purchase, and verify entitlements. Keep Next.js and Supabase; start with one pricing mode and one payment provider before enabling additional providers.

1. Create configuration

Install dependencies, then run the wizard from the project root.

pnpm install
pnpm setup:project

Use pnpm.cmd in Windows PowerShell when needed. The wizard asks for your product name, app ID, site URL, pricing mode, providers, and optional secondary-site locale. After confirmation it creates .env.local. Enter secrets into that file in your editor; the wizard never collects them through terminal prompts.

If .env.local exists, the wizard exits without changing it. Edit the existing file and run pnpm setup:check. Do not delete existing credentials just to rerun the wizard. Once users or orders exist, do not casually change NEXT_PUBLIC_APP_ID or the pricing mode.

For automation, provide non-sensitive settings explicitly.

pnpm setup:project --name "My SaaS" --app-id my-saas --mode credits --providers paypal --yes

Optional flags include --site-url https://your-domain.example and --locale cn. Omit locale for the main site; use cn for a CNY secondary site and verify the Alipay sandbox gateway before testing. Run pnpm setup:project --help for all options. The wizard does not create remote databases, register payment products, or deploy a website.

2. Know where to customize

The name setting does not replace all blog, documentation, marketing, or email-sender text. Review sender configuration and notification templates using the email guide. Restart local development after environment changes. Production NEXT_PUBLIC_* values are compiled into the frontend and require rebuilding and redeploying. Editing .env.local does not update deployment-platform settings.

Configure only the active mode

The checker reads actual plan keys from config/payment.ts, rather than assuming a fixed number of offers. Every purchasable offer needs its mapping. To offer fewer plans, first adjust visible offers using the payment configuration guide. Do not rename the existing fixed keys. Provider amounts, currencies, and intervals must match the application configuration.

When unlimited subscriptions enable trials, the current PayPal / Creem returning-customer flow uses each provider's SUB_NOTRIAL_PRO_MONTHLY mapping. Missing values trigger a warning. Follow the provider guide and verify that returning customers cannot receive another trial. Alipay does not support a free trial here; its subscription entitlements come from a one-time payment, not automatic renewal.

3. Check configuration

pnpm setup:check
pnpm setup:check --production

The default follows Next.js development precedence: existing process variables, .env.development.local, .env.local, .env.development, then .env. Production checks use .env.production.local, .env.local, .env.production, then .env. A local production check does not verify the environment configured on your hosting platform.

Check secondary-site overrides using the same style of dotenv loading as the project's dev:locale script.

pnpm exec dotenv -e .env.local.locale -- pnpm setup:check

Add --json for machine-readable output. Exit code 0 means local required-value and format checks passed, 1 means configuration errors, and 2 means the command could not run. Warnings do not fail the check but should be reviewed before launch. The existing build precheck is unchanged; run the full checker explicitly.

Reports contain variable names, remediation, and documentation paths, never credential values. Empty fields and examples such as xxx or your_... do not pass. Only enabled providers and the selected mode are required. The checker also flags disabled payment buttons, maintenance mode, and accidental server secrets in the public Supabase key setting.

Passing local checks does not prove that migrations ran, keys are valid, OAuth is configured, webhooks are reachable, or payments work. Complete the following acceptance steps.

4. Initialize the database and sign in

1. Follow the source repository's DATABASE_SETUP.md to connect Supabase, review migrations, and deploy them. The wizard never guesses migration changes or resets a database.
2. Keep NEXT_PUBLIC_APP_ID consistent with an existing project. Use a unique identifier for a new project.
3. Configure Supabase Site URL and allowed redirects. Enable email login or Google / GitHub OAuth as needed, and configure email delivery.
4. Run pnpm dev:noPay, then register, verify email if enabled, sign in, reload, and sign out. The existing pnpm dev ngrok integration remains available but requires local machine configuration.
5. Check that the user profile works and a second account cannot access the first account's billing, credits, or subscriptions.

5. Complete a sandbox purchase

1. Use the selected provider's test environment or sandbox accounts. The checker never charges money and cannot determine whether a product ID belongs to test or live mode.
2. Match configured amounts, currencies, and intervals against provider products. Stripe uses Price IDs, Creem uses Product IDs, and PayPal subscriptions use Plan IDs.
3. Expose the local app through a public HTTPS tunnel and register https://your-public-host/api/webhooks/provider, such as /api/webhooks/stripe. Plain localhost is not reachable by provider callbacks. Check the site URL and auth redirect allowlist when external return URLs are needed.
4. Set NEXT_PUBLIC_PAYMENT_CTA_DISABLED=false, disable maintenance mode, and complete a sandbox checkout from /pricing.
5. Check webhook delivery in the provider dashboard and order/entitlement changes in the app. A browser success redirect alone is not proof of payment processing.
6. Redeliver the same webhook and verify that credits or entitlements are not granted twice.

Verify the selected mode

After the first purchase, follow provider guides for refunds, renewals, retries, and cancellation. Existing Creem automated checks run with pnpm test:creem-webhook; they do not replace a complete sandbox transaction.

6. Prepare to launch

Configure the deployed site URL and all settings for the selected payment environment. Update auth redirect allowlists, webhook URLs, and signing secrets, then rebuild and deploy. Review marketing copy, logos, legal text, email sender, administrator allowlist, and contact email.

Recheck login and payment callbacks in the deployed environment. Keep useful error logs and troubleshooting instructions without recording passwords, API keys, or complete sensitive payment payloads.