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/solid-start/v2/(0)building-your-application/(0)routing.mdx b/src/routes/solid-start/v2/(0)building-your-application/(0)routing.mdx
new file mode 100644
index 0000000000..fdfcae5a93
--- /dev/null
+++ b/src/routes/solid-start/v2/(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 User {params.id}
;
+}
+```
+
+## 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 {JSON.stringify(post(), null, 2)};
+}
+```
diff --git a/src/routes/solid-start/v2/(0)building-your-application/(1)api-routes.mdx b/src/routes/solid-start/v2/(0)building-your-application/(1)api-routes.mdx
new file mode 100644
index 0000000000..d2461a50e6
--- /dev/null
+++ b/src/routes/solid-start/v2/(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`](/v2/solid-start/reference/server/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.
diff --git a/src/routes/solid-start/v2/(0)building-your-application/(3)data-fetching.mdx b/src/routes/solid-start/v2/(0)building-your-application/(3)data-fetching.mdx
new file mode 100644
index 0000000000..1da23b5f5e
--- /dev/null
+++ b/src/routes/solid-start/v2/(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>;
+}, "posts");
+
+export default function PostsPage() {
+ const posts = createAsync(() => getPosts());
+
+ return {(post) => {post.title}};
+}
+```
+
+## 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 {JSON.stringify(user(), null, 2)};
+}
+```
+
+## 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 {JSON.stringify(post(), null, 2)};
+}
+```
+
+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/solid-start/v2/(0)building-your-application/(4)data-mutation.mdx b/src/routes/solid-start/v2/(0)building-your-application/(4)data-mutation.mdx
new file mode 100644
index 0000000000..e6c763211b
--- /dev/null
+++ b/src/routes/solid-start/v2/(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"`](/v2/solid-start/reference/server/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 (
+
+ );
+}
+```
+
+## 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 (
+
+ );
+}
+```
+
+## 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 (
+
+ );
+}
+```
+
+## 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).
diff --git a/src/routes/solid-start/v2/(0)index.mdx b/src/routes/solid-start/v2/(0)index.mdx
new file mode 100644
index 0000000000..f3ac798f36
--- /dev/null
+++ b/src/routes/solid-start/v2/(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).
diff --git a/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx b/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
new file mode 100644
index 0000000000..dec2830f0b
--- /dev/null
+++ b/src/routes/solid-start/v2/(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)
diff --git a/src/routes/solid-start/v2/(1)getting-started.mdx b/src/routes/solid-start/v2/(1)getting-started.mdx
new file mode 100644
index 0000000000..9817f03ebe
--- /dev/null
+++ b/src/routes/solid-start/v2/(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).
diff --git a/src/routes/solid-start/v2/(2)migrating-from-v1.mdx b/src/routes/solid-start/v2/(2)migrating-from-v1.mdx
new file mode 100644
index 0000000000..2ea44c50f4
--- /dev/null
+++ b/src/routes/solid-start/v2/(2)migrating-from-v1.mdx
@@ -0,0 +1,107 @@
+---
+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 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.
+
+## Migration steps
+
+### Update dependencies
+
+```package-install
+@solidjs/start@2.0.0-alpha.3
+```
+
+```package-remove
+vinxi
+```
+
+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`.
+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, `solidStart()` 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
+
+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 HTTP entrypoint exposes helpers such as `readBody`, `getQuery`, `getRequestHeader`, `setResponseHeader`, `useSession`, and related cookie/session utilities.
+
+### Update TypeScript environment types
+
+Environment types ship in `@solidjs/start/env`.
+Make sure your TypeScript config includes it.
+
+```json
+{
+ "compilerOptions": {
+ "types": ["@solidjs/start/env"]
+ }
+}
+```
+
+### Revisit middleware syntax
+
+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
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ async (_event, next) => {
+ return await next();
+ },
+]);
+```
+
+## Still in the v1 docs
+
+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
diff --git a/src/routes/solid-start/v2/reference/client/client-only.mdx b/src/routes/solid-start/v2/reference/client/client-only.mdx
new file mode 100644
index 0000000000..1d630749f9
--- /dev/null
+++ b/src/routes/solid-start/v2/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>(
+ fn: () => Promise<{ default: T }>,
+ options?: { lazy?: boolean }
+): (props: ComponentProps & { 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 & { 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