+
+ );
+}
+```
+
+## Use asynchronous data
+
+Metadata can read the same query result as the route. Wrap the rendered data in `Suspense` or `Show` when it may not be available immediately.
+
+```tsx title="src/routes/users/[id].tsx"
+import { Title } from "@solidjs/meta";
+import { createAsync, query, type RouteSectionProps } from "@solidjs/router";
+import { Show } from "solid-js";
+
+const getUser = query(async (id: string) => {
+ "use server";
+ return { id, name: `User ${id}` };
+}, "user");
+
+export default function User(props: RouteSectionProps) {
+ const user = createAsync(() => getUser(props.params.id));
+
+ return (
+
+ {(value) => (
+ <>
+ {value().name}
+
{value().name}
+
+ )}
+
+ );
+}
+```
+
+See the [`@solidjs/meta` documentation](/solid-meta) for all supported head elements and provider behavior.
diff --git a/src/routes/solid-start/v2/(0)building-your-application/(6)route-prerendering.mdx b/src/routes/solid-start/v2/(0)building-your-application/(6)route-prerendering.mdx
new file mode 100644
index 000000000..1d4c3e00f
--- /dev/null
+++ b/src/routes/solid-start/v2/(0)building-your-application/(6)route-prerendering.mdx
@@ -0,0 +1,57 @@
+---
+title: Route pre-rendering
+use_cases: >-
+ static site generation, ssg, blog sites, documentation, marketing pages,
+ performance optimization, seo improvement
+tags:
+ - prerender
+ - ssg
+ - static
+ - performance
+ - build
+ - seo
+version: "2.0"
+description: >-
+ Pre-render SolidStart routes to static HTML with Nitro v3.
+---
+
+Route pre-rendering produces static HTML during `vite build`. Nitro writes the generated files to `.output/public`, where a CDN or server can serve them without rendering the route on each request.
+
+Configure prerendering through Nitro's top-level Vite configuration.
+
+## Pre-render selected routes
+
+```tsx title="vite.config.ts"
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+ plugins: [solidStart(), nitro()],
+ nitro: {
+ prerender: {
+ routes: ["/", "/about"],
+ },
+ },
+});
+```
+
+## Crawl links
+
+Set `crawlLinks` to start at `/` and follow links found in rendered HTML. Add `routes` when the crawler needs additional entry points.
+
+```tsx title="vite.config.ts"
+export default defineConfig({
+ plugins: [solidStart(), nitro()],
+ nitro: {
+ prerender: {
+ crawlLinks: true,
+ failOnError: true,
+ },
+ },
+});
+```
+
+Dynamic routes that are not linked from a crawled page must be listed explicitly or discovered from another entry route.
+
+For retry, concurrency, ignore, and output-path options, see [Nitro's prerender configuration](https://nitro.build/config#prerender).
diff --git a/src/routes/solid-start/v2/(0)building-your-application/(7)static-assets.mdx b/src/routes/solid-start/v2/(0)building-your-application/(7)static-assets.mdx
new file mode 100644
index 000000000..0f4fa1290
--- /dev/null
+++ b/src/routes/solid-start/v2/(0)building-your-application/(7)static-assets.mdx
@@ -0,0 +1,93 @@
+---
+title: Static assets
+use_cases: >-
+ images, fonts, documents, favicon, robots.txt, service workers, media files,
+ public resources
+tags:
+ - assets
+ - images
+ - public
+ - static
+ - media
+ - files
+version: "2.0"
+description: >-
+ Manage static assets in SolidStart using the public directory or imports.
+ Serve images, fonts, documents, and media files.
+---
+
+Within SolidStart there are two ways to import static assets into your project: using the public directory and using imports.
+
+## Public directory
+
+Rich web applications use assets to create visuals.
+In SolidStart, the `/public` directory can be used to store static assets.
+These assets are served at the exact path they are in, relative to the public directory:
+
+```
+|-- public
+| favicon.ico -> /favicon.ico
+| |-- images
+| | |-- logo.png -> /images/logo.png
+| | |-- background.png -> /images/background.png
+| |-- models
+| | |-- player.gltf -> /models/player.gltf
+| |-- documents
+| | |-- report.pdf -> /documents/report.pdf
+```
+
+If you would like to reference an asset in the public directory, you can use the absolute path to the asset:
+
+```tsx { 5 }
+export default function About() {
+ return (
+ <>
+
About
+
+
+ );
+}
+```
+
+This is ideal when you want to have human-readable, stable references to static assets.
+This can be useful for assets such as:
+
+- documents
+- service workers
+- images, audio, and video
+- manifest files
+- metadata files (e.g., `robots.txt`, sitemaps)
+- favicon
+
+## Importing assets
+
+Vite provides a way to import assets directly into your Solid components:
+
+```tsx
+import logo from "./solid.png";
+
+export default function About() {
+ return (
+ <>
+
About
+
+ // Renders
+
+
+ );
+}
+```
+
+When you use imports, Vite will create a hashed filename.
+For example, `solid.png` will become `solid.2d8efhg.png`.
+
+## Public directory versus imports
+
+The public directory and imports are both valid ways to include static assets in your project.
+The driver to use one over the other is based on your use case.
+
+For dynamic updates to your assets, using the public directory is the best choice.
+It allows you to maintain full control over the asset URL paths, ensuring that the links remain consistent even when the assets are updated.
+
+When using imports, the filename is hashed and therefore will not be predictable over time.
+This can be beneficial for cache busting but detrimental if you want to send someone a link to the asset.
diff --git a/src/routes/solid-start/v2/(0)index.mdx b/src/routes/solid-start/v2/(0)index.mdx
index 072ddb76d..8b4457880 100644
--- a/src/routes/solid-start/v2/(0)index.mdx
+++ b/src/routes/solid-start/v2/(0)index.mdx
@@ -16,7 +16,7 @@ description: >-
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.
+SolidStart v2 builds a full-stack app on top of [Solid v1](/), [Solid Router](/solid-router), and [Vite 8+](https://vite.dev). It uses Vite's Environment API for client and server builds and works with deployment Vite plugins such as [Nitro v3](https://nitro.build) and the [Cloudflare Vite plugin](https://www.npmjs.com/package/@cloudflare/vite-plugin).
The framework is split into a handful of entry points:
@@ -26,6 +26,8 @@ The framework is split into a handful of entry points:
- `@solidjs/start/http` for request, response, cookie, and session helpers
- `@solidjs/start/middleware` for middleware composition
+SolidStart v2 requires Node.js 24 or newer and Vite 8 or 9.
+
## What v2 keeps
The core model carries over from v1:
@@ -37,6 +39,6 @@ The core model carries over from v1:
## What changed from v1
-Configuration moved from `app.config.ts` to `vite.config.ts` through `solidStart()`.
+Configuration moved from `app.config.ts` to `vite.config.ts`. The `solidStart()` plugin configures the application, while a deployment Vite plugin configures the server runtime and deployment target.
If you are upgrading an existing app, start with the [migration guide](/solid-start/v2/migrating-from-v1).
diff --git a/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx b/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx
new file mode 100644
index 000000000..34b475990
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx
@@ -0,0 +1,155 @@
+---
+title: Middleware
+use_cases: >-
+ request interception, header management, global data sharing, request
+ preprocessing, logging, redirects
+tags:
+ - middleware
+ - headers
+ - interceptors
+ - logging
+ - preprocessing
+ - locals
+version: "2.0"
+description: >-
+ Compose H3 v2 middleware for authentication, logging, headers, and
+ request-scoped data in SolidStart.
+---
+
+Middleware runs around SolidStart's request handler. It is useful for logging, redirects, request preprocessing, response headers, and initializing request-scoped data.
+
+Do not rely on middleware alone for authorization. Client-side navigation can reuse data and server functions independently of a page request, so authorization must also be enforced close to each protected query, action, or API route.
+
+## Configure middleware
+
+Create a middleware module and pass its path to `solidStart()`.
+
+```ts title="src/middleware/index.ts"
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ async (event, next) => {
+ console.log("Request received:", event.req.url);
+ const startedAt = Date.now();
+
+ const response = await next();
+
+ console.log(`Request took ${Date.now() - startedAt}ms`);
+ return response;
+ },
+]);
+```
+
+```tsx title="vite.config.ts" {7}
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+ plugins: [solidStart({ middleware: "./src/middleware/index.ts" }), nitro()],
+});
+```
+
+Each entry is an [H3 middleware](https://h3.dev/guide/basics/middleware). Code before `await next()` runs before the downstream handler. Code after it runs as the response unwinds.
+
+## Request-scoped locals
+
+SolidStart decorates configured middleware with its request context. Use `getRequestEvent()` to read or update `event.locals` for later server code.
+
+```ts title="src/middleware/index.ts"
+import { createMiddleware } from "@solidjs/start/middleware";
+import { getRequestEvent } from "solid-js/web";
+
+export default createMiddleware([
+ async (_event, next) => {
+ const requestEvent = getRequestEvent();
+ if (requestEvent) {
+ requestEvent.locals.requestId = crypto.randomUUID();
+ }
+ return next();
+ },
+]);
+```
+
+Augment `App.RequestEventLocals` to type custom fields. See [Request events](/solid-start/v2/advanced/request-events#locals).
+
+## Headers and cookies
+
+H3 v2 uses Web standard `Request`, `Response`, and `Headers` objects. You can access them through the H3 event or use SolidStart's context-aware HTTP helpers.
+
+```ts title="src/middleware/index.ts"
+import { getCookie, setCookie } from "@solidjs/start/http";
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ async (event, next) => {
+ const theme = getCookie("theme") ?? "system";
+ setCookie("theme", theme, {
+ httpOnly: true,
+ secure: true,
+ sameSite: "lax",
+ });
+
+ const response = await next();
+ event.res.headers.set("x-theme", theme);
+ return response;
+ },
+]);
+```
+
+`@solidjs/start/http` and `@solidjs/start/middleware` are server-only entrypoints. Importing them from client-reachable code causes a clear development or build error.
+
+## Short-circuit the request
+
+Return a `Response` before calling `next()` to stop the chain.
+
+```ts
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ (event, next) => {
+ if (!event.req.headers.get("authorization")) {
+ return new Response("Unauthorized", { status: 401 });
+ }
+ return next();
+ },
+]);
+```
+
+Redirect responses from Solid Router work the same way:
+
+```ts
+import { redirect } from "@solidjs/router";
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ (event, next) => {
+ if (new URL(event.req.url).pathname === "/login") {
+ return redirect("/auth/login", 301);
+ }
+ return next();
+ },
+]);
+```
+
+## Middleware order
+
+Middleware uses an onion model. Before-`next()` logic runs in declaration order; after-`next()` logic runs in reverse order.
+
+The v1 object form with `onRequest` and `onBeforeResponse` remains available for migration but is deprecated. In `2.0.0-rc.1`, deprecated `onBeforeResponse` arrays run in their declared order. Remove any manual reversal added as a workaround for earlier prereleases.
+
+## Custom H3 handlers
+
+The experimental `decorateHandler` and `decorateMiddleware` exports from `@solidjs/start/server` provide Solid's request context to custom H3 code that runs outside the configured middleware chain.
+
+```ts
+import { decorateHandler } from "@solidjs/start/server";
+import { defineHandler } from "nitro";
+
+export default defineHandler(
+ decorateHandler(() => {
+ // getRequestEvent() is available here
+ return { ok: true };
+ })
+);
+```
diff --git a/src/routes/solid-start/v2/(1)advanced/(1)session.mdx b/src/routes/solid-start/v2/(1)advanced/(1)session.mdx
new file mode 100644
index 000000000..a0ce18f57
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(1)session.mdx
@@ -0,0 +1,87 @@
+---
+title: Sessions
+use_cases: >-
+ user sessions, authentication state, preferences storage, stateful
+ interactions, login persistence
+tags:
+ - sessions
+ - cookies
+ - authentication
+ - state
+ - storage
+ - persistence
+version: "2.0"
+description: >-
+ Manage encrypted cookie sessions with the SolidStart HTTP helpers.
+---
+
+Sessions let the server associate state with multiple requests from the same browser. SolidStart exposes H3 v2's encrypted cookie-session helpers through `@solidjs/start/http`.
+
+Session helpers are server-only. Use them from server functions, API routes, middleware, or other server-only modules.
+
+## Create a session helper
+
+`useSession` reads the current session and returns methods for updating or clearing it.
+
+```ts title="src/lib/session.ts"
+import { useSession } from "@solidjs/start/http";
+
+type SessionData = {
+ userId?: string;
+ theme?: "light" | "dark";
+};
+
+export function useAppSession() {
+ "use server";
+
+ return useSession({
+ name: "app-session",
+ password: process.env.SESSION_SECRET as string,
+ cookie: {
+ httpOnly: true,
+ secure: process.env.NODE_ENV === "production",
+ sameSite: "lax",
+ },
+ });
+}
+```
+
+Use a secret of at least 32 characters and store it in a private environment variable. Generate one with:
+
+```sh frame="none"
+openssl rand -base64 32
+```
+
+## Read session data
+
+```ts
+export async function getCurrentUserId() {
+ "use server";
+ const session = await useAppSession();
+ return session.data.userId ?? null;
+}
+```
+
+## Update session data
+
+```ts
+export async function setTheme(theme: "light" | "dark") {
+ "use server";
+ const session = await useAppSession();
+ await session.update({ theme });
+}
+```
+
+## Clear a session
+
+```ts
+export async function logout() {
+ "use server";
+ const session = await useAppSession();
+ await session.clear();
+}
+```
+
+In addition to `useSession`, `@solidjs/start/http` exports `getSession`, `updateSession`, `clearSession`, `sealSession`, and `unsealSession` for lower-level workflows.
+
+Cookie sessions should contain small, non-sensitive identifiers and preferences. For revocation, device management, or larger data, store the session record in a database and keep only its opaque ID in the cookie.
diff --git a/src/routes/solid-start/v2/(1)advanced/(2)request-events.mdx b/src/routes/solid-start/v2/(1)advanced/(2)request-events.mdx
new file mode 100644
index 000000000..39e9cc755
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(2)request-events.mdx
@@ -0,0 +1,56 @@
+---
+title: Request events
+use_cases: >-
+ server context access, local data storage, request handling, server functions,
+ event access
+tags:
+ - events
+ - server
+ - context
+ - locals
+ - requests
+ - functions
+version: "2.0"
+description: >-
+ Access request events, typed locals, and the native H3 v2 event in SolidStart.
+---
+
+Call [`getRequestEvent`](/reference/server-utilities/get-request-event) from `solid-js/web` to access the current request in server-rendering, API, middleware, query, and action code.
+
+```tsx
+import { getRequestEvent } from "solid-js/web";
+
+const event = getRequestEvent();
+const request = event?.request;
+```
+
+`getRequestEvent()` returns `undefined` outside a request context.
+
+## Locals
+
+`event.locals` is request-scoped storage shared by SolidStart middleware and server code. Add your fields to the global `App.RequestEventLocals` interface:
+
+```tsx title="src/env.d.ts"
+declare namespace App {
+ interface RequestEventLocals {
+ user?: { id: string };
+ requestId: string;
+ }
+}
+```
+
+The `@solidjs/start/env` type entry provides the base namespace and should be included in `tsconfig.json`.
+
+```json title="tsconfig.json"
+{
+ "compilerOptions": {
+ "types": ["@solidjs/start/env"]
+ }
+}
+```
+
+## Native event
+
+`event.nativeEvent` is the underlying H3 v2 event. It exposes Web standard request and response objects as `event.nativeEvent.req` and `event.nativeEvent.res`.
+
+Most application code does not need the native event. Prefer `event.request`, `event.response`, or a helper from `@solidjs/start/http`. The HTTP entrypoint is server-only, so import it only from server code or inside a function marked with `"use server"`.
diff --git a/src/routes/solid-start/v2/(1)advanced/(3)return-responses.mdx b/src/routes/solid-start/v2/(1)advanced/(3)return-responses.mdx
new file mode 100644
index 000000000..adaf4b94c
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(3)return-responses.mdx
@@ -0,0 +1,62 @@
+---
+title: Returning responses
+use_cases: >-
+ server function responses, error handling, response types, api responses,
+ typescript typing
+tags:
+ - responses
+ - server
+ - functions
+ - typescript
+ - errors
+ - api
+version: "2.0"
+description: >-
+ Return typed Response objects from server functions. Handle redirects,
+ reloads, and JSON responses with proper TypeScript support.
+---
+
+In SolidStart, it is possible to return a Response object from a server function.
+[`solid-router`](/solid-router) knows how to handle certain responses with its [`query`](/solid-router/reference/data-apis/query) and [`action`](/solid-router/reference/data-apis/action) APIs.
+For TypeScript, when returning a response using `solid-router`'s `redirect`, `reload`, or `json` helpers, they will not impact the return value of the server function.
+
+While we suggest depending on the type of the function to handle errors differently, you can always return or throw a response.
+
+## Examples
+
+In the following example, the `hello` function will return a value of type `Promise<{ hello: string }>`:
+
+```tsx
+import { json } from "@solidjs/router";
+import { GET } from "@solidjs/start";
+
+const hello = GET(async (name: string) => {
+ "use server";
+ return json(
+ { hello: new Promise((r) => setTimeout(() => r(name), 1000)) },
+ { headers: { "cache-control": "max-age=60" } }
+ );
+});
+```
+
+However, in this example, since `redirect` and `reload` return `never` as their type, `getUser` can only return a value of type `Promise`:
+
+```tsx { 4, 10, 14}
+export async function getUser() {
+ "use server";
+
+ const session = await getSession();
+ const userId = session.data.userId;
+ if (userId === undefined) return redirect("/login");
+
+ try {
+ const user: User = await db.user.findUnique({ where: { id: userId } });
+ // throwing can be awkward.
+ if (!user) return redirect("/login");
+ return user;
+ } catch {
+ // do stuff
+ throw redirect("/login");
+ }
+}
+```
diff --git a/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx b/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
index 1bca99001..07d59a1df 100644
--- a/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
+++ b/src/routes/solid-start/v2/(1)advanced/(4)serialization.mdx
@@ -1,7 +1,8 @@
---
title: Serialization
use_cases: >-
- server function payloads, data transfer, csp, security, performance
+ server function payloads, data transfer, custom types, seroval plugins, csp,
+ security, performance
tags:
- serialization
- server-functions
@@ -40,6 +41,57 @@ export default defineConfig({
If your app enforces a Content Security Policy, keep `json`.
+## Custom types
+
+Use a custom Seroval plugin when a server function needs to accept or return a value that Seroval does not support, such as a database identifier, decimal type, or another custom class.
+
+Set `serialization.plugins` to a module whose default export is an array of plugins:
+
+```tsx title="vite.config.ts"
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+ plugins: [
+ solidStart({
+ serialization: {
+ plugins: "src/seroval-plugins.ts",
+ },
+ }),
+ ],
+});
+```
+
+Create plugins with the API exported by `@solidjs/start/serialization`. The entrypoint exports `createPlugin`, `OpaqueReference`, and the related plugin types. Importing from it keeps the plugin on the same Seroval version that SolidStart uses.
+
+```ts title="src/seroval-plugins.ts"
+import { createPlugin } from "@solidjs/start/serialization";
+import { Money } from "./lib/money";
+
+const moneyPlugin = createPlugin({
+ tag: "app/Money",
+ test: (value) => value instanceof Money,
+ parse: {
+ sync: (value, ctx) => ({ cents: ctx.parse(value.cents) }),
+ async: async (value, ctx) => ({
+ cents: await ctx.parse(value.cents),
+ }),
+ stream: (value, ctx) => ({ cents: ctx.parse(value.cents) }),
+ },
+ serialize: (node, ctx) =>
+ `new globalThis.Money(${ctx.serialize(node.cents)})`,
+ deserialize: (node, ctx) => new Money(ctx.deserialize(node.cents) as number),
+});
+
+export default [moneyPlugin];
+```
+
+SolidStart bundles the plugin module into both the client and server builds, so it must not import server-only code. Built-in SolidStart plugins run before custom plugins.
+
+Custom plugins apply to server function and action payloads. They do not affect the hydration payload produced by `solid-js/web`.
+
+With the default `json` mode, `deserialize` rebuilds the value. If you use `js` mode, the code returned by `serialize` can only refer to globals available in the client. In the example above, `Money` must be assigned to `globalThis.Money` before deserialization.
+
## Server function payloads
SolidStart applies extra handling for certain payload types so file uploads and binary data can flow without being serialized by Seroval. This applies to both server function arguments and return values. SolidStart bypasses Seroval for:
diff --git a/src/routes/solid-start/v2/(1)advanced/(5)auth.mdx b/src/routes/solid-start/v2/(1)advanced/(5)auth.mdx
new file mode 100644
index 000000000..b711a3ced
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(5)auth.mdx
@@ -0,0 +1,61 @@
+---
+title: Auth
+use_cases: >-
+ user authentication, protected routes, authorization checks, secure data
+ access, login systems
+tags:
+ - authentication
+ - authorization
+ - security
+ - protected
+ - login
+ - users
+version: "2.0"
+description: >-
+ Implement authentication and protected routes in SolidStart. Secure sensitive
+ resources and handle user authorization properly.
+---
+
+Server functions can be used to protect sensitive resources like user data.
+
+```tsx
+"use server";
+
+async function getPrivatePosts() {
+ const user = await getUser();
+ if (!user) {
+ return null; // or throw an error
+ }
+
+ return db.getPosts({ userId: user.id, private: true });
+}
+```
+
+The `getUser` function can be [implemented using sessions](/solid-start/v2/advanced/session).
+
+## Protected Routes
+
+Routes can be protected by checking the user or session object during data fetching.
+This example uses [Solid Router](/solid-router).
+
+```tsx
+const getPrivatePosts = query(async function () {
+ "use server";
+ const user = await getUser();
+ if (!user) {
+ throw redirect("/login");
+ }
+
+ return db.getPosts({ userId: user.id, private: true });
+});
+
+export default function Page() {
+ const posts = createAsync(() => getPrivatePosts(), { deferStream: true });
+}
+```
+
+Once the user hits this route, the router will attempt to fetch `getPrivatePosts` data.
+If the user is not signed in, `getPrivatePosts` will throw and the router will redirect to the login page.
+
+To prevent errors when opening the page directly, set `deferStream: true`.
+This would ensure `getPrivatePosts` resolves before the page loads since server-side redirects cannot occur after streaming has started.
diff --git a/src/routes/solid-start/v2/(1)advanced/(6)websocket.mdx b/src/routes/solid-start/v2/(1)advanced/(6)websocket.mdx
new file mode 100644
index 000000000..bcfebcf15
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(6)websocket.mdx
@@ -0,0 +1,72 @@
+---
+title: WebSocket endpoint
+use_cases: >-
+ real-time updates, chat applications, live notifications, multiplayer games,
+ collaborative editing, streaming data
+tags:
+ - websocket
+ - real-time
+ - streaming
+ - server
+ - events
+version: "2.0"
+description: >-
+ Add a Nitro v3 WebSocket endpoint to a SolidStart application.
+---
+
+SolidStart v2 uses Nitro v3's cross-platform WebSocket support. Enable the feature in Nitro's Vite configuration and define the endpoint as a Nitro server route.
+
+## Enable WebSockets
+
+```tsx title="vite.config.ts"
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+ plugins: [solidStart(), nitro()],
+ nitro: {
+ serverDir: "./server",
+ features: {
+ websocket: true,
+ },
+ },
+});
+```
+
+## Create an endpoint
+
+Files in `server/routes` use Nitro's file-based server routing. This example handles connections at `/ws`.
+
+```ts title="server/routes/ws.ts"
+import { defineWebSocketHandler } from "nitro";
+
+export default defineWebSocketHandler({
+ open(peer) {
+ console.log("open", peer.id);
+ peer.send("Connected");
+ },
+ message(peer, message) {
+ console.log("message", peer.id, message.text());
+ peer.send(message.text());
+ },
+ close(peer, details) {
+ console.log("close", peer.id, details.code, details.reason);
+ },
+ error(peer, error) {
+ console.error("websocket error", peer.id, error);
+ },
+});
+```
+
+Connect with the browser WebSocket API:
+
+```ts
+const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+const socket = new WebSocket(`${protocol}//${location.host}/ws`);
+
+socket.addEventListener("open", () => socket.send("Hello"));
+socket.addEventListener("message", (event) => console.log(event.data));
+```
+
+Nitro also supports upgrade hooks, peer context, topics, namespaces, and pub/sub. See the [Nitro WebSocket guide](https://nitro.build/docs/websocket).
diff --git a/src/routes/solid-start/v2/(1)getting-started.mdx b/src/routes/solid-start/v2/(1)getting-started.mdx
index a912b49a0..14ca5604d 100644
--- a/src/routes/solid-start/v2/(1)getting-started.mdx
+++ b/src/routes/solid-start/v2/(1)getting-started.mdx
@@ -16,7 +16,7 @@ description: >-
---
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.
+SolidStart v2 requires Node.js 24 or newer.
## Create a project
@@ -42,14 +42,15 @@ dev
## Configuration
-Configuration lives in `vite.config.ts`, where the `solidStart()` plugin from `@solidjs/start/config` does the work.
+Configuration lives in `vite.config.ts`. SolidStart configures the application and Nitro v3 supplies the server and deployment integration.
```tsx title="vite.config.ts"
import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
import { solidStart } from "@solidjs/start/config";
export default defineConfig({
- plugins: [solidStart()],
+ plugins: [solidStart(), nitro()],
});
```
@@ -57,13 +58,26 @@ If your app already has middleware, `solidStart()` also accepts a `middleware` o
```tsx title="vite.config.ts"
import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
import { solidStart } from "@solidjs/start/config";
export default defineConfig({
- plugins: [solidStart({ middleware: "./src/middleware/index.ts" })],
+ plugins: [solidStart({ middleware: "./src/middleware/index.ts" }), nitro()],
});
```
+Use the top-level `nitro` property for Nitro options such as deployment presets, prerendering, tasks, and WebSockets.
+
+## Development toolbar
+
+During development, SolidStart adds a toolbar for inspecting application errors and server function calls. The toolbar is not included in production builds.
+
+To hide it during development, set `devOverlay` to `false`:
+
+```tsx title="vite.config.ts"
+solidStart({ devOverlay: false });
+```
+
## Start adding routes
The filesystem router reads files from your routes directory and turns them into UI routes or API routes.
diff --git a/src/routes/solid-start/v2/(2)guides/(0)security.mdx b/src/routes/solid-start/v2/(2)guides/(0)security.mdx
new file mode 100644
index 000000000..88feed732
--- /dev/null
+++ b/src/routes/solid-start/v2/(2)guides/(0)security.mdx
@@ -0,0 +1,220 @@
+---
+title: Security
+use_cases: >-
+ production apps, user input handling, authentication, public apis, preventing
+ attacks, secure deployments, compliance
+tags:
+ - security
+ - xss
+ - csrf
+ - cors
+ - csp
+ - middleware
+ - protection
+version: "2.0"
+description: >-
+ Secure your SolidStart apps against XSS, CSRF attacks. Configure CSP headers,
+ CORS policies, and implement security best practices.
+---
+
+## XSS (Cross Site Scripting)
+
+Solid automatically escapes values passed to JSX expressions to reduce the risk of XSS attacks.
+However, this protection does not apply when using [`innerHTML`](/reference/jsx-attributes/innerhtml).
+
+To protect your application from XSS attacks:
+
+- Set a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
+- Validate and sanitize user inputs, especially form inputs on the server and client.
+- Avoid using `innerHTML` when possible.
+ If necessary, make sure to sanitize user-supplied data with libraries such as [DOMPurify](https://github.com/cure53/DOMPurify).
+- Sanitize attributes containing user-supplied data within `
+
+ );
+}
+```
+
+This is ideal when you want to have human-readable, stable references to static assets.
+This can be useful for assets such as:
+
+- documents
+- service workers
+- images, audio, and video
+- manifest files
+- metadata files (e.g., `robots.txt`, sitemaps)
+- favicon
+
+## Importing assets
+
+Vite provides a way to import assets directly into your Solid components:
+
+```tsx
+import logo from "./solid.png";
+
+export default function About() {
+ return (
+ <>
+ 
+
+ );
+}
+```
+
+When you use imports, Vite will create a hashed filename.
+For example, `solid.png` will become `solid.2d8efhg.png`.
+
+## Public directory versus imports
+
+The public directory and imports are both valid ways to include static assets in your project.
+The driver to use one over the other is based on your use case.
+
+For dynamic updates to your assets, using the public directory is the best choice.
+It allows you to maintain full control over the asset URL paths, ensuring that the links remain consistent even when the assets are updated.
+
+When using imports, the filename is hashed and therefore will not be predictable over time.
+This can be beneficial for cache busting but detrimental if you want to send someone a link to the asset.
diff --git a/src/routes/solid-start/v2/(0)index.mdx b/src/routes/solid-start/v2/(0)index.mdx
index 072ddb76d..8b4457880 100644
--- a/src/routes/solid-start/v2/(0)index.mdx
+++ b/src/routes/solid-start/v2/(0)index.mdx
@@ -16,7 +16,7 @@ description: >-
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.
+SolidStart v2 builds a full-stack app on top of [Solid v1](/), [Solid Router](/solid-router), and [Vite 8+](https://vite.dev). It uses Vite's Environment API for client and server builds and works with deployment Vite plugins such as [Nitro v3](https://nitro.build) and the [Cloudflare Vite plugin](https://www.npmjs.com/package/@cloudflare/vite-plugin).
The framework is split into a handful of entry points:
@@ -26,6 +26,8 @@ The framework is split into a handful of entry points:
- `@solidjs/start/http` for request, response, cookie, and session helpers
- `@solidjs/start/middleware` for middleware composition
+SolidStart v2 requires Node.js 24 or newer and Vite 8 or 9.
+
## What v2 keeps
The core model carries over from v1:
@@ -37,6 +39,6 @@ The core model carries over from v1:
## What changed from v1
-Configuration moved from `app.config.ts` to `vite.config.ts` through `solidStart()`.
+Configuration moved from `app.config.ts` to `vite.config.ts`. The `solidStart()` plugin configures the application, while a deployment Vite plugin configures the server runtime and deployment target.
If you are upgrading an existing app, start with the [migration guide](/solid-start/v2/migrating-from-v1).
diff --git a/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx b/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx
new file mode 100644
index 000000000..34b475990
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(0)middleware.mdx
@@ -0,0 +1,155 @@
+---
+title: Middleware
+use_cases: >-
+ request interception, header management, global data sharing, request
+ preprocessing, logging, redirects
+tags:
+ - middleware
+ - headers
+ - interceptors
+ - logging
+ - preprocessing
+ - locals
+version: "2.0"
+description: >-
+ Compose H3 v2 middleware for authentication, logging, headers, and
+ request-scoped data in SolidStart.
+---
+
+Middleware runs around SolidStart's request handler. It is useful for logging, redirects, request preprocessing, response headers, and initializing request-scoped data.
+
+Do not rely on middleware alone for authorization. Client-side navigation can reuse data and server functions independently of a page request, so authorization must also be enforced close to each protected query, action, or API route.
+
+## Configure middleware
+
+Create a middleware module and pass its path to `solidStart()`.
+
+```ts title="src/middleware/index.ts"
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ async (event, next) => {
+ console.log("Request received:", event.req.url);
+ const startedAt = Date.now();
+
+ const response = await next();
+
+ console.log(`Request took ${Date.now() - startedAt}ms`);
+ return response;
+ },
+]);
+```
+
+```tsx title="vite.config.ts" {7}
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { solidStart } from "@solidjs/start/config";
+
+export default defineConfig({
+ plugins: [solidStart({ middleware: "./src/middleware/index.ts" }), nitro()],
+});
+```
+
+Each entry is an [H3 middleware](https://h3.dev/guide/basics/middleware). Code before `await next()` runs before the downstream handler. Code after it runs as the response unwinds.
+
+## Request-scoped locals
+
+SolidStart decorates configured middleware with its request context. Use `getRequestEvent()` to read or update `event.locals` for later server code.
+
+```ts title="src/middleware/index.ts"
+import { createMiddleware } from "@solidjs/start/middleware";
+import { getRequestEvent } from "solid-js/web";
+
+export default createMiddleware([
+ async (_event, next) => {
+ const requestEvent = getRequestEvent();
+ if (requestEvent) {
+ requestEvent.locals.requestId = crypto.randomUUID();
+ }
+ return next();
+ },
+]);
+```
+
+Augment `App.RequestEventLocals` to type custom fields. See [Request events](/solid-start/v2/advanced/request-events#locals).
+
+## Headers and cookies
+
+H3 v2 uses Web standard `Request`, `Response`, and `Headers` objects. You can access them through the H3 event or use SolidStart's context-aware HTTP helpers.
+
+```ts title="src/middleware/index.ts"
+import { getCookie, setCookie } from "@solidjs/start/http";
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ async (event, next) => {
+ const theme = getCookie("theme") ?? "system";
+ setCookie("theme", theme, {
+ httpOnly: true,
+ secure: true,
+ sameSite: "lax",
+ });
+
+ const response = await next();
+ event.res.headers.set("x-theme", theme);
+ return response;
+ },
+]);
+```
+
+`@solidjs/start/http` and `@solidjs/start/middleware` are server-only entrypoints. Importing them from client-reachable code causes a clear development or build error.
+
+## Short-circuit the request
+
+Return a `Response` before calling `next()` to stop the chain.
+
+```ts
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ (event, next) => {
+ if (!event.req.headers.get("authorization")) {
+ return new Response("Unauthorized", { status: 401 });
+ }
+ return next();
+ },
+]);
+```
+
+Redirect responses from Solid Router work the same way:
+
+```ts
+import { redirect } from "@solidjs/router";
+import { createMiddleware } from "@solidjs/start/middleware";
+
+export default createMiddleware([
+ (event, next) => {
+ if (new URL(event.req.url).pathname === "/login") {
+ return redirect("/auth/login", 301);
+ }
+ return next();
+ },
+]);
+```
+
+## Middleware order
+
+Middleware uses an onion model. Before-`next()` logic runs in declaration order; after-`next()` logic runs in reverse order.
+
+The v1 object form with `onRequest` and `onBeforeResponse` remains available for migration but is deprecated. In `2.0.0-rc.1`, deprecated `onBeforeResponse` arrays run in their declared order. Remove any manual reversal added as a workaround for earlier prereleases.
+
+## Custom H3 handlers
+
+The experimental `decorateHandler` and `decorateMiddleware` exports from `@solidjs/start/server` provide Solid's request context to custom H3 code that runs outside the configured middleware chain.
+
+```ts
+import { decorateHandler } from "@solidjs/start/server";
+import { defineHandler } from "nitro";
+
+export default defineHandler(
+ decorateHandler(() => {
+ // getRequestEvent() is available here
+ return { ok: true };
+ })
+);
+```
diff --git a/src/routes/solid-start/v2/(1)advanced/(1)session.mdx b/src/routes/solid-start/v2/(1)advanced/(1)session.mdx
new file mode 100644
index 000000000..a0ce18f57
--- /dev/null
+++ b/src/routes/solid-start/v2/(1)advanced/(1)session.mdx
@@ -0,0 +1,87 @@
+---
+title: Sessions
+use_cases: >-
+ user sessions, authentication state, preferences storage, stateful
+ interactions, login persistence
+tags:
+ - sessions
+ - cookies
+ - authentication
+ - state
+ - storage
+ - persistence
+version: "2.0"
+description: >-
+ Manage encrypted cookie sessions with the SolidStart HTTP helpers.
+---
+
+Sessions let the server associate state with multiple requests from the same browser. SolidStart exposes H3 v2's encrypted cookie-session helpers through `@solidjs/start/http`.
+
+Session helpers are server-only. Use them from server functions, API routes, middleware, or other server-only modules.
+
+## Create a session helper
+
+`useSession` reads the current session and returns methods for updating or clearing it.
+
+```ts title="src/lib/session.ts"
+import { useSession } from "@solidjs/start/http";
+
+type SessionData = {
+ userId?: string;
+ theme?: "light" | "dark";
+};
+
+export function useAppSession() {
+ "use server";
+
+ return useSession