Next.js 16.4

Over the 16.x releases, we’ve introduced a new programming model that addresses many of the frustrations you've had with App Router from the start: It brings fast initial loads, even for personalized pages It gives server-rendered apps instant client navigations It makes caching opt-in, declarative, and composable This new programming model is called Cache Components, and it will become the default in Next.js 17. Prior to this release, we didn’t recommend it universally because there were some cases where it couldn’t achieve the same cost and performance guarantees as with the previous model. This release includes key features that close those gaps. Starting with Next.js 16.4, we’re excited to recommend Cache Components as the best choice for every Next.js app. As of today, all new apps created with create-next-app will have Cache Components enabled by default. Greenfield projects can enjoy all the benefits of the new model with no reservations. For existing apps, we’ve been investing in better agentic tooling to help codebases migrate to the new model. The new next upgrade --agent command gives agents version-specific guidance on upgrading your app, and dedicated Skills help agents with any refactorings needed for you to adopt Cache Components. Next.js 16.4 also includes several out-of-the-box improvements for all Next.js apps, including less memory usage and disk size in dev, reduced compile times, smaller production bundles, and React 19.3. Here’s a full overview of what to expect in this release, starting with Cache Components. What are Cache Components? Cache Components are a suite of features that lets you mark specific parts of your component tree as eligible for caching. Think of 'use cache' as a component-level version of the Cache-Control HTTP header: Next.js interprets these 'use cache' annotations as it renders your pages, caching your component's UI in the browser (during client navigations) and, optionally, on the server (during server rendering, or ahead of time during the build). These composable annotations let you mix client-side caching, fully pluggable server-side caching, and request-time rendering all within a single page, and they replace the implicit caching behaviors of the previous App Router versions. To learn more about Cache Components, read the guide on caching. What's new in Cache Components In this post, we use "Cache Components" to refer to the new programming model, which you can use today by enabling two flags in your Next.js config: Cache Components first shipped without Partial Prefetching, but it's now considered part of the model. You can learn more about Partial Prefetching from our previous release post. Next, here's what's new for Cache Components in 16.4. Ensuring shells, prefetches, or pages are static One of the hallmark features of 'use cache' is the ability to build pages that stream static and dynamic content together in a single response from the server. For example, you can compose the current user’s avatar alongside a blog post that is otherwise statically prerendered: Next.js can serve the prerendered blog post from cache (like your app's /public folder, or a CDN) and render the UserAvatar at request time, all from the same HTTP response. This flexibility is what enables you to build apps with sophisticated UIs, without sacrificing speed or dynamism. But sometimes you want to build an app with fully static pages. In those cases, one dynamic component can degrade the performance or cost characteristics of an otherwise optimized site. In Next.js 16.4, ensureStatic offers a simple way to guarantee that a route’s shell, prefetch, or full navigation is static. For apps that want to avoid unintentional compute and keep their server costs down, this lets you prevent a dynamic component from accidentally sneaking into a route. For example, if we wanted to enforce that our blog post page from the example above was always static, and that adding a dynamic component like UserAvatar should never be possible, we could add export const ensureStatic to the route: By setting ensureStatic to "navigation", Next.js will fail the build if any dynamic content is ever included in this page, ensuring that navigations to this route will never render at request time. While "navigation" is the most restrictive form, you can also set ensureStatic to "prefetch" (to ensure links with explicit prefetching to this route only fetch static content) or "shell" (to ensure that only static content is fetched when this route is first discovered) if you need more fine-grained control. In addition to using it on individual pages, you can also add ensureStatic to a layout to apply the same guarantees to all pages within that layout. For example, you could add ensureStatic = 'navigation' to the root layout to easily guarantee that every page navigation in your site is static: Then, you could push it down to nested layouts if certain pages start to need dynamic content. Many dynamic apps won't need this feature, but for optimized sites like ecommerce stores, marketing pages, or blogs, ensureStatic is a simple way to guard against unwanted request-time rendering. Learn more about keeping pages static and the ensureStatic config. Excluding content from a prefetch Prefetching is a powerful way to improve the UX of your Next.js applications. By using <Link prefetch> or useRouter().prefetch(), you can eliminate loading states by prerendering a page's cached UI before an actual navigation takes place. For example, let's look at a simple email app. Here's an Inbox that renders links to each message: And here's the Message page, which shows a spinner when loading a message thread for the first time, then caches it in the browser for subsequent visits: While this lets users instantly view messages they've already loaded, they'll still see the loading spinner when opening a message for the first time. To eliminate that initial loading state, we could add prefetch to our Inbox's links: Now, each link will prefetch all the cached data and UI on the Message page as soon as it becomes visible, so it's ready by the time the user clicks. This makes for a great UX by eliminating loading states from the app, but it also means that every visible link loads the entire message thread ahead of time—even for messages the user never opens. For our email app, this might be too costly or introduce too much strain on our servers. Instead of just turning prefetching back off, a better solution would be to only prefetch the first message, and defer rendering the rest of the thread until the user actually navigates. In Next.js 16.4, we can do exactly this. The new navigation API lets you exclude loading cached content during a prefetch, effectively deferring it until an actual navigation takes place. In our example, we could extract the thread into a new component, and add await navigation() to exclude it from the prefetch: Now the Message page only renders the first message during a prefetch, and waits for a full navigation to load the rest of the thread from the database and render it. In addition to navigation(), we've also added prefetch(), which you can await to exclude cached content that would otherwise be included in a route's shell. This way, rendering that content will be deferred until an explicit prefetch with <Link prefetch> or useRouter().prefetch(). These APIs give you more control over what data gets loaded at different stages of a navigation, letting you balance eager and lazy rendering in a way that’s right for your app. Learn more about deferring work to a later stage, and see the navigation and prefetch API references. New agent features We're investing in agent tooling to make Next.js a system that continuously helps keep your app secure and up to date. Next.js 16.4 builds on our documentation, Skills, and verification tools with agent upgrades and feedback, helping us learn from how you build and bring improvements back to your app. Agent upgrades The new --agent option for next upgrade helps your agent upgrade your app from start to finish. It checks your installed version, selects a target release, and prepares the migration guides, any needed codemods, and verification steps for your agent. The agent applies the update, resolves migration issues, and checks that your app still works. You or your agent can run it from your app's directory: Using next@canary runs the latest upgrade tooling, even if your app is on an older version of Next.js. Your agent gets up-to-date guidance to bring your app to the latest release. Getting up to date is the first step. To help you stay current, Next.js 16.4 introduces experimental.agentUpgrade. As you or your agent run next dev or next build, Next.js will automatically nudge you or your agent when a relevant upgrade is available, so you don't have to remember to check yourself. When you choose to upgrade, it starts the same agent workflow with your configured policy. You can configure these reminders in your Next.js config: 'security' (the default policy): Remind you about upgrades that address known vulnerabilities affecting your installed version. 'latest': Remind you about newer major or minor releases and use the latest upgrade policy to keep your app current. false: Disable upgrade reminders. We're also working on a future policy for this flag to help agents adopt new features and programming model changes idiomatically, such as migrating to Cache Components. Today, you can use our Skills for adopting Cache Components and Partial Prefetching to have your agent help you migrate to the new model. Learn more about upgrading with a coding agent and the agentUpgrade config. Agent feedback Coding agents often encounter framework errors, unclear docs, or workarounds while building and upgrading apps. The new experimental agent feedback workflow lets them prepare draft reports that you can review and choose to send to the Next.js team.