DEV Community: Gabor Koos

How I Built a Static Ecosystem Site for My Open Source Tools (Eleventy + Tailwind + GitHub Pages)

Gabor Koos — Sun, 14 Jun 2026 20:10:22 +0000

I've been building the fetch-kit ecosystem for about a year - ffetch (a fetch wrapper with resiliency features), chaos-fetch (a network failure testing tool), chaos-proxy (a proxy to inject network chaos), and the chaos arena (to set up different network failure modes). Each tool has its own GitHub repo and README, but there was no single place that answered "what is this, when do I use it, and how does it all fit together"? Someone landing on the ffetch repo had no idea chaos-fetch existed, let alone the arena.

So I built fetchkit.org.

The stack

Eleventy (v3) for static site generation - Nunjucks templates, fast builds, zero client-side framework overhead
Tailwind CSS v4 with a custom dark color palette derived from the logo background color
GitHub Pages for hosting with a custom GitHub Actions workflow that builds on push to main and deploys the dist folder
Cloudflare for DNS (with A records kept grey/DNS-only - GitHub Pages does its own cert verification and breaks if it sees Cloudflare IPs instead of its own)
GoatCounter for privacy-friendly analytics

What's on it

Each tool gets its own page with: what it does, code examples, a comparison table (e.g. chaos-fetch vs chaos-proxy), and links to the blog posts I've already written about it. The homepage has a news widget that pulls from my blog's RSS feed filtered by the fetch-kit tag.

The Cloudflare gotcha

Worth calling out: if you host on GitHub Pages with a custom domain and Cloudflare, keep your A records as DNS only (grey cloud), not proxied. GitHub periodically re-verifies that the domain resolves to its own IPs. With Cloudflare proxying on, it sees Cloudflare IPs, marks the domain as misconfigured, and stops serving it. The CNAME for www can be proxied fine - only the apex A records matter.

Source

The site source is at github.com/fetch-kit/fetch-kit.github.io if you want to see the Eleventy + Tailwind v4 setup.

Your Package Manager Is Lying to You

Gabor Koos — Fri, 12 Jun 2026 00:12:15 +0000

Package managers are usually treated as interchangeable tooling: install dependencies, commit the lockfile, and move on. In that framing, the only question that seems to matter is performance.

In practice, the differences run much deeper. npm, Yarn, and pnpm are built on fundamentally different models of what node_modules should be: different assumptions about how dependencies should be represented on disk, how strictly boundaries should be enforced, and how much implicit behavior the ecosystem should tolerate.

Bun and Deno go further: they challenge the model itself. Bun treats the entire developer loop as something that should feel instantaneous. Deno folds dependency management into a broader security and web-native runtime philosophy.

This is why migrations often feel disproportionate. The lockfile might be perfect and your application code untouched, yet builds break because scripts, plugins, and tools were written against a different set of invariants about the filesystem.

The real axis of difference isn't speed or disk usage, but how each tool chooses to represent and resolve dependencies.

Every package manager is a different compromise between what physically exists on disk and what the ecosystem expects to find. Those tradeoffs are easiest to see through five competing goals.

The Five Competing Goals

Every package manager is trying to optimize the same things:

Reproducible installs
Install speed and cache reuse
Disk efficiency across multiple projects
Compatibility with the Node ecosystem as it exists today
Developer experience (integrated tooling, lower friction, safer defaults)

No tool can maximize all five at once. The practical choice is usually the one whose failure mode you’re most willing to tolerate.

npm: The Pragmatic Baseline (Compatibility Over Correctness)

npm is the default package manager for Node.js and has been since its early days. If you use Node, you have npm. This gives npm a huge advantage in terms of ecosystem compatibility and developer familiarity, but it also means npm has had to make compromises to maintain that compatibility over time.

Core Model

npm flattens the dependency tree by placing packages as high as possible in node_modules, then falls back to nested subdirectories only when version conflicts force it. This simple strategy was born from pragmatism: Node's module resolution algorithm walks up the directory tree looking for node_modules, so the flatter the structure, the faster the lookup and the fewer surprises developers encounter. The strategy has persisted because it still broadly works with how the Node ecosystem is wired.

Design Philosophy

npm's philosophy is pragmatic continuity: rather than enforce a strict model of dependency access, npm prioritizes keeping the ecosystem running as it currently runs. This means tolerating patterns that are structurally impure if those patterns are common in the wild. A new, stricter model might be more correct, but it would break existing code and tooling, so npm's design philosophy is to bend toward the ecosystem rather than ask the ecosystem to bend toward it.

Strengths

This design brings several concrete advantages. Compatibility is the biggest: almost every tool in the JavaScript ecosystem was first tested and optimized for npm's semantics, so migrating away from npm often means discovering edge cases in other tooling. Setup is minimal, which matters for teams that don't want to spend cycles learning tooling; npm just works by default. And there is real value in being bundled with Node itself: it means npm is always available, always installed, and always familiar to anyone with Node on their machine.

Weaknesses

The cost of this compatibility-first approach is structural ambiguity. Hoisting can make undeclared dependencies accidentally available, which means the actual runtime dependency graph often differs from what package.json files claim. On larger codebases, this ambiguity compounds: node_modules can become very large and performance can degrade in monorepos or CI pipelines where many projects share the same machine. Install times are generally slower than newer, store-based approaches, especially when you are running the same installs repeatedly across different projects or CI runs.

The Lie It Tells

npm's lie is a useful one: it suggests that a package's runtime behavior matches its declared dependencies. In reality, a package can often reach into the hoisted tree and use packages it never declared, simply because those packages were placed somewhere reachable. The discrepancy is usually invisible until something changes—a new dependency, a version conflict, or a different install layout on a different machine—and suddenly that undeclared access no longer works.

Example

Suppose your app declares react, but one of your dependencies declares lodash. npm hoists both to the top level of node_modules. If your app imports lodash directly, it will work—and the import may be there because someone saw it was available and used it for convenience. Months later, you update a different dependency, or remove the one that was declaring lodash. Now npm's hoisting algorithm arranges things differently, and lodash is no longer at the top level. Your app's direct import lodash suddenly fails, and the error looks baffling because you never explicitly declared the dependency and the import appears to be fine in the code.

Best for

npm remains the default choice for most teams, especially those building straightforward applications, maintaining legacy codebases, or operating in environments where broad ecosystem compatibility matters more than perfect structural correctness. If your priority is minimizing friction and maximizing the number of third-party packages and tools that work without special configuration, npm is still usually the right call.

Yarn (Berry): Reproducibility as a Response to npm's Early Chaos

When people refer to "Yarn" in 2026, there is often ambiguity about which version they mean. Yarn Classic (v1) was released as a faster alternative to npm in the npm v3–v4 era and is still widely used in legacy projects. Yarn Berry (v2 and later) is a much more ambitious reimagining, released around 2019, that fundamentally questions whether node_modules should exist at all. This section focuses on Yarn Berry, because that is where Yarn's design philosophy is most visible.

Core Model

Yarn Berry combines a strong lockfile system with Plug'n'Play (PnP) as its default linker mode, which can abandon the traditional node_modules directory entirely. In PnP mode, Yarn uses a .pnp.cjs file to map each package to its location in a global cache, and module resolution is intercepted to consult that map. Berry is not limited to PnP, though: it also supports alternative linker modes that use node_modules layouts (including npm-like and pnpm-like behavior), which can reduce migration friction for ecosystems that still assume on-disk trees. The lockfile is deterministic to the byte, meaning the same yarn.lock on any machine will always produce the exact same dependency tree and artifacts. If you want, you can run yarn install --immutable and ship the dependencies as part of your repository, enabling zero-install setups where CI does not need to download or build anything.

Design Philosophy

Yarn's philosophy is reproducibility as a first-class concern and extensibility as a design principle. Every decision in Yarn Berry prioritizes the ability to reproduce an install exactly, down to the checksum of every file. The plugin system allows customization at nearly every step of the install process, which appeals to large organizations that need to enforce internal policies or integrate custom private registries and tooling. Yarn treats package management as a build artifact that deserves the same rigor as compiled code.

Strengths

Yarn delivers on reproducibility in ways that are genuinely powerful for large teams. Every install is deterministic and can be verified; there is no ambiguity about what your project depends on or how it was resolved. The plugin ecosystem is extensive, allowing organizations to customize resolution, transport, and authentication without forking the entire tool. Zero-install workflows are real: you can ship .yarn/cache and .pnp.cjs in version control so anyone cloning the repo can start work immediately without running yarn install. For enterprise teams managing complex monorepos with internal tooling, Yarn's flexibility can be a major advantage.

Weaknesses

The cost of this power is complexity and ecosystem friction. Plug'n'Play mode breaks many tools that assume a traditional node_modules directory exists. Older packages may have scripts that do fs.readdirSync('node_modules') or similar filesystem introspection, and those simply fail under PnP. Even many modern tools can behave unexpectedly because they were written for node_modules semantics. Build tools, bundlers, and testing frameworks often need special configuration or plugins to work well with PnP. Using node_modules-based linker modes can reduce some of that migration pain, but you also give up part of PnP's strictness and determinism story. Yarn Berry adoption is still much smaller than npm or pnpm, so community support and third-party integration are less mature. For teams that do not have a dedicated DevOps or tooling function, Yarn's flexibility can feel like unnecessary overhead.

The Lie It Tells

Yarn's lie is seductive: that you can completely abstract away node_modules and replace it with something cleaner and more reproducible without paying a compatibility tax. The reality is that the Node ecosystem is deeply wired around the expectation of a physical node_modules directory, and that wiring is stronger than Yarn's tooling can fully hide. Tools that Yarn does not control will still expect node_modules to exist.

Example

You enable PnP mode and everything works locally. Your build tool has a Yarn plugin, your test runner runs fine, and the install is instant. Then a team member uses a script that was written by someone else in your organization years ago, or tries to use a third-party tool that does require.resolve() with filesystem assumptions, and it fails because the packages are not actually on disk in node_modules anymore. You can often fix this by adding a Yarn plugin or switching to a different tool, but each fix is a small friction point.

Best for

Yarn Berry is best suited to large organizations with dedicated tooling teams, complex monorepos, or projects where reproducibility and extensibility are more valuable than broad tool compatibility. If you are willing to invest in understanding and maintaining Yarn's plugin system, or if your CI environment is fully under your control and can be customized, Yarn offers genuine advantages. For smaller teams or projects that need to work smoothly with a wide variety of third-party tools out of the box, Yarn's cost-to-benefit ratio is often too high.

pnpm: Structural Correctness Through Isolation

Note that I am biased towards pnpm, because it was created by a fellow Hungarian called Zoltan Kochan.

pnpm takes a different approach to the same problems that motivated Yarn. Rather than try to abstract away node_modules, pnpm makes node_modules stricter and more honest about what dependencies are actually available.

Core Model

pnpm uses a content-addressable global store and symlinks to build a non-flattened node_modules tree. Each package in your project gets its own node_modules directory containing only the packages it directly declares, plus symlinks to those packages' dependencies. This means a package's node_modules mirrors its package.json exactly: if it declares lodash, lodash is there; if it does not, lodash is not accessible through the filesystem, even if some other package brought it in. The global store deduplicates identical copies of the same package across multiple projects, which saves substantial disk space, especially in monorepo environments.

Design Philosophy

pnpm's philosophy is structural correctness and efficiency. The core belief is that the dependency graph should be explicit and strict: if a package declares a dependency, it should be there; if it does not, it should not be. This honesty creates friction with the ecosystem, but it also exposes bugs and bad practices that npm and Yarn hide. pnpm's secondary goal is disk efficiency, achieved through content-addressable storage and symlinks rather than through hoisting or abstraction.

Strengths

pnpm delivers tangible benefits for the specific use cases it targets. Disk savings are real and measurable, especially in monorepos or CI environments where many projects are installed on the same machine; a global store means installing lodash a second time costs almost nothing. Isolation eliminates phantom dependencies entirely, so your code is forced to match what your package.json claims. Installation is fast, both because the global store avoids duplication and because pnpm can leverage hard links and copy-on-write in certain environments. For monorepos in particular, pnpm's performance characteristics are better than npm's in almost every scenario.

Weaknesses

The cost is ecosystem friction. Tools and packages that were written assuming npm's hoisting behavior will break under pnpm. A postinstall script that does require('lodash') without declaring lodash will fail. Build tools that walk the node_modules tree looking for specific files may find them in unexpected places because they are symlinked rather than copied. Older packages with complex installs sometimes fail. On Windows, symlinks can introduce permission issues. The Node ecosystem was not built around strict isolation, so opting into pnpm means being prepared for occasional surprises and workarounds.

The Lie It Tells

pnpm's lie is that the filesystem representation of dependencies is obvious and complete. The reality is that the filesystem is now abstract: packages are symlinks to a global store, and the actual files are cached globally. You can no longer walk into node_modules and see what you have; you have to understand symlinks and content addressing. For teams used to simple filesystem navigation, this is a minor lie, but it is there.

Example

You install a package that has a postinstall script expecting to reach a transitive dependency. Under npm, the hoisting may make that work accidentally. Under pnpm, the transitive dependency is not in that package's node_modules tree, so the script fails. You either need to add the transitive dependency to the package's declared dependencies (which is the "correct" fix) or work around it. This kind of friction is common enough to notice during monorepo migrations.

Best for

