Configuration

The service.json file is the single source of truth for each service. Here is the complete schema.

service.json schema

service.json — annotated

{
  "appName": "my-service",           // Required: unique name
  "appType": "backend",             // Required: backend | frontend | library | worker
  "port": 3000,                     // Required: service port
  "stack": "api",                   // Optional: stack grouping
  "features": [                      // Optional: features to enable
    "typescript",
    "vite",
    "bun"
  ],
  "replicas": 1,                    // Optional: number of replicas
  "backendName": "api-backend",     // Optional: backend for frontend
  "basePath": "/api",               // Optional: URL base path
  "internalDependencies": [         // Optional: other services
    "database",
    "cache"
  ],
  "envVars": {                      // Optional: environment variables
    "NODE_ENV": "development",
    "API_URL": "http://localhost:3001"
  }
}

Required fields

appName

The unique identifier for your service. Lowercase with hyphens.

service.json

"appName": "order-service"

appType

The type of service. Determines which generators run.

backend — API service
frontend — Web application
library — Shared code package
worker — Background job processor
migrator — Database migration service

port

The port your service listens on.

service.json

"port": 3000

Optional fields

features

List of features to enable. Triggers corresponding generators.

typescript — TypeScript support
vite — Vite bundler
bun — Bun runtime
node — Node.js runtime
nginx — Nginx reverse proxy
playwright — E2E testing
prisma — Database ORM

stack

Groups related services for selective startup and Tilt orchestration.

service.json

"stack": "order-management"

internalDependencies

Other services this service depends on. TDK resolves boot order automatically.

service.json

"internalDependencies": ["database", "redis", "auth-service"]

Examples by type

Backend service

api-gateway / service.json

{
  "appName": "api-gateway",
  "appType": "backend",
  "port": 3000,
  "features": ["typescript", "bun"],
  "internalDependencies": ["database", "redis"],
  "envVars": {
    "NODE_ENV": "development"
  }
}

Frontend service

web-app / service.json

{
  "appName": "web-app",
  "appType": "frontend",
  "port": 5173,
  "features": ["typescript", "vite"],
  "backendName": "api-gateway",
  "basePath": "/app"
}