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 --installThe +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:zlibis reached throughprocess.getBuiltinModule('node:zlib'), which simply fails in a browser and is caught. - Base64 and UTF-8 use
Bufferwhen it exists andTextEncoder/btoaotherwise. - 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/CNAMEholds the domain, and a DNSCNAMErecord forjsspoints atdnd-ed.github.io.- Pages is set to deploy from GitHub Actions; the workflow uploads
docs/outwithactions/upload-pages-artifactand publishes it withactions/deploy-pages. NEXT_PUBLIC_BASE_PATHstill exists, so the same site can be hosted under a project path (/jsshenanigans) if the custom domain ever goes away.trailingSlash: trueandimages: { unoptimized: true }keep the export Pages-friendly, andpublic/.nojekyllstops Pages from ignoring_next.
Running it locally
cd docs
npm install
npm run dev # http://localhost:3000npm run build writes the static site to docs/out, and npm start serves it.
