<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Could React be an alternative to Nunjucks for GOV.UK services? I built a prototype to find out.]]></title><description><![CDATA[I built a GOV.UK-style prototype to see if React could work as an alternative to Nunjucks. Pages are server rendered and work without JavaScript.]]></description><link>https://alexbuzea.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Fri, 20 Nov 2026 17:16:27 GMT</lastBuildDate><atom:link href="https://alexbuzea.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Could React be an alternative to Nunjucks for GOV.UK services? I built a prototype to find out.]]></title><description><![CDATA[I built a GOV.UK-style prototype to see if React could work as an alternative to Nunjucks. Pages are server rendered and work without JavaScript.]]></description><link>https://alexbuzea.hashnode.dev/could-react-be-an-alternative-to-nunjucks-for-gov-uk-services-i-built-a-prototype-to-find-out</link><guid isPermaLink="true">https://alexbuzea.hashnode.dev/could-react-be-an-alternative-to-nunjucks-for-gov-uk-services-i-built-a-prototype-to-find-out</guid><category><![CDATA[React]]></category><category><![CDATA[progressive web apps]]></category><category><![CDATA[gov.uk]]></category><dc:creator><![CDATA[Alex Buzea]]></dc:creator><pubDate>Fri, 13 Nov 2026 16:04:43 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/23026a7f-be3a-43c6-885c-26216bb9b578.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>I've been wondering whether React could work as an alternative to Nunjucks for building <a href="http://GOV.UK">GOV.UK</a> services. I'm not saying it should, I just wanted to know if it could meet the requirements <a href="http://GOV.UK">GOV.UK</a> sets for services, progressive enhancement in particular, so I built a small prototype to test it. This is what I learned, including the parts that aren't so great (see Figure 1).</p>
<p>You can try the <a href="https://react-progressive-enhancement-prototype.onrender.com/">live demo</a> yourself. Turn JavaScript off and it still works. The code is on <a href="https://github.com/AlexBuzea/govuk-react-progressive-enhancement-prototype">GitHub</a></p>
<img src="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/33feaf8f-f267-47f7-84f1-af898c9acc73.png" alt="" style="display:block;margin:0 auto" />

