Skip to content

Commit 27a34a2

Browse files
LadyBluenotesLadyBluenotes
committed
update docs for accuracy
1 parent 44fe189 commit 27a34a2

7 files changed

Lines changed: 35 additions & 52 deletions

File tree

‎src/routes/reference/rendering/dev.mdx‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,9 @@ const DEV:
4444

4545
## Behavior
4646

47-
- In the development browser bundle, `DEV` is defined and exposes development hooks.
47+
- In the development browser bundle, `DEV` is defined and exposes development hooks and internals.
4848
- In production and server bundles, `DEV` is `undefined`.
49+
- `DEV` is intended for tooling, diagnostics, and library code that needs development-only behavior.
4950

5051
## Examples
5152

@@ -55,9 +56,7 @@ const DEV:
5556
import { DEV } from "solid-js";
5657

5758
if (DEV) {
58-
DEV.hooks.afterUpdate = () => {
59-
console.log("component graph updated");
60-
};
59+
console.warn("development-only check");
6160
}
6261
```
6362

‎src/routes/reference/rendering/hydrate.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,15 +74,16 @@ Dispose function for the hydrated root.
7474

7575
## Behavior
7676

77-
- `hydrate` is a client-only API and throws in the server bundle.
78-
- `hydrate` reuses server-rendered DOM instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`.
77+
- `hydrate` is a client-only API.
78+
- `hydrate` reuses DOM produced by Solid's server renderer instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`.
79+
- The hydrated DOM and the JSX returned by `fn` must match the server output for hydration to succeed.
7980
- The returned function disposes the hydrated root.
8081

8182
## Examples
8283

8384
### Basic usage
8485

85-
```ts
86+
```tsx
8687
import { hydrate } from "solid-js/web";
8788

8889
// #app already contains server-rendered Solid markup

‎src/routes/reference/rendering/hydration-script.mdx‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ Delegated event names captured before client scripts load.
7272

7373
- The generated script initializes `window._$HY` and bootstraps delegated event replay before the runtime loads.
7474
- The default captured delegated events are `"click"` and `"input"` unless `eventNames` is overridden.
75+
- Place the generated script once in the server-rendered document when the page will hydrate on the client.
7576
- `HydrationScript` returns JSX for server-rendered HTML output, and `generateHydrationScript` returns a string for manual HTML generation.
7677
- In browser bundles, these exports are placeholders that return `undefined`.
7778

@@ -81,11 +82,18 @@ Delegated event names captured before client scripts load.
8182

8283
```tsx
8384
import { HydrationScript } from "solid-js/web";
84-
85-
// Use when generating HTML on the server
86-
<head>
87-
<HydrationScript />
88-
</head>;
85+
import type { JSX } from "solid-js";
86+
87+
function Html(props: { children: JSX.Element }) {
88+
return (
89+
<html lang="en">
90+
<head>
91+
<HydrationScript />
92+
</head>
93+
<body>{props.children}</body>
94+
</html>
95+
);
96+
}
8997
```
9098

9199
### `generateHydrationScript`

‎src/routes/reference/rendering/render-to-stream.mdx‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,10 @@ function renderToStream<T>(
3232
renderId?: string;
3333
onCompleteShell?: (info: { write: (v: string) => void }) => void;
3434
onCompleteAll?: (info: { write: (v: string) => void }) => void;
35-
onError?: (err: any) => void;
3635
}
3736
): {
3837
pipe: (writable: { write: (v: string) => void }) => void;
39-
pipeTo: (writable: WritableStream) => Promise<void>;
38+
pipeTo: (writable: WritableStream) => void;
4039
};
4140
```
4241

@@ -74,21 +73,16 @@ Callback invoked when the shell is ready to flush.
7473

7574
Callback invoked after all server suspense boundaries have settled.
7675

77-
#### `onError`
78-
79-
- **Type:** `(err: any) => void`
80-
81-
Callback invoked when a rendering error is encountered.
82-
8376
## Return value
8477

8578
- **Type:** `{ pipe: ..., pipeTo: ... }`
8679

87-
Streaming controller with `pipe` and `pipeTo` methods. The runtime implementation is also thenable and can resolve to the complete HTML string.
80+
Streaming controller with `pipe` and `pipeTo` methods.
8881

8982
## Behavior
9083

91-
- `renderToStream` is a server rendering API and is unsupported in browser bundles. It buffers the shell HTML, including suspense fallback content, and can flush it before later async fragments and serialized data stream as resources resolve.
84+
- `renderToStream` is a server rendering API and is unsupported in browser bundles.
85+
- It renders the shell first, including suspense fallback content, and can flush that output before later async fragments and serialized data stream as resources resolve.
9286
- `onCompleteShell` and `onCompleteAll` receive a `write()` helper for injecting additional output into the stream.
9387
- `pipe` writes to Node-style writable targets.
9488
- `pipeTo` writes to a `WritableStream`.
@@ -97,19 +91,19 @@ Streaming controller with `pipe` and `pipeTo` methods. The runtime implementatio
9791

9892
### `pipe`
9993

100-
```ts
94+
```tsx
10195
import { renderToStream } from "solid-js/web";
10296

10397
renderToStream(() => <App />).pipe(response);
10498
```
10599

