Skip to content
Source
Sign inSign up
TanStack/form

docs: general docs updates #2118

Openharry-whorlow(GitHub profile, opens in a new tab)wants to merge 6 commits intomain fromssr-docsopened

Summary by CodeRabbit

  • Documentation
    • Replaced the old combined SSR/meta-framework guide with separate TanStack Start, Next.js, and Remix guides.
    • Added detailed integration guides for TanStack Start, Next.js (App Router + Server Actions), and Remix covering server/client validation and state merging.
    • Added “Why Index as Key?” for array examples.
    • Added submission-handling docs describing canSubmitWhenInvalid across frameworks.
    • Updated React guides navigation and removed an outdated transform reference.
    1. Note

      Reviews paused

      It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

      Use the following commands to manage reviews:

      • @coderabbitai resume to resume automatic reviews.
      • @coderabbitai review to trigger a single review.

      Use the checkboxes below for quick actions:

      • ▶️ Resume reviews
      • 🔍 Trigger review
      📝 Walkthrough

      Walkthrough

      Removed the combined SSR guide and replaced it with three separate React framework guides (TanStack Start, Next.js, Remix); updated docs navigation; added array key rationale; added submission-handling docs for multiple frameworks; deleted docs/framework/react/guides/ssr.md.

      Changes

      Cohort / File(s)Summary
      React framework guides (added)
      docs/framework/react/guides/tanstack-start.md, docs/framework/react/guides/nextjs.md, docs/framework/react/guides/remix.md
      New integration guides showing shared formOptions, server-side validation patterns using createServerValidate/ServerValidateError, examples for merging server state into client via useTransform/merge, and example client submission flows per framework.
      TanStack Start route (added exports / server fns)
      app/routes/index.tsx
      Added exported formOpts (formOptions(...)), server POST handler handleForm, server GET getFormDataFromServer, and exported Route (file route) — server-side validation and client merge flows illustrated in examples.
      React guide removed
      docs/framework/react/guides/ssr.md
      Deleted the prior combined SSR/meta-framework integration guide and its end-to-end examples for TanStack Start, Next.js, and Remix.
      Arrays guidance (updated)
      docs/framework/react/guides/arrays.md
      Added "Why Index as Key?" section explaining use of key={i} for array items due to index-based field names and instance/state alignment.
      Docs navigation / config (updated)
      docs/config.json
      Split the former SSR guide link into separate TanStack Start, Next.js, and Remix entries in React Guides; removed useTransform reference from React functions list.
      Submission-handling docs (added/updated)
      docs/framework/react/guides/submission-handling.md, docs/framework/solid/guides/submission-handling.md, docs/framework/vue/guides/submission-handling.md, docs/framework/angular/guides/submission-handling.md
      Added documentation showing the canSubmitWhenInvalid boolean option for form creation/injection across React, Solid, Vue, and Angular with example snippets demonstrating submission when invalid.

      Sequence Diagram(s)

      mermaid sequenceDiagram participant Client participant Server participant FormLib Note over Client,FormLib: Client mounts form with useForm + useTransform Client->>Server: Submit form (Server Action / POST) Server->>Server: createServerValidate -> validate request alt Validation fails Server-->>Client: Return ServerValidateError with e.formState Client->>FormLib: useTransform merges server formState into client store else Validation succeeds Server-->>Client: Success / redirect end

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~20 minutes

      Poem

      🐰 I hopped through docs with nimble feet, Split one big guide so each framework can meet. Keys in arrays and submits that bend, Tiny pages added, old ones end. Hops, notes, and carrots — docs ready to send! 🥕

      🚥 Pre-merge checks | ✅ 1 | ❌ 2

      ❌ Failed checks (1 warning, 1 inconclusive)

      Check nameStatusExplanationResolution
      Description check⚠️ WarningThe pull request has no description provided, missing all required template sections including what changes were made, motivation, testing checklist completion, and release impact assessment.Add a comprehensive description following the template, explaining the documentation restructuring (SSR guide removal and framework-specific guide additions), motivation, and confirm testing via 'pnpm test:pr' and changeset requirements.
      Title check❓ InconclusiveThe title 'docs: general docs updates' is vague and does not clearly convey the specific nature of the changes, which include restructuring SSR documentation, adding framework-specific guides, and updating submission-handling docs.Consider a more descriptive title such as 'docs: restructure SSR guides and add framework-specific integration examples' to better reflect the scope of changes.
      ✅ Passed checks (1 passed)
      Check nameStatusExplanation
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
      ✏️ Tip: You can configure your own custom pre-merge checks in the settings.
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Commit unit tests in branch `ssr-docs`

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    2. View your CI Pipeline Execution ↗ for commit efa1fe78ca5c226da85713d3dfbb2527992e24d3

      CommandStatusDurationResult
      nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded23sView ↗
      nx run-many --target=build --exclude=examples/**✅ Succeeded<1sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-04-13 14:46:55 UTC

    3. 🚀 Changeset Version Preview

      No changeset entries found. Merging this PR will not cause a version bump for any packages.

    4. More templates

      @tanstack/angular-form

      npm i https://pkg.pr.new/@tanstack/angular-form@2118

      @tanstack/form-core

      npm i https://pkg.pr.new/@tanstack/form-core@2118

      @tanstack/form-devtools

      npm i https://pkg.pr.new/@tanstack/form-devtools@2118

      @tanstack/lit-form

      npm i https://pkg.pr.new/@tanstack/lit-form@2118

      @tanstack/react-form

      npm i https://pkg.pr.new/@tanstack/react-form@2118

      @tanstack/react-form-devtools

      npm i https://pkg.pr.new/@tanstack/react-form-devtools@2118

      @tanstack/react-form-nextjs

      npm i https://pkg.pr.new/@tanstack/react-form-nextjs@2118

      @tanstack/react-form-remix

      npm i https://pkg.pr.new/@tanstack/react-form-remix@2118

      @tanstack/react-form-start

      npm i https://pkg.pr.new/@tanstack/react-form-start@2118

      @tanstack/solid-form

      npm i https://pkg.pr.new/@tanstack/solid-form@2118

      @tanstack/solid-form-devtools

      npm i https://pkg.pr.new/@tanstack/solid-form-devtools@2118

      @tanstack/svelte-form

      npm i https://pkg.pr.new/@tanstack/svelte-form@2118

      @tanstack/vue-form

      npm i https://pkg.pr.new/@tanstack/vue-form@2118

      commit: efa1fe7

    5. Actionable comments posted: 3

      🤖 Prompt for all review comments with AI agents
      Verify each finding against the current code and only fix it if needed.
      
      Inline comments:
      In `@docs/framework/react/guides/tanstack-start.md`:
      - Around line 1-4: The frontmatter field `id: ssr` is incorrect for this guide;
      update the frontmatter `id` to match the new guide route (e.g., set `id:
      framework/react/guides/tanstack-start` or a concise `tanstack-start`) so the
      sidebar/navigation resolves correctly—modify the `id` entry in the file's top
      YAML block (replace `id: ssr`) to the matching route string.
      - Line 167: Rewrite the sentence for correct grammar and clarity: capitalize the
      sentence start, change "it's" to "its", and rephrase to say that useTransform's
      primary responsibility is merging server and client state; mention that under
      the hood useTransform is a useCallback whose dependencies mirror the server
      state so when the server state changes it automatically patches the client state
      (reference useTransform and useCallback).
      - Around line 12-14: Update the prerequisites to include the correct starter
      package name so examples import correctly: add installation of
      "@tanstack/react-form-start" (in addition to or instead of
      "@tanstack/react-form" as appropriate) to the bulleted list so the imports used
      in the examples (imports from "@tanstack/react-form-start") will resolve; ensure
      the text explicitly instructs users to run the package install (e.g.,
      npm/yarn/pnpm) for "@tanstack/react-form-start" and optionally clarify when
      "@tanstack/react-form" is also needed.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: e23d7534-682b-4635-9bcc-4e121a2aea6c

      📥 Commits

      Reviewing files that changed from the base of the PR and between cdf783c50aaaf5e689a566c4b97edd9066243992 and 0842cff17e2e236025bcd0d198db065d78be5f6c.

      📒 Files selected for processing (5)
      • docs/config.json
      • docs/framework/react/guides/nextjs.md
      • docs/framework/react/guides/remix.md
      • docs/framework/react/guides/ssr.md
      • docs/framework/react/guides/tanstack-start.md
      💤 Files with no reviewable changes (1)
      • docs/framework/react/guides/ssr.md
      ✅ Files skipped from review due to trivial changes (2)
      • docs/framework/react/guides/remix.md
      • docs/framework/react/guides/nextjs.md
      Resolvedby harry-whorlow(GitHub profile, opens in a new tab)
      Resolvedby harry-whorlow(GitHub profile, opens in a new tab)
      Resolvedby harry-whorlow(GitHub profile, opens in a new tab)
    6. Actionable comments posted: 2

      🤖 Prompt for all review comments with AI agents
      Verify each finding against the current code and only fix it if needed.
      
      Inline comments:
      In `@docs/framework/angular/guides/submission-handling.md`:
      - Line 106: Fix the sentence to correct the grammar and API reference by
      changing "a invalid state `canSubmitWhenInvalid` boolean flag can be provided to
      useForm" to "an invalid state: the `canSubmitWhenInvalid` boolean flag can be
      provided to injectForm"; ensure the identifier `canSubmitWhenInvalid` remains
      code-formatted and replace `useForm` with `injectForm` so the docs reference the
      correct Angular API.
      
      In `@docs/framework/vue/guides/submission-handling.md`:
      - Line 101: The sentence contains a grammatical error: change "a invalid state
      `canSubmitWhenInvalid` boolean flag can be provided to useForm." to use "an"
      before "invalid" so it reads "an invalid state" while keeping the
      `canSubmitWhenInvalid` identifier and surrounding wording unchanged; update the
      line to "In a situation where you want to be able to submit in an invalid state
      `canSubmitWhenInvalid` boolean flag can be provided to useForm." to correct the
      article usage.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: 2664fd00-f1ea-4b83-a9a1-a52f2a427ff8

      📥 Commits

      Reviewing files that changed from the base of the PR and between 0842cff17e2e236025bcd0d198db065d78be5f6c and 707b5ed4b30f4cf1be20feafdc6bfff99c6ba285.

      📒 Files selected for processing (4)
      • docs/framework/angular/guides/submission-handling.md
      • docs/framework/react/guides/submission-handling.md
      • docs/framework/solid/guides/submission-handling.md
      • docs/framework/vue/guides/submission-handling.md
      ✅ Files skipped from review due to trivial changes (2)
      • docs/framework/react/guides/submission-handling.md
      • docs/framework/solid/guides/submission-handling.md
      OutdatedResolvedby harry-whorlow(GitHub profile, opens in a new tab)
      OutdatedResolvedby harry-whorlow(GitHub profile, opens in a new tab)
    7. Looks solid! The array explanation might need some rephrasing with the new context, hopefully my explanation is clear enough.

      docs/framework/react/guides/arrays.md line 57
      @@ -52,3 +52,6 @@
      5252 </form.Field>
      5353 ```
      5454
      55+## Why Index as Key?
      56+
      57+You may notice that these examples use `key={i}` the array index as the key prop. React's documentation generally advises _against_ using array indices as keys when items can be reordered or deleted. TanStack Form is an exception to this rule. Because field names in TanStack Form arrays are index-based, using the array index as `key` is required, it keeps React component instances, form store state, and field names in sync.

      This is only partially true. Yes, the field data is identified by the index, but the rendering usually isn't. Many reordering libraries break when using the index as key.

      We addressed that for React, so while it may impact performance slightly, you can use arbitrary key props. I believe it's still broken in Vue.

      docs/framework/react/guides/nextjs.md line 150
      @@ -0,0 +130,21 @@
      130+ </div>
      131+ )
      132+ }}
      133+ </form.Field>
      134+ <form.Subscribe
      135+ selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      136+ >
      137+ {([canSubmit, isSubmitting]) => (
      138+ <button type="submit" disabled={!canSubmit}>
      139+ {isSubmitting ? '...' : 'Submit'}
      140+ </button>
      141+ )}
      142+ </form.Subscribe>
      143+ </form>
      144+ )
      145+}
      146+```
      147+
      148+### useTransform
      149+
      150+you may have noticed util function `useTransform` being used throughout these examples, it's primary responsibility is the merging of the server and client state. Under the hood it is a useCallback whose deps are that of the server state, when the server state changes it will automatically patch the client state.
      you may have noticed the util function `useTransform` being used throughout these examples. Its primary responsibility is the merging of the server and client state. Under the hood, it is a useCallback whose deps are that of the server state, when the server state changes it will automatically patch the client state.

      This change needs to be applied to the other SSR docs.

Sign in to join this conversation.