<blockquote>
<p><em>Figure 1: The prototype's start page, running on the live demo.</em></p>
</blockquote>
<h2>Why look at this at all?</h2>
<p>A lot of <a href="http://GOV.UK">GOV.UK</a> services run on Node with Nunjucks, and the <a href="http://GOV.UK">GOV.UK</a> Frontend macros are written for it. Nunjucks came from Mozilla, and the last npm release (3.2.4) was in April 2023. I'm not claiming it's abandoned, and it works fine today. But I think it's fair to ask what <a href="http://GOV.UK">GOV.UK</a> teams would do if a template engine they rely on went quiet for a long time, and whether React could be one answer.</p>
<h2>What progressive enhancement means</h2>
<p><a href="http://GOV.UK">GOV.UK</a> expects services to work for as many people as possible, so the core of a service should work with plain HTML and CSS. JavaScript is then layered on top to improve the experience, but nothing essential should depend on it. That might be because someone has JavaScript turned off, a script fails to load, or they're on a slow connection or an older device. It's also the reason a form should still submit and show its errors if the scripts never run.</p>
<p>The <a href="http://GOV.UK">GOV.UK</a> Service Manual explains this in more detail in its guidance on <a href="https://www.gov.uk/service-manual/technology/using-progressive-enhancement">using progressive enhancement</a>.</p>
<h2>A quick introduction to React</h2>
<p>React is a JavaScript library for building user interfaces out of components. A component is a small function that returns HTML-like markup, called JSX, and takes typed inputs called props. Components can be nested and reused, so a page is built up from small pieces.</p>
<p>Most people know React from single page apps, which use client-side rendering. The server sends an almost empty HTML page along with a bundle of JavaScript. React then builds the page in the browser, and every interaction updates it from there without a full page reload.</p>
<p>That works well for highly interactive apps, but it has a cost. The page ships a lot of JavaScript, and there's very little to see until it has all downloaded and run. If the JavaScript fails to load or is turned off, there's no page at all. That isn't a good fit for a service that has to work for everyone, including people on a slow connection or an older device. If that were the only way to use React, this article would be a lot shorter.</p>
<h2>React can render on the server too</h2>
<p>React has several APIs for rendering on the server, and you can find the full list in the <a href="https://react.dev/reference/react-dom/server">React documentation</a>. The oldest is <code>renderToString</code>, which has been around for years. It builds the whole page as one HTML string and only sends it once everything is ready. React 18 came out in March 2022 and added <code>renderToPipeableStream</code>, which is built for Node.</p>
<p>I chose <code>renderToPipeableStream</code> for two reasons. First, it can stream the HTML. Streaming means the server starts sending the page to the browser in chunks as they're ready, rather than waiting until the whole page has been built, so the browser can begin showing it sooner. Second, it's what React recommends for Node, and its docs point Node users towards it rather than <code>renderToString</code>.</p>
<p>To be fair, my prototype doesn't use Suspense yet, so it isn't really taking advantage of streaming in pieces. Streaming content in later relies on a small inline script, so I'd want to think carefully about how that behaves with JavaScript off.</p>
<pre><code class="language-tsx">export function render(res, page, status = 200) {
  const { pipe } = renderToPipeableStream(&lt;Document&gt;{page}&lt;/Document&gt;, {
    onShellReady() {
      res.statusCode = status;
      res.setHeader("Content-Type", "text/html; charset=utf-8");
      pipe(res);
    },
  });
}
</code></pre>
<p>That's a shortened version of the real thing with the error handling taken out. A route then just calls <code>render(res, &lt;HelpPage /&gt;)</code>.</p>
<h2>Node and Nunjucks, or Node and React?</h2>
<p>The usual setup is a Node server with routes, form posts, validation on the server and redirects, rendering a Nunjucks template. The React version keeps all of that. Only the rendering step changes, so instead of a template the route renders a component. If you already know Node and Express, the structure will feel very familiar.</p>
<p>Here's the server side of the name and address form. The first handler shows the page. The second validates the posted answers and either renders the page again with the errors and what the user typed, or redirects on to the next page:</p>
<pre><code class="language-tsx">export const saveDetails = (req, res) =&gt; {
  const details = {
    fullName: text(req.body.fullName),
    addressLine1: text(req.body.addressLine1),
    /* ...the other fields */
  };
  const errors = validateDetails(details);

  if (Object.keys(errors).length &gt; 0) {
    render(res, &lt;DetailsPage details={details} errors={errors} /&gt;);
    return;
  }
  res.redirect(303, "/customise");
};
</code></pre>
<p>That's a simplified version of the real handler (I've left out the session and CSRF handling). If you've written a Nunjucks form handler before, the only line that looks different is the <code>render</code> call.</p>
<p>I did look at Next.js and React Server Components too, but I didn't go that way, for two reasons. The first is that Next.js sends its own runtime and React to the browser on every page, even when the content was rendered on the server, so each page ships some JavaScript. The browser needs that code to hydrate the page and to handle navigation between pages. Plain Node lets a page send none of React at all. The second is that <a href="http://GOV.UK">GOV.UK</a> teams already know Node and Express, so there's less to learn.</p>
<p>I'm not the first to try React for <a href="http://GOV.UK">GOV.UK</a>. I briefly looked at <a href="https://github.com/govuk-react/govuk-react">govuk-react</a> and <a href="https://github.com/daniel-ac-martin/NotGovUK">NotGovUK</a>, and this prototype takes a different approach. govuk-react is a component library that rebuilds the <a href="http://GOV.UK">GOV.UK</a> styles with styled-components. NotGovUK is a framework that renders pages on the server, and then the whole app hydrates in the browser, so the React code for the app is sent with every page. This prototype is different because it is server-side rendering first. Every page is complete HTML from the server and works without any JavaScript. Most pages send no React at all, and React only runs in the browser for the few components that need it. It isn't a framework or a component library, just a small experiment in how far that approach goes.</p>
<h2>The same field written both ways</h2>
<p>Here's a text input as a Nunjucks macro, then the React component from my prototype. I wrote the Nunjucks one just for this comparison, it isn't part of the app.</p>
<p><strong>Nunjucks (</strong><a href="http://GOV.UK"><strong>GOV.UK</strong></a> <strong>Frontend macro)</strong></p>
<pre><code class="language-jinja">{{ govukInput({
  label: { text: "Full name" },
  id: "fullName",
  name: "fullName",
  autocomplete: "name",
  value: details.fullName,
  errorMessage: errors.fullName and { text: errors.fullName }
}) }}
</code></pre>
<p><strong>React</strong></p>
<pre><code class="language-tsx">&lt;GovukInput
  name="fullName"
  label="Full name"
  autoComplete="name"
  defaultValue={details.fullName}
  error={errors.fullName}
