Next.js 15 has been officially released!

Intro

Next.js is a framework based on the React.js library, currently developed and maintained by Vercel. It is a tool for building fast and scalable web applications that can be rendered on the server side (Server-Side Rendering), or pre-rendered statically (Static Site Generation), which improves page load speed and optimizes SEO. There is also render on the client side (Client-Side Rendering), a method where content is rendered in the browser using JavaScript after the initial page load.

Thanks to its flexibility and ease of integration with other technologies, the popularity of Next.js has incredibly risen to over 7 million downloads per week. The choice of this tool is undoubtedly influenced by support for TypeScript and the ability to integrate it with GraphQL, REST APIs, or many CMS systems. In addition, Vercel, the company developing Next.js, offers support for hosting applications based on this framework.

On October 24th in San Francisco, another technological-business conference, NextConf dedicated to Next.js, took place. At the conference, we could learn among other things about the advantages of using server components, building interfaces with the help of AI, and optimizing LCP (Largest Contentful Paint), which plays a key role in SEO website optimization. The NextConf conference also included workshops on Next.js basics, building applications based on OpenAI, and AWS Bedrock - a platform that allows rapid development of blockchain-based applications.

Information about the version 15 began appearing in official articles on nextjs.org's blog in May. At that time, Next.js 15 was in the RC (Release Candidate) phase, which is the last stage before the final release. This meant that if no critical errors were detected, Next.js 15 RC would become a stable version. We have reached that point. The official Next.js 15 release took place on October 21st. We deliberated on the best way to showcase the latest Next.js and concluded that we would divide the article into four sections:

• Stable in Next 15 - this section discusses the elements that have reached stability status. These are functionalities and mechanisms that we can confidently use in commercial projects without the risk of encountering critical errors.
• Improvements - this section covers improvements introduced compared to the previous version, Next.js 14. Some elements of the framework have been optimized for performance and ease of use.
• Breaking changes - this section analyzes the breaking changes that introduce irreversible changes that may require adjustments to existing code.
• Experimental features - in this part, we looked at functionalities that are still in the experimental phase. This will give a glimpse of what might become an integral part of the current or next version of Next.js.

Each of these sections allows for a more detailed understanding of what Next.js 15 has to offer and how best to utilize the new features that it brings.

Stable in Next 15

TURBOPACK

Turbopack is a tool created by the developers of Next.js due to performance issues encountered with webpack. It has been designed to make the transition as seamless as possible for developers. Turbopack supports JavaScript and TypeScript out of the box. Moreover, it handles all module importing methods, including dynamic imports and both ES and CommonJS modules. A key feature is its capability to live reload environmental variables. Turpopack provides faster code compilation times, supports App Router and Pages Router, offers tree-shaking within modules, and allows for tracking and diagnosing performance issues. The creators affirm that Turbopack is a stable tool and emphasize their use of this tool in developing their own applications such as vercel.com and nextjs.org, with satisfying results. As quoted from the Next.js blog:

“For instance, with vercel.com, a large Next.js app, we've observed:

• Up to 76.7% faster local server startup.
• Up to 96.3% faster code updates with Fast Refresh.
• Up to 45.8% faster initial route compile without caching (as Turbopack does not yet feature disk caching).”

BUNDLING EXTERNAL PACKAGES

Bundling external packages is a functionality that can enhance the performance of our application. In the App Router, packages imported in server components and Route Handlers are bundled by default. We can choose to exclude specific packages from bundling if necessary, using the new serverExternalPackages configuration option, which replaces the former (experimental) serverComponentsExternalPackages. In the Pages Router, packages are not bundled by default, so to use this functionality, we must add the transpilePackages option in the config file and list each package individually. However, a new option bundlePagesRouterDependencies has been introduced, enabling automatic bundling active in the App Router to also work in the Pages Router, thereby standardizing the configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// next.config.ts – before
const nextConfig = {
  transpilePackages: ['@dnd/utils'],
  experimental: {
    serverComponentsExternalPackages: ['@dnd/ui'],
  },
};

// next.config.ts – after
const nextConfig = {
  bundlePagesRouterDependencies: true,
  serverExternalPackages: ['@dnd/ui'],
};

