From 5ae2ad72ecb1a799518cf41a7930dcbd80a44186 Mon Sep 17 00:00:00 2001 From: Ayobami Haastrup <47716486+AyobamiH@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:26:55 -0700 Subject: [PATCH 1/3] Document server-side rendering setup --- .storybook/preview.tsx | 1 + README.md | 10 ++ docs/server-side-rendering.md | 146 +++++++++++++++++++++++++ stories/Guides/ServerSideRendering.mdx | 7 ++ 4 files changed, 164 insertions(+) create mode 100644 docs/server-side-rendering.md create mode 100644 stories/Guides/ServerSideRendering.mdx diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx index d553f10c..8a868a6c 100644 --- a/.storybook/preview.tsx +++ b/.storybook/preview.tsx @@ -50,6 +50,7 @@ const preview: Preview = { storySort: { order: [ 'Welcome', + 'Guides', 'Migration Guides', 'Form Elements', 'Content Presentation', diff --git a/README.md b/README.md index 5d239140..d7ad9668 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,16 @@ import { Button, DateInput, Form } from 'nhsuk-react-components'; ; ``` +## Server-side rendering + +Version 6.0.0 and later support server-side rendering (SSR) and React Server Components +(RSC). Components render HTML on the server, then components that need JavaScript are +enhanced after hydration. + +Read the [server-side rendering guide](/docs/server-side-rendering.md) for the required +NHS.UK frontend styles, browser feature detection, React Server Component imports and +progressive enhancement checks. + ## Development To run this project locally, set up Yarn using [Node.js corepack](https://github.com/nodejs/corepack#readme) diff --git a/docs/server-side-rendering.md b/docs/server-side-rendering.md new file mode 100644 index 00000000..a30f774b --- /dev/null +++ b/docs/server-side-rendering.md @@ -0,0 +1,146 @@ +# Server-side rendering + +Version 6.0.0 and later of `nhsuk-react-components` support server-side rendering (SSR) +and React Server Components (RSC). + +The components render HTML on the server. Components that need JavaScript preserve their +[`'use client'` boundaries](https://react.dev/reference/rsc/use-client) and load the +matching NHS.UK frontend module after hydration. You do not need to opt the components +out of SSR. + +SSR helps deliver usable HTML before JavaScript loads, but it does not guarantee +progressive enhancement by itself. Make sure users can still access content and complete +their task when JavaScript is unavailable. + +## Load NHS.UK frontend styles + +The styles are provided by the `nhsuk-frontend` peer dependency. Install it alongside +`nhsuk-react-components` if it is not already a dependency: + +```bash +npm install nhsuk-frontend +``` + +Load the NHS.UK frontend styles once in your application layout. You can serve the +precompiled stylesheet from: + +```text +node_modules/nhsuk-frontend/dist/nhsuk/nhsuk-frontend.min.css +``` + +and reference it in your page: + +```html + +``` + +Alternatively, include NHS.UK frontend in your Sass entry point: + +```scss +@forward 'nhsuk-frontend/dist/nhsuk'; +``` + +See the NHS.UK frontend guidance for [other CSS and asset setup +options](https://github.com/nhsuk/nhsuk-frontend/blob/main/docs/installation/installing-with-npm.md). + +## Add browser feature detection + +Add the NHS.UK frontend feature-detection script at the start of the ``, before the +rendered page content: + +```html + + + + +``` + +In a JSX layout, set `suppressHydrationWarning` on the `` because the script changes +its class before React hydrates the page: + +```jsx +{children} +``` + +## Render components on the server + +Use the components normally in a route or page that your React framework renders on the +server: + +```jsx +import { Button, Form, TextInput } from 'nhsuk-react-components'; + +export default function SignInPage() { + return ( +
+ + + + ); +} +``` + +JavaScript-enhanced components initialise their own NHS.UK frontend module after +hydration. Do not also call `initAll()` for components rendered by this package, because +that would initialise them twice. If the page also contains non-React NHS.UK markup, +scope its initialisation to a container that does not include components rendered by +this package. + +If you manage rendering without a framework, use [React's server rendering and hydration +APIs](https://react.dev/reference/react-dom/server). React recommends streaming APIs such +as `renderToPipeableStream` for Node.js and `renderToReadableStream` for web streams. + +## Use React Server Components + +The package preserves client boundaries for interactive components, so compatible RSC +frameworks can import them from Server Components. A component marked with `'use client'` +can still be pre-rendered to HTML on the server and hydrated in the browser. + +For multipart components, prefer the named child exports instead of dot notation across +an RSC boundary: + +```jsx +import { Breadcrumb, BreadcrumbItem } from 'nhsuk-react-components'; + +export default function PageBreadcrumb() { + return ( + + Home + NHS services + + ); +} +``` + +RSC bundlers may not preserve dynamically assigned properties such as `Breadcrumb.Item`. +Named exports avoid that multipart namespace limitation. If you need to pass event +handlers or other non-serialisable props, create a local Client Component wrapper for +that usage. + +## Avoid hydration mismatches + +The server and client must produce the same initial markup. + +- Pass stable `id` or `idPrefix` props where the component provides them. Form controls + can use `name` as a fallback, but explicit identifiers make the rendered markup easier + to reason about. +- Do not calculate initial props from browser-only state during rendering. +- Do not use random values or the current time in initial component content. +- Check the browser console for hydration warnings in a production build. + +## Check progressive enhancement + +Before releasing an SSR implementation: + +1. Inspect the server response or page source and confirm the component HTML is present. +2. Disable JavaScript and confirm users can still access content and complete the task. +3. Enable JavaScript and confirm enhanced components work without hydration warnings. +4. Run your framework's production build and test the server-rendered route. + +Read [how NHS.UK frontend supports different +browsers](https://github.com/nhsuk/nhsuk-frontend/blob/main/docs/contributing/browser-support.md) +for more about its baseline HTML and CSS experience. diff --git a/stories/Guides/ServerSideRendering.mdx b/stories/Guides/ServerSideRendering.mdx new file mode 100644 index 00000000..b24555ba --- /dev/null +++ b/stories/Guides/ServerSideRendering.mdx @@ -0,0 +1,7 @@ +import { Markdown, Meta } from '@storybook/addon-docs/blocks'; + +import Docs from '../../docs/server-side-rendering.md?raw'; + + + +{Docs} From 25b142768c2eed8c26bea7db1db4342754c89d6d Mon Sep 17 00:00:00 2001 From: Ayobami Haastrup <47716486+AyobamiH@users.noreply.github.com> Date: Fri, 28 Aug 2026 04:06:34 -0700 Subject: [PATCH 2/3] Fix repository-relative SSR guide link --- README.md | 97 +++++++++++++++++++++++-------------------------------- 1 file changed, 40 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index d7ad9668..78eb0ead 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,48 @@ -# NHS.UK React components +# NHS.UK React Components -This repository contains the code for NHS.UK React components - a port of the [NHS.UK frontend components](https://github.com/nhsuk/nhsuk-frontend). +[![CI](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/main.yml/badge.svg)](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/main.yml) +[![Known Vulnerabilities](https://snyk.io/test/github/NHSDigital/nhsuk-react-components/badge.svg?targetFile=package.json)](https://snyk.io/test/github/NHSDigital/nhsuk-react-components?targetFile=package.json) +[![npm](https://img.shields.io/npm/v/nhsuk-react-components)](https://www.npmjs.com/package/nhsuk-react-components) -[![GitHub Actions CI Status](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/NHSDigital/nhsuk-react-components/actions?query=workflow%3A%22CI+Build%22+branch%3Amain) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/nhsuk-react-components.svg)](https://bundlephobia.com/result?p=nhsuk-react-components) +A React component library based on the [NHS.UK frontend library](https://github.com/nhsuk/nhsuk-frontend). -## Documentation and examples +## Installation -[View documentation and examples](https://nhsdigital.github.io/nhsuk-react-components) +Install from npm: -## Install package +```bash +npm install nhsuk-react-components +``` -You can install this package into your service using either `npm` or `yarn`. +or using Yarn: ```bash -npm install --save nhsuk-react-components - -# Or yarn add nhsuk-react-components ``` ## Usage -```jsx +Import the components you need: + +```tsx import { Button, DateInput, Form } from 'nhsuk-react-components'; -
- - - - - - - -
; +const Example = () => ( +
+ + + + + + + +
+); ``` ## Server-side rendering @@ -47,7 +51,7 @@ Version 6.0.0 and later support server-side rendering (SSR) and React Server Com (RSC). Components render HTML on the server, then components that need JavaScript are enhanced after hydration. -Read the [server-side rendering guide](/docs/server-side-rendering.md) for the required +Read the [server-side rendering guide](docs/server-side-rendering.md) for the required NHS.UK frontend styles, browser feature detection, React Server Component imports and progressive enhancement checks. @@ -69,43 +73,22 @@ Then run the following: yarn build --watch ``` -2. **Open documentation and examples** +2. **Run Storybook** ```bash yarn storybook ``` -## Upgrading - -- [Upgrading to 1.0](/docs/upgrade-to-1.0.md) -- [Upgrading to 2.0](/docs/upgrade-to-2.0.md) -- [Upgrading to 3.0](/docs/upgrade-to-3.0.md) -- [Upgrading to 4.0](/docs/upgrade-to-4.0.md) -- [Upgrading to 5.0](/docs/upgrade-to-5.0.md) -- [Upgrading to 6.0](/docs/upgrade-to-6.0.md) - -## Maintainers +3. **Run tests** -**We’re currently looking for new maintainers** If you have knowledge of React and would be willing to help maintain this library, you can [email me (Thomas Judd-Cooper)](mailto:thomas.judd-cooper1@nhs.net). - -- Thomas Judd-Cooper ([GitHub](https://github.com/tomdango)) -- Sam Brown ([GitHub](https://github.com/samueldavidbrown)) -- Luke Pearson ([GitHub](https://github.com/lukepearson)) -- Kevin Kuszyk ([GitHub](https://github.com/kevinkuszyk)) -- Kai Spencer ([GitHub](https://github.com/KaiSpencer)) -- Ed Horsford ([GitHub](https://github.com/edwardhorsford)) - -## Preparing releases - -Releases run in CI using github actions. - -To prepare a release create a new release TAG in github with your release version. + ```bash + yarn test + ``` -- Create a new release with a tag like `major.minor.patch` against main. -- If the change is a `beta` then select `pre-release` as true, this will make the `tag` point at `beta`. Otherwise the tag will be `latest`. +## Contributing -## Thanks +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidance. -Chromatic +## License -Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions. +This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. From 66fc09d80622afea0202c5ba75e77ae85e496355 Mon Sep 17 00:00:00 2001 From: Ayobami Haastrup <47716486+AyobamiH@users.noreply.github.com> Date: Fri, 28 Aug 2026 08:15:10 -0700 Subject: [PATCH 3/3] Restore focused SSR documentation scope --- README.md | 95 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 78eb0ead..aaa813fb 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,44 @@ -# NHS.UK React Components +# NHS.UK React components -[![CI](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/main.yml/badge.svg)](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/main.yml) -[![Known Vulnerabilities](https://snyk.io/test/github/NHSDigital/nhsuk-react-components/badge.svg?targetFile=package.json)](https://snyk.io/test/github/NHSDigital/nhsuk-react-components?targetFile=package.json) -[![npm](https://img.shields.io/npm/v/nhsuk-react-components)](https://www.npmjs.com/package/nhsuk-react-components) +This repository contains the code for NHS.UK React components - a port of the [NHS.UK frontend components](https://github.com/nhsuk/nhsuk-frontend). -A React component library based on the [NHS.UK frontend library](https://github.com/nhsuk/nhsuk-frontend). +[![GitHub Actions CI Status](https://github.com/NHSDigital/nhsuk-react-components/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/NHSDigital/nhsuk-react-components/actions?query=workflow%3A%22CI+Build%22+branch%3Amain) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/nhsuk-react-components.svg)](https://bundlephobia.com/result?p=nhsuk-react-components) -## Installation +## Documentation and examples -Install from npm: +[View documentation and examples](https://nhsdigital.github.io/nhsuk-react-components) -```bash -npm install nhsuk-react-components -``` +## Install package -or using Yarn: +You can install this package into your service using either `npm` or `yarn`. ```bash +npm install --save nhsuk-react-components + +# Or yarn add nhsuk-react-components ``` ## Usage -Import the components you need: - -```tsx +```jsx import { Button, DateInput, Form } from 'nhsuk-react-components'; -const Example = () => ( -
- - - - - - - -
-); +
+ + + + + + + +
; ``` ## Server-side rendering @@ -73,22 +69,43 @@ Then run the following: yarn build --watch ``` -2. **Run Storybook** +2. **Open documentation and examples** ```bash yarn storybook ``` -3. **Run tests** +## Upgrading - ```bash - yarn test - ``` +- [Upgrading to 1.0](/docs/upgrade-to-1.0.md) +- [Upgrading to 2.0](/docs/upgrade-to-2.0.md) +- [Upgrading to 3.0](/docs/upgrade-to-3.0.md) +- [Upgrading to 4.0](/docs/upgrade-to-4.0.md) +- [Upgrading to 5.0](/docs/upgrade-to-5.0.md) +- [Upgrading to 6.0](/docs/upgrade-to-6.0.md) + +## Maintainers + +**We’re currently looking for new maintainers** If you have knowledge of React and would be willing to help maintain this library, you can [email me (Thomas Judd-Cooper)](mailto:thomas.judd-cooper1@nhs.net). + +- Thomas Judd-Cooper ([GitHub](https://github.com/tomdango)) +- Sam Brown ([GitHub](https://github.com/samueldavidbrown)) +- Luke Pearson ([GitHub](https://github.com/lukepearson)) +- Kevin Kuszyk ([GitHub](https://github.com/kevinkuszyk)) +- Kai Spencer ([GitHub](https://github.com/KaiSpencer)) +- Ed Horsford ([GitHub](https://github.com/edwardhorsford)) + +## Preparing releases + +Releases run in CI using github actions. + +To prepare a release create a new release TAG in github with your release version. -## Contributing +- Create a new release with a tag like `major.minor.patch` against main. +- If the change is a `beta` then select `pre-release` as true, this will make the `tag` point at `beta`. Otherwise the tag will be `latest`. -Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidance. +## Thanks -## License +Chromatic -This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. +Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions.