From 7ebd2c9e3152cbc97af7c21b21c7c45946c81143 Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Sun, 28 Jun 2026 17:45:18 -0700
Subject: [PATCH 1/7] Separate SolidStart v2 routes and enable v2 sidebar

---
 .../(3)data-fetching.mdx                      |   1 +
 .../(4)data-mutation.mdx                      |   1 +
 .../solid-start/(2)migrating-from-v1.mdx      |  98 ----------------
 .../v2/solid-start/(2)migrating-from-v1.mdx   | 108 ++++++++++++++++++
 vite.config.ts                                |  18 ++-
 5 files changed, 127 insertions(+), 99 deletions(-)
 delete mode 100644 src/routes/solid-start/(2)migrating-from-v1.mdx
 create mode 100644 src/routes/v2/solid-start/(2)migrating-from-v1.mdx

diff --git a/src/routes/solid-start/(0)building-your-application/(3)data-fetching.mdx b/src/routes/solid-start/(0)building-your-application/(3)data-fetching.mdx
index 74c1104aa1..5381062d2b 100644
--- a/src/routes/solid-start/(0)building-your-application/(3)data-fetching.mdx
+++ b/src/routes/solid-start/(0)building-your-application/(3)data-fetching.mdx
@@ -1,5 +1,6 @@
 ---
 title: "Data fetching"
+version: "1.0"
 ---
 
 Fetching data from a remote API or database is a core task for most applications.
diff --git a/src/routes/solid-start/(0)building-your-application/(4)data-mutation.mdx b/src/routes/solid-start/(0)building-your-application/(4)data-mutation.mdx
index 2692c4dfc6..f1a0204a0e 100644
--- a/src/routes/solid-start/(0)building-your-application/(4)data-mutation.mdx
+++ b/src/routes/solid-start/(0)building-your-application/(4)data-mutation.mdx
@@ -1,5 +1,6 @@
 ---
 title: "Data mutation"
+version: "1.0"
 ---
 
 Mutating data on a server is a common task in most applications.
diff --git a/src/routes/solid-start/(2)migrating-from-v1.mdx b/src/routes/solid-start/(2)migrating-from-v1.mdx
deleted file mode 100644
index 9ebc51f8fb..0000000000
--- a/src/routes/solid-start/(2)migrating-from-v1.mdx
+++ /dev/null
@@ -1,98 +0,0 @@
----
-title: Migrating from v1
-use_cases: >-
-  existing project, migration, upgrade
-tags:
-  - setup
-  - installation
-  - starter
-  - template
-  - quickstart
-  - init
-version: "2.0"
-description: >-
-  Migrate your SolidStart project from v1 to v2.
----
-
-This is a migration guide of how to upgrade your v1 SolidStart app to our new v2 version.
-
-Please note that some third-party packages may not be compatible with v2 yet.
-
-## Migration steps
-
-### Update dependencies
-
-```package-install
-@solidjs/start@2.0.0-alpha.2 @solidjs/vite-plugin-nitro-2 vite@7
-```
-
-```package-remove
-vinxi
-```
-
-### Configuration files
-
-- Remove `app.config.ts`
-- Create `vite.config.ts`
-
-```tsx title="vite.config.ts"
-import { solidStart } from "@solidjs/start/config";
-import { defineConfig } from "vite";
-import { nitroV2Plugin } from "@solidjs/vite-plugin-nitro-2";
-
-export default defineConfig(() => {
-	return {
-		plugins: [
-			solidStart({
-				middleware: "./src/middleware/index.ts",
-			}),
-			nitroV2Plugin(),
-		],
-	};
-});
-```
-
-Compile-time environment variables are now handled by Vite's environment API.
-
-```tsx title="vite.config.ts"
-// ...
-export default defineConfig(({ mode }) => {
-	const env = loadEnv(mode, process.cwd(), "");
-
-	return {
-		// ...
-		environments: {
-			ssr: {
-				define: {
-					"process.env.DATABASE_URL": JSON.stringify(env.DATABASE_URL),
-				},
-			},
-		},
-	};
-});
-```
-
-Update the build/dev commands to use native Vite instead of vinxi.
-
-```json
-"scripts": {
-  "dev": "vite dev",
-  "build": "vite build",
-  "start": "vite preview"
-}
-```
-
-### Environment types
-
-Only the `types` entry is new in v2. Everything else can remain unchanged.
-
-```json
-"compilerOptions": {
-  "types": ["@solidjs/start/env"]
-}
-```
-
-## Server runtime helpers
-
-- Replace all imports from `vinxi/http` with `@solidjs/start/http`
-- Optional: update the middleware syntax to the newer [H3 syntax](https://h3.dev/guide/basics/middleware)
diff --git a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
new file mode 100644
index 0000000000..04bde4e19e
--- /dev/null
+++ b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
@@ -0,0 +1,108 @@
+---
+title: Migrating from v1
+use_cases: >-
+  existing project, migration, upgrade
+tags:
+  - setup
+  - installation
+  - starter
+  - template
+  - quickstart
+  - init
+version: "2.0"
+description: >-
+  Migrate your SolidStart project from v1 to v2.
+---
+
+This guide covers the package-level changes that are verified for `@solidjs/start@2.0.0-alpha.3`.
+It focuses on the parts of the migration that are confirmed in this session from the published package surface and current repository configuration.
+
+Some ecosystem packages may still target v1-only APIs.
+Audit those dependencies before shipping a production upgrade.
+
+## Migration steps
+
+### Update dependencies
+
+```package-install
+@solidjs/start@2.0.0-alpha.3
+```
+
+```package-remove
+vinxi
+```
+
+The published `2.0.0-alpha.3` package exports its framework plugin from `@solidjs/start/config`.
+That is the verified entry point for configuring a v2 app.
+
+### Move framework configuration into `vite.config.ts`
+
+V1 projects centered their framework configuration around `app.config.ts`.
+For the current v2 alpha, move that setup into a Vite config that calls `solidStart()`.
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+	plugins: [solidStart()],
+});
+```
+
+If your app already has custom middleware, the published v2 config type also exposes a `middleware` option:
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+	plugins: [solidStart({ middleware: "./src/middleware/index.ts" })],
+});
+```
+
+### Update server runtime imports
+
+The current v2 package exports HTTP helpers from `@solidjs/start/http`.
+Replace imports from `vinxi/http` with that module.
+
+```tsx
+import { getCookie, setCookie, useSession } from "@solidjs/start/http";
+```
+
+The published HTTP entrypoint exposes helpers such as `readBody`, `getQuery`, `getRequestHeader`, `setResponseHeader`, `useSession`, and related cookie/session utilities.
+
+### Update TypeScript environment types
+
+The current package also publishes `@solidjs/start/env` for type support.
+Make sure your TypeScript config includes it.
+
+```json
+{
+	"compilerOptions": {
+		"types": ["@solidjs/start/env"]
+	}
+}
+```
+
+### Revisit middleware syntax
+
+The v2 middleware entrypoint exports `createMiddleware`, and its published types now prefer H3 middleware arrays.
+The older `onRequest` and `onBeforeResponse` object form is still present but marked deprecated in the package types.
+
+```tsx
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+	async (_event, next) => {
+		return await next();
+	},
+]);
+```
+
+## Still unknown in this session
+
+- The full replacement guidance for every v1 entrypoint file is Unknown.
+- The recommended production `start` script for generated apps is Unknown.
+- The exact v2 equivalents for advanced topics like auth, prerendering, metadata, and background tasks are Unknown.
+
+Keep those areas on the v1 docs until the current v2 API and examples are verified.
\ No newline at end of file
diff --git a/vite.config.ts b/vite.config.ts
index 85b4da9e1c..47283a44cb 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -45,7 +45,11 @@ export default defineConfig({
 						version: ["latest", "v2"],
 					},
 					{
-						project: ["router", "start", "meta"],
+						project: "start",
+						version: ["latest", "v2"],
+					},
+					{
+						project: ["router", "meta"],
 						version: "latest",
 					},
 				],
