Configuration

Vibestrap separates configuration into three layers, each with a clear purpose. Knowing which layer to touch will save you a lot of time.

The three layers

Layer	File	What it controls
Brand & business config	`src/config/site.ts`	Product name, pricing, plans, providers active flag, social links — anything a buyer should change.
Secrets & runtime config	`.env.local` (validated by `src/env.ts`)	API keys, database URL, signing secrets — anything that varies per environment.
Customer-facing copy	`messages/en.json` + `messages/zh.json`	Every string the user sees. Bilingual; both files must have the same keys.

If you find yourself editing component source to change copy, stop — you should be editing messages/{en,zh}.json instead.

What `siteConfig` controls

The whole file is ~250 lines. Here are the load-bearing fields:

siteConfig.name            // brand name, used in <title> + emails + footer
siteConfig.url             // canonical URL — drives sitemap, OG, mail links
siteConfig.shortDescription // hero subtitle, OG image
siteConfig.product         // pricing card: standard / promo, price IDs per provider
siteConfig.payment.provider // 'stripe' | 'creem' | 'nowpayments'
siteConfig.customerService  // { enable, provider: 'crisp' | 'tawk' | … }
siteConfig.affiliate        // { enable, provider, internalCommissionPct }
siteConfig.newsletter       // { enable, provider: 'resend' | 'beehiiv' }
siteConfig.analytics        // { vercel, googleAnalytics, posthog, plausible, umami }
siteConfig.credits          // ledger config: registerGift, monthlyFree, …
siteConfig.demoPlans        // four-tier sample (one-time + monthly + yearly)
siteConfig.i18n             // locales + default locale
siteConfig.features         // feature flags (blog / newsletter / OAuth providers)

Every field has inline comments — read it once cover-to-cover, you’ll know what you can change without grep-ing the codebase.

What lives outside `siteConfig`

These have their own homes — by design.

Concern	Where
Env vars / secrets	`.env.local`, validated by `src/env.ts`
Database schema	`src/db/{auth,app,affiliate,ai,license}.schema.ts`
AI provider list / pricing	`src/ai/index.ts` + `src/ai/pricing.ts`
Marketing copy	`messages/{en,zh}.json`
Mail templates	`src/mail/templates/`
Theme tokens	`src/app/globals.css` (`@theme` block)
Sidebar nav for /docs	`src/config/docs-nav.ts`

Adding a new feature flag

Add to siteConfig.features:

features: { ..., enableMyFeature: true }

Reference in code:

import { siteConfig } from '@/config/site';
if (siteConfig.features.enableMyFeature) { ... }

That’s it — no extra plumbing.

Adding an env var

Add a Zod-validated entry in src/env.ts (server section if it’s secret; client section if it has the NEXT_PUBLIC_ prefix and is safe to ship to the browser).
If it’s a public var, add it to experimental__runtimeEnv too (Next.js requires this).
Document it in Env reference.
Use import { env } from '@/env' to read it — never process.env.X directly.

Best-practice checklist

✅ Brand changes happen in siteConfig and messages/. No component-source edits.
✅ Secrets only in .env.local. The .env.example documents the shape; the real .env.local is gitignored.
✅ When swapping a provider (Stripe → Creem), change siteConfig.payment.provider AND set the matching *_PRICE_* env vars. The rest of the app doesn’t care which provider is active.
✅ Both messages/en.json and messages/zh.json always have the same keys. node scripts/check-i18n.mjs enforces this.

Getting started

Authentication

Payments

AI primitives

Growth

Content & i18n

Operations

Deployment

Reference

The three layers

What `siteConfig` controls

What lives outside `siteConfig`

Adding a new feature flag

Adding an env var

Best-practice checklist

​The three layers

​What siteConfig controls

​What lives outside siteConfig

​Adding a new feature flag

​Adding an env var

​Best-practice checklist

The three layers

What `siteConfig` controls

What lives outside `siteConfig`

Adding a new feature flag

Adding an env var

Best-practice checklist