Skip to Content
jsshenanigans

How this site was made

The stack, the one library change it forced, and how it deploys.

This site is two things: documentation written with Fumadocs, and an editor that runs jss in the browser. It is hosted on GitHub Pages, so it is a static export — no server at all.

Stack

  • Next.js 16 with the App Router, output: 'export'.
  • Fumadocs (fumadocs-core, fumadocs-ui, fumadocs-mdx) for the docs, including its static search index.
  • Tailwind CSS 4.
  • The library itself, installed with file:.. so the site always tests the checkout it lives in.

Scaffolding

The app was generated with the official Fumadocs template, then trimmed:

npx create-fumadocs-app@latest docs \
  --template "+next+fuma-docs-mdx+static" \
  --pm npm --no-git --install

The +static template already produces an output: 'export' app with a static search route (staticGET), which is what makes GitHub Pages possible.

The library change this forced

The first time the editor imported jss, the build failed. src/codec.js began with import zlib from 'node:zlib', plus node:module and Buffer, so a browser bundle could not even load the module.

The fix was to make the codec isomorphic:

  • It no longer imports Node built-ins at the top level. node:zlib is reached through process.getBuiltinModule('node:zlib'), which simply fails in a browser and is caught.
  • Base64 and UTF-8 use Buffer when it exists and TextEncoder/btoa otherwise.
  • A new register_backend() lets an environment supply its own zstd.

In the browser, the site supplies one built on WebAssembly and registers it before anything is decoded:

const zstd = await import('@bokuweb/zstd-wasm');
await zstd.init(`${base}/zstd.wasm`);
jss.register_backend({
  name: 'zstd-wasm',
  compress: (bytes) => zstd.compress(bytes),
  decompress: (bytes) => zstd.decompress(bytes),
});

The .wasm file is copied into public/ at setup time, and init() is given a path that includes the Pages base path.

GitHub Pages details

The site is served from the custom domain jss.itzdanti.dev, so it has no base path:

  • docs/public/CNAME holds the domain, and a DNS CNAME record for jss points at dnd-ed.github.io.
  • Pages is set to deploy from GitHub Actions; the workflow uploads docs/out with actions/upload-pages-artifact and publishes it with actions/deploy-pages.
  • NEXT_PUBLIC_BASE_PATH still exists, so the same site can be hosted under a project path (/jsshenanigans) if the custom domain ever goes away.
  • trailingSlash: true and images: { unoptimized: true } keep the export Pages-friendly, and public/.nojekyll stops Pages from ignoring _next.

Running it locally

cd docs
npm install
npm run dev      # http://localhost:3000

npm run build writes the static site to docs/out, and npm start serves it.

On this page