pnpm is the best practical upgrade from npm if your pain point is disk usage or install time in a monorepo, or if you want the strictness of explicit dependencies without the complexity and friction of Yarn's PnP mode. It is increasingly becoming the package manager of choice for large monorepos and organizations that can tolerate the ecosystem friction. For solo projects or teams that prioritize broad compatibility over strictness, pnpm offers less value.

Bun: Speed as a First-Class Citizen

Bun is a newer runtime that bundles its own package manager, and that manager reflects Bun's core philosophy: speed should feel magical, and the entire developer experience should be instantaneous. Unlike npm, Yarn, and pnpm, which are package managers that happen to work with Node, Bun's package manager is designed from the ground up as part of a runtime that understands and optimizes for the entire development loop.

Core Model

Bun's package manager uses a global cache with aggressive deduplication, typically via hardlinks rather than pnpm-style symlink graphs. pnpm's approach is symlink-heavy and isolation-first. Bun's is tuned for fast installs and runtime throughput. The install process is dramatically faster than npm, in part because Bun itself is written in Zig and uses parallelism aggressively, and in part because Bun can resolve and validate dependencies using runtime knowledge that npm cannot. Bun also attempts to maintain broad compatibility with npm's node_modules layout, so the transition is often smooth, but Bun can also use its own dependency resolution when advantageous.

Design Philosophy

Bun's philosophy is simplicity through speed. The core belief is that friction in the development loop comes from waiting—waiting for installs, waiting for builds, waiting for tests. Bun attacks that friction by making every operation as fast as possible, and by consolidating tools that developers usually need to install separately (bundler, transpiler, test runner, package manager) into a single cohesive system. The design accepts some ecosystem incompatibility if that incompatibility enables significant speed gains.

Strengths

Bun is genuinely fast in ways that matter. Install times are often 5–10x faster than npm, and that speed translates to real developer experience gains, especially in CI pipelines or on machines with slower disks. Running bun install and then immediately using installed packages feels snappy in a way that npm rarely achieves. Because Bun is a complete runtime, it can also function as a drop-in replacement for Node in many scenarios: you can run TypeScript files directly without transpilation, use Bun's built-in test runner instead of installing Jest, and use Bun's bundler instead of webpack. For greenfield projects or teams willing to commit to Bun as their primary runtime, this all-in-one experience is compelling.

Weaknesses

Bun is still maturing, and that maturity gap is visible in production. Some native Node modules do not work with Bun because Bun's native module interface is different from Node's. Complex webpack configurations or advanced build setups sometimes require adaptation. Third-party tools that hook into Node internals (like certain APM or debugging tools) may not work. Bun's adoption is still small compared to Node, so the ecosystem is less tested against Bun semantics. The risk is real: betting on Bun means accepting that you may hit undocumented edge cases or that some dependency may not work as expected. For teams that need guaranteed stability and compatibility across a broad range of tooling, Bun is not yet a safe choice.

The Lie It Tells

Bun's lie is that you can use it as a drop-in replacement for Node without any friction. The reality is that while Bun is compatible with a high percentage of Node packages and tooling, it is not completely compatible. Tools that assume Node internals, native modules with Node-specific bindings, or code that relies on subtle Node.js behavior differences will surface issues that are not immediately obvious.

Example

You switch your project to Bun and installs become blazingly fast. Your basic tests run. You deploy and everything works for a few weeks. Then a package that uses a native module breaks because its Node-specific binding does not work in Bun. Or an internal tool relies on node being available in the PATH, and Bun is not recognized as a drop-in replacement. Or a third-party SDK that patches Node internals fails. These are not Bun issues; they are ecosystem expectations that Bun has not yet fully absorbed.

Best for

Bun is best for greenfield projects where you control the entire toolchain and can commit to Bun as your primary runtime. If your primary goal is speed and developer experience, and you are willing to occasionally work around compatibility edge cases, Bun is a compelling choice. For existing projects heavily invested in Node.js tooling, or for production systems that require broad compatibility guarantees, Bun is not yet the pragmatic choice.

Deno: The Secure, Web-Native Alternative

Deno is a runtime built by the creator of Node, and its package manager reflects a philosophical rethinking of what dependency management should mean on the web. Its design starts from URL-native imports and a global cache model, but modern Deno also provides strong npm interoperability for teams that need Node-style workflows. This hybrid approach is still meaningfully different from the defaults in npm, Yarn, pnpm, and Bun, and it surfaces tradeoffs that appeal to developers who care about security and clean architecture more than ecosystem inertia.

Core Model

In modern Deno, you can import npm packages directly with npm: specifiers (for example import chalk from "npm:chalk@5") and map clean bare specifiers via deno.json/deno.jsonc import maps. The runtime still uses a global cache as its primary model, but for Node compatibility workflows it can also materialize a node_modules directory when needed. In that mode, layout behavior is configurable rather than fixed, so teams can choose conventions that are closer to isolated or hoisted dependency trees depending on interoperability needs.

Design Philosophy

Deno's philosophy is security by default and simplicity through URLs. The core belief is that dependencies should be explicit and traceable, and that the web's native import model (URLs) is cleaner and more secure than npm's node_modules. Security is not an afterthought; Deno grants zero permissions by default. A script cannot access the network, file system, or environment variables without explicit permission flags. This is a radical departure from Node, where every installed package can do anything to your system.

Strengths

Deno's security model is genuinely compelling. You know exactly what URLs you are importing from, and you can audit them. Third-party code cannot access your file system or make network calls unless you explicitly allow it with permission flags. The built-in toolchain is also excellent: Deno includes a formatter, linter, test runner, documentation generator, and bundler without needing additional installations. For projects starting from scratch with TypeScript, Deno feels clean and cohesive in a way that Node does not. URL-based imports can also reduce registry coupling and make dependency provenance clearer in workflows that use them.

Weaknesses

Deno is smaller than Node and npm, so the ecosystem is still narrower in practice even with strong npm interoperability. While many npm packages now run well through Deno's compatibility layer, edge cases remain around tooling assumptions, native addons, and deeply Node-specific behavior in older dependencies. Import maps and npm: specifiers reduce migration friction substantially, but they do not eliminate all compatibility work for mature codebases with complex build pipelines. For teams deeply embedded in Node-specific tooling, Deno can still feel like a step sideways before it feels like a step forward.

The Lie It Tells

Deno's lie is that teams treat its compatibility story as a migration shortcut. In practice, Deno gives you several valid models at once (URL imports, npm: imports, import maps, optional node_modules), and that flexibility creates architectural decisions teams still need to standardize. Security defaults and cleaner primitives help, but dependency policy, version governance, and ecosystem fit checks are still real work.

Example

You start a new Deno project and mix npm: imports with import-map aliases, so local development feels close to Node while still keeping Deno's runtime defaults. It works well for most dependencies. Later, your team adds tooling that assumes a specific node_modules layout and hits subtle integration issues in CI until you align configuration and conventions across repos. The lesson is not that Deno is incompatible; it is that flexibility needs explicit team standards.

Best for

Deno is best for security-conscious projects, fresh TypeScript greenfield work, and teams that philosophically prefer the web's native import model. If you are building backend services or tooling where the built-in security model matters, and you are willing to accept a smaller ecosystem, Deno is a compelling choice. For projects that rely heavily on npm packages or for teams that need maximum ecosystem access, Deno is not yet pragmatic.

The Core Thesis: Different Mental Models

When we step back from each tool's implementation details, a clearer pattern emerges. The real axis of difference is not speed or disk usage or which tool claims to be the fastest. The real difference is how each tool chooses to represent and resolve dependencies in the first place, and what that representation means about the relationship between your code and the packages it depends on.

At the heart of these five tools is one fundamental question: how should the package manager resolve and physically (or virtually) lay out dependencies on your machine? npm flattens them to maximize compatibility. Yarn reproducibly locks them and can abstract them away entirely. pnpm isolates them structurally. Bun optimizes around speed. Deno rejects the node_modules model altogether. Each answer reflects a different assumption about what dependencies should be, and each assumption carries consequences.

Tool	Mental Model	Core Assumption	Best For
npm	Flattened convenience graph	Compatibility first	Most everyday projects
Yarn	Reproducible build artifact	Tooling extensibility	Enterprise customization
pnpm	Explicit isolated graph	Structural correctness	Monorepos & large codebases
Bun	Invisible high-performance detail	Speed should feel magical	Speed-first greenfield
Deno	URL-native + npm-compatible hybrid	Security-first defaults + interoperability	Security / philosophy-driven work

Where Things Actually Break

Understanding these mental models is intellectually interesting, but the gap between philosophy and practice is where package managers reveal themselves. The Node.js ecosystem was built entirely around npm's assumptions. Thousands of packages, build tools, and deployment scripts are hardcoded to expect npm's specific model of dependency resolution and layout. Any deviation from that model carries a compatibility tax, and that tax is paid in small, accumulated frictions that add up.

I once spent four hours debugging a monorepo migration from npm to pnpm. The overall migrate looked clean: update the lockfile, run pnpm install, commit, done. But a postinstall script deep in one of our dependencies was doing something that should have been impossible: it was reaching into a transitive dependency that pnpm didn't hoist by default. The script didn't declare that dependency, so it shouldn't have been able to find it. Under npm's flattened model, it was just there. Under pnpm's strict model, it was nowhere. The build broke silently at a step the script didn't fail on, it just couldn't find what it needed. Debugging required understanding not just what pnpm did differently, but what that dependency's script was secretly assuming about npm's layout.

Why Switching Feels Like Progress (or Regress)

Every few years, a new wave of developers discovers a newer package manager and adopts it with missionary zeal. npm → Yarn felt revolutionary in 2016 because npm was genuinely unstable and Yarn's lockfile was a genuine breakthrough. npm → pnpm often feels like finally getting it right, because pnpm's strict isolation catches real bugs that npm hides. npm → Bun feels like magic because it is fast. npm → Deno feels philosophically cleaner because security-by-default and URL-based imports genuinely reduce certain classes of risk.

And yet, for most day-to-day work, staying on npm still feels like the rational default. That is not because npm is objectively best, adoption is rarely driven by just technical superiority in isolation. It's driven by the difference between friction and payoff. For a small team on a stable project with no monorepo pain, the chore of switching to pnpm outweighs the payoff. For a team that has just hit their third incident caused by a phantom dependency, pnpm suddenly looks very attractive. For a greenfield project where speed is critical and you can control the entire toolchain, Bun is worth the risk. But most teams inherit their package manager from whatever was already there when they joined.

Practical Decision Guidance in 2026

Choosing a package manager should be boring and practical, not philosophical. Here is how to think about it:

If you are starting a new project or working on something small, solo, or legacy where nothing breaks and you want zero friction, npm is still the right choice. It is the default, it works, and your entire team already understands it. If you have a monorepo with hundreds of packages and your CI pipeline is slow or your developers are regularly confused about which dependencies are actually available, pnpm is the strongest practical upgrade. It solves real pain points without requiring architectural rethinking. If you have a large enterprise with heavy custom workflows, heavy internal tooling requirements, or deep build customization, Yarn Berry can provide the plugin system and flexibility you need. If you are starting a new greenfield project and your primary constraint is speed—and you are willing to occasionally work around compatibility edges, Bun offers a genuinely better developer experience. If you are building something security-critical or you are philosophically committed to clean, traceable dependencies, Deno is worth the ecosystem cost.

The truth is that most teams do not actually choose their package manager, they inherit one. The developer who set up the project chose it three years ago, and now changing it feels like choosing to fight an unnecessary battle. That inertia is not always wrong. Switching has real costs, and the payoff is often smaller than it feels until you have actually experienced years of pain under your current tool.

Conclusion

Your package manager is not malicious. It's not lying out of deception, it's lying out of necessity. Every tool optimizes for a specific set of assumptions about what node_modules should represent, what dependencies should mean, and what the developer's priority actually is. npm optimizes for compatibility and zero configuration. Yarn optimizes for reproducibility and extensibility. pnpm optimizes for correctness and disk efficiency. Bun optimizes for speed. Deno optimizes for security and simplicity on the web.

The real question you need to ask yourself is not "which package manager is best?" but "which set of assumptions, and which set of lies, am I willing to live with?" Because every tool has tradeoffs: they make a fundamental choice about what matters and what you can afford to sacrifice. Understanding those choices, and understanding what your real pain point actually is, is the only way to make a decision you will not regret.

How to Evaluate an npm Package - 2026 Edition

Gabor Koos — Thu, 11 Jun 2026 02:11:05 +0000

Every time you run npm install, you are adding code that will execute in your production environment: code written by someone you have never met, with access to whatever your process can reach. It might touch your filesystem, make outbound network requests, read environment variables, or quietly exfiltrate data. You are, in effect, trusting a stranger with your infrastructure.

Most developers manage this risk by checking two numbers: weekly downloads and GitHub stars. Neither tells you anything meaningful about whether a package is safe, maintained, or honest about what it does. (Most npm packages use GitHub. If a project is hosted elsewhere, apply the same principles.)

Supply chain attacks have made this worse. Event-stream, ua-parser-js, node-ipc, xz utils - the pattern is consistent: a legitimate, widely used package gets compromised, either through a maintainer being social-engineered, a typosquat, or a dependency buried three levels deep. The npm ecosystem, with its culture of small composable packages and deep transitive dependency trees, is a particularly attractive target. You can do everything right and still get hit through something you never directly installed.

