Stacks Project Configuration

Project-level configuration files that control the development environment, build system, and runtime. For feature-specific configs (database, email, auth, etc.), see the corresponding package skill.

bunfig.toml

# Order matters: the env layer decrypts .env before the preloader reads it.
preload = [
  "./storage/framework/core/env/plugin.ts",
  "./storage/framework/defaults/resources/plugins/preloader.ts",
]

[test]
preload = [
  "./storage/framework/core/env/plugin.ts",
  "./tests/setup.ts",
]
coverage = false

[run]
bun = true                          # equivalent to `bun --bun` for `bun run`

[serve.static]
plugins = ["bun-plugin-stx"]        # stx template processing for static serves

[install]
registry = { url = "https://registry.npmjs.org/", token = "$BUN_AUTH_TOKEN" }
linker = "hoisted"                  # REQUIRED when using better-dx

See stacks-plugins for what each preloaded module does, and why some commands
deliberately skip the auto-import graph.

TypeScript

There is exactly one tsconfig in the project root. It extends the framework's
app config, and restates the tunable defaults so you can edit or delete any one
of them:

tsconfig.json                                  <- yours; the only one in the root
  extends storage/framework/tsconfig.app.json  <- app paths, include/exclude
    extends storage/framework/tsconfig.base.json  <- every compiler option

• Change a line in the root compilerOptions to override that option.
• Delete a line to fall back to the framework default.
• Delete the whole block to take the defaults wholesale.

Path aliases, module resolution, and which files get checked are owned by the
framework and update with it.

Framework internals are checked separately by
storage/framework/tsconfig.framework.json - do not point your root config at
storage/framework/**.

bun run typecheck:app    # app/, config/, resources/, routes/
bun run typecheck        # framework internals
bun run typecheck:clean  # drop the incremental cache

Type checking runs on TypeScript 7 - tsc is the native Go compiler (tsgo), so
both checks finish in a couple of seconds. Options removed in 7.0 (baseUrl,
importsNotUsedAsValues, preserveValueImports, suppressImplicitAnyIndexErrors)
are gone from every config; path mappings resolve relative to the file that
declares them, so no baseUrl is needed.

Incremental build info lands in storage/framework/.cache/typescript/, not in
node_modules, so it survives a reinstall.

package.json (Root)

Key sections:

{
  "type": "module",
  "workspaces": [
    "storage/framework/**",
    "!**/node_modules/**",
    "!**/dist/**",
    "!**/docs/deps/**",
    "!storage/framework/server/storage/**",
    "!storage/framework/cache/**"
  ],
  "engines": {
    "bun": ">=1.3.0"
  },
  "systemDependencies": {
    "sqlite": ">=3.47.2"
  }
}

.env Setup

# Required
APP_NAME=MyApp
APP_ENV=local            # local | dev | stage | prod
APP_KEY=                 # generate with: buddy key:generate
APP_URL=http://localhost:3000

# Database
DB_CONNECTION=sqlite     # sqlite | mysql | postgres
DB_DATABASE=database/stacks.sqlite

# Optional (add as needed)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
STRIPE_SECRET_KEY=
MAIL_MAILER=ses

System Requirements

• Bun >= 1.3.0 (runtime + package manager)
• SQLite >= 3.47.2 (default database)

Key Project Scripts

bun run dev          # start dev server
bun run build        # production build
bun run lint         # lint (uses pickier)
bun run test         # run tests
bun run deploy       # deploy to cloud
bun run fresh        # clean reinstall
bun run build:reset  # full clean rebuild

better-dx Integration

• Provides typescript, pickier, bun-plugin-dtsx as peer dependencies
• Do NOT install these separately if better-dx is in package.json
• REQUIRES linker = "hoisted" in bunfig.toml

Gotchas

• bunfig.toml MUST have linker = "hoisted" when better-dx is installed
• Preload order is load-bearing — the env plugin decrypts .env before the
  preloader reads it. Swapping them breaks encrypted config
• The stx plugin belongs under [serve.static], not [serve]
• One tsconfig in the root. Adding a second (a tsconfig.framework.json, say)
  splits the source of truth. Point scripts at the framework's config by path
  instead
• Workspace excludes prevent node_modules and dist from being treated as packages
• .env is auto-loaded by Bun — no dotenv package needed
• Generate APP_KEY before deployment: buddy key:generate