Skip to main content

Building the infrastructure underneath Next.js

We ran Next.js's own deployment test suite against the hosting platform we've been building, and went from 639 passing test files to 937 of 940 in two days.

Author
Sean WhitemanFounder, Easel.sh
Published
Reading time
4 min

You can run Next.js on practically any server with Node.js installed. Run next build followed by next start, and you have a working Next.js application.

Building a managed hosting platform for Next.js is a considerably larger undertaking. We want to serve static assets from a global CDN, execute functions on demand, distribute cached responses across regions, and handle deployments without interrupting active sessions. Developers shouldn't have to provision servers or configure any of this themselves.

We've spent the past several months building that infrastructure at Easel. Much of that time was spent developing our routing engine in Rust, which interprets an application's build output and determines how each request should be served.

Our own Next.js applications have been running on Easel for months, as have those of our customers. Occasionally, someone would encounter a combination of framework features we hadn't accounted for.

Last week, we felt the platform was mature enough to pursue complete Next.js compatibility.

1,255 test files

The Next.js repository contains an extensive suite of end-to-end tests designed to run against deployed applications. Next.js's documentation names this suite the contract for functional compatibility: a hosting platform that passes it supports Next.js. The tests cover years of framework development, including some remarkably specific interactions between features.

We built a harness to run the entire deployment suite against Easel. Each test file gets its own deployment. The runs used a local copy of our stack on a single machine: the same edge and routing engine we run in production, with local stand-ins for the storage and serverless services behind them.

Our first complete run, against Next.js 16.5.0-canary.48, yielded 639 passing files, 294 failing files, and 322 files skipped by Next.js.

Within two days, 937 of the 940 files that run in deployment mode were passing.

Every update to our results tracker during the push, by hours since the first complete run of the Next.js 16.5.0-canary.48 deployment suite on November 12. Most updates record reruns of the affected test files, not a full run. Passing files dipped when we started building test apps with Next.js's deployment adapter, which exposed new gaps. The total grew from 933 to 940 at the same point, because Next.js runs some test files only against adapter builds. Files Next.js skips in deployment mode are excluded.

The result for every test file is on Are We Next Yet?

Several of the failures led to architectural improvements in infrastructure we'd already been operating for months.

Resumable routing

Our routing engine evaluates a sequence of rules that can modify requests, check for the existence of resources, rewrite destinations, and invoke functions.

Middleware can execute partway through this sequence and return a modified request. Previously, our router would evaluate its routing rules again from the beginning.

The right fix wasn't obvious. One of our attempts to improve middleware compatibility fixed three test cases and broke twelve others.

The restart caused problems during client-side navigation in the Pages Router. A request for JSON data would be rewritten by middleware, and subsequent routing would incorrectly interpret it as a regular HTML page request.

We added the ability to suspend routing, execute middleware, and resume from the same position with the modified request.

Simplified. Restarting runs the rules before middleware a second time; resuming carries on from where routing stopped.

This resolved failures spanning middleware, custom matchers, redirects, and Server Actions.

Waiting for a cache entry that will never exist

Our CDN implements request coalescing. When multiple requests arrive for the same uncached resource, one request populates the cache while the others wait.

A Next.js metadata streaming test exposed a problem with this approach. A prefetch request was producing a streaming response that wouldn't be cached, but subsequent requests were still waiting for the stream to finish.

We changed our implementation to release waiting requests as soon as the original response is determined to be uncacheable.

Conceptual timelines. Horizontal distances don't represent measured durations.

All 19 cases in the metadata streaming test passed.

Are We Next Yet?

We've published the results of our compatibility testing at arewenextyet.easel.sh, where you can explore the status of individual test files and their associated framework features.

Are we Next yet? headline: Almost. 99.2% passing, 4,615 of the 4,650 Next.js deploy test cases that run, on Next.js 16.5.0-canary.48.
The Every test grid, one cell per test case, almost all passing. A hovered failing cell names its test, an OpenTelemetry middleware trace case, and its file.
arewenextyet.easel.sh. The headline counts test cases; hover any cell in the grid to see its test and open its file.

As of our latest run, 936 of the 940 test files that run in deployment mode pass. The remaining four:

  • prerender-encoding is a deliberate divergence, made after the push. Easel keeps an encoded slash (%2F) encoded when it looks up build output, so /admin%2Fsecret can't reach /admin/secret past a route that guards /admin/. The test expects a 404 there, and Easel serves the page.
  • otel-middleware-trace reads trace spans through the Vercel CLI, which Next.js's harness only does for deployments the Vercel CLI made. Every response has the expected status.
  • metadata-streaming-parallel-routes has two assertions that Next.js expects to fail in deployment mode. They pass on Easel, and the test runner reports an unexpected pass as a failure.
  • next-image-legacy/default has two assertions, an SVG's measured size and a CSS value, that fail the same way under next start on the same machine. We attribute them to the test environment.

These are functional compatibility tests. They aren't a performance benchmark or a direct comparison with Vercel.

We'll continue running Next.js's deployment suite as both the framework and our infrastructure evolve.

Our goal is for developers to be able to deploy their existing Next.js applications globally on Easel, with every framework feature available out of the box.

All posts

Start deploying

Free to start. Import a repository and get a production URL in a few minutes.