Commands and Environment
Reference the starter's npm commands, configuration groups, feature flags, and deployment precedence.
The starter is locked with npm. Use Node.js >=24.0.1, npm >=11.3.0, and the committed package-lock.json.
Setup and runtime
| Command | Behavior |
|---|---|
npm ci | Install exactly the locked dependency graph |
npm run setup | Run the interactive local environment, database, auth, and optional payment setup |
npm run dev | Start the Next.js development server |
npm run build | Create the production Next.js build |
npm run start | Serve an existing production build |
docker compose up -d | Start PostgreSQL 16 and Mailpit locally |
docker compose down | Stop local services without deleting the named database volume |
If local port 5432 is already occupied, pass a host-port override to setup:
VIBEANY_POSTGRES_PORT=55432 npm run setupValidation and tests
| Command | Behavior |
|---|---|
npm run lint | Lint source files under src/ |
npm run typecheck:all | Type-check the full repository, including tests |
npm run validate | Run the current docs validator, i18n validation, and source lint; it is not a full release gate |
npm run preflight | Check deployment environment, enabled capabilities, DB reachability, migration blockers, and TypeScript |
npm run --silent preflight -- --json | Emit the redacted preflight report as JSON |
npm run architecture:check | Run automated dependency and repository boundary tests |
npm test | Start Vitest in watch mode |
npm run test:run | Run all Vitest tests once |
npm run test:unit | Run tests under tests/unit once |
npm run test:coverage | Run tests with the configured coverage thresholds |
npm run e2e | Run the Playwright suite |
npm run e2e:smoke | Run the smoke E2E spec |
npm run e2e:auth | Run the authentication E2E spec |
PostgreSQL integration commands require explicitly configured disposable test databases. The suites reject unsafe targets where implemented.
Database and product commands
| Command | Behavior |
|---|---|
npm run db:generate | Generate SQL migrations and Drizzle metadata from schema changes |
npm run db:migrate | Apply committed SQL files through the transactional app_migrations runner |
npm run db:push | Always fail; schema push is forbidden |
npm run db:studio | Open Drizzle Studio for the configured database |
npm run rebrand:validate | Check for remaining starter branding |
npm run i18n:validate | Validate locale structure and required messages |
npm run i18n:coverage | Report translation coverage |
npm run starter:check | Run starter consistency checks after significant customization or upgrade |
npm run payments:refund:assess -- ... | Produce a read-only refund-policy assessment; it does not contact a provider or change data |
npm run deploy:vercel | Run the strict payment-off Vercel baseline preflight, migrations, and production deploy |
The public operating path only requires the buyer-facing commands listed here.
Environment file precedence
.env.exampleis the canonical public inventory of supported starter variables.- Local scripts load
.env.localunless an authoritative deployment environment is active. npm run deploy:verceldefaults to.env.production.local, removes inherited application values, and prevents child commands from falling back to.env.local.- Vercel environment changes affect a deployment only after a new build.
- Any
NEXT_PUBLIC_*value is exposed to browser code. Never place a credential in one.
Core application
| Variable | Purpose |
|---|---|
DATABASE_URL | PostgreSQL connection used by Better Auth, Drizzle, and application persistence |
BETTER_AUTH_SECRET | Session and authentication secret; required by preflight |
BETTER_AUTH_URL | Canonical Better Auth origin; leave unset for variable-port local development, set in production |
NEXT_PUBLIC_SITE_URL | Public site origin used by metadata and preflight |
NEXT_PUBLIC_APP_URL | Application origin and production auth fallback |
NEXT_PUBLIC_BRAND_NAME | Optional deployment-specific brand name override |
NEXT_PUBLIC_BRAND_WORDMARK_ACCENT | Optional wordmark accent override |
ADMIN_EMAILS | Comma-separated administrator email allowlist |
Authentication, email, and abuse controls
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_ENABLE_EMAIL_AUTH | Enable Better Auth email/password UI and delivery |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Complete Google OAuth server credential pair |
NEXT_PUBLIC_GOOGLE_CLIENT_ID | Browser-visible Google client ID used by One Tap detection |
NEXT_PUBLIC_ENABLE_ONE_TAP | Enable Google One Tap when the full Google configuration exists |
RESEND_API_KEY, RESEND_FROM_EMAIL | Resend delivery credentials and verified sender |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS | Complete SMTP fallback configuration |
NEXT_PUBLIC_TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY | Complete Turnstile key pair for signup verification |
Production must enable at least one complete authentication method. The supported Vercel baseline uses email/password and Resend even though the runtime also supports Google OAuth and SMTP.
Payments
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_ENABLE_PAYMENTS | Gate payment UI and payment endpoints |
PAYMENTS_PROVIDER | Select exactly one active provider: stripe or creem |
CRON_SECRET | Authenticate scheduled subscription-credit grants |
PAYMENTS_SUBSCRIPTION_REFUND_MAX_USAGE_PERCENT | Exclusive manual-review usage threshold; 5 means exactly 5% is not eligible |
STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | Stripe server and browser keys |
STRIPE_WEBHOOK_SECRET | Stripe signing secret for /api/payments/webhook |
STRIPE_PRICE_STARTER_*, STRIPE_PRICE_PRO_* | Canonical monthly and annual subscription Price IDs |
STRIPE_PRICE_CREDITS_SMALL, STRIPE_PRICE_CREDITS_MEDIUM, STRIPE_PRICE_CREDITS_LARGE | Visible one-time credit-pack Price IDs |
STRIPE_PRICE_LANDING_BASIC, STRIPE_PRICE_LANDING_PRO | Optional one-time product Price IDs |
CREEM_API_KEY, CREEM_API_BASE | Creem credential and test/production API origin |
CREEM_WEBHOOK_SECRET, CREEM_SIGNATURE_HEADER | Creem signing configuration |
CREEM_PRODUCT_STARTER_*, CREEM_PRODUCT_PRO_* | Monthly and annual subscription Product IDs |
CREEM_PRODUCT_CREDITS_SMALL, CREEM_PRODUCT_CREDITS_MEDIUM, CREEM_PRODUCT_CREDITS_LARGE | Visible credit-pack Product IDs |
CREEM_PRODUCT_LANDING_BASIC, CREEM_PRODUCT_LANDING_PRO | Optional one-time Product IDs |
When payments are enabled, preflight validates only the selected provider but requires its complete built-in visible catalog. STRIPE_PRICE_STARTER and STRIPE_PRICE_PRO remain legacy monthly aliases; new configuration should use the explicit _MONTHLY variables.
Changing PAYMENTS_PROVIDER changes new checkout and webhook traffic. Existing subscription cancellation and portal operations use the provider stored on the subscription. Changing the flag does not migrate live subscriptions.
Storage and AI image generation
| Variable | Purpose |
|---|---|
STORAGE_PROVIDER | r2, s3, or minio |
S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET_NAME | Required S3-compatible credential set |
S3_REGION | Optional region; runtime default is auto |
S3_PUBLIC_URL | Optional public or CDN base URL |
NEXT_PUBLIC_ENABLE_IMAGE_GENERATION | Gate the image page, navigation, and API |
IMAGE_PROVIDER | Optional explicit selector: fal, modelscope, or dashscope |
FAL_KEY, MODELSCOPE_API_KEY, DASHSCOPE_API_KEY | Provider credentials |
Without an explicit image selector, runtime priority is Fal, ModelScope, then DashScope among configured providers.
Presentation, legal, analytics, and development
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_TERMS_VERSION, NEXT_PUBLIC_PRIVACY_VERSION | Legal document versions shown in signup flows |
NEXT_PUBLIC_GA_ID, NEXT_PUBLIC_CLARITY_ID | Optional analytics identifiers |
LOG_LEVEL | debug, info, warn, or error |
NEXT_PUBLIC_SHOW_DEV_WARNINGS | Toggle local development warnings |
NEXT_PUBLIC_SHOW_PURCHASE_DEBUG, NEXT_PUBLIC_ENABLE_SELF_GRANT, ALLOW_MANUAL_GRANT | Reserved or presentation-facing development variables; not server authorization controls |
Keep diagnostic UI disabled in production, but do not treat these variables as an authorization boundary. The current admin credit-adjustment route relies on server authentication plus ADMIN_EMAILS; it does not consult ALLOW_MANUAL_GRANT. The old Supabase browser variables are not part of the active Better Auth setup and should not be documented as required configuration.
See Deploy to Vercel for the stricter baseline environment contract.