RFC: Upstream ArkEnv add-on to TanStack CLI (@tanstack/create) & Rsbuild compatibility

[yamcodes]

Summary

ArkEnv now provides an official TanStack CLI add-on, allowing developers to scaffold a fresh TanStack Start application with ArkEnv configured out of the box:

npx @tanstack/cli create my-app --add-ons https://arkenv.js.org/tanstack/info.json

This RFC discusses the roadmap to submit ArkEnv as an official built-in catalog add-on directly to TanStack/cli (npx @tanstack/cli create my-app --add-ons arkenv), our release timing strategy (graduating from v1 alpha to GA), and alignment with emerging Rsbuild bundler support in the TanStack CLI.

---

Current State (Hosted Remote Add-on)

ArkEnv's add-on is maintained inside the monorepo at packages/tanstack-addon and compiled to https://arkenv.js.org/tanstack/info.json:

• Multi-Validator Support: Offers an interactive engine selector (ArkType recommended default, Zod, or Valibot via @arkenv/standard).
• Convention-Aligned Scaffolding: Configures @arkenv/vite-plugin in vite.config.ts, creates src/env.ts, .env.example, and optionally includes a demo route at /demo/arkenv that tests client secret leak protection.
• Zero Drift: The add-on is compiled and tested continuously in Turborepo CI against TanStack's AddOnCompiledSchema.

---

Preconditions for the Upstream PR to TanStack/cli

To ensure maximum stability and open-source etiquette, we are queuing the upstream PR until two conditions are met:

1. ArkEnv v1 GA Graduation:
   Built-in add-ons in TanStack CLI live directly in the @tanstack/cli npm bundle. They should reference stable GA packages on npm, not active pre-release alphas (@alpha). Once ArkEnv v1.0.0 GA is published, the template dependencies will be locked to canonical releases.

2. Canonical URLs and Branding:
   The add-on metadata permanently links to https://arkenv.js.org. No temporary or preview domains will ever appear upstream.

3. Rsbuild Bundler Alignment (TanStack/cli#505):

   • TanStack Start officially supports both Vite and Rsbuild.
   • Currently, @tanstack/create scaffolds Vite projects exclusively.
   • However, TanStack/cli#505 is actively adding --bundler (Vite / Rsbuild) support to the CLI, reviewed by Rsbuild project lead @chenjiahan.
   • Once Document Standard Schema validator support #505 lands, ArkEnv is uniquely positioned to support both bundlers natively via @arkenv/vite-plugin and @arkenv/rsbuild-plugin.

---

Reference

A full evaluation note covering all design layers (Packaging, Distribution, Validator engines, Demo scope, and Bundlers) lives in the repository at docs/design/tanstack-cli-addon.md.

---

Feedback Welcome

We welcome feedback from the TanStack community, early adopters, and build tool maintainers:

• What starter environment variables or demo scenarios are most helpful in new TanStack Start projects?
• Are there specific Rsbuild integration hooks you would like to see when TanStack CLI adds first-class Rsbuild scaffolding?