stacks-config

# Stacks Configuration ## Key Paths - Core package: `storage/framework/core/config/src/` - Configuration directory: `config/` - Defaults: `storage/framework/core/config/src/defaults.ts` - Overrides: `storage/framework/core/config/src/overrides.ts` ## Config API ```typescript import { config, getConfig } from '@stacksjs/config' config.app.name // 'Stacks' config.database // full database config config.auth // auth config getConfig() // returns full StacksOptions ``` ## Individual Config Exports ```typescript import { ai, analytics, app, auth, cache, cloud, cli, database, dns, docs, email, errors, git, hashing, library, logging, notification, payment, ports, queue, realtime, security, saas, searchEngine, services, filesystems, team, ui } from '@stacksjs/config' ``` ## Config Builder Functions ```typescript import { defineApp, defineDatabase, defineCache, defineEmail } from '@stacksjs/config' // Used in config files: export default defineApp({ name: 'My App', env: 'production', url: 'https://myapp.com' }) satisfies AppConfig ``` All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineEvents` `defineModel` is NOT among them: it comes from `@stacksjs/orm`, and it builds a model rather than returning a config object. `@stacksjs/config` used to export a second one typed `(config: Model) => Model`, which widened every literal a model declared - its table name, its attribute names - so a model that imported the wrong one silently lost the typing the ORM version exists to provide. The app-level registries have their own helpers, in the packages that own what they name: `defineEvents` and `defineListener` from `@stacksjs/events`, `defineMiddleware` from `@stacksjs/router`, `defineGates` from `@stacksjs/auth`. ## Helper Functions - `determineAppEnv(): 'dev' | 'stage' | 'prod' | string` - `localUrl(): string` — local development URL ## Feature Flags `feature(name)` from `@stacksjs/config` reads `enabled` on `config/<name>.ts`. It accepts the installable bundles (`dashboard`, `commerce`, `cms`, `forms`, `marketing`, `monitoring`, `realtime`, `queue`) plus two config gates: `auth` (whether the ORM loads Team, Referral, Subscriber, Site and the other account models; it does not mount the auth routes, `STACKS_DEFAULT_ROUTES` does) and `email` (the email webhook route bundle). `./buddy features` lists both groups. Any other name is a compile error, so a typo cannot silently read `false`. An app's own flags are declared first: ```ts declare module '@stacksjs/config' { interface AppFeatureFlags { 'new-checkout': true } } ``` ## All 44 Config Files ### Core App | File | Type | Key Settings | |------|------|-------------| | `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale, seo (sitemap.xml / robots.txt) | | `auth.ts` | AuthConfig | guards, providers, token and browser-session lifetimes, passwordReset | | `database.ts` | DatabaseConfig | default driver, connections (sqlite/mysql/postgres/dynamodb), queryLogging | | `cache.ts` | CacheConfig | driver('memory'), ttl(3600), maxKeys(-1), redis config | | `env.ts` | EnvConfig | validation schemas for env vars | | `stacks.ts` | StackExtensionRegistry | extension definitions | ### Services | File | Type | Key Settings | |------|------|-------------| | `email.ts` | EmailConfig | from, domain, mailboxes, server config, ports, categorization, default('ses') | | `sms.ts` | SmsConfig | enabled(false), provider('twilio'), drivers (twilio/vonage/pinpoint) | | `notification.ts` | NotificationConfig | default('email') | | `payment.ts` | PaymentConfig | driver('stripe'), stripe keys | | `ai.ts` | AiConfig | default model, AWS Bedrock models | | `analytics.ts` | AnalyticsConfig | driver('fathom'), tracking settings | ### Infrastructure | File | Type | Key Settings | |------|------|-------------| | `cloud.ts` | CloudConfig | project, mode(server/serverless), environments, infrastructure | | `dns.ts` | DnsConfig | a, aaaa, cname, mx, txt records, nameservers | | `queue.ts` | QueueConfig | default('sync'), connections (sync/database/redis/sqs/memory) | | `realtime.ts` | RealtimeConfig | enabled(true), mode, driver, channels, WebSocket config | | `search-engine.ts` | SearchEngineConfig | driver('opensearch') | ### Development | File | Type | Key Settings | |------|------|-------------| | `ports.ts` | Ports | frontend:3000, backend:3001, admin:3002, ... api:3008 | | `lint.ts` | PickierOptions | format rules, indent, quotes, semi | | `git.ts` | GitConfig | hooks, scopes, commit types | | `commit.ts` | UserConfig | cz-git conventional commit config | | `logging.ts` | LoggingConfig | logsPath, deploymentsPath | | `docs.ts` | BunPressOptions | docsDir, outDir, nav, sitemap | ### Security | File | Type | Key Settings | |------|------|-------------| | `security.ts` | SecurityConfig | api.rowScoping('deny'), api.models('all' / 'own' / 'none' / names; `STACKS_MODEL_APIS` overrides), firewall (enabled, countryCodes, rateLimitPerMinute) | | `hashing.ts` | HashingConfig | driver('bcrypt'), bcrypt.rounds(12), argon2 config | ### Features | File | Type | Key Settings | |------|------|-------------| | `blog.ts` | BlogConfig | subdomain, postsPerPage, enableRss/enableSitemap (enableComments and enableSearch are declared but not yet honoured) | | `cms.ts` | CmsConfig | content management settings | | `saas.ts` | SaasConfig | plans (Hobby/Pro/Lifetime with pricing), webhook, currencies | | `ui.ts` | HeadwindOptions | content, output, minify | | `stx.ts` | StxOptions | componentsDir, layoutsDir, partialsDir | ### Data & Storage | File | Type | Key Settings | |------|------|-------------| | `filesystems.ts` | FilesystemsConfig | driver('bun'), root, s3 config, defaultVisibility('private') | | `file-systems.ts` | — | re-exports from filesystems.ts | | `query-builder.ts` | — | re-exports from qb.ts | | `qb.ts` | QueryBuilderConfig | dialect, timestamps, pagination, softDeletes, transactions | ### Other | File | Type | Key Settings | |------|------|-------------| | `buddy-bot.ts` | BuddyConfig (`@buddysh/buddy`) | repository, dashboard, workflows | | `cli.ts` | BinaryConfig | name, command, description | | `deps.ts` | PantryConfig | system dependencies (bun, sqlite, redis, etc.) | | `errors.ts` | ErrorConfig | comprehensive validation error messages | | `library.ts` | LibraryConfig | name, owner, webComponents, functions | | `phone.ts` | PhoneConfig | enabled, provider, businessHours | | `services.ts` | ServicesConfig | API keys for 20+ services | | `team.ts` | Team | name, members | ## Default Values (from defaults.ts) - App name: `'Stacks'` - Cache driver: `'memory'` - Database: SQLite at `database/stacks.sqlite` - Hashing: bcrypt, 12 rounds - Auth token expiry: 30 days - Ports: frontend 3000, backend 3001, admin 3002, api 3008 ## Gotchas - Config files are TypeScript with `satisfies` for type checking - All configs support environment variable overrides via `env.*` - Framework provides defaults — user overrides in `~/config/*.ts` - Two duplicate file pairs: `file-systems.ts`/`filesystems.ts` and `query-builder.ts`/`qb.ts` - Config changes may require dev server restart - The `services.ts` file contains API keys for AWS, Stripe, Slack, Discord, OpenAI, Anthropic, etc. - Lazy loading is used in config to avoid circular dependencies