feat(tanstack): upstream catalog add-on to TanStack/cli

[yamcodes]

Summary

Submit @arkenv/tanstack-addon as an official built-in catalog add-on directly to the TanStack/cli repository (packages/create/src/frameworks/react/add-ons/arkenv), enabling developers to scaffold TanStack Start applications via:

npx @tanstack/cli create my-app --add-ons arkenv

Context & RFC

• Public RFC Discussion: #1817
• Design Note: docs/design/tanstack-cli-addon.md
• Current Live Add-on: Available today via https://arkenv.js.org/tanstack/info.json (compiled from packages/tanstack-addon).

Blocking Preconditions

This issue is marked blocked pending two external milestones:

1. ArkEnv v1 GA Graduation:
   • Wait until 1.0.0 GA packages (@arkenv/core, @arkenv/standard, @arkenv/vite-plugin, @arkenv/rsbuild-plugin) are published on npm under the latest tag (no @alpha).
   • Tear down the temporary /tanstack/* proxy rewrite in apps/www/next.config.ts on main so apps/www/public/tanstack/ serves natively.
2. Upstream Bundler Alignment (TanStack/cli#505):
   • Monitor TanStack/cli#505 (adding first-class --bundler / --build-tool Vite & Rsbuild support to @tanstack/create).
   • If Document Standard Schema validator support #505 is merged, adapt template dependencies/integrations to support both @arkenv/vite-plugin and @arkenv/rsbuild-plugin.

Acceptance Criteria

• Submit PR to TanStack/cli adding packages/create/src/frameworks/react/add-ons/arkenv containing info.json, package.json.ejs, README.md, and assets/.
• Dependencies point to stable GA releases (e.g. ^1.0.0).
• Verify npx @tanstack/cli create test-app --add-ons arkenv successfully runs interactively with validator selection (ArkType, Zod, Valibot) and optional demo route.
• Update ArkEnv documentation in apps/www/content/docs/frameworks/tanstack-start.mdx to feature the bare identifier npx @tanstack/cli create my-app --add-ons arkenv.

[pullfrog]

Analysis — not actionable yet; both blocking preconditions are unmet

I checked the two external gates named in the issue body against their live sources. Neither has cleared, so this stays blocked. Full implementation should wait; here's the verified state and a ready-to-run plan for when the gates open.

Verified state of the blocking preconditions

1. ArkEnv v1 GA graduation — NOT met. npm dist-tags today:

package	latest tag	notes
@arkenv/core	1.0.0-alpha.10	v1 line only on alpha
@arkenv/standard	1.0.0-alpha.10	v1 line only on alpha
@arkenv/vite-plugin	0.1.6	that's still the v0 line; v1 ships as 1.0.0-alpha.15 under alpha
@arkenv/rsbuild-plugin	1.0.0-alpha.1	v1 line only on alpha

None are 1.0.0 GA on latest, so acceptance criterion #2 ("dependencies point to stable GA releases, e.g. ^1.0.0") cannot be satisfied — packages/tanstack-addon/.add-on/package.json.ejs still emits ^1.0.0-alpha.1 ranges. The /tanstack/:path* proxy rewrite in apps/www/next.config.ts (marked TODO(v1-ga)) is also still present on the current default branch, and apps/www/public/tanstack/ is only committed on v1, not on the stable line — so the tear-down half of precondition 1 hasn't happened either.

2. TanStack/cli#505 (Rsbuild bundler support) — NOT merged. PR is open, merged: false, mergeable_state: dirty, last updated 2026-08-27. Until it lands, folding @arkenv/rsbuild-plugin into the catalog add-on is premature.

Additional gotcha to fold into the eventual work

Per repo knowledge from the existing add-on work: at @tanstack/create@0.70 / @tanstack/cli@0.71 (what packages/tanstack-addon pins), the remote add-on flow (--add-ons <url>) is non-interactive — option values fall back to defaults, no validator/demo prompt. Acceptance criterion #3 (interactive validator + demo selection) only applies to a built-in catalog add-on, so it must be verified against the @tanstack/cli version current at merge time (re-pin @tanstack/create in devDeps if it has moved), and built-in add-ons use a different option key path (addOnOption['arkenv'] resolves for the catalog id, unlike remote URLs) which the templates already handle via the fallback lookup.

Plan for when both gates clear

1. After v1 GA publish (@arkenv/core, @arkenv/standard, @arkenv/vite-plugin, @arkenv/rsbuild-plugin all 1.0.0 on latest):
   • Flip package.json.ejs ranges from ^1.0.0-alpha.1 to ^1.0.0.
   • Tear down the /tanstack/:path* rewrite in apps/www/next.config.ts and commit the apps/www/public/tanstack/ mirror on the stable branch via packages/tanstack-addon/scripts/build.ts so arkenv.js.org serves it natively.
2. After feat(create): add Rsbuild as a bundler option TanStack/cli#505 merges (or, if it stalls, decide explicitly whether to ship Vite-only and add Rsbuild as a follow-up): add a bundler option (vite | rsbuild) that swaps @arkenv/vite-plugin ↔ @arkenv/rsbuild-plugin and the VITE_ ↔ PUBLIC_ prefix in templates.
3. Assemble the catalog directory matching TanStack's built-in shape (packages/create/src/frameworks/react/add-ons/arkenv/: info.json, package.json.ejs, README.md, assets/ — cf. the t3env reference, which also carries package.json + small-logo.svg), sourced from packages/tanstack-addon; keep it compiled/tested in Turborepo CI (tests/compile.test.ts, tests/templates.test.ts already exist).
4. Open the upstream PR to TanStack/cli with those assets and GA version ranges.
5. Verify npx @tanstack/cli create test-app --add-ons arkenv with validator selection and optional demo route.
6. Docs: update apps/www/content/docs/frameworks/tanstack-start.mdx to headline the bare npx @tanstack/cli create my-app --add-ons arkenv. Coordinate this with the upstream merge (the bare identifier only resolves once the catalog add-on ships); keep the URL form as the fallback until then.
7. Label hygiene: drop blocked only when both gates are confirmed — npm latest on all four packages and TanStack/cli#505 merged (or an explicit decision to ship Vite-only).

Suggested next step: keep this issue open and blocked, and re-trigger planning when either gate flips. Recommended re-check point: a v1 GA release announcement / 1.0.0 on npm latest.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}