/&gt;
</code></pre>
<p>They look pretty similar, which is part of the appeal for me. I named the React components after the Nunjucks macros (<code>govukInput</code> becomes <code>GovukInput</code>, <code>govukRadios</code> becomes <code>GovukRadios</code> and so on), so anyone who knows <a href="http://GOV.UK">GOV.UK</a> Frontend can tell straight away what each one is. The difference is what sits behind them.</p>
<p>Every React component declares the props it accepts as a TypeScript type. This is the real one for <code>GovukInput</code>:</p>
<pre><code class="language-tsx">type GovukInputProps = InputHTMLAttributes&lt;HTMLInputElement&gt; &amp; {
  name: string;      // required
  label: string;     // required
  hint?: string;     // optional
  error?: string;    // optional
  hidden?: boolean;  // optional
};
</code></pre>
<p>A prop without a question mark is required, and one with a question mark is optional. The component also accepts any normal HTML input attribute, such as <code>autoComplete</code>. If someone leaves out <code>label</code>, or misspells it as <code>lable</code>, TypeScript flags it in the editor and in the project's type check, before the page is ever run (see Figure 2). In a Nunjucks macro the same mistake simply renders with the label missing.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/10352b3b-4aa2-45c2-926f-4a9262991e42.png" alt="" style="display:block;margin:0 auto" />

<blockquote>
<p><em>Figure 2: TypeScript flags a misspelled or missing prop in the editor, before the page is run.</em></p>
</blockquote>
<p>The Nunjucks macros are maintained for you by the Design System team, whereas my React components are only a proof of concept. But there's no reason they couldn't be built out properly as a shared npm library, which is the same model the macros use today.</p>
<h2>Islands: React only where it's needed</h2>
<p>Most pages in the prototype are server only. The server renders the HTML, the form posts as normal and no React is sent to the browser. They do still load the standard <a href="http://GOV.UK">GOV.UK</a> Frontend scripts, which any service needs, Nunjucks ones included. Those do things like moving focus to the error summary so screen readers announce it (see Figure 3).</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/fbcfc1de-57e4-4c63-a11f-a249426df2bb.png" alt="" style="display:block;margin:0 auto" />

<blockquote>
<p><em>Figure 3: On a server only page, the only scripts are the standard</em> <a href="http://GOV.UK"><em>GOV.UK</em></a> <em>Frontend ones. No React is loaded.</em></p>
</blockquote>
<p>For the few places where a bit of interactivity helps, I used the islands pattern. The server still renders the whole page, interactive part included. Then a small script attaches React to that one component, which is what hydrating means. The rest of the page stays as plain HTML. With JavaScript off, the hydration never happens and the component just works as an ordinary form (see Figure 4).</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/6f337753-63ab-4ebc-91a4-1c367f748691.png" alt="" style="display:block;margin:0 auto" />

<blockquote>
<p><em>Figure 4: How a page is built. The server always sends complete HTML. With JavaScript off the island works as a normal form, and with it on React hydrates just that component.</em></p>
</blockquote>
<p>The page marks the island and passes its props across as text:</p>
<pre><code class="language-tsx">&lt;div id="customise" data-props={JSON.stringify(formProps)}&gt;
  &lt;CustomiseForm {...formProps} /&gt;
