Documentation

Configuration

Learn about service.json and all available options.

service.json Schema

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

{
  "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. Must be lowercase with hyphens.

"appName": "order-service"

appType

The type of service. Affects 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.

"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 together for Tilt orchestration.

"stack": "order-management"

internalDependencies

Other services this service depends on.

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

Examples by Type

Backend Service

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

Frontend Service

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