From 46185fa1dc85072f8d080ba6aff810295b5e0972 Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Fri, 11 Sep 2026 16:27:30 -0600 Subject: [PATCH 1/2] docs(start): add TanStack Form mutation workflow --- docs/start/config.json | 4 + .../framework/react/guide/tanstack-form.md | 87 ++++++++++ examples/react/start-form/.gitignore | 5 + examples/react/start-form/README.md | 23 +++ examples/react/start-form/package.json | 30 ++++ .../react/start-form/playwright.config.ts | 13 ++ .../react/start-form/src/routeTree.gen.ts | 87 ++++++++++ examples/react/start-form/src/router.tsx | 5 + .../react/start-form/src/routes/__root.tsx | 28 ++++ .../react/start-form/src/routes/index.tsx | 103 ++++++++++++ .../react/start-form/src/routes/saved.tsx | 17 ++ examples/react/start-form/src/server/goal.ts | 38 +++++ examples/react/start-form/src/start.ts | 8 + examples/react/start-form/tests/form.spec.ts | 114 +++++++++++++ examples/react/start-form/tsconfig.json | 17 ++ examples/react/start-form/vite.config.ts | 7 + pnpm-lock.yaml | 157 ++++++++++++++++++ 17 files changed, 743 insertions(+) create mode 100644 docs/start/framework/react/guide/tanstack-form.md create mode 100644 examples/react/start-form/.gitignore create mode 100644 examples/react/start-form/README.md create mode 100644 examples/react/start-form/package.json create mode 100644 examples/react/start-form/playwright.config.ts create mode 100644 examples/react/start-form/src/routeTree.gen.ts create mode 100644 examples/react/start-form/src/router.tsx create mode 100644 examples/react/start-form/src/routes/__root.tsx create mode 100644 examples/react/start-form/src/routes/index.tsx create mode 100644 examples/react/start-form/src/routes/saved.tsx create mode 100644 examples/react/start-form/src/server/goal.ts create mode 100644 examples/react/start-form/src/start.ts create mode 100644 examples/react/start-form/tests/form.spec.ts create mode 100644 examples/react/start-form/tsconfig.json create mode 100644 examples/react/start-form/vite.config.ts diff --git a/docs/start/config.json b/docs/start/config.json index 57703aad89..a3a42e6ed8 100644 --- a/docs/start/config.json +++ b/docs/start/config.json @@ -94,6 +94,10 @@ "label": "Server Functions", "to": "framework/react/guide/server-functions" }, + { + "label": "Forms and Mutations", + "to": "framework/react/guide/tanstack-form" + }, { "label": "Streaming Data from Server Functions", "to": "framework/react/guide/streaming-data-from-server-functions" diff --git a/docs/start/framework/react/guide/tanstack-form.md b/docs/start/framework/react/guide/tanstack-form.md new file mode 100644 index 0000000000..40c9fe4f21 --- /dev/null +++ b/docs/start/framework/react/guide/tanstack-form.md @@ -0,0 +1,87 @@ +--- +id: tanstack-form +title: Forms and Mutations with TanStack Form +description: Use TanStack Form with Start server functions for field errors, pending state, optimistic updates, loader refresh, and navigation after saving. +--- + +TanStack Form owns field state and submission feedback. Start server functions validate and save the submitted values, and Router loaders read the saved result. The [working example](https://github.com/TanStack/router/tree/main/examples/react/start-form) connects those pieces in a small reading-goal form. + +The example saves a non-sensitive preference in a per-browser cookie. It needs no database or account, and does not treat that cookie as authentication. For application records, authorize the caller and write through your database before reporting success. + +## Choose a submission path + +This guide uses `@tanstack/react-form` with `useServerFn`. The form requires JavaScript and disables its controls until hydration. Its HTML method is POST so a native submission cannot put entered values in the URL. + +If you need a native form action that works without JavaScript, use the [Form Start integration](/form/latest/docs/framework/react/guides/ssr#using-tanstack-form-in-tanstack-start). That guide covers `@tanstack/react-form-start`, server validation state, and native submission. Do not mix its redirect-and-cookie validation flow into a client RPC handler without deciding how the response should be consumed. + +## Validate at the write endpoint + +`saveGoal` accepts a string, then validates its trimmed value before setting the cookie. The server rejects empty or overlong goals even when a caller bypasses the form. Known validation failures return a field message. Unexpected failures reach the client's failure handler. + +Client validation makes the form easier to use, but does not authorize or validate a network request. The example deliberately checks only an empty string on the client so whitespace-only input demonstrates server validation. + +The handler uses `private, no-store`, and the cookie is HTTP-only, SameSite Lax, and Secure on HTTPS. The example also enables Start's CSRF middleware for server-function requests. CSRF checks and account authorization solve separate problems; an application with accounts needs both. + +## Put server errors next to their field + +The form calls the server through `useServerFn(saveGoal)`. A validation result becomes a Form error: + +```tsx +const result = await save({ data: value }) +if (result.error) { + formApi.setErrorMap({ + onSubmit: { fields: { goal: result.error } }, + }) + return +} +``` + +The input reads `field.state.meta.errors` and connects the error container with `aria-describedby`. Its entered value remains available for correction. See Form's [validation guide](/form/latest/docs/framework/react/guides/validation) for validator types and field-error APIs. + +## Keep pending state through the refresh + +`onSubmit` is async. `form.Subscribe` observes `isSubmitting` and disables the whole fieldset until the save, loader refresh, and optional navigation finish. Both save buttons share that state, so another submission cannot race the first one. + +After a successful write, the example awaits `router.invalidate()`. This makes the loader read the newly saved cookie before the form reports **Saved.** A completed server request alone does not replace Router's loaded data. + +The final page also reads its value through a loader. Reloading that page checks persistence independently of the form's local state. + +## Make optimistic state temporary + +Before the request, the component places the candidate goal in `optimisticGoal`. The preview renders that value while the request is pending, with the saved loader value underneath it. + +On success, the loader refresh completes before the temporary value is cleared. On a validation or HTTP failure, `finally` clears the preview and shows the previously loaded goal. It preserves the input so the user can correct or retry it. + +A failed response does not always mean a write failed. The server might have committed a write before the connection broke. The failure message therefore asks the user to reload and check, rather than claiming that storage is unchanged. Important or non-idempotent mutations need their own retry and idempotency policy. + +## Navigate only after saving + +The two buttons use Form's submission metadata. **Save** keeps the user on the form. **Save and continue** calls: + +```tsx +void form.handleSubmit({ redirect: true }) +``` + +`onSubmit` reads `meta.redirect` and navigates to `/saved` only after the server reports success and Router refreshes. Validation failures stay on the form. This is client navigation after an RPC submission; a native POST flow should return an appropriate redirect response instead. + +See [Form submission handling](/form/latest/docs/framework/react/guides/submission-handling) for the metadata API and [Start server functions](./server-functions) for request and response behavior. + +## Run the example and its checks + +After the Router repository's dependency and framework build setup: + +```sh +cd examples/react/start-form +pnpm dev +``` + +Open http://localhost:3150. Stop that server before running Playwright: + +```sh +pnpm exec playwright install chromium +pnpm test:e2e +pnpm build +FORM_PRODUCTION=1 pnpm test:e2e +``` + +The tests cover server field errors, a pending optimistic preview, persisted loader data, a second browser's separate preference, redirect after saving, and cross-site rejection. A test intercepts a submission with an HTTP 500 response to check rollback, preserved input, and retry. That failure fixture tests client behavior; it does not claim to exercise a database outage. Both runs check for uncaught browser errors. diff --git a/examples/react/start-form/.gitignore b/examples/react/start-form/.gitignore new file mode 100644 index 0000000000..4bbad8098f --- /dev/null +++ b/examples/react/start-form/.gitignore @@ -0,0 +1,5 @@ +node_modules +.output +.tanstack +test-results +playwright-report diff --git a/examples/react/start-form/README.md b/examples/react/start-form/README.md new file mode 100644 index 0000000000..4754a56fd5 --- /dev/null +++ b/examples/react/start-form/README.md @@ -0,0 +1,23 @@ +# TanStack Form with Start + +A reading-goal form with server validation, field errors, pending controls, an optimistic preview, loader refresh, and navigation after saving. The [Start form guide](https://tanstack.com/start/latest/docs/framework/react/guide/tanstack-form) explains the workflow. + +Follow the Router repository's dependency and framework build setup, then run: + +```sh +cd examples/react/start-form +pnpm dev +``` + +Open http://localhost:3150. The example stores a non-sensitive preference in a per-browser cookie. No database or account is required. It uses client RPC submission and requires JavaScript. The Form docs separately cover native form actions. + +After stopping the dev server: + +```sh +pnpm exec playwright install chromium +pnpm test:e2e +pnpm build +FORM_PRODUCTION=1 pnpm test:e2e +``` + +Tests check server validation, pending preview, persistence, redirect, separate browser state, and CSRF. An intercepted HTTP 500 response verifies client rollback and retry. A failed response can leave a real write's result uncertain, so the UI asks the user to reload and check. diff --git a/examples/react/start-form/package.json b/examples/react/start-form/package.json new file mode 100644 index 0000000000..4bdd281eae --- /dev/null +++ b/examples/react/start-form/package.json @@ -0,0 +1,30 @@ +{ + "name": "tanstack-start-example-form", + "private": true, + "sideEffects": false, + "type": "module", + "scripts": { + "dev": "vite --port 3150", + "build": "vite build && tsc --noEmit", + "start": "node .output/server/index.mjs", + "test:e2e": "playwright test" + }, + "dependencies": { + "@tanstack/react-router": "workspace:^", + "@tanstack/react-start": "workspace:^", + "@tanstack/react-form": "1.33.5", + "react": "^19.0.0", + "react-dom": "^19.0.0", + "zod": "^4.4.3" + }, + "devDependencies": { + "@types/node": "^22.5.4", + "@types/react": "^19.0.8", + "@types/react-dom": "^19.0.3", + "@vitejs/plugin-react": "^6.0.1", + "nitro": "^3.0.260311-beta", + "typescript": "npm:@typescript/typescript6@^6.0.2", + "vite": "^8.0.14", + "@playwright/test": "^1.61.0" + } +} diff --git a/examples/react/start-form/playwright.config.ts b/examples/react/start-form/playwright.config.ts new file mode 100644 index 0000000000..4b212c946b --- /dev/null +++ b/examples/react/start-form/playwright.config.ts @@ -0,0 +1,13 @@ +import { defineConfig } from '@playwright/test' +export default defineConfig({ + testDir: './tests', + use: { browserName: 'chromium', baseURL: 'http://localhost:3150' }, + webServer: { + command: + process.env.FORM_PRODUCTION === '1' + ? 'PORT=3150 node .output/server/index.mjs' + : 'pnpm dev', + url: 'http://localhost:3150', + timeout: 120_000, + }, +}) diff --git a/examples/react/start-form/src/routeTree.gen.ts b/examples/react/start-form/src/routeTree.gen.ts new file mode 100644 index 0000000000..bbe280cda9 --- /dev/null +++ b/examples/react/start-form/src/routeTree.gen.ts @@ -0,0 +1,87 @@ +/* eslint-disable */ + +// @ts-nocheck + +// noinspection JSUnusedGlobalSymbols + +// This file was automatically generated by TanStack Router. +// You should NOT make any changes in this file as it will be overwritten. +// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified. + +import { Route as rootRouteImport } from './routes/__root' +import { Route as IndexRouteImport } from './routes/index' +import { Route as SavedRouteImport } from './routes/saved' + +const IndexRoute = IndexRouteImport.update({ + id: '/', + path: '/', + getParentRoute: () => rootRouteImport, +} as any) +const SavedRoute = SavedRouteImport.update({ + id: '/saved', + path: '/saved', + getParentRoute: () => rootRouteImport, +} as any) + +export interface FileRoutesByFullPath { + '/': typeof IndexRoute + '/saved': typeof SavedRoute +} +export interface FileRoutesByTo { + '/': typeof IndexRoute + '/saved': typeof SavedRoute +} +export interface FileRoutesById { + __root__: typeof rootRouteImport + '/': typeof IndexRoute + '/saved': typeof SavedRoute +} +export interface FileRouteTypes { + fileRoutesByFullPath: FileRoutesByFullPath + fullPaths: '/' | '/saved' + fileRoutesByTo: FileRoutesByTo + to: '/' | '/saved' + id: '__root__' | '/' | '/saved' + fileRoutesById: FileRoutesById +} +export interface RootRouteChildren { + IndexRoute: typeof IndexRoute + SavedRoute: typeof SavedRoute +} + +declare module '@tanstack/react-router' { + interface FileRoutesByPath { + '/': { + id: '/' + path: '/' + fullPath: '/' + preLoaderRoute: typeof IndexRouteImport + parentRoute: typeof rootRouteImport + } + '/saved': { + id: '/saved' + path: '/saved' + fullPath: '/saved' + preLoaderRoute: typeof SavedRouteImport + parentRoute: typeof rootRouteImport + } + } +} + +const rootRouteChildren: RootRouteChildren = { + IndexRoute: IndexRoute, + SavedRoute: SavedRoute, +} +export const routeTree = rootRouteImport + ._addFileChildren(rootRouteChildren) + ._addFileTypes() + +import type { getRouter } from './router.tsx' +import type { startInstance } from './start.ts' +declare module '@tanstack/react-start' { + interface Register { + ssr: true + router: Awaited> + config: Awaited> + } +} diff --git a/examples/react/start-form/src/router.tsx b/examples/react/start-form/src/router.tsx new file mode 100644 index 0000000000..bb899b1fdf --- /dev/null +++ b/examples/react/start-form/src/router.tsx @@ -0,0 +1,5 @@ +import { createRouter } from '@tanstack/react-router' +import { routeTree } from './routeTree.gen' +export function getRouter() { + return createRouter({ routeTree }) +} diff --git a/examples/react/start-form/src/routes/__root.tsx b/examples/react/start-form/src/routes/__root.tsx new file mode 100644 index 0000000000..08aab343b4 --- /dev/null +++ b/examples/react/start-form/src/routes/__root.tsx @@ -0,0 +1,28 @@ +import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router' +import type { ReactNode } from 'react' +export const Route = createRootRoute({ + head: () => ({ + meta: [ + { charSet: 'utf-8' }, + { name: 'viewport', content: 'width=device-width, initial-scale=1' }, + { title: 'Reading goal | TanStack Form' }, + ], + }), + shellComponent: ({ children }: { children: ReactNode }) => ( + + + + + + {children} + + + + ), + notFoundComponent: () => ( +
+

Page not found

+ Home +
+ ), +}) diff --git a/examples/react/start-form/src/routes/index.tsx b/examples/react/start-form/src/routes/index.tsx new file mode 100644 index 0000000000..a4677942a4 --- /dev/null +++ b/examples/react/start-form/src/routes/index.tsx @@ -0,0 +1,103 @@ +import { createFileRoute, useHydrated, useRouter } from '@tanstack/react-router' +import { useForm } from '@tanstack/react-form' +import { useServerFn } from '@tanstack/react-start' +import { useState } from 'react' +import { readGoal, saveGoal } from '../server/goal' +export const Route = createFileRoute('/')({ + loader: () => readGoal(), + headers: () => ({ 'Cache-Control': 'private, no-store' }), + component: Home, +}) +function Home() { + const goal = Route.useLoaderData() + const router = useRouter() + const hydrated = useHydrated() + const save = useServerFn(saveGoal) + const [optimisticGoal, setOptimisticGoal] = useState(null) + const [message, setMessage] = useState('') + const form = useForm({ + defaultValues: { goal }, + onSubmitMeta: { redirect: false }, + validators: { + onSubmit: ({ value }) => + value.goal.length === 0 + ? { fields: { goal: 'Enter a reading goal.' } } + : undefined, + }, + onSubmit: async ({ value, formApi, meta }) => { + setMessage('') + setOptimisticGoal(value.goal.trim()) + try { + const result = await save({ data: value }) + if (result.error) { + formApi.setErrorMap({ onSubmit: { fields: { goal: result.error } } }) + return + } + await router.invalidate() + setMessage('Saved.') + if (meta.redirect) { + await router.navigate({ to: '/saved' }) + } + } catch { + setMessage( + 'Could not confirm the save. Reload to check your saved goal.', + ) + } finally { + setOptimisticGoal(null) + } + }, + }) + return ( +
+

Reading goal

+

Current goal: {optimisticGoal ?? goal}

+
{ + event.preventDefault() + void form.handleSubmit() + }} + > + state.isSubmitting}> + {(isSubmitting) => ( +
+ + {(field) => ( +
+ + + field.handleChange(event.target.value) + } + onBlur={field.handleBlur} + aria-describedby="goal-error" + aria-invalid={field.state.meta.errors.length > 0} + /> + +
+ )} +
+ + +
+ )} +
+
+

