@defra/docusaurus-theme-govuk 0.0.2-alpha → 0.0.4-alpha

package/README.md

@@ -13,12 +13,22 @@ A Docusaurus 3 theme that applies the [GOV.UK Design System](https://design-syst
 - Bundled GDS Transport fonts and GOV.UK static assets
 - Compatible with React 18 and React 19
 
+
 ## Installation
 
 ```bash
 npm install docusaurus-theme-govuk
 ```
 
+### Consumer responsibilities
+
+- Install all required peer dependencies (see `peerDependencies` in the package).
+- Use the theme in your Docusaurus config as shown below.
+- Ensure your project uses compatible versions of Docusaurus and React.
+- Configure navigation and sidebar via `themeConfig.govuk.navigation`.
+
+No additional setup is required beyond standard Docusaurus theme usage.
+
 ## Configuration
 
 Update your `docusaurus.config.js` (or `.cjs`):

package/index.js

@@ -1,14 +1,21 @@
 const path = require('path');
-const webpack = require('webpack');
-const CopyPlugin = require('copy-webpack-plugin');
+const fs = require('fs');
 
 module.exports = function themeGovuk(context, options) {
+  const siteDir = context.siteDir;
+
+  // Resolve webpack and plugins from the consumer's node_modules.
+  // Top-level require() would fail when installed via file: (symlink) because
+  // the theme directory has no local node_modules in that case.
+  const webpack = require(require.resolve('webpack', { paths: [siteDir] }));
+  const CopyPlugin = require(require.resolve('copy-webpack-plugin', { paths: [siteDir] }));
+
   const themePath = path.resolve(__dirname, './src/theme');
   const shimPath = path.resolve(__dirname, './src/lib/react-foundry-router-shim.js');
 
-  // Resolve govuk-frontend assets directory from this package's dependencies
+  // Resolve govuk-frontend assets directory from the consumer's node_modules
   const govukFrontendAssetsPath = path.dirname(
-    require.resolve('govuk-frontend/package.json')
+    require.resolve('govuk-frontend/package.json', { paths: [siteDir] })
   );
 
   // The base URL for this Docusaurus site (e.g. '/interactive-map/')
@@ -33,31 +40,71 @@ module.exports = function themeGovuk(context, options) {
     },
 
     configureWebpack(config, isServer, utils) {
-      // Resolve React from the consumer (siteDir) to avoid dual-instance issues.
-      // The theme ships its own node_modules/react via `file:` linking,
-      // so we must force all React imports to the consumer's single copy.
-      const siteDir = context.siteDir;
-
       // Helper: resolve a package from the consumer's siteDir.
       // Uses require.resolve with paths so it follows Node's resolution
       // (handles hoisted AND nested node_modules like @docusaurus/core/node_modules/react-router-dom).
+      // Also handles ESM-only packages (e.g. @mdx-js/react) that don't export ./package.json.
+      // Find the directory of an installed package by walking node_modules up
+      // the filesystem from each search path. Uses only fs.existsSync — no
+      // require.resolve — so it works even for ESM-only packages (e.g.
+      // @mdx-js/react) where jiti's require.resolve shim fails at runtime.
+      // Falls back to __dirname so that packages installed in the theme's own
+      // node_modules are found when consuming via file: (local dev).
+      function findPkgDir(pkg, searchPaths) {
+        const allSearchPaths = [...searchPaths, __dirname];
+        for (const startDir of allSearchPaths) {
+          let dir = startDir;
+          while (true) {
+            const candidate = path.join(dir, 'node_modules', pkg);
+            if (fs.existsSync(path.join(candidate, 'package.json'))) {
+              return candidate;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir) break; // filesystem root
+            dir = parent;
+          }
+        }
+        throw new Error(
+          `Could not find package "${pkg}" from [${allSearchPaths.join(', ')}]`
+        );
+      }
       function resolveFromSite(pkg) {
         try {
-          return path.dirname(
-            require.resolve(`${pkg}/package.json`, { paths: [siteDir] })
-          );
+          return findPkgDir(pkg, [siteDir]);
         } catch {
-          // Fallback: try resolving from @docusaurus/core (where react-router is nested in 3.9.x)
-          const docuCorePath = path.dirname(
-            require.resolve('@docusaurus/core/package.json', { paths: [siteDir] })
-          );
-          return path.dirname(
-            require.resolve(`${pkg}/package.json`, { paths: [docuCorePath] })
-          );
+          // Fallback: try resolving from @docusaurus/core's location (where
+          // react-router may be nested in Docusaurus 3.9.x).
+          const docuCoreDir = findPkgDir('@docusaurus/core', [siteDir]);
+          return findPkgDir(pkg, [docuCoreDir]);
         }
       }
 
+      // Resolve the CJS entry point of a package without going through jiti.
+      // Reads the package's own package.json `main` field (CJS) rather than
+      // using require.resolve which jiti may fail on.
+      function findPkgEntry(pkg) {
+        const pkgDir = findPkgDir(pkg, [siteDir]);
+        const pkgJson = JSON.parse(
+          fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')
+        );
+        const main = pkgJson.main || 'index.js';
+        return path.resolve(pkgDir, main);
+      }
+
+      // Use MiniCssExtractPlugin for production/server builds, style-loader for dev/client
+      let MiniCssExtractPlugin;
+      if (!isServer && process.env.NODE_ENV === 'production') {
+        MiniCssExtractPlugin = require('mini-css-extract-plugin');
+        if (!config.plugins) config.plugins = [];
+        config.plugins.push(new MiniCssExtractPlugin({ filename: 'assets/css/govuk-theme.[contenthash].css' }));
+      }
       return {
+        // Also resolve webpack loaders from the theme's own node_modules.
+        // When consumed via file: (local dev), loaders like style-loader,
+        // css-loader etc. live in the theme dir, not the consumer's node_modules.
+        resolveLoader: {
+          modules: ['node_modules', path.resolve(__dirname, 'node_modules')],
+        },
         resolve: {
           extensions: ['.mjs', '.js', '.jsx', '.json', '.scss'],
           fullySpecified: false,
@@ -102,15 +149,15 @@ module.exports = function themeGovuk(context, options) {
           // which fail under webpack's fullySpecified enforcement for .mjs files.
           new webpack.NormalModuleReplacementPlugin(
             /^@react-foundry\/component-helpers$/,
-            require.resolve('@react-foundry/component-helpers')
+            findPkgEntry('@react-foundry/component-helpers')
           ),
           new webpack.NormalModuleReplacementPlugin(
             /^@react-foundry\/client-component-helpers$/,
-            require.resolve('@react-foundry/client-component-helpers')
+            findPkgEntry('@react-foundry/client-component-helpers')
           ),
           new webpack.NormalModuleReplacementPlugin(
             /^@react-foundry\/uri$/,
-            require.resolve('@react-foundry/uri')
+            findPkgEntry('@react-foundry/uri')
           ),
           // Resolve asset paths from @not-govuk packages to govuk-frontend
           new webpack.NormalModuleReplacementPlugin(
@@ -159,10 +206,22 @@ module.exports = function themeGovuk(context, options) {
                 fullySpecified: false,
               },
             },
+            {
+              // Force .docusaurus generated files (registry.js, routes.js etc.)
+              // to javascript/auto so that webpack's require.resolveWeak() magic
+              // transforms work.  Without this, a consumer with "type":"module"
+              // in their package.json causes webpack to treat these files as pure
+              // ESM, leaving require.resolveWeak() untransformed in the browser
+              // bundle, which throws "require is not defined" at runtime.
+              test: /\.docusaurus[/\\][^/\\]+\.js$/,
+              type: 'javascript/auto',
+            },
             {
               test: /\.scss$/,
               use: [
-                'style-loader',
+                (!isServer && process.env.NODE_ENV === 'production')
+                  ? require('mini-css-extract-plugin').loader
+                  : 'style-loader',
                 {
                   loader: 'css-loader',
                   options: {
@@ -183,11 +242,7 @@ module.exports = function themeGovuk(context, options) {
                 {
                   loader: 'sass-loader',
                   options: {
-                    implementation: require('sass'),
-                    // Override GOV.UK asset path to include the Docusaurus baseUrl.
-                    // The default '../../assets/' produces URLs without baseUrl,
-                    // causing 404s when baseUrl is not '/'.
-                    // Only prepend for SCSS/Sass files — plain CSS can't use Sass variables.
+                    implementation: require(require.resolve('sass', { paths: [siteDir] })),
                     additionalData: (content, loaderContext) => {
                       if (/\.scss$|\.sass$/.test(loaderContext.resourcePath)) {
                         return `$govuk-assets-path: '${baseUrl}assets/';\n` + content;
@@ -196,6 +251,7 @@ module.exports = function themeGovuk(context, options) {
                     },
                     sassOptions: {
                       includePaths: [
+                        path.join(siteDir, 'node_modules'),
                         path.resolve(__dirname, 'node_modules'),
                       ],
                       quietDeps: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.2-alpha",
+  "version": "0.0.4-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",
@@ -23,7 +23,8 @@
   "peerDependencies": {
     "@docusaurus/core": "^3.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "webpack": "^5.0.0"
   },
   "dependencies": {
     "@mdx-js/react": "^3.0.0",
@@ -40,5 +41,8 @@
   },
   "engines": {
     "node": ">=18.0"
+  },
+  "devDependencies": {
+    "mini-css-extract-plugin": "^2.10.0"
   }
 }

package/src/lib/react-foundry-router-shim.js

@@ -43,13 +43,9 @@ export const useIsActive = () => {
 
   return (href, exact = true) => {
     const target = URI.parse(href, location.pathname);
-    const dir = target.pathname.endsWith('/') ? target.pathname : target.pathname + '/';
-    // Root path '/' should only match exactly, not as a prefix for all paths
-    const pathStart = target.pathname === '' || (target.pathname !== '/' && location.pathname.startsWith(dir));
-    const pathMatch = target.pathname === '' || location.pathname === target.pathname;
+    const pathMatch = location.pathname === target.pathname;
     const queryMatch = includes(location.query, target.query);
-    const activeExact = !!(pathMatch && queryMatch);
-    return exact ? activeExact : !!(activeExact || (pathStart && queryMatch));
+    return pathMatch && queryMatch;
   };
 };
 

package/src/theme/Layout/index.js

@@ -1,4 +1,5 @@
 import React from 'react';
+import '../../css/theme.scss';
 import {SkipLink, Header, Footer, PhaseBanner, ServiceNavigation, NavigationMenu} from '@not-govuk/simple-components';
 import {useLocation} from '@docusaurus/router';
 import Head from '@docusaurus/Head';