Before your local stack starts, TDK CLI checks the host, the generated files, the migration order, and the port choices. Here is what each check catches and why it matters.
Most local stacks fail the same way. You run the start command, something breaks ten seconds in, and the error is three layers away from the cause. A port is taken. A file was hand-edited. A migration ran before the database was ready. You spend the next hour finding the one line that caused it.
TDK CLI takes a different approach. It checks the common causes before anything starts. Here are five of those checks, what each one catches, and how to read the result.
1. Can this machine run the stack at all?
tdk doctor --json reports the host type, whether a container runtime is reachable, and a flag called canUp. The host types it knows are local, wsl2, devcontainer, codespaces, webcontainer, and native-windows.
canUp is false when tdk up cannot work here. On a WebContainer there is no Docker daemon. On native Windows, the stack refuses to start unless you set TDK_ALLOW_NATIVE_WINDOWS=1. When no container runtime answers, the answer is the same.
The point is that the question is answered before you try. A false canUp tells you the problem is the machine, not your code.
2. Has any generated file been hand-edited?
Each service writes its runtime files under .autogenerated/, including the Dockerfile, the routing config, and the Vite configs. TDK also saves a snapshot of each file under .autogenerated/.tdk-contract/.
Before Tilt starts, tdk up compares the current files with those snapshots. If you changed one by hand, startup stops and the message names the file. tdk up --dry-run runs the same comparison without starting anything.
The fix is almost always the same: edit service.json, or the generator, and run tdk up again. A hand edit would be overwritten on the next generation anyway, so the check saves you from losing it silently.
3. Does the database run before the code that needs it?
The contributor rules for the repo say that new examples run database migrations in a separate migrator resource, not in the API's own startup. The order is Postgres, then the migrator, then the API.
tdk doctor backs that rule up. It warns when a backend or worker runs a migration command from its start script, its Dockerfile CMD or ENTRYPOINT, an entrypoint script, or its source.
This matters because a migration in a start script runs every time the container restarts, and it runs before anything has checked that the database is ready. Moving it into a resource with its own place in the order makes the sequence visible.
4. Do the ports clash?
Local stacks reserve several ports at once: the HTTP proxy, HTTPS, and Postgres. When 5432 is already taken by another database on your machine, TDK does not fail. It looks in a fallback range and picks a free port.
On my scratch project, Postgres wanted 5432, found it taken, and used 15432 from the fallback range of 15432 to 15532. The command printed that choice, and the overrides: TDK_POSTGRES_PORT, TDK_HTTP_PORT, and TDK_HTTPS_PORT. If you need a fixed port, set it explicitly and the stack uses it.
The result is printed on every start, so a changed port is never a surprise.
5. Which services will start, and in what order?
tdk up main --dry-run shows what would run without starting containers. It lists the services, their health URLs, the ports, and the Tilt command it would execute.
You can narrow the scope too. tdk up --only starts the named services and the services they depend on through dependsOn, plus any shared infrastructure. A service you did not ask for stays off.
Before you trust a change, you can see what it would start and check that the order matches what you expect.
Why this changes the first ten minutes
These checks do not fix your code. They make the failures appear in the place where you can fix them. A host problem shows up in doctor. A hand edit shows up before startup. A bad migration order shows up in the config, not in a log three layers down.
If you read one habit from this list, make it the dry run. Run tdk up --dry-run, read the plan, and then start the stack. Most surprises are visible before any container is built.
Try it
npm install -g @tdk-landscape/tdk-cli-core
tdk doctor --json
tdk up main --dry-run
Read the canUp value and the dry-run plan. If both look right, run tdk up and watch tdk status --json until readiness is true. The TDK CLI README has the full command list.
Top comments (0)