{"canonical_url":"https://engineer.company/glossary/nextjs/","content_markdown":"# Next.js\n\n## What it is\n\nNext.js is a framework that wraps React, the library for building user interfaces out of components,\nand supplies the parts React leaves to each application: routing, rendering on the server, data\nfetching and a build that is configured for you. The package and its command are both called `next`,\nas in `next dev` and `next build`.\n\nIt was first released in 2016, in [its authors' words](https://nextjs.org/blog/next-13-4) “to\nprovide an easy way to server-render React applications”. The early design rested on a few\nprinciples: zero setup, the filesystem as an API, so that a file in a `pages/` folder became a\nroute, automatic server rendering and code splitting, and data fetching left to the developer. By\n2023 the release notes credited over 2,600 developers alongside a core team at Vercel.\n\nNext.js 13, on October 25, 2022, added an `app` directory in beta, built on\n[React Server Components](https://react.dev/reference/rsc/server-components), with nested layouts\nand streaming. Next.js 13.4, on May 4, 2023, declared this App Router stable, and the documentation\nhas described two routers ever since. The Pages Router is “the original router, still supported and\nbeing improved”. They differ even in which React they run: the App Router ships React canary\nreleases built in, while the Pages Router uses whatever version the project's `package.json` names.\nIn the App Router, pages and layouts render on the server unless a file opts into the browser with a\n`\"use client\"` directive.\n\nNext.js 16 arrived on October 21, 2025. It made Turbopack the default bundler, renamed the\n`middleware.ts` file to `proxy.ts`, and introduced Cache Components, a model in which a `\"use\ncache\"` directive marks what may be cached and everything else is rendered at request time. Next.js\n16.4, on October 6, 2026, recommends Cache Components for every app, switches them on for new\nprojects made with `create-next-app`, and says they “will become the default in Next.js 17”.\n\n## Why it matters\n\nThe decision Next.js answers is whether to let a framework own the routing, rendering and server of\na React application, or to assemble those pieces yourself and keep the choices.\n\nWhat it offers is convention in place of configuration. Routes come from files, bundlers and\ncompilers are set up automatically, and each route can be built ahead of time, rendered on the\nserver for each request or rendered in the browser. Server Components keep data access and secrets\non the server and send less JavaScript to the browser. For an application that mixes public pages\nwith a signed-in area and its own backend, that per-route choice is the main attraction.\n\nThe first cost is a server, running Node.js 20.9 or later for Next.js 16. Setting `output: 'export'`\nwrites one HTML file per route for any static web server, and the guide pitches it as a way to start\nstatic and add server features later. Its list of what needs a Node.js server, though, covers much\nof what sets Next.js apart: Proxy, Server Actions, cookies, rewrites, redirects, headers,\nIncremental Static Regeneration and image optimisation with the default loader.\n\nThe second cost is pace. Four feature releases followed 16.0 within a year, and the caching model is\nabout to change its default again. The 16.4 notes say Cache Components replace “the implicit caching\nbehaviors of the previous App Router versions”, so code written for Next.js 13 to 15 caches by\ndifferent rules. Tutorials found online are split between the two routers as well.\n\nThe third cost is that upgrades are security work. On December 3, 2025, the project published an\nadvisory for CVE-2025-66478, a critical vulnerability in the React Server Components protocol,\ntelling users to upgrade to patched versions immediately, and the blog carried three more security\nposts between September 30 and October 14, 2026. A team that adopts Next.js signs up to follow its\nreleases closely. A team publishing documents that read the same for every visitor pays for a server\nmodel it hardly uses.\n\n## What it looks like in practice\n\nIn the founder's work under NextMariner, the Next.js 16 frontend\n[renders each surface its own way](/portfolio/built-the-next-js-16-frontend-ssr-ssg-and-csr/),\nwhich is the per-route choice put to work. Marketing and public pages are statically generated, the\ngenuinely interactive parts stay client-rendered, and on the authenticated dashboard and the big\ndirectory listings a factory, `createPrefetchedServerPage`, fetches the page's data on the server\nand hands it to the client already populated. Pages move onto the factory one at a time, and the\npage is candid that the rest of the authenticated app is still client-rendered and queued behind it:\n“a migration with a working mechanism and an obvious next page, rather than a finished sweep.” The\nApp Router was designed for that kind of move; the 13.4 release notes describe adopting it\nincrementally.\n\nA [layered test suite](/portfolio/built-a-test-suite-across-go-sql-and-browser/) gives\na Next.js frontend a layer of its own: 543 Vitest and Playwright specs, including 48 end-to-end\nfiles and 30 browser specs, beside separate layers for the Go API and the database. Each layer is\nchecked where its behaviour lives rather than everything through a browser, which matters in a\nframework whose component tree runs partly on the server and partly in the browser.\n\nWhen the founder, working under NextMariner,\n[hardened an application](/portfolio/hardened-the-application-with-nonce-based-csp/), the\nbrowser-facing protections went into `proxy.ts`, the renamed middleware. It sets a\nContent-Security-Policy with a per-request nonce and `strict-dynamic`, plus HSTS and SameSite\ncookies. Authorisation lives elsewhere: entitlements, covering tier, role, organisation and ship\nscoping, are re-checked on the server on every request, and the frontend's gates count as UX only.\nThat split matches the Proxy reference, which calls the feature a last resort and tells developers\nto verify authorisation “inside each Server Function rather than relying on Proxy alone”.\n\n## Where it goes wrong\n\n**After a sign-in redirect is added, the login page loads without its styles.** Without a `matcher`,\nProxy runs on every request, including built files under `_next/static`, optimised images under\n`_next/image` and everything in `public/`, so a redirect meant for pages also catches the CSS,\nJavaScript and images the login page needs. Give Proxy a matcher that skips those paths:\n\n```ts\n// proxy.ts\nexport const config = {\n    matcher: [\"/((?!_next/static|_next/image|favicon.ico).*)\"],\n};\n```\n\nFiles from `public/` share no prefix, so add their paths as well.\n\n**A form action works for a signed-out user on a route that looks protected.** Server Functions have\nno routes of their own: they arrive as POST requests to the page where they are used, so a matcher\nthat skips a path skips the functions there as well. The Proxy reference warns that changing the\nmatcher, or moving a function to another route during a refactor, “can silently remove Proxy\ncoverage”. Check the session and the user's permissions inside every Server Function, and treat\nProxy as an outer layer, never the only one.\n\n**A user saves a change and the page still shows the old value.** In Next.js 16, `revalidateTag(tag,\n'max')` gives tagged entries stale-while-revalidate behaviour: the cached copy keeps being served\nwhile a fresh one is fetched, which suits content that can tolerate eventual consistency and\nsurprises the person who just pressed Save. Call `updateTag(tag)` from the Server Action that made\nthe change; it expires the entry and reads fresh data within the same request. The old one-argument\n`revalidateTag(tag)` is deprecated and is now a TypeScript error.\n\n**The upgrade codemod finishes and the build still fails on `params` or `cookies()`.** Next.js 15\nmade the request APIs asynchronous with temporary synchronous compatibility, and Next.js 16 removes\nit. The `upgrade` codemod does not run every migration, so also run\n`npx @next/codemod@canary next-async-request-api .`, then `npx next typegen` to generate the\n`PageProps`, `LayoutProps` and `RouteContext` helpers. The same upgrade removes `next lint` and\nstops `next build` from linting, so add ESLint or Biome as a step of its own.\n\n## Further reading\n\n- [Next.js Docs](https://nextjs.org/docs) — the official documentation, with a switch between the\n  App Router and Pages Router versions of every page.\n- [Next.js 16](https://nextjs.org/blog/next-16) — the release that brought Cache Components,\n  `proxy.ts` and Turbopack as the default bundler, with its breaking changes.\n- [How to upgrade to version 16](https://nextjs.org/docs/app/guides/upgrading/version-16) — the\n  codemods, the version requirements and every removed or renamed API.\n- [proxy.js](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) — matchers, where\n  Proxy sits in the request order and why middleware was renamed.\n- [Next.js 16.4](https://nextjs.org/blog/next-16-4) — the case for Cache Components and the plan to\n  make them the default in Next.js 17.\n- [How to create a static export](https://nextjs.org/docs/app/guides/static-exports) — which\n  features need a server, and what `output: 'export'` writes.\n\n\u003chttps://engineer.company/glossary/nextjs/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What Next.js adds on top of React, when its server-first model earns its keep, and the Proxy, caching and upgrade traps that catch teams on version 16.","formats":{"gemtext":"https://engineer.company/glossary/nextjs/index.gmi","gopher":"https://engineer.company/glossary/nextjs/gophermap","html":"https://engineer.company/glossary/nextjs/","json":"https://engineer.company/glossary/nextjs/index.json","markdown":"https://engineer.company/glossary/nextjs/index.md","pdf":"https://engineer.company/glossary/nextjs/index.pdf"},"kind":"page","language":"en","title":"What is Next.js?","url":"https://engineer.company/glossary/nextjs/","version":1}