There is a newer variation worth knowing about. AI coding assistants hallucinate package names. They confidently suggest npm install some-plausible-sounding-package for packages that do not exist. Attackers monitor those hallucinations and register the names - a technique now called slopsquatting - so that when a developer follows the suggestion without checking, they install something malicious. If an LLM suggests a package you have never heard of, verify that it exists, has a real history, and has provenance before you run the install.

This risk increases when you run LLMs in agent mode. In many setups, package selection and installation happen back-to-back without a human checkpoint. If you are doing that, rely on enforcement in the toolchain (for example, a wrapper or install hook that blocks unknown or unverified packages), not on "remember to check first" prompt text.

None of the above means you should stop using open source packages - that would make you less productive without making you meaningfully safer. What it means is that picking a package deserves more than a five-second glance at the star count.

This guide gives you a repeatable process for evaluating an npm package before you add it. It takes 5 to 10 minutes. It won't guarantee safety - nothing will - but it will help you make an informed decision rather than an optimistic one.

0. Do you actually need this package?

Before you audit anything, ask the simplest question first: should this dependency exist in your project at all?

Many npm incidents become severe not because one package is inherently catastrophic, but because a tiny convenience package gets copied across dozens of services and frontend apps until it is everywhere. If that package is compromised, abandoned, or suddenly unpublished, your blast radius is no longer small.

What to check:

Do a removal test in your head: if this package disappeared tomorrow, how hard would it be to replace? If the answer is "we would have to refactor half the codebase," treat it as high-risk and apply stricter scrutiny.

If it is a tiny utility, ask whether you can implement the same thing in a few lines in your own codebase. Pulling a dependency for one helper function is often not worth the long-term risk.

Check the package dependency footprint. A package with zero runtime dependencies is not automatically safe, but fewer dependencies generally means a smaller attack surface and fewer transitive surprises. On npm, inspect the dependency count and scan what those dependencies actually are.

Then check where you plan to use it. A package used in one isolated internal tool has a different risk profile from one that will be imported across every service.

1. Is it actively maintained?

An unmaintained package is a liability that compounds over time. Security vulnerabilities go unpatched. Compatibility with newer Node versions breaks silently. The API freezes while the ecosystem moves on, and eventually you are pinned to an old version of something because updating it would require replacing a package nobody is touching anymore.

The obvious signal is recent commits, but commit frequency alone is misleading. A package can have a commit last week that does nothing but update a CI action. What you are looking for is whether the author is still engaged with the actual software.

What to check:

On the GitHub repository, go to the Issues tab. Look at the oldest open issues. Are they acknowledged? If someone reported a bug 18 months ago and the author has never replied, that tells you something about what the maintenance relationship looks like when things go wrong.

Look at the Commits tab. Filter out bot commits and CI noise. When was the last time a human made a meaningful change to the source code, not just a dependency bump or a workflow tweak?

Look at who is doing the work. If almost every meaningful commit, release, and issue reply comes from one person, you have maintainer concentration risk (the "bus factor" - the number of people who would need to be hit by a bus before the project is in trouble). That is not automatically bad - many excellent packages are run by one maintainer - but it means your operational risk is tied to one human's availability and energy.

On the npm page, go to the Versions tab. Is there a recognizable release cadence - monthly, quarterly, whatever - or a 2-year gap followed by a burst of activity? Long gaps followed by sudden updates are sometimes a red flag in themselves: accounts do get taken over.

Check the CHANGELOG. If it just lists commit hashes, it is nearly useless. A changelog that says "Fixed: deduplication plugin now clones responses per waiter to prevent body-already-used errors" is a changelog written by someone who cares whether you understand what changed and why. The quality of the changelog is a proxy for how the author thinks about the people using their software.

Finally, if the package exposes a public API that has changed over time, look for a migration guide. An author who documents breaking changes and provides an upgrade path is an author who thinks about the downstream cost of their decisions.

2. Can you trust what's actually published to npm?

Maintenance is about the future. This section is about something more immediate: whether what is on the npm registry right now is actually what the author intended to publish.

The npm registry has no verification by default. When you install a package, you are trusting that the bytes you receive match the source code you can read on GitHub. For most packages, most of the time, that is true. But the mechanism that links source to publish - an NPM_TOKEN stored as a CI secret, or sometimes just on a developer's laptop - is exactly the kind of credential that attackers target.

The event-stream attack in 2018 is the clearest example: a maintainer handed over control of a popular package to a stranger. The stranger published a version with a malicious dependency. Millions of projects were affected before anyone noticed. No one hacked GitHub. No one broke npm's infrastructure. They just got the credentials.

