A backend in TDK CLI Core is a service with a health route, a port read from the environment, and a place in the start order. Those basics are generated, so the work you do is the API itself. This article covers the choices you make and the one rule that saves the most debugging time.
Choosing a language
The default backend is Bun with Hono. TDK also supports other languages through the --language flag: Go, Python, and Rust are explicit, opt-in providers, and node is listed as a language option too. Omitting the flag gives the default. Existing projects are not affected by these options.
Go, Python, and Rust own their runtime, so a framework cannot be combined with them. Pick the language, then the scaffold it provides.
Choosing a framework
On the Bun runtime, the frameworks are Hono (the default), Express, Elysia, Fastify, NestJS, Koa, and h3. The framework is saved in service.json. Pick the one your team already knows, because the generated setup is the same for each, and the code you write is the part that varies.
What is generated
Every backend gets a health route, a port read from the environment, and a bind address that accepts traffic from the proxy. It also gets a Dockerfile and a service.json entry. You write the routes, the data access, and the tests.
The migration rule
This is the rule that saves the most time. Migrations run in their own resource, ordered after Postgres and before the API. They do not run in the API's startup path.
The reason is repeatability. A migration in a start script runs on every restart. Two instances can run it at once. And the API may start before the schema is ready. A separate migrator resource runs once, in order, and the API starts only after it succeeds.
tdk doctor warns when a backend or worker runs a migration command from its start script, Dockerfile CMD or ENTRYPOINT, an entrypoint script, or its source. Treat that warning as a real finding, not as noise.
Health and readiness
The health route should report readiness, not just that the process is alive. Keep it cheap, and do not make it depend on a slow query. tdk status --json reports whether each service is ready, so you can see the result without guessing.
Testing
The generated services include a test file as a starting point. Add tests for the behaviour you care about, and run them before you rely on the stack. A passing test that exercises a route is more useful than a health check alone.
Summary
A TDK backend starts with the plumbing done: a health route, a port from the environment, and a place in the start order. Pick a language and framework, put migrations in their own ordered step, and keep the health check honest.
Top comments (0)