106100
### `pipeTo`
107101

108-
```ts
102+
```tsx
109103
import { renderToStream } from "solid-js/web";
110104

111105
const { writable } = new TransformStream();
112-
await renderToStream(() => <App />).pipeTo(writable);
106+
renderToStream(() => <App />).pipeTo(writable);
113107
```
114108

115109
## Related

‎src/routes/reference/rendering/render-to-string-async.mdx‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,6 @@ function renderToStringAsync<T>(
3030
timeoutMs?: number;
3131
nonce?: string;
3232
renderId?: string;
33-
noScripts?: boolean;
34-
onError?: (err: any) => void;
3533
}
3634
): Promise<string>;
3735
```
@@ -64,18 +62,6 @@ Nonce applied to inline scripts emitted during rendering.
6462

6563
Identifier used to namespace the render output.
6664

67-
#### `noScripts`
68-
69-
- **Type:** `boolean`
70-
71-
Disables script emission, including serialized data used for hydration continuation.
72-
73-
#### `onError`
74-
75-
- **Type:** `(err: any) => void`
76-
77-
Callback invoked when a rendering error is encountered.
78-
7965
## Return value
8066

8167
- **Type:** `Promise<string>`
@@ -84,16 +70,17 @@ Promise that resolves to the rendered HTML string.
8470

8571
## Behavior
8672

87-
- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles. It builds on [`renderToStream`](/reference/rendering/render-to-stream) and waits for the full stream result before resolving.
88-
- If the timeout elapses, the returned promise rejects instead of resolving partial HTML.
89-
- Resource data is serialized for client hydration unless scripts are disabled.
73+
- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles.
74+
- It waits for server suspense boundaries to settle before resolving the final HTML string.
75+
- `timeoutMs` limits how long the render waits for async suspense work to finish.
76+
- Resource data is serialized for client hydration.
9077
- `renderId` namespaces the render output when multiple top-level roots are present.
9178

9279
## Examples
9380

9481
### Basic usage
9582

96-
```ts
83+
```tsx
9784
import { renderToStringAsync } from "solid-js/web";
9885

9986
const html = await renderToStringAsync(() => <App />);

‎src/routes/reference/rendering/render-to-string.mdx‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ function renderToString<T>(
2828
options?: {
2929
nonce?: string;
3030
renderId?: string;
31-
onError?: (err: any) => void;
3231
}
3332
): string;
3433
```
@@ -55,12 +54,6 @@ Nonce applied to inline scripts emitted during rendering.
5554

5655
Identifier used to namespace the render output.
5756

58-
#### `onError`
59-
60-
- **Type:** `(err: any) => void`
61-
62-
Callback invoked when a rendering error is encountered.
63-
6457
## Return value
6558

6659
- **Type:** `string`
@@ -70,6 +63,7 @@ Rendered HTML string.
7063
## Behavior
7164

7265
- `renderToString` is a server rendering API, is unsupported in browser bundles, and completes synchronously.
66+
- It returns the current render output without waiting for async suspense boundaries to settle.
7367
- The output includes hydration markup. Inline serialized scripts are emitted only when serializer data is produced.
7468
- Registered assets are injected into the HTML output, typically before `</head>`.
7569
- `renderId` namespaces the render output when multiple top-level roots are present.
@@ -78,7 +72,7 @@ Rendered HTML string.
7872

7973
### Basic usage
8074

81-
```ts
75+
```tsx
8276
import { renderToString } from "solid-js/web";
8377

8478
const html = renderToString(() => <App />);

‎src/routes/reference/rendering/render.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Dispose function for the mounted root.
6363

6464
### Basic usage
6565

66-
```ts
66+
```tsx
6767
import { render } from "solid-js/web";
6868

6969
const dispose = render(() => <App />, document.getElementById("app")!);

0 commit comments

Comments
 (0)