export default nextConfig;

INSTRUMENTATION.JS API

The "instrumentation.js" file serves to integrate observability tools with the Next.js application. It enables performance monitoring, error capturing, and aids in debugging. With Next.js 15, the experimental configuration option instrumentationHook could be removed, as the functionality is now stable. Additionally, a new hook onRequestError has been introduced, allowing the capture of the context of all errors thrown on the server, including those from routing (app/pages), route handlers, middleware, server components, and server actions.

1
2
3
4
5
6
7
8
9
10
11
12
// instrumentation.ts

import { type Instrumentation } from 'next';
import * as Sentry from '@sentry/nextjs';

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  Sentry.captureException(err, context);
};

Improvements

ROUTES

The Pages Router (/pages) will continue to support React 18 but will also be enhanced to support React 19 if it becomes stable. For the Next.js App Router (/app), we can still use the latest version of React 19 RC.

METADATABASE

For projects hosted on Vercel, the environmental variables for metadataBase have been updated. To clarify, metadataBase is an option that facilitates setting the base URL prefix for metadata that requires a full URL. Typically, this parameter is set in the app/layout.js file and applies to URL-based metadata fields in all routers. For preview deployments, the VERCEL_BRANCH_URL environmental variable will take precedence, and if not present, it will default to VERCEL_URL for production deployments, it will be VERCEL_PROJECT_PRODUCTION_URL.

1
2
import type { Metadata } from 'next'; 
export const metadata: Metadata = { metadataBase: new URL('https://acme.com'), }

UPGRADE CREATE-NEXT-APP

The create-next-app installer for creating and configuring a new project based on Next not only changes the look of the homepage but also automatically ignores the .env file. A prompt in the installer now offers the option to enable Turbopack (explained under the stable section) for local development. This option is off by default but can be enabled using the --turbo flag. Additionally, a new option to create a completely minimalistic project (using the —empty flag) removes unnecessary files and styles. The welcome screen will display the well-known "hello world" text from the programming industry.

CODEMOD CLI

Codemod is a tool that assists developers in the code migration process. It is used for making code changes that can sometimes be time-consuming to perform manually, such as rewriting syntax, updating libraries, and changing file imports. The current version of codemod is 15.0.2-canary.4.

The Next.js 15 version introduced an upgraded CLI codemod interface that will update dependencies and display available code modifications for us. Use the command: npx @next/codemod@canary upgrade latest. The canary uses the latest version of codemod, while latest refers to the Next.js version. Codemod's canary version is recommended as its developers continue to enhance this tool. More information here.

THE ERROR OVERLAY

To provide a better experience during server code inspection, a green button overlay was added. This button allows copying the error stack and opening it in a new browser window, provided that the Next.js app was started with Node.js inspector and is being used on Chrome. If you are not using Chrome or have not enabled Node.js —inspect, then the green button will lead to the Next.js documentation. If you start the Next.js app without the inspector, the green button won't appear.

STATIC ROUTE INDICATOR

The Static Indicator is a tool that provides developers with information about the current route. It helps to identify which routes are static and which are dynamic. This visual clue aids in performance improvement by understanding how a page is rendered.

appIsrStatus - a property indicating whether a route is static or dynamic and whether a specific page is statically generated (created ahead of time on the server). By default, this property is enabled and can be temporarily disabled by clicking the close icon, but only for one hour. If you want to permanently disable it, this must be done in next.config.js by setting it to false.

buildActivity - a build indicator that appears by default in the bottom right corner of the page when editing code, as Next.js compiles the applications.

buildActivityPosition - a property allowing the change of the indicator's position, necessary for example when a chat is set in the bottom right corner, which might obstruct the view of the indicator.

1
2
3
4
5
6
7
// next.config.js

devIndicators: {
  appIsrStatus?: boolean, // defaults to true
  buildActivity?: boolean, // defaults to true
  buildActivityPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left', // defaults to 'bottom-right'
};

TYPESCRIPT IN NEXT.CONFIG.JS

Next.js 15 allows the use of TypeScript in the next.config.ts configuration file, enabling the import of types to be used within the config file.

