Edge Runtime supported Network APIs
The Edge Runtime supports these Network APIs: Blob, fetch, FetchEvent, File, FormData, Headers, Request, Response, URLSearchParams, WebSocket.
Next.js · API reference · all subjects
config
577 notes in this subject, read out of this brain and free to use. This is page 9 of 10.
Edge Runtime streaming support depends on deployment adapter
Both Node.js Runtime and Edge Runtime can support streaming depending on your deployment adapter.
Edge Runtime supported Encoding APIs
The Edge Runtime supports these Encoding APIs: atob, btoa, TextDecoder, TextDecoderStream, TextEncoder, TextEncoderStream.
Edge Runtime supported Stream APIs
The Edge Runtime supports these Stream APIs: ReadableStream, ReadableStreamBYOBReader, ReadableStreamDefaultReader, TransformStream, WritableStream, WritableStreamDefaultWriter.
Edge Runtime supported Web Standard APIs
The Edge Runtime supports comprehensive Web Standard APIs including: AbortController, Array, ArrayBuffer, Atomics, BigInt, BigInt64Array, BigUint64Array, Boolean, clearInterval, clearTimeout, console, DataView, Date, decodeURI, decodeURIComponent, DOMException, encodeURI, encodeURIComponent, Error, EvalError, Float32Array, Float64Array, Function, Infinity, Int8Array, Int16Array, Int32Array, Intl, isFinite, isNaN, JSON, Map, Math, Number, Object, parseFloat, parseInt, Promise, Proxy, queueMicrotask, RangeError, ReferenceError, Reflect, RegExp, Set, setInterval, setTimeout, SharedArrayBuffer, String, structuredClone, Symbol, SyntaxError, TypeError, Uint8Array, Uint8ClampedArray, Uint32Array, URIError, URL, URLPattern, URLSearchParams, WeakMap, WeakSet, WebAssembly.
Edge Runtime AsyncLocalStorage polyfill
The Edge Runtime provides AsyncLocalStorage as a Next.js specific polyfill.
Edge Runtime limited API set limitation
The Edge Runtime contains a limited set of APIs and does not support all Node.js APIs. Some packages may not work as expected.
Edge Runtime process.env support
Environment variables can be accessed using process.env in the Edge Runtime for both next dev and next build.
Edge Runtime does not support native Node.js APIs
Native Node.js APIs are not supported in the Edge Runtime. You cannot read or write to the filesystem. Calling require directly is not allowed; ES Modules must be used instead.
Custom status code for redirects instead of permanent
In rare cases, you can use the `statusCode` property instead of the `permanent` property, but not both. To ensure IE11 compatibility, a `Refresh` header is automatically added for the 308 status code.
Path matching with single parameter
Path matches work with parameters like `/old-blog/:slug` which matches `/old-blog/first-post` and `/old-blog/post-1` but not `/old-blog/a/b` (no nested paths). Patterns are anchored to the start, so `/old-blog/:slug` will not match `/archive/old-blog/first-post`. Matched parameters can be used in the destination path.
redirects configuration in next.config.js
The `redirects` key in `next.config.js` allows you to redirect incoming request paths to different destination paths. It is defined as a synchronous or async function that returns an array of redirect objects.
Redirect object properties: source, destination, permanent
A redirect object has the following required properties: `source` (the incoming request path pattern), `destination` (the path to route to), and `permanent` (boolean). If `permanent` is true, a 308 status code is used to instruct clients/search engines to cache the redirect forever. If `permanent` is false, a 307 status code is used for a temporary redirect that is not cached.
Why Next.js uses 307 and 308 status codes for redirects
Next.js uses 307 for temporary redirects and 308 for permanent redirects to explicitly preserve the request method used. Traditionally, 302 and 301 status codes were used, but many browsers changed the request method to GET regardless of the original method. For example, a POST request with a 302 redirect might become a GET request after the redirect, which is unexpected.
Redirect object optional properties: basePath, locale, has, missing
Optional redirect properties are: `basePath` (false or undefined; if false, the basePath won't be included when matching), `locale` (false or undefined; whether the locale should not be included when matching), `has` (array of has objects with type, key, and value properties for conditional matching), and `missing` (array of missing objects with type, key, and value properties for conditional matching).
Redirect processing order: before filesystem
Redirects are checked before the filesystem, which includes pages and `/public` files.
Client-side routing with redirects in Pages Router
When using the Pages Router, redirects are not applied to client-side routing (Link, router.push) unless Proxy is present and matches the path.
Query values passed through redirects
When a redirect is applied, any query values provided in the request will be passed through to the redirect destination. For example, a request to `/old-blog/post-1?hello=world` with a redirect from `/old-blog/:path*` to `/blog/:path*` will result in a redirect to `/blog/post-1?hello=world`.
Path parameter syntax requires forward slash before colon
Remember to include the forward slash `/` before the colon `:` in path parameters of the `source` and `destination` paths. If you omit it, the path will be treated as a literal string and you run the risk of causing infinite redirects.
Regex path matching with parentheses
To match a regex path, wrap the regex in parentheses after a parameter. For example, `/post/:slug(\d{1,})` will match `/post/123` but not `/post/abc`. Matched parameters can be used in the destination.
Escaping special characters in redirect source paths
The following characters are used for regex path matching and must be escaped by adding `\` before them when used in the `source` as non-special values: `(`, `)`, `{`, `}`, `:`, `*`, `+`, `?`. For example, to match `/english(default)/something`, use source `/english\(default\)/:slug`.
has and missing objects for conditional redirect matching
Both the `source` and all `has` items must match, and all `missing` items must not match for the redirect to be applied. `has` and `missing` items have the following fields: `type` (string; must be header, cookie, host, or query), `key` (string; the key from the selected type to match against), `value` (string or undefined; the value to check for; if undefined any value will match; a regex like string can capture a specific part of the value).
Conditional redirect with header matching example
A redirect can be applied only if a specific header is present. For example, if the header `x-redirect-me` is present, the redirect will be applied. If the header `x-do-not-redirect` is present, the redirect will NOT be applied.
Regex value capture in has/missing for destination reuse
A regex-like string can be used in the `value` field to capture a specific part of the value. For example, if the value `first-(?<paramName>.*)` is used for `first-second`, then `second` will be usable in the destination with `:paramName`. If the value is provided without a named capture group, the value will not be available in the destination.
Redirects with basePath support
When using `basePath` support, each `source` and `destination` in redirects is automatically prefixed with the `basePath` unless you add `basePath: false` to the redirect. For example, with `basePath: '/docs'`, a source `/with-basePath` automatically becomes `/docs/with-basePath`. Setting `basePath: false` allows external redirects.
Redirects with i18n in App Router
In the App Router, you can include locales in redirects, but only as hardcoded paths. For dynamic or per-request locale handling, use dynamic route segments and proxy, which can redirect based on the user's preferred language.
Other redirect methods in Next.js
Redirects can also be implemented inside API Routes and Route Handlers based on the incoming request, inside `getStaticProps` and `getServerSideProps` to redirect specific pages at request-time, and using dynamic route segments and proxy for internationalization.
redirects version history
The `redirects` feature was added in v9.5.0. The `has` property was added in v10.2.0. The `missing` property was added in v13.3.0.
Wildcard path matching example
To match a wildcard path, use `*` after a parameter. For example, `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`. Matched parameters can be used in the destination with the same wildcard syntax.
Path parameter modifiers: *, +, ?
You can use modifiers on parameters: `*` (zero or more), `+` (one or more), `?` (zero or one). For example, `/blog/:slug*` matches `/blog`, `/blog/a`, and `/blog/a/b/c`.
trailingSlash config option in next.config.js
The trailingSlash configuration option can be set in next.config.js. When set to true, URLs without trailing slashes are redirected to their counterparts with trailing slashes. For example, /about will redirect to /about/.
trailingSlash exceptions for static files
When using trailingSlash: true, certain URLs are exceptions and will not have a trailing slash appended. Static file URLs (files with extensions like /file.txt, images/photos/picture.png) and any paths under .well-known/ (like .well-known/subfolder/config.json) will remain unchanged.
trailingSlash with output export
When used with output: "export" configuration, the /about page will output /about/index.html instead of the default /about.html when trailingSlash is enabled.
trailingSlash code example
module.exports = { trailingSlash: true, }
trailingSlash version history
trailingSlash was added in Next.js v9.5.0.
trailingSlash config default behavior
By default, Next.js redirects URLs with trailing slashes to their counterpart without a trailing slash. For example, /about/ will redirect to /about.
rewrites afterFiles behavior
Rewrites in `afterFiles` are checked after pages and public files are checked but before dynamic routes. They are tried in order. If a `source`, `has`, and `missing` matches the request, it's rewritten to `destination`; the first rewrite that resolves to a static file, page, or dynamic route is served.
rewrites fallback behavior
Rewrites in `fallback` are checked after both pages, public files, and dynamic routes are checked. These are applied before rendering the 404 page. If you use fallback: true or 'blocking' in getStaticPaths (Pages Router), those dynamic routes take priority over the fallback rewrites defined in next.config.js (App Router), or the fallback rewrites will not be run (Pages Router).
rewrites parameter handling in destination
When using parameters in a rewrite, parameters are passed in the query by default when none of the parameters are used in the `destination`. If a parameter is used in the destination, none of the parameters will be automatically passed in the query. You can still pass parameters manually in the query if one is already used in the destination by specifying the query in the `destination`.
rewrites path matching patterns
Path matches are allowed, for example `/blog/:slug` will match `/blog/first-post` (no nested paths). The pattern `/blog/:slug` matches `/blog/first-post` and `/blog/post-1` but not `/blog/a/b`. Patterns are anchored to the start: `/blog/:slug` will not match `/archive/blog/first-post`. You can use modifiers on parameters: `*` (zero or more), `+` (one or more), `?` (zero or one). For example, `/blog/:slug*` matches `/blog`, `/blog/a`, and `/blog/a/b/c`.
rewrites regex path matching
To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`. The characters `(`, `)`, `{`, `}`, `[`, `]`, `|`, `\\`, `^`, `.`, `:`, `*`, `+`, `-`, `?`, `$` are used for regex path matching, so when used in the `source` as non-special values they must be escaped by adding `\\` before them.
rewrites header cookie and query matching with has
To only match a rewrite when header, cookie, or query values also match, the `has` field can be used. Both the `source` and all `has` items must match for the rewrite to be applied. `has` items can have the following fields: `type` (String, required) - must be either `header`, `cookie`, `host`, or `query`; `key` (String, required) - the key from the selected type to match against; `value` (String or undefined, optional) - the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value `first-(?<paramName>.*)` is used for `first-second` then `second` will be usable in the destination with `:paramName`.
rewrites config option basics
Rewrites allow you to map an incoming request path to a different destination path. They act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. Rewrites are applied to client-side routing. In contrast, redirects will reroute to a new page and show the URL changes. You can define rewrites using the `rewrites` key in `next.config.js`.
rewrites function signature and return types
The `rewrites` key in `next.config.js` can be defined as a synchronous or async function. It should return, or resolve to, either an array or an object of arrays holding objects with `source` and `destination` properties. When the function returns an array, rewrites are applied after checking the filesystem (pages and /public files) and before dynamic routes. When it returns an object of arrays (as of v10.1), this behavior can be changed with `beforeFiles`, `afterFiles`, and `fallback` keys.
rewrites object properties
Each rewrite object has the following properties: `source` (String, required) - the incoming request path pattern; `destination` (String, required) - the path you want to route to; `basePath` (false or undefined, optional) - if false the basePath won't be included when matching, can be used for external rewrites only; `locale` (false or undefined, optional) - whether the locale should not be included when matching; `has` (array, optional) - array of has objects with `type`, `key` and `value` properties; `missing` (array, optional) - array of missing objects with `type`, `key` and `value` properties.
rewrites App Router routing order
In the App Router, Next.js checks routes in this order: 1. headers are checked/applied; 2. redirects are checked/applied; 3. proxy is checked; 4. beforeFiles rewrites are checked/applied; 5. static files from the public directory, _next/static files, and non-dynamic pages are checked/served; 6. afterFiles rewrites are tried in order; 7. dynamic routes are matched against the current path; 8. fallback rewrites are checked/applied before rendering the 404 page.
rewrites beforeFiles behavior
Rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source; they continue until all `beforeFiles` have been checked. For each entry, if `source`, `has`, and `missing` matches the request, it's rewritten to `destination`. This allows overriding page files.
rewrites missing field for conditional matching
The `missing` field is an array of missing objects with the same structure as `has` objects (`type`, `key`, `value` properties). All `missing` items must not match for the rewrite to be applied. This allows you to apply rewrites when certain headers, cookies, queries, or hosts are NOT present.
rewrites to external URL
Rewrites allow you to rewrite to an external URL. This is especially useful for incrementally adopting Next.js. For example, you can rewrite `/blog` to `https://example.com/blog` and `/blog/:slug` to `https://example.com/blog/:slug`. Matched parameters can be used in the external destination URL.
rewrites with trailingSlash config
If you're using `trailingSlash: true`, you also need to insert a trailing slash in the `source` parameter. If the destination server is also expecting a trailing slash it should be included in the `destination` parameter as well.
rewrites incremental adoption pattern
You can have Next.js fall back to proxying to an existing website after checking all Next.js routes using fallback rewrites. This way you don't have to change the rewrites configuration when migrating more pages to Next.js. Example: a fallback rewrite with source `/:path*` pointing to an external domain.
rewrites with basePath support
When leveraging `basePath` support with rewrites, each `source` and `destination` is automatically prefixed with the `basePath` unless you add `basePath: false` to the rewrite. When `basePath: false` is set, the rewrite cannot be used for internal rewrites (e.g., `destination: '/another'`) and must point to an external URL.
rewrites with i18n support (Pages Router only)
When leveraging i18n support with rewrites in the Pages Router, each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the rewrite. If `locale: false` is used, you must prefix the `source` and `destination` with a locale for it to be matched correctly. When `locale: false` is set, it's still possible to match all locales using patterns like `/:locale/api-alias/:path*`.
rewrites version history
Version history: v13.3.0 added `missing` field; v10.2.0 added `has` field; v9.5.0 added Headers support.
rewrites basic example
Example of a basic rewrite in next.config.js: ```js module.exports = { rewrites() { return [ { source: '/about', destination: '/', }, ] }, } ``` Navigating to `<Link href="/about">` will serve content from `/` while keeping the URL as `/about`.
rewrites beforeFiles, afterFiles, fallback example
Example of rewrites with beforeFiles, afterFiles, and fallback: ```js module.exports = { rewrites() { return { beforeFiles: [ { source: '/some-page', destination: '/somewhere-else', has: [{ type: 'query', key: 'overrideMe' }], }, ], afterFiles: [ { source: '/non-existent', destination: '/somewhere-else', }, ], fallback: [ { source: '/:path*', destination: `https://my-old-site.com/:path*`, }, ], } }, } ```
rewrites path matching example
Example of path matching in rewrites: ```js module.exports = { rewrites() { return [ { source: '/blog/:slug', destination: '/news/:slug', }, ] }, } ``` The pattern `/blog/:slug` matches `/blog/first-post` and `/blog/post-1` but not `/blog/a/b`.
rewrites wildcard path matching example
Example of wildcard path matching in rewrites: ```js module.exports = { rewrites() { return [ { source: '/blog/:slug*', destination: '/news/:slug*', }, ] }, } ``` The pattern `/blog/:slug*` matches `/blog`, `/blog/a`, and `/blog/a/b/c`.
rewrites regex path matching example
Example of regex path matching in rewrites: ```js module.exports = { rewrites() { return [ { source: '/old-blog/:post(\\d{1,})', destination: '/blog/:post', }, ] }, } ``` The pattern `/old-blog/:post(\\d{1,})` matches `/old-blog/123` but not `/old-blog/abc`.
rewrites regex character escaping example
Example of escaping special regex characters in rewrites: ```js module.exports = { rewrites() { return [ { source: '/english\\(default\\)/:slug', destination: '/en-us/:slug', }, ] }, } ``` This will match `/english(default)/something` being requested.