{message}

+
+ ) +} diff --git a/examples/react/start-form/src/routes/saved.tsx b/examples/react/start-form/src/routes/saved.tsx new file mode 100644 index 0000000000..400298dbe7 --- /dev/null +++ b/examples/react/start-form/src/routes/saved.tsx @@ -0,0 +1,17 @@ +import { createFileRoute, Link } from '@tanstack/react-router' +import { readGoal } from '../server/goal' +export const Route = createFileRoute('/saved')({ + loader: () => readGoal(), + headers: () => ({ 'Cache-Control': 'private, no-store' }), + component: Saved, +}) +function Saved() { + const goal = Route.useLoaderData() + return ( +
+

Goal saved

+

{goal}

+ Edit your goal +
+ ) +} diff --git a/examples/react/start-form/src/server/goal.ts b/examples/react/start-form/src/server/goal.ts new file mode 100644 index 0000000000..fb98e96db3 --- /dev/null +++ b/examples/react/start-form/src/server/goal.ts @@ -0,0 +1,38 @@ +import { createServerFn } from '@tanstack/react-start' +import { + getCookie, + getRequestUrl, + setCookie, + setResponseHeader, +} from '@tanstack/react-start/server' +import { z } from 'zod' +const schema = z.object({ + goal: z + .string() + .trim() + .min(1, 'Enter a reading goal.') + .max(80, 'Use 80 characters or fewer.'), +}) +export const readGoal = createServerFn({ method: 'GET' }).handler(() => { + setResponseHeader('Cache-Control', 'private, no-store') + return getCookie('reading_goal') ?? 'Read one chapter' +}) +export const saveGoal = createServerFn({ method: 'POST' }) + .validator(z.object({ goal: z.string() })) + .handler(({ data }) => { + setResponseHeader('Cache-Control', 'private, no-store') + const result = schema.safeParse(data) + if (!result.success) { + return { + error: result.error.issues[0]?.message ?? 'Check your reading goal.', + } + } + setCookie('reading_goal', result.data.goal, { + httpOnly: true, + sameSite: 'lax', + secure: getRequestUrl().protocol === 'https:', + path: '/', + maxAge: 60 * 60 * 24 * 30, + }) + return { error: '' } + }) diff --git a/examples/react/start-form/src/start.ts b/examples/react/start-form/src/start.ts new file mode 100644 index 0000000000..4c97030fc8 --- /dev/null +++ b/examples/react/start-form/src/start.ts @@ -0,0 +1,8 @@ +import { createCsrfMiddleware, createStart } from '@tanstack/react-start' +export const startInstance = createStart(() => ({ + requestMiddleware: [ + createCsrfMiddleware({ + filter: ({ handlerType }) => handlerType === 'serverFn', + }), + ], +})) diff --git a/examples/react/start-form/tests/form.spec.ts b/examples/react/start-form/tests/form.spec.ts new file mode 100644 index 0000000000..8394602a59 --- /dev/null +++ b/examples/react/start-form/tests/form.spec.ts @@ -0,0 +1,114 @@ +import { expect, test } from '@playwright/test' +let browserErrors: Array = [] +test.beforeEach(({ page }) => { + browserErrors = [] + page.on('pageerror', (error) => browserErrors.push(error.message)) +}) +test.afterEach(() => { + expect(browserErrors).toEqual([]) +}) + +test('server field errors, pending preview, persistence, redirect and CSRF', async ({ + page, + request, +}) => { + await page.goto('/') + await page.getByLabel('Your goal').fill(' ') + await page.getByRole('button', { name: 'Save', exact: true }).click() + await expect(page.getByRole('alert')).toHaveText('Enter a reading goal.') + await expect( + page.getByText('Current goal: Read one chapter', { exact: true }), + ).toBeVisible() + await page.getByLabel('Your goal').fill('x'.repeat(81)) + await page.getByRole('button', { name: 'Save', exact: true }).click() + await expect(page.getByRole('alert')).toHaveText( + 'Use 80 characters or fewer.', + ) + await page.getByLabel('Your goal').fill('Read two chapters') + let release = () => {} + const gate = new Promise((resolve) => { + release = resolve + }) + await page.route('**/_serverFn/**', async (route) => { + if (route.request().method() === 'POST') { + await gate + } + await route.continue() + }) + const submitted = page.waitForRequest( + (r) => + r.method() === 'POST' && + new URL(r.url()).pathname.startsWith('/_serverFn/'), + ) + await page.getByRole('button', { name: 'Save', exact: true }).click() + const write = await submitted + try { + await expect(page.getByRole('button', { name: 'Saving...' })).toBeDisabled() + await expect( + page.getByRole('button', { name: 'Save and continue' }), + ).toBeDisabled() + await expect( + page.getByText('Current goal: Read two chapters', { exact: true }), + ).toBeVisible() + } finally { + release() + } + await expect(page.getByRole('status')).toHaveText('Saved.') + await page.unroute('**/_serverFn/**') + await page.reload() + await expect(page.getByLabel('Your goal')).toHaveValue('Read two chapters') + expect(await (await request.get('/')).text()).toContain('Read one chapter') + const headers = await write.allHeaders() + delete headers.cookie + delete headers['content-length'] + const crossSite = await page.request.post(write.url(), { + headers: { + ...headers, + origin: 'https://untrusted.example', + 'sec-fetch-site': 'cross-site', + }, + data: write.postData() ?? '', + }) + expect(crossSite.status()).toBe(403) + await page.getByLabel('Your goal').fill('Finish a book') + await page.getByRole('button', { name: 'Save and continue' }).click() + await expect(page).toHaveURL(/\/saved$/) + await expect(page.getByText('Finish a book', { exact: true })).toBeVisible() + const response = await page.reload() + expect(response?.headers()['cache-control']).toContain('no-store') + await expect(page.getByText('Finish a book', { exact: true })).toBeVisible() +}) + +test('HTTP failure rolls back the preview, preserves input, and permits retry', async ({ + page, +}) => { + await page.goto('/') + await page.getByLabel('Your goal').fill('A new goal') + await page.route('**/_serverFn/**', async (route) => { + if (route.request().method() === 'POST') { + await route.fulfill({ + status: 500, + contentType: 'application/json', + body: '{"error":"test server failure"}', + }) + } else { + await route.continue() + } + }) + await page.getByRole('button', { name: 'Save', exact: true }).click() + await expect(page.getByRole('status')).toHaveText( + 'Could not confirm the save. Reload to check your saved goal.', + ) + await expect( + page.getByText('Current goal: Read one chapter', { exact: true }), + ).toBeVisible() + await expect(page.getByLabel('Your goal')).toHaveValue('A new goal') + await expect( + page.getByRole('button', { name: 'Save', exact: true }), + ).toBeEnabled() + await page.unroute('**/_serverFn/**') + await page.getByRole('button', { name: 'Save', exact: true }).click() + await expect(page.getByRole('status')).toHaveText('Saved.') + await page.reload() + await expect(page.getByLabel('Your goal')).toHaveValue('A new goal') +}) diff --git a/examples/react/start-form/tsconfig.json b/examples/react/start-form/tsconfig.json new file mode 100644 index 0000000000..1d0362ff0c --- /dev/null +++ b/examples/react/start-form/tsconfig.json @@ -0,0 +1,17 @@ +{ + "compilerOptions": { + "strict": true, + "esModuleInterop": true, + "jsx": "react-jsx", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["DOM", "DOM.Iterable", "ES2024"], + "isolatedModules": true, + "resolveJsonModule": true, + "skipLibCheck": true, + "target": "ES2024", + "allowJs": true, + "forceConsistentCasingInFileNames": true, + "noEmit": true + } +} diff --git a/examples/react/start-form/vite.config.ts b/examples/react/start-form/vite.config.ts new file mode 100644 index 0000000000..195c5224e2 --- /dev/null +++ b/examples/react/start-form/vite.config.ts @@ -0,0 +1,7 @@ +import { tanstackStart } from '@tanstack/react-start/plugin/vite' +import { defineConfig } from 'vite' +import viteReact from '@vitejs/plugin-react' +import { nitro } from 'nitro/vite' +export default defineConfig({ + plugins: [tanstackStart(), viteReact(), nitro()], +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index fe6d5f7342..cb0ce3464a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15579,6 +15579,52 @@ importers: specifier: ^3.24.2 version: 3.25.57 + examples/react/start-form: + dependencies: + '@tanstack/react-form': + specifier: 1.33.5 + version: 1.33.5(@tanstack/react-start@packages+react-start)(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + '@tanstack/react-router': + specifier: workspace:* + version: link:../../../packages/react-router + '@tanstack/react-start': + specifier: workspace:* + version: link:../../../packages/react-start + react: + specifier: ^19.2.3 + version: 19.2.3 + react-dom: + specifier: ^19.2.3 + version: 19.2.3(react@19.2.3) + zod: + specifier: ^4.4.3 + version: 4.5.4 + devDependencies: + '@playwright/test': + specifier: ^1.61.0 + version: 1.61.1 + '@types/node': + specifier: 25.0.9 + version: 25.0.9 + '@types/react': + specifier: ^19.2.8 + version: 19.2.9 + '@types/react-dom': + specifier: ^19.2.3 + version: 19.2.3(@types/react@19.2.9) + '@vitejs/plugin-react': + specifier: ^6.0.1 + version: 6.0.1(@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7(supports-color@10.2.2))(rolldown@1.0.2)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)))(babel-plugin-react-compiler@1.0.0)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)) + nitro: + specifier: ^3.0.260311-beta + version: 3.0.260311-beta(@electric-sql/pglite@0.3.2)(@emnapi/core@1.11.3)(@emnapi/runtime@1.11.3)(@libsql/client@0.15.15)(@netlify/blobs@10.1.0)(chokidar@5.0.0)(dotenv@17.4.2)(giget@3.3.1)(ioredis@5.11.1(supports-color@10.2.2))(jiti@2.7.0)(lru-cache@11.5.1)(miniflare@4.20260317.0)(mysql2@3.15.3)(rollup@4.63.1)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)) + typescript: + specifier: npm:@typescript/typescript6@^6.0.2 + version: '@typescript/typescript6@6.0.2' + vite: + specifier: ^8.0.14 + version: 8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0) + packages: '@adobe/css-tools@4.4.1': @@ -29453,6 +29499,27 @@ packages: use-sync-external-store: optional: true + '@tanstack/react-form@1.33.5': + resolution: {integrity: sha512-LlRB28qJwO/QCGaHvWnbdh4haBgTFiZVmzA2uzxSBS3YA7/IqrQ6HOBK70CkFQ+DbflZ7NawsmSln13h5iIdTA==} + peerDependencies: + '@tanstack/react-start': '*' + react: ^19.2.3 + peerDependenciesMeta: + '@tanstack/react-start': + optional: true + + '@tanstack/form-core@1.33.5': + resolution: {integrity: sha512-3dfx9MBP0aq5sXKteikG629X9oviptrQj0IFRk9YGcb+lB7Kv5x8S17oOSk1wUWgjQZ4xVJEMbKwOAODymocgA==} + + '@tanstack/devtools-event-client@0.4.4': + resolution: {integrity: sha512-6T5Yop/793YI+H+5J8Hsyj4kCih9sl4t3ElLgKioW5hk3ocn+ZdSJ94tT7vL7uabxSugWYBZlOTMPzEw2puvQw==} + engines: {node: '>=18'} + hasBin: true + + '@tanstack/pacer-lite@0.1.1': + resolution: {integrity: sha512-y/xtNPNt/YeyoVxE/JCx+T7yjEzpezmbb+toK8DDD1P4m7Kzs5YR956+7OKexG3f8aXgC3rLZl7b1V+yNUSy5w==} + engines: {node: '>=18'} + snapshots: '@adobe/css-tools@4.4.1': {} @@ -45433,3 +45500,93 @@ snapshots: immer: 10.1.1 react: 19.2.3 use-sync-external-store: 1.6.0(react@19.2.3) + '@tanstack/react-form@1.33.5(@tanstack/react-start@packages+react-start)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)': + dependencies: + '@tanstack/form-core': 1.33.5 + '@tanstack/react-store': 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + react: 19.2.3 + optionalDependencies: + '@tanstack/react-start': link:packages/react-start + transitivePeerDependencies: + - react-dom + + '@tanstack/form-core@1.33.5': + dependencies: + '@tanstack/devtools-event-client': 0.4.4 + '@tanstack/pacer-lite': 0.1.1 + '@tanstack/store': 0.11.1 + + '@tanstack/devtools-event-client@0.4.4': {} + + '@tanstack/pacer-lite@0.1.1': {} + + '@vitejs/plugin-react@6.0.1(@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7(supports-color@10.2.2))(rolldown@1.0.2)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)))(babel-plugin-react-compiler@1.0.0)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0))': + dependencies: + '@rolldown/pluginutils': 1.0.0-rc.7 + vite: 8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0) + optionalDependencies: + '@rolldown/plugin-babel': 0.2.3(@babel/core@7.29.7(supports-color@10.2.2))(rolldown@1.0.2)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)) + babel-plugin-react-compiler: 1.0.0 + + '@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7(supports-color@10.2.2))(rolldown@1.0.2)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0))': + dependencies: + '@babel/core': 7.29.7(supports-color@10.2.2) + picomatch: 4.0.7 + rolldown: 1.0.2 + optionalDependencies: + vite: 8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0) + optional: true + + nitro@3.0.260311-beta(@electric-sql/pglite@0.3.2)(@emnapi/core@1.11.3)(@emnapi/runtime@1.11.3)(@libsql/client@0.15.15)(@netlify/blobs@10.1.0)(chokidar@5.0.0)(dotenv@17.4.2)(giget@3.3.1)(ioredis@5.11.1(supports-color@10.2.2))(jiti@2.7.0)(lru-cache@11.5.1)(miniflare@4.20260317.0)(mysql2@3.15.3)(rollup@4.63.1)(vite@8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0)): + dependencies: + consola: 3.4.2 + crossws: 0.4.4(srvx@0.11.22) + db0: 0.3.4(@electric-sql/pglite@0.3.2)(@libsql/client@0.15.15)(mysql2@3.15.3) + env-runner: 0.1.6(miniflare@4.20260317.0) + h3: 2.0.1-rc.16(crossws@0.4.4(srvx@0.11.22)) + hookable: 6.1.0 + nf3: 0.3.11 + ocache: 0.1.2 + ofetch: 2.0.0-alpha.3 + ohash: 2.0.11 + rolldown: 1.0.0-rc.9(@emnapi/core@1.11.3)(@emnapi/runtime@1.11.3) + srvx: 0.11.22 + unenv: 2.0.0-rc.24 + unstorage: 2.0.0-alpha.6(@netlify/blobs@10.1.0)(chokidar@5.0.0)(db0@0.3.4(@electric-sql/pglite@0.3.2)(@libsql/client@0.15.15)(mysql2@3.15.3))(ioredis@5.11.1(supports-color@10.2.2))(lru-cache@11.5.1)(ofetch@2.0.0-alpha.3) + optionalDependencies: + dotenv: 17.4.2 + giget: 3.3.1 + jiti: 2.7.0 + rollup: 4.63.1 + vite: 8.0.14(@types/node@25.0.9)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.97.2)(terser@5.51.2)(tsx@4.20.3)(yaml@2.9.0) + transitivePeerDependencies: + - '@azure/app-configuration' + - '@azure/cosmos' + - '@azure/data-tables' + - '@azure/identity' + - '@azure/keyvault-secrets' + - '@azure/storage-blob' + - '@capacitor/preferences' + - '@deno/kv' + - '@electric-sql/pglite' + - '@emnapi/core' + - '@emnapi/runtime' + - '@libsql/client' + - '@netlify/blobs' + - '@planetscale/database' + - '@upstash/redis' + - '@vercel/blob' + - '@vercel/functions' + - '@vercel/kv' + - aws4fetch + - better-sqlite3 + - chokidar + - drizzle-orm + - idb-keyval + - ioredis + - lru-cache + - miniflare + - mongodb + - mysql2 + - sqlite3 + - uploadthing From 6586ed34a27538cd64db8084aa5ad105e52120ee Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Fri, 11 Sep 2026 17:42:37 -0600 Subject: [PATCH 2/2] test(start): catch cold Form hydration hook errors --- examples/react/start-form/playwright.config.ts | 2 +- examples/react/start-form/tests/form.spec.ts | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/examples/react/start-form/playwright.config.ts b/examples/react/start-form/playwright.config.ts index 4b212c946b..4524e6de26 100644 --- a/examples/react/start-form/playwright.config.ts +++ b/examples/react/start-form/playwright.config.ts @@ -6,7 +6,7 @@ export default defineConfig({ command: process.env.FORM_PRODUCTION === '1' ? 'PORT=3150 node .output/server/index.mjs' - : 'pnpm dev', + : 'pnpm dev --force', url: 'http://localhost:3150', timeout: 120_000, }, diff --git a/examples/react/start-form/tests/form.spec.ts b/examples/react/start-form/tests/form.spec.ts index 8394602a59..264a1f0a7b 100644 --- a/examples/react/start-form/tests/form.spec.ts +++ b/examples/react/start-form/tests/form.spec.ts @@ -3,6 +3,14 @@ let browserErrors: Array = [] test.beforeEach(({ page }) => { browserErrors = [] page.on('pageerror', (error) => browserErrors.push(error.message)) + page.on('console', (message) => { + if ( + message.type() === 'error' && + message.text().includes('Invalid hook call') + ) { + browserErrors.push(message.text()) + } + }) }) test.afterEach(() => { expect(browserErrors).toEqual([])