add-a-service

Add a service

A services/* package is anything with a URL or its own deploy — an HTTP server, a webhook receiver, or a background worker (which has no URL but still runs as its own process). Use this when a new surface needs to run independently.

When to use

• New HTTP endpoint group that deserves its own process/deploy → new service.
• New background consumer (queue worker, cron) → new service (no URL, still a Tilt resource).
• Not for shared logic with no runtime of its own — that's a lib.

Steps

1. Name it. services/<name>, package @stack/<name>. No pinned port — served roles run behind Portless at <name>.stack.localhost:1355 (Portless injects a random PORT). See docs/portless.md.

2. Files:

   services/<name>/
   ├── package.json
   ├── tsconfig.json
   └── src/
       ├── index.ts        # entrypoint: start the server / worker
       └── <feature>/      # organize BY FEATURE, not by layer
   

3. package.json — a dev script Tilt will call:

   {
     "name": "@stack/<name>",
     "private": true,
     "type": "module",
     "scripts": {
       "dev": "bun --hot src/index.ts",
       "start": "bun src/index.ts",
       "typecheck": "bash ../../scripts/typecheck-native.sh --noEmit"
     }
   }
   

4. tsconfig.json: { "extends": "../../tsconfig.base.json", "include": ["src"] }

5. src/index.ts — Hono for HTTP; read the port from process.env.PORT (Portless injects it — never hardcode). Always expose /health:

   import { Hono } from "hono";
   const app = new Hono();
   app.get("/health", (c) => c.json({ ok: true }));
   const port = Number(process.env.PORT ?? 3003); // fallback only for standalone runs
   export default { port, fetch: app.fetch };
   

   For a background worker there's no server — just start the consumer loop and log readiness. No /health, no port (no Portless wrapper either — see ai-worker in the Tiltfile).

6. Persistence via @stack/db only. Payments via @stack/payment only. Never import another service's internals — talk over HTTP.