config

577 notes in this subject, read out of this brain and free to use. This is page 5 of 10.

productionBrowserSourceMaps performance impact

Enabling productionBrowserSourceMaps can increase next build time and increases memory usage during next build.

productionBrowserSourceMaps example configuration

To enable source maps in production, set productionBrowserSourceMaps to true in next.config.js: ```js filename="next.config.js" module.exports = { productionBrowserSourceMaps: true, } ```

proxyClientMaxBodySize string format

proxyClientMaxBodySize can be specified using a human-readable string format with supported units: b, kb, mb, gb. Example: proxyClientMaxBodySize: '1mb'

proxyClientMaxBodySize configuration option

proxyClientMaxBodySize is an experimental configuration option in next.config.js/ts that sets a size limit on the buffered request body when proxy is used. By default, the maximum body size is 10MB. When proxy is used, Next.js automatically clones and buffers the request body in memory to enable multiple reads in both the proxy and the underlying route handler.

proxyClientMaxBodySize example with proxy and route handler

When using proxyClientMaxBodySize, the request body is buffered according to the size limit and available both in the proxy function and in the route handler. Example: a proxy function can read the body with await request.text(), and if the body exceeded the limit, only partial data is available. The same body is then available in the route handler, which can also read it with await request.text().

proxyClientMaxBodySize behavior when limit exceeded

When a request body exceeds the configured proxyClientMaxBodySize limit: (1) Next.js buffers only the first N bytes up to the limit, (2) a warning is logged to the console indicating which route exceeded the limit, (3) the request continues processing normally but only the partial body is available, and (4) the request does not fail or return an error to the client.

proxyClientMaxBodySize applies only with proxy

The proxyClientMaxBodySize setting only applies when proxy is used in the application. The limit applies per-request, not globally across all concurrent requests.

proxyClientMaxBodySize number format

proxyClientMaxBodySize can be specified as a number representing bytes. Example: proxyClientMaxBodySize: 1048576 (which equals 1MB in bytes).

proxyClientMaxBodySize configuration location

proxyClientMaxBodySize is configured under the experimental property in next.config.ts or next.config.js. Example: experimental: { proxyClientMaxBodySize: '1mb' }

React Compiler benefits

The React Compiler automatically optimizes component rendering and reduces the need for manual memoization using useMemo and useCallback.

reactCompiler true example

Example configuration enabling React Compiler for all relevant files: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { reactCompiler: true, } export default nextConfig ```

reactCompiler annotation mode example

Example configuration enabling annotation mode for opt-in React Compiler optimization: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { reactCompiler: { compilationMode: 'annotation', }, } export default nextConfig ```

reactCompiler with compilationMode annotation

Set reactCompiler.compilationMode to 'annotation' to enable opt-in mode. In this mode, you must annotate specific components or hooks with the 'use memo' directive from React to enable the React Compiler for them.

reactCompiler config option

The reactCompiler option in next.config.js enables the React Compiler to automatically optimize component rendering. It can be set to true to enable the compiler for all relevant files, or configured as an object with additional options like compilationMode.

React Compiler how it works in Next.js

The React Compiler runs through a Babel plugin. Next.js uses a custom SWC optimization that only applies the React Compiler to relevant files such as those with JSX or React Hooks, avoiding unnecessary compilation of all files and keeping builds fast.

React Compiler installation

To use the React Compiler with Next.js, install the babel-plugin-react-compiler as a dev dependency using npm, pnpm, yarn, or bun: npm install -D babel-plugin-react-compiler or equivalent.

reactMaxHeadersLength configuration example

In next.config.js, configure reactMaxHeadersLength by setting it as a module export property: module.exports = { reactMaxHeadersLength: 1000 }

reactMaxHeadersLength use case

React emits headers during prerendering that can be added to the response to improve performance by allowing the browser to preload resources like fonts, scripts, and stylesheets. If a reverse proxy between the browser and server doesn't support long headers, you should set reactMaxHeadersLength to a lower value to prevent header truncation.

reactMaxHeadersLength config option

The reactMaxHeadersLength option in next.config.js sets the maximum length of headers that React emits and adds to the response. The default value is 6000 bytes. This option is only available in App Router.

Incremental Strict Mode migration with React.StrictMode

If you are not ready to enable Strict Mode for your entire application, you can incrementally migrate on a page-by-page basis by wrapping specific pages or components with the React.StrictMode component.

