add docs about serialization modes (#1436)

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

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"
 	]

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).

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). Note that `unsafe-eval` is only required for `serialization.mode: "js"`.
+
 ### 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.
@@ -60,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';

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,48 @@ 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.
+
+### 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
 
-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 +135,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 +153,6 @@ export default defineConfig({
 
 Within `wrangler.toml` you will need to enable node compatibility:
 
-
 ```
 compatibility_flags = [ "nodejs_compat" ]
 ```
@@ -130,6 +165,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.                                                                                                 |

src/routes/solid-start/reference/server/use-server.mdx

@@ -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.
@@ -97,7 +98,8 @@ 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