How QuickJS Brings Modern JavaScript to Nginx via njs

When people think of Nginx, they usually picture a high‑performance, stable, resource‑efficient server with simple configuration. While Nginx excels at these basics, its traditional configuration language is static and increasingly insufficient for modern front‑end/back‑end separation, edge computing, authentication, and gray‑release routing needs.

To address this, Nginx introduced the njs module, a JavaScript engine that lets you embed logic in the configuration. Early versions of njs only supported a limited ES5‑ish syntax, lacking modern features such as import/export and async/await, which made development feel like stepping back to 2012.

Recently, Nginx added support for QuickJS in njs. QuickJS is a tiny (≈367 KB) JavaScript engine that implements the full ES2023 standard, enabling developers to use modern module systems, async/await, async generators, Proxy, BigInt, and more directly inside Nginx.

What can JavaScript do inside Nginx?

Previously you could only write simple if statements or URI rewrites. With modern njs you can now:

Perform dynamic routing based on request content, similar to Express.

Implement lightweight request validation without calling a backend service.

Generate asynchronous log data with custom formats.

Customize headers and body handling for flexible request forwarding.

Example of an authentication script:

async function auth(r) {
  const resp = await ngx.fetch("http://auth-service/validate", {
    method: "POST",
    body: JSON.stringify({ token: r.headersIn['Authorization'] })
  });
  if (resp.status !== 200) {
    r.return(401, "Unauthorized");
  }
}

This code looks like typical Node.js but runs inside Nginx with zero external dependencies.

Why is JavaScript gaining traction in Nginx?

Huge pool of JavaScript developers lowers the learning curve.

JavaScript offers clearer, more debuggable logic than DSLs.

JS provides flexibility and readability for complex tasks.

Unified toolchains enable smoother front‑end/back‑end collaboration.

Earlier attempts used Lua, which suffered from a small ecosystem and outdated syntax. Embedding a full JavaScript engine would be too heavyweight, but QuickJS strikes a perfect balance of size, speed, and modern features, aligning with Nginx’s design philosophy.

Evolution of JavaScript in Nginx

Initially, only tiny scripts could be placed in the config.

njs arrived, allowing more structured logic functions.

QuickJS now enables complete modern JavaScript execution.

Over time, JavaScript has become the core scripting language for Nginx, not by replacing existing services but by providing a versatile “glue” language for infrastructure tasks.

Practical use cases

Dynamic routing : route requests by region, time, or device.

Custom logging : capture user behavior, request details, rule hits.

Edge interception : implement pre‑flight security, IP blacklists, auth caching.

Front‑end tool integration : coordinate deployments with Vite, Bun, etc.

In summary, JavaScript has evolved from a browser language to a universal tool that can now script Nginx itself, offering modern, flexible, and efficient solutions at the edge of the network.