1
2
3
4
5
6
7
8
9
// next.config.js

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  /* config options here */
};

export default nextConfig;

Note that the module resolution in next.config.ts is currently limited to CommonJS, which can cause incompatibilities with packages that use ECMAScript Modules (ESM).

ESLINT 9 SUPPORT

ESLint is a tool that helps developers maintain consistency and quality in their code according to specified formatting rules and guidelines. Not only does it inform about errors, but most can be automatically corrected, enhancing code quality and simplifying teamwork. As of October 5, 2024, support for ESLint 8 ended, so Next.js 15 introduced support for the new version - ESLint 9. To ensure a smooth transition to the new version, Next.js maintains backward compatibility, allowing the continued use of version 8, thereby sustaining compatibility with version 15. As the arrival of ESLint 10 approaches, Next.js will stop supporting older configurations, so it's advisable to start migrating to the newer version as soon as possible. Link to migration and new configuration format

REACT 19 AND HYDRATION ERROR IMPROVEMENTS

With the stable release of Next.js 15, a decision was made to adapt the framework for React 19. In this version, the App Router uses React 19 RC (Release Candidate). Based on feedback from the community, backward compatibility for React 18 with the Pages Router was introduced. If you are still using the Pages Router, you will be able to update your React version at a convenient time for you. The creators of Next.js work closely with React developers and ensure that although React 19 is in the RC phase, based on conducted tests, they can be confident about its stability. Thus, deciding to switch to Next.js 15 ensures our project is prepared to embrace React 19. It is worth checking out a few links: Next.js 15 upgrade guide, React 19 upgrade guide, and the React Conf Keynote from React Conf. While it is possible to run the Pages Router in React 18 and the App Router in React 19, this is not recommended. It can lead to unintended consequences and inconsistencies in typing since the fundamental API and rendering logic between the two versions might not be entirely compatible. Changes have also appeared in hydration errors. Initially, an explanation for those unfamiliar with this term: hydration errors are errors that occur during the hydration process in server-side rendered (SSR) apps. Hydration is the process where JavaScript code in the browser connects with existing HTML structures generated by SSR. In short, hydration errors happen when the server-side state of an application does not match the browser's state. Already, Next.js 14.1 checked corrections for error messages and hydration errors. Next.js 15 continues this process by adding an improved and more detailed view of hydration errors, including the source code of the error with suggestions on how to resolve it.

<FORM>

The <Form> component in latest Next.js extends the HTML <form> element with:

• client-side navigation functions - meaning that only specific parts of the page are updated without the need to reload the entire page,
• prefetching - a mechanism that loads data before it is actually needed by the user, speeding up navigation (e.g., layout and loading UI files are additionally downloaded),
• Progressive Enhancement strategy, which means that if JavaScript has not yet loaded, the form still operates through full-page navigation.

Therefore, we notice that the component is useful for forms that redirect to a new page, such as a search form leading to a results page. This is particularly valuable for forms that change URL parameters.

1
2
3
4
5
6
7
8
// sample code from documentation:

import Form from 'next/form';

<Form action="/search">
  <input name="query" />
  <button type="submit">Submit</button>
</Form>;

