'npm' is not recognized as an internal or external command,
operable program or batch file.

Your command is fine. The machine is fine. Windows simply does not ship with Node.js, npm or Git.

This post starts from why the command fails and ends with a verified environment. No prior knowledge assumed.

1. Why commands can be typed at all​

When you type a word into a terminal, Windows walks through a list of directories called PATH, looking for a matching program:

← swipe horizontally to see the full diagram →

So "command not found" has exactly two causes:

1. The program is not installed
2. It is installed, but its directory is not on PATH

The installers for Node.js and Git add themselves to PATH by default — as long as you do not untick that option.

Background: what you type is usually a real file — .exe, .cmd or .ps1. npm is npm.cmd, and git is git.exe.

2. What to install​

Two are required, two are optional:

← swipe horizontally to see the full diagram →

Two version channels:

• LTS: long-term support, stable — pick this
• Current: newest features, newest bugs — not for a first setup

⚠️ Download only from the official links above. Third-party "green builds" or "all-in-one packs" can be modified, and the risk is not worth it for commands that touch your accounts.

3. Install Node.js​

3.1 Download​

Open nodejs.org/en/download, pick the LTS column, download Windows Installer (.msi) 64-bit.

3.2 Install​

Run the installer and click Next all the way through, pausing on one page:

← swipe horizontally to see the full diagram →

Click Finish.

3.3 Verify​

Close the old terminal and open a new one (PATH is read when a terminal starts, so an old window will not see the change).

node -v

Expected output, something like:

v20.11.1

Then npm:

npm -v

10.2.4

Different numbers are fine. Any version output means it works.

4. Install Git​

4.1 Download​

Open git-scm.com/download/win and download 64-bit Git for Windows Setup (not the Portable build).

4.2 Install​

Click Next through everything; only three pages are worth a look:

The editor page does not matter; you can change it later.

You also get Git Bash, a Unix-like terminal that is often friendlier for the commands in this series.

4.3 Set your identity​

Git needs to know who authored a commit. Right after installing, run:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

• Use the email tied to your GitHub account, otherwise commits will not count toward your contribution graph
• This is a one-time setup

Verify:

git config --global --list

5. Three commands to confirm the environment​

← swipe horizontally to see the full diagram →

node -v
npm -v
git --version

If all three print a version, you are done.

To see where a program actually lives, use where:

where node
where npm
where git

It prints the full path. If where finds nothing but the program is clearly installed, PATH is misconfigured — reinstalling with Add to PATH ticked is the quickest fix.

6. Run your first project​

A working toolchain is not the same as a working project. Clone a public repository to practise:

# 1. Pick a folder for code
cd D:\Projects

# 2. Clone
git clone https://github.com/LxHanesser/Connexion-Collective.git

# 3. Enter it
cd Connexion-Collective

# 4. Install dependencies (use ci when a lockfile exists)
npm ci

# 5. Start the dev server
npm run start

Open http://localhost:3000 and the site should be running.

npm ci versus npm install​

If you remember one rule: cloned project, use npm ci.

7. The second error everyone hits: npm.ps1​

Node is installed and node -v works, but npm throws a wall of red text:

← swipe horizontally to see the full diagram →

That is Windows script execution policy, not a broken Node install. One line fixes it:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Press Y, then reopen the terminal.

Much safer than setting Unrestricted.

If you would rather not change system settings, use Git Bash (installed with Git); it is not subject to this policy.

8. Common error table​

9. Final checklist​

10. Optional: multiple Node versions​

Some old projects need Node 16 while new ones want 20. nvm-windows handles that:

• Download: github.com/coreybutler/nvm-windows/releases

nvm install 20
nvm use 20
nvm list

⚠️ Uninstall any existing Node.js before installing nvm, otherwise both fight over PATH and versions get confusing.

You do not need this on day one. Get a single version working first.

Wrap-up​

The whole flow is five steps:

1. Install Node.js LTS (keep "Add to PATH")
2. Install Git for Windows (default branch: main)
3. Configure git user.name / user.email
4. Reopen the terminal, run node -v / npm -v / git --version
5. Clone a project, npm ci, npm run start

Most of the time is not spent clicking Next. It is spent on the command still not being found after installing, or npm printing a wall of red. Nine times out of ten that comes down to three things: PATH not applied, terminal not restarted, script execution policy.

Remember those three and Windows will rarely block you again.

Next step​

Once the toolchain works, continue with Deploying Docusaurus to Cloudflare Pages — build settings, caching and security headers, and a go-live checklist that puts this environment to work.

This post walks the whole path, and ends with a checklist you can run through line by line.

← swipe horizontally to see the full diagram →

The build runs on Cloudflare's machines. You need neither a server nor an upload of build/.

Why Pages​

For a static site there are plenty of options: Vercel, Netlify, GitHub Pages, object storage plus a CDN. Pages won on practical grounds:

That covers about 95% of what a static site needs.

1. Get it running locally first​

No toolchain yet? This post assumes node, npm and git already work in your terminal. If they do not, start with First steps on a new PC: installing Node.js, npm and Git on Windows — it goes from why PATH matters to a verified setup, then come back.

New project:

npx create-docusaurus@latest my-site classic
cd my-site
npm run start      # dev server with hot reload
npm run build      # production build
npm run serve      # preview the build output

Skip this step if you already have a project. The important part: make npm run build pass with zero errors locally. Debugging a failure on CI is far worse than debugging it on your own machine.

Docusaurus 3 requires Node ≥ 18; in practice, use 20 or newer.

2. Get three fields right in docusaurus.config.js​

const config = {
  title: 'Connexion Collective',
  url: 'https://connexioncollective.com',  // no trailing slash
  baseUrl: '/',                            // root deployment means /
  trailingSlash: undefined,                // see below
  // ...
};

These three decide every generated URL:

trailingSlash has three values:

• undefined: follow the URL as written (default, least surprising)
• true: always /blog/post/
• false: always /blog/post

Changing it later rebuilds every URL on the site, so decide up front.

3. Repo and build command​

Three things belong in the repo: package.json, package-lock.json, and source. build/ and node_modules/ go in .gitignore.

On CI, use npm ci rather than npm install:

npm ci          # exact lockfile install, reproducible
npm run build   # output lands in build/

The upside of npm ci is determinism: what you installed locally is what CI installs. The cost is that package-lock.json must match package.json, otherwise it fails — which is actually a feature, because it catches a stale lockfile before it reaches production.

Once the build passes, look at what actually lands in build/ — everything later in this post revolves around that directory:

← swipe horizontally to see the full diagram →

The _headers file and 404.html in that tree are the main characters of the second half.

