Stacks Dependencies

Key Paths

• Root: package.json
• Deps config: config/deps.ts
• Bun lock: bun.lock
• Bun config: bunfig.toml

Pantry Configuration (config/deps.ts)

import type { PantryConfig } from 'ts-pantry'

interface PantryConfig {
  dependencies: Record<string, string>   // System-level dependencies
  global: boolean
  services: {
    enabled: boolean
    autoStart: boolean
    database: DatabaseConfig
    postDatabaseSetup: string[]
    frameworks: FrameworkConfig
  }
  preSetup: LifecycleHook
  postSetup: LifecycleHook
  preActivation: LifecycleHook
  postActivation: LifecycleHook
  cache: CacheConfig
  network: NetworkConfig
  security: SecurityConfig
  logging: LoggingConfig
  updates: UpdateConfig
  resources: ResourceConfig
  profiles: ProfileConfig
  verbose: boolean
  installPath: string
  autoInstall: boolean
  installDependencies: boolean
  installBuildDeps: boolean
}

System Dependencies

dependencies: {
  bun: '1.3.0',
  sqlite: '3.47.2',
  redis: '7.0.0',
  // ... other system-level requirements
}

Workspace Dependencies

Core packages use workspace:* references:

{
  "@stacksjs/auth": "workspace:*",
  "@stacksjs/database": "workspace:*",
  "@stacksjs/router": "workspace:*"
}

Key Framework Dependencies

Package	Purpose
better-dx	Shared dev tooling (provides typescript, pickier, bun-plugin-dtsx)
bun-query-builder	Database query building
@stacksjs/ts-auth	Authentication library
@stacksjs/ts-cloud	Cloud infrastructure (AWS CDK)
ts-rate-limiter	Rate limiting
ts-collect	Collection utilities
ts-mocker	Fake data generation
ts-slug	URL slug generation

CLI Commands

buddy add <package>        # Add a dependency
buddy install              # Install dependencies
buddy outdated             # Check for outdated packages
buddy fresh                # Clean + reinstall
bun run upgrade            # Upgrade dependencies
bun run build:reset        # Full reset: rm deps → reinstall → generate → lint → build

Lockfiles

A Stacks project commits two lockfiles, and they describe one tree:

• bun.lock resolves node_modules/, which the app root reads.
• pantry.lock records the system toolchain (Bun itself, SQLite, curl, git)
  and every npm package, which pantry/ holds and the framework source
  resolves from.

Pantry follows bun.lock's pin when it satisfies the declared npm range, so
shared npm records must agree. Native platform records can differ between
hosts. Review the generated difference and use the repository's lock guards:
an allowed platform addition does not excuse a missing or changed declared
dependency, stale workspace ranges, or a lost system-toolchain block.

Regenerating. Use the repository's declared, Pantry-managed Bun. Change the
ranges, run bun install, then pantry install --ignore-scripts --quiet, and
commit both lockfiles with the manifests. This is the metadata-only mode the
framework release action uses. A plain pantry install can activate project
services and run postDatabaseSetup or postSetup hooks, including migrations
and seeding; those are separate from maintaining dependency locks.

Check head -2 bun.lock says lockfileVersion: 2; an older Bun on PATH
downgrades it.

Who else writes them.

• buddy release regenerates both and refuses to commit a pantry.lock that
  violates a range it records or drops the root system block.
• The dependency bot (@buddysh/buddy 0.11.5+, via better-dx) runs
  pantry install after the JS manager on its Linux runner, so dependency pull
  requests arrive with both lockfiles current.

The guards. CI's compile job installs and fails if either lockfile
changed, and lockfile-matches-manifests.test.ts compares the ranges both
lockfiles record against the manifests. Either failure means a lockfile was
not regenerated with its manifest, not that the guard is wrong.

Dependency Update System

• buddy-bot (@buddysh/buddy, shipped by better-dx) handles dependency updates, NOT renovatebot
• Automated PR creation for dependency updates, run as bunx @buddysh/buddy in .github/workflows/buddy-bot.yml
• Configured via config/buddy-bot.ts (read as the pre-rename fallback for config/buddy.ts, which in a Stacks app would read as the Stacks CLI's config)

Gotchas

• buddy-bot, not renovatebot — Stacks uses its own dependency update bot
• better-dx provides peer deps — do NOT separately install typescript, pickier, or bun-plugin-dtsx if better-dx is present
• bunfig.toml requires linker = "hoisted" when using better-dx
• Pantry manages system deps — OS-level dependencies like SQLite, Redis, Bun itself
• Workspace references — all @stacksjs/* packages use workspace:* in the monorepo
• bun.lock not bun.lockb — Stacks uses the text-based lockfile format
• Build reset is destructive — bun run build:reset removes all deps and reinstalls from scratch