Skip to content

Commit c83f957

Browse files
atilafassinaatilafassina
committed
expand docs on rendering modes
1 parent 2997ee3 commit c83f957

5 files changed

Lines changed: 143 additions & 37 deletions

File tree

‎src/routes/solid-start/building-your-application/data.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"title": "Building your application",
33
"pages": [
4+
"rendering-modes.mdx",
45
"routing.mdx",
56
"api-routes.mdx",
67
"css-and-styling.mdx",

‎src/routes/solid-start/building-your-application/rendering-modes.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "Rendering Modes"
3+
---
4+
5+
SolidStart has 3 kinds of rendering modes: `sync`, `async`, and `stream`.
6+
Let's talk about how each of them work and which one to pick.
7+
8+
:::note
9+
Default is **stream** and performance-wise should be preferred as a rule-of-thumb.
10+
:::
11+
12+
All modes have some degree of Server-Side Rendering, you may need to change them globally depending on your deployment provider.
13+
And you may prefer to override them for better bot support and SEO.
14+
15+
## Impacted Features
16+
17+
| Feature | sync | async | stream |
18+
| -------------------- | ----------- | --------------------------- | ----------------------- |
19+
| Data fetching | Client-side | Server-side (blocking) | Server-side (streaming) |
20+
| Suspense fallbacks | Yes | No | Yes |
21+
| Time to first byte | Fast | Slower (waits for all data) | Faster |
22+
| Total page load time | Slower | Fast (server fetches) | Faster (progressive) |
23+
24+
### Sync Mode
25+
26+
Uses [`renderToString`](/reference/rendering/render-to-string) to render the page from Solid's core to render the page synchronously.
27+
All async features are disabled and the page is rendered as soon as possible and sent to the client-side where data fetching will happen post-hydration.
28+
29+
### Async Mode
30+
31+
Uses [`renderToStringAsync`](/reference/rendering/render-to-string-async) to render the page from Solid's core to render the page asynchronously.
32+
All Suspense boundares are resolved and rendered before being sent to the client-side.
33+
34+
No suspense fallbacks are shown in the browser, which makes this mode ideal for SEO optimizations and bot support.
35+
36+
### Stream Mode
37+
38+
Uses [`renderToStream`](/reference/rendering/render-to-stream) to render the page from Solid's core to render the page streaming.
39+
Leveraging [TransformableStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to progressively send the HTML to the client-side.
40+
41+
This mode is ideal for performance and future-friendly apps. .
42+
43+
## Global Configuration
44+
45+
The modes can be defined app-wide via the configuration file or via the [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server) file.
46+
47+
```tsx title="app.config.ts"
48+
import { defineConfig } from "@solidjs/start/config";
49+
50+
export default defineConfig({
51+
mode: "stream",
52+
});
53+
```
54+
55+
The value in [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server) overrides the value in [`app.config.ts`](/solid-start/reference/entrypoints/app-config).
56+
57+
```tsx title="src/entry-server.tsx"
58+
import { createHandler, StartServer } from "@solidjs/start/server";
59+
60+
export default createHandler(() => (
61+
<StartServer document={...} mode="async" />
62+
), {
63+
mode: "async"
64+
});
65+
```
66+
67+
## Per-Route Configuration
68+
69+
The optional secondary parameter in [`createHandler`](/solid-start/reference/server/create-handler) can be an object or a function that receives the `RequestEvent` and returns an object with the mode to use for the route.
70+
71+
```tsx title="src/entry-server.tsx"
72+
import { createHandler, StartServer } from "@solidjs/start/server";
73+
74+
export default createHandler(() => (
75+
<StartServer document={...} />
76+
), {
77+
mode: (event) => {
78+
return event.request.url.includes("/special-route") ? "async" : "stream";
79+
}
80+
});
81+
```
82+
83+
It can also be used for bot detection via the `userAgent` property of the `RequestEvent`.
84+
85+
```tsx title="src/entry-server.tsx"
86+
import { createHandler, StartServer } from "@solidjs/start/server";
87+
88+
export default createHandler(() => (
89+
<StartServer document={...} />
90+
), {
91+
mode: (event) => {
92+
return isBot(event.request.userAgent) ? "async" : "stream";
93+
}
94+
});
95+
```

‎src/routes/solid-start/reference/config/define-config.mdx‎

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@ export default defineConfig({
2121
});
2222
```
2323

24-
The `vite` option can also be a function that can be customized for each Vinxi router.
24+
The `vite` option can also be a function that can be customized for each Vinxi router.
2525

2626
In SolidStart, 3 routers are used:
27+
2728
- `server` - server-side routing
28-
- `client` - for the client-side routing
29+
- `client` - for the client-side routing
2930
- `server-function` - server functions.
3031

3132
```tsx
@@ -44,11 +45,11 @@ export default defineConfig({
4445

4546
## Configuring Nitro
4647

47-
SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms.
48-
The `server` option exposes some Nitro options including the build and deployment presets.
48+
SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms.
49+
The `server` option exposes some Nitro options including the build and deployment presets.
4950
An overview of all available presets is available in the [Deploy section of the Nitro documentation](https://nitro.build/deploy).
5051

51-
Some common ones include:
52+
Some common ones include:
5253

5354
**Servers**
5455

@@ -85,7 +86,7 @@ export default defineConfig({
8586

8687
#### Special note
8788

88-
SolidStart uses async local storage.
89+
SolidStart uses async local storage.
8990
Netlify, Vercel, and Deno support this out of the box but if you're using Cloudflare you will need to specify the following:
9091

9192
```js
@@ -103,22 +104,22 @@ export default defineConfig({
103104

104105
Within `wrangler.toml` you will need to enable node compatibility:
105106

106-
107107
```
108108
compatibility_flags = [ "nodejs_compat" ]
109109
```
110110

111111
## Parameters
112112

113-
| Property | Type | Default | Description |
114-
| -------------------- | ------------------------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115-
| ssr | boolean | true | Toggle between client and server rendering. |
116-
| solid | object | | Configuration object for [vite-plugin-solid](https://github.com/solidjs/vite-plugin-solid) |
117-
| extensions | string[] | ["js", "jsx", "ts", "tsx"] | Array of file extensions to be treated as routes. |
118-
| server | object | | Nitro server config options |
119-
| appRoot | string | "./src" | The path to the root of the application. |
120-
| routeDir | string | "./routes" | The path to where the routes are located. |
121-
| middleware | string | | The path to an optional [middleware](/solid-start/advanced/middleware) file. |
122-
| devOverlay | boolean | true | Toggle the dev overlay. |
123-
| experimental.islands | boolean | false | Enable "islands" mode. |
124-
| vite | `ViteConfig` or `({ router })=>ViteConfig` | | [Vite config object](https://vitejs.dev/config/shared-options.html). Can be configured for each `router` which has the string value "server", "client" or "server-function"` |
113+
| Property | Type | Default | Description |
114+
| -------------------- | ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115+
| ssr | boolean | true | Toggle between client and server rendering. |
116+
| mode | stream, async, sync | stream | The rendering mode to use. |
117+
| solid | object | | Configuration object for [vite-plugin-solid](https://github.com/solidjs/vite-plugin-solid) |
118+
| extensions | string[] | js, jsx, ts, tsx | Array of file extensions to be treated as routes. |
119+
| server | object | | Nitro server config options |
120+
| appRoot | string | "./src" | The path to the root of the application. |
121+
| routeDir | string | "./routes" | The path to where the routes are located. |
122+
| middleware | string | | The path to an optional [middleware](/solid-start/advanced/middleware) file. |
123+
| devOverlay | boolean | true | Toggle the dev overlay. |
124+
| experimental.islands | boolean | false | Enable "islands" mode. |
125+
| vite | `ViteConfig` or `({ router })=>ViteConfig` | | [Vite config object](https://vitejs.dev/config/shared-options.html). Can be configured for each `router` which has the string value "server", "client" or "server-function"` |

‎src/routes/solid-start/reference/entrypoints/entry-server.mdx‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
title: entry-server.tsx
33
---
44

5-
`entry-server.tsx` is where an application starts on the server.
5+
This is where application is rendered on the server.
66
This happens by `entry-server.tsx` providing a document component to [`<StartServer>`](/solid-start/reference/server/start-server) and passing it into [`createHandler`](/solid-start/reference/server/create-handler) for server side rendering.
7-
A typical `entry-server.tsx` for a new project looks like this:
87

9-
```tsx
8+
Every SolidStart app must have an `entry-server.tsx` file, the most basic usage looks about the following example:
9+
10+
```tsx title="src/entry-server.tsx"
1011
import { createHandler, StartServer } from "@solidjs/start/server";
1112

1213
export default createHandler(() => (
@@ -29,4 +30,4 @@ export default createHandler(() => (
2930
));
3031
```
3132

32-
For setting different SSR modes (sync | async | stream), see [`createHandler`](/solid-start/reference/server/create-handler).
33+
To take full advantage of the `entry-server.tsx` file, check the [`createHandler` docs](/solid-start/reference/server/create-handler) and the [Rendering Modes](/solid-start/building-your-application/rendering-modes) page.

‎src/routes/solid-start/reference/server/create-handler.mdx‎

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,36 @@ title: createHandler
33
---
44

55
The `createHandler` is used to start the server in [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server).
6-
It takes a function that returns a static document (often created with [`<StartServer>`](/solid-start/reference/server/start-server)), and serves it using one of the three function for server side rendering (SSR):
6+
It takes a function that returns a static document (often created with [`<StartServer>`](/solid-start/reference/server/start-server)), renders, and serves it.
77

8-
- [`renderToString`](/reference/rendering/render-to-string) - "sync"
9-
- [`renderToStringAsync`](/reference/rendering/render-to-string-async) - "async"
10-
- [`renderToStream`](/reference/rendering/render-to-stream) - "stream"
8+
:::note
9+
To fully understand how to leverage different rendering modes, please refer to the [Rendering Modes](/solid-start/building-your-application/rendering-modes) page.
10+
:::
1111

12-
The SSR mode can be configured through the `mode` property on the options object:
12+
A `createHandler` is essential to every SolidStart app.
13+
To fallback the rendering mode to the [`app.config.ts`](/solid-start/reference/entrypoints/app-config-ts) definition (or the default "stream" mode), you can use the `createHandler` without any options.
1314

14-
```tsx
15+
```tsx title="src/entry-server.tsx"
1516
import { createHandler, StartServer } from "@solidjs/start/server";
1617

1718
export default createHandler(() => (
1819
<StartServer document={...}
1920
/>
20-
), {
21-
mode: "async"
22-
});
21+
));
2322
```
2423

25-
## Parameters
24+
It is also possible to [override the rendering mode for a specific route](/solid-start/building-your-application/rendering-modes#per-route-configuration).
25+
26+
## Type Signature
2627

27-
| Argument | Type | Default | Description |
28-
| ------------ | ------------------------ | -------- | ----------------------------------------------------------------- |
29-
| fn | fn: (context: PageEvent) | | A function that returns the static document for your application. |
30-
| options.mode | string | "stream" | The SSR mode. Options are 'sync', 'async' and 'stream'. |
28+
```tsx
29+
type RenderingModes = "stream" | "async" | "sync";
30+
31+
function createHandler(
32+
handler: () => (document: any, options?: any) => void,
33+
options?:
34+
| { mode?: RenderingModes }
35+
| ((event: RequestEvent) => { mode: RenderingModes })
36+
| undefined
37+
): (event: RequestEvent) => Response;
38+
```

0 commit comments

Comments
 (0)