[Feature] TDK CLI integration: run a TanStack app as a local TDK resource #520

Which project does this relate to?

Create Tanstack App

Describe the feature

1. TanStack/cli issue

Project: Create Tanstack App

Labels: enhancement

Describe the feature

Add a documented, optional way to use a TanStack CLI app inside a TDK CLI landscape, and a small add-on that makes that handoff explicit.

TDK CLI (Tilt Development Kit, @tdk-landscape/tdk-cli-core) is a local multi-service runner. It is not a deploy and not a Compose file. Each service has a service.json. tdk up <stack> starts that slice with Docker + Tilt, health-checked boot order, and *.localhost routing. Frontends today are Vite SPAs (react default, vue optional). TDK owns the generated Vite config (.autogenerated/vite.config.frontend.autogenerated.ts) and does not want a root vite.config.ts from the framework provider.

TanStack CLI and TDK CLI solve different problems:

There is no shared contract today. A TanStack app dropped into a TDK repo does not get a service.json, and tdk resource --type frontend cannot scaffold TanStack Router or Start.

Requested outcome: one recipe that works from either CLI, with Router-only as the first supported path and Start as an explicit second path.

Proposed use

From an existing TDK project:

tdk project --yes
tdk resource shop-web --type frontend --framework tanstack-router --stack shop --yes
tdk resource orders-api --type backend --stack shop --yes
tdk up shop

From TanStack CLI, opt in with an add-on instead of a new required flag:

tanstack create shop-web --router-only --add-ons tdk -y
# later, inside a TDK project:
tdk up shop

Start stays available, but not by pretending it is the current Vite SPA provider:

# phase 2 — Start dev server is brought in, TDK does not rewrite vite.config.ts
tanstack create shop-web --blank --add-ons tdk -y
tdk resource shop-web --type bring-your-own --stack shop

What the TanStack add-on should write

Category tooling. No runtime dependency on TDK inside the generated app.

• service.json with type: "frontend", framework, stack, and the port convention TDK already uses (frontends in 3000–3999).
• A short TDK.md (or a section in the generated README) with install, tdk up, and the boundary: TDK is local only; deploy stays on the TanStack deployment add-on (Cloudflare, Netlify, and so on).
• package.json script hints only, for example "dev:tdk": "tdk up" when the CLI is present. Do not fail pnpm dev if TDK is not installed.
• Nothing that overwrites TanStack Start’s vite.config.ts in v1.

Router-only maps cleanly onto TDK’s provider contract (Vite SPA, no root vite.config.ts, starter index.html + entry). Start does not: Start owns Vite config and is SSR. Shipping Start as a normal --framework provider would fight both generators. Call that out in the issue so it is not implemented as a drive-by.

Acceptance

• Docs page: “Use with TDK CLI”, linked from TanStack CLI docs and from the add-on details (tanstack create --addon-details tdk).
• --router-only --add-ons tdk produces a service.json that tdk config verify accepts once the TDK provider exists.
• --blank / Start + tdk documents the bring-your-own path and does not emit a provider framework id TDK will reject.
• Add-on is optional. Default tanstack create is unchanged.
• JSON introspection includes the add-on (--list-add-ons --json).

Additional context

TDK frontend provider contract: https://github.com/tdk-landscape/tdk-cli-core/blob/main/docs/frontend-framework-providers.md

Relevant TDK commands:

tdk resource my-app --type frontend --stack api
tdk resource my-vue-app --type frontend --framework vue --stack api

framework is an enum on service.json (react, vue today). Unknown ids are rejected before files are written. A TanStack provider has to be registered in TDK (cli/src/frontend-frameworks/, Starlark Vite templates, service-schema.json). That half belongs in tdk-landscape/tdk-cli-core; companion issue linked below.

Companion issue (file against TDK, link here): feat(frontend) tanstack-router provider, and a TanStack Start bring-your-own path.

Non-goals:

• Replacing TanStack deployment add-ons with TDK. TDK does not deploy.
• Making TDK a required toolchain.
• Teaching TDK’s React/Ink CLI UI about TanStack. This is about generated apps and service.json, not the TDK terminal UI.

Additional context

linked issue tdk-landscape/tdk-cli-core#234