Provenance attestation is the modern answer to this. When a package is published with provenance, the npm registry receives a cryptographic attestation (signed by GitHub's OIDC infrastructure) that ties the specific package tarball to a specific commit in a specific repository, built by a specific GitHub Actions workflow run. You can verify it. The attestation is public. If someone publishes a package claiming to be from a specific repository but the attestation does not match, that is detectable.

What to check:

Go to npmjs.com/package/<package-name>. Next to the version name, there should be a green "Provenance" badge if the package was published with provenance:

Click on it, then on the "View more details" link. It will take you to the bottom of the page:

It shows the repository URL, the commit SHA, and the GitHub Actions workflow run that published the package. You can click through to all of those things to verify that they exist and make sense. If the badge is there and the details check out, you can be reasonably confident that the package you are installing is what the author intended to publish.

If it is not there, the package was published without provenance - which is not automatically suspicious (most packages predate the feature), but it means you cannot verify the source-to-publish chain.

You can also check from the command line. In any project that has the package installed, run:

npm audit signatures

This verifies the cryptographic signatures of all installed packages and reports which ones have valid provenance attestation.

If you want to look at how a package is published, find the .github/workflows/ directory in the repository and open the publish workflow. Look for three things:

npm publish --provenance - this is what generates the attestation
id-token: write in the job permissions - this is what allows the OIDC token exchange with npm
The absence of NPM_TOKEN as a secret - if the workflow uses Trusted Publishing (OIDC), there is no long-lived token to steal

Finally, look at how GitHub Actions are referenced in the workflow files. Actions referenced as uses: actions/checkout@v4 or uses: actions/setup-node@main are pinned to a mutable tag - the action author can change what that tag points to at any time, and your workflow will silently start running different code. Actions pinned to a full commit SHA (uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd) cannot be changed without updating the reference in the workflow file itself. It is a small thing, but it closes a real attack surface.

One more thing that runs code on your machine before you have reviewed any of it: install scripts. The preinstall, install, and postinstall hooks in package.json execute the moment you run npm install. Most legitimate packages do not need them - native addons that compile C++ bindings are the main genuine use case. If you see an install script in a package that has no obvious reason for one, that is worth understanding before you proceed.

3. Is the CI pipeline real or decorative?

A green badge in the README is easy to fake, or rather, easy to earn without it meaning much. A repository can have continuous integration that runs three tests on a single happy path and reports 100% pass rate. That badge is technically accurate and entirely useless.

What you want to know is whether the CI pipeline actually protects the codebase: whether it would catch a regression, a type error, or a broken edge case before it ships.

What to check:

Go to the Actions tab on GitHub. Look at the workflow runs. Do they trigger on pull_request events, not just on pushes to main? A pipeline that only runs after merging is not protecting anything, it's just producing a record of what already happened.

Open a recent merged pull request. Did CI run on it? Did anyone have to wait for it to pass before merging? If the PR was merged 30 seconds after it was opened with no CI run, the pipeline is decoration.

Find the test configuration file: vitest.config.js, jest.config.js, or equivalent. Look for coverage thresholds. Something like:

thresholds: {
  lines: 90,
  functions: 90,
  branches: 90,
}

If thresholds are configured, the CI pipeline will fail if coverage drops below them. If they are not configured, coverage might be reported but it is not enforced, an author can delete half the tests and the build will still pass.

Also look at what the tests actually cover. A test/ directory that mirrors the src/ structure, or unit tests co-located with the source files, is a good sign. A single index.test.ts file with a handful of smoke tests is a different thing entirely. You cannot audit the tests in detail, but you can get a sense of whether the author takes them seriously.

4. Is the code quality visible?

You are not going to audit the entire codebase of every package you consider. That is not realistic. But you can take a quick look at the signals that correlate with code quality, the things an author does or does not do that are visible at a glance and tend to predict whether the package is robust or fragile.

What to check:

Look at the linting configuration: eslint.config.js, .eslintrc, or equivalent. Does it exist? Is it non-trivial? A blank or near-empty linting config suggests the author is not enforcing consistency or catching obvious mistakes automatically. Linting is table stakes; its absence is a signal.

Check whether the package ships a well-formed bundle. Look at the exports field in package.json. A modern package should specify named export conditions: import and require if it supports both module systems, or just import if it is intentionally ESM-only, and ideally types if it ships TypeScript declarations. A package that only sets main with no exports field at all was written before this became standard practice. That is not disqualifying, but it tells you something about how current the author's practice is.

Look at the package.json for a prepublishOnly script:

"prepublishOnly": "npm run build && npm run test:ci"

This prevents an author from accidentally publishing a broken build or a build that skips tests. It does not protect against malicious publishes, but it does tell you the author has thought about accidental ones.

For TypeScript packages specifically: open tsconfig.json and check whether strict: true is set. Strict mode enables null checks, strict function types, and no-implicit-any - a whole class of bugs caught at compile time rather than in production. An author who turns it off has decided some of those bugs are acceptable.

Also search the repository for any and @ts-ignore. A few uses in genuinely awkward interop situations is normal. Dozens of them scattered through the source code means the TypeScript types are largely cosmetic: the package has the .ts extension but not the type safety.

5. What happens when something goes wrong?

Every non-trivial package will eventually have a security vulnerability. The question is how the author handles it when it does. Do they respond quickly? Do they disclose responsibly - privately first, then publicly with a fix? Do they document what happened so you can assess whether your version is affected?

What to check:

Look for a SECURITY.md file in the repository root, or go to github.com/<owner>/<repo>/security/policy. This should tell you how to report a vulnerability privately, a contact method, a timeline for response, and some indication that the author takes disclosures seriously. Its absence does not mean the package is insecure, but it does mean that if you find something, you have no clear path to report it without accidentally disclosing it publicly.

Go to the Security tab on GitHub and look at the Advisories section. Has anything been published? If yes, how was it handled - was the disclosure coordinated, was a fix available when it went public, was the affected version range clearly documented? A well-handled historical advisory is actually a positive signal; it means the author knows what a responsible disclosure process looks like and has followed it.

Check osv.dev or snyk.io for known vulnerabilities in the package. These aggregate CVEs and GitHub Security Advisories. If the package has known unpatched vulnerabilities, that is something you need to know before installing it.

Socket.dev goes further than CVE databases. Rather than waiting for a vulnerability to be reported and cataloged, it does behavioral analysis: does this package access the network? Does it touch the filesystem in unexpected ways? Does it contain obfuscated code? Does it have install scripts? It also has a GitHub app that runs this analysis on pull requests and flags new dependencies before they are merged. For packages you are seriously considering, it is worth a quick check.

If you operate in a high-assurance environment, Socket Firewall is also worth knowing about. Instead of only warning at review time, it enforces package policy at install time and can block known-malicious packages from entering your environment at all. That is usually overkill for hobby projects, but for regulated or security-sensitive systems it can be a strong extra control.

Finally, look at how quickly past security issues were addressed. A critical vulnerability fixed within days is different from one that sat open for three months. Response time on security issues is one of the clearest signals of how seriously an author takes the responsibility of maintaining a public package.

The Checklist

Not all of these checks carry equal weight. If you only have time for three things:

Do you actually need it? If you can replace it quickly or avoid it entirely, you remove risk instead of managing it.
Does it have provenance? This is the clearest signal that the published package is what the author intended to publish.
Does it have unexplained install scripts? Code runs on your machine the moment you run npm install.

If the package is production-critical, add a fourth check: is the maintainer responsive? If something goes wrong, you want to know that the person who can fix it will actually fix it.

Everything else is worth checking when the stakes are higher.

Security-critical signals

These affect whether the package is safe to install and whether what you are installing is what the author published.

Signal	Where to check	Green	Red
Provenance	npmjs.com version page	"Provenance" section present and matches repo	No provenance, or version published from unknown source
Trusted publishing	`.github/workflows/publish.yml`	OIDC + `--provenance`, no `NPM_TOKEN`	`NPM_TOKEN` secret, manual publish steps
Install scripts	`package.json` scripts field	None present, or obvious native-addon reason	`preinstall`/`postinstall` with no clear justification
Pinned CI actions	`.github/workflows/*.yml`	SHA-pinned third-party actions	`@v3`, `@latest`, `@main`

Operational maturity signals

These tell you how seriously the author takes maintenance, quality, and the long-term cost of depending on their package.

Signal	Where to check	Green	Red
Active maintenance	GitHub commits + open issues	Commits in last 3 months, issues acknowledged	Last commit 2+ years ago, stale issues ignored
Dependency footprint	npm package page + lockfile tree	Few dependencies for package scope, no surprising transitive tree	Large transitive tree for a trivial utility
Maintainer concentration	Commits, releases, issue/PR responses	Work distributed across multiple active maintainers	One maintainer handles nearly all code, releases, and support
Coverage enforced	vitest/jest config	Thresholds configured at 80%+	No thresholds, or coverage badge that never changes
Security policy	`SECURITY.md` or Security tab	Clear disclosure process, contact method	Missing, or just a generic template with no contact

A package that is clean on security-critical signals but weak on operational maturity is a calculated risk. A package that fails the security-critical signals is a different category of problem.

Risk is not binary

None of this is a pass/fail test. It is a risk assessment, and risk depends on context.

A utility that formats dates in a UI has a different risk profile than an HTTP client sitting between your service and a government API. A dependency that receives 50 million weekly downloads has more eyes on it than one that receives 500. A package from an organization with a dedicated security team is different from one maintained by a single developer in their spare time. None of these are disqualifying conditions on their own - some of the most reliable packages in the ecosystem are maintained by individuals - but they affect how much scrutiny you should apply.

The goal is not to find a package with a perfect score on every dimension. The goal is to understand what you are accepting when you add it to your project, and to make that decision deliberately rather than by default.

How I Built a Confluence Crawler

Gabor Koos — Fri, 22 May 2026 22:37:58 +0000

TLDR: If you are not interested in the story and just want the tool, go straight to the repository: github.com/gkoos/confluence2md. It is a CLI that crawls Confluence and mirrors it into local Markdown files, including links, comments, and attachments, with support for incremental updates.

This started with a small problem that slowly became expensive: finding things in our company Confluence was harder than it should have been.

The first issue was human. Search results were noisy; useful pages existed, but they were buried under stale docs, half-duplicated runbooks, and pages whose titles made sense only to the person who wrote them three years ago. When you are in the middle of an incident or trying to understand a legacy service, that's not ideal.

The second issue was machine. I was building workflows with LLMs, and Confluence turned out to be a difficult source to work with directly. The content model is not designed around LLM retrieval quality. You can pull pages through APIs, but you still need to normalize structure, preserve context, handle references, and keep updates in sync. If the source layer is messy, everything downstream in your AI pipeline inherits the mess.

At some point the idea clicked: Markdown is a format that both humans and machines handle well. Humans can read it in any editor, Git can diff it, indexers can process it, LLM pipelines can chunk it. So instead of fighting Confluence at query time, why not mirror the space locally into clean Markdown and treat that mirror as the canonical retrieval layer?

That was the origin of confluence2md.

The First Attempt

The first design looked almost too clean: at heart, this is a two-phase crawling problem.

Phase one: start from one or more seed pages, crawl linked pages to a configurable depth, and convert each page into Markdown.

Phase two: once you know the complete set of crawled pages, rewrite internal Confluence links into local relative links.

On paper, this gives you exactly what you want. You avoid guessing link targets while crawling, because rewrite decisions happen only after the graph is known. You keep the logic separable: fetching and conversion in phase one, graph-aware link correction in phase two.

I expected most of the effort to be around traversal performance and retry logic. Instead, the hardest work appeared in the conversion layer and update model. The crawling algorithm was the easy part.

The Pain of Converting Confluence to Markdown

Confluence content is not "almost Markdown": it is stored in a custom storage format that is XML-heavy, macro-heavy, and full of edge cases that are perfectly valid in Confluence but awkward outside of it.

The first surprise: two pages that look visually similar in Confluence can serialize very differently in storage format. Tables, rich text blocks, code snippets, callouts, and macro output can appear in patterns that are not trivial to flatten into readable Markdown.

The second surprise was links: "a link to another Confluence page" is not a single thing. You encounter multiple URL shapes, embedded references, path-based forms, query-based forms, and links whose targets are obvious to Confluence but not obvious to your converter. If link extraction fails silently, your local mirror is technically present but functionally broken.

The third surprise was macros. Macros are one of Confluence's superpowers, but also one of the biggest export headaches. Some macros map cleanly to Markdown - like constructs. Others are effectively mini-apps embedded in page content. You need a strategy for graceful degradation, not perfect one-to-one fidelity. Your realistic goal is utility, not pixel-perfect cloning.

The key lesson was that conversion is not just a renderer problem. You are trying to preserve meaning and navigability under a different representation model. Once I accepted that, the implementation got better: normalize aggressively, preserve critical references, and be explicit about what gets transformed versus passed through. And I most likely missed lots of edge cases too. The best I could do was to cover the most common patterns I encountered and make sure the system is resilient to weird content rather than brittle.

The Pain of Comments and Attachments

After getting page conversion to a usable state, comments and attachments became the next wall.

Comments matter more than people think. In many organizations, the real decision history lives in comments: caveats, corrections, "do not do this anymore", and contextual notes that never made it into the page body. Exporting pages without comments creates a technically complete mirror that is practically incomplete.

Attachments are similar. A runbook that references scripts, screenshots, or PDFs is only useful if those references survive locally. Broken attachment links are almost worse than missing files, because they create false confidence.

In Confluence APIs, comments and attachments often come through different endpoints and different response shapes. They do not naturally slot into a naive page conversion pass. I had to treat them as first-class parts of the model: fetch, normalize, persist, and rewrite references so local files resolve correctly.

For comments, the practical choice was to append them into a clear section in each generated Markdown page. That keeps context colocated with the source page while staying machine-readable. For attachments, the rule was simple: if a page references a file and that file is in scope, download it and rewrite the reference to local path. If not, fail visibly.

Once those rules were in place, the mirror stopped feeling like an "export artifact" and started feeling like a usable documentation corpus.

The Pain of Updates

Then came the real operational problem.

A corporate Confluence space can have thousands of pages. Most runs happen because a small subset changed. Full recrawls are wasteful, slow, and expensive in API quota terms. If every update cycle requires reprocessing everything, people stop running updates, and your mirror becomes stale.

Initially, CQL looked like the obvious solution. Query pages by modification window, fetch only changed content, done. In theory, elegant. In practice, not sufficient.

Why it did not hold up in production:

CQL can tell you what changed according to indexed metadata, but does not magically solve all dependency and consistency issues for a local mirror. Link graphs can shift. Referenced pages may become relevant without being directly changed in a way your query catches at the right time. Some operational edge cases appear around indexing lag and query behavior that are tolerable in UI search but painful for deterministic synchronization.

I needed a model that prioritized reliable convergence over clever query shortcuts.

The solution became an incremental strategy backed by checkpoints and deterministic traversal behavior. In short: keep the crawl model stable, detect what is dirty versus reusable, and make update decisions based on explicit processing state rather than optimistic assumptions.

This is where the dual-checkpoint idea paid off:

A completed checkpoint tracks what finished processing.
A successful checkpoint tracks what finished with zero errors.

That split avoids a common failure mode where partial runs accidentally look "healthy" and poison future incrementals. You can advance progress while still preserving correctness signals.

The result is that updates mode can reuse clean artifacts aggressively while still rerendering genuinely dirty pages. It is fast enough to run frequently, and predictable enough to trust.

Technical Choices

Go was a deliberate choice, not just personal preference.

For CLI tools, Go gives you a very practical package: fast startup, straightforward concurrency, solid standard library, and simple deployment through static binaries. That matters when your users might run the tool in local shells, CI jobs, or mixed developer environments across operating systems.

The crawling workload itself also maps well to Go's model. You can manage concurrency and rate limiting cleanly without pulling in heavyweight runtime dependencies. The codebase stays compact and maintainable, which matters for a tool that has to evolve with API quirks.

On distribution, Go keeps friction low. Cross-platform release artifacts for Linux, macOS, and Windows are easy to automate, and users can download, extract, and run without installing language runtimes. For internal tooling adoption, that is a huge win.

From Chaos to a Working Mirror

At this point, the major blockers were resolved: conversion fidelity, link rewriting, comments and attachments, and incremental update correctness.

What emerged is not a one-off exporter but a repeatable mirror process. You can point it at seeds, run a full sync, then run updates regularly and keep a local Markdown representation of your Confluence knowledge that stays useful over time.

That sounds simple now, but it took several iterations to make "works once" become "works repeatedly under real constraints".

What Is It Good For

The first obvious use case is a personal or team second brain. Once content is local Markdown, people can search and browse with tools they already trust instead of relying entirely on Confluence UI behavior.

The second is offline and operational resilience. If network access is limited, if Confluence is degraded, or if you simply want a local snapshot for incident work, the mirror is immediately useful.

The third is versioned knowledge management. Putting mirrored docs in Git gives you history, diffs, and visibility into how operational knowledge evolves. That is valuable for onboarding, audits, and postmortems.

The fourth is machine workflows. Clean local Markdown plus metadata is a far better substrate for indexing and retrieval than trying to resolve everything live against Confluence APIs at query time.

In practice, this means one mirror can serve multiple audiences: humans browsing docs, engineers diffing changes, and AI systems consuming structured text.

Next Steps

The obvious next step is to feed the mirror into a RAG pipeline, but that should not mean "one page equals one chunk". That naive approach throws away structural signals and often hurts retrieval quality.

A stronger pipeline should chunk by semantic boundaries: headings, sections, and content blocks that correspond to coherent ideas. It should preserve metadata such as page ID, title, source URL, section path, and update timestamp. It should also account for duplicated content, stale snapshots, and link context that may improve answer grounding.

Another important step is retrieval strategy. Hybrid retrieval often works better than pure vector search for operational docs, because exact keywords (service names, env vars, incident IDs) matter. A good pipeline can combine lexical and semantic retrieval, then rerank with contextual scoring.

There is also room for change-aware indexing: when the mirror updates, only re-embed affected chunks and keep stable identifiers so downstream stores do not churn unnecessarily.

In other words, mirroring Confluence to Markdown is not the final destination. It is the foundation. Once that foundation is reliable, higher-level knowledge workflows become much easier to build correctly.

Conclusion

This project began as frustration with documentation discoverability and ended as a practical data pipeline for both humans and machines.

The core idea is simple: convert an operationally messy knowledge source into a local, readable, versionable, machine-friendly representation. The implementation was not simple at all, especially around conversion fidelity and incremental correctness, but the payoff is real: a Confluence space you can actually work with.

If this sounds useful for your team, the tool is open source and ready to run:
github.com/gkoos/confluence2md

Your Recursion Is Lying to You

Gabor Koos — Sat, 09 May 2026 17:04:40 +0000

Recursion is one of those ideas developers learn early and trust for years. If the recursive step is simple and the base case is correct, the code feels clean and safe.

It is elegant for a reason: many problems are naturally recursive, and the code often mirrors how we explain the logic out loud. For tree walks, nested structures, and divide-and-conquer patterns, recursion can be easier to read than explicit loops.

The catch is physical limits. Even with a correct base case and sound logic, each recursive call still consumes stack space. At some depth, you crash with stack overflow.

If you read Your Debounce Is Lying to You and Your Throttling Is Lying to You, this is the recursion version of the same pattern: elegant abstraction, hidden operational edge.

Problem Setup: Recursion Hits The Wall

You can run everything below directly in a browser console. Let's start simple: a recursive sum of all integers from 1 to n.

function sum(n) {
  if (n === 0) return 0;
  return n + sum(n - 1);
}

sum(10); // 55

Now push a big input:

sum(100000); // RangeError or InternalError: too much recursion in most JS runtimes

What just happened? The function is logically correct, but each call to sum stays on the stack until the one below it returns. At depth 100,000 the runtime runs out of stack space and throws. It has nothing to do with the result being wrong, it is purely a physical limit on how many nested frames the runtime can hold at once.

The Tail Recursion Rescue Story

The usual next step is tail call optimization. The idea is simple: make the recursive call the last thing the function does, so the runtime can reuse the same frame instead of pushing a new one.

Note that sum is not tail-recursive, even though the recursive call appears on the last line. After sum(n - 1) returns, there is still pending work: the result must be added to n. A call is only in tail position when its return value is forwarded immediately, with no pending computation afterward.

The tail-recursive version moves that pending state into an accumulator:

function sumTR(n, acc = 0) {
  if (n === 0) return acc;
  return sumTR(n - 1, acc + n);
}

sumTR(10); // 55

Here sumTR(...) is the very last thing that happens — no pending +, no pending anything. The running total lives in acc, not in waiting stack frames. In theory, a runtime that implements TCO can execute this in constant stack space regardless of depth.

Now repeat the same stress input:

sumTR(100000); // may still throw RangeError!

Even with correct tail-recursive structure, many JavaScript runtimes still allocate a new stack frame per call and throw at large depth. This surprises developers who expect TCO to be a universal guarantee. ECMAScript 2015 formally specified proper tail calls in strict mode, but most engines never adopted the feature consistently. Some shipped it and then walked it back due to performance regressions. Others never implemented it at all. The result is that you cannot assume tail recursion is stack-safe in production JavaScript, even if the code is correctly structured for TCO.

A Note on Fibonacci

Fibonacci is the go-to recursion textbook example and it does run into stack limits too, but it carries a second problem that makes it even worse: exponential time complexity.

function fib(n) {
  if (n <= 1) return n;
  return fib(n - 1) + fib(n - 2);
}

Each call branches into two more calls, so the total number of calls grows as O(2ⁿ). fib(30) already makes over a million calls; fib(50) is in the tens of billions. In a browser this freezes the tab long before any stack limit is reached, which makes the failure mode look identical to a stack overflow but have a completely different root cause.

The tail-recursive version of Fibonacci:

function fibTR(n, a = 0, b = 1) {
  if (n === 0) return a;
  if (n === 1) return b;
  return fibTR(n - 1, b, a + b);
}

This version runs in linear time, but it still risks stack overflow at large n due to the same TCO uncertainty. The exponential version is a red herring for this discussion because it fails for a completely different reason: stack overflow and exponential blowup are two separate problems. They look the same from the outside (the page hangs or crashes) but require completely different fixes.

Runtime Reality (At The Time Of Writing)

At the time of writing (May 2026), proper tail-call optimization support is not something you can count on across JavaScript runtimes.

Runtime	Engine	Proper Tail Calls You Can Rely On?	Practical Take
Chrome	V8	No	Do not expect stack-safe tail recursion.
Node.js	V8	No	Tail-recursive code can still overflow.
Deno	V8	No	Same operational expectation as Node/Chrome.
Firefox	SpiderMonkey	No	Do not treat tail recursion as a safety guarantee.
Safari	JavaScriptCore	Inconsistent — JSC has shipped and walked back TCO across versions	Do not rely on it; behavior has varied enough across releases that it is not a stable guarantee.
Bun	JavaScriptCore-based	Engine-dependent, not a cross-runtime guarantee	Verify on exact version; do not assume universal behavior.

The key point is portability. Tail recursion is a property of function structure, while stack reuse is a property of runtime implementation. Even if one engine behaves better in one version, production JavaScript usually spans multiple targets, and correctness should not depend on optimizer-specific behavior. A function can be perfectly tail-recursive in shape and still consume stack per call in the environments your users actually run.

Better Patterns for Production Code

Every recursive function can be rewritten iteratively, and that is usually the safest choice in production when input depth can grow. Iteration does not rely on runtime optimizations for stack safety, because it does not consume stack frames per step. This does not mean giving up the recursive mental model. You can still write code that is conceptually recursive but uses an explicit stack or a trampoline to manage control flow without hitting physical limits.

function sumIter(n) {
  let acc = 0;
  for (let i = n; i > 0; i--) acc += i;
  return acc;
}

sumIter(1000000); // no recursive stack growth

The Trampoline Pattern

If you want to keep the recursive structure for readability but need to avoid stack growth, you can use a trampoline: a loop that repeatedly calls a function that returns either a final result or another function to call.

function trampoline(fn) {
  let result = fn;
  while (typeof result === 'function') {
    result = result();
  }
  return result;
}

function sumTrampoline(n, acc = 0) {
  if (n === 0) return acc;
  return () => sumTrampoline(n - 1, acc + n);
}

trampoline(() => sumTrampoline(100000)); // no stack overflow, still tail-recursive in spirit

Trampolines trade stack safety for additional function allocations and dispatch overhead, so they are most useful when preserving recursive structure matters more than raw performance.

This approach scales in a way that does not depend on runtime tail-call behavior, which is exactly what you want when input depth can grow. If recursive structure improves readability for a particular problem, these techniques let you keep that mental model with explicit tradeoffs instead of implicit runtime assumptions.

A useful rule of thumb is to keep recursion for small, bounded depths that you control, and switch to iterative control flow as soon as depth is user-driven, data-driven, or operationally uncertain. For hot paths, benchmark both styles, but do not base correctness on assumed TCO.

Practical Checklist

Never assume TCO in JavaScript for production-critical paths.
Test with realistic upper bounds, not toy input sizes.
Favor iterative implementations when depth can grow.
Treat recursion as a readability tool, not a stack-safety guarantee.

Conclusion

Recursion itself is not the enemy, unverified runtime assumptions are. Tail-recursive shape does not automatically make JavaScript stack-safe, and that gap is where many "works on my machine" surprises come from in production.

Use recursion where it improves clarity and depth is genuinely bounded. When depth can grow or input is outside your control, prefer iterative designs that make stack behavior explicit and portable.

Decorating Promises Without Breaking Them

Gabor Koos — Fri, 10 Apr 2026 14:18:20 +0000

I wanted .get().json().

This came up while building convenience plugins for ffetch, a lightweight fetch wrapper focused on keeping native semantics intact. Libraries like ky solve the ergonomics problem by introducing a custom Response-like object, which works great until something outside the library expects a plain Response. I wanted a different path.

Not because I needed it, strictly speaking. await fetch('/api/todos/1') followed by await response.json() works perfectly fine. But after the hundredth time writing that two-step dance across a codebase, you start reaching for something cleaner.

The usual answer is a wrapper class or a custom Promise subclass. Both work, but both carry a hidden cost: you are now responsible for whatever happens when you swap out the native Response for your own abstraction. instanceof checks break. Framework integrations that inspect the response directly can behave unexpectedly. And the moment someone passes your custom object into something that expected a plain Response, you have a problem.

I wanted a different answer. This is about that.

The Goal

The cleaner call site I was after looks like this:

const todo = await client.get('/api/todos/1').json()

Two requirements in tension. On one hand, .json() should be reachable without a separate await and variable assignment. On the other hand, await client.get('/api/todos/1') should still resolve to a genuine, unmodified Response — not a wrapper, not a subclass, not a Proxy.

Most approaches collapse this tension by picking one side. Either you get ergonomics and lose native semantics, or you keep native semantics and write the two-liner. The question is whether you can actually have both.

The Mechanism

A Promise in JavaScript is an object. Like any object, you can assign properties to it at runtime.

That is the whole trick. Instead of wrapping the Promise or replacing it with something else, you decorate it in place: attach the convenience methods directly as properties on the Promise instance returned by the fetch call.

Here is what that looks like in practice:

function attachResponseShortcuts(promise: Promise<Response>) {
  const descriptor = (fn: (r: Response) => unknown) => ({
    value: function (this: Promise<Response>) {
      return this.then(fn)
    },
    enumerable: false,
    writable: false,
    configurable: false,
  })

  Object.defineProperties(promise, {
    json:        descriptor((r) => r.json()),
    text:        descriptor((r) => r.text()),
    blob:        descriptor((r) => r.blob()),
    arrayBuffer: descriptor((r) => r.arrayBuffer()),
    formData:    descriptor((r) => r.formData()),
  })

  return promise
}

A few things are happening here that are worth unpacking.

Property descriptors, not assignment. Using Object.defineProperties instead of promise.json = fn gives explicit control over the property attributes. Each method is enumerable: false which means it stays invisible to for...in loops, Object.keys, and JSON serialization. (They will still show up in browser DevTools when you expand the object and in Object.getOwnPropertyDescriptors(), but that is useful for debugging anyway — the point is they do not pollute standard iteration or JSON output.) It is writable: false and configurable: false, so it cannot be accidentally overwritten or deleted at runtime. This is intentional: without these locks, a careless reassignment (promise.json = myMock) would silently break the convenience layer for everyone holding that promise. The tradeoff is that it also prevents intentional overrides — if you need to mock .json() in a test, you cannot. This is a deliberate choice favoring safety over flexibility.

Forwarding, not reimplementing. Each method is a one-liner that calls .then() on the Promise itself (via this) and delegates immediately to the native Response method. The parsing behavior, error handling, and body consumption rules all come from the browser or runtime. We are not reimplementing anything. The methods are thin pass-throughs.

The Promise remains a Promise. await client.get('/api/todos/1') still resolves to the same native Response it always did. The added methods live on the instance itself, not on the prototype chain like native methods do — they are invisible properties on the Promise object. They do not affect the resolution value, the prototype chain, or any standard Promise behavior. (This is a meaningful difference: calls to promise.constructor or Object.getPrototypeOf(promise) see an untouched Promise, not a subclass or wrapper.)

Idempotency

If multiple plugins or hooks might touch the same promise — which is the case in a plugin-based architecture — you need to guard against decorating the same object twice. Object.defineProperties will throw if you try to redefine a non-configurable property.

A marker handles this, and this is one of the rare cases where a Symbol is genuinely useful: it provides collision-free identity that no other code can accidentally claim.

const DECORATED = Symbol('ffetch.responseShortcutsDecorated')

function attachResponseShortcuts(promise: Promise<Response>) {
  if ((promise as any)[DECORATED]) return promise

  // ... defineProperties ...

  Object.defineProperty(promise, DECORATED, { value: true, enumerable: false })
  return promise
}

The marker is invisible to Object.keys, Object.getOwnPropertyNames, and iteration — only findable via Object.getOwnPropertySymbols if you explicitly look for it. Decoration becomes a safe, idempotent operation regardless of call order, with zero risk of collision with any third-party code or browser internals.

Typing It

TypeScript does not know about properties you attach at runtime, so you have to tell it. The cleanest model here is an intersection type: the call site return type is Promise<Response> intersected with the shortcut interface.

interface ResponseShortcuts {
  json<T = unknown>(): Promise<T>
  text(): Promise<string>
  blob(): Promise<Blob>
  arrayBuffer(): Promise<ArrayBuffer>
  formData(): Promise<FormData>
}

type DecoratedPromise = Promise<Response> & ResponseShortcuts

This is honest. DecoratedPromise really is both things simultaneously: a standard Promise that resolves to Response, and an object that happens to have five extra methods. The intersection expresses both without hiding either.

When the library does not have the plugin installed, the return type is Promise<Response> with no extras. When it does, it is Promise<Response> & ResponseShortcuts. TypeScript catches you if you try to call .json() without the plugin, and it autocompletes when you have it. No runtime cost either way.

Tradeoffs Worth Naming

This technique is additive, not transformative. That is its strength and its limit.

It cannot change what Response contains. If you call .json() on a response that came back with a text/html body, you get the same parse error you would have got with the two-liner. The shortcut is a convenience, not a type-safe schema layer.

Body consumption rules are also unchanged. Response bodies can only be read once — calling .json() and then separately awaiting the response and calling .json() again will fail, exactly as native fetch would. Decoration does not change the underlying object.

The TypeScript types also do not capture body consumption state. If the response body was already read (e.g., by an upstream handler or middleware), calling .json() will throw at runtime. TypeScript will not catch this — the types express the structural shape of the methods, not the preconditions for their success. This is a general limitation of modeling Response state in TypeScript, not specific to this technique, but it is worth knowing: the intersection type Promise<Response> & ResponseShortcuts is a shape guarantee, not a behavioral one.

And if you or your team prefer strict explicitness — no augmented promise objects, all parsing explicit — then this pattern is probably not the right call. It is a style choice. The native two-liner is perfectly readable, just longer.

Where this genuinely shines is in a plugin or middleware architecture where you want to offer ergonomics as opt-in behavior. The baseline remains untouched, native fetch-compatible, and requires zero knowledge of the convenience layer to work with.

The Broader Point

What I find interesting about this technique is that it demonstrates a property of JavaScript that is easy to forget: objects are open. A Promise is not a sealed system. You can extend it in flight without wrapping or subclassing, and without disturbing the contract anyone else has with it.

Preserve native behavior first. Layer ergonomics second, explicitly, and as close to invisibly as possible.

If the shortcut is there and you use it, you gain a line. If the shortcut is there and you do not use it, nothing changes. That is the shape of a good opt-in.

The full implementation lives in ffetch if you want to see it in context. But the technique itself applies anywhere you need to decorate promises with convenience methods.

Introducing the Fetch Client Chaos Arena

Gabor Koos — Sun, 05 Apr 2026 13:40:02 +0000

There are many HTTP clients in the JavaScript ecosystem, and while they all solve similar problems, they can behave very differently under stress, retries, and failures. Picking the right one is not always straightforward.

Introducing ffetch-demo: a live browser arena for benchmarking JavaScript HTTP clients under controlled network chaos. The idea is simple: run the same request workload through different clients and compare how they behave when conditions get rough.

In the demo, you can configure chaos scenarios such as:

latency injection
random failures and drops
status-code spikes
retry pressure and timeout stress

Built With chaos-fetch

The chaos layer in the arena is powered by @fetchkit/chaos-fetch, which makes it easy to apply deterministic and randomized network stressors through middleware-style configuration.

npm: @fetchkit/chaos-fetch
GitHub: fetch-kit/chaos-fetch

Current clients in the arena:

native fetch
axios
ky
@fetchkit/ffetch

The output focuses on practical reliability signals (success/failure rates, error patterns, and latency distributions) so you can quickly see behavioral differences between clients.

Live demo: fetch-kit.github.io/ffetch-demo

GitHub: fetch-kit/ffetch-demo

Your Debounce Is Lying to You

Gabor Koos — Sat, 28 Mar 2026 06:52:27 +0000

Debounce is one of those patterns every frontend developer learns early and keeps using forever.

At its core, debouncing does one thing well: it coalesces a burst of calls into one invocation after a quiet window. That is a great fit for noisy UI signals.

Its most familiar use case is autocomplete, but the same pattern applies to resize handlers, scroll listeners, live validation, filter controls, and telemetry hooks.

A typical implementation looks like this:

function debounce(fn, delay) {
    let timer;
    return (...args) => {
        clearTimeout(timer);
        timer = setTimeout(() => fn(...args), delay);
    };
}

const search = debounce(async (q) => {
    const res = await fetch(`/api/search?q=${q}`);
    const data = await res.json();
    render(data);
}, 300);

It looks disciplined. It feels efficient. It ships fast.

And this is where the title comes from.

The issue is not debounce itself. The issue is this vanilla debounce + fetch pattern once real network behavior enters the picture.

It gives the feeling that requests are "under control," but it does not control request lifecycle: response ordering, cancellation of stale work, or failure behavior.

That is why it feels like debounce is "lying" in production: the UI looks smoothed, while the network layer is still fragile.

In this article, we will keep debounce for what it is good at (UI smoothing), then harden the request path with cancellation, retries, and better error handling.

The Illusion of "Fixed" Behavior

Debounce is convincing: you type quickly, the UI triggers fewer calls, and the network tab looks quieter. It feels like the system is now stable. But in production, under real network conditions, many things can go wrong. You will experience stale data, wasted requests, silent failures and other unexpected behaviors.

This is true for any network request, but debounce adds another layer of complexity: it makes the UI look smooth while the network can still be unpredictable. This mismatch can create a false sense of security.

Debounce itself only guarantees one thing:

"I won't call this function too often."

Debounce smooths input frequency, not request lifecycle. It does not guarantee:

Responses arrive in order.
Stale requests stop running.
Failures are handled consistently.

In other words: it is a UI pattern, not a network pattern. So you have to make sure the underlying network layer is robust enough to handle real-world conditions. Before we examine what can go wrong, let's set the stage!

The Companion Code

To make these problems visible, we have a companion demo app with a single text input where every keystroke triggers a debounced request to /api/echo?q=<input>. The backend is an Express server that returns { query, timestamp }, and the frontend appends each response to a div as query@timestamp. The stack is minimal: Node.js + Express on the backend, and plain HTML/CSS/JavaScript in the browser.

Clone the repo and install dependencies:

git clone https://github.com/gkoos/article-debouncing.git
cd article-debouncing
npm install

Then start the app:

npm start

And navigate to http://localhost:3000 in your browser. You will see something like this:

Now, as you type in the input field, you will see the responses coming back in the list below:

The UI also shows toast notifications for request success and failure, which will become relevant in later sections.

This is our baseline setup, it demonstrates the basic pattern. There is a 300ms debounce on the input, and the backend immediately responds with the query and a timestamp. The UI appends each response to the list.

Problem 1: Race Conditions (aka Stale UI)

On your local machine, everything is fast and smooth. But in production, network conditions are unpredictable. Requests can take varying amounts of time to complete, so there is no guarantee that responses will arrive in the same order they were sent. Let's see what happens if we add random delays to the server response to simulate real network conditions.

Check out the 01-stale-requests branch and restart the server:

git checkout 01-stale-requests
npm start

We added a middleware that introduces a random delay of 0–1000ms for each request. Now, when you type quickly, you might see responses arriving out of order:

We typed 12345678, but the UI shows 1234567! The response for 7 came back after 8, so the UI is now stale. This is a classic race condition, and debounce itself does not prevent it. The UI is showing results for an older query, which can lead to confusion and errors in a real application.

How to fix this? We need to ensure that only the latest request's response is processed, and any previous requests are either cancelled or ignored. We could implement a simple version of this by keeping track of the latest query and ignoring responses that don't match it. But that would still allow all requests to run, which is inefficient. A better approach is to use the AbortController API to cancel stale requests, so they don't consume resources or trigger side effects when they complete.

AbortController is a browser-native API. You create a controller, pass its signal to fetch, and call abort() whenever you want to cancel the request. The fetch will throw an AbortError, which you can catch and ignore since it's expected.

Here is the updated debounce callback with cancellation:

let controller;

const debouncedFetch = debounce(async (q) => {
  if (!q) return;

  if (controller) controller.abort();
  controller = new AbortController();

  try {
    const response = await fetch(`/api/echo?q=${encodeURIComponent(q)}`, {
      signal: controller.signal
    });
    const data = await response.json();
    // render data...
  } catch (err) {
    if (err.name === 'AbortError') return;
    // handle real errors...
  }
}, 300);

Two things changed:

Before each request, we abort any in-flight request from the previous call and create a fresh controller.
After catching an error, we check if it's an AbortError and return early: these are expected and not real failures.

The result: in normal flow, only the last request in a typing burst ever completes. Previous ones are cancelled at the network level, not just ignored after the fact. (For absolute safety, you can also guard the render step with a request ID check. This covers the tiny edge window where a response resolves right before a newer request aborts the previous one.)

Problem 2: Network Failures

The network is not only unpredictable in terms of latency, but also in terms of reliability. Sometimes a request can fail that would have succeeded if retried. This can be due to transient server issues like network congestion, temporary spikes in load, or database timeouts. If we want a more robust user experience, we need to handle these failures gracefully.

Let's simulate random failures in our backend. Check out the 02-failures branch and restart the server:

git checkout 02-failures
npm start

This version of the server adds a random failure mechanism: each request has a 40% chance to fail with a 500 error. Now this may be too aggressive, but it will help us see the problem clearly. When you type in the input field, you will see some requests fail:

Well, that's not good. First, our UI shows undefined@undefined when a request fails. That happens because the server returns { error: 'Internal Server Error' } on a 500, so data.query and data.timestamp are both undefined. Vanilla fetch doesn't throw on HTTP error status codes: it only rejects on network failures. So we need to check response.ok ourselves:

const response = await fetch(`/api/echo?q=${encodeURIComponent(q)}`, {
  signal: controller.signal
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

Now a 500 throws before we ever touch the body, the catch handles it, and the error toast shows instead of broken output.

But that's just the start. In a real app, you would want to implement some retry logic for transient failures. For example, you could automatically retry a failed request up to 3 times with exponential backoff. This way, if a request fails due to a temporary issue, it has a chance to succeed without the user having to do anything.

To implement this manually you'd need to write retry loops, track attempt counts, implement backoff timing, and make sure none of it fires after a cancellation. That's not trivial, and it's not the interesting part of your app, so let's use a library for that.

@fetchkit/ffetch is a thin wrapper around fetch that handles exactly this. We'll use it for the retry behavior in our demo.

There are good alternatives in this space (for example ky, axios, or a custom wrapper). I chose ffetch here because it keeps a fetch-compatible API surface and handles abort-aware retries cleanly.

Since this is a minimal demo with no build step, we load it directly from a CDN rather than installing it. In a real project you'd npm install @fetchkit/ffetch and import it normally, but here a single import line is enough:

import { createClient } from 'https://esm.sh/@fetchkit/ffetch';

const api = createClient({
  retries: 3, // retry up to 3 times on failure
  shouldRetry: (ctx) => ctx.response?.status >= 500, // only retry on 5xx errors
});

api has the exact same call signature as fetch: same arguments, same return type. You drop it in as a replacement:

const response = await api(`/api/echo?q=${encodeURIComponent(q)}`, {
  signal: controller.signal
});

What this buys us in this specific scenario:

retries: 3 — if the server returns a 500, ffetch retries up to 3 more times before giving up
shouldRetry — we only retry on 5xx; anything else (network error, abort) propagates immediately
abort-aware backoff — if controller.abort() fires during the delay between retries, the wait exits immediately and the abort propagates; no stale work keeps running in the background

That last point is quite convenient here. Without it, aborting a request mid-retry would cut the active fetch but leave the backoff timer running, which would then fire another fetch attempt that instantly aborts. Now we handle this correctly.

There's one more thing we can clean up. Because the native fetch does not throw on HTTP error status codes (one of the pain points of the API), we had to add a manual check:

if (!response.ok) throw new Error(`HTTP ${response.status}`);

ffetch can handle this too. With the throwOnHttpError: true config option, any HTTP error response throws automatically, no manual check needed.

const api = createClient({
  retries: 3,
  shouldRetry: (ctx) => ctx.response?.status >= 500,
  throwOnHttpError: true,
});

Now the fetch call is just:

const response = await api(`/api/echo?q=${encodeURIComponent(q)}`, {
  signal: controller.signal
});
const data = await response.json();

The catch block still handles everything - HTTP errors, network failures, real errors - without any extra branching in the happy path.

The final implementation can be found in the 03-fixed branch:

git checkout 03-fixed
npm start

For reference, the full code for the debounce callback with ffetch can be found here.

Conclusion

Debounce is not the problem. The problem is treating it as a complete solution for network control when it only handles one dimension of it: call frequency. It is a very useful pattern for smoothing out noisy UI signals, but it does not handle the complexities of real network behavior. To build a robust application, you need to complement debounce with proper request lifecycle management: cancellation of stale requests, retries with backoff for transient failures, and consistent error handling. This way, you can ensure that your UI remains not only responsive but also accurate even under unpredictable network conditions.

Developing and Benchmarking the Same Feature in Node and Go

Gabor Koos — Thu, 19 Mar 2026 19:43:56 +0000

When I started building chaos-proxy, the initial goal was simple: make API chaos testing practical for JavaScript and TypeScript teams. I wanted something that could sit between an app and its upstream API and introduce realistic turbulence on demand: latency spikes, intermittent failures, and other behavior that makes integration tests feel closer to production.

Node.js was the obvious first runtime for that because the ecosystem, tooling, and middleware ergonomics are excellent for rapid iteration. It is hard to overstate how productive that setup is when the main audience is already living in npm, TypeScript, and JavaScript test runners.

Later, I rewrote the same proxy in Go to push raw proxy performance further and support higher throughput under load. The intent was not to replace one with the other philosophically, but to explore a different optimization frontier with the same product idea.

This post documents what happened when I implemented the same non-trivial feature in both runtimes: hot config reload. Then I reran the benchmark from my previous article to see how the newer versions compare.

The interesting part is not only the final numbers. It is also how two mature runtimes guide you toward different internal designs, even when you are enforcing the same external behavior contract.

Old benchmark post:
https://blog.gaborkoos.com/posts/2025-10-11-Nodejs-vs-Go-in_Practice-Performance-Comparison-of-chaos-proxy-And-chaos-proxy-go/

Repositories:

Node implementation: https://github.com/fetch-kit/chaos-proxy
Go implementation: https://github.com/fetch-kit/chaos-proxy-go

Implementing Hot Config Reload in Two Runtimes

The goal of hot config reload was to allow users to update the proxy's behavior without downtime. This means that when a new config is posted to the /reload endpoint, the proxy should parse, validate, and apply the new configuration atomically, without interrupting in-flight requests. This enables advanced testing scenarios where you can change the chaos behavior on the fly to model dynamic production conditions like feature rollouts, traffic shifts, or evolving failure modes.

Both implementations follow the same external contract:

POST /reload accepts a full config snapshot
Parse -> validate -> build -> swap, all-or-nothing
Deterministic in-flight behavior (request-start snapshot semantics)
Reject concurrent reload requests
Consistent status model (400, 409, 415, success returns version and reload duration)

So the user-facing behavior is aligned. Clients see the same API and guarantees. The internal shape is where Node and Go felt very different.

Runtime model

Node leaned toward a dynamic runtime object: rebuild middleware/router chain, then swap the active runtime. That style maps naturally to the way Node applications are often composed. Rebuilds are straightforward to express, and the overall control flow stays compact.

Go leaned toward immutable runtime snapshots: config + router + version behind an atomic pointer. In practice, this makes the runtime feel more explicit. You can point to exactly what a request observed and exactly when a new version became active.

Concurrency model

In Node, most complexity is around making reload writes serialized and safe while requests continue flowing.

In Go, the read/write split is explicit: request path loads one snapshot at request start, reload path builds fresh state under lock, then atomically swaps.

Behaviorally both approaches are equivalent from a user perspective. The difference is mostly in how obvious the invariants are when you revisit the code weeks later.

In-flight guarantees

Both versions guarantee request-start snapshot semantics.

In Node, this is easier to accidentally violate if mutable shared state leaks into request handling.

In Go, the pointer-load-at-entry pattern makes this guarantee structurally harder to violate.

That was one of the strongest practical contrasts for me: same requirement, different default safety profile.

Router lifecycle and rebuild mechanics

Node composition is lightweight and ergonomic for rebuilds.

Go rebuilds a fresh router and re-registers middleware/routes on each reload. Behavior is explicit and predictable at the snapshot level, with middleware execution order deterministic only when config uses ordered list elements (not multiple keys in one map). It can look verbose at first, but this explicitness pays off when debugging edge cases around reload timing.

Validation and rollback boundaries

Both use the same pipeline: parse -> validate -> build -> swap.

Node gives more dynamic flexibility but needs stricter guard discipline.

Go's type-driven pipeline made failure paths and rollback behavior cleaner to reason about.

In both runtimes, treating build and swap as separate phases was the key to keeping rollback semantics simple.

Stateful middleware behavior

Both implementations rebuild middleware instances on reload. That means in-memory middleware state (for example counters or local token buckets) resets by design after a successful reload. This is intentional and worth calling out to users because it is product behavior, not an implementation accident.

Benchmark Rerun

After adding hot config reload support, I reran the old benchmark setup.

The goal here was not to produce an absolute, universal number for every environment. The goal was to keep methodology stable enough to compare the old and new versions and see whether the relative shape changed.

System and Test Environment (Same Machine as the Old Article)

This rerun was executed on the same machine as the benchmark in the previous article, with the same local topology (Caddy backend on localhost, proxy on localhost, load generated by hey on the same host).

Machine characteristics:

CPU: AMD Ryzen 7 5800H with Radeon Graphics
Cores/Threads: 8 cores / 16 threads
Base clock: 3.2 GHz
RAM: 16 GB DDR4
OS: Windows 10 Home 22H2 64-bit

Benchmark setup characteristics:

Backend: Caddy serving /api/hello on localhost:8080
Proxy target: localhost:5000
Load generator: hey
Command pattern: hey -n 1000 -c 50 http://localhost:/api/hello
Runs per scenario: 3 (median reported)

Reproducibility command block (same pattern used for this article):

# 1) Start Caddy backend
./caddy.exe run --config Caddyfile

# 2) Baseline (direct Caddy)
for i in 1 2 3; do ./hey -n 1000 -c 50 http://localhost:8080/api/hello | tee -a baseline-caddy-runs.txt; done

# 3) Node proxy benchmark (in another terminal, start proxy first)
npx chaos-proxy --config chaos.yaml
for i in 1 2 3; do ./hey -n 1000 -c 50 http://localhost:5000/api/hello | tee -a node-3.0.1-runs.txt; done

# Stop the Node proxy process before running the Go proxy benchmark (both use port 5000)

# 4) Go proxy benchmark (in another terminal, start proxy first)
./chaos-proxy-go.exe --config chaos.yaml
for i in 1 2 3; do ./hey -n 1000 -c 50 http://localhost:5000/api/hello | tee -a go-0.2.1-runs.txt; done

Versions in this rerun:

chaos-proxy (Node): 3.0.1
chaos-proxy-go (Go): 0.2.1

I also verified response-size parity for fairness:

Caddy: 94 bytes/request
Node 3.0.1: 94 bytes/request
Go 0.2.1: 94 bytes/request

This check mattered because an earlier Node run returned compacted JSON (smaller payload), which could bias throughput. The final numbers below use matched response sizes.

Current Rerun (Median of 3)

Scenario	Requests/sec	Avg Latency (s)	P99 Latency (s)
Direct Caddy	24,912.1845	0.0018	0.0156
chaos-proxy Node 3.0.1	3,788.0065	0.0129	0.0318
chaos-proxy-go 0.2.1	7,286.8293	0.0062	0.0248

Old Benchmark Reference (from previous post)

Scenario	Requests/sec	Avg Latency (s)	P99 Latency (s)
Direct Caddy	28,383.8519	0.0016	0.0116
chaos-proxy Node 2.0.0	4,262.3420	0.0115	0.0417
chaos-proxy-go 0.0.5	8,828.0577	0.0053	0.0140

What changed?

1) Go vs Node in current versions

Go is still clearly ahead.
Throughput: Go is about 1.92x higher than Node (7286.8 vs 3788.0 req/sec).
Average latency: Node is about 2.08x slower than Go (0.0129s vs 0.0062s).

2) Go old vs Go new

Throughput decreased from 8828.1 to 7286.8 req/sec (~17.5% lower).
Average latency increased from 0.0053s to 0.0062s (~17.0% higher).
P99 increased from 0.0140s to 0.0248s.

3) Node old vs Node new