&lt;/div&gt;
&lt;script type="module" src="/islands/customise.js" /&gt;
</code></pre>
<p>The island's entry file is only a few lines:</p>
<pre><code class="language-tsx">import { hydrateRoot } from "react-dom/client";
import { CustomiseForm } from "../pages/customise/CustomiseForm";

const root = document.getElementById("customise");
if (root) {
  const props = JSON.parse(root.dataset.props ?? "{}");
  hydrateRoot(root, &lt;CustomiseForm {...props} /&gt;);
}
</code></pre>
<p>Vite handles the bundling. Every file in the islands folder becomes its own script, and React goes into one shared chunk that only gets downloaded once. Adding a new island means adding a file, with no build config to change.</p>
<p>As for the numbers, server only pages send no React. An island page loads about 70 kB of shared React (gzipped) plus 0.7 to 2.5 kB for the island itself, on top of the <a href="http://GOV.UK">GOV.UK</a> Frontend scripts (see Figure 5).</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aef47588da294b398e03c58/00d7a66b-0d7d-4e9d-adee-161552daacf6.png" alt="" style="display:block;margin:0 auto" />

<blockquote>
<p><em>Figure 5: On an island page, customise.js and chunks/react.js load on top of the</em> <a href="http://GOV.UK"><em>GOV.UK</em></a> <em>Frontend scripts.</em></p>
</blockquote>
<h2>One form, with and without JavaScript</h2>
<p>The smallest example I have is a counter. It's a normal HTML form that posts to the server:</p>
<pre><code class="language-tsx">async function onSubmit(event) {
  event.preventDefault();   // stop the post and page reload
  setCount(count + 1);      // update the page straight away
  await fetch("/apply/increment", { method: "POST", /* same fields */ });
}

&lt;form method="post" action="/apply/increment" onSubmit={onSubmit}&gt;
</code></pre>
<p>With JavaScript off, the browser posts the form and the page reloads. With it on, <code>preventDefault()</code> stops that, React updates the number straight away and the same request saves it in the background. Either way the count is saved on the server (see Figure 6).</p>
<p><a class="embed-card" href="https://youtu.be/rjhprvGvAhg">https://youtu.be/rjhprvGvAhg</a></p>

<blockquote>
<p><em>Figure 6: With JavaScript off the page reloads on every click. With it on, the number updates straight away and the page doesn't reload.</em></p>
</blockquote>
<h2>A more realistic example</h2>
<p>The permit options form also works as a plain HTML form. With JavaScript on, errors appear instantly, the price updates as you pick options and a zone list filters as you type. The same validation code runs on the server and in the browser, so the two can't disagree.</p>
<p>One detail worth knowing: the server and the first browser render have to produce identical HTML or hydration complains. So a flag starts as <code>false</code> and only becomes <code>true</code> once React has started in the browser:</p>
<pre><code class="language-tsx">const [jsEnabled, setJsEnabled] = useState(false);
useEffect(() =&gt; setJsEnabled(true), []);

{!jsEnabled ? (
  &lt;GovukButton type="submit" formMethod="get" formAction="/customise"&gt;
    Filter zones
  &lt;/GovukButton&gt;
) : null}
</code></pre>
<p>With JavaScript off the flag never changes, so people get a "Filter zones" button that reloads the page with the filter applied. With JavaScript on the button goes away because the list filters as you type (see Figures 7 and 8).</p>
<p><a class="embed-card" href="https://youtu.be/HILgIsqBu0M">https://youtu.be/HILgIsqBu0M</a></p>

<blockquote>
<p><em>Figure 7: With JavaScript on, the price updates, the zone list filters as you type and errors appear before the form is sent.</em></p>
</blockquote>
<p><a class="embed-card" href="https://youtu.be/6PQmZWWTYb0">https://youtu.be/6PQmZWWTYb0</a></p>

