Configuration

TDK has two JSON configuration files: a service.json per service and a project-level .tdk/project.json. These schemas help your editor; the CLI remains the runtime source of truth.

service.json

This backend manifest is valid JSON. Field notes follow the file instead of appearing as invalid JSON comments.

{
  "$schema": "https://flisk.sh/schema.service.json",
  "schemaVersion": 1,
  "appName": "api-backend",
  "appType": "backend",
  "stack": "shop",
  "port": 4000,
  "healthCheckPath": "/health",
  "dependsOn": []
}

appName, appType, stack, and schemaVersion are required; a backend also needs a port. Optional fields include dependsOn and healthCheckPath. See the service schema source. VS Code and other JSON editors can read the $schema hint.

.tdk/project.json

Use the project configuration schema through an editor association. In VS Code, add this to workspace .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["/services/**/service.json"],
      "url": "https://flisk.sh/schema.service.json"
    },
    {
      "fileMatch": ["/.tdk/project.json"],
      "url": "https://raw.githubusercontent.com/tdk-landscape/tdk-cli-core/main/engine/schemas/project-schema.json"
    }
  ]
}

tdk doctor checks local environment readiness and discovered service issues. tdk config verify checks whether generated project files match .tdk/project.json; it does not lint service.json or Helm values. TDK does not validate your production chart.

Required fields

appName

The unique identifier for your service. Lowercase with hyphens.

"appName": "catalog-api"

appType

The type of service. Determines which generators run.

• backend — API service
• frontend — Web application
• library — Shared code package
• sdk — Generated client SDK
• worker — Background job processor
• migrator — Database migration service

Workers must enable nats in featuresEnabled. They have no HTTP server, so they get no Traefik route and no HTTP health check.

stack

Groups related services for selective startup and Tilt orchestration. tdk up <stack> starts one stack.

"stack": "reports"

port

The port your service listens on. Backends need one in 4000-5999 and frontends use 3000-3999. TDK runs the service on exactly this port, and other containers reach it as http://<appName>:<port>. Backend ports are not published on localhost; reach them through Traefik at http://api.<project>.localhost/api/<name without -api>.

"port": 4410

Optional fields

framework

Which single-page-app provider generates a frontend's Vite and TypeScript config. Leave it out and you get React, so existing manifests are unchanged.

• react — React + Vite. The default when framework is omitted, so older manifests keep working
• vue — Vue 3 + Vite (@vitejs/plugin-vue). Scaffold with tdk resource web --type frontend --framework vue

tdk resource web --type frontend --framework vue --stack shop

That writes "framework": "vue" into web/service.json. Docker, nginx, Traefik and Tilt are shared with React frontends. Needs TDK CLI 1.3.75 or newer; older releases ignore the field and generate React config. See the Vue example, or add a framework.

featuresEnabled

Platform features to enable. Only these values are valid:

• nats — NATS JetStream eventing. TDK injects TILT_NATS_URL; you provide the broker (see the auth + queue + email example)
• prisma — Database ORM and migrations
• redis — Caching layer
• infisical — Secrets management
• vitest — Test framework
• traefik — Reverse-proxy routing
• websocket — WebSocket support
• graphql — GraphQL server
• grpc — gRPC protocol

dependsOn

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

"dependsOn": ["auth-emulator", "catalog-api"]

params

Non-secret environment variables for the container. Use them to point one service at another by resource name and port, so swapping a local stand-in for a managed service is a config change. Secrets belong in secrets, not here.

"params": {
  "OIDC_ISSUER": "http://api.my-project.localhost/api/auth-emulator",
  "OIDC_JWKS_URL": "http://auth-emulator:4400/.well-known/jwks.json"
}

The auth + queue + email example uses this to run an identity provider, a queue and email locally.

package.json scripts

Each service also needs a package.json next to its service.json, with npm scripts required by appType. See package.json scripts for the list.

Examples by type

Real manifests from the reference repositories are on the examples page. These show the shape of each type.

Backend service

{
  "appName": "catalog-api",
  "appType": "backend",
  "stack": "store",
  "port": 4300,
  "featuresEnabled": ["prisma"],
  "dependsOn": []
}

Frontend service (Vue)

{
  "appName": "storefront-web",
  "appType": "frontend",
  "framework": "vue",
  "stack": "store",
  "port": 3300,
  "basePath": "/storefront-web",
  "dependsOn": ["catalog-api"]
}

Worker

{
  "appName": "report-worker",
  "appType": "worker",
  "stack": "reports",
  "port": 4420,
  "featuresEnabled": ["nats"]
}