The action prop in the <Form> Component is the URL or path to which to navigate after the form is submitted. If we use an empty string, it will cause navigation to the same page with updated search parameters. Besides action, we can also use replace if we want the current browser history state to be replaced, instead of pushing a new entry onto the browser history stack. By default, this option is set to false. We also have the option to use the scroll option (default true), which controls the scroll behavior during navigation. Suppose you are on a page with a long form and need to scroll down to see the entire content. You fill out the form, then press the “submit” button. If the scroll value is set to true, after submitting the form, the page will automatically scroll to the top (to the start of the new page you moved to). Additionally, the page remembers your scrolling position when you press the “back” button in the browser. The prefetch option (default true), controls whether the path should be pre-fetched when the form becomes visible (is within the user's field of vision). In the case of action, which is a function action={myAction}, the <Form> component behaves like a React form, performing an action when the form is submitted. In this case, the replace and scroll options are ignored.

SELF-HOSTING IMPROVEMENTS

Next.js 15 brings greater control over Cache-Control directives, among other things, it does not overwrite custom values with default Next settings.

For controlling the stale-while-revalidate period sent for ISR pages, enhancements such as changing the default value to one year and the ability to add an expireTime value to the Next configuration, which replaces the earlier experimental swrDelta option, have been introduced.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// next.config.ts – before

const nextConfig = {
  experimental: {
    // one hour in seconds
    swrDelta: 3600,
  },
};

// next.config.ts – after

const nextConfig = {
  expireTime: 3600,
};

Additionally, image optimization for self-hosting has been improved. From now on, Next.js will automatically use the sharp library when using the next start command or in standalone mode.

SERVER COMPONENTS HMR

HMR will now utilize fetch responses from previous renders. Previously, server components were restarted upon each save, which meant re-executing API queries. This negatively impacted performance and could potentially incur costs of calling paid APIs.

ENHANCE STATIC GENERATION FOR THE APP ROUTER

Build times have been significantly reduced, especially for pages with slower network queries, by implementing improvements:

• the fetch query cache is shared across pages on the same workers
• previously, generating static pages required two renders (one to generate data for client-site navigation and another to render HTML for the initial page visit). From now on, Next only uses the first render.

ENHANCE SECURITY FOR SERVER ACTIONS

Server Actions allow client components to invoke asynchronous server functions. We define them by exporting as an asynchronous function and adding a use server directive at the start of the file.

Until now, a Server Action function that is not imported anywhere else in the code is still publicly accessible via an HTTP endpoint.

To improve security in Next 15, dead code elimination and secure action identifiers have been introduced. The former ensures that unused Server Actions will not have their identifiers in the browser-side bundle, which should improve performance. In the latter case, Next.js will create hard-to-guess identifiers, which will be periodically recalculated between compilations. This allows referring to and invoking Server Actions, thereby increasing security.

PRELOAD ALL CHUNKS FOR NEXT/DYNAMIC IN SSR

From version Next 15 onwards, JS chunks for next/dynamic will preload using defer. This attribute ensures that the script executes after the DOM is ready but before DOMContentLoaded and never blocks the page. This may enhance rendering.

Breaking changes

MINIMUM REQUIREMENTS

The Next.js 15 framework requires developers to have at least version 18.18.0 of Node installed, it is therefore recommended you install this, along with the latest version of React 19 RC. This is due to Next.js 15 utilizing new features and mechanisms that have been implemented in new React 19.

CACHING SEMANCTICS: ROUTE HANDLERS AND CLIENT SIDE ROUTER CAHCE

Next.js 15 changes the default settings for caching GET Route Handlers and the Client Router Cache. The creators of Next.js justify these changes by listening to feedback from developers working with the framework, as well as the impact of caching on functionalities such as Partial Prerendering (PPR) and integration with third-party libraries using fetch. Briefly, the changes involve shifting from the "cached by default with an option to disable" approach (previous versions of Next.js) to "uncached by default with an option to enable" (Next.js 15).

GET Route Handlers are no longer cached by default. In the previous version, route handlers using the HTTP GET method were cached by default. This behavior could be changed by setting a dynamic function or dynamic config option. From Next.js 15 onwards, route handlers with GET are not cached by default. However, there is an option to change this functionality using the dynamic option:

1
2
3
4
5
6
7
// app/blog/route.ts

export const dynamic = 'force-static';

export async function GET() {
  // ...
}

Other special Route Handlers remain static by default unless changed via dynamic functions or configuration options. Examples of such Route Handlers include metadata files like sitemap.ts, icon.ts, or manifest.ts.

The Client Router Cache no longer caches Page components by default. staleTimes is an experimental option in next.config.js, which allows for caching of page segments in the client-side router cache. This option was available in the previous version, but in Next.js 15, its default value has been changed to 0 for page segments. This means that during navigation in the application, users will always receive the latest data from page components. Other caching behaviors remain unchanged:

• loading.js - will still be cached for 5 minutes or a custom value of staleTimes.static.
• support for partial rendering will continue, as shared layout data will not be re-fetched from the server,
• navigating back/forward will still utilize the cache, and the browser's scroll position will be restored.

Here's how the default values for client router cache have changed:

1
2
3
4
5
6
7
8
9
10
// next.config.ts

const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 60,
      static: 120,
    },
  },
};

