Reworked Next.js and New TanStack Start Support (#795)

* feat: add initial adapter and options for TanStack Start

* chore: upgrade TanStack Start

* chore: update to fix Windows Start dev

* feat: migrate NextJS and TanStack Start integrations to throw when validation occured

* chore: fix test:ci usage

* chore: remove unused deps

* docs: update Next.js SSR docs

docs/framework/react/guides/ssr.md

@@ -44,7 +44,10 @@ Next, we can create [a React Server Action](https://unicorn-utterances.com/posts
 'use server'
 
 // Notice the import path is different from the client
-import { createServerValidate } from '@tanstack/react-form/nextjs'
+import {
+  ServerValidateError,
+  createServerValidate,
+} from '@tanstack/react-form/nextjs'
 import { formOpts } from './shared-code'
 
 // Create the server action that will infer the types of the form from `formOpts`
@@ -58,7 +61,18 @@ const serverValidate = createServerValidate({
 })
 
 export default async function someAction(prev: unknown, formData: FormData) {
-  return await serverValidate(formData)
+  try {
+    await serverValidate(formData)
+  } catch (e) {
+    if (e instanceof ServerValidateError) {
+      return e.formState
+    }
+
+    // Some other error occurred while validating your form
+    throw e
+  }
+
+  // Your form has successfully validated!
 }
 ```
 
@@ -84,7 +98,7 @@ export const ClientComp = () => {
 
   const form = useForm({
     ...formOpts,
-    transform: useTransform((baseForm) => mergeForm(baseForm, state), [state]),
+    transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
   })
 
   const formErrors = form.useStore((formState) => formState.errors)

examples/lit/simple/package.json

@@ -13,7 +13,7 @@
     "lit": "^3.1.1"
   },
   "devDependencies": {
-    "vite": "^5.0.10"
+    "vite": "^5.1.4"
   },
   "browserslist": {
     "production": [

examples/lit/ui-libraries/package.json

@@ -14,7 +14,7 @@
     "@material/web": "^1.0.0"
   },
   "devDependencies": {
-    "vite": "^5.0.10"
+    "vite": "^5.1.4"
   },
   "browserslist": {
     "production": [

examples/react/array/package.json

@@ -17,7 +17,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "vite": "^5.0.10"
+    "vite": "^5.1.4"
   },
   "browserslist": {
     "production": [

examples/react/next-server-actions/src/app/action.ts

@@ -1,6 +1,9 @@
 'use server'
 
-import { createServerValidate } from '@tanstack/react-form/nextjs'
+import {
+  ServerValidateError,
+  createServerValidate,
+} from '@tanstack/react-form/nextjs'
 import { formOpts } from './shared-code'
 
 const serverValidate = createServerValidate({
@@ -13,5 +16,16 @@ const serverValidate = createServerValidate({
 })
 
 export default async function someAction(prev: unknown, formData: FormData) {
-  return await serverValidate(formData)
+  try {
+    await serverValidate(formData)
+  } catch (e) {
+    if (e instanceof ServerValidateError) {
+      return e.formState
+    }
+
+    // Some other error occurred while validating your form
+    throw e
+  }
+
+  // Your form has successfully validated!
 }

examples/react/next-server-actions/src/app/client-component.tsx

@@ -1,12 +1,8 @@
 'use client'
 
 import { useActionState } from 'react'
-import {
-  initialFormState,
-  mergeForm,
-  useForm,
-  useTransform,
-} from '@tanstack/react-form'
+import { mergeForm, useForm, useTransform } from '@tanstack/react-form'
+import { initialFormState } from '@tanstack/react-form/nextjs'
 import someAction from './action'
 import { formOpts } from './shared-code'
 
@@ -15,7 +11,7 @@ export const ClientComp = () => {
 
   const form = useForm({
     ...formOpts,
-    transform: useTransform((baseForm) => mergeForm(baseForm, state), [state]),
+    transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
   })
 
   const formErrors = form.useStore((formState) => formState.errors)

examples/react/query-integration/package.json

@@ -18,7 +18,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "vite": "^5.0.10"
+    "vite": "^5.1.4"
   },
   "browserslist": {
     "production": [

examples/react/simple/package.json

@@ -17,7 +17,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "vite": "^5.0.10"
+    "vite": "^5.1.4"
   },
   "browserslist": {
     "production": [

examples/react/tanstack-start/.gitignore

@@ -0,0 +1,22 @@
+node_modules
+package-lock.json
+yarn.lock
+
+.DS_Store
+.cache
+.env
+.vercel
+.output
+.vinxi
+
+/build/
+/api/
+/server/build
+/public/build
+.vinxi
+# Sentry Config File
+.env.sentry-build-plugin
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

examples/react/tanstack-start/README.md

@@ -0,0 +1,72 @@
+# Welcome to TanStack.com!
+
+This site is built with TanStack Router!
+
+- [TanStack Router Docs](https://tanstack.com/router)
+
+It's deployed automagically with Vercel!
+
+- [Vercel](https://vercel.com/)
+
+## Development
+
+From your terminal:
+
+```sh
+pnpm install
+pnpm dev
+```
+
+This starts your app in development mode, rebuilding assets on file changes.
+
+## Editing and previewing the docs of TanStack projects locally
+
+The documentations for all TanStack projects except for `React Charts` are hosted on [https://tanstack.com](https://tanstack.com), powered by this TanStack Router app.
+In production, the markdown doc pages are fetched from the GitHub repos of the projects, but in development they are read from the local file system.
+
+Follow these steps if you want to edit the doc pages of a project (in these steps we'll assume it's [`TanStack/form`](https://github.com/tanstack/form)) and preview them locally :
+
+1. Create a new directory called `tanstack`.
+
+```sh
+mkdir tanstack
+```
+
+2. Enter the directory and clone this repo and the repo of the project there.
+
+```sh
+cd tanstack
+git clone [email protected]:TanStack/tanstack.com.git
+git clone [email protected]:TanStack/form.git
+```
+
+> [!NOTE]
+> Your `tanstack` directory should look like this:
+>
+> ```
+> tanstack/
+>    |
+>    +-- form/
+>    |
+>    +-- tanstack.com/
+> ```
+
+> [!WARNING]
+> Make sure the name of the directory in your local file system matches the name of the project's repo. For example, `tanstack/form` must be cloned into `form` (this is the default) instead of `some-other-name`, because that way, the doc pages won't be found.
+
+3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
+
+```sh
+cd tanstack.com
+pnpm i
+# The app will run on https://localhost:3000 by default
+pnpm dev
+```
+
+4. Now you can visit http://localhost:3000/form/latest/docs/overview in the browser and see the changes you make in `tanstack/form/docs`.
+
+> [!NOTE]
+> The updated pages need to be manually reloaded in the browser.
+
+> [!WARNING]
+> You will need to update the `docs/config.json` file (in the project's repo) if you add a new doc page!

examples/react/tanstack-start/app.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from '@tanstack/start/config'
+import tsConfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  vite: {
+    plugins: () => [
+      tsConfigPaths({
+        projects: ['./tsconfig.json'],
+      }),
+    ],
+  },
+  react: {
+    exclude: [/packages/],
+  },
+} as Partial<Parameters<typeof defineConfig>[0]> as never)

examples/react/tanstack-start/app/client.tsx

@@ -0,0 +1,7 @@
+import { hydrateRoot } from 'react-dom/client'
+import { StartClient } from '@tanstack/start'
+import { createRouter } from './router'
+
+const router = createRouter()
+
+hydrateRoot(document.getElementById('root')!, <StartClient router={router} />)

examples/react/tanstack-start/app/routeTree.gen.ts

@@ -0,0 +1,57 @@
+/* prettier-ignore-start */
+
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file is auto-generated by TanStack Router
+
+// Import Routes
+
+import { Route as rootRoute } from './routes/__root'
+import { Route as IndexImport } from './routes/index'
+
+// Create/Update Routes
+
+const IndexRoute = IndexImport.update({
+  path: '/',
+  getParentRoute: () => rootRoute,
+} as any)
+
+// Populate the FileRoutesByPath interface
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexImport
+      parentRoute: typeof rootRoute
+    }
+  }
+}
+
+// Create and export the route tree
+
+export const routeTree = rootRoute.addChildren({ IndexRoute })
+
+/* prettier-ignore-end */
+
+/* ROUTE_MANIFEST_START
+{
+  "routes": {
+    "__root__": {
+      "filePath": "__root.tsx",
+      "children": [
+        "/"
+      ]
+    },
+    "/": {
+      "filePath": "index.tsx"
+    }
+  }
+}
+ROUTE_MANIFEST_END */

examples/react/tanstack-start/app/router.tsx

@@ -0,0 +1,17 @@
+import { createRouter as createTanStackRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function createRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    defaultPreload: 'intent',
+  })
+
+  return router
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof createRouter>
+  }
+}

examples/react/tanstack-start/app/routes/__root.tsx

@@ -0,0 +1,43 @@
+import { createRootRoute } from '@tanstack/react-router'
+import { Outlet, ScrollRestoration } from '@tanstack/react-router'
+import { Body, Head, Html, Meta, Scripts } from '@tanstack/start'
+import * as React from 'react'
+
+export const Route = createRootRoute({
+  meta: () => [
+    {
+      charSet: 'utf-8',
+    },
+    {
+      name: 'viewport',
+      content: 'width=device-width, initial-scale=1',
+    },
+    {
+      title: 'TanStack Form + Start',
+    },
+  ],
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  )
+}
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <Html>
+      <Head>
+        <Meta />
+      </Head>
+      <Body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </Body>
+    </Html>
+  )
+}