feat: upstream TanStack CLI catalog add-on prep - #1978
Merged
Merged
Conversation
Scaffolded apps install @arkenv/core, @arkenv/standard, and @arkenv/vite-plugin at ^1.0.0-rc.2, and the TanStack Start docs lead with the catalog id. Co-authored-by: Yam Borodetsky <hi@yam.codes>
🦋 Changeset detectedLatest commit: 49ac8c4 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
yamcodes
added
docs
Cursor
@arkenv/agent-plugin
arkenv
@arkenv/build
@arkenv/bun-plugin
@arkenv/core
@arkenv/fumadocs-ui
@arkenv/nextjs
@arkenv/nuxt
@arkenv/rsbuild-plugin
@arkenv/standard
@arkenv/tanstack-addon
@arkenv/vite-plugin
commit: |
github-actions
Bot
added
the
tests
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
ℹ️ No critical issues — one sequencing note and a small test-coverage nit.
Reviewed changes
- Repoint scaffolded deps to rc —
@arkenv/core,@arkenv/standard, and@arkenv/vite-pluginnow pin^1.0.0-rc.2in.add-on/package.json.ejs,.add-on/info.json, and the committedapps/www/public/tanstack/mirror. Confirmed npmlatestis1.0.0-rc.2for all three, and^1.0.0-rc.2does accept1.0.0on GA. - Bump add-on metadata version —
info.jsonversionmoves1.0.0-alpha.1→1.0.0-rc.2; thepatchchangeset moves the@arkenv/tanstack-addonpackage to rc.2 to match. - Docs quickstart — TanStack Start page now leads with
--add-ons arkenvand adds an "Older CLI builds" callout for the hosted URL. - READMEs — package README leads with the catalog id; new
.add-on/README.mdis the catalog README for upstreaming (shape matches upstreamt3env, and#/envmatches the CLI base template's#/*alias). - Test pinning — default-branch assertions now pin the two versions instead of
toBeDefined().
Technical details
# Docs lead with a catalog id that isn't upstreamed yet
## Affected sites
- apps/www/content/docs/frameworks/tanstack-start.mdx:33 — quickstart leads with `--add-ons arkenv`
- packages/tanstack-addon/README.md:10 — same
- packages/tanstack-addon/.add-on/README.md — does not mention the catalog-id gating
## Required outcome
- No code change required. Confirm the hosted-URL fallback stays prominent until the
catalog entry ships in a released `@tanstack/cli`.
## Open questions for the human
- Per the PR body, TanStack/cli#505 is open and the catalog PR could not even be
opened, so `--add-ons arkenv` errors on every currently released CLI. The
"Older CLI builds" callout covers the fallback, but the primary command is a
copy-paste failure today. Do you want to lead with the hosted URL and demote the
catalog id to a "coming soon", or is shipping the future-state command acceptable
because the site deploys on merge and the callout is adjacent?DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
- Autofix-only delta —
[autofix.ci] apply automated fixes(ba302ced) reformatted the bare docs URL inpackages/tanstack-addon/.add-on/README.mdinto a markdown link; no other file changed sinceddd5c703. The full PR remains as summarized: rc.2 dependency pins across the add-on templates and theapps/www/public/tanstack/mirror, matchinginfo.jsonversion bump, docs quickstart + older-CLI callout, and the catalog README.
Prior review feedback (version pinning in the Zod/Valibot test branches; the catalog-id sequencing note) still stands and is not restated here.
DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
Zod, Valibot, and the remote URL path now assert the same ^1.0.0-rc.2 range as the ArkType default. Co-authored-by: Yam Borodetsky <hi@yam.codes>
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
- Expanded version-pin test coverage — the Zod, Valibot, and remote-URL cases in
packages/tanstack-addon/tests/templates.test.tsnow assert@arkenv/standardand@arkenv/vite-pluginagainst the shared^1.0.0-rc.2range, closing the prior default-branch-only gap so a partial future bump can no longer slip through. - Extracted a shared
ARKENV_RANGEconst — the expected range now lives in one documented constant (templates.test.ts:25) reused across all fourpackage.json.ejsassertions.
The prior thread (Zod/Valibot coverage) is addressed and resolved; the catalog-id sequencing note remains as the author chose, with the hosted-URL fallback adjacent.
DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
The bare arkenv catalog id is not in a released CLI yet, so the changelog example uses the hosted add-on URL. Co-authored-by: Yam Borodetsky <hi@yam.codes>
The bare arkenv catalog id is not in the published CLI, so the docs and package README show the URL that works today. Co-authored-by: Yam Borodetsky <hi@yam.codes>
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
- Docs quickstart leads with the hosted URL —
apps/www/content/docs/frameworks/tanstack-start.mdx:33now showsnpx @tanstack/cli create my-app --add-ons https://arkenv.js.org/tanstack/info.jsonas the primary command. The "Older CLI builds" callout is replaced by a "No catalog id yet" callout (:36) that states@tanstack/clihas noarkenvadd-on and--add-ons arkenvfails, pointing back at the URL above. - Package README mirrors the same ordering —
packages/tanstack-addon/README.md:10leads with the hosted URL and adds a one-line note that--add-ons arkenvfails until the catalog id ships; the existing-projecttanstack add <url>path is unchanged.
This resolves the prior review's sequencing concern: the docs and READMEs now lead with the command that works on every currently released @tanstack/cli, rather than a future-state id. The packages/tanstack-addon/.add-on/README.md catalog README intentionally omits the gating note since it is only served once the catalog exists. No behavioral surface changed.
DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
Merged
yamcodes
pushed a commit
that referenced
this pull request
Sep 25, 2026
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to v1, this PR will be updated.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ `v1` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `v1`.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ # Releases ## @arkenv/build@1.0.0-rc.3 ### Major Changes - #### Remove the SharedSchema key extractors _[`#2011`](#2011) [`9483c3c`](9483c3c) [@yamcodes](https://github.com/yamcodes)_ `extractSharedKeys` and `extractSharedBlock` are no longer exported from `@arkenv/build`. `@arkenv/nextjs/config` and `@arkenv/nuxt` (including `@arkenv/nuxt/standard/config`) no longer re-export `extractSharedKeys`. Shared keys in a flat `arkenv()` call still come from `extractKeys` and `classifyEnvKeys`. **BREAKING CHANGE**: Those helpers scanned source for a `SharedSchema = { ... }` assignment. Classify a flat `arkenv()` call instead. ```ts import { classifyEnvKeys } from "@arkenv/build"; const { sharedKeys } = classifyEnvKeys(source, ["NEXT_PUBLIC_"]); ``` ### Patch Changes - #### Reject runtime keys in the plugin option guard _[`#2012`](#2012) [`87f3743`](87f3743) [@yamcodes](https://github.com/yamcodes)_ The shared transform-option guard now treats `env`, `coerce`, `onUndeclaredKey`, `arrayFormat`, `emptyAsUndefined`, `debugSecrets`, and `toJsonSchema` as unsupported plugin options. The build reads the loaded environment. ## @arkenv/bun-plugin@1.0.0-rc.3 ### Major Changes - #### Export only `arkenvPlugin` from the Bun plugin _[`#2015`](#2015) [`7417dd7`](7417dd7) [@yamcodes](https://github.com/yamcodes)_ `@arkenv/bun-plugin` and `@arkenv/bun-plugin/standard` now export `arkenvPlugin` as the default and the only named export. The `arkenvBunPlugin` and `hybrid` aliases have been removed. `arkenvPlugin` is still both a factory and a plugin object with `name`, `target`, and `setup`. ```ts import arkenvPlugin from "@arkenv/bun-plugin"; await Bun.build({ plugins: [arkenvPlugin], }); ``` **BREAKING CHANGE**: `arkenvBunPlugin` and `hybrid` are no longer exported. Use `arkenvPlugin` instead. - #### Reject runtime options on bundler plugins _[`#2012`](#2012) [`87f3743`](87f3743) [@yamcodes](https://github.com/yamcodes)_ Vite, Bun, and Rsbuild plugins now accept only `schemaPath`, `clientPrefix`, `logger`, and `logLevel`. The build validates the environment loaded for that compile. Variables already set on `process.env` win over env files. ```ts import { arkenvPlugin } from "@arkenv/vite-plugin"; export default { plugins: [arkenvPlugin({ schemaPath: "src/env.ts" })], }; ``` Set `env`, `coerce`, `onUndeclaredKey`, `arrayFormat`, `emptyAsUndefined`, `debugSecrets`, and `toJsonSchema` on `arkenv()` in `env.ts`. The plugin rejects those keys. ```ts import arkenv from "@arkenv/core"; export const env = arkenv( { PORT: "number" }, { coerce: true, onUndeclaredKey: "reject" }, ); ``` **BREAKING CHANGE**: Plugin option types no longer include runtime `arkenv()` fields, including `env`. Passing them now throws. ```diff - arkenvPlugin({ env: { PORT: "3000" }, coerce: true }) + arkenvPlugin({ schemaPath: "src/env.ts" }) ``` ### Patch Changes <details><summary>Updated 3 dependencies</summary> <small> [`87f3743`](87f3743) [`9483c3c`](9483c3c) [`089ef43`](089ef43) </small> - `@arkenv/build@1.0.0-rc.3` - `@arkenv/core@1.0.0-rc.3` - `@arkenv/standard@1.0.0-rc.3` </details> ## @arkenv/nextjs@1.0.0-rc.3 ### Major Changes - #### Remove the SharedSchema key extractors _[`#2011`](#2011) [`9483c3c`](9483c3c) [@yamcodes](https://github.com/yamcodes)_ `extractSharedKeys` and `extractSharedBlock` are no longer exported from `@arkenv/build`. `@arkenv/nextjs/config` and `@arkenv/nuxt` (including `@arkenv/nuxt/standard/config`) no longer re-export `extractSharedKeys`. Shared keys in a flat `arkenv()` call still come from `extractKeys` and `classifyEnvKeys`. **BREAKING CHANGE**: Those helpers scanned source for a `SharedSchema = { ... }` assignment. Classify a flat `arkenv()` call instead. ```ts import { classifyEnvKeys } from "@arkenv/build"; const { sharedKeys } = classifyEnvKeys(source, ["NEXT_PUBLIC_"]); ``` ### Patch Changes <details><summary>Updated 3 dependencies</summary> <small> [`87f3743`](87f3743) [`9483c3c`](9483c3c) [`089ef43`](089ef43) </small> - `@arkenv/build@1.0.0-rc.3` - `@arkenv/core@1.0.0-rc.3` - `@arkenv/standard@1.0.0-rc.3` </details> ## @arkenv/nuxt@1.0.0-rc.3 ### Major Changes - #### Remove the SharedSchema key extractors _[`#2011`](#2011) [`9483c3c`](9483c3c) [@yamcodes](https://github.com/yamcodes)_ `extractSharedKeys` and `extractSharedBlock` are no longer exported from `@arkenv/build`. `@arkenv/nextjs/config` and `@arkenv/nuxt` (including `@arkenv/nuxt/standard/config`) no longer re-export `extractSharedKeys`. Shared keys in a flat `arkenv()` call still come from `extractKeys` and `classifyEnvKeys`. **BREAKING CHANGE**: Those helpers scanned source for a `SharedSchema = { ... }` assignment. Classify a flat `arkenv()` call instead. ```ts import { classifyEnvKeys } from "@arkenv/build"; const { sharedKeys } = classifyEnvKeys(source, ["NEXT_PUBLIC_"]); ``` ### Patch Changes <details><summary>Updated 3 dependencies</summary> <small> [`87f3743`](87f3743) [`9483c3c`](9483c3c) [`089ef43`](089ef43) </small> - `@arkenv/build@1.0.0-rc.3` - `@arkenv/core@1.0.0-rc.3` - `@arkenv/standard@1.0.0-rc.3` </details> ## @arkenv/rsbuild-plugin@1.0.0-rc.3 ### Major Changes - #### Export only `arkenvPlugin` from the Rsbuild plugin _[`#2015`](#2015) [`7417dd7`](7417dd7) [@yamcodes](https://github.com/yamcodes)_ `@arkenv/rsbuild-plugin` and `@arkenv/rsbuild-plugin/standard` now export `arkenvPlugin` as the default and the only named export. The `arkenvRsbuildPlugin` alias has been removed. ```ts import { arkenvPlugin } from "@arkenv/rsbuild-plugin"; export default defineConfig({ plugins: [arkenvPlugin()], }); ``` **BREAKING CHANGE**: `arkenvRsbuildPlugin` is no longer exported. Import `arkenvPlugin` instead. - #### Reject runtime options on bundler plugins _[`#2012`](#2012) [`87f3743`](87f3743) [@yamcodes](https://github.com/yamcodes)_ Vite, Bun, and Rsbuild plugins now accept only `schemaPath`, `clientPrefix`, `logger`, and `logLevel`. The build validates the environment loaded for that compile. Variables already set on `process.env` win over env files. ```ts import { arkenvPlugin } from "@arkenv/vite-plugin"; export default { plugins: [arkenvPlugin({ schemaPath: "src/env.ts" })], }; ``` Set `env`, `coerce`, `onUndeclaredKey`, `arrayFormat`, `emptyAsUndefined`, `debugSecrets`, and `toJsonSchema` on `arkenv()` in `env.ts`. The plugin rejects those keys. ```ts import arkenv from "@arkenv/core"; export const env = arkenv( { PORT: "number" }, { coerce: true, onUndeclaredKey: "reject" }, ); ``` **BREAKING CHANGE**: Plugin option types no longer include runtime `arkenv()` fields, including `env`. Passing them now throws. ```diff - arkenvPlugin({ env: { PORT: "3000" }, coerce: true }) + arkenvPlugin({ schemaPath: "src/env.ts" }) ``` ### Patch Changes <details><summary>Updated 3 dependencies</summary> <small> [`87f3743`](87f3743) [`9483c3c`](9483c3c) [`089ef43`](089ef43) </small> - `@arkenv/build@1.0.0-rc.3` - `@arkenv/core@1.0.0-rc.3` - `@arkenv/standard@1.0.0-rc.3` </details> ## @arkenv/vite-plugin@1.0.0-rc.3 ### Major Changes - #### Export only `arkenvPlugin` from the Vite plugin _[`#2015`](#2015) [`7417dd7`](7417dd7) [@yamcodes](https://github.com/yamcodes)_ `@arkenv/vite-plugin` and `@arkenv/vite-plugin/standard` now export `arkenvPlugin` as the default and the only named export. The `arkenvVitePlugin` alias has been removed. ```ts import arkenvPlugin from "@arkenv/vite-plugin"; export default defineConfig({ plugins: [arkenvPlugin()], }); ``` **BREAKING CHANGE**: `arkenvVitePlugin` is no longer exported. Import `arkenvPlugin` instead. - #### Reject runtime options on bundler plugins _[`#2012`](#2012) [`87f3743`](87f3743) [@yamcodes](https://github.com/yamcodes)_ Vite, Bun, and Rsbuild plugins now accept only `schemaPath`, `clientPrefix`, `logger`, and `logLevel`. The build validates the environment loaded for that compile. Variables already set on `process.env` win over env files. ```ts import { arkenvPlugin } from "@arkenv/vite-plugin"; export default { plugins: [arkenvPlugin({ schemaPath: "src/env.ts" })], }; ``` Set `env`, `coerce`, `onUndeclaredKey`, `arrayFormat`, `emptyAsUndefined`, `debugSecrets`, and `toJsonSchema` on `arkenv()` in `env.ts`. The plugin rejects those keys. ```ts import arkenv from "@arkenv/core"; export const env = arkenv( { PORT: "number" }, { coerce: true, onUndeclaredKey: "reject" }, ); ``` **BREAKING CHANGE**: Plugin option types no longer include runtime `arkenv()` fields, including `env`. Passing them now throws. ```diff - arkenvPlugin({ env: { PORT: "3000" }, coerce: true }) + arkenvPlugin({ schemaPath: "src/env.ts" }) ``` ### Patch Changes <details><summary>Updated 3 dependencies</summary> <small> [`87f3743`](87f3743) [`9483c3c`](9483c3c) [`089ef43`](089ef43) </small> - `@arkenv/build@1.0.0-rc.3` - `@arkenv/core@1.0.0-rc.3` - `@arkenv/standard@1.0.0-rc.3` </details> ## arkenv@1.0.0-rc.3 ### Minor Changes - #### Stop installing the agent skill during init _[`#1984`](#1984) [`2c1dd0f`](2c1dd0f) [@yamcodes](https://github.com/yamcodes)_ `arkenv init` no longer prompts for or installs the ArkEnv agent skill, including under `--yes`. When the skill is not already in the project, the next-steps note still prints `npx skills add yamcodes/arkenv`. `@arkenv/agent-plugin` already includes the skill. - #### Scaffold `arkenvPlugin` in Vite and Rsbuild configs _[`#2015`](#2015) [`7417dd7`](7417dd7) [@yamcodes](https://github.com/yamcodes)_ `arkenv init` now writes `arkenvPlugin` into new Vite and Rsbuild config entries. Vite binds the default import as `arkenvPlugin`. Rsbuild imports the named `arkenvPlugin`. ```ts import arkenvPlugin from "@arkenv/vite-plugin"; export default defineConfig({ plugins: [arkenvPlugin()], }); ``` ### Patch Changes - #### Scaffold Zod and Valibot init on standard mode _[`#2020`](#2020) [`a3815e6`](a3815e6) [@yamcodes](https://github.com/yamcodes)_ `arkenv init` no longer installs `arktype` when you choose Zod or Valibot. Next.js, Nuxt, Vite, Rsbuild, and Bun now scaffold the `/standard` integration entry, and Next.js and Nuxt also install `@arkenv/standard`. ```ts import arkenv from "@arkenv/nuxt/standard"; import * as z from "zod"; export const env = arkenv({ DATABASE_URL: z.url(), }); ``` Re-running init replaces the other engine's entry. A Nuxt app that still registers `@arkenv/nuxt/module` switches to `@arkenv/nuxt/standard/module` when you choose Zod or Valibot, and the same replacement applies to the Next.js, Vite, and Rsbuild imports. Choosing ArkType switches those entries back. ArkType init is unchanged: it still installs `arktype` and uses the ArkType integration entry. ## @arkenv/agent-plugin@1.0.0-rc.2 ### Patch Changes - #### Parse audit sources with the TypeScript 7 sync API _[`#1990`](#1990) [`f3039bf`](f3039bf) [@yamcodes](https://github.com/yamcodes)_ The agent plugin audit now parses source files through `typescript/unstable/sync` instead of the classic TypeScript compiler API. - #### Point init refusals at nextActions _[`#1977`](#1977) [`dd2fa82`](dd2fa82) [@yamcodes](https://github.com/yamcodes)_ Agent instructions now tell you to retry only when a refusal's `nextActions` include a `run-command` with `--force`. ## @arkenv/core@1.0.0-rc.3 ### Patch Changes - #### Restore keyword suggestions inside inline schemas _[`#1975`](#1975) [`089ef43`](089ef43) [@yamcodes](https://github.com/yamcodes)_ A partial keyword in an inline schema string suggests ArkType keywords again. `arkenv({ PORT: "n" })` offers `never`, `null`, and `number`. The same suggestions are back on `arkenv` from `@arkenv/core/safe`. ```ts import arkenv from "@arkenv/core"; export const env = arkenv({ PORT: "number.port = 3000", }); ``` ## @arkenv/tanstack-addon@1.0.0-rc.2 ### Patch Changes - #### Scaffold `arkenvPlugin` in the TanStack add-on _[`#2015`](#2015) [`7417dd7`](7417dd7) [@yamcodes](https://github.com/yamcodes)_ The TanStack CLI add-on now registers the Vite plugin as `arkenvPlugin`. ```ts import arkenvPlugin from "@arkenv/vite-plugin"; export default defineConfig({ plugins: [arkenvPlugin()], }); ``` - #### Point TanStack add-on dependencies at the current release _[`#1978`](#1978) [`888e6c2`](888e6c2) [@yamcodes](https://github.com/yamcodes)_ Scaffolded TanStack Start apps now install `@arkenv/core`, `@arkenv/standard`, and `@arkenv/vite-plugin` at `^1.0.0-rc.2`, which matches the versions on npm `latest` and still accepts `1.0.0` when it publishes. Usage: ```bash npx @tanstack/cli create my-app --add-ons https://arkenv.js.org/tanstack/info.json ``` ## @arkenv/standard@1.0.0-rc.3 No changes in this release. Co-authored-by: arkenv-bot[bot] <237618717+arkenv-bot[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1818
What changed
The TanStack add-on now installs the packages on npm
latest(1.0.0-rc.2):@arkenv/core,@arkenv/standard, and@arkenv/vite-pluginat^1.0.0-rc.2. That range also accepts1.0.0when it publishes.^1.0.0alone does not, because1.0.0is not on npm yet.Docs, the package README, and the changelog all use the command that works on the published CLI:
--add-ons arkenvfails today.@tanstack/clihas noarkenvcatalog entry. TanStack/cli#505 does not add one.packages/tanstack-addon/.add-on/README.mdis the catalog README to copy upstream next toinfo.jsonandpackage.json.ejs.Upstream PR
TanStack/cli#505 is still open, so this stays Vite-only (no Rsbuild bundler switch).
Opening the catalog PR on
TanStack/clifailed: theyamcodestoken can pull that repo but cannot fork it (403 Resource not accessible by personal access token,push: false). The add-on tree was verified against a local checkout ofTanStack/climain(@tanstack/cli@0.71.0/@tanstack/create@0.70.0).Verification
Against that checkout, with install skipped:
create test-app --add-ons arkenvwrites ArkTypesrc/env.ts,@arkenv/core/@arkenv/vite-pluginat^1.0.0-rc.2, the Vite plugin import,/demo/arkenv, and.env.example.--add-on-configZod keeps the demo route; Valibot withdemo: falseomits it.Published
@tanstack/cli--list-add-onsincludest3envand does not includearkenv.packages/tanstack-addontests: 16 passed.tsc --noEmitand Biome on the touched files passed. Repo-widenub run typecheckcannot start here because Turborepo 2.10 rejectspackageManager: nub@0.9.3.