core: Prerendering

Integrate prerendering of pages into the standard build process (i.e.
`pnpm build`) using vite-plugin-prerender.

The prerendered pages will be output to the dist/ directory by default.

NOTES

- On Apple devices using Apple Silicon it may be necessary to set the
  `PUPPETEER_EXECUTABLE_PATH` environment variable and use it to point
  to a working installation of a version of Chromium that is compatible
  with installed version of Puppeteer. The Puppeteer post-install
  scripts ought to install such a version of Chromium in ~/.cache. Use
  a .env.production.local file to do this.

LINKS

- https://github.com/Rudeus3Greyrat/vite-plugin-prerender
- https://github.com/puppeteer/puppeteer

README.md

@@ -38,7 +38,7 @@ Any environment variable whose name is prefixed with `VITE_` will be exposed to
 pnpm dev
 ```
 
-### Compile and Minify for Production
+### Compile, Minify and Prerender for Production
 
 ```sh
 pnpm build
@@ -117,3 +117,27 @@ pnpm spelling:fix
 - Commit message linting is provided by [commitlint](https://github.com/conventional-changelog/commitlint?tab=readme-ov-file). Messages should conform to the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) specification. See [.commitlintrc.yaml](.commitlintrc.yaml) for details.
 - Git branch name linting is provided by [branch-name-lint](https://github.com/barzik/branch-name-lint) (actually we use [a fork](https://github.com/al/branch-name-lint/tree/integration/error-handling-issues) that we currently maintain). See [.branch-name-lint.json](.branch-name-lint.json) for details.
 - [lint-staged](https://github.com/lint-staged/lint-staged) ensures that pre-commit checks (linting, formatting, and spell checking) are only run on staged files.
+
+## Troubleshooting
+
+### `pnpm build` hangs or Chromium segfaults during prerendering on OSX
+
+Page prerendering is provided by [vite-plugin-prerender](https://github.com/Rudeus3Greyrat/vite-plugin-prerender), which itself relies upon [puppeteer](https://github.com/puppeteer/puppeteer/).
+
+[puppeteer](https://github.com/puppeteer/puppeteer/) installs x86 versions of Chromium even when running on Apple Silicon/ARM64 chips.
+
+If necessary run:
+
+```sh
+pnpm node node_modules/puppeteer/install.mjs
+```
+
+This should install a suitable version of Chromium, under ~/.cache/puppeteer/chrome/ by default. Verify that it works by launching it, e.g.
+
+```sh
+open '~/.cache/puppeteer/chrome/mac_arm-126.0.6478.182/chrome-mac-arm64/Google Chrome for Testing.app'
+```
+
+To instruct the build process to use this version of Chromium (or some other one that you have installed manually), set the `PUPPETEER_EXECUTABLE_PATH` variable path.
+
+Use of an environment file is recommended. Remember that even when running locally, the build environment will most likely be set to `production`, so you should create/modify the .env.production.local file.

cspell.config.yaml

@@ -30,6 +30,10 @@ ignoreWords:
   - Mansalva
   - mktemp
   - predeploy
+  - Prerender
+  - prerender
+  - prerenderer
+  - prerendering
   - realpath
   - sublicensable
   - substr

package.json

@@ -3,9 +3,11 @@
     "@gtm-support/vue-gtm": "^3.0.1",
     "@headlessui/vue": "^1.7.22",
     "@heroicons/vue": "^2.1.3",
+    "@prerenderer/renderer-puppeteer": "^1.2.4",
     "@unhead/vue": "^1.9.14",
     "@vueuse/core": "^11.0.1",
     "dotenv-flow": "^4.1.0",
+    "puppeteer": "^22.14.0",
     "vue": "^3.4.38",
     "vue-router": "^4.4.2"
   },
@@ -43,6 +45,7 @@
     "stylelint-config-tailwindcss": "^0.0.7",
     "tailwindcss": "^3.4.9",
     "vite": "^5.4.2",
+    "vite-plugin-prerender": "^1.0.8",
     "vite-plugin-vue-devtools": "^7.3.8",
     "vue-tsc": "^2.0.28"
   },