4. Create the Pages project​

4.1 Connect the repo​

Cloudflare Dashboard → Workers & Pages → Create → Pages → Connect to Git
→ pick the repo → pick the branch (main)

Three build settings:

The output directory is build — not public, not dist. Get this wrong and the build succeeds while deploying an empty site.

4.2 Pin the Node version​

Add an environment variable in the project settings:

NODE_VERSION = 20

Without it, the builder uses whatever default it has. When Docusaurus bumps its engine requirement, the build starts failing in ways that are hard to trace. This is the single most overlooked failure mode.

And: never put secrets here. The build needs Node and dependencies. A token in the build environment is a supply-chain backdoor.

4.3 First deploy​

Push to main and the build starts. A few minutes later you get a xxx.pages.dev URL.

Click through the whole site on that temporary URL first, then attach the custom domain. That way, if something breaks later, you know whether it is a build problem or a domain problem.

5. Attach a custom domain​

Project → Custom domains → Set up a custom domain

If the domain lives in the same Cloudflare account, the correct DNS record is created for you. Otherwise add a CNAME pointing at your-project.pages.dev.

After that, the pages.dev URL still works and is still public. If you do not want it indexed, block it in robots.txt or put Cloudflare Access in front of it.

6. Three things to configure after deploying​

6.1 _headers: caching and security headers​

Pages reads a _headers file at the root of the output directory. In a Docusaurus project, put it at static/_headers so the build copies it to build/.