<blockquote>
<p><em>Figure 8: With JavaScript off, the Filter zones button reloads the page and errors come from the server.</em></p>
</blockquote>
<h2>What I like and what's left to explore</h2>
<p>The things I found appealing:</p>
<ul>
<li>Types, so mistakes show up when you build rather than in front of users.</li>
<li>Small components with markup that looks a lot like HTML.</li>
<li>React is one of the most widely used libraries: 42% of developers said they had used it in the <a href="https://survey.stackoverflow.co/2026/technology/data/web-framework">2026 Stack Overflow Developer Survey</a>. That means there are plenty of experienced developers, which should help with onboarding.</li>
<li>Components can be tested, including automated accessibility checks with axe.</li>
<li>The components could be published as an npm library and maintained in one place by a team, working the same way the Nunjucks macros do today, with reusable components that every service picks up by installing a package.</li>
<li>Tools like Storybook would let developers and designers browse every component and every state (errors, hints, disabled and so on) and test them by hand without having to run a whole service.</li>
</ul>
<p>Still to explore:</p>
<ul>
<li>The <a href="http://GOV.UK">GOV.UK</a> components in my prototype are a proof of concept. A real library would be a bigger piece of work, with a team keeping it in step with new <a href="http://GOV.UK">GOV.UK</a> Frontend releases.</li>
<li>Designers used to the Prototype Kit may want some support with JSX at first, which something like Storybook could help with.</li>
<li>It's a prototype, so answers are held in memory and I haven't tested it with real assistive technology.</li>
</ul>
<h2>Where that leaves me</h2>
<p>The prototype shows that React can be used as a server side template engine on a familiar Node setup. Every page is rendered to complete HTML on the server using <code>renderToPipeableStream</code>, forms post and validate there, and the whole journey works with JavaScript turned off. Browser tests run the journey with JavaScript off, and check the options page again with its island scripts blocked or broken, so the version without JavaScript is checked rather than assumed. Most pages send no React at all, and the few that do only hydrate a single component. On the pages with an island, the same validation rules run on the server and in the browser, so the two versions can't disagree about what's valid.</p>
<p>React is only sent to the browser for the components where it adds something, such as instant validation, a live price and a filtered list. On those pages the cost is a shared React chunk of about 70 kB gzipped plus a small script for each island, loaded on top of the <a href="http://GOV.UK">GOV.UK</a> Frontend scripts every service already uses. Vite keeps that simple, because a new island is just a new file.</p>
<p>Alongside that come types, testing and reusable components, which could be shared as an npm library and reviewed in a tool like Storybook, much like the Nunjucks macros are shared today.</p>
<p>After looking further into whether anyone had used this approach as well, I found that The Guardian has. In a <a href="https://theguardian.engineering/blog/info-2022-mar-25-react-islands-on-theguardiancom.html">2022 engineering post</a> they describe using React islands on <a href="http://theguardian.com">theguardian.com</a>: instead of hydrating the whole page, they make only small, isolated sections interactive and leave the rest as server rendered HTML, so there is less JavaScript to download and run, especially on slower connections and less powerful devices. Their main goals were performance and maintainability rather than progressive enhancement, and they built their own implementation instead of using a framework, but the underlying pattern is the same one this prototype uses. It's reassuring to see it working at that scale, and their point that islands should be easy to add, so unused JavaScript doesn't creep back in, is something the islands folder here is meant to help with.</p>
<p>Try the <a href="https://react-progressive-enhancement-prototype.onrender.com/">live demo</a> with JavaScript on and off, and see the code on <a href="https://github.com/AlexBuzea/govuk-react-progressive-enhancement-prototype">GitHub</a></p>
<p>The demo runs on a free hosting plan that sleeps when it isn't used, so the first load can take up to a minute.</p>
<p>There's still more to explore. I haven't tested it with real assistive technology, built a full component library or tried keeping one in step with <a href="http://GOV.UK">GOV.UK</a> Frontend releases, and I haven't compared it against a larger service. But as a first look, React appears to be a workable option for building progressively enhanced <a href="http://GOV.UK">GOV.UK</a> services. If you work on them, I'd love to hear what you think.</p>
<p>You can find me on <a href="https://www.linkedin.com/in/alexbuzea/">LinkedIn</a>.</p>
]]></content:encoded></item></channel></rss>