Throughput decreased from 4262.3 to 3788.0 req/sec (~11.1% lower).
Average latency increased from 0.0115s to 0.0129s (~12.2% higher).
P99 improved from 0.0417s to 0.0318s.

Adding hot-reload-safe runtime mechanics introduces measurable overhead even in steady-state forwarding paths, which is why both implementations are slower than their previous versions in this benchmark shape.

I did not trigger reloads during benchmark traffic, so this should be interpreted as structural overhead from the runtime architecture needed to guarantee safe reload semantics, not reload execution cost itself.

Why There Is Overhead Even Without Calling /reload

Even if reload is never triggered during the benchmark request stream, the hot reload feature still changes the steady-state architecture:

Requests now run through runtime indirection designed for safe snapshot semantics.
Runtime objects and routing/middleware composition are organized around swap-ready boundaries.
Concurrency guards and state-boundary discipline are now part of the normal request path design.

In other words, the cost is not from running /reload repeatedly during the test. The cost comes from maintaining reload-safe invariants all the time.

Conclusion

Implementing the same feature in Node and Go was one of the most useful engineering exercises I have done in a while.

The final behavior contract can be identical across runtimes, but the implementation pressure points are very different:

Node emphasizes dynamic composition and careful mutation control.
Go emphasizes snapshot immutability and explicit concurrency boundaries.