/*
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: geolocation=(), microphone=(), camera=()

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/img/*
  Cache-Control: public, max-age=3600, must-revalidate

← swipe horizontally to see the full diagram →

HTML and hashed assets must be treated differently; that split is the whole point.

Why the split:

• HTML changes. Caching it for a year means visitors never see new posts.
• /assets/* carries a content hash in the filename, so a change produces a new name — safe to mark immutable.

A common trap: if _headers sits in the wrong place (repo root instead of static/), Pages does not complain. It just silently does nothing. Verify by building locally and checking that build/_headers exists.

6.2 Security headers and CSP​

Beyond the basics, a CSP has to match what the site actually loads. A real example:

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://static.cloudflareinsights.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://cdn.example.com; connect-src 'self' https://cloudflareinsights.com; frame-src https://giscus.app; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'

frame-ancestors only works inside CSP; setting it anywhere else does nothing.

6.3 404 and sitemap​

Docusaurus emits build/404.html, and Pages serves it for unknown paths while keeping status 404. That is correct behaviour.

But the sitemap may include /404 unless you exclude it:

sitemap: {
  ignorePatterns: ['/404', '/en/404'],   // exclude both locales
},

7. The eight pitfalls I actually hit​

1. Absolute local paths end up in the bundle​

Docusaurus serialises siteConfig into the client JS, and themes/plugins are absolute paths:

D:\Projects\my-website\node_modules\@easyops-cn\docusaurus-search-local

Harmless functionally, but it publishes your directory layout. Fix it in a postBuild hook:

// plugins/postBuildCleanup.cjs
function postBuild(context) {
  const siteDir = context.siteDir;
  const escaped = JSON.stringify(siteDir).slice(1, -1); // escaped backslashes on Windows

  for (const file of walk(context.outDir)) {
    if (!/\.(html|js|json)$/.test(file)) continue;
    let text = fs.readFileSync(file, 'utf8');
    text = text.split(escaped).join('/site');
    text = text.split(siteDir).join('/site');
    fs.writeFileSync(file, text);
  }
}

Verify by grepping build/ for your username or drive letter.

2. Cloudflare refuses prefetch and you get a pile of 503s​

This one is genuinely confusing. The console shows a dozen 503s for /assets/js/*.js, yet the same URL returns 200 via curl.

The cause is Cloudflare Speed Brain, which intercepts every Sec-Purpose: prefetch request. The response says so:

cf-speculation-refused: prefetch refused: not eligible

Docusaurus's Link component uses an IntersectionObserver, so every link entering the viewport prefetches its route chunk — meaning every page load produces a dozen refused requests.

Two ways out:

1. Turn Speed Brain off (zone → Speed → Optimization). Docusaurus chunk prefetch starts working again, and for an SPA that is the prefetch that actually matters.
2. Disable prefetch in the front end: intercept the window.docusaurus assignment and replace prefetch with a no-op.

I chose the first, because Speed Brain prefetches HTML documents while SPA navigation never requests a document. It was pure overhead plus console noise.

3. Checking production with curl gives you 403 and false conclusions​

Cloudflare serves a challenge page (roughly 5 KB of HTML, status 403 or 503) to suspicious automated requests.

If you scrape the page with curl at that moment, you conclude "the page does not contain X" — while the content is fine and you were simply handed a challenge.

How to tell: check the response length and content-type; challenge pages are 5–6 KB and contain Just a moment. For real verification, use a browser — or accept that you cannot verify from this network right now.

4. Values in _headers do not match what arrives​

You write X-Frame-Options: DENY, production shows SAMEORIGIN.

Cloudflare edge rules (Transform Rules, Managed Rules) override origin headers. _headers is a declaration; the edge has the final say.

Order of investigation: read the response headers, then the Cloudflare Rules, and only then suspect _headers.

5. Old Node version fails the build during install​

The log shows Unsupported engine or a syntax error in a dependency. Set NODE_VERSION.

6. npm install versus npm ci​

They differ in how strictly they treat the lockfile. If package-lock.json lags behind package.json, npm ci fails outright.

Habit: run npm ci && npm run build locally before pushing, matching CI.

7. Preview deployments quietly consume build quota​

Every push to a non-main branch triggers a preview build. For a personal site this rarely matters, but with many branches it can approach the 500/month limit.

You can restrict previews to specific branches, or only build on pull requests.

8. Changing trailingSlash breaks existing links​

The generated directory layout changes (/blog/post vs /blog/post/), so external links, bookmarks and search results all point at the old form.

If you must change it, add a fallback in _redirects:

/blog/:slug/  /blog/:slug  301

8. Go-live checklist​

Run through this after the first successful deploy:

9. Cost and limits​

A personal site will not come close. The only two things to watch are build count (many branches, frequent pushes) and file size (do not commit video).

Wrap-up​

The whole thing compresses to five steps:

1. Local `npm run build` passes
2. Connect the repo: build command `npm run build`, output `build`
3. Set NODE_VERSION, attach the custom domain
4. Write `static/_headers` (cache + security)
5. Walk the checklist

The time sink is not "how do I deploy". It is how do I confirm the deployment is correct: does caching work, were the headers overridden, did anything leak into the output, what are those red entries in the console actually saying.

That part is what makes a static site solid.

• The list page offers one “older entries” link — no page count, no sense of position
• Prev/next links at the bottom of a post show titles only, no dates, no place in the timeline

List page: numbers are easy, “current page” is not​

The paginator receives metadata that includes totalPages, so drawing the numbers is trivial.

The awkward part is working out the current page. My first attempt used metadata.page + 1, which produced:

• Page 1 rendering as “Page 2 of 2”
• Page 2 rendering as “Page 3 of 2”

So the field is 1-based, not 0-based as I assumed. Rather than guess, derive it from the URL:

const match = pathname.match(/\/page\/(\d+)\/?$/);
const current = match ? Number(match[1]) : 1;

/blog/page/2 → 2, /blog → 1, and /en/blog/page/2 works the same way.

The base path is derived too, from nextPage / previousPage, so neither language prefix has to be hard-coded:

const base = sample.replace(/\/page\/\d+\/?$/, '');

Post page: it needs an index of every post​

The prev/next props only carry {permalink, title}. Dates and a “Post N of M” position require knowing about all posts.

useBlogMetadata() does not work on post pages — it reads route data that is not there and throws.

The solution was a 30-line build-time plugin:

// plugins/blogPostIndex.cjs
async loadContent() {
  // read blog/*.md frontmatter → slug / title / date, sorted newest first
  return {posts};
},
async contentLoaded({content, actions}) {
  actions.setGlobalData(content);
}

The client reads it with usePluginData('blog-post-index'). The payload is 2.8 KB and costs no runtime request.

Two API details​

1. @docusaurus/useGlobalData is a default export. Writing import {useGlobalData} does not fail at build time — it explodes during rendering with useGlobalData is not a function, which is exactly the SSG failure I hit.
2. Data written by setGlobalData is keyed by globalData[pluginName][pluginId], so usePluginData('blog-post-index') is the reliable accessor.

Matching the two languages​

The index stores slugs while pages expose permalinks. The relationship is simple: /blog/<slug> in Chinese, /en/blog/<slug> in English — the last segment is identical.

const slugOf = (permalink) => String(permalink).split('/').filter(Boolean).pop();

Matching on that gives “第 N / M 篇” on the Chinese page and Post N of M on the English one, with the same position in both.

Visuals​

• Prev/next became cards: direction label, title, date
• Two columns on desktop, stacked on phones
• align-items: stretch keeps them equal height (both measured 132px)
• Page buttons are 44px on phones; arrows grey out at the ends

Verification​

Takeaway​

When the built-in paginator lacks information, there are two levers: change the data source (a build-time plugin) or change the rendering (override the component). This used both — the plugin supplies data, the component redraws the UI.

While in there I also removed the “Edit this page” / “Edit this post” links from docs and blog pages. That entry point is for authors; visitors clicking it only reach GitHub’s editor.

I assumed my own changes had broken the navbar. Reading the framework source showed otherwise: this is Docusaurus’s design.

The reason is in the source​

The mobile sidebar has two columns:

• Column one: navbar items (Start here, Blog, Tools, …)
• Column two: the contextual menu for the current page (docs sidebar / blog post list)

The logic that decides which column opens lives in navbarSecondaryMenu/display.js:

// When the sidebar closes, mark secondary as shown so it reopens first
useEffect(() => {
  if (!hasContent) { setShown(false); return; }
  if (!mobileSidebar.shown) { setShown(true); }
}, [mobileSidebar.shown, hasContent]);

In other words: whenever the current page has secondary content, the next open always shows that column first. On docs and blog pages the first column is pushed off-screen, reachable only via “← Back to main menu”.

Three options​

I took the third.

Implementation​

Override Navbar/MobileSidebar/SecondaryMenu. The original is 36 lines — a back button plus the contextual content — so we insert one row between them:

<>
  <SecondaryMenuBackButton onClick={() => secondaryMenu.hide()} />

  <nav className="mobile-quicknav">
    <Link to="/">Home</Link>
    <Link to="/blog">Blog</Link>
    <Link to="/tools">Tools</Link>
  </nav>

  {secondaryMenu.content}
</>

The CSS is thin: a three-column grid, min-height: 44px, 8px gaps, and hover styles guarded by @media (hover: hover) because :hover sticks on touch devices.

Verification​

• All three entries are 44px tall at 375px
• Tapping “Blog” navigates to /blog and closes the menu
• The docs navigation stays below the quick links, and the back button remains
• The same row appears on blog pages, where column two is the post list
• Desktop is untouched (the mobile sidebar does not render above 997px)

One nice detail: Link is locale-aware, so the English site goes to /en/blog without any manual prefix.

Takeaway​

When framework behaviour looks like a bug, fighting it is usually the expensive option. Adding a thin layer on top of its structure is cheap, survives upgrades, and does not damage accessibility.

I chose the latter, and the reason is verifiability.

The problem with seals​

A typical seal widget is three lines of HTML:

<div id="cc-myssl-id">
  <a href="https://myssl.com/your-domain?from=mysslid">
    <img src="https://static.myssl.com/res/images/myssl-id3.png">
  </a>
</div>

It looks official, but the image is generic: the same PNG for everyone, with no proof that the domain belongs to you. The only real information is behind the link — the live report it opens.

The costs are concrete:

For a site aiming at zero external requests, none of that is worth it.

Self-hosted badges, linked to reports​

The alternative is plain HTML/CSS pills, each pointing at an authoritative report:

Every number can be checked on the spot by a third party, instead of resting on an image anyone can paste.

Rule: never claim what you have not verified​

A few things had to be stated honestly:

1. SSL Labs really is A+ — all four edge endpoints. So the badge says A+.
2. Security Headers is A, not A+ — so it says A. The grade is capped by a warning about 'unsafe-inline' in the CSP, which cannot be removed (the edge injects a per-request inline script; blocking it can break the challenge flow). That is an architectural limit, not a misconfiguration.
3. HSTS says HSTS, not Preload. The response header carries the preload directive, but the domain is not on the browser preload list. Claiming “HSTS Preload” would be false.
4. DNSSEC only got a tick after two public resolvers both returned AD=true.

Two traps​

Trap one: a light footer plus white borders equals invisible.

I wrote rgba(255,255,255,0.22) borders out of habit, assuming a dark footer. The real background is rgb(248,250,252) — the badges were nearly invisible. They now have separate palettes for light and dark themes.

Trap two: the theme’s .footer a rule uses !important.

The badge text kept rendering in the theme green. The cause was a rule in the site CSS:

.footer a { color: #2e8555 !important; }

!important beats specificity, so the only fix is a more specific selector such as .footer .footer-badge.

The little orange cloud​

An “Hosted on Cloudflare” badge sounds easy until you look at the logo: the official mark is the cloud plus the wordmark, far too wide for a pill.

So I loaded the official SVG in a browser, used getBBox() on each path, and found the cloud is three of the four paths spanning x 54.9–103.1 / y 3.6–25.4. Those three paths became an 808-byte SVG whose viewBox is cropped to the cloud itself.

• The paths are untouched (cropped, not redrawn), which satisfies the “do not modify the mark” rule
• It is a same-origin file, so no external request
• The white path reads as a highlight against the dark footer

Legally this is nominative use: the mark identifies which service the site runs on, it does not imply partnership or endorsement, and clicking it goes back to their site.

Mobile​

Five badges wrap into 2+2+1 on a phone, leaving the last one stranded. A two-column grid plus grid-column: 1 / -1 on the hosting badge gives a tidy 2×2 with a full-width row underneath.

Heights are 32px on desktop and 44px on phones, so they are actually tappable.

The annoying part: you cannot see this on a desktop browser.

Step one: turn "overflow" into a number​

document.documentElement.scrollWidth - document.documentElement.clientWidth

A 320 viewport produced a scrollWidth of 400 — 80px, not an optical illusion.

Step two: find what is wider than the viewport​

Walk every element and look for a right edge past the viewport. The first suspect was the navbar's sidebar backdrop:

DIV.navbar-sidebar__backdrop   w=400

Nearly fooled me. It is position: fixed, so it does not take part in document flow and cannot create scrollbars — it just happened to be 400px wide and matched my filter.

Excluding fixed elements revealed the real shape of the problem: <main> was 400px wide while its parent was 320.

Step three: bisect​

If <main> is being stretched, find what stretches it. Crude but effective: hide each child in turn and see whether scrollWidth drops back to 320.

for (const kid of node.children) {
  kid.style.display = 'none';
  const fixedNow = document.documentElement.scrollWidth <= vw;
  kid.style.display = '';
  if (fixedNow) return kid;   // found it
}

First level hit: the file-list <ul>. Inside, every <li> was 400px wide — because of one monospace path:

data/my_pack/function/main.mcfunction

Root cause: the default min-width​

This is a classic flex-layout trap:

• A flex item's min-width defaults to auto, meaning it will not shrink below its min-content
• For white-space: nowrap text, min-content is the full line width
• So a 37-character monospace path pushed the entire chain to 400px

I assumed min-width: 0 on the containers would fix it. It did not: min-width: 0 allows shrinking, but a flex container still consults its children's content size when computing its own minimum.

The actual fix is to let the content wrap:

.itemName {
  white-space: normal;
  word-break: break-all;
}

break-all allows breaks between any characters — a path has no spaces, so normal wrapping finds no break opportunity. After that, 320 and 375 both went to zero.

The touch target found in the same pass​

The same sweep measured tappable heights and found the copy buttons in result lists were only 32px tall.

Project rules require at least 44×44. The bug was scope: min-height had been set for <a> in that row but not for <button>:

.itemActions button { min-width: 44px; min-height: 44px; }

The embarrassing part: my test scripts lied twice​

I drove the browser through CDP scripts to simulate user actions, and got two false results — neither of which was the app's fault:

First: I selected the page-range field with input[type=text]. That field has no type attribute (text is the default), and CSS attribute selectors do not match elements missing the attribute — so it grabbed the navbar search box instead. I typed the page range into site search.

Second: earlier in the project I decided whether an iframe was blocked by listening for iframe.onload. A blocked iframe also fires onload (with an error document), which led to exactly the opposite conclusion.

The lesson is plain: test scripts are code and they are wrong sometimes. When a result disagrees with expectations, suspect the test before the thing under test.

A breakpoint trade-off​

The tool switcher at the top of each tool page turns into a horizontally scrolling strip on narrow screens. Fourteen tools already need two swipes; more would be unusable.

So it now splits by breakpoint:

• ≥768px: horizontal chips, one tap to any tool
• ≤767px: a native <select> with optgroups — no horizontal scrolling, one-handed, still fine at fifty tools

Native controls have a quiet advantage on mobile: the OS handles touch, scrolling and accessibility for you, which is more reliable than a hand-rolled dropdown.

Takeaway​

Mobile bugs have two properties: invisible on desktop, and not judgeable by eye. So convert them into numbers — how many pixels of overflow, how tall is the target — then bisect.

And verify your verifier.

It can. PDF is a structured container format; pages can be copied into a new document without ever rendering them. But a few limits need stating up front, or users hit a wall exactly when it matters.

The library​

pdf-lib: pure JavaScript, no WASM, no native code. It does not render — it reads and writes PDF object structures, which is exactly what merging and splitting need.

It ships as its own 412 KB chunk and is only fetched when you open the PDF tool, so the rest of the site is unaffected.

Merging: move pages into a new document​

const out = await PDFDocument.create();
for (const bytes of sources) {
  const doc = await PDFDocument.load(bytes);
  const pages = await out.copyPages(doc, doc.getPageIndices());
  pages.forEach((page) => out.addPage(page));
}
const result = await out.save();

The key is copyPages: it copies page objects — content streams, resource dictionaries, font references — into the target document.

That means no quality loss: nothing is re-rendered, nothing is recompressed, vectors stay vectors. It also means the output roughly equals the sum of the inputs; merging does not magically shrink or inflate anything.

Splitting: copy a range​

The page box accepts 1-3,5,8-10, with commas, spaces or full-width commas. The parser is short:

for (const part of text.split(/[,，\s]+/)) {
  const m = part.match(/^(\d+)(?:[-–](\d+))?$/);
  // validate 1 <= start <= end <= pageCount
}

Out-of-range input errors out instead of quietly returning an empty document — that failure mode is the hardest to debug.

"Every page as its own file" does not fire N download prompts; it produces a single ZIP, reusing the hand-written store-mode packer described in the ICO/ZIP post, so no extra dependency for one download.

Three explicit limits​

1. Encrypted PDFs fail​

PDFDocument.load() throws on password-protected documents. The tool says so plainly — "this PDF is password-protected and cannot be processed" — rather than producing a blank file.

That is deliberate: silent failure is worse than an error.

2. Everything lives in memory​

There is no streaming. The file is read fully into an ArrayBuffer and the output is generated fully before download. Dozens of pages are fine; a several-hundred-page image-heavy album will crawl, or stall a mobile browser.

The current policy is neither a hard limit nor a pretence: it is slow, and you can see it is slow. Handling genuinely large files would need chunking plus a Worker, which multiplies the complexity.

3. Digital signatures break​

A PDF signature covers the whole document's bytes. Any modification — including appending one page — invalidates it. That is the format's design, not a defect of the tool.

Likewise, form fields (AcroForm) may not survive page copying, because field definitions are document-level rather than page-level. Supporting them properly needs dedicated field-merging logic.

How it is verified​

Nobody runs regression tests for a small client-side tool, so you build samples yourself:

1. Generate test files with pdf-lib (2 pages + 1 page)
2. Upload, merge and download in the browser
3. Read the result back in Node and assert 3 pages
4. Split with range 2 and assert 1 page

That loop is far more trustworthy than "I clicked it and nothing looked broken". It also did surface a problem on the first run — though that turned out to be my test script selecting the wrong input, not the tool itself (a different story).

Where this fits​

A client-side PDF tool should be positioned as handling everyday documents of a few dozen pages, not as a desktop replacement.

Writing "what it cannot do" on the page is more honest than shipping an implementation that falls over.

That does not work. A mosaic enlarges pixel blocks while keeping tens of thousands of colours, so you get a low-resolution photo, not pixel art. Real pixel art has two hard constraints: how many cells, and how many colours.

Step one: hard downsampling​

ctx.imageSmoothingEnabled = false;
ctx.drawImage(bitmap, 0, 0, targetWidth, targetHeight);

Turning smoothing off is the whole trick. With smoothing you get averaging and soft edges; without it you get nearest-neighbour sampling — each target pixel takes exactly one source pixel, so edges stay hard.

Target widths run 16–128. 32–64 suits avatars; 16 suits tiny icons.

Step two: extract a palette from the image​

This is the interesting part. We want to recolour with at most N colours — where do those N come from?

Median cut, briefly​

Put every opaque pixel in one box, then repeat:

1. Find the box with the largest colour spread (compare the range of R, G and B, take the widest channel)
2. Split that box at the median along that channel
3. Stop when the number of boxes equals the target colour count

Average the pixels in each box and you have the palette.

Why this works well here:

• Deterministic: the same input always yields the same palette, so refreshing never changes the result
• No iteration: unlike k-means, there is no convergence loop
• Proportional by construction: large flat areas get split repeatedly, while detail-dense regions end up with fewer representatives — which matches how the eye weights large areas

Why not k-means​

k-means usually produces slightly better palettes, but it is random initialisation plus iteration: the same image can give different palettes on two runs, and users read that as a broken tool.

For a tool where the output is instantly visible, stability beats a 5% quality gain.

Step three: map pixels​

With the palette fixed, replace each pixel with the nearest colour in Euclidean distance:

const d = (r1-r2)**2 + (g1-g2)**2 + (b1-b2)**2;

Brute force over the palette is fine. 128×128 is 16,384 pixels, at most 32 palette entries, so about 520,000 distance computations — milliseconds in a browser, no spatial index needed.

Pixels with alpha below 16 are skipped and stay transparent; otherwise transparent regions get filled with black.

Fixed palettes​

Two classic palettes are offered alongside the automatic one:

• PICO-8 (16 colours): the fantasy console's palette, high saturation, good for game assets
• Game Boy (4 colours): that green-tinted greyscale, extremely stylised

Choosing a fixed palette skips the median cut and maps straight to it. The upside is a consistent look across a set of assets; the downside is that source colours get dragged — a warm photo under the Game Boy palette turns into an alarming field of green.

Export: integer scaling​

Pixel art must be enlarged, but never smoothly:

ctx.imageSmoothingEnabled = false;
ctx.drawImage(small, 0, 0, w * scale, h * scale);

Export offers 1× / 2× / 4× / 8× / 16×. 8× is the sweet spot: a 48px-wide image becomes 384px, ready for sharing.

Numbers from testing​

• A 48px-wide image takes under 10 ms from downsampling to palette mapping
• The number of colours actually used is often below the target, because some boxes average to the same colour
• On gradient-heavy images (a sky photo), median cut gives most boxes to the gradient and leaves only a few for the subject. Those images do better with a contrast adjustment first

The point​

The technical content is not a clever algorithm. It is enforcing two constraints: a fixed grid and a fixed colour count. Honour both and the result reads as pixel art; the palette choice is only style after that.

An 800-byte icon can spend more than 500 bytes on metadata nobody asked for. But cleaning it up requires knowing which bytes are junk and which are load-bearing.

Safe to delete​

Remove those and the rendered pixels do not change at all.

Never touch​

• id and every reference to it: <use href="#a">, url(#grad), clip-path, filter, mask. Kill an id and you get a blank canvas.
• xlink:href: the legacy form of the same thing. Leave it alone.
• Anything inside <defs>: nothing renders directly, everything is a resource.
• The semantics of viewBox: precision can drop, proportions cannot change.

So the tool only removes things provably unrelated to rendering. It never rewrites path data — that is a different class of optimisation (curve fitting) with much higher risk.

A real bug: deleting attributes is not enough​

My first version stripped inkscape: / sodipodi: attributes with a regex and called it done. The output still contained a <sodipodi:namedview/> element — no children, but hundreds of bytes of attributes.

So two more rules went in: remove self-closing editor elements, then remove paired <sodipodi:xxx>…</sodipodi:xxx> blocks.

The lesson: when you regex XML, attributes and elements are different dimensions, and it is easy to only think of one.

Precision, and the cost of a global regex​

Cutting decimals from six places to two typically saves 10–20%. But running \d+\.\d+ across the whole file also hits things you did not mean to change, like version="1.1" becoming version="1".

That does not affect rendering, but it does change meaning. The safer approach is to only touch geometry attributes (d, cx, cy, r, x, y, width, height, transform), which requires parsing tags and roughly doubles the code.

I took the shortcut and exposed precision as a 0–4 setting so the user decides. That is a deliberate trade-off, not an oversight.

Worth knowing: at zero decimals circles become polygons and illustration edges go visibly angular. For icons, one or two places is plenty.

Measured result​

A 120×120 test icon with comments, metadata and a namedview:

before   853 B
after    285 B   (−67%)

Verification was not just "the file got smaller": the output still starts with <svg, keeps the xlink namespace, retains ids and references, and renders correctly in the preview.

When not to use this​

If the SVG embeds raster data (<image> with base64) or leans on lots of <text>, the savings are small and the risk of collateral damage is higher. Those files are better cleaned by hand than shoved through a tool.

The usual move is to install a library for each. But both formats are less complicated than their reputation suggests.

ICO: a six-byte header and a directory​

ICONDIR        6 bytes      reserved(2) + type(2, 1=icon) + count(2)
ICONDIRENTRY   16 bytes×N   width, height, palette, reserved, planes, depth, size, offset
payload                     one image per size

Since Vista, an ICO may embed PNG data directly, so the payload is just several PNGs concatenated — no BMP encoder needed.

Two details that bite:

• A 256 size is stored as 0. Width and height are one byte each, so 256 cannot fit; the spec uses 0.
• Offsets are from the start of the file, not from the payload. The first image sits at 6 + 16 × count.

Verification is straightforward: read the bytes back. The first four should be 00 00 01 00; then follow each directory entry's offset and expect the PNG signature 89 50 4E 47. Four sizes, four signatures — if they line up, the directory arithmetic is right.

ZIP: two structures, really​

A full ZIP implementation is a lot (deflate, data descriptors, ZIP64). In store mode only it is three pieces:

local header + data   (one per file)
central directory     (one record per file)
EOCD                  (where the directory is, and how many entries)

No compression, so no deflate; you just need correct CRC32, offsets and lengths.

The parts that matter:

• CRC32 is over the raw bytes, not the string length. Build the Uint8Array first, then checksum it.
• Name length is in bytes. Non-ASCII names are multi-byte in UTF-8, and you must set flag 0x0800 so the unzipper knows the encoding.
• Central directory offsets point at the local header, not at the data.
• The EOCD needs the directory's start offset and total size. One wrong byte and the archive is dead.

I verified the output with the OS unzipper: pack.mcmeta, the function file and the tag JSON all extract fine, which means the CRCs and offsets are correct.

What it costs​

The trade-off is no compression. For a datapack of a few kilobytes, store mode is plenty; for tens of megabytes of assets you want a real deflate implementation.

There is also no tolerance: no input validation, no ZIP64 (over 4 GB or 65,535 files). For "produce a download" that never matters.

What you get instead: zero dependencies, zero supply-chain surface, fully inspectable output. Both encoders together are under 200 lines — you can read them once and know exactly what they do, which is more reassuring than two more packages in node_modules.

Choosing: look at dependencies first​

The most popular package is qrcode, which is feature-complete but depends on pngjs, yargs, and dijkstrajs — far too heavy for "draw squares on a canvas".

The other option is qrcode-generator: zero dependencies, written by the author of the QR specification book, still maintained in 2025. It only computes the matrix and leaves rendering to me, which is exactly right.

Pitfall 1: the exports field blocks the way​

I wanted its UTF-8 variant and instinctively wrote:

import {stringToBytes} from 'qrcode-generator/dist/qrcode_UTF8.mjs';

The build failed immediately: Package subpath './dist/qrcode_UTF8.mjs' is not defined by "exports". The package's exports only allows importing from the root.

The fix turned out cleaner: import the root, then implement UTF-8 bytes myself:

import qrcode from 'qrcode-generator';
qrcode.stringToBytes = (s) => Array.from(new TextEncoder().encode(s));

TextEncoder is browser-native — cleaner than pulling in a variant file.

Pitfall 2: garbled Chinese​

Without overriding stringToBytes, the library treats each character as a single byte and Chinese comes out garbled. After the override, length is counted in UTF-8 bytes and the QR content matches the input.

One constraint to note: the longer the content, the denser the code, and exceeding capacity throws. The tool wraps it in try/catch and reports "content too long".

Rendering and export​

Once the matrix is available, draw it yourself:

const count = qr.getModuleCount();
const cell = Math.floor(size / (count + margin * 2));

Using an integer cell avoids half-pixel blur, and the margin is applied on all sides. Export is just canvas.toBlob('image/png') — no extra encoder needed.

Choosing an error-correction level​

L/M/Q/H: higher levels resist damage but get denser for the same content. M is enough for everyday use; go to Q or H for printed material that wears easily.

Lesson​

Small libraries' exports restrictions often block the way, but a few lines of native code usually get around them. When choosing a library, the dependency count matters more than the feature count.

1. Why no Pages Functions​

Functions solve plenty of problems (dynamic injection, auth), but they turn a pure static project into a project with a backend: a runtime, cold starts, and more code paths to maintain.

My rule of thumb: if it can be solved at build time or in the browser, never add a function. The footer day counter runs in the browser, the search index is generated at build time, image compression uses WASM — not a single function was written.

2. WASM MIME types and self-hosting​

WASM files live in static/wasm/ and are served as static assets. Browsers check the MIME type when using instantiateStreaming; Pages handles .wasm correctly, and if an environment does not, Emscripten falls back to loading via ArrayBuffer.

The key point is do not use a CDN: a third-party CDN adds a domain, a failure point, and another trust relationship.

3. Cache strategy follows whether the filename has a fingerprint​

There are only two cache rules in _headers:

• /assets/*: one year, immutable, because those filenames contain a content hash;
• /img/*: one week, since images rarely change.

HTML gets no long cache — Pages' default behaviour ensures a new deploy is visible immediately.

The security headers X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy stay in place.

4. Distinguish build warnings that matter​

After adding jSquash, the build gained a "circular dependency between chunks" warning. It looks alarming, but it only affects hash reuse between chunks, not the runtime. My approach: confirm the output works, note it, and do not restructure the architecture just to silence it.

5. Confirming a deploy actually happened​

Do not check the dashboard — check the output: note the main.[hash].js filename after building, then request the live page a minute after pushing. A changed hash means the new version is live. Last time it took a little over a minute from push to the CDN serving the new bundle.

Lesson​

The complexity of static hosting is not in the server but in "build output" and "caching". Get file fingerprints, cache headers, and size limits right, and let the platform handle the rest.

First, a reality check: Pages is not the bottleneck​

Plenty of people add a CDN because they are "afraid of exceeding the quota". So I did the arithmetic first:

The conclusion is blunt: 1.6% of the file limit, 2.2% of the per-file limit, 0.5% of the build budget. There is roughly thirty times the headroom left.

What actually breaks first is something else:

1. Repository size — binaries in git slow down clones, CI caches, and your disk.
2. Build time — Docusaurus gets slower with lots of image assets, and Pages caps a build at 20 minutes.
3. The 25 MiB per-file limit — only videos and uncompressed originals hit it, but when they do it is a hard failure.

So the honest reason is "repo and build", not "quota". That distinction matters: it means you only need to move the large files out, not the whole site.

The setup: public bucket plus custom domain, no Worker​

There are three ways to attach object storage to a static site:

I took the third. Objects live in an R2 bucket and are served directly from a dedicated cdn. subdomain — same Cloudflare account, certificate issued automatically, egress free.

The important part: no server is involved. Requests are handled at Cloudflare's edge; a cache hit returns immediately, a miss fetches once from R2. The site still ships nothing but build output.

The filename is the version​

Long cache lifetimes only work if "the same URL is always the same bytes". So the filename carries a content hash:

The upload script does very little: hash the file with SHA-256, take the first 12 characters, put them in the filename, set Content-Type and Cache-Control. Which makes this safe:

Cache-Control: public, max-age=31536000, immutable

The cost is explicit: changing an image means changing its URL. Overwriting an object to "update" a picture leaves the edge serving the old one — and that bug is genuinely painful to track down.

CORS does not stop hotlinking​

This was the main takeaway, and the easiest thing to get wrong.

In other words, CORS controls whether scripts may read the bytes — it has nothing to do with whether someone may display your image. Configuring CORS does not stop hotlinking, because <img> was never subject to it.

The only real defence is a Referer allowlist at the edge: accept references that come from this site's own domain, reject everything else.

There is a deliberate trade-off here — empty referers must be allowed. Opening an image URL directly, RSS readers, and privacy-focused browsers may all omit it, and blocking those would break legitimate visits.

A check like this stops people from casually borrowing your images; it will not stop anyone who deliberately crafts the request header, and it is not meant to. The point of a public bucket is to keep the cost bounded. Genuinely preventing it needs signed URLs, which needs a server — which exits this design entirely.

Ten minutes to configure, two hours to prove​

The configuration was the easy part. Proving it actually worked was not.

Trap one: curl always returned 403. After a while I realised it was not the hotlink rule at all — the whole zone runs bot verification, even the main site returns 403 to curl. That 403 carries cf-mitigated: challenge, which looks like a WAF block but is not.

Trap two: a headless browser is also classified as a bot, so it lands on the challenge page too.

Trap three is the fun one: my first hotlink test attached the forged Referer to the challenge platform's own requests, so the challenge could never complete and the page stayed stuck — it looked like "successfully blocked" while proving nothing.

The correct sequence is two steps: load the URL normally to clear the challenge, then issue a second, separate request carrying the Referer under test. Only then is a 403 definitely attributable to the WAF.

Final results:

Where things stand​

• Bucket, custom domain, CORS, cache rule, and hotlink protection are all configured and tested
• The site has real images for the first time — the ones you are looking at
• Source files live in media-src/ and never enter git; only URLs do
• Change an image, change the key. Never overwrite

One last honest note: if your site is a few megabytes with a handful of images, do not bother. Wait until the repository starts bloating and builds start slowing down — by then you will know exactly which problem you are solving.

Five measured problems​

There was also a hidden bug: the global .row .col:hover transform applied to footer columns, making whole columns jump on hover.

The plan: three columns​

• Left: brand (name, one-line tagline, three pill buttons for Subscribe / Surprise me / GitHub);
• Middle: site navigation;
• Right: more (tools, changelog, terms);
• Bottom: a divider and a single copyright line.

The home-made block was deleted and its information merged into the footer, leaving exactly one footer.

How it was implemented​

The theme's Footer component can be swizzled, but that means maintaining a copy across theme upgrades. I chose another path: build the brand area from the footer.links config using its html field, and rearrange with CSS, leaving theme source untouched.

Breakpoints follow where the content actually wraps: three columns get cramped below 840px, so at 996px it becomes "brand on one row, two nav columns below", and below 420px everything stacks.

Result​

At 1440px the footer container is left=143 width=1140, matching the content; at 900px the brand takes its own row with two nav columns side by side; at 375px it is a centered single column with 4.5rem of bottom padding to clear the back-to-top button.

Lesson​

"It doesn't look good" is the hardest requirement because it has no acceptance criteria. Break it into alignments, widths, whitespace, breakpoints, and overlaps — then there is a direction to change and a way to verify.

Attempt one: iframe plus virtual time — failed​

The idea was simple: a diagnostic page loading the site in a 375px-wide iframe, reading its scrollWidth. The screenshot always got stuck at "measuring..." — the iframe's async loading never finished before capture, and --virtual-time-budget did not save it.

Switching to CDP​

Instead, connect directly to the DevTools protocol: launch headless Edge with --remote-debugging-port, connect from Node over WebSocket, set Emulation.setDeviceMetricsOverride to 375×812 with deviceScaleFactor=2 and mobile=true, then run a check via Runtime.evaluate.

const de = document.documentElement;
const overflow = de.scrollWidth > de.clientWidth;

That number is trustworthy: as long as scrollWidth equals the viewport width, there is no horizontal scrolling.

What one check-up found​

Measuring six pages at 375px surfaced these problems:

• the homepage's three-column info block was still three columns on phones (col--4 does not stack by itself);
• the hero title was fixed at 3.5rem, far too large on narrow screens;
• the marquee was an empty green strip on mobile;
• footer titles were white text on a light background, nearly invisible;
• the copyright line was covered by the "back to top" button.

After fixing, re-measured: six pages × 375/320, every one with scrollWidth == clientWidth.

A "fake bug" found along the way​

Screenshots taken with --window-size=375 looked cropped, and I briefly thought the layout had exploded. In fact headless windows have a minimum width, and the screenshot was cropped to 375 — the page itself never overflowed. Screenshots lie; numbers do not.

Lesson​

Mobile checks can and should be scripted:

1. Set the viewport to real device sizes (375, 320);
2. Assert scrollWidth == clientWidth for every key route;
3. Record which elements overflow, to locate the culprit;
4. Keep the script in the repo so it can be rerun after every change.

Compared to "take a look on my phone", this is repeatable, regression-friendly, and does not depend on having a device at hand.

Risks that genuinely do not exist​

With no server, these are off the table: SQL injection, privilege escalation, SSRF, an upload endpoint being abused, a database being dumped. A tool only touches files the visitor selected, and results go back to that visitor's own browser.

The four things actually worth defending​

1. Supply chain. Third-party packages execute at build time and can read the repo and modify output. Countermeasures: pin exact versions, commit the lockfile, prefer zero- or few-dependency libraries, and inspect postinstall scripts. For the QR code tool I eventually picked the zero-dependency qrcode-generator over qrcode, which drags in pngjs and yargs.

2. Decoder vulnerabilities. A malicious image can trigger memory errors in a WASM decoder. The blast radius is the tab that opened it — no server means no other users are affected. Countermeasure: follow upstream releases, do not hand-patch binaries.

3. Resource exhaustion. One enormous image can freeze a phone tab. Countermeasures: 25 MB per file, a 40-megapixel ceiling, 20 files per batch, concurrency limited to 2, and automatic downscaling beyond the limit.

4. XSS. File names, QR content, and user input are all untrusted. Countermeasures: always textContent or Canvas drawing, never HTML concatenation; revoke blob: URLs when done.

Proving "nothing is uploaded"​

Not by claiming it, but by capturing traffic: run the whole compression flow in a headless browser and record the host of every request. The result was only the local static server and blob: addresses, with no external requests, and the WASM indeed came from our own /wasm/.

A side benefit​

Because there are only static files, there is almost nothing exploitable to configure on Cloudflare Pages: no environment variables, no functions, no runtime version to babysit. The attack surface shrinks to "build output plus a browser".

Lesson​

Security is not a single dimension called "has a backend or not". What pure front-end projects most often neglect is the dependency chain and input handling — hold those to backend standards.

Layer one: route-level splitting​

Docusaurus bundles each page separately. The tool page component is only 10 KB, and the homepage or an article never downloads it. Cold loads with caching disabled:

That 570 KB is the framework, React, and the search client — nothing to do with tools.

Layer two: library-level lazy loading​

The compression logic and jSquash live behind await import(), pulled only when the button is pressed. WASM comes even later: it is requested when encoding actually starts, and only for the format in use.

Layer three: prewarming​

Lazy loading solves "pay nothing until you click", but the first click still waits for a 250 KB download — roughly 1–2 seconds on a phone. So the tool prewarms as soon as a file is selected:

• Initialise the encoder for the current output format in the background;
• When the format changes, debounce 500 ms before prewarming again, so flipping back and forth does not re-download;
• Prewarm failures are silent; the real compression retries and reports errors.

Measured: the encoder download starts 34 ms after selecting a file, and clicking "Start compressing" to a result takes only 172 ms.

The trade-off​

Prewarming downloads the WASM once more, but only after a strong signal of intent — the user already picked a file. It is not an unconditional prefetch. For data-sensitive situations it can be turned back into pure lazy loading at the cost of a slower first click.

Lesson​

Lazy loading and prewarming are not opposites. The first governs the entry cost, the second governs the first-interaction cost. Draw the boundary clearly and both goals can be met.

My first thought was "user error". My second was "no, this is mine".

The symptoms​

• Compression finishes and the item state becomes "done";
• The main button is enabled only when there are pending items — now zero, so it is disabled;
• Changing quality or format does not invalidate finished results, and there is no "rerun" entry point;
• The only way out is deleting the image and selecting it again — which feels like a page refresh.

Root cause​

I tied "can I click" to "are there pending items", but a tool page has more than two states. The real model is at least:

pending → working → done, plus a dimension for whether the result matches the current settings.

I skipped that last dimension, so results could exist while being impossible to recompute.

The fix​

1. Button label follows state: with pending items it reads "Start compressing (N)"; once everything is done it becomes "Recompress" and is always clickable;
2. Sign each result with its parameters: every result stores the format:quality:maxEdge used to produce it, and is marked stale when settings differ;
3. Show a hint: when stale results exist, prompt "Settings changed — click Recompress to rerun with current parameters";
4. Free memory before rerunning: revoke old blob: URLs one by one so repeated compression does not pile up memory.

Measured on one image: default quality 96 KB → quality 40 gives 57 KB → WebP gives 18 KB, with no refresh at any point.

Lesson​

Do not assemble async tool state from booleans (busy / hasResult / disabled each doing its own thing) — contradictory combinations appear quickly. Model the state and "which parameters the result belongs to" explicitly, and a whole class of bugs disappears.

Pitfall 1: init is not on the entry point​

The intuitive import:

import {init, encode} from '@jsquash/webp';

At runtime the console only says e.init is not a function. Digging into dist revealed that the package entry only exports encode and decode:

// @jsquash/webp/index.js
export {default as encode} from './encode.js';
export {default as decode} from './decode.js';

init is a named export of encode.js. So:

const mod = await import('@jsquash/webp/encode.js');
await mod.init({locateFile});
const encode = mod.default;

Lesson: a library's README and its actual exports often disagree. Reading dist beats reading docs.

Pitfall 2: where the WASM comes from​

By default the Emscripten glue looks for the .wasm next to the module itself. I wanted to self-host, so files went into static/wasm/ and init got a resolver:

await init({locateFile: (file) => `/wasm/${file.split('/').pop()}`});

Note that libwebp has a SIMD variant: the library probes with wasm-feature-detect, loading webp_enc_simd.wasm when supported and the plain build otherwise. Both files must be present, or machines with SIMD support get a 404.

Pitfall 3: oxipng works differently​

The first two are Emscripten; oxipng is wasm-bindgen, so initialisation differs:

const mod = await import('@jsquash/oxipng/optimise.js');
await mod.init('/wasm/squoosh_oxipng_bg.wasm');
const optimise = mod.default;

Internally it also checks whether it is in a Worker and whether multithreading is available, choosing between the single-threaded and parallel packages. We run on the main thread, so it takes the single-threaded one.

How to debug this class of problem​

• Catch exceptions in the browser first (I listen to Runtime.exceptionThrown over CDP);
• Log before and after init to distinguish "not exported" from "failed to load";
• Read dist in node_modules instead of second-hand docs.

None of the three is hard, but all three stall on "the docs do not say". After this round I have a fresh appreciation for "the source is the API".

Where Canvas falls short​

The browser's toBlob uses a built-in encoder with only format and quality as knobs. For photos, quality 0.75 WebP usually saves 60–80%, which sounds fine — but push it lower and details smear, while a dedicated tool still saves another half.

The difference is not the algorithm but the encoder: browsers ship general-purpose implementations, while mozjpeg, libwebp, and oxipng are tuned specifically for "smaller file at the same visual quality".

Switching to WASM encoders​

I used three encoders packaged by jSquash:

• mozjpeg for JPEG, with quality and progressive options;
• libwebp for WebP, auto-detecting CPU SIMD support for a faster build;
• oxipng for lossless PNG optimisation — it does not touch pixels, it re-packs compression blocks.

With all three paths working, measurements on synthetic images (magnitude only):

One easily missed detail​

When PNG goes down the "lossless optimisation" path, not a single pixel changes — only the compression gets smarter. This is especially effective for screenshots, icons, and flat colour blocks, and there is no psychological burden of quality loss. So it is the default in the tool: PNG in, PNG out, no resizing means straight to oxipng, skipping canvas.

The cost is WASM size: about 1 MB across four binaries. But they load on demand — if you never press compress, not a byte is downloaded.

Lesson​

Compression is not "turn the quality down", it is "use the right encoder". Canvas is fine for thumbnails and quick previews; when size actually matters, bring in the professionals.