rsnext/docs/api-reference/edge-runtime.md

185 lines
12 KiB
Markdown
Raw Normal View History

---
description: The Next.js Edge Runtime is based on standard Web APIs. Learn more about the supported APIs available.
---
# Edge Runtime
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
The Next.js Edge Runtime is based on standard Web APIs, which is used by [Middleware](/docs/middleware.md) and [Edge API Routes](/docs/api-routes/edge-api-routes.md).
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
## Network APIs
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
- [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
- [`Fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
- [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent)
- [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
- [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
- [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
- [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
- [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File)
- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
## Encoding APIs
- [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
- [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/atob)
- [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/btoa)
## Web Stream APIs
- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
- [`ReadableStreamBYOBReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader)
- [`ReadableStreamDefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader)
- [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
- [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
- [`WritableStreamDefaultWriter`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter)
## Web Crypto APIs
- [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
- [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
- [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
## Web Standards APIs
- [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
- [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
- [`Web Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
## V8 Primitives
- [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
- [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
- [`Atomics`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics)
- [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
- [`BigInt64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array)
- [`BigUint64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array)
- [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
- [`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearInterval)
- [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearTimeout)
- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/Console)
- [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
- [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
- [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI)
- [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent)
- [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
- [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
- [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
- [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError)
- [`Float32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array)
- [`Float64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array)
- [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
- [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
- [`Int8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array)
- [`Int16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int16Array)
- [`Int32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array)
- [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
- [`isFinite`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite)
- [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN)
- [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
- [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
- [`Math`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math)
- [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
- [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
- [`parseFloat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat)
- [`parseInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt)
- [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
- [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
- [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError)
- [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError)
- [`Reflect`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect)
- [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
- [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
- [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setInterval)
- [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout)
- [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)
- [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
- [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)
- [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError)
- [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
- [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
- [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError)
- [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
- [`Uint8ClampedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray)
- [`Uint16Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array)
- [`Uint32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array)
- [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
- [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
- [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)
- [`WebAssembly`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly)
## Next.js Specific Polyfills
- [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
## Environment Variables
You can use `process.env` to access [Environment Variables](/docs/basic-features/environment-variables.md) for both `next dev` and `next build`.
Running `console.log` on `process.env` **will not** show all your Environment Variables. You have to access the variables directly as shown below:
```javascript
console.log(process.env)
// { NEXT_RUNTIME: 'edge' }
console.log(process.env.TEST_VARIABLE)
// value
```
## Unsupported APIs
The Edge Runtime has some restrictions including:
- Native Node.js APIs **are not supported**. For example, you can't read or write to the filesystem
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
- `node_modules` _can_ be used, as long as they implement ES Modules and do not use native Node.js APIs
- Calling `require` directly is **not allowed**. Use ES Modules instead
The following JavaScript language features are disabled, and **will not work:**
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
- `eval`: Evaluates JavaScript code represented as a string
- `new Function(evalString)`: Creates a new function with the code provided as an argument
feat(edge): allows configuring Dynamic code execution guard (#39539) ### 📖 What's in there? Dynamic code evaluation (`eval()`, `new Function()`, ...) is not supported on the edge runtime, hence why we fail the build when detecting such statement in the middleware or `experimental-edge` routes at build time. However, there could be false positives, which static analysis and tree-shaking can not exclude: - `qs` through these dependencies (get-intrinsic: [source](https://github.com/ljharb/get-intrinsic/blob/main/index.js#L12)) - `function-bind` ([source](https://github.com/Raynos/function-bind/blob/master/implementation.js#L42)) - `has` ([source](https://github.com/tarruda/has/blob/master/src/index.js#L5)) This PR leverages the existing `config` export to let user allow some of their files. it’s meant for allowing users to import 3rd party modules who embed dynamic code evaluation, but do not use it (because or code paths), and can't be tree-shaked. By default, it’s keeping the existing behavior: warn in dev, fails to build. If users allow dynamic code, and that code is reached at runtime, their app stills breaks. ### 🧪 How to test? - (existing) integration tests for disallowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-dynamic` - (new) integration tests for allowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-configurable` - (amended) production tests for validating the new configuration keys: `pnpm testheadless --testPathPattern=config-validations` To try it live, you could have an application such as: ```js // lib/index.js /* eslint-disable no-eval */ export function hasUnusedDynamic() { if ((() => false)()) { eval('100') } } export function hasDynamic() { eval('100') } // pages/index.jsx export default function Page({ edgeRoute }) { return <p>{edgeRoute}</p> } export const getServerSideProps = async (req) => { const res = await fetch(`http://localhost:3000/api/route`) const data = await res.json() return { props: { edgeRoute: data.ok ? `Hi from the edge route` : '' } } } // pages/api/route.js import { hasDynamic } from '../../lib' export default async function handle() { hasDynamic() return Response.json({ ok: true }) } export const config = { runtime: 'experimental-edge' , allowDynamic: '/lib/**' } ``` Playing with `config.allowDynamic`, you should be able to: - build the app even if it uses `eval()` (it will obviously fail at runtime) - build the app that _imports but does not use_ `eval()` - run the app in dev, even if it uses `eval()` with no warning ### 🆙 Notes to reviewers Before adding documentation and telemetry, I'd like to collect comments on a couple of points: - the overall design for this feature: is a list of globs useful and easy enough? - should the globs be relative to the application root (current implementation) to to the edge route/middleware file? - (especially to @sokra) is the implementation idiomatic enough? I've leverage loaders to read the _entry point_ configuration once, then the ModuleGraph to get it back during the parsing phase. I couldn't re-use the existing `getExtractMetadata()` facility since it's happening late after the parsing. - there's a glitch with `import { ServerRuntime } from '../../types'` in `get-page-static-info.ts` ([here](https://github.com/vercel/next.js/pull/39539/files#diff-cb7ac6392c3dd707c5edab159c3144ec114eafea92dad5d98f4eedfc612174d2L12)). I had to use `next/types` because it was failing during lint. Any clue why? ### ☑️ Checklist - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [x] Integration tests added - [x] Documentation added - [x] Telemetry added. In case of a feature if it's used or not. - [x] Errors have helpful link attached, see `contributing.md`
2022-09-13 00:01:00 +02:00
- `WebAssembly.compile`
- `WebAssembly.instantiate` with [a buffer parameter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#primary_overload_%E2%80%94_taking_wasm_binary_code)
In rare cases, your code could contain (or import) some dynamic code evaluation statements which _can not be reached at runtime_ and which can not be removed by treeshaking.
You can relax the check to allow specific files with your Middleware or Edge API Route exported configuration:
```javascript
export const config = {
runtime: 'edge', // for Edge API Routes only
unstable_allowDynamic: [
feat(edge): allows configuring Dynamic code execution guard (#39539) ### 📖 What's in there? Dynamic code evaluation (`eval()`, `new Function()`, ...) is not supported on the edge runtime, hence why we fail the build when detecting such statement in the middleware or `experimental-edge` routes at build time. However, there could be false positives, which static analysis and tree-shaking can not exclude: - `qs` through these dependencies (get-intrinsic: [source](https://github.com/ljharb/get-intrinsic/blob/main/index.js#L12)) - `function-bind` ([source](https://github.com/Raynos/function-bind/blob/master/implementation.js#L42)) - `has` ([source](https://github.com/tarruda/has/blob/master/src/index.js#L5)) This PR leverages the existing `config` export to let user allow some of their files. it’s meant for allowing users to import 3rd party modules who embed dynamic code evaluation, but do not use it (because or code paths), and can't be tree-shaked. By default, it’s keeping the existing behavior: warn in dev, fails to build. If users allow dynamic code, and that code is reached at runtime, their app stills breaks. ### 🧪 How to test? - (existing) integration tests for disallowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-dynamic` - (new) integration tests for allowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-configurable` - (amended) production tests for validating the new configuration keys: `pnpm testheadless --testPathPattern=config-validations` To try it live, you could have an application such as: ```js // lib/index.js /* eslint-disable no-eval */ export function hasUnusedDynamic() { if ((() => false)()) { eval('100') } } export function hasDynamic() { eval('100') } // pages/index.jsx export default function Page({ edgeRoute }) { return <p>{edgeRoute}</p> } export const getServerSideProps = async (req) => { const res = await fetch(`http://localhost:3000/api/route`) const data = await res.json() return { props: { edgeRoute: data.ok ? `Hi from the edge route` : '' } } } // pages/api/route.js import { hasDynamic } from '../../lib' export default async function handle() { hasDynamic() return Response.json({ ok: true }) } export const config = { runtime: 'experimental-edge' , allowDynamic: '/lib/**' } ``` Playing with `config.allowDynamic`, you should be able to: - build the app even if it uses `eval()` (it will obviously fail at runtime) - build the app that _imports but does not use_ `eval()` - run the app in dev, even if it uses `eval()` with no warning ### 🆙 Notes to reviewers Before adding documentation and telemetry, I'd like to collect comments on a couple of points: - the overall design for this feature: is a list of globs useful and easy enough? - should the globs be relative to the application root (current implementation) to to the edge route/middleware file? - (especially to @sokra) is the implementation idiomatic enough? I've leverage loaders to read the _entry point_ configuration once, then the ModuleGraph to get it back during the parsing phase. I couldn't re-use the existing `getExtractMetadata()` facility since it's happening late after the parsing. - there's a glitch with `import { ServerRuntime } from '../../types'` in `get-page-static-info.ts` ([here](https://github.com/vercel/next.js/pull/39539/files#diff-cb7ac6392c3dd707c5edab159c3144ec114eafea92dad5d98f4eedfc612174d2L12)). I had to use `next/types` because it was failing during lint. Any clue why? ### ☑️ Checklist - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [x] Integration tests added - [x] Documentation added - [x] Telemetry added. In case of a feature if it's used or not. - [x] Errors have helpful link attached, see `contributing.md`
2022-09-13 00:01:00 +02:00
'/lib/utilities.js', // allows a single file
'/node_modules/function-bind/**', // use a glob to allow anything in the function-bind 3rd party module
],
}
```
`unstable_allowDynamic` is a [glob](https://github.com/micromatch/micromatch#matching-features), or an array of globs, ignoring dynamic code evaluation for specific files. The globs are relative to your application root folder.
feat(edge): allows configuring Dynamic code execution guard (#39539) ### 📖 What's in there? Dynamic code evaluation (`eval()`, `new Function()`, ...) is not supported on the edge runtime, hence why we fail the build when detecting such statement in the middleware or `experimental-edge` routes at build time. However, there could be false positives, which static analysis and tree-shaking can not exclude: - `qs` through these dependencies (get-intrinsic: [source](https://github.com/ljharb/get-intrinsic/blob/main/index.js#L12)) - `function-bind` ([source](https://github.com/Raynos/function-bind/blob/master/implementation.js#L42)) - `has` ([source](https://github.com/tarruda/has/blob/master/src/index.js#L5)) This PR leverages the existing `config` export to let user allow some of their files. it’s meant for allowing users to import 3rd party modules who embed dynamic code evaluation, but do not use it (because or code paths), and can't be tree-shaked. By default, it’s keeping the existing behavior: warn in dev, fails to build. If users allow dynamic code, and that code is reached at runtime, their app stills breaks. ### 🧪 How to test? - (existing) integration tests for disallowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-dynamic` - (new) integration tests for allowing dynamic code evaluation: `pnpm testheadless --testPathPattern=runtime-configurable` - (amended) production tests for validating the new configuration keys: `pnpm testheadless --testPathPattern=config-validations` To try it live, you could have an application such as: ```js // lib/index.js /* eslint-disable no-eval */ export function hasUnusedDynamic() { if ((() => false)()) { eval('100') } } export function hasDynamic() { eval('100') } // pages/index.jsx export default function Page({ edgeRoute }) { return <p>{edgeRoute}</p> } export const getServerSideProps = async (req) => { const res = await fetch(`http://localhost:3000/api/route`) const data = await res.json() return { props: { edgeRoute: data.ok ? `Hi from the edge route` : '' } } } // pages/api/route.js import { hasDynamic } from '../../lib' export default async function handle() { hasDynamic() return Response.json({ ok: true }) } export const config = { runtime: 'experimental-edge' , allowDynamic: '/lib/**' } ``` Playing with `config.allowDynamic`, you should be able to: - build the app even if it uses `eval()` (it will obviously fail at runtime) - build the app that _imports but does not use_ `eval()` - run the app in dev, even if it uses `eval()` with no warning ### 🆙 Notes to reviewers Before adding documentation and telemetry, I'd like to collect comments on a couple of points: - the overall design for this feature: is a list of globs useful and easy enough? - should the globs be relative to the application root (current implementation) to to the edge route/middleware file? - (especially to @sokra) is the implementation idiomatic enough? I've leverage loaders to read the _entry point_ configuration once, then the ModuleGraph to get it back during the parsing phase. I couldn't re-use the existing `getExtractMetadata()` facility since it's happening late after the parsing. - there's a glitch with `import { ServerRuntime } from '../../types'` in `get-page-static-info.ts` ([here](https://github.com/vercel/next.js/pull/39539/files#diff-cb7ac6392c3dd707c5edab159c3144ec114eafea92dad5d98f4eedfc612174d2L12)). I had to use `next/types` because it was failing during lint. Any clue why? ### ☑️ Checklist - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [x] Integration tests added - [x] Documentation added - [x] Telemetry added. In case of a feature if it's used or not. - [x] Errors have helpful link attached, see `contributing.md`
2022-09-13 00:01:00 +02:00
Be warned that if these statements are executed on the Edge, _they will throw and cause a runtime error_.
## Related
<div class="card">
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
<a href="/docs/advanced-features/middleware.md">
<b>Middleware</b>
<small>Run code before a request is completed.</small>
</a>
</div>
<div class="card">
<a href="/docs/api-reference/next/server.md">
<b>Middleware API Reference</b>
<small>Learn more about the supported APIs for Middleware.</small>
</a>
</div>
Middleware docs update (#38111) * Initial outline added for middleware docs * Feedback changes - not included new user agent yet * edge api routes docs * middleware page some cleanup * moved api stuff to next server, added useragent * waitUntil example added * Updated env vars section * Added cookies on the request object example * fixed naming * fixed import typo * Amy feedback * Update docs/advanced-features/middleware.md Co-authored-by: Amy Burns <amy.burns@vercel.com> * first commit * more fixes * re-structuring based on feedback * changes to middleware.md * updates to edge-api-routes * code typo * Update docs/advanced-features/middleware.md Co-authored-by: JJ Kasper <jj@jjsweb.site> * Update edge-api-routes.md * Update Edge Runtime API docs * Clarify API docs * Update * Update docs/advanced-features/middleware.md * Update switchable runtime docs * Update response * experimental-edge * Update docs/advanced-features/middleware.md * Add example of forwarding headers and address comments * Add proxying headers to middleware upgrade guide * Apply suggestions from code review Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * fix middleware directory spec * localization explanation * update detecting runtime * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Balázs Orbán <info@balazsorban.com> * fix prettier issues * table fix * Update docs/advanced-features/react-18/switchable-runtime.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * Update docs/api-routes/edge-api-routes.md Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> * lint-fix Co-authored-by: molebox <hello@richardhaines.dev> Co-authored-by: Amy Burns <amy.burns@vercel.com> Co-authored-by: Ismael Rumzan <ismael.rumzan@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Balázs Orbán <info@balazsorban.com> Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com> Co-authored-by: Ismael <ismael@vercel.com>
2022-06-28 17:22:48 +02:00
<div class="card">
<a href="/docs/api-routes/edge-api-routes.md">
<b>Edge API Routes</b>
<small>Build high performance APIs in Next.js. </small>
</a>
</div>