package.json Scripts

Every service needs a package.json next to its service.json, with a fixed set of npm scripts. TDK's Docker build (L3/L4 layers) and the Tilt dev loop invoke these scripts directly by name, so a missing one fails silently until tdk up or a production build.

Required scripts by appType

• backend — dev, build, start
• worker — dev, build, start
• migrator — dev, build, start
• frontend — dev, build
• library — dev, build
• sdk — dev, build

Frontend, library, and SDK services skip start — they're served statically or consumed as packages, never run as a standalone process in production. Backend, worker, and migrator services are long-running processes, so all three scripts are required.

What each script is for

dev

Runs the service directly from source with hot reload. This is what tdk up uses in local development, via Tilt.

"dev": "bun run src/index.ts"

build

Compiles the service for production. TDK's L3 Docker layer runs this script to produce the artifact that ships in the image.

"build": "tsc"

start

Runs the compiled production output. TDK's L4 Docker runtime layer sets this as the container's entrypoint command for backend, worker, and migrator services.

"start": "bun run dist/index.js"

Examples

Backend / worker / migrator

{
  "name": "reservation-api",
  "scripts": {
    "dev": "bun run src/index.ts",
    "build": "tsc",
    "start": "bun run dist/index.js",
    "test": "bun test",
    "typecheck": "tsc --noEmit"
  }
}

Frontend / library / SDK

{
  "name": "checkout-app",
  "scripts": {
    "dev": "vite --host 0.0.0.0 --port 3210",
    "build": "tsc --noEmit && vite build",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  }
}

Catching gaps early

tdk doctor discovers every service.json in the project, reads the matching package.json, and reports exactly which required scripts are missing per service — before Tilt tries and fails to run one.

tdk doctor

✗ Services missing required package.json scripts:
    user-portal-api: missing "build", "start"
ℹ Fix: Add the missing scripts to each service's package.json