## What
Fixes the CSP documentation "Without Nonces" example to only include
`'unsafe-eval'` in development mode.
## Why
The example was showing `'unsafe-eval'` without a development check,
which would cause it to be shipped to production. This is inconsistent
with the guidance in the "Development vs Production Considerations"
section which correctly shows how to conditionally add `'unsafe-eval'`
only in development.
## How
Added a `isDev` check using `process.env.NODE_ENV === 'development'` and
conditionally includes `'unsafe-eval'` in the `script-src` directive
only when in development mode.
When self-hosting Next.js, it's possible to customize a cache handler
for ISR. Self-hosted Next.js also makes use of a similar cache interface
for `next/image`, but there's no way to customize this cache handler.
This plugs into the [existing
ability](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath)
to customize a `cacheHandler` to support the `IMAGE` type. This lets you
implement whatever constraints you might have on your self-hosted
environment, eg the need for an LRU cache, or storing optimized images
outside of disk.
This is currently opt-in because it's a breaking change for cache
handlers to start receiving `IMAGE` cache types, which we'll make
default in the next major.
## What
Adds a `--experimental-cpu-prof` flag to `next dev`, `next build`, and
`next start` commands to capture V8 CPU profiles for debugging
performance bottlenecks.
## Why
When investigating slow builds, slow dev server startups, or production
server performance issues, having access to CPU profiles is invaluable.
This provides a first-party way to capture these profiles without
needing to manually set up the V8 inspector.
## How
- Adds `--experimental-cpu-prof` flag to CLI commands
- Uses V8's built-in CPU profiler via Node.js inspector module
- Profiles are saved to `.next/cpu-profiles/` with descriptive filenames
- Profiles are saved on process exit (Ctrl+C, SIGTERM, or normal exit)
### Profile files generated
**`next dev`:**
- `dev-main-*` - Parent process (dev server orchestration)
- `dev-server-*` - Child server process (request handling and rendering)
**`next build` (Turbopack):**
- `build-main-*` - Main build orchestration process
- `build-turbopack-*` - Turbopack compilation worker
**`next build` (Webpack):**
- `build-main-*` - Main build orchestration process
- `build-webpack-client-*` - Client bundle compilation worker
- `build-webpack-server-*` - Server bundle compilation worker
- `build-webpack-edge-server-*` - Edge runtime compilation worker
**`next start`:**
- `start-main-*` - Production server process
## Changes addressing PR review comments
- Removed signal handlers from `cpu-profile.ts` to prevent conflicts
with CLI cleanup logic (telemetry, traces, etc.)
- Added synchronous exit handler for non-signal process exits (errors,
`process.exit()` calls)
- CLI commands now explicitly call `saveCpuProfile()` as part of their
cleanup before exiting
- Replaced raw ANSI escape codes with `picocolors` library
- Added comprehensive documentation about profile file naming for each
command
- Added build profiling test that verifies correct profile generation
for both Turbopack and Webpack modes
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
## What?
Improves the error shown when `generateMetadata` or `metadata` is
exported from a Client Component.
Also updated the documentation to further explain why it can only be
used in a server component and the steps to follow to resolve the error.
This PR adds instructions on how to run and navigate the new turbopack
bundle analyzer to the existing [Optimizing package bundling guide
](https://nextjs.org/docs/app/guides/package-bundling).
Todo:
- [x] Embed video
- [x] Add image for import chain
---------
Co-authored-by: Luke Sandberg <lukesandberg@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Rich Haines <hello@richardhaines.dev>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
This PR updates the custom server documentation to remove usage of
Node's
deprecated `url.parse()` API. The example does not require URL parsing,
since
the `parsedUrl` argument is optional for the Next.js `RequestHandler`.
Removing `url.parse()` avoids Node deprecation warnings (DEP0116,
DEP0169) and
keeps the example aligned with current best practices.
### What changed?
- Removed the `url.parse()` import and usage.
- Removed unused `parsedUrl` variable.
- Updated both TS and JS examples to use `handle(req, res)` directly.
### Why?
- `url.parse()` is deprecated in modern Node versions.
- The example works without URL parsing.
- Simplifies the docs and matches recommended APIs.
Fixes#86951 and https://github.com/vercel/next.js/issues/83183
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
I think overall it's not appropriate to add Vercel-specific caveats to
these guides because they make it look like they're upselling Vercel.
I've edited to emphasize the self-hosting condition instead, from which
one should be able to infer it doesn't apply to Vercel.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Corrects a grammatical error in the data preloading explanation. The
phrase "an utility function" was updated to "a utility function" because
"utility" begins with a consonant sound. This improves clarity and
maintains consistency with standard English usage throughout the
documentation.
### What?
[ZenStack](https://github.com/zenstackhq/zenstack) is a toolkit built
above Prisma ORM for adding access control and other features. This
change adds one of its packages "@zenstackhq/runtime" to the default
list of "serverComponentsExternalPackages".
### Why?
The package is frequently used in Next.js route handlers and results in
false-positive errors with Next.js's bundler (likely caused by
dynamically `require` modules).
### How?
Add the package to the default external packages list.
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
### What?
Adds `@alinea/generated` to the external package list
### Why?
[`Alinea`](https://github.com/alineacms/alinea) generates this package
at build time and it should not end up in a cache (much like the
`@prisma/client` package)
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
Fixes grammar error in cache components doc
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## Title
docs: add example for enabling both AVIF and WebP image formats
## Description
### What?
This PR enhances the image component documentation by adding examples
showing how to enable both AVIF and WebP image formats together in
`next.config.js`. It also updates the `image-component` example to
demonstrate this configuration.
### Why?
Currently, the documentation only shows examples for:
- WebP only (default): `formats: ['image/webp']`
- AVIF only: `formats: ['image/avif']`
However, many developers want to enable both formats together to:
- Prefer AVIF for browsers that support it (better compression, ~20%
smaller files)
- Fall back to WebP for broader browser compatibility
- Maximize image optimization across different browsers
This configuration is a best practice but wasn't clearly documented with
an example.
### How?
- Added example configuration `formats: ['image/avif', 'image/webp']` to
App Router image component documentation
- Added the same example to Pages Router (legacy) image component
documentation for consistency
- Updated `examples/image-component/next.config.js` to demonstrate the
configuration
- Added clarification that the order matters - Next.js uses the first
format in the array that the browser supports
### Changes Made
- `docs/01-app/03-api-reference/02-components/image.mdx` - Added AVIF +
WebP example
- `docs/02-pages/04-api-reference/01-components/image-legacy.mdx` -
Added AVIF + WebP example
- `examples/image-component/next.config.js` - Added formats
configuration
### Testing
- [x] Documentation changes only - no code changes
- [x] Verified examples are syntactically correct
- [x] Checked that formatting follows Next.js documentation guidelines
### Checklist
- [x] Run `pnpm prettier-fix` to fix formatting issues (if applicable)
- [x] Documentation follows the docs guidelines
- [x] Changes are clear and helpful for developers
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
This PR fixes the docs' example where it used class (like cacheHandler
(no s)), but cacheHandlers expect an object.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Changed better match example images and to be consistent within
documentation copy.
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Remove redundant example code for overriding cache profiles.
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR. ✅ (no changes)
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide✅
### What?
Remove a redundant example in the `cacheLife` docs.
### Why?
Because the redundant example is confusing.
### How?
Closes NEXT-
Fixes #
-->
delete is reserved word
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Tim Neutkens