Performance-wise, the high-level outcome still holds: the Go proxy remains roughly 2x faster than the Node proxy in this benchmark shape. At the same time, both implementations are now better specified in terms of live reconfiguration semantics, which was the actual feature goal. The implementations are likely not fully performance-tuned yet. For now, that trade-off is acceptable for the feature guarantees we wanted.

And yes, it was genuinely fun to build.

From the Database Zoo to the Database Safari

Gabor Koos — Tue, 10 Mar 2026 01:46:38 +0000

Over the past year I've been writing a series called The Database Zoo, exploring the growing ecosystem of modern databases. The idea behind the series was simple: instead of treating "the database" as a single category, look at the different species that exist today - probabilistic databases, time-series systems, vector databases, and more - and understand why they were built and what problems they solve.

While working on the series, it became clear that the topic deserved a more structured and expanded treatment.

That work eventually turned into a book.

I'm currently writing The Database Safari, to be published by Apress (Springer Nature). The book grows out of the ideas in the Database Zoo series, but develops them into a more cohesive guide to specialized databases: how they work internally, what trade-offs they make, and when they make sense in real systems.

The book is already listed on SpringerLink:

https://link.springer.com/book/9798868827082

I'll share more updates as the writing progresses.

Using Pagination to Improve GraphQL Performance

