From 7ffe317c1c31170884b7aa768c654b40d31deb4c Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Tue, 3 Mar 2026 20:31:58 +0100 Subject: [PATCH 1/6] add docs about serialization modes --- src/routes/solid-start/guides/security.mdx | 6 ++- .../reference/config/define-config.mdx | 43 +++++++++++++++---- .../reference/server/use-server.mdx | 16 ++++--- 3 files changed, 48 insertions(+), 17 deletions(-) diff --git a/src/routes/solid-start/guides/security.mdx b/src/routes/solid-start/guides/security.mdx index f6ba3bed4..9c6f1ba1b 100644 --- a/src/routes/solid-start/guides/security.mdx +++ b/src/routes/solid-start/guides/security.mdx @@ -11,7 +11,7 @@ tags: - csp - middleware - protection -version: '1.0' +version: "1.0" description: >- Secure your SolidStart apps against XSS, CSRF attacks. Configure CSP headers, CORS policies, and implement security best practices. @@ -38,12 +38,14 @@ It is highly recommended to read the [Cross Site Scripting Prevention Cheat Shee To configure the `Content-Security-Policy` HTTP header, a [middleware](/solid-start/advanced/middleware) can be used. +If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). + ### With nonce (recommended) If you want to use a [strict CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP#strict_csp) with nonces: 1. Create a middleware that configures the CSP header. -It must then be registered using the [`onRequest`](/solid-start/advanced/middleware#onrequest) event. + It must then be registered using the [`onRequest`](/solid-start/advanced/middleware#onrequest) event. 2. Create a nonce using a cryptographic random value generator, such as the [`randomBytes`](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback) function from the `crypto` module. 3. Store the nonce in the [`locals`](/solid-start/advanced/middleware#locals) object. 4. Configure SolidStart to use the nonce in your [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server) file. diff --git a/src/routes/solid-start/reference/config/define-config.mdx b/src/routes/solid-start/reference/config/define-config.mdx index 5f3748e3a..f56b8627f 100644 --- a/src/routes/solid-start/reference/config/define-config.mdx +++ b/src/routes/solid-start/reference/config/define-config.mdx @@ -10,7 +10,7 @@ tags: - deployment - build - plugins -version: '1.0' +version: "1.0" description: >- Configure SolidStart apps with defineConfig. Set up Vite plugins, Nitro presets, and deployment targets for any platform. @@ -35,11 +35,12 @@ export default defineConfig({ }); ``` -The `vite` option can also be a function that can be customized for each Vinxi router. +The `vite` option can also be a function that can be customized for each Vinxi router. In SolidStart, 3 routers are used: + - `server` - server-side routing -- `client` - for the client-side routing +- `client` - for the client-side routing - `server-function` - server functions. ```tsx @@ -56,13 +57,39 @@ export default defineConfig({ }); ``` +## Serialization + +SolidStart serializes server function payloads so they can move between server and client. You can configure the serializer mode to balance performance, payload size, and Content Security Policy (CSP) constraints. + +```tsx +import { defineConfig } from "@solidjs/start/config"; + +export default defineConfig({ + serialization: { + mode: "json", + }, +}); +``` + +### Modes + +- `json`: Uses `JSON.parse` on the client. This is the safest option for strict CSP because it avoids `eval`. Payloads can be slightly larger. +- `js`: Uses Seroval's JS serializer for smaller payloads and better performance, but it relies on `eval` during client-side deserialization and requires `unsafe-eval` in CSP. + +### Defaults + +- SolidStart v1 defaults to `js` for backwards compatibility. +- SolidStart v2 defaults to `json` for CSP compatibility. + +Seroval defines the supported value types and edge cases. See the full list in the Seroval compatibility docs. + ## Configuring Nitro -SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms. -The `server` option exposes some Nitro options including the build and deployment presets. +SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms. +The `server` option exposes some Nitro options including the build and deployment presets. An overview of all available presets is available in the [Deploy section of the Nitro documentation](https://nitro.build/deploy). - Some common ones include: +Some common ones include: **Servers** @@ -99,7 +126,7 @@ export default defineConfig({ #### Special note -SolidStart uses async local storage. +SolidStart uses async local storage. Netlify, Vercel, and Deno support this out of the box but if you're using Cloudflare you will need to specify the following: ```js @@ -117,7 +144,6 @@ export default defineConfig({ Within `wrangler.toml` you will need to enable node compatibility: - ``` compatibility_flags = [ "nodejs_compat" ] ``` @@ -130,6 +156,7 @@ compatibility_flags = [ "nodejs_compat" ] | solid | object | | Configuration object for [vite-plugin-solid](https://github.com/solidjs/vite-plugin-solid) | | extensions | string[] | ["js", "jsx", "ts", "tsx"] | Array of file extensions to be treated as routes. | | server | object | | Nitro server config options | +| serialization | object | | Serialization settings for server function payloads. | | appRoot | string | "./src" | The path to the root of the application. | | routeDir | string | "./routes" | The path to where the routes are located. | | middleware | string | | The path to an optional [middleware](/solid-start/advanced/middleware) file. | diff --git a/src/routes/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/reference/server/use-server.mdx index 5f8be7212..a9218cb5b 100644 --- a/src/routes/solid-start/reference/server/use-server.mdx +++ b/src/routes/solid-start/reference/server/use-server.mdx @@ -11,7 +11,7 @@ tags: - actions - security - database -version: '1.0' +version: "1.0" description: >- Create server-only functions in SolidStart using 'use server' directive. Handle database operations, API calls, and secure logic on the server. @@ -26,7 +26,9 @@ const logHello = async (message: string) => { console.log(message); }; ``` + Or when using at the top of a file. + ```tsx // File-level "use server"; @@ -74,16 +76,15 @@ The following examples show how to use server functions alongside solid-router's ```tsx {3} const getUser = query((id) => { - "use server"; - return db.getUser(id); + "use server"; + return db.getUser(id); }, "users"); const updateUser = action(async (id, data) => { - "use server" - await db.setUser(id, data); - throw redirect("/", { revalidate: getUser.keyFor(id) }); + "use server"; + await db.setUser(id, data); + throw redirect("/", { revalidate: getUser.keyFor(id) }); }); - ``` When `getUser` or `updateUser` are triggered on the client, an http request will be made to the server, which calls the corresponding server function. @@ -98,6 +99,7 @@ The data for the redirected page is fetched and streamed to the client in the sa Server functions allow the serialization of many different data types in the response, using the Seroval serializer. The full list is available [in Seroval's source code](https://github.com/lxsmnsyc/seroval/blob/main/docs/compatibility.md#supported-types). +Configure serialization mode and CSP behavior in [`defineConfig`](/solid-start/reference/config/define-config#serialization). ## Meta information From fc9066f30988168b6625dbd3a877500de66466a7 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 4 Mar 2026 11:36:55 +0100 Subject: [PATCH 2/6] Update src/routes/solid-start/reference/config/define-config.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/routes/solid-start/reference/config/define-config.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/solid-start/reference/config/define-config.mdx b/src/routes/solid-start/reference/config/define-config.mdx index f56b8627f..8f186f781 100644 --- a/src/routes/solid-start/reference/config/define-config.mdx +++ b/src/routes/solid-start/reference/config/define-config.mdx @@ -81,7 +81,7 @@ export default defineConfig({ - SolidStart v1 defaults to `js` for backwards compatibility. - SolidStart v2 defaults to `json` for CSP compatibility. -Seroval defines the supported value types and edge cases. See the full list in the Seroval compatibility docs. +Seroval defines the supported value types and edge cases. See the full list in the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). ## Configuring Nitro From 28e05cf79fd5ff7634e906312263c77429625d19 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 4 Mar 2026 14:04:41 +0100 Subject: [PATCH 3/6] Update src/routes/solid-start/guides/security.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/routes/solid-start/guides/security.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/solid-start/guides/security.mdx b/src/routes/solid-start/guides/security.mdx index 9c6f1ba1b..78e3736fa 100644 --- a/src/routes/solid-start/guides/security.mdx +++ b/src/routes/solid-start/guides/security.mdx @@ -38,7 +38,7 @@ It is highly recommended to read the [Cross Site Scripting Prevention Cheat Shee To configure the `Content-Security-Policy` HTTP header, a [middleware](/solid-start/advanced/middleware) can be used. -If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). +If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). Note that `'unsafe-eval'` is only required when using `serialization.mode: "js"`, and the nonce-based CSP example below assumes this mode. ### With nonce (recommended) From 9d7faa6bec4988e63b8186f86cc65e5e615e8682 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 4 Mar 2026 14:04:49 +0100 Subject: [PATCH 4/6] Update src/routes/solid-start/reference/server/use-server.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/routes/solid-start/reference/server/use-server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/reference/server/use-server.mdx index a9218cb5b..c3939669b 100644 --- a/src/routes/solid-start/reference/server/use-server.mdx +++ b/src/routes/solid-start/reference/server/use-server.mdx @@ -11,7 +11,7 @@ tags: - actions - security - database -version: "1.0" +version: '1.0' description: >- Create server-only functions in SolidStart using 'use server' directive. Handle database operations, API calls, and secure logic on the server. From 75d802c98a1fd21cfe33c4c61541a96947e02f3f Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 4 Mar 2026 14:04:56 +0100 Subject: [PATCH 5/6] Update src/routes/solid-start/guides/security.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/routes/solid-start/guides/security.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/solid-start/guides/security.mdx b/src/routes/solid-start/guides/security.mdx index 78e3736fa..aa52a873b 100644 --- a/src/routes/solid-start/guides/security.mdx +++ b/src/routes/solid-start/guides/security.mdx @@ -11,7 +11,7 @@ tags: - csp - middleware - protection -version: "1.0" +version: '1.0' description: >- Secure your SolidStart apps against XSS, CSRF attacks. Configure CSP headers, CORS policies, and implement security best practices. From 193015eb5dbd32035ce0248e3e4cae104b0d3bc3 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 4 Mar 2026 11:33:47 +0100 Subject: [PATCH 6/6] add new serialization section --- src/routes/solid-start/advanced/data.json | 1 + .../solid-start/advanced/serialization.mdx | 78 +++++++++++++++++++ src/routes/solid-start/guides/security.mdx | 6 +- .../reference/config/define-config.mdx | 11 ++- .../reference/server/use-server.mdx | 2 +- 5 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 src/routes/solid-start/advanced/serialization.mdx diff --git a/src/routes/solid-start/advanced/data.json b/src/routes/solid-start/advanced/data.json index e0f08e8ba..b9f0ac6d3 100644 --- a/src/routes/solid-start/advanced/data.json +++ b/src/routes/solid-start/advanced/data.json @@ -5,6 +5,7 @@ "session.mdx", "request-events.mdx", "return-responses.mdx", + "serialization.mdx", "auth.mdx", "websocket.mdx" ] diff --git a/src/routes/solid-start/advanced/serialization.mdx b/src/routes/solid-start/advanced/serialization.mdx new file mode 100644 index 000000000..f896c92cc --- /dev/null +++ b/src/routes/solid-start/advanced/serialization.mdx @@ -0,0 +1,78 @@ +--- +title: Serialization +use_cases: >- + server function payloads, data transfer, csp, security, performance +tags: + - serialization + - server-functions + - csp + - security + - performance +version: "1.0" +description: >- + Understand how SolidStart serializes server function payloads, supported + types, and CSP tradeoffs. +--- + +SolidStart serializes server function arguments and return values so they can travel between server and client. It uses Seroval under the hood and streams payloads to keep responses responsive. + +## Configuration + +Configure serialization in your `app.config.ts` with `defineConfig`: + +```tsx tab title="v1" +import { defineConfig } from "@solidjs/start/config"; + +export default defineConfig({ + serialization: { + mode: "js", + }, +}); +``` + +```tsx tab title="v2" +import { defineConfig } from "vite"; +import { solidStart } from "@solidjs/start"; + +export default defineConfig({ + plugins: [ + solidStart({ + serialization: { + mode: "json", + }, + }), + ], +}); +``` + +See the full config reference in [`defineConfig`](/solid-start/reference/config/define-config#serialization). + +## Modes + +- `json`: Uses `JSON.parse` on the client. Best for strict CSP because it avoids `eval`. Payloads can be slightly larger. +- `js`: Uses Seroval's JS serializer for smaller payloads and better performance, but it requires `unsafe-eval` in CSP. + +:::caution[v2 Breaking Change: Defaults] +SolidStart v1 defaults to `js` for backwards compatibility. SolidStart v2 defaults to `json` for CSP compatibility. +::: + +## Supported types (default) + +SolidStart enables Seroval plus a default set of web platform plugins. These plugins add support for: + +- `AbortSignal`, `CustomEvent`, `DOMException`, `Event` +- `FormData`, `Headers`, `ReadableStream` +- `Request`, `Response` +- `URL`, `URLSearchParams` + +Seroval supports additional value types. The compatibility list is broader than what SolidStart enables by default, so treat it as a superset. See the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). + +## Limits and exclusions + +- `RegExp` is disabled by default. +- JSON mode enforces a maximum serialization depth of 64. If you exceed this, flatten the structure or return a simpler payload. + +## Related guidance + +- Configure modes and defaults in [`defineConfig`](/solid-start/reference/config/define-config#serialization). +- CSP implications and nonce examples live in the [Security guide](/solid-start/guides/security#content-security-policy-csp). diff --git a/src/routes/solid-start/guides/security.mdx b/src/routes/solid-start/guides/security.mdx index aa52a873b..8d663ff89 100644 --- a/src/routes/solid-start/guides/security.mdx +++ b/src/routes/solid-start/guides/security.mdx @@ -11,7 +11,7 @@ tags: - csp - middleware - protection -version: '1.0' +version: "1.0" description: >- Secure your SolidStart apps against XSS, CSRF attacks. Configure CSP headers, CORS policies, and implement security best practices. @@ -38,7 +38,7 @@ It is highly recommended to read the [Cross Site Scripting Prevention Cheat Shee To configure the `Content-Security-Policy` HTTP header, a [middleware](/solid-start/advanced/middleware) can be used. -If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). Note that `'unsafe-eval'` is only required when using `serialization.mode: "js"`, and the nonce-based CSP example below assumes this mode. +If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). Note that `unsafe-eval` is only required for `serialization.mode: "js"`. ### With nonce (recommended) @@ -62,7 +62,7 @@ export default createMiddleware({ const csp = ` default-src 'self'; - script-src 'nonce-${nonce}' 'strict-dynamic' 'unsafe-eval'; + script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; diff --git a/src/routes/solid-start/reference/config/define-config.mdx b/src/routes/solid-start/reference/config/define-config.mdx index 8f186f781..d8c7d637f 100644 --- a/src/routes/solid-start/reference/config/define-config.mdx +++ b/src/routes/solid-start/reference/config/define-config.mdx @@ -81,7 +81,16 @@ export default defineConfig({ - SolidStart v1 defaults to `js` for backwards compatibility. - SolidStart v2 defaults to `json` for CSP compatibility. -Seroval defines the supported value types and edge cases. See the full list in the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). +### Supported types (default) + +SolidStart enables Seroval plus a default set of web platform plugins. These plugins add support for: + +- `AbortSignal`, `CustomEvent`, `DOMException`, `Event` +- `FormData`, `Headers`, `ReadableStream` +- `Request`, `Response` +- `URL`, `URLSearchParams` + +Seroval supports additional value types. The compatibility list is broader than what SolidStart enables by default, so treat it as a superset. See the full list in the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). ## Configuring Nitro diff --git a/src/routes/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/reference/server/use-server.mdx index c3939669b..41f850175 100644 --- a/src/routes/solid-start/reference/server/use-server.mdx +++ b/src/routes/solid-start/reference/server/use-server.mdx @@ -98,7 +98,7 @@ The data for the redirected page is fetched and streamed to the client in the sa ## Serialization Server functions allow the serialization of many different data types in the response, using the Seroval serializer. -The full list is available [in Seroval's source code](https://github.com/lxsmnsyc/seroval/blob/main/docs/compatibility.md#supported-types). +For supported types, defaults, and CSP tradeoffs, see the [Serialization guide](/solid-start/advanced/serialization). Configure serialization mode and CSP behavior in [`defineConfig`](/solid-start/reference/config/define-config#serialization). ## Meta information