I Read TDK's Starlark Engine So You Don't Have To

Most people who open the TDK CLI repo see TypeScript first. The CLI is written in TypeScript, and that is where the commands live. But the part that decides what your local stack looks like is written in Starlark, the Python-like language that Tilt uses. If you want to change what gets generated, you end up there.

This post is a map of that part. I read the maintainer guide and the engine layout in the tdk-cli-core repo, and this is what I found. I have not written an engine change of my own, so treat the steps below as a reading guide, not a tested recipe.

Two stages, two languages

The repo's maintainer guide splits generation into two stages:

1. CLI time, in TypeScript. When you run tdk project or tdk resource, the CLI copies a starter and writes your first source files and service.json. Project-level files come from Handlebars templates.
2. Tilt time, in Starlark. When Tilt loads the project's Tiltfile, Starlark reads every service.json, works out the resources, and writes the per-service files under .autogenerated/.

The guide puts it plainly: the CLI sets up the project, and the Tilt engine derives the runtime configuration. The two are connected, but they are not interchangeable.

That split matters for where you edit. A bug in a generated Dockerfile is almost always a Starlark bug, not a template bug.

Starlark is the generator, not a template

This is the detail that trips people up. The docs say that Starlark is the generator implementation language here, and it is not a template-file extension. The modules build the output content in code and write it through Tilt's filesystem helpers.

So you will not find a Dockerfile.hbs for a service. You will find a .star module that builds the Dockerfile text as a string. The same goes for the Vite config, the TypeScript configs, the Prisma config, the package-manager config, and the frontend API helpers. Some of those outputs are TypeScript files or JSON, but they are still produced by Starlark.

Where things live

The table from the maintainer guide is the one to keep open:

• engine/topologies/tilt/generators/ holds the per-file generators: Vite, TypeScript, Docker and package configs, environment files, and the agent guidance file. Start with index.star there.
• engine/topologies/tilt/resources/ declares the Tilt resources, their start order, their dependencies, and their triggers.
• engine/topologies/tilt/manifest/ loads and maps the manifests, and holds the schema and constants.
• engine/topologies/platform/ holds the shared building blocks such as Docker and networking.
• discovery/ scans the service.json files and builds the resource registry.
• The root Tiltfile wires discovery, the engine, and the extensions together.

The engine also has a .tilt-engine/ folder with its own README. That README is partly out of date, so check any path it names against engine/topologies/ before you rely on it.

The rule that saves you an afternoon

The generated files start with a header that says not to edit them. That header is accurate. The guide says to edit the inputs or the generator, never the outputs. Each generated file names its generator in that header, so you can find the module that wrote it.

If you hand-edit .autogenerated/, tdk up notices. It compares each file with a snapshot before Tilt starts, and a hand edit blocks startup and names the file. So the fix is always upstream: change the Starlark generator, or change service.json.

Debugging without guessing

When a generator misbehaves, the repo gives you a switch. Set TDK_DEBUG=1 and run tdk up --verbose, and the Starlark debug logs appear in the Tilt output.

For a quick check that does not start containers, use tdk up main --dry-run. It shows the services, the ports, and the exact Tilt command, which tells you the generation ran and what it would start.

The contributing guide has a recipe for changing the engine or discovery. Read that before you touch the generators, because it names the checks the repo expects.

Where to start contributing

If you want to read the engine without changing it yet, the Hacktoberfest issues are a good way in. A few that touch this area:

• #1131: map the Starlark topology module boundaries. Write a current map of the topology modules. It is a documentation task, and writing the map forces you to read every module.
• #1177: add tests for the Compose helper paths in Starlark. Adds tests for helper code that already works, so you learn the Starlark without changing behaviour.
• #1128: move migrator Compose generation into a focused module. A refactor with clear boundaries, good for seeing how a generator is split.

Before you open a pull request, sign off every commit with git commit -s. The repo checks the Developer Certificate of Origin line on every commit.

What I'd still want to know

I have not run a Starlark change through the full test suite, and I have not measured how long a generation takes on a large project. Those are the questions I would answer before recommending the engine for a team with many services. If you run them first, tell the repo what you found.