Configuration

ShipKit keeps configuration in four places, and each one answers a different question:

A secret is an environment variable; a value someone running the business should tune without a developer is an operator setting; the rest is code.

Config files in src/config

Components import these files directly rather than reading import.meta.env. Most user-facing copy is not here but in messages/en.json and messages/zh.json (see i18n); the app name reaches that copy as a parameter, so renaming the app in the UI is one edit.

app-config.ts

Everything in it ships as a placeholder. Go through it before the first deploy.

url and the APP_URL environment variable both hold your origin but do different jobs: url is compiled into the pages, APP_URL is what the server uses for auth callbacks and checkout return URLs. In production both should be your domain.

A few branding files sit outside src/config: public/manifest.json, the icons in public/, and public/og.png, the social card, which bun run og redraws from scripts/og-card.html.

plans.ts

The single source of truth for pricing: webhooks resolve an incoming Stripe price id or Creem product id against this file, so an unlisted id is not recognized. The ids ship as REPLACE_ME placeholders until the /stripe or /creem skill writes the real ones in. See Payments and Credits.

Environment variables

Secrets are read from .dev.vars locally and from Worker secrets in production. .dev.vars.example is the list, and src/core/env.ts validates it with zod. Required keys are checked on first use and a missing one stops the request with an error naming it; optional keys are checked only by the code that needs them, so deleting a feature never breaks startup. Empty strings count as unset.

Purchase buttons read the active provider's key: until it is set they show "coming soon" instead of starting a checkout, so the app is usable before payments exist.

Environment is read at boot, so restart the dev server after editing .dev.vars. Changing BETTER_AUTH_SECRET signs everyone out and makes any stored secret-type setting unreadable, so treat it as permanent once you are live. Deploy covers pushing secrets to production.

When you add a variable, add it to both .dev.vars.example and the schema in src/core/env.ts. D1 and R2 need no variables at all: they are bindings.

wrangler.jsonc

The Cloudflare side of the app. The fields you are most likely to touch:

Keep the binding names (DB, BUCKET and the rate limiter names): the code refers to them. After changing this file, run bun run cf-typegen to regenerate the Env types.

Operator settings

Some values belong to whoever runs the business, not to the codebase: how long to keep audit logs, how many days a subscription survives a missed webhook. These live at /admin/settings (Settings → Settings in the console) and change without a deploy.

How they behave:

• Defaults live in code. The database stores only overrides. A key nobody has changed follows the default in the feature's code, so a new default you ship reaches every deployment that never touched it. Each row can be reset to its default.
• Changes take up to a minute. Values are cached for 60 seconds per Worker isolate.
• Ranges are enforced. Each numeric setting has a minimum and maximum, checked in the form and again on the server.
• Permissions apply. Viewing needs settings.read, editing settings.write; see Permissions.
• Deleted features take their settings with them. Each group belongs to a feature and disappears when you delete it.

Adding a setting

A feature declares its settings in its own settings.ts with registerSetting(): a namespaced key such as billing.grace_days, a kind (number, boolean, string or secret), the code default, an optional range and unit, and a label and hint as message functions so the console localizes them. src/core/settings/handlers.ts imports that file with one line. src/features/billing/settings.ts is a short model to copy.

Server code reads the value with getNumberSetting('billing.grace_days') (or getSetting, getSecretSetting) from src/core/settings/store.ts. A secret is encrypted at rest and never sent back to the browser; a setting marked visibility: 'public' is readable by any signed-in user, for limits the browser has to enforce.

One constraint: a settings.ts file is loaded by the browser bundle too, so it must import nothing server-only. Keep the default in a client-safe config.ts beside it, as billing does. src/core/settings/handlers.test.ts fails if you get this wrong. Adding features covers the other registries a new feature can plug into.