App router Strict Mode default

Since Next.js 13.5.1, Strict Mode is enabled by default (true) when using the app router. The reactStrictMode configuration is only necessary for the pages router.

Strict Mode purpose

Strict Mode highlights potential problems in an application, helping identify unsafe lifecycles, legacy API usage, and other problematic features.

Strict Mode is development-only

React's Strict Mode is a development mode only feature and does not affect production builds.

reactStrictMode configuration syntax

In next.config.js, enable Strict Mode with: module.exports = { reactStrictMode: true, }

reactStrictMode config option

reactStrictMode is a boolean configuration option in next.config.js that enables React's Strict Mode for the Next.js application. It is set by default to true with the app router since Next.js 13.5.1. For the pages router, you must explicitly set reactStrictMode: true to enable it. You can disable Strict Mode by setting reactStrictMode: false.

sassOptions implementation property

The implementation property in sassOptions specifies which Sass implementation to use. The value 'sass-embedded' is a supported option.

sassOptions configuration example

Example sassOptions configuration: In next.config.ts, define sassOptions with properties like additionalData and implementation, then spread them into the nextConfig sassOptions object: const nextConfig: NextConfig = { sassOptions: { ...sassOptions, implementation: 'sass-embedded', } }

sassOptions config option

sassOptions is a configuration option in next.config.ts or next.config.js that allows you to configure the Sass compiler.

Sass functions property webpack-only

The functions property for defining custom Sass functions is only supported with webpack. When using Turbopack, custom Sass functions are not available because Turbopack's Rust-based architecture cannot directly execute JavaScript functions passed through this option.

sassOptions type safety limitation

sassOptions properties are not fully typed outside of the implementation property because Next.js does not maintain the other possible properties.

sassOptions additionalData property

The additionalData property in sassOptions allows you to inject additional Sass code that will be prepended to all Sass files. It accepts a string containing valid Sass syntax, such as variable definitions.

serverActions configuration structure

The serverActions configuration is located under the experimental key in next.config.js. It accepts the following options: allowedOrigins (array of safe origin domains), and bodySizeLimit (request body size limit). For Next.js v13, serverActions can be set to a boolean true to enable the feature.

serverActions.allowedOrigins example configuration

The allowedOrigins option is configured as follows: module.exports = { experimental: { serverActions: { allowedOrigins: ['my-proxy.com', '*.my-proxy.com'] } } }

serverActions.bodySizeLimit configuration

The bodySizeLimit option in serverActions configuration sets the maximum size of the request body sent to a Server Action. The default limit is 1MB to prevent excessive server resource consumption and potential DDoS attacks. The value can be specified as a number of bytes (e.g., 1000) or as a string format supported by bytes (e.g., '500kb' or '3mb'). The limit applies to the raw HTTP request body, including bytes added by multipart/form-data for boundaries, part headers, and field metadata. When configuring uploads close to the limit, an additional 10–20 KB should be left for multipart overhead as a rule of thumb.

Server Actions stable in Next.js 14, enabled by default

Server Actions became a stable feature in Next.js 14 and are enabled by default. In earlier versions of Next.js (v13 and earlier), Server Actions can be enabled by setting experimental.serverActions to true in next.config.js.

serverActions.bodySizeLimit example configuration

The bodySizeLimit option is configured as follows: module.exports = { experimental: { serverActions: { bodySizeLimit: '2mb' } } }

Enabling Server Actions in Next.js v13

To enable Server Actions in Next.js v13, set experimental.serverActions to true in next.config.js as follows: const config = { experimental: { serverActions: true } }; module.exports = config

serverActions.allowedOrigins configuration

The allowedOrigins option in serverActions configuration accepts a list of extra safe origin domains from which Server Actions can be invoked. Next.js compares the origin of a Server Action request with the host domain to ensure they match and prevent CSRF attacks. If allowedOrigins is not provided, only the same origin is allowed. The option supports wildcard patterns like '*.my-proxy.com'.

serverComponentsHmrCache option

The serverComponentsHmrCache is an experimental configuration option that controls whether fetch responses in Server Components are cached across Hot Module Replacement (HMR) refreshes in local development. This setting defaults to true, meaning the HMR cache is enabled by default.

serverComponentsHmrCache default behavior

