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
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
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
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' | stringlocalUrl(): string — local development URL
All 44 Config Files
Core App
| File |
Type |
Key Settings |
app.ts |
AppConfig |
name, env, url, debug, key, timezone, locale |
auth.ts |
AuthConfig |
guards, providers, tokenExpiry(30d), tokenRotation(7d), 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 |
firewall (enabled, countryCodes, rateLimitPerMinute:500) |
hashing.ts |
HashingConfig |
driver('bcrypt'), bcrypt.rounds(12), argon2 config |
Features
| File |
Type |
Key Settings |
blog.ts |
BlogConfig |
subdomain, postsPerPage, enableComments/RSS/sitemap |
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 |
BuddyBotConfig |
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
1---2name: stacks-config3description: Use when working with Stacks configuration - the 44 config files, config helper functions, default values, environment-specific overrides, or the defineApp/defineDatabase/etc builder functions. Covers @stacksjs/config and the config/ directory.4license: MIT5---67# Stacks Configuration89## Key Paths10- Core package: `storage/framework/core/config/src/`11- Configuration directory: `config/`12- Defaults: `storage/framework/core/config/src/defaults.ts`13- Overrides: `storage/framework/core/config/src/overrides.ts`1415## Config API1617```typescript18import { config, getConfig } from '@stacksjs/config'1920config.app.name // 'Stacks'21config.database // full database config22config.auth // auth config23getConfig() // returns full StacksOptions24```2526## Individual Config Exports2728```typescript29import { 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'30```3132## Config Builder Functions3334```typescript35import { defineApp, defineDatabase, defineCache, defineEmail } from '@stacksjs/config'3637// Used in config files:38export default defineApp({39 name: 'My App',40 env: 'production',41 url: 'https://myapp.com'42}) satisfies AppConfig43```4445All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineEvents`4647`defineModel` is NOT among them: it comes from `@stacksjs/orm`, and it builds a48model rather than returning a config object. `@stacksjs/config` used to export a49second one typed `(config: Model) => Model`, which widened every literal a model50declared - its table name, its attribute names - so a model that imported the51wrong one silently lost the typing the ORM version exists to provide.5253The app-level registries have their own helpers, in the packages that own what54they name: `defineEvents` and `defineListener` from `@stacksjs/events`,55`defineMiddleware` from `@stacksjs/router`, `defineGates` from `@stacksjs/auth`.5657## Helper Functions58- `determineAppEnv(): 'dev' | 'stage' | 'prod' | string`59- `localUrl(): string` — local development URL6061## All 44 Config Files6263### Core App64| File | Type | Key Settings |65|------|------|-------------|66| `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale |67| `auth.ts` | AuthConfig | guards, providers, tokenExpiry(30d), tokenRotation(7d), passwordReset |68| `database.ts` | DatabaseConfig | default driver, connections (sqlite/mysql/postgres/dynamodb), queryLogging |69| `cache.ts` | CacheConfig | driver('memory'), ttl(3600), maxKeys(-1), redis config |70| `env.ts` | EnvConfig | validation schemas for env vars |71| `stacks.ts` | StackExtensionRegistry | extension definitions |7273### Services74| File | Type | Key Settings |75|------|------|-------------|76| `email.ts` | EmailConfig | from, domain, mailboxes, server config, ports, categorization, default('ses') |77| `sms.ts` | SmsConfig | enabled(false), provider('twilio'), drivers (twilio/vonage/pinpoint) |78| `notification.ts` | NotificationConfig | default('email') |79| `payment.ts` | PaymentConfig | driver('stripe'), stripe keys |80| `ai.ts` | AiConfig | default model, AWS Bedrock models |81| `analytics.ts` | AnalyticsConfig | driver('fathom'), tracking settings |8283### Infrastructure84| File | Type | Key Settings |85|------|------|-------------|86| `cloud.ts` | CloudConfig | project, mode(server/serverless), environments, infrastructure |87| `dns.ts` | DnsConfig | a, aaaa, cname, mx, txt records, nameservers |88| `queue.ts` | QueueConfig | default('sync'), connections (sync/database/redis/sqs/memory) |89| `realtime.ts` | RealtimeConfig | enabled(true), mode, driver, channels, WebSocket config |90| `search-engine.ts` | SearchEngineConfig | driver('opensearch') |9192### Development93| File | Type | Key Settings |94|------|------|-------------|95| `ports.ts` | Ports | frontend:3000, backend:3001, admin:3002, ... api:3008 |96| `lint.ts` | PickierOptions | format rules, indent, quotes, semi |97| `git.ts` | GitConfig | hooks, scopes, commit types |98| `commit.ts` | UserConfig | cz-git conventional commit config |99| `logging.ts` | LoggingConfig | logsPath, deploymentsPath |100| `docs.ts` | BunPressOptions | docsDir, outDir, nav, sitemap |101102### Security103| File | Type | Key Settings |104|------|------|-------------|105| `security.ts` | SecurityConfig | firewall (enabled, countryCodes, rateLimitPerMinute:500) |106| `hashing.ts` | HashingConfig | driver('bcrypt'), bcrypt.rounds(12), argon2 config |107108### Features109| File | Type | Key Settings |110|------|------|-------------|111| `blog.ts` | BlogConfig | subdomain, postsPerPage, enableComments/RSS/sitemap |112| `cms.ts` | CmsConfig | content management settings |113| `saas.ts` | SaasConfig | plans (Hobby/Pro/Lifetime with pricing), webhook, currencies |114| `ui.ts` | HeadwindOptions | content, output, minify |115| `stx.ts` | StxOptions | componentsDir, layoutsDir, partialsDir |116117### Data & Storage118| File | Type | Key Settings |119|------|------|-------------|120| `filesystems.ts` | FilesystemsConfig | driver('bun'), root, s3 config, defaultVisibility('private') |121| `file-systems.ts` | — | re-exports from filesystems.ts |122| `query-builder.ts` | — | re-exports from qb.ts |123| `qb.ts` | QueryBuilderConfig | dialect, timestamps, pagination, softDeletes, transactions |124125### Other126| File | Type | Key Settings |127|------|------|-------------|128| `buddy-bot.ts` | BuddyBotConfig | repository, dashboard, workflows |129| `cli.ts` | BinaryConfig | name, command, description |130| `deps.ts` | PantryConfig | system dependencies (bun, sqlite, redis, etc.) |131| `errors.ts` | ErrorConfig | comprehensive validation error messages |132| `library.ts` | LibraryConfig | name, owner, webComponents, functions |133| `phone.ts` | PhoneConfig | enabled, provider, businessHours |134| `services.ts` | ServicesConfig | API keys for 20+ services |135| `team.ts` | Team | name, members |136137## Default Values (from defaults.ts)138- App name: `'Stacks'`139- Cache driver: `'memory'`140- Database: SQLite at `database/stacks.sqlite`141- Hashing: bcrypt, 12 rounds142- Auth token expiry: 30 days143- Ports: frontend 3000, backend 3001, admin 3002, api 3008144145## Gotchas146- Config files are TypeScript with `satisfies` for type checking147- All configs support environment variable overrides via `env.*`148- Framework provides defaults — user overrides in `~/config/*.ts`149- Two duplicate file pairs: `file-systems.ts`/`filesystems.ts` and `query-builder.ts`/`qb.ts`150- Config changes may require dev server restart151- The `services.ts` file contains API keys for AWS, Stripe, Slack, Discord, OpenAI, Anthropic, etc.152- Lazy loading is used in config to avoid circular dependencies
stacksjs