Gabor Koos — Thu, 19 Feb 2026 22:42:13 +0000

GraphQL makes it easy to request exactly the data you need, but that flexibility can quickly turn into a performance problem when queries return large result sets. A single field that returns "all items" may work fine during development, yet silently degrade into slow responses, high memory usage, or even process crashes as data volume grows.

This is especially relevant in Node.js backends, where resolvers often materialize entire result sets in memory before returning a response. Fetching a large number of records in a single GraphQL query doesn't just increase response time, it can put sustained pressure on the event loop, garbage collector, and overall process stability.

Pagination is the standard solution to this problem, but not all pagination strategies behave the same under load.

In this article, we'll look at three common approaches to pagination in a Node.js GraphQL API: fetching everything at once, offset-based pagination, and cursor-based pagination. Rather than treating pagination as a purely theoretical concern, we'll instrument each approach and observe how it affects response times and memory usage.

We'll build a minimal GraphQL API using Express and Apollo Server, backed by a SQLite database seeded with 500,000 products. You'll see how naive queries show up as slow requests and memory spikes, how offset-based pagination improves things but still has hidden costs, and why cursor-based pagination is - spoiler alert! - the recommended pattern for stable, scalable GraphQL APIs.

Setting Up the Project

To keep things simple, the article is accompanied by a runnable demo repository. The project is a small Node.js GraphQL API, with a SQLite backend populated with 500,000 products.

Prerequisites

To follow along, you'll only need:

Node.js 18+
npm
A basic understanding of GraphQL and Node.js development

Installation

Start by cloning the repository and installing dependencies:

git clone https://github.com/gkoos/article-graphql-pagination
cd article-graphql-pagination
npm install

The project uses Prisma with SQLite and includes a seed script that creates 500,000 product records to demonstrate performance differences between pagination strategies.

Run the following commands to initialize and seed the database:

npx prisma generate
npm run prisma:migrate
npm run prisma:seed

This will create the database schema and populate it with realistic-looking product data.

Running the Server

Once setup is complete, start the server:

npm start

The GraphQL API will be available at http://localhost:4000, where you can explore the schema and run queries using the Apollo Sandbox.

The Problem: Fetching All Data at Once

Before introducing pagination, let's start with the simplest approach: returning all records from a GraphQL field in a single request.

In our app, the allProducts query does exactly that. It loads all 500,000 products from the database and returns them as a single response. This kind of query is easy to write, easy to understand, and surprisingly common in early GraphQL schemas.

Here's the resolver behind it:

// src/resolvers.js
...
allProducts: async () => {
    console.time('allProducts');
    const products = await prisma.product.findMany({
    orderBy: { id: 'asc' }
    });
    console.timeEnd('allProducts');
    console.log(`Fetched ${products.length} products (ALL)`);
    return products;
},

There's nothing technically wrong with this resolver. It does exactly what it promises. The problem is scale.

Running the Fetch-All Query

Open the GraphQL Sandbox at http://localhost:4000 and run the following query:

query allProducts {
  allProducts {
    id
    name
    price
    category
  }
}

Depending on your machine, the query may take several seconds to complete. You'll also notice that the response payload is very large: hundreds of thousands of objects serialized into JSON and sent over the wire in one go.

In your terminal, you should see a log message like this:

allProducts: 2.817s
Fetched 500000 products (ALL)

A single request:

Executes a large database query
Allocates memory for all 500,000 rows
Serializes the entire result set before responding

In a real production API, this kind of request can quickly become problematic under concurrent load.

Why This Pattern Breaks Down

Even in this local setup, you can observe:

High response times (often several seconds)
Significant memory usage spikes during request processing

Because the resolver loads the entire dataset eagerly, the cost of this query scales linearly with the number of rows in the table. As the dataset grows, so does response time, memory pressure, and GC activity in the Node.js process.

This is one of those things that often goes unnoticed during development, but becomes very visible once real data and real traffic hit the system.

Fetching all data at once has a few fundamental problems:

Unbounded results: There's no upper limit on how much data a client can request.
Poor memory characteristics: Large result sets must be held in memory until the response is sent.
Unpredictable performance: Response time grows with dataset size, not request intent.
Easy to abuse: A single client can unintentionally (or intentionally) stress the backend.

Pagination exists to put boundaries around this behavior.

Naive Offset-Based Pagination

A natural first step after realizing that fetching everything at once doesn't scale is to introduce offset-based pagination. This approach limits the number of records returned per request and allows clients to "page through" results using a combination of limit and offset.

Offset-based pagination is simple to implement and easy to reason about, which makes it a common choice in REST APIs and an equally common first attempt in GraphQL.

Implementing Offset Pagination

In our demo project, the productsOffset query exposes this pattern:

// src/resolvers.js
...
productsOffset: async (_, { limit, offset }) => {
    console.time('productsOffset');
    if (limit > 100) {
        limit = 100; // enforce a maximum limit to prevent abuse
    }
    const products = await prisma.product.findMany({
    take: limit,
    skip: offset,
    orderBy: { id: 'asc' }
    });
    console.timeEnd('productsOffset');
    console.log(`Fetched ${products.length} products (offset: ${offset}, limit: ${limit})`);
    return products;
},

One thing that's important to note here is if we don't limit the number of records returned, we could still end up fetching everything at once. Always implement a server-side maximum limit to prevent abuse.

The resolver uses Prisma's take and skip options to implement limit and offset behavior. Clients can specify how many records they want (limit) and where to start (offset).

The corresponding GraphQL query looks like this:

query productsOffset {
  productsOffset(limit: 20, offset: 0) {
    id
    name
    price
    category
  }
}

Instead of returning all 500,000 products, this query fetches just a small window of results. Clients can request subsequent pages by increasing the offset value.

Observing the Improvement

Run the offset-based query a few times from the GraphQL Sandbox, changing the offset to simulate paging through the dataset.

In your terminal, you should see logs like this:

productsOffset: 17.44ms
Fetched 20 products (offset: 0, limit: 20)

Compared to the fetch-all approach, you should immediately notice:

Much faster response times
Shorter database query time
Lower overall memory usage per request

By limiting how many records are loaded and serialized, offset-based pagination dramatically reduces the per-request cost. Even under load, this approach is far more stable than returning everything at once.

The Hidden Cost of Offsets

While offset-based pagination is a clear improvement, it comes with a less obvious downside.

As the offset value increases, the database still needs to scan past the skipped rows to reach the requested page. For small offsets this isn't a problem, but deeper pages can become increasingly expensive, especially on large tables.

Let's query the last page of products:

query productsOffset {
  productsOffset(limit: 20, offset: 499980) {
    id
    name
    price
    category
  }
}

Run this query and observe the terminal logs:

productsOffset: 1.055s
Fetched 20 products (offset: 499980, limit: 20)

In this particular case, the first query took 17ms, while the last page took more than a second!

From the client's perspective, this query looks almost identical to fetching the first page, but from the database's perspective, it may involve scanning hundreds of thousands of rows before returning just 20.

Why This Matters in GraphQL APIs

Offset-based pagination also has semantic issues in GraphQL:

Unstable pagination: Inserts or deletes can shift offsets, causing clients to skip or duplicate items.
No natural continuation: Clients must manage offsets manually.
Poor fit for infinite scrolling: Large offsets become increasingly inefficient.

These limitations are why offset-based pagination is generally considered a transitional solution in GraphQL APIs.

Cursor-Based Pagination

Offset-based pagination improves performance by limiting result size, but it still becomes less efficient as clients paginate deeper into a dataset. In GraphQL APIs, the recommended alternative is cursor-based pagination, where each page starts from a known position instead of skipping an arbitrary number of rows.

Cursor-based pagination is a better fit for large datasets because its performance depends on page size, not page number.

Implementing Cursor-Based Pagination

In this project, cursor-based pagination is implemented using Prisma’s native cursor support. Each product's id is encoded into an opaque cursor, which the client passes back when requesting the next page.

At a high level, the resolver:

Decodes the after cursor (if present)
Uses it as a database cursor
Fetches first + 1 records to determine if another page exists
Builds a connection-style response with edges and pageInfo

Here is the resolver implementation:

// src/resolvers.js
// Helper function to encode cursor
function encodeCursor(id) {
  return Buffer.from(id.toString()).toString('base64');
}

// Helper function to decode cursor
function decodeCursor(cursor) {
  return parseInt(Buffer.from(cursor, 'base64').toString('ascii'));
}

...