By default, the HMR cache applies to all fetch requests in Server Components, including those with the cache: 'no-store' option. This means uncached requests will not show fresh data between HMR refreshes. However, the cache is cleared on navigation or full-page reloads.

serverComponentsHmrCache configuration example

To disable the HMR cache, set serverComponentsHmrCache to false in the experimental object of next.config.js: experimental: { serverComponentsHmrCache: false }

serverComponentsHmrCache benefits

The serverComponentsHmrCache option results in faster responses and reduced costs for billed API calls during local development by caching fetch responses across HMR refreshes.

serverComponentsHmrCache cache clearing

The HMR cache for Server Components is cleared when the user navigates to a different page or performs a full-page reload, even if serverComponentsHmrCache is enabled.

staleTimes dynamic property

The dynamic property in staleTimes specifies the revalidation time in seconds for pages that are neither statically generated nor fully prefetched (e.g. with prefetch={true}). Default: 0 seconds (not cached). This default changed from 30 seconds to 0 seconds in v15.0.0.

staleTimes does not affect back/forward caching

The staleTimes configuration does not change back/forward caching behavior. Back/forward caching is maintained to prevent layout shift and to prevent losing the browser scroll position.

staleTimes experimental config

staleTimes is an experimental feature that enables caching of page segments in the Client Cache. It is configured in next.config.js under the experimental.staleTimes object with two properties: dynamic and static, each specifying revalidation times in seconds.

staleTimes static property

The static property in staleTimes specifies the revalidation time in seconds for statically generated pages, or when the prefetch prop on Link is set to true, or when calling router.prefetch(). Default: 5 minutes (300 seconds).

staleTimes with loading boundaries

Loading boundaries are considered reusable for the static period defined in the staleTimes configuration.

staleTimes does not affect partial rendering

The staleTimes configuration does not affect partial rendering, meaning shared layouts will not automatically be refetched on every navigation; only the page segment that changes will be refetched.

staleTimes configuration example

Example next.config.js with staleTimes experimental feature: ```js /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { staleTimes: { dynamic: 30, static: 180, }, }, } module.exports = nextConfig ```

transpilePackages and serverExternalPackages conflict

A package cannot appear in both transpilePackages and serverExternalPackages. Next.js throws an error at build start if a package is listed in both.

transpilePackages automatic inclusion

Packages listed in optimizePackageImports and the entries in default-transpiled-packages.json are added to transpilePackages automatically. You do not need to repeat them.

transpilePackages config option

transpilePackages is a Next.js config option that compiles and bundles dependencies instead of treating them as untouched runtime code. It accepts an array of package names, including scoped names like @scope/pkg. Paths and glob patterns are not supported. It replaces the next-transpile-modules package.

transpilePackages version history

transpilePackages was added in Next.js v13.0.0.

transpilePackages syntax and example

transpilePackages is configured in next.config.js as an array of package names. Example: const nextConfig = { transpilePackages: ['package-name', '@scope/pkg'], }

When to use transpilePackages for raw TypeScript or JSX

Add a package to transpilePackages when a node_modules dependency ships raw TypeScript or JSX. Next.js does not compile code inside node_modules by default. Listing the package opts it in, or you can build the package to plain JavaScript and point its main/exports at the compiled output.

transpilePackages for Webpack Pages Router monorepo dependencies

Add a package to transpilePackages when you build with Webpack for the Pages Router and the dependency's source lives outside the next app's directory, such as an apps/web app importing packages/ui in the same monorepo.

transpilePackages for Pages Router node_modules bundling

Add a package to transpilePackages when you use the Pages Router and want a node_modules dependency bundled into the route. Pages Router loads node_modules server-side dependencies through Node.js require at runtime. Listing the package bundles its source into the route instead. App Router already bundles Server Component and Route Handler dependencies unless the package is listed in serverExternalPackages.

Turbopack and Webpack automatic workspace transpilation

Turbopack transpiles workspace packages (npm, pnpm, or Yarn workspaces) in your monorepo automatically under both routers. Webpack does the same for the App Router. This means you typically do not need to add workspace packages to transpilePackages.

Turbopack FileSystem Cache configuration example

To configure Turbopack FileSystem Cache in next.config.ts: import type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { turbopackFileSystemCacheForDev: true, turbopackFileSystemCacheForBuild: true, }, } export default nextConfig

Give your agent this brain