@alxia/react-router 0.12.0 → 0.12.1

package/README.md

@@ -300,12 +300,17 @@ paint:
 ```tsx
 // app/root.tsx
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
-import { CspNonceMeta, InlineScript } from '@alxia/react-router/document';
+import {
+	CspNonceMeta,
+	InlineScript,
+	useNonce,
+} from '@alxia/react-router/document';
 import { themeBootScript } from '<your theme library>';
 
 const THEME_BOOT = themeBootScript();
 
 export function Layout({ children }: { children: React.ReactNode }) {
+	const nonce = useNonce();
 	return (
 		<html lang="en" suppressHydrationWarning>
 			<head>
@@ -313,7 +318,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 				<InlineScript code={THEME_BOOT} />
 				<CspNonceMeta />
 				<Meta />
-				<Links />
+				<Links nonce={nonce} />
 			</head>
 			<body>
 				{children}
@@ -329,10 +334,12 @@ export default function App() {
 }
 ```
 
-`THEME_BOOT` is your theme library's own boot script. With `/entry`, `<Links>`,
-`<Scripts>` and `<ScrollRestoration>` take the nonce from `<ServerRouter nonce>`,
-so their `nonce` props are optional; `useNonce()` stays for `InlineScript`,
-`CspNonceMeta` and any script or style the app inserts. An entry of your own
+`THEME_BOOT` is your theme library's own boot script. With `/entry`,
+`<Scripts>` and `<ScrollRestoration>` take the nonce from `<ServerRouter nonce>`
+and need no prop. `<Links>` does not suppress the hydration warning for its
+critical-CSS `<style nonce>` in development, so pass it `useNonce()`, as above;
+`useNonce()` also serves `InlineScript`, `CspNonceMeta` and any script or style
+the app inserts. An entry of your own
 wraps the router:
 
 ```tsx

package/docs/guide/csp-nonce.md

@@ -64,11 +64,13 @@ export {
 It reads `nonceOf(loadContext)` by default; `createEntry({ nonce })`
 takes another source ([the entry](document.md#the-entry)).
 
-The root passes nothing: `<Links>`, `<Scripts>` and `<ScrollRestoration>`
-fall back to the nonce `<ServerRouter nonce>` put in React Router's
-framework context, so their `nonce` props are optional with this entry.
-`useNonce()` stays for what the app inserts itself: an `InlineScript`, a
-`CspNonceMeta`, any other script or style.
+`<Scripts>` and `<ScrollRestoration>` fall back to the nonce `<ServerRouter
+nonce>` put in React Router's framework context, so they need no `nonce` prop
+with this entry. `<Links>` needs `<Links nonce={useNonce()} />`: it does not
+suppress the hydration warning for its development critical-CSS `<style>`
+([why](document.md#what-react-router-renders)). `useNonce()` also serves what
+the app inserts itself: an `InlineScript`, a `CspNonceMeta`, any other script
+or style.
 
 ### An entry of your own
 

package/docs/guide/document.md

@@ -61,19 +61,23 @@ tests: reset modules between them, or render the server path with
 
 ## What React Router renders
 
-With `@alxia/react-router/entry`, the root passes nothing. `<Links>`,
-`<Scripts>` and `<ScrollRestoration>` fall back to the nonce `<ServerRouter
-nonce>` put in React Router's framework context, so their `nonce` props are
-optional:
+With `@alxia/react-router/entry`, `<Scripts>` and `<ScrollRestoration>` need
+no `nonce`: they fall back to the nonce `<ServerRouter nonce>` put in React
+Router's framework context, and they suppress the hydration warning for the
+attribute the browser hides. `<Links>` falls back to it on the server too, but
+does not suppress the warning, so pass it `useNonce()`:
 
 ```tsx
 // app/root.tsx
+import { useNonce } from '@alxia/react-router/document';
+
 export function Layout({ children }: { children: React.ReactNode }) {
+	const nonce = useNonce();
 	return (
 		<html lang="en">
 			<head>
 				<meta charSet="utf-8" />
-				<Links />
+				<Links nonce={nonce} />
 			</head>
 			<body>
 				{children}
@@ -85,6 +89,13 @@ export function Layout({ children }: { children: React.ReactNode }) {
 }
 ```
 
+Why `<Links>` needs it: in development, React Router renders the critical CSS
+as a `<style nonce>`. The server writes the nonce on it, the browser hides the
+attribute and React Router's client knows none, so without the prop the client
+renders the `<style>` with no nonce and React reports a mismatch
+([Troubleshooting](../troubleshooting.md#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties-on-a-style-with-a-nonce)).
+`useNonce()` returns the same value on both sides.
+
 Keep `useNonce()` for what React Router does not render: an `InlineScript`,
 a `CspNonceMeta`, and any script or style the app inserts itself.
 

package/docs/troubleshooting.md

@@ -28,6 +28,7 @@ a loader, a message React Router or the browser prints, or an error from
 - [`Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'none'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-default-src-none)
 - [`Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-script-src-self-nonce-)
 - [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties)
+- [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties` on a `<style>` with a `nonce`](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties-on-a-style-with-a-nonce)
 - [`useNonce()` is undefined on the server](#usenonce-is-undefined-on-the-server)
 - [`TypeError: InlineScript(): the code contains "</script" or "<!--", which ends or confuses the script element; escape it, such as "<\/script" inside a string`](#typeerror-inlinescript-the-code-contains-script-or----which-ends-or-confuses-the-script-element-escape-it-such-as-script-inside-a-string)
 - [`TypeError: createPageLanguage(): the fallback … is not one of the languages; got ….`](#typeerror-createpagelanguage-the-fallback--is-not-one-of-the-languages-got-)
@@ -603,6 +604,40 @@ A warning on another element is a real mismatch: a `nonce` the browser hid
 is read by `useNonce()` from the document, so never pass it from loader
 data ([guide](guide/document.md#the-theme-boot-script)).
 
+### `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties` on a `<style>` with a `nonce`
+
+**When:** in development (`react-router dev`) with a CSP nonce, the console
+warns that a tree hydrated but some attributes did not match, and the diff
+shows `nonce="…"` on the `<style data-react-router-critical-css>` in `<head>`.
+
+**Why:** React Router renders the critical CSS as a `<style nonce>`. The
+server writes the nonce from `<ServerRouter nonce>`, the browser hides the
+attribute, and `<Links />` has no nonce to render on the client. Unlike
+`<Scripts>` and `<ScrollRestoration>`, `<Links>` does not suppress that
+warning.
+
+**Fix:** pass it the nonce `useNonce()` reads, on both sides:
+
+```tsx
+// app/root.tsx
+import { useNonce } from '@alxia/react-router/document';
+
+export function Layout({ children }: { children: React.ReactNode }) {
+	const nonce = useNonce();
+	return (
+		<html lang="en">
+			<head>
+				<Links nonce={nonce} />
+			</head>
+			<body>{children}</body>
+		</html>
+	);
+}
+```
+
+`<Scripts>` and `<ScrollRestoration>` need nothing
+([guide](guide/document.md#what-react-router-renders)).
+
 ### `useNonce()` is undefined on the server
 
 **When:** the page's inline scripts or `<CspNonceMeta />` render with no

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.12.0",
+	"version": "0.12.1",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",