;
}
```
### Nested Layout Pattern
```tsx
// routes/blog.tsx -- layout wrapper for /blog/*
import type { RouteSectionProps } from "@solidjs/router";
export default function BlogLayout(props: RouteSectionProps) {
return (
{props.children}
);
}
```
---
## Decision Tree: Data Loading
```
Need server-side data?
├─ YES: Is it a read operation (query)?
│ ├─ YES: Use query() + createAsync()
│ │ └─ Need fine-grained store updates? → Use createAsyncStore()
│ └─ NO: It's a mutation → Use action() (see Actions section)
└─ NO: Client-only data
└─ Use createSignal/createResource directly
```
---
## Data Loading Pattern
### Step 1: Define a Query with Server Function
```tsx
import { query } from "@solidjs/router";
const getUser = query(async (id: string) => {
"use server";
const user = await db.getUser(id);
if (!user) throw new Error("User not found");
return user;
}, "user");
```
### Step 2: Consume with createAsync
```tsx
import { createAsync } from "@solidjs/router";
import { Suspense } from "solid-js";
export default function UserPage() {
const params = useParams();
const user = createAsync(() => getUser(params.id));
return (
Loading...}>
{user()?.name}
);
}
```
### Step 3: Preload for Instant Navigation
```tsx
import type { RouteDefinition } from "@solidjs/router";
export const route = {
preload({ params }) {
getUser(params.id); // fire-and-forget, warms cache
},
} satisfies RouteDefinition;
```
---
## Decision Tree: Mutations
```
Need to mutate server data?
├─ From a
);
}
```
### Programmatic Action with useAction
```tsx
import { action, useAction } from "@solidjs/router";
const toggleTodo = action(async (id: string) => {
"use server";
await db.toggleTodo(id);
}, "toggleTodo");
function TodoItem(props: { id: string; done: boolean }) {
const doToggle = useAction(toggleTodo);
return (
);
}
```
### Submission Tracking
```tsx
import { useSubmission } from "@solidjs/router";
function TodoForm() {
const submission = useSubmission(addTodo);
return (
);
}
```
### Response Helpers After Actions
```tsx
import { redirect, reload, revalidate } from "@solidjs/router";
const updateUser = action(async (id: string, formData: FormData) => {
"use server";
await db.updateUser(id, Object.fromEntries(formData));
// Option 1: Redirect (ALWAYS throw)
throw redirect("/users");
// Option 2: Revalidate specific query + redirect
throw redirect("/users", { revalidate: getUser.keyFor(id) });
// Option 3: Reload current page
throw reload({ revalidate: getUser.key });
}, "updateUser");
```
---
## Server Functions
### Function-Level "use server"
```tsx
const getData = async (id: string) => {
"use server";
return db.getData(id); // Runs server-only, compiled to RPC
};
```
### File-Level "use server"
```tsx
// src/lib/server/queries.ts
"use server";
export async function getUsers() {
return db.getUsers();
}
export async function getProduct(id: string) {
return db.getProduct(id);
}
```
### Serialization Requirement
Arguments and return values MUST be serializable (SolidStart uses Seroval). NEVER pass DOM nodes, functions, or class instances through server functions.
---
## SSR and Hydration
| Mode | Function | Use Case |
|------|----------|----------|
| Sync SSR | `renderToString` | Static pages, no async data |
| Streaming SSR | `renderToStream` | Dynamic pages with Suspense boundaries |
| Client hydration | `hydrate` | Attach reactivity to server-rendered HTML |
### Streaming SSR (Default in SolidStart)
```tsx
import { renderToStream } from "solid-js/web";
const stream = renderToStream(() => , {
onCompleteShell() {
// Shell rendered, Suspense fallbacks in place
},
onCompleteAll() {
// All async content resolved
},
});
stream.pipe(res); // Node.js
stream.pipeTo(writable); // Web Streams
```
### HydrationScript
ALWAYS include `` once in the HTML head. It captures user events (click, input) before Solid loads, then replays them after hydration.
### isServer
```tsx
import { isServer } from "solid-js/web";
if (isServer) {
// Tree-shaken from client bundle at build time
}
```
---
## API Routes
API routes export named HTTP method handlers (NOT a default component):
```tsx
// routes/api/users/[id].ts
import type { APIEvent } from "@solidjs/start/server";
export async function GET({ params }: APIEvent) {
const user = await db.getUser(params.id);
if (!user) return new Response("Not found", { status: 404 });
return user; // Auto-serialized to JSON
}
export async function DELETE({ params }: APIEvent) {
await db.deleteUser(params.id);
return new Response(null, { status: 204 });
}
```
API routes are prioritized over UI routes at the same path.
---
## SolidStart 0.x to 1.0 Migration
| 0.x (Deprecated) | 1.0 (Current) |
|-------------------|----------------|
| `createServerData$` | `query()` + `createAsync()` |
| `createServerAction$` | `action()` |
| `createRouteData` | `query()` + `createAsync()` |
| `useRouteData()` | `createAsync(() => myQuery())` |
| `server$()` wrapper | `"use server"` directive |
---
## Reference Links
- [references/methods.md](references/methods.md) -- API signatures for query, createAsync, action, redirect, renderToStream, hydrate
- [references/examples.md](references/examples.md) -- File routing, data loading, server functions, action/form, SSR, API route patterns
- [references/anti-patterns.md](references/anti-patterns.md) -- Next.js patterns, getServerSideProps, useEffect data fetching, React Router patterns
### Official Sources
- https://docs.solidjs.com/solid-start
- https://docs.solidjs.com/solid-start/building-your-application/routing
- https://docs.solidjs.com/solid-start/reference/server/use-server
- https://docs.solidjs.com/solid-router/reference/data-apis/query
- https://docs.solidjs.com/solid-router/reference/data-apis/action
- https://docs.solidjs.com/solid-router/reference/data-apis/create-async
- https://docs.solidjs.com/reference/rendering/render-to-stream
- https://docs.solidjs.com/reference/rendering/hydrate
- https://docs.solidjs.com/solid-start/building-your-application/api-routes