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' | string
localUrl(): 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-config-43description: 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: MIT5compatibility: Bun >= 1.3.0, TypeScript6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-config-49---1011# Stacks Configuration1213## Key Paths14- Core package: `storage/framework/core/config/src/`15- Configuration directory: `config/`16- Defaults: `storage/framework/core/config/src/defaults.ts`17- Overrides: `storage/framework/core/config/src/overrides.ts`1819## Config API2021```typescript22import { config, getConfig } from '@stacksjs/config'2324config.app.name // 'Stacks'25config.database // full database config26config.auth // auth config27getConfig() // returns full StacksOptions28```2930## Individual Config Exports3132```typescript33import { 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'34```3536## Config Builder Functions3738```typescript39import { defineApp, defineDatabase, defineCache, defineEmail } from '@stacksjs/config'4041// Used in config files:42export default defineApp({43 name: 'My App',44 env: 'production',45 url: 'https://myapp.com'46}) satisfies AppConfig47```4849All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineEvents`5051`defineModel` is NOT among them: it comes from `@stacksjs/orm`, and it builds a52model rather than returning a config object. `@stacksjs/config` used to export a53second one typed `(config: Model) => Model`, which widened every literal a model54declared - its table name, its attribute names - so a model that imported the55wrong one silently lost the typing the ORM version exists to provide.5657The app-level registries have their own helpers, in the packages that own what58they name: `defineEvents` and `defineListener` from `@stacksjs/events`,59`defineMiddleware` from `@stacksjs/router`, `defineGates` from `@stacksjs/auth`.6061## Helper Functions62- `determineAppEnv(): 'dev' | 'stage' | 'prod' | string`63- `localUrl(): string` — local development URL6465## All 44 Config Files6667### Core App68| File | Type | Key Settings |69|------|------|-------------|70| `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale |71| `auth.ts` | AuthConfig | guards, providers, tokenExpiry(30d), tokenRotation(7d), passwordReset |72| `database.ts` | DatabaseConfig | default driver, connections (sqlite/mysql/postgres/dynamodb), queryLogging |73| `cache.ts` | CacheConfig | driver('memory'), ttl(3600), maxKeys(-1), redis config |74| `env.ts` | EnvConfig | validation schemas for env vars |75| `stacks.ts` | StackExtensionRegistry | extension definitions |7677### Services78| File | Type | Key Settings |79|------|------|-------------|80| `email.ts` | EmailConfig | from, domain, mailboxes, server config, ports, categorization, default('ses') |81| `sms.ts` | SmsConfig | enabled(false), provider('twilio'), drivers (twilio/vonage/pinpoint) |82| `notification.ts` | NotificationConfig | default('email') |83| `payment.ts` | PaymentConfig | driver('stripe'), stripe keys |84| `ai.ts` | AiConfig | default model, AWS Bedrock models |85| `analytics.ts` | AnalyticsConfig | driver('fathom'), tracking settings |8687### Infrastructure88| File | Type | Key Settings |89|------|------|-------------|90| `cloud.ts` | CloudConfig | project, mode(server/serverless), environments, infrastructure |91| `dns.ts` | DnsConfig | a, aaaa, cname, mx, txt records, nameservers |92| `queue.ts` | QueueConfig | default('sync'), connections (sync/database/redis/sqs/memory) |93| `realtime.ts` | RealtimeConfig | enabled(true), mode, driver, channels, WebSocket config |94| `search-engine.ts` | SearchEngineConfig | driver('opensearch') |9596### Development97| File | Type | Key Settings |98|------|------|-------------|99| `ports.ts` | Ports | frontend:3000, backend:3001, admin:3002, ... api:3008 |100| `lint.ts` | PickierOptions | format rules, indent, quotes, semi |101| `git.ts` | GitConfig | hooks, scopes, commit types |102| `commit.ts` | UserConfig | cz-git conventional commit config |103| `logging.ts` | LoggingConfig | logsPath, deploymentsPath |104| `docs.ts` | BunPressOptions | docsDir, outDir, nav, sitemap |105106### Security107| File | Type | Key Settings |108|------|------|-------------|109| `security.ts` | SecurityConfig | firewall (enabled, countryCodes, rateLimitPerMinute:500) |110| `hashing.ts` | HashingConfig | driver('bcrypt'), bcrypt.rounds(12), argon2 config |111112### Features113| File | Type | Key Settings |114|------|------|-------------|115| `blog.ts` | BlogConfig | subdomain, postsPerPage, enableComments/RSS/sitemap |116| `cms.ts` | CmsConfig | content management settings |117| `saas.ts` | SaasConfig | plans (Hobby/Pro/Lifetime with pricing), webhook, currencies |118| `ui.ts` | HeadwindOptions | content, output, minify |119| `stx.ts` | StxOptions | componentsDir, layoutsDir, partialsDir |120121### Data & Storage122| File | Type | Key Settings |123|------|------|-------------|124| `filesystems.ts` | FilesystemsConfig | driver('bun'), root, s3 config, defaultVisibility('private') |125| `file-systems.ts` | — | re-exports from filesystems.ts |126| `query-builder.ts` | — | re-exports from qb.ts |127| `qb.ts` | QueryBuilderConfig | dialect, timestamps, pagination, softDeletes, transactions |128129### Other130| File | Type | Key Settings |131|------|------|-------------|132| `buddy-bot.ts` | BuddyBotConfig | repository, dashboard, workflows |133| `cli.ts` | BinaryConfig | name, command, description |134| `deps.ts` | PantryConfig | system dependencies (bun, sqlite, redis, etc.) |135| `errors.ts` | ErrorConfig | comprehensive validation error messages |136| `library.ts` | LibraryConfig | name, owner, webComponents, functions |137| `phone.ts` | PhoneConfig | enabled, provider, businessHours |138| `services.ts` | ServicesConfig | API keys for 20+ services |139| `team.ts` | Team | name, members |140141## Default Values (from defaults.ts)142- App name: `'Stacks'`143- Cache driver: `'memory'`144- Database: SQLite at `database/stacks.sqlite`145- Hashing: bcrypt, 12 rounds146- Auth token expiry: 30 days147- Ports: frontend 3000, backend 3001, admin 3002, api 3008148149## Gotchas150- Config files are TypeScript with `satisfies` for type checking151- All configs support environment variable overrides via `env.*`152- Framework provides defaults — user overrides in `~/config/*.ts`153- Two duplicate file pairs: `file-systems.ts`/`filesystems.ts` and `query-builder.ts`/`qb.ts`154- Config changes may require dev server restart155- The `services.ts` file contains API keys for AWS, Stripe, Slack, Discord, OpenAI, Anthropic, etc.156- Lazy loading is used in config to avoid circular dependencies