productsCursor: async (_, { first = 20, after }) => {
    console.time('productsCursor');

    const cursor = after ? { id: decodeCursor(after) } : undefined;

    // Fetch one extra to determine if there's a next page
    const products = await prisma.product.findMany({
    take: first + 1,
    ...(cursor && {
        skip: 1, // Skip the cursor itself
        cursor: cursor
    }),
    orderBy: { id: 'asc' }
    });

    const hasNextPage = products.length > first;
    const edges = products.slice(0, first).map(product => ({
    cursor: encodeCursor(product.id),
    node: product
    }));

    const pageInfo = {
    hasNextPage,
    hasPreviousPage: !!after,
    startCursor: edges.length > 0 ? edges[0].cursor : null,
    endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : null
    };

    const totalCount = await prisma.product.count();

    console.timeEnd('productsCursor');
    console.log(`Fetched ${edges.length} products (cursor-based, after: ${after || 'start'})`);

    return {
    edges,
    pageInfo,
    totalCount
    };
},

This approach ensures that each query resumes from a precise position in the dataset rather than scanning past thousands of rows.

Querying with Cursors

To fetch the first page of products:

query cursorProductsFirst {
  productsCursor(first: 20) {
    edges {
      cursor
      node {
        id
        name
        price
        category
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

In the terminal, you'll see something like:

productsCursor: 39.993ms
Fetched 20 products (cursor-based, after: start)

And the response will be:

{
  "data": {
    "productsCursor": {
      "edges": [
        {
          "cursor": "MQ==",
          "node": {
            "id": 1,
            "name": "Product 1",
            "price": 581.7240166646505,
            "category": "Clothing"
          }
        },
        ...
        {
          "cursor": "MjA=",
          "node": {
            "id": 20,
            "name": "Product 20",
            "price": 979.7302196981608,
            "category": "Sports"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "MQ==",
        "endCursor": "MjA="
      },
      "totalCount": 500000
    }
  }
}

The format is slightly different from our offset-based implementation, but all 20 products are returned as expected, plus some useful pagination metadata. To fetch the next page, the client simply uses the endCursor from the previous response:

query cursorProductsNext {
  productsCursor(first: 20, after: "MjA=") {
    edges {
      cursor
      node {
        id
        name
        price
        category
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

And the response will contain products 21-40:

{
  "data": {
    "productsCursor": {
      "edges": [
        {
          "cursor": "MjE=",
          "node": {
            "id": 21,
            "name": "Product 21",
            "price": 194.5758511706771,
            "category": "Toys"
          }
        },
        ...
        {
          "cursor": "NDA=",
          "node": {
            "id": 40,
            "name": "Product 40",
            "price": 527.7330156641641,
            "category": "Electronics"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "MjE=",
        "endCursor": "NDA="
      },
      "totalCount": 500000
    }
  }
}

And for the next page, we would use the new endCursor value of "NDA=" and so on.

The cursor itself is opaque to the client and should be treated as an implementation detail. If the client can "guess" cursor values, it may lead to unintended behavior.

Now let's try to fetch the last page using the cursor! To do this on the client-side, we should keep following the endCursor values until we reach the end. However, for demonstration purposes, we will cheat a little and directly encode the 499980th product's ID and create a cursor for it. In resolvers.js, the encodeCursor() function does this. What we need is Buffer.from("499980").toString("base64"), which results in NDk5OTgw, therefore our query to fetch the last page looks like this:

query cursorProductsNext {
  productsCursor(first: 20, after: "NDk5OTgw") {
    edges {
      cursor
      node {
        id
        name
        price
        category
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Check your terminal logs again:

productsCursor: 35.197ms
Fetched 20 products (cursor-based, after: NDk5OTgw)

As you can see, the response times remain consistent regardless of how deep we paginate into the dataset!

Compared to offset-based pagination, you should observe:

Consistent database execution time, even for later pages
Uniform request duration across pages
Stable memory usage per request

Because each query starts from a known position, the database does not need to scan past large numbers of rows.

Why Cursor-Based Pagination Scales Better

Cursor-based pagination avoids the main pitfalls of offset-based pagination:

Performance does not degrade as clients paginate deeper
Pagination remains stable when records are inserted or deleted
Works naturally with infinite scrolling or stream-like UIs
Produces predictable, easy-to-compare timings/measurements in observability tools

Although cursor-based pagination requires slightly more setup than offset-based pagination, it provides far more reliable performance characteristics and is the preferred pattern for production GraphQL APIs.

Conclusion

Pagination is often treated as a schema design detail in GraphQL, but as shown earlier, it has a direct and measurable impact on performance, memory usage, and system stability.

Fetching all data at once may be convenient, but it quickly becomes a liability as datasets grow. Offset-based pagination improves the situation by limiting result size, yet still introduces hidden costs that surface as users paginate deeper. Cursor-based pagination, on the other hand, provides consistent performance characteristics regardless of dataset size, making it the most reliable choice for production GraphQL APIs.

More importantly, this article highlights the value of observability-driven decisions. Without instrumentation, all three approaches can appear to "work". But with proper profiling in place, the differences become clear, allowing you to make informed choices about how to design your API for real-world usage patterns.

If you're building or maintaining a GraphQL API in Node.js, cursor-based pagination should be your default (unless your dataset is small and unlikely to grow). And whatever approach you choose, instrument it early. Pagination is not just about shaping responses: it's about shaping how your system behaves under real-world load.

Lessons Learned from Running a Privacy-First Disposable Email Service: Insights from nullmail.cc

Gabor Koos — Wed, 18 Feb 2026 22:00:21 +0000

A few days ago, I got an unexpected email from Cloudflare: my domain, maildock.store, had stopped using their nameservers and was at risk of being deleted. This was unexpected, as I hadn't made any changes to the DNS settings. After some investigation, I discovered that the domain had been flagged for abuse, likely due to its association with disposable email services.

For context, maildock.store powers nullmail.cc, a privacy-first disposable email service. Users can create addresses, receive emails, and have them automatically deleted after expiration - all without signing up, tracking, or sending any outgoing mail. The frontend is a SvelteKit app on Vercel, emails are forwarded via forwardemail.net into a Supabase database, and the system automatically cleans up expired content. It's minimal by design, but robust enough to provide a fully functional disposable inbox - mostly in free tiers of various services.

Despite this simplicity, domains like maildock.store can trigger automated abuse flags. What followed was a whirlwind of DNS checks, WHOIS lookups, blacklist verification, and conversations with the .store registry, Radix. In this post, I'll walk through the story, how (I think) I resolved the issue, and the architectural choices that made it possible to recover safely, while keeping the service privacy-first.

Design Philosophy

At its core, Nullmail is built around privacy, simplicity, and minimalism. The goal is straightforward: users should be able to receive emails without giving away personal information, signing up for accounts, or being tracked. There's no analytics, no logging beyond what's necessary to deliver emails, and no outgoing SMTP - the service is strictly receive-only.

Every design choice reflects this philosophy. Addresses are ephemeral and automatically expire, keeping the system lean and reducing the risk of abuse. The database only stores what's necessary: the address itself and the emails sent to it. No unnecessary metadata, no IP logs, no behavioral tracking. Even the UI is stripped down to essentials, giving users just enough functionality to check their inbox and manage addresses.

This minimal, privacy-first approach has a practical benefit as well: it reduces the attack surface and limits what can go wrong. There's no complicated backend for sending mail, no rate-limiting infrastructure, and no analytics that could trigger false positives with anti-spam systems.

Architecture Overview

The simplicity of Nullmail's design is mirrored in its architecture. The service combines a few lightweight, well-chosen components to deliver a fully functional disposable email system while staying mostly in free tiers:

Frontend: A SvelteKit app hosted on Vercel. It handles the user interface for reading emails and managing addresses, with minimal JavaScript and no tracking.
Backend/API: The same SvelteKit app provides serverless API routes on Vercel for core operations: creating new addresses, listing inboxes, fetching email bodies, and extending expiry timestamps.
Database: A Supabase Postgres instance stores addresses and emails. The database schema is minimal, consisting of:
- addresses table: stores the address and its expiry timestamp.
- emails table: stores sender, recipient, subject, body, and delivery timestamp. Each email references an address, and expired addresses (and their emails) are automatically deleted via a scheduled cron job every five minutes.
Email ingestion: All incoming emails are routed through forwardemail.net. ForwardEmail posts inbound mail to a Vercel API endpoint, which inserts it into the Supabase database.
Domains & DNS: The service operates under the domains maildock.store and nullmail.cc. DNS is managed through Cloudflare, which provides:
- Nameserver hosting
- MX, SPF, DMARC, TLSRPT, and _security TXT records
- Proxying for web traffic (though Nullmail is mostly static)
- Protection against accidental misconfiguration or abuse flags
Optional UX: Browser extensions for Chrome and Firefox open the site with a fromExtension=1 flag for minor interface tweaks.

The codebase can be found on GitHub: gkoos/nullmail.

This architecture is lightweight but resilient, perfectly aligned with the privacy-first philosophy: no outgoing SMTP, minimal logging, and automated cleanup. It also meant that when the domain was flagged by Radix, most of the infrastructure was unaffected: the problem was isolated to DNS and registry-level issues.

The Incident

Even with a minimal, receive-only setup, disposable email domains can attract attention from automated abuse systems. As I mentioned earlier, I got an email from Cloudflare warning that maildock.store had stopped using their nameservers and was at risk of being deleted. At first, it felt like a false alarm — I hadn't touched any DNS settings.

Digging deeper, I discovered that the domain had been placed on ServerHold by Radix, the registry that manages .store domains. ServerHold is usually reserved for domains flagged for abuse, spam, or other policy violations. In my case, the likely trigger was the domain's association with my disposable email service, even though Nullmail is strictly receive-only and doesn't send outbound mail.

To investigate, I ran WHOIS checks, TXT and MX lookups, and verified DNS settings through Cloudflare. I also checked common spam/blacklist sources like SURBL: initially, the domain appeared flagged, though later it was cleared. While the frontend and database remained fully functional, the suspension meant that any new email delivery could fail and the domain risked being removed entirely.

This incident highlighted the harsh reality: even a minimal, privacy-first service with just a few users can run into registry-level issues. Fortunately, the architecture - isolated frontend, serverless backend, and Cloudflare-managed DNS - meant that the problem was largely contained to the domain itself, and recovery would be possible with the right steps.

The Resolution

Once I confirmed that maildock.store was on ServerHold, the next step was to contact Radix directly via their unsuspension form. I explained the service, emphasized it's receive-only nature, and detailed the privacy-first safeguards in place.

Radix responded positively and removed the ServerHold, reinstating the domain. To further prevent future issues and provide a point of contact for abuse reports, I created a dedicated abuse mailbox (abuse@maildock.store). This mailbox is stored in the Supabase database, has no public access, and is checked only via the Supabase UI as needed.

Next, I verified and cleaned up the DNS records in Cloudflare:

Removed old registrar NS entries that were no longer needed.
Deleted test or placeholder A records that could confuse DNS checks.
Confirmed MX records pointing to forwardemail.net were correct.
Ensured SPF, DMARC, TLSRPT, and _security TXT records were properly configured, with the abuse mailbox as the contact.

After these steps, the domain was fully operational again: emails were being received reliably, and the system continued to enforce automatic cleanup of expired content.

This experience reinforced the importance of clear abuse contact channels, proper DNS hygiene, and documenting a simple, minimal architecture that isolates potential issues. Even a small, receive-only service can be flagged, but thoughtful design makes recovery straightforward.

Honestly, I should have anticipated this sooner. Luckily, the solution was simple, and the service is back up without any lasting damage. The incident also provided valuable insights into how registry-level abuse flags work and how to design a service that can recover gracefully from them.

Lessons Learned

The ServerHold incident with maildock.store offered several insights about running a minimal disposable email service:

Despite being receive-only, with no outgoing mail, maildock.store was still flagged for potential abuse. utomated systems at the registry level tend to be cautious and sometimes overly conservative. Also, because no logs are kept, there's no way to tell what triggered the flag, which is a risk of a privacy-first approach.
DNS and registry configurations matter more than expected.
Inconsistencies in nameservers or leftover records may trigger alerts. While the system itself was unaffected, the domain's reachability depends on clear, correct DNS entries.
Direct communication with the registry is crucial - and they were responsive and helpful in resolving the issue once I provided context about the service and its safeguards.
Automated abuse flags are often resolvable with context. Having a clear explanation and a point of contact (abuse@maildock.store) allowed me to restore the domain quickly.
Minimalism has trade-offs: a simple architecture isolates most operations from failures like this, but no logging and lack of outbound monitoring means we rely on external feedback to detect issues.
The "why" remains uncertain: we still don't know exactly what triggered the abuse flag. This leaves open questions about how disposable domains are evaluated, and whether additional safeguards could reduce false positives. And also makes me wonder if the domain was targeted by a malicious actor who reported it, or tried to exploit the service, or if it was just an automated flag based on the domain's history or traffic patterns.

Overall, the experience reinforced that running a privacy-first service comes with uncertainties and edge cases. While minimalism and privacy help in some areas, external systems (registries, DNS providers, abuse monitors) can still impact availability in ways that are outside the service's direct control. In a larger context, this highlights the need to do your due diligence and understand the challenges of running a service that interacts with the broader internet ecosystem, even if it's designed to be as simple and private as possible. Also, value your users, but don't trust them to not try to abuse the service, and design with that in mind.