ASYNC REQUEST APIS

Traditionally in server-side rendering, the server waits for the request before rendering content. However, not all components depend on request-specific data. The server could prepare as much data as possible before the request arrives. To facilitate this and aid future optimizations, it is necessary to introduce a change that allows specifying when to wait for the request.

For this reason, the following APIs are becoming asynchronous: cookies, headers, draftMode, params (in layout.ts, page.ts, route.js, default.js, generateMetadata, and generateViewport), searchParams (in page.ts).

To facilitate migration, all these APIs will remain available synchronously until the next major version but will display warnings. The Next.js developers also provide a codemod for automatic code refactoring:

1
npx @next/codemod@canary next-async-request-api .

DYNAMIC SITEMAP

In the latest version of the Next.js 15 framework, the automatically added .xml extension to sitemap routes has been removed when the route was dynamic. In the previous version, the URL difference between the development and production versions looked like this:

• dev: /sitemap.xml/[id]
• prod: /sitemap/[id].xml.

Now it has been standardized as /sitemap/[id]. Additionally, users can now freely add extensions to files, e.g., .xml, .html, .txt.

SHARP INSTEAD OF SQUOOSH

After analyzing the image APIs, the decision was made to move away from Squoosh, which until now enabled optimization and reduction of image file sizes without reducing quality, but operated slowly. It has been replaced with the more efficient Node’s Sharp. Additionally, an error has been added to notify when the file src has space at the beginning or end of the name. Another change forces the browser to download the image when entering directly into the image URL - the image will not open in the browser window as before. This option can of course be reverted to the previous version through: contentDispositionType: 'inline'.

CHANGES IN NEXT/FONT

Considering the theme of fonts, support has been added for custom fontFamily names using next/font. As known, next/font creates a font hash during CSS generation to achieve proper scope. This has caused a problem when using the given font with external libraries that provide CSS with predefined font names. This issue has been resolved by adding the usedFontFamilyName flag, which allows selecting a fontFamily name that will be used in the output CSS. Additionally, in the new Next.js 15, all external font loading configurations (e.g., webpack using file-loader for handling fonts) are planned for removal. The recommended practice will be to directly use next/font.

In the context of studying speed and analyzing applications, the outdated analyticsId configuration has been removed. It is worth mentioning that support for it was discontinued as of Next.js 14.1.1. In Next.js 15, it will be recommended to use this package or useReportWebVitals if reporting to any provider is desired.

CHANGES IN NEXT/DYNAMIC

Error messages have also been included for situations where a user specifies ssr: false (Server Side Rendering) in server-side components. This happens because the mentioned option should only be handled in client components. Additionally, it is worth noting that functions revalidatePath and revalidateTag will also generate error messages if they are executed during rendering. Recall that RevalidatePath is a method used for rechecking and confirming the path to a specified file or location in the system, while revalidateTag is a method used to confirm the currency of a tag.

The outdated suspense prop from next/dynamic has been removed, and the component is not wrapped in Suspense for ssr options and those not containing loading. Next/dynamic allows for dynamically importing components using React.lazy and, in some cases, wraps them by default in React.Suspense. To explain, React.lazy allows for the dynamic import of a component, meaning the component is loaded only when necessary, not immediately when the application starts. React.Suspense, in turn, allows for temporarily displaying an alternative loading component until the dynamically imported component is loaded.

Experimental features

REACT COMPILER

We discussed the React Compiler in our article when the new version of React 19 was announced (React 19 has been officially announced). The compiler (created by the React Team) has been added and marked as an experimental feature in the new Next.js 15 version.

React Compiler understands your code on a deep level thanks to its grasp of JavaScript semantics and React principles, enabling it to add automatic optimizations to the code. The compiler reduces the amount of manual memoization, which developers often implement using APIs such as useMemo and useCallback. As a result, the code becomes simpler, more readable, easier to maintain, and less prone to errors.

Currently, this tool is available as a Babel plugin, which unfortunately may result in slower development and build times. For more information about this tool, visit the official documentation.

