+
+ );
+}
+```
+
+## 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/(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..0e6a47238 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
@@ -26,7 +26,7 @@ Create a new app with the Solid scaffolding tool:
solid
```
-Follow the interactive prompts and choose the SolidStart template or an official example that matches your use case.
+Follow the interactive prompts, choose **SolidStart**, and then choose **v2**. You can skip the version prompt with the `--solidstart --v2` flags.
After the project is created, install dependencies:
@@ -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,16 @@ 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.
+
## 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