Add a New Feature Module
Create a new shared package in the monorepo and roll it out safely with feature flags.
This recipe adds a module under packages/, wires it into apps, and gates rollout with existing feature-flag patterns.
Rollout principle
Ship new modules behind explicit feature flags so deployment topology and user-facing behavior can be controlled independently.
Workflow
Scaffold a package
Create a package folder with src/ and package.json.
Suggested package fields:
name:@ai/<module-name>private:truemainandexportspointing tosrc/index.ts- a
typecheckscript (tsc --noEmit)
Then:
bun installExport a clean API surface
In packages/<module-name>/src/index.ts, export only what apps should consume. Keep internals private to reduce coupling.
Add rollout controls
Use the existing @ai/features pattern:
- add a new key to
FeatureFlagsinpackages/features/src/types.ts - add env mapping in
FEATURE_ENV_VARS - parse value in
packages/features/src/config.tsusingenvBool(...) - add the corresponding variable to
.env.example
Then gate usage in app code via isFeatureEnabled(...) or getFeatureFlags().
Wire into consuming apps
Add the new workspace package dependency where needed (for example apps/app/package.json and/or apps/admin/package.json), then run:
bun installValidate and run
bun typecheck
bun lint
bun dev:appIf module affects workers or infra-driven flows, also run:
bun dev:worker
bun healthDocument enablement
Update docs with env variable names, default behavior, required services, and fallback behavior when disabled.