Skip to content

PATTERN Cited by 1 source

Clean reimplementation over adapter

Pattern

When an adapter approach (reverse-engineering the output of a closed / bespoke upstream tool to reshape it for a target platform) becomes unsustainable, reimplement the upstream tool's public API surface from scratch on a shared foundation — rather than continuing to chase the upstream's output format.

Forces

  • Upstream output shape is bespoke + undocumented — reverse engineering is the only path.
  • Upstream output format changes across versions — adapter breaks on every upgrade.
  • Maintenance cost on adapter grows super-linearly — new features require new reverse engineering; fixes become "a game of whack-a-mole".
  • API surface (the public contract) is stable and well documented — it's the output-shape layer beneath it that's the problem.

Canonical application — vinext vs. OpenNext

The 2026-02-24 vinext post names this explicitly:

"Building on top of Next.js output as a foundation has proven to be a difficult and fragile approach. Because OpenNext has to reverse-engineer Next.js's build output, this results in unpredictable changes between versions that take a lot of work to correct."

OpenNext adapts Turbopack output to non-Vercel runtimes. vinext reimplements the Next.js API surface (routing, SSR, RSC, server actions, caching, middleware) as a Vite plugin. ~95 % of the code is pure Vite; none of it reverse-engineers Turbopack output.

"This is not a wrapper around Next.js and Turbopack output. It's an alternative implementation of the API surface: routing, server rendering, React Server Components, server actions, caching, middleware. All of it built on top of Vite as a plugin."

When this pattern makes sense

  • Target API is well-specified — extensive docs, comprehensive test suite (can be ported as an executable spec). See concepts/well-specified-target-api.
  • A solid foundation exists to build on (Vite for vinext; LLVM for compilers; etc.) so you're not rebuilding from scratch.
  • Adapter cost has grown high enough to justify a full rewrite.
  • Modern tooling (AI-assisted coding in vinext's case) makes the rewrite tractable in reasonable time — see patterns/ai-driven-framework-rewrite.

Counter-indications

  • API surface not publicly specified — adapter is safer because reverse-engineered output at least works for what upstream actually produces.
  • No solid foundation to build on — from-scratch rewrite multiplies scope.
  • Adapter cost is manageable — premature rewrite is pure engineering risk.

Consequences

  • Predictable upgrades — you track the upstream API, not the upstream output format. Upstream can change its output however it wants.
  • No "whack-a-mole" on version upgrades.
  • Platform-portable by construction — the foundation (Vite) was chosen for cross-platform output.
  • Ongoing commitment to API-surface parity — you have to keep up with new upstream APIs.

Seen in

Last updated · 200 distilled / 1,178 read