Configuration

starter.config.ts(Licensees only) decides which parts of the kit are on, which providers each part bundles, and your plans, roles, permissions and languages. You edit it whenever you change one of those. Secrets and values that differ between deploys go in environment variables instead.

How it works

1. defineStarterConfig returns the object unchanged. It exists for its types: the literals you write become unions such as PlanId, UserRole, Permission and FlagId in shared/types/config.ts(Licensees only), so a misspelled plan or permission fails typecheck. The shape is StarterConfig in shared/types/starter.ts(Licensees only).
2. nuxt.config.ts loads the file at build time. build/assertions.ts(Licensees only) checks it against wrangler.jsonc and i18n/locales/, and the registries in modules/ check providers, plans and roles. Every failure names the key and the fix.
3. Only the providers you list are bundled. build/runtime-config.ts(Licensees only) declares a runtime-config slot for each credential those providers read, and NUXT_* environment variables fill the slots.
4. When a deployed Worker boots, server/plugins/env-check.ts(Licensees only) logs one [env] warning naming every variable an enabled part needs and the deploy lacks. It stays quiet under pnpm dev.

Read the config in code

Import the file directly. It works the same in server routes, components and composables:

import starter from '~~/starter.config'

export const sellsYearly = Object.values(starter.payments.plans).some(
  (plan) => plan.mode === 'subscription' && 'year' in plan.intervals,
)

export function isTopPlan(plan: PlanId): boolean {
  return plan === 'promax'
}

PlanId and the other unions from shared/types/config.ts are auto-imported on both sides. Because PlanId is 'pro' | 'promax' | 'lifetime', comparing it with 'proMax' fails typecheck.

Change it

Save the file and pnpm dev restarts, because nuxt.config.ts watches it.

Keep it pure data. Nuxt, Vite, @nuxt/content, Vitest and the seed scripts all load it, and the seed scripts' loader (scripts/seed/lib/starter-config.mjs(Licensees only)) refuses any import other than #starter/define. A function or a second import breaks at least one of them. The #starter/* entry under imports in package.json exists for that one import, so leave it there.

The build refuses a config that can't work:

• build/assertions.ts(Licensees only): a declared locale with no file in i18n/locales/, or a file there that no locale declares; no HYPERDRIVE binding; cloudflare email without a send_email binding named EMAIL; the queue on without its producer, consumer and dead letter consumer; workersai without the AI binding; a storage purpose whose binding or bucket isn't in r2_buckets; a deletion grace period with auth on and email off; notifications with auth off; a firstAccountRole that doesn't grant users:manage.
• modules/tenancy-assert.ts(Licensees only): an org permission that a plan sells, more than two orgs.levels, an ownerRole that can't be held at the root, invitations with email off, organizations with auth off.
• modules/payments-registry.ts(Licensees only): the plan rules on Payments, such as a plan id outside /^[a-z][a-z0-9]*$/ or trialDays with Creem or Lemon Squeezy enabled.

Set environment variables

Nitro fills each runtime-config key from NUXT_ plus the key's path in upper snake case:

Locally they go in .env. .env.example(Licensees only) lists every variable the kit reads and where each value comes from. On a deploy, set them on the Worker. The Worker reads them per request, so changing one needs no rebuild:

pnpm exec wrangler secret put NUXT_PAYMENTS_STRIPE_SECRET_KEY --name <worker>

A few are read at build time and baked into the bundle: NUXT_SITE_URL, NUXT_PUBLIC_TURNSTILE_SITE_KEY and NUXT_IMAGE_PROVIDER. For pnpm deploy:cf those go in .env.production (Deployment).

Each topic page lists its own variables. These belong to the app as a whole:

Every key

Defaults are the shipped values. The linked page covers each part in full.

activity, security, legal

payments

Details, provider setup and the ref variables are on Payments.

access

See Permissions.

orgs

See Organizations.

auth

See Auth.

email, contact and ai

email.adapters and ai.adapters declare a provider you drop into that part's adapters/custom/. See Email, Contact and AI.

i18n and flags

See Languages and Feature flags.

notifications, storage, account, queue

monitoring, analytics, marketing, socialProof

Good to know

• App code imports this file, so it ships in the browser bundle. Never put a secret in it.
• Ids that end up in a variable name must match /^[a-z][a-z0-9]*$/: plan ids, AI role ids and the file name of a custom adapter. Nitro maps proMax, pro-max and pro_max to the same variable, which is why the config says promax and workersai.
• A slot exists only for a provider that was listed when you built. Setting NUXT_PAYMENTS_POLAR_SECRET_KEY does nothing until polar is in payments.providers and the app is rebuilt.
• Values pass through destr, and an empty line such as NUXT_PAYMENTS_STRIPE_REFS_PRO_MONTH= sets an empty string over the default. Comment out lines you don't use.
• A new plan, app role or org level also needs its copy in every file in i18n/locales/. plan-copy, role-copy and org-copy in test/unit/ fail until it is there.