docs: overhaul TanStack Start guide - #1819
Conversation
Rewrite the framework guide in the-voice register: Turbo lead, Vite as the default CLI path, Rsbuild Callout with manual install, Callouts instead of ::: directives, schema as its own H2, and named arkenvRsbuildPlugin import. Mention both plugins on the frameworks index card.
|
github-actions
Bot
added
docs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
ℹ️ Minor suggestions only — four small polish items inline, plus two informational notes.
Reviewed changes — docs-only overhaul of the TanStack Start guide and its framework index card.
- Rewrote
tanstack-start.mdxto lead with Vite as the default path: the add-on quickstart now states it scaffoldsarkenvVitePlugin()+env.ts+ ArkType, and the interactive-options / demo-route promises are gone — an accurate simplification given remote add-ons run on defaults at the pinned@tanstack/createversions. - Restructured "Manual installation" per bundler (
### Vite/### Rsbuild, each with ArkType + Standard Schema), and switched the Rsbuild config to the namedarkenvRsbuildPluginimport, which matches both the package exports and the reference docs. - Promoted "Define your schema" to a top-level section, relocated the CLI-vs-runtime warning into a callout there, and converted all
:::admonitions to<Callout>. - Added a "Using Rsbuild?" callout and mentioned
@arkenv/rsbuild-pluginon the framework index card. I verified the external claim: TanStack/cli#505 is an open PR adding Rsbuild as a bundler option, so "not currently supported for scaffolding or add-ons" is accurate today. - Confirmed the test-plan boxes:
check:mdx(mdxlint--frail) passes both files, and everypackage-installfence satisfies the fence vitest'snpm install/npxassertion. No behavioral surface; the Rsbuild/Vite imports and/standardsubpaths are all real exports.
ℹ️ Alpha-pinning guidance dropped
The "Pinning alphas" note was deleted in favor of "Author bare @arkenv/* package names; the docs site applies the release tag automatically." Since the renderer tags install lines with the active channel, during pre-GA readers following these commands get mutable @alpha builds — the exact reproducibility gap (lockfiles differing across machines/CI) the removed note warned about. If that pinning advice is still wanted for alpha users it no longer exists anywhere in the docs; if the drop is a deliberate reversal that's a fine call — flagging so it's an explicit choice.
Technical details
# Alpha-pinning guidance removed
## Affected sites
- apps/www/content/docs/frameworks/tanstack-start.mdx — removed `:::info[Pinning alphas]` note; replaced with "the docs site applies the release tag automatically"
## Required outcome
- Confirm whether the pre-GA reproducibility advice is intentionally gone, or should be restored (e.g. in a shared location reachable from all framework guides)
## Open questions for the human
- Is the alpha-pin guidance still desirable until GA, and does it belong in this guide or somewhere shared?ℹ️ #rsbuild cross-link now lands on the install section
The restructure introduced a second ### Rsbuild heading (under "Manual installation" in addition to the one under "Configuration"). Fumadocs slugging keeps #rsbuild for the first occurrence, so the existing cross-link from apps/www/content/docs/reference/rsbuild-plugin.mdx:7 ("TanStack Start guide") now resolves to the install-commands section rather than the Configuration section it used to reach. Harmless either way, but worth confirming the landing point is the intended one.
Technical details
# Anchor shift for #rsbuild
## Affected sites
- apps/www/content/docs/reference/rsbuild-plugin.mdx:7 — links `/docs/frameworks/tanstack-start#rsbuild`
- apps/www/content/docs/frameworks/tanstack-start.mdx — now has two `### Rsbuild` headings; `#rsbuild` resolves to the first (Manual installation, line 85)
## Required outcome
- Confirm the cross-link's landing section is intentional, or make the target unambiguousDeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
| npm install -D @arkenv/rsbuild-plugin | ||
| ``` | ||
|
|
||
| ## Configuration |
There was a problem hiding this comment.
Blank line dropped: the base file kept one between this install fence and the heading, and every other ## in this doc is preceded by a blank line. Renderer-wise it's harmless, but it breaks the file's own consistency — restore the blank line after the closing fence.
| reads must match your bundler's client prefix: `VITE_` for Vite or | ||
| `PUBLIC_` for Rsbuild. Everything else stays on the server. | ||
|
|
||
| <Callout type="info" title="Import from `@arkenv/core`, not `arkenv`"> |
There was a problem hiding this comment.
<Callout> title is a plain-string prop, so these backticks print literally in the rendered header — unlike the :::warning[...] admonition syntax this replaces, which rendered inline code. (Same applies to the import.meta.env callout at line 288.) Suggest a title without backticks, e.g. "Import from the runtime package, not the CLI".
| Reading `import.meta.env` skips ArkEnv. Import `{ env }` so public keys stay | ||
| typed and coerced and server secrets stay out of the client bundle. | ||
| ::: | ||
| <Callout type="warn" title="Do not read `import.meta.env` directly"> |
There was a problem hiding this comment.
Same as the @arkenv/core callout above: backticks inside a <Callout> title render literally instead of as code. Use a title without backticks, e.g. "Use the env import, not import.meta.env" would still show the backticks — better: set the codified name in the body and keep the title plain.
There was a problem hiding this comment.
ℹ️ The only delta since the prior review is the autofix.ci pass, which restores the dropped blank line that was flagged inline — addressed cleanly, no new issues. The two backtick-in-
Callout-title comments from the initial review are still outstanding.
Reviewed changes — one new commit since the prior review (376e2f2): 505e8258 ([autofix.ci] apply automated fixes), which adds the single missing blank line between the Rsbuild Standard-Schema install fence and ## Configuration. No other content changed; md.mdxlint state and fence compliance are unaffected.
DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏
1 participant
Summary
Rewrite TanStack Start docs for Vite-first path and Rsbuild support.
Test plan