EXPERIMENTAL STATIC GENERATION CONTROL

New experimental options allow for greater control over Static Generation:

• staticGenerationRetryCount – the number of attempts to generate a page when an error occurs during the build
• staticGenerationMaxConcurrency – the maximum number of pages processed per worker
• staticGenerationMinPagesPerWorker – the minimum number of pages before creating a new worker

1
2
3
4
5
6
7
8
9
// next.config.ts

const nextConfig = {
  experimental: {
    staticGenerationRetryCount: 1,
    staticGenerationMaxConcurrency: 8,
    staticGenerationMinPagesPerWorker: 25,
  },
};

UNSTABLE_AFTER: EXECUTING CODE AFTER A RESPONSE

unstable_after is a new experimental API option that allows executing a specific task after a query or pre-render has finished. This feature is useful when you want to perform a side effect like logging or analytics without blocking the response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// next.config.ts

const nextConfig = {
  experimental: {
    after: true,
  },
};

export default nextConfig;

// app/layout.ts

import { unstable_after as after } from 'next/server';
import { logEvent } from '@/utils';

export default function Layout({ children }) {
  // Secondary task
  after(() => {
    logEvent();
  });

  // Primary task
  return <>{children}</>;
}

It’s important to note that the unstable_after function will also be executed if the response ends with an error. Moreover, invoking this function does not make the route dynamic. Used in a static page, it will be executed during build or revalidation. unstable_after can also be nested within another unstable_after invocation.

UNSTABLE_RETHROW: AVOID CATCHING INTERNAL ERRORS

unstable_rethrow allows you to avoid catching internal errors generated by Next.js. For example, if you use the notFound function inside a try/catch, the error will be caught, and the not-found.ts page will not render. Using unstable_rethrow will re-throw the internal error, and the not-found.ts page will be correctly rendered to the user. Below is a simplified example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { notFound } from 'next/navigation';

// not-found.ts will not render
export default async function Page() {
  let data;

  try {
    const response = await fetch('...');
    if (response.status === 404) notFound();
    // ...
  } catch (error) {
    console.error(error);
  }
}

// not-found.ts will render due to the rethrow of the error

export default async function Page() {
  let data;
  try {
    const response = await fetch('https://.../');
    if (response.status === 404) notFound();
    // ...
  } catch (error) {
    unstable_rethrow(error);
    console.error(error);
  }
}

In addition to the notFound() function, unstable_rethrow supports re-throwing errors in cases of redirect() and permanentRedirect() as well.

Summary

Next.js 15 introduces a series of enhancements that make using this framework even more appealing to developers. One of the key features is the new Turbopack tool, which replaces Webpack and offers significantly faster compilation times. This makes the process of developing and testing applications more efficient. Additionally, Next.js 15 provides extended support for TypeScript in configuration files and native support for ESLint 9, which facilitates maintaining high code quality.

The framework also introduces improvements in image and font management, including the switch to the Sharp image optimization library and the ability to define custom font family names through next/font, allowing for greater control over resources in the application. Integration with React 19 enables developers to benefit from the latest enhancements and performance gains available in this library, which is vital for the efficiency and modernity of projects.

Next.js 15 also offers advanced features that facilitate application scaling, including improved static generation and dynamic routing management. Innovations such as Server Components HMR (Hot Module Replacement) and enhanced functionality of Server Actions increase the security and performance of server solutions. Changes in caching management and optimizations in client navigation, including new options for prefetching, contribute to faster and smoother interactions with the application.

Additionally, it is worth noting the experimental features such as the React Compiler and Static Generation Control, which offer the opportunity to experiment with the latest optimization methods, translating into an advantage in creating and developing future versions of applications. New diagnostic and debugging tools like the Static Indicator significantly facilitate performance monitoring and problem-solving during development.

In conclusion, Next.js 15 offers a rich set of tools that support the creation of efficient, secure, and easier-to-maintain web applications. These enhancements make it an excellent choice for developers seeking a modern and sophisticated framework for creating web applications. We hope this article has helped in understanding some aspects of the new version of Next.js 15 and encouraged you to check it out personally.