The earlier sequence diagram followed tdk up. This one follows the command you run before any of that: tdk resource, which creates a new service. It is the step where a project gets its first source files, so it is worth knowing what happens in order.
The steps below follow what I saw when I ran the command in a scratch project, and the provider and template structure in the repo. The messages are summaries of real output, so check exact wording against your version.
The sequence
sequenceDiagram
autonumber
actor Dev as Developer
participant CLI as tdk CLI (TypeScript)
participant Root as Project root finder
participant Prov as Framework or language provider
participant Tpl as Templates and generator
participant FS as Project folder on disk
participant Disc as Discovery paths in .tdk/project.json
Dev->>CLI: tdk resource storefront-web --type frontend -y
CLI->>Root: find .tdk/project.json from here upward
alt no project found
Root-->>CLI: not found
CLI-->>Dev: error, run tdk project --yes first
else project found
Root-->>CLI: project root and config
CLI->>CLI: validate name, type, framework, and stack
CLI->>Prov: ask for starter files for the chosen framework
Prov-->>CLI: package.json, entry file, component, test, tsconfig
CLI->>Tpl: fill the Dockerfile and service.json
Tpl-->>CLI: rendered files
CLI->>Disc: check the target path against discovery paths
alt path outside discovery
Disc-->>CLI: services/*/* is the default, apps/ is not scanned
CLI->>FS: place the resource under services/<stack>/<name>
CLI-->>Dev: placed here instead of apps/, use --path to choose
else path inside discovery
CLI->>FS: write files under the chosen folder
end
FS-->>CLI: files written
CLI-->>Dev: resource created, next steps: bun install, tdk up <stack>
end
Note over Dev,FS: Generated runtime files under .autogenerated are not written here
Dev->>CLI: tdk up main --dry-run
CLI-->>Dev: plan shows the new service, no containers startedThe steps that matter
The project root. The command searches upward for .tdk/project.json. Run it outside a project and it stops with a clear message, and the fix is tdk project --yes first. Creating a project and adding a resource are separate steps.
The checks. The CLI validates the name, the resource type, the framework, and the stack before it writes anything. A bad combination is rejected here, not after files have been created.
The provider. The framework or language provider owns the starter files: a package.json, an entry file, a component, and a test for a frontend. TypeScript providers write these, not templates. This is why the frontend scaffold and the Rust scaffold look different.
The placement check. This is the step that surprised me most. The command compares the target folder with the discovery paths in .tdk/project.json. In the default setup those paths are services/*/*, so a resource requested under apps/ would never be started by tdk up. The CLI places it under services/<stack>/<name> and tells you why. The --path option overrides the choice.
The files on disk. The resource folder receives its source files and a service.json. The runtime files are not written here. They appear later, when Tilt loads the project and the engine generates the .autogenerated folder.
Where to look next
After the command, tdk up main --dry-run shows the new service in the plan without starting containers. The first sequence diagram covers what happens at that point.
Common surprises
-
The resource is not where you asked. Check the message for the placement reason, and use
--pathif you need another location. -
tdk updoes not see the new service. Check that the folder is inside a discovery path. - The frontend needs its dependencies installed. The next-steps output says so. Run the install before the first start.
Summary
tdk resource is a short chain: find the project, check the inputs, ask a provider for starter files, render the manifest, check the placement, and write the folder. Most surprises come from the placement step, so read its message before you assume the files went where you wanted.