@@ -73,6 +77,18 @@ export default defineConfig({
 						},
 					},
 				},
+				{
+					project: "start",
+					version: "v2",
+					title: "SolidStart",
+					themeConfig: {
+						sidebar: {
+							"/v2/solid-start": createFilesystemSidebar(
+								"./src/routes/v2/solid-start"
+							),
+						},
+					},
+				},
 				{
 					project: "meta",
 					title: "Solid Meta",

From 9cc78f6d7e0d321caa44aa32083240c7869ed55b Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Sun, 28 Jun 2026 18:17:44 -0700
Subject: [PATCH 2/7] Add SolidStart v2 documentation for routing, API routes,
 data fetching, data mutation, overview, and getting started

---
 .../(0)routing.mdx                            |  84 +++++++++++++
 .../(1)api-routes.mdx                         |  90 ++++++++++++++
 .../(3)data-fetching.mdx                      |  89 ++++++++++++++
 .../(4)data-mutation.mdx                      | 112 ++++++++++++++++++
 src/routes/v2/solid-start/(0)index.mdx        |  42 +++++++
 .../v2/solid-start/(1)getting-started.mdx     |  91 ++++++++++++++
 .../v2/solid-start/(2)migrating-from-v1.mdx   |  29 +++--
 7 files changed, 522 insertions(+), 15 deletions(-)
 create mode 100644 src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
 create mode 100644 src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
 create mode 100644 src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
 create mode 100644 src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
 create mode 100644 src/routes/v2/solid-start/(0)index.mdx
 create mode 100644 src/routes/v2/solid-start/(1)getting-started.mdx

diff --git a/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx b/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
new file mode 100644
index 0000000000..3722e39046
--- /dev/null
+++ b/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
@@ -0,0 +1,84 @@
+---
+title: Routing
+use_cases: >-
+  page navigation, url structure, dynamic paths, route organization,
+  filesystem routing, api endpoints
+tags:
+  - routing
+  - filesystem
+  - pages
+  - dynamic
+  - api
+version: "2.0"
+description: >-
+  SolidStart v2 routing uses the filesystem router to map files in
+  src/routes to UI routes and API routes.
+---
+
+Routes come from the filesystem.
+`FileRoutes` from `@solidjs/start/router` maps files in `src/routes` into route paths.
+
+This page covers the route filename conventions.
+
+## UI routes and API routes
+
+There are two route shapes:
+
+- Files with a default export become UI routes.
+- Files that export HTTP method names such as `GET` or `POST` become API routes.
+
+You can read more about handler exports in [API routes](/v2/solid-start/building-your-application/api-routes).
+
+## Basic filename mapping
+
+File names map to paths using these rules:
+
+- `src/routes/index.tsx` becomes `/`
+- `src/routes/about.tsx` becomes `/about`
+- `src/routes/blog/index.tsx` becomes `/blog`
+- `src/routes/blog/post.tsx` becomes `/blog/post`
+
+An `.mdx` file in `src/routes` is also treated as a page route.
+
+## Dynamic segments
+
+Bracketed segments become route params:
+
+- `src/routes/users/[id].tsx` becomes `/users/:id`
+- `src/routes/users/[[id]].tsx` becomes `/users/:id?`
+- `src/routes/docs/[...slug].tsx` becomes `/docs/*slug`
+
+Read them with [`useParams`](/solid-router/reference/primitives/use-params):
+
+```tsx title="src/routes/users/[id].tsx"
+import { useParams } from "@solidjs/router";
+
+export default function UserPage() {
+	const params = useParams();
+	return <h1>User {params.id}</h1>;
+}
+```
+
+## Route config exports
+
+The filesystem router also looks for an exported `route` object alongside a page component.
+That lets a route file attach route-level behavior while still default-exporting UI.
+
+```tsx title="src/routes/posts/[id].tsx"
+import { query, createAsync, type RouteDefinition } from "@solidjs/router";
+
+const getPost = query(async (id: string) => {
+	"use server";
+	const response = await fetch(`https://example.com/api/posts/${id}`);
+	return response.json();
+}, "post");
+
+export const route = {
+	preload: ({ params }) => getPost(params.id),
+} satisfies RouteDefinition;
+
+export default function PostPage(props: { params: { id: string } }) {
+	const post = createAsync(() => getPost(props.params.id));
+	return <pre>{JSON.stringify(post(), null, 2)}</pre>;
+}
+```
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
new file mode 100644
index 0000000000..e6a50aaf2e
--- /dev/null
+++ b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
@@ -0,0 +1,90 @@
+---
+title: API routes
+use_cases: >-
+  rest api, webhooks, oauth callbacks, server endpoints, route handlers,
+  request handling
+tags:
+  - api
+  - http
+  - server
+  - handlers
+  - endpoints
+version: "2.0"
+description: >-
+  SolidStart v2 API routes are filesystem routes that export HTTP method
+  handlers and receive typed APIEvent objects from @solidjs/start/server.
+---
+
+Use an API route when you need a route that returns data or handles incoming HTTP requests instead of rendering page UI.
+
+A file becomes an API route when it exports one or more HTTP method names such as `GET`, `POST`, `PATCH`, or `DELETE`.
+
+## Create an API route
+
+An API route lives in `src/routes` and exports handler functions named after the HTTP methods it handles.
+
+```tsx title="src/routes/api/ping.ts"
+export function GET() {
+	return new Response("pong");
+}
+```
+
+The package exports `APIEvent` from `@solidjs/start/server`.
+That type includes:
+
+- `request` for the incoming `Request`
+- `params` for dynamic path parameters
+- `response` for the mutable response stub
+- `locals` for request-scoped locals
+- `nativeEvent` for the underlying H3 event
+
+```tsx title="src/routes/api/users/[id].ts"
+import type { APIEvent } from "@solidjs/start/server";
+
+export async function GET({ params }: APIEvent) {
+	return Response.json({ userId: params.id });
+}
+```
+
+## File naming follows the same router
+
+API routes use the same path conventions as UI routes.
+For example:
+
+- `src/routes/api/users.ts` becomes `/api/users`
+- `src/routes/api/users/[id].ts` becomes `/api/users/:id`
+- `src/routes/api/files/[...slug].ts` becomes `/api/files/*slug`
+
+## HEAD fallback
+
+If a route exports `GET` but not `HEAD`, `HEAD` requests are handled by the `GET` handler.
+Export `HEAD` explicitly when you need custom behavior.
+
+## Request helpers
+
+Cookie, session, header, and request helpers are exported from `@solidjs/start/http`.
+
+```tsx title="src/routes/api/session.ts"
+import { getCookie } from "@solidjs/start/http";
+import type { APIEvent } from "@solidjs/start/server";
+
+export function GET(_event: APIEvent) {
+	const userId = getCookie("userId");
+	if (!userId) {
+		return new Response("Not logged in", { status: 401 });
+	}
+
+	return Response.json({ userId });
+}
+```
+
+## When to use an API route
+
+API routes are a good fit when you need:
+
+- endpoints for other clients
+- webhook receivers
+- auth callback handlers
+- routes that return non-HTML responses
+
+If the data is only needed by your route UI, prefer [Data fetching](/v2/solid-start/building-your-application/data-fetching) or [Data mutation](/v2/solid-start/building-your-application/data-mutation) before introducing a separate API boundary.
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx b/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
new file mode 100644
index 0000000000..89d541ee3b
--- /dev/null
+++ b/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
@@ -0,0 +1,89 @@
+---
+title: Data fetching
+use_cases: >-
+  api calls, database queries, loading states, preloading data, server-side
+  fetching, route data
+tags:
+  - fetch
+  - data
+  - query
+  - async
+  - server
+version: "2.0"
+description: >-
+  Fetch data in SolidStart v2 with Solid Router queries, createAsync, and
+  server-backed functions compiled from the use server directive.
+---
+
+Data loading is built around Solid Router's [`query`](/solid-router/reference/data-apis/query) API and [`createAsync`](/solid-router/reference/data-apis/create-async).
+The `"use server"` directive lets a query body run only on the server when needed.
+
+## Basic query usage
+
+Use `query` to define cached data loading and `createAsync` to read the result inside a route component.
+
+```tsx title="src/routes/posts.tsx"
+import { For } from "solid-js";
+import { createAsync, query } from "@solidjs/router";
+
+const getPosts = query(async () => {
+	const response = await fetch("https://example.com/api/posts");
+	return response.json() as Promise<Array<{ id: number; title: string }>>;
+}, "posts");
+
+export default function PostsPage() {
+	const posts = createAsync(() => getPosts());
+
+	return <For each={posts()}>{(post) => <li>{post.title}</li>}</For>;
+}
+```
+
+## Keep the data function on the server
+
+If your query needs direct access to server-only resources, add the `"use server"` directive inside the query function.
+
+```tsx title="src/routes/account.tsx"
+import { createAsync, query } from "@solidjs/router";
+import { useSession } from "@solidjs/start/http";
+
+const getCurrentUser = query(async () => {
+	"use server";
+
+	const session = await useSession<{ userId?: string }>({
+		password: process.env.SESSION_SECRET as string,
+		name: "session",
+	});
+
+	return { userId: session.data.userId ?? null };
+}, "currentUser");
+
+export default function AccountPage() {
+	const user = createAsync(() => getCurrentUser());
+	return <pre>{JSON.stringify(user(), null, 2)}</pre>;
+}
+```
+
+## Preload route data
+
+If you want to warm the query before rendering the page, export a `route.preload` function from the route module.
+
+```tsx title="src/routes/posts/[id].tsx"
+import { createAsync, query, type RouteDefinition } from "@solidjs/router";
+
+const getPost = query(async (id: string) => {
+	"use server";
+	const response = await fetch(`https://example.com/api/posts/${id}`);
+	return response.json();
+}, "post");
+
+export const route = {
+	preload: ({ params }) => getPost(params.id),
+} satisfies RouteDefinition;
+
+export default function PostPage(props: { params: { id: string } }) {
+	const post = createAsync(() => getPost(props.params.id));
+	return <pre>{JSON.stringify(post(), null, 2)}</pre>;
+}
+```
+
+Cache invalidation and advanced query behavior are handled by [Solid Router](/solid-router), so use the Solid Router references when you need lower-level cache semantics.
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
new file mode 100644
index 0000000000..54224afd5e
--- /dev/null
+++ b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
@@ -0,0 +1,112 @@
+---
+title: Data mutation
+use_cases: >-
+  form submission, server writes, data updates, user input handling,
+  validation, actions
+tags:
+  - forms
+  - actions
+  - mutations
+  - server
+  - validation
+version: "2.0"
+description: >-
+  Mutate data in SolidStart v2 with Solid Router actions and server-only action
+  bodies compiled from the use server directive.
+---
+
+Mutations run through Solid Router's [`action`](/solid-router/reference/data-apis/action) API.
+When a mutation must run on the server, place the `"use server"` directive inside the action body.
+
+## Handle form submissions with actions
+
+An action can be passed directly to a form element, with named actions and form-driven submission tracking.
+
+```tsx title="src/routes/posts/new.tsx"
+import { action } from "@solidjs/router";
+
+const createPost = action(async (formData: FormData) => {
+	"use server";
+
+	const title = formData.get("title")?.toString() ?? "";
+	return { created: title.length > 0, title };
+}, "createPost");
+
+export default function NewPostPage() {
+	return (
+		<form action={createPost} method="post">
+			<input name="title" />
+			<button>Create post</button>
+		</form>
+	);
+}
+```
+
+## Show pending and error state
+
+Use [`useSubmission`](/solid-router/reference/data-apis/use-submission) from `@solidjs/router` to observe the active submission.
+
+```tsx title="src/routes/profile.tsx"
+import { Show } from "solid-js";
+import { action, useSubmission } from "@solidjs/router";
+
+const saveProfile = action(async (formData: FormData) => {
+	"use server";
+
+	const displayName = formData.get("displayName")?.toString();
+	if (!displayName) {
+		throw new Error("Display name is required.");
+	}
+
+	return { ok: true };
+}, "saveProfile");
+
+export default function ProfilePage() {
+	const submission = useSubmission(saveProfile);
+
+	return (
+		<form action={saveProfile} method="post">
+			<Show when={submission.error}>
+				<p>{submission.error?.message}</p>
+			</Show>
+			<input name="displayName" />
+			<button disabled={submission.pending}>
+				{submission.pending ? "Saving..." : "Save"}
+			</button>
+		</form>
+	);
+}
+```
+
+## Prefill action arguments
+
+Use `.with(...)` to prefill leading arguments.
+
+```tsx title="src/routes/projects/[id].tsx"
+import { action } from "@solidjs/router";
+
+const archiveProject = action(async (projectId: string, formData: FormData) => {
+	"use server";
+
+	return {
+		projectId,
+		reason: formData.get("reason")?.toString() ?? null,
+	};
+}, "archiveProject");
+
+export default function ProjectPage(props: { params: { id: string } }) {
+	return (
+		<form action={archiveProject.with(props.params.id)} method="post">
+			<input name="reason" />
+			<button>Archive</button>
+		</form>
+	);
+}
+```
+
+## Pair actions with route data
+
+When a mutation changes data that is also loaded by a route `query`, keep the read path and write path close together.
+That makes it easier to reason about revalidation behavior through the Solid Router data APIs.
+
+Read this page together with [Data fetching](/v2/solid-start/building-your-application/data-fetching).
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(0)index.mdx b/src/routes/v2/solid-start/(0)index.mdx
new file mode 100644
index 0000000000..ef5e7e7148
--- /dev/null
+++ b/src/routes/v2/solid-start/(0)index.mdx
@@ -0,0 +1,42 @@
+---
+title: Overview
+titleTemplate: ":title"
+use_cases: >-
+  getting started, new projects, learning solidstart, framework overview,
+  architecture decisions
+tags:
+  - overview
+  - introduction
+  - getting-started
+  - routing
+  - server
+version: "2.0"
+description: >-
+  SolidStart v2 overview: routing, server functions, HTTP helpers, and
+  Vite-based configuration.
+---
+
+SolidStart 2.0 builds a full-stack app on top of [Solid](/) and [Solid Router](/solid-router), with file-based routing, server functions, and Vite-based configuration.
+
+The framework is split into a handful of entry points:
+
+- `@solidjs/start/config` for the `solidStart()` Vite plugin
+- `@solidjs/start/router` for file-routed UI integration
+- `@solidjs/start/server` for server rendering helpers and server-side types
+- `@solidjs/start/http` for request, response, cookie, and session helpers
+- `@solidjs/start/middleware` for middleware composition
+
+## What v2 keeps
+
+The core model carries over from v1:
+
+- File-based routing from `src/routes`
+- API route handlers exported by HTTP method name
+- Server-backed data loading and mutation with `query` and `action`
+- Server-only code compiled from the `"use server"` directive
+
+## What changed from v1
+
+Configuration moved from `app.config.ts` to `vite.config.ts` through `solidStart()`.
+
+If you are upgrading an existing app, start with the [migration guide](/v2/solid-start/migrating-from-v1).
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(1)getting-started.mdx b/src/routes/v2/solid-start/(1)getting-started.mdx
new file mode 100644
index 0000000000..e750e4b9d4
--- /dev/null
+++ b/src/routes/v2/solid-start/(1)getting-started.mdx
@@ -0,0 +1,91 @@
+---
+title: Getting started
+use_cases: >-
+  new project, initial setup, project creation, starter template, first app,
+  quick start, bootstrapping
+tags:
+  - setup
+  - installation
+  - starter
+  - template
+  - quickstart
+version: "2.0"
+description: >-
+  Start a SolidStart v2 project with create-solid and configure the Vite
+  plugin.
+---
+
+The easiest way to start a new SolidStart project is with `create-solid`.
+It can scaffold a new app from the SolidStart template or from one of the official examples.
+
+## Create a project
+
+Create a new app with the Solid scaffolding tool:
+
+```package-create
+solid
+```
+
+Follow the interactive prompts and choose the SolidStart template or an official example that matches your use case.
+
+After the project is created, install dependencies:
+
+```package-install-local
+
+```
+
+Then start the development server:
+
+```package-run
+dev
+```
+
+## Configuration
+
+Configuration lives in `vite.config.ts`, where the `solidStart()` plugin from `@solidjs/start/config` does the work.
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+	plugins: [solidStart()],
+});
+```
+
+If your app already has middleware, `solidStart()` also accepts a `middleware` option:
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+	plugins: [solidStart({ middleware: "./src/middleware/index.ts" })],
+});
+```
+
+## Start adding routes
+
+The filesystem router reads files from your routes directory and turns them into UI routes or API routes.
+For example:
+
+- `src/routes/index.tsx` becomes `/`
+- `src/routes/about.tsx` becomes `/about`
+- `src/routes/api/ping.ts` can expose `/api/ping`
+
+Read [Routing](/v2/solid-start/building-your-application/routing) next if you want the exact filename conventions.
+
+## Type support
+
+Environment types ship in `@solidjs/start/env`.
+Add it to your TypeScript config if your template has not already done so.
+
+```json
+{
+	"compilerOptions": {
+		"types": ["@solidjs/start/env"]
+	}
+}
+```
+
+If you are migrating an existing app instead of creating a new one, continue with [Migrating from v1](/v2/solid-start/migrating-from-v1).
\ No newline at end of file
diff --git a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
index 04bde4e19e..0e2b86eaba 100644
--- a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
+++ b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
@@ -14,8 +14,8 @@ description: >-
   Migrate your SolidStart project from v1 to v2.
 ---
 
-This guide covers the package-level changes that are verified for `@solidjs/start@2.0.0-alpha.3`.
-It focuses on the parts of the migration that are confirmed in this session from the published package surface and current repository configuration.
+This guide covers the package-level migration changes for SolidStart 2.0.
+It focuses on the parts of the upgrade that already have corresponding v2 docs in this site.
 
 Some ecosystem packages may still target v1-only APIs.
 Audit those dependencies before shipping a production upgrade.
@@ -32,13 +32,12 @@ Audit those dependencies before shipping a production upgrade.
 vinxi
 ```
 
-The published `2.0.0-alpha.3` package exports its framework plugin from `@solidjs/start/config`.
-That is the verified entry point for configuring a v2 app.
+The framework plugin now comes from `@solidjs/start/config`.
 
 ### Move framework configuration into `vite.config.ts`
 
 V1 projects centered their framework configuration around `app.config.ts`.
-For the current v2 alpha, move that setup into a Vite config that calls `solidStart()`.
+Move that setup into a Vite config that calls `solidStart()`.
 
 ```tsx title="vite.config.ts"
 import { defineConfig } from "vite";
@@ -49,7 +48,7 @@ export default defineConfig({
 });
 ```
 
-If your app already has custom middleware, the published v2 config type also exposes a `middleware` option:
+If your app already has custom middleware, `solidStart()` also exposes a `middleware` option:
 
 ```tsx title="vite.config.ts"
 import { defineConfig } from "vite";
@@ -62,18 +61,18 @@ export default defineConfig({
 
 ### Update server runtime imports
 
-The current v2 package exports HTTP helpers from `@solidjs/start/http`.
+HTTP helpers are exported from `@solidjs/start/http`.
 Replace imports from `vinxi/http` with that module.
 
 ```tsx
 import { getCookie, setCookie, useSession } from "@solidjs/start/http";
 ```
 
-The published HTTP entrypoint exposes helpers such as `readBody`, `getQuery`, `getRequestHeader`, `setResponseHeader`, `useSession`, and related cookie/session utilities.
+The HTTP entrypoint exposes helpers such as `readBody`, `getQuery`, `getRequestHeader`, `setResponseHeader`, `useSession`, and related cookie/session utilities.
 
 ### Update TypeScript environment types
 
-The current package also publishes `@solidjs/start/env` for type support.
+Environment types ship in `@solidjs/start/env`.
 Make sure your TypeScript config includes it.
 
 ```json
@@ -86,7 +85,7 @@ Make sure your TypeScript config includes it.
 
 ### Revisit middleware syntax
 
-The v2 middleware entrypoint exports `createMiddleware`, and its published types now prefer H3 middleware arrays.
+The v2 middleware entrypoint exports `createMiddleware`, and its types now prefer H3 middleware arrays.
 The older `onRequest` and `onBeforeResponse` object form is still present but marked deprecated in the package types.
 
 ```tsx
@@ -99,10 +98,10 @@ export default createMiddleware([
 ]);
 ```
 
-## Still unknown in this session
+## Still in the v1 docs
 
-- The full replacement guidance for every v1 entrypoint file is Unknown.
-- The recommended production `start` script for generated apps is Unknown.
-- The exact v2 equivalents for advanced topics like auth, prerendering, metadata, and background tasks are Unknown.
+A few topics keep their v1 guidance until the v2 pages land:
 
-Keep those areas on the v1 docs until the current v2 API and examples are verified.
\ No newline at end of file
+- Entrypoint file replacements
+- Production `start` script names for generated apps
+- Auth, prerendering, metadata, and background tasks
\ No newline at end of file

From 89fcf0026ff860910b9f921ad535755be99c7045 Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Sun, 28 Jun 2026 18:23:07 -0700
Subject: [PATCH 3/7] Add SolidStart v2 documentation for new server functions,
 middleware, and HTTP handling components

---
 .../(1)api-routes.mdx                         |  2 +-
 .../(4)data-mutation.mdx                      |  2 +-
 .../reference/client/client-only.mdx          | 75 +++++++++++++++++++
 .../reference/routing/file-routes.mdx         | 63 ++++++++++++++++
 .../reference/server/create-middleware.mdx    | 68 +++++++++++++++++
 .../server/get-server-function-meta.mdx       | 58 ++++++++++++++
 .../v2/solid-start/reference/server/get.mdx   | 61 +++++++++++++++
 .../reference/server/http-header.mdx          | 73 ++++++++++++++++++
 .../reference/server/http-status-code.mdx     | 65 ++++++++++++++++
 .../reference/server/use-server.mdx           | 64 ++++++++++++++++
 10 files changed, 529 insertions(+), 2 deletions(-)
 create mode 100644 src/routes/v2/solid-start/reference/client/client-only.mdx
 create mode 100644 src/routes/v2/solid-start/reference/routing/file-routes.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/create-middleware.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/get.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/http-header.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/http-status-code.mdx
 create mode 100644 src/routes/v2/solid-start/reference/server/use-server.mdx

diff --git a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
index e6a50aaf2e..0a930696d2 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
@@ -17,7 +17,7 @@ description: >-
 
 Use an API route when you need a route that returns data or handles incoming HTTP requests instead of rendering page UI.
 
-A file becomes an API route when it exports one or more HTTP method names such as `GET`, `POST`, `PATCH`, or `DELETE`.
+A file becomes an API route when it exports one or more HTTP method names such as [`GET`](/v2/solid-start/reference/server/get), `POST`, `PATCH`, or `DELETE`.
 
 ## Create an API route
 
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
index 54224afd5e..791aba71cd 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
@@ -16,7 +16,7 @@ description: >-
 ---
 
 Mutations run through Solid Router's [`action`](/solid-router/reference/data-apis/action) API.
-When a mutation must run on the server, place the `"use server"` directive inside the action body.
+When a mutation must run on the server, place the [`"use server"`](/v2/solid-start/reference/server/use-server) directive inside the action body.
 
 ## Handle form submissions with actions
 
diff --git a/src/routes/v2/solid-start/reference/client/client-only.mdx b/src/routes/v2/solid-start/reference/client/client-only.mdx
new file mode 100644
index 0000000000..1d630749f9
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/client/client-only.mdx
@@ -0,0 +1,75 @@
+---
+title: clientOnly
+use_cases: >-
+  client-only components, browser-only imports, fallback rendering
+tags:
+  - client
+  - component
+  - lazy
+version: "2.0"
+description: >-
+  clientOnly creates a component that renders only on the client.
+---
+
+`clientOnly` wraps an async component import and renders a fallback on the server.
+
+## Import
+
+```tsx
+import { clientOnly } from "@solidjs/start";
+```
+
+## Type
+
+```tsx
+function clientOnly<T extends Component<any>>(
+	fn: () => Promise<{ default: T }>,
+	options?: { lazy?: boolean }
+): (props: ComponentProps<T> & { fallback?: JSX.Element }) => any;
+```
+
+## Parameters
+
+### `fn`
+
+- **Type:** `() => Promise<{ default: T }>`
+- **Required:** Yes
+
+Function that imports the client component.
+
+### `options`
+
+- **Type:** `{ lazy?: boolean }`
+- **Required:** No
+
+Loading options. A truthy `lazy` defers the import to the returned component.
+
+## Return value
+
+- **Type:** `(props: ComponentProps<T> & { fallback?: JSX.Element }) => any`
+
+Returns a component for the imported default export.
+
+## Behavior
+
+- On the server, the component renders `props.fallback`.
+- The client loads `fn` immediately unless `lazy` is set.
+- `fallback` is split from the remaining props before the loaded component renders.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { clientOnly } from "@solidjs/start";
+
+const Map = clientOnly(() => import("./Map"), { lazy: true });
+
+export default function Page() {
+	return <Map fallback={<p>Loading map...</p>} />;
+}
+```
+
+## Related
+
+- [Routing](/v2/solid-start/building-your-application/routing)
diff --git a/src/routes/v2/solid-start/reference/routing/file-routes.mdx b/src/routes/v2/solid-start/reference/routing/file-routes.mdx
new file mode 100644
index 0000000000..e265c1fb58
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/routing/file-routes.mdx
@@ -0,0 +1,63 @@
+---
+title: FileRoutes
+use_cases: >-
+  file routes, route definitions, filesystem routes
+tags:
+  - routing
+  - files
+  - routes
+  - component
+version: "2.0"
+description: >-
+  FileRoutes returns route definitions generated from filesystem routes.
+---
+
+`FileRoutes` returns route definitions generated from filesystem routes.
+
+## Import
+
+```tsx
+import { FileRoutes } from "@solidjs/start/router";
+```
+
+## Type
+
+```tsx
+const FileRoutes: () => any[];
+```
+
+## Parameters
+
+`FileRoutes` takes no arguments.
+
+## Return value
+
+- **Type:** `any[]`
+
+Returns generated route definitions.
+
+## Behavior
+
+- On the server, `FileRoutes` returns the request event routes.
+- Client routes come from the generated page route config and are cached in module scope.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { Router } from "@solidjs/router";
+import { FileRoutes } from "@solidjs/start/router";
+
+export default function App() {
+	return (
+		<Router>
+			<FileRoutes />
+		</Router>
+	);
+}
+```
+
+## Related
+
+- [Routing](/v2/solid-start/building-your-application/routing)
diff --git a/src/routes/v2/solid-start/reference/server/create-middleware.mdx b/src/routes/v2/solid-start/reference/server/create-middleware.mdx
new file mode 100644
index 0000000000..46d3933f29
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/create-middleware.mdx
@@ -0,0 +1,68 @@
+---
+title: createMiddleware
+use_cases: >-
+  request middleware, response middleware, h3 middleware
+tags:
+  - server
+  - middleware
+  - request
+  - response
+version: "2.0"
+description: >-
+  createMiddleware composes H3 middleware for SolidStart.
+---
+
+`createMiddleware` composes middleware for handling requests and responses. It takes an array of [H3 middleware](https://h3.dev/guide/basics/middleware).
+
+## Import
+
+```tsx
+import { createMiddleware } from "@solidjs/start/middleware";
+```
+
+## Type
+
+```tsx
+function createMiddleware(args: Middleware[]): Middleware[];
+```
+
+## Parameters
+
+### `args`
+
+- **Type:** `Middleware[]`
+- **Required:** Yes
+
+An array of [H3 middleware](https://h3.dev/guide/basics/middleware). To run logic before the response, `await next()` inside the middleware.
+
+## Return value
+
+- **Type:** `Middleware[]`
+
+Returns the composed middleware array.
+
+## Behavior
+
+- Each middleware receives the event and a `next` function.
+- A returned `Response` ends the chain.
+- The object form with `onRequest` and `onBeforeResponse` still works but is deprecated.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+	async (event, next) => {
+		const response = await next();
+		if (response instanceof Response) return response;
+		return new Response("Not found", { status: 404 });
+	},
+]);
+```
+
+## Related
+
+- [API routes](/v2/solid-start/building-your-application/api-routes)
diff --git a/src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx b/src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx
new file mode 100644
index 0000000000..5cc6e387dd
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx
@@ -0,0 +1,58 @@
+---
+title: getServerFunctionMeta
+use_cases: >-
+  server function metadata, request metadata, server functions
+tags:
+  - server
+  - functions
+  - metadata
+version: "2.0"
+description: >-
+  getServerFunctionMeta returns metadata for the current server function request.
+---
+
+`getServerFunctionMeta` reads server function metadata from the current request event locals.
+
+## Import
+
+```tsx
+import { getServerFunctionMeta } from "@solidjs/start";
+```
+
+## Type
+
+```tsx
+interface ServerFunctionMeta {
+	id: string;
+}
+
+function getServerFunctionMeta(): ServerFunctionMeta | undefined;
+```
+
+## Parameters
+
+`getServerFunctionMeta` takes no arguments.
+
+## Return value
+
+- **Type:** `ServerFunctionMeta | undefined`
+
+Returns `getRequestEvent()?.locals.serverFunctionMeta`.
+
+## Behavior
+
+- With no request event, `getServerFunctionMeta` returns `undefined`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { getServerFunctionMeta } from "@solidjs/start";
+
+const meta = getServerFunctionMeta();
+```
+
+## Related
+
+- [`"use server"`](/v2/solid-start/reference/server/use-server)
diff --git a/src/routes/v2/solid-start/reference/server/get.mdx b/src/routes/v2/solid-start/reference/server/get.mdx
new file mode 100644
index 0000000000..d3a15d8166
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/get.mdx
@@ -0,0 +1,61 @@
+---
+title: GET
+use_cases: >-
+  server functions, get handlers, query functions
+tags:
+  - server
+  - get
+  - function
+version: "2.0"
+description: >-
+  GET returns the GET handler attached to a server function.
+---
+
+`GET` returns the `.GET` property from a function.
+
+## Import
+
+```tsx
+import { GET } from "@solidjs/start";
+```
+
+## Type
+
+```tsx
+function GET<T extends (...args: any[]) => any>(
+	fn: T
+): (...args: Parameters<T>) => ReturnType<T>;
+```
+
+## Parameters
+
+### `fn`
+
+- **Type:** `T extends (...args: any[]) => any`
+- **Required:** Yes
+
+Function with a `GET` property.
+
+## Return value
+
+- **Type:** `(...args: Parameters<T>) => ReturnType<T>`
+
+Returns `fn.GET`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { GET } from "@solidjs/start";
+
+const getMessage = Object.assign(async () => "hello", {
+	GET: async () => "hello",
+});
+
+const handler = GET(getMessage);
+```
+
+## Related
+
+- [Data fetching](/v2/solid-start/building-your-application/data-fetching)
diff --git a/src/routes/v2/solid-start/reference/server/http-header.mdx b/src/routes/v2/solid-start/reference/server/http-header.mdx
new file mode 100644
index 0000000000..687c771399
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/http-header.mdx
@@ -0,0 +1,73 @@
+---
+title: HttpHeader
+use_cases: >-
+  response headers, server rendering, header cleanup
+tags:
+  - server
+  - headers
+  - component
+version: "2.0"
+description: >-
+  HttpHeader sets or appends a response header during server rendering.
+---
+
+`HttpHeader` sets or appends a response header on the server.
+
+## Import
+
+```tsx
+import { HttpHeader } from "@solidjs/start";
+```
+
+## Type
+
+```tsx
+interface HttpHeaderProps {
+	name: string;
+	value: string;
+	append?: boolean;
+}
+
+const HttpHeader: (props: HttpHeaderProps) => null;
+```
+
+## Props
+
+### `name`
+
+- **Type:** `string`
+- **Optional:** No
+
+Header name.
+
+### `value`
+
+- **Type:** `string`
+- **Optional:** No
+
+Header value.
+
+### `append`
+
+- **Type:** `boolean`
+- **Optional:** Yes
+
+Appends the value instead of setting it.
+
+## Behavior
+
+- A truthy `append` calls `appendHeader(name, value)`; otherwise `setHeader(name, value)` runs.
+- Cleanup removes its own header value unless the event has completed or been handled.
+- Client rendering returns `null`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { HttpHeader } from "@solidjs/start";
+
+export default function Page() {
+	return <HttpHeader name="cache-control" value="max-age=60" />;
+}
+```
diff --git a/src/routes/v2/solid-start/reference/server/http-status-code.mdx b/src/routes/v2/solid-start/reference/server/http-status-code.mdx
new file mode 100644
index 0000000000..666dc63eb3
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/http-status-code.mdx
@@ -0,0 +1,65 @@
+---
+title: HttpStatusCode
+use_cases: >-
+  response status, server rendering, status text
+tags:
+  - server
+  - status
+  - component
+version: "2.0"
+description: >-
+  HttpStatusCode sets the response status during server rendering.
+---
+
+`HttpStatusCode` sets the response status code on the server.
+
+## Import
+
+```tsx
+import { HttpStatusCode } from "@solidjs/start";
+```
+
+## Type
+
+```tsx
+interface HttpStatusCodeProps {
+	code: number;
+	text?: string;
+}
+
+const HttpStatusCode: (props: HttpStatusCodeProps) => null;
+```
+
+## Props
+
+### `code`
+
+- **Type:** `number`
+- **Optional:** No
+
+HTTP status code assigned to the response.
+
+### `text`
+
+- **Type:** `string`
+- **Optional:** Yes
+
+HTTP status text assigned to the response.
+
+## Behavior
+
+- `event.response.status` is set to `code` and `event.response.statusText` to `text`.
+- Cleanup resets the status to `200` when the event is not complete.
+- Client rendering returns `null`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { HttpStatusCode } from "@solidjs/start";
+
+export default function NotFound() {
+	return <HttpStatusCode code={404} />;
+}
+```
diff --git a/src/routes/v2/solid-start/reference/server/use-server.mdx b/src/routes/v2/solid-start/reference/server/use-server.mdx
new file mode 100644
index 0000000000..8d88ed3184
--- /dev/null
+++ b/src/routes/v2/solid-start/reference/server/use-server.mdx
@@ -0,0 +1,64 @@
+---
+title: '"use server"'
+use_cases: >-
+  server functions, server-only functions, server references
+tags:
+  - server
+  - directive
+  - functions
+version: "2.0"
+description: >-
+  "use server" marks server functions for the server function compiler.
+---
+
+`"use server"` is the directive string recognized by the server function compiler.
+
+## Import
+
+No import is required for the directive.
+
+## Type
+
+```tsx
+const DIRECTIVE = "use server";
+```
+
+## Parameters
+
+The directive has no parameters.
+
+## Return value
+
+The directive does not return a value.
+
+## Behavior
+
+- The compiler uses `"use server"` as its directive string.
+- Client builds transform server references with the configured client runtime.
+- SSR and server-function builds use the configured server runtime for transformed references.
+- Valid transformed modules are added to the server function manifest.
+
+## Examples
+
+### Function directive
+
+```tsx
+const logMessage = async (message: string) => {
+	"use server";
+	console.log(message);
+};
+```
+
+### File directive
+
+```tsx
+"use server";
+
+export async function logMessage(message: string) {
+	console.log(message);
+}
+```
+
+## Related
+
+- [`getServerFunctionMeta`](/v2/solid-start/reference/server/get-server-function-meta)

From aef930dae170ac2338287b054b038cc3dac74667 Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Sun, 28 Jun 2026 18:25:00 -0700
Subject: [PATCH 4/7] Add v2 SolidStart serialization page

---
 .../(1)advanced/(4)serialization.mdx          | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx

diff --git a/src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx b/src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx
new file mode 100644
index 0000000000..dec2830f0b
--- /dev/null
+++ b/src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx
@@ -0,0 +1,46 @@
+---
+title: Serialization
+use_cases: >-
+  server function payloads, data transfer, csp, security, performance
+tags:
+  - serialization
+  - server-functions
+  - csp
+  - security
+  - performance
+version: "2.0"
+description: >-
+  How SolidStart serializes server function payloads and the CSP tradeoff
+  between json and js modes.
+---
+
+Server function arguments and return values are serialized so they can travel between server and client.
+
+## Configuration
+
+Set the mode on `solidStart()` in `vite.config.ts`:
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+	plugins: [
+		solidStart({
+			serialization: { mode: "json" },
+		}),
+	],
+});
+```
+
+## Modes
+
+- `json`: deserializes with `JSON.parse` on the client. It avoids `eval`, so it fits a strict CSP. This is the default.
+- `js`: a smaller binary format that needs `eval` on the client, which a strong CSP blocks.
+
+If your app enforces a Content Security Policy, keep `json`.
+
+## Related
+
+- [Data fetching](/v2/solid-start/building-your-application/data-fetching)
+- [Data mutation](/v2/solid-start/building-your-application/data-mutation)

From f03db79f8a91d6af823c6d42da72d8a1dcd45719 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 29 Jun 2026 01:28:58 +0000
Subject: [PATCH 5/7] ci: apply automated fixes

---
 .../v2/solid-start/(0)building-your-application/(0)routing.mdx  | 2 +-
 .../solid-start/(0)building-your-application/(1)api-routes.mdx  | 2 +-
 .../(0)building-your-application/(3)data-fetching.mdx           | 2 +-
 .../(0)building-your-application/(4)data-mutation.mdx           | 2 +-
 src/routes/v2/solid-start/(0)index.mdx                          | 2 +-
 src/routes/v2/solid-start/(1)getting-started.mdx                | 2 +-
 src/routes/v2/solid-start/(2)migrating-from-v1.mdx              | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx b/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
index 3722e39046..fdfcae5a93 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
@@ -81,4 +81,4 @@ export default function PostPage(props: { params: { id: string } }) {
 	const post = createAsync(() => getPost(props.params.id));
 	return <pre>{JSON.stringify(post(), null, 2)}</pre>;
 }
-```
\ No newline at end of file
+```
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
index 0a930696d2..d2461a50e6 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
@@ -87,4 +87,4 @@ API routes are a good fit when you need:
 - auth callback handlers
 - routes that return non-HTML responses
 
-If the data is only needed by your route UI, prefer [Data fetching](/v2/solid-start/building-your-application/data-fetching) or [Data mutation](/v2/solid-start/building-your-application/data-mutation) before introducing a separate API boundary.
\ No newline at end of file
+If the data is only needed by your route UI, prefer [Data fetching](/v2/solid-start/building-your-application/data-fetching) or [Data mutation](/v2/solid-start/building-your-application/data-mutation) before introducing a separate API boundary.
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx b/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
index 89d541ee3b..1da23b5f5e 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
@@ -86,4 +86,4 @@ export default function PostPage(props: { params: { id: string } }) {
 }
 ```
 
-Cache invalidation and advanced query behavior are handled by [Solid Router](/solid-router), so use the Solid Router references when you need lower-level cache semantics.
\ No newline at end of file
+Cache invalidation and advanced query behavior are handled by [Solid Router](/solid-router), so use the Solid Router references when you need lower-level cache semantics.
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
index 791aba71cd..e6c763211b 100644
--- a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
+++ b/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
@@ -109,4 +109,4 @@ export default function ProjectPage(props: { params: { id: string } }) {
 When a mutation changes data that is also loaded by a route `query`, keep the read path and write path close together.
 That makes it easier to reason about revalidation behavior through the Solid Router data APIs.
 
-Read this page together with [Data fetching](/v2/solid-start/building-your-application/data-fetching).
\ No newline at end of file
+Read this page together with [Data fetching](/v2/solid-start/building-your-application/data-fetching).
diff --git a/src/routes/v2/solid-start/(0)index.mdx b/src/routes/v2/solid-start/(0)index.mdx
index ef5e7e7148..f3ac798f36 100644
--- a/src/routes/v2/solid-start/(0)index.mdx
+++ b/src/routes/v2/solid-start/(0)index.mdx
@@ -39,4 +39,4 @@ The core model carries over from v1:
 
 Configuration moved from `app.config.ts` to `vite.config.ts` through `solidStart()`.
 
-If you are upgrading an existing app, start with the [migration guide](/v2/solid-start/migrating-from-v1).
\ No newline at end of file
+If you are upgrading an existing app, start with the [migration guide](/v2/solid-start/migrating-from-v1).
diff --git a/src/routes/v2/solid-start/(1)getting-started.mdx b/src/routes/v2/solid-start/(1)getting-started.mdx
index e750e4b9d4..9817f03ebe 100644
--- a/src/routes/v2/solid-start/(1)getting-started.mdx
+++ b/src/routes/v2/solid-start/(1)getting-started.mdx
@@ -88,4 +88,4 @@ Add it to your TypeScript config if your template has not already done so.
 }
 ```
 
-If you are migrating an existing app instead of creating a new one, continue with [Migrating from v1](/v2/solid-start/migrating-from-v1).
\ No newline at end of file
+If you are migrating an existing app instead of creating a new one, continue with [Migrating from v1](/v2/solid-start/migrating-from-v1).
diff --git a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
index 0e2b86eaba..2ea44c50f4 100644
--- a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
+++ b/src/routes/v2/solid-start/(2)migrating-from-v1.mdx
@@ -104,4 +104,4 @@ A few topics keep their v1 guidance until the v2 pages land:
 
 - Entrypoint file replacements
 - Production `start` script names for generated apps
-- Auth, prerendering, metadata, and background tasks
\ No newline at end of file
+- Auth, prerendering, metadata, and background tasks

From de5da6cd70a7e464bc8f387310dd79fe56a9489d Mon Sep 17 00:00:00 2001
From: Brenley Dueck <brenleydueck@gmail.com>
Date: Mon, 29 Jun 2026 19:30:49 -0500
Subject: [PATCH 6/7] Move SolidStart v2 docs under SolidStart routes

---
 .../v2}/(0)building-your-application/(0)routing.mdx   |  0
 .../(0)building-your-application/(1)api-routes.mdx    |  0
 .../(0)building-your-application/(3)data-fetching.mdx |  0
 .../(0)building-your-application/(4)data-mutation.mdx |  0
 .../{v2/solid-start => solid-start/v2}/(0)index.mdx   |  0
 .../v2}/(1)advanced/(4)serialization.mdx              |  0
 .../v2}/(1)getting-started.mdx                        |  0
 .../v2}/(2)migrating-from-v1.mdx                      |  0
 .../v2}/reference/client/client-only.mdx              |  0
 .../v2}/reference/routing/file-routes.mdx             |  0
 .../v2}/reference/server/create-middleware.mdx        |  0
 .../v2}/reference/server/get-server-function-meta.mdx |  0
 .../v2}/reference/server/get.mdx                      |  0
 .../v2}/reference/server/http-header.mdx              |  0
 .../v2}/reference/server/http-status-code.mdx         |  0
 .../v2}/reference/server/use-server.mdx               | 11 +++++++++++
 vite.config.ts                                        |  2 +-
 17 files changed, 12 insertions(+), 1 deletion(-)
 rename src/routes/{v2/solid-start => solid-start/v2}/(0)building-your-application/(0)routing.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(0)building-your-application/(1)api-routes.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(0)building-your-application/(3)data-fetching.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(0)building-your-application/(4)data-mutation.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(0)index.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(1)advanced/(4)serialization.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(1)getting-started.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/(2)migrating-from-v1.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/client/client-only.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/routing/file-routes.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/create-middleware.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/get-server-function-meta.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/get.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/http-header.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/http-status-code.mdx (100%)
 rename src/routes/{v2/solid-start => solid-start/v2}/reference/server/use-server.mdx (72%)

diff --git a/src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx b/src/routes/solid-start/v2/(0)building-your-application/(0)routing.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(0)building-your-application/(0)routing.mdx
rename to src/routes/solid-start/v2/(0)building-your-application/(0)routing.mdx
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx b/src/routes/solid-start/v2/(0)building-your-application/(1)api-routes.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(0)building-your-application/(1)api-routes.mdx
rename to src/routes/solid-start/v2/(0)building-your-application/(1)api-routes.mdx
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx b/src/routes/solid-start/v2/(0)building-your-application/(3)data-fetching.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(0)building-your-application/(3)data-fetching.mdx
rename to src/routes/solid-start/v2/(0)building-your-application/(3)data-fetching.mdx
diff --git a/src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx b/src/routes/solid-start/v2/(0)building-your-application/(4)data-mutation.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(0)building-your-application/(4)data-mutation.mdx
rename to src/routes/solid-start/v2/(0)building-your-application/(4)data-mutation.mdx
diff --git a/src/routes/v2/solid-start/(0)index.mdx b/src/routes/solid-start/v2/(0)index.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(0)index.mdx
rename to src/routes/solid-start/v2/(0)index.mdx
diff --git a/src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx b/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(1)advanced/(4)serialization.mdx
rename to src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
diff --git a/src/routes/v2/solid-start/(1)getting-started.mdx b/src/routes/solid-start/v2/(1)getting-started.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(1)getting-started.mdx
rename to src/routes/solid-start/v2/(1)getting-started.mdx
diff --git a/src/routes/v2/solid-start/(2)migrating-from-v1.mdx b/src/routes/solid-start/v2/(2)migrating-from-v1.mdx
similarity index 100%
rename from src/routes/v2/solid-start/(2)migrating-from-v1.mdx
rename to src/routes/solid-start/v2/(2)migrating-from-v1.mdx
diff --git a/src/routes/v2/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/v2/reference/client/client-only.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/client/client-only.mdx
rename to src/routes/solid-start/v2/reference/client/client-only.mdx
diff --git a/src/routes/v2/solid-start/reference/routing/file-routes.mdx b/src/routes/solid-start/v2/reference/routing/file-routes.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/routing/file-routes.mdx
rename to src/routes/solid-start/v2/reference/routing/file-routes.mdx
diff --git a/src/routes/v2/solid-start/reference/server/create-middleware.mdx b/src/routes/solid-start/v2/reference/server/create-middleware.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/server/create-middleware.mdx
rename to src/routes/solid-start/v2/reference/server/create-middleware.mdx
diff --git a/src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx b/src/routes/solid-start/v2/reference/server/get-server-function-meta.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/server/get-server-function-meta.mdx
rename to src/routes/solid-start/v2/reference/server/get-server-function-meta.mdx
diff --git a/src/routes/v2/solid-start/reference/server/get.mdx b/src/routes/solid-start/v2/reference/server/get.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/server/get.mdx
rename to src/routes/solid-start/v2/reference/server/get.mdx
diff --git a/src/routes/v2/solid-start/reference/server/http-header.mdx b/src/routes/solid-start/v2/reference/server/http-header.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/server/http-header.mdx
rename to src/routes/solid-start/v2/reference/server/http-header.mdx
diff --git a/src/routes/v2/solid-start/reference/server/http-status-code.mdx b/src/routes/solid-start/v2/reference/server/http-status-code.mdx
similarity index 100%
rename from src/routes/v2/solid-start/reference/server/http-status-code.mdx
rename to src/routes/solid-start/v2/reference/server/http-status-code.mdx
diff --git a/src/routes/v2/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/v2/reference/server/use-server.mdx
similarity index 72%
rename from src/routes/v2/solid-start/reference/server/use-server.mdx
rename to src/routes/solid-start/v2/reference/server/use-server.mdx
index 8d88ed3184..722edffc4c 100644
--- a/src/routes/v2/solid-start/reference/server/use-server.mdx
+++ b/src/routes/solid-start/v2/reference/server/use-server.mdx
@@ -59,6 +59,17 @@ export async function logMessage(message: string) {
 }
 ```
 
+:::note[Using with query]
+When wrapping a server function with [`query`](/solid-router/reference/data-apis/query), place `"use server"` inside the inner function rather than at the file level. A file-level directive turns the whole module — including the `query` wrapper that also runs on the client — into a server reference.
+
+```tsx
+export const logMessage = query(async (message: string) => {
+	"use server";
+	console.log(message);
+}, "log-message");
+```
+:::
+
 ## Related
 
 - [`getServerFunctionMeta`](/v2/solid-start/reference/server/get-server-function-meta)
diff --git a/vite.config.ts b/vite.config.ts
index 47283a44cb..9005074d8b 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -84,7 +84,7 @@ export default defineConfig({
 					themeConfig: {
 						sidebar: {
 							"/v2/solid-start": createFilesystemSidebar(
-								"./src/routes/v2/solid-start"
+								"./src/routes/solid-start/v2"
 							),
 						},
 					},

From 7acd72a5cc7cff16455a4b7329bf101b8f1a9f40 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Tue, 30 Jun 2026 00:31:36 +0000
Subject: [PATCH 7/7] ci: apply automated fixes

---
 src/routes/solid-start/v2/reference/server/use-server.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/routes/solid-start/v2/reference/server/use-server.mdx b/src/routes/solid-start/v2/reference/server/use-server.mdx
index 722edffc4c..3cbffd8e8c 100644
--- a/src/routes/solid-start/v2/reference/server/use-server.mdx
+++ b/src/routes/solid-start/v2/reference/server/use-server.mdx
@@ -68,6 +68,7 @@ export const logMessage = query(async (message: string) => {
 	console.log(message);
 }, "log-message");
 ```
+
 :::
 
 ## Related