We took a look at unique Next.js projects that have one or more requests
for a specific image size and here are the findings as seen from the
Image Optimization API:
- `w=16` 4.2%
- `w=32` 17.1%
- `w=48` 21.4%
- `w=64` 22.6%
- `w=96` 25.8%
- `w=128` 29.5%
- `w=256` 46.5%
- `w=384` 35.1%
- `w=640` 57.2%
Only 4.2% of Next.js projects ever made a request to a 16px width image.
This is low enough to remove from the default configuration so that all
other projects can benefit from reduced html
[srcset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset)
and fewer variations exposed from the backend API.
You might think that this means few developers are using `<Image
width={16} />` but it probably means that most displays nowadays use
devicePixelRatio 2 meaning that specifying a 16px image width will
actually fetch the 32px width to ensure it won't looking blurry on your
retina display.
BREAKING CHANGE: this is technically a breaking change but it won't
cause apps to stop working, its just 4% of them may have some requests
serve a 32px image instead of 16px. Those apps can of course opt in by
changing their `images.imageSizes` config back to allowing 16.
### What?
This PR removes the automatic ESLint linting that previously ran during `next build`. The documentation has been updated to reflect this change.
### Why?
As part of Next.js 16, we're removing the automatic build-time linting that was previously included in the build process. This gives developers more control over when linting runs by explicitly invoking their linter via npm scripts.
### How?
- Updated documentation to clarify that automatic build-time linting has been removed in Next.js 16
- Removed the `runLint` parameter and related linting code from the build process
- Removed the `verifyAndLint.ts` file which is no longer needed
- Simplified type checking code by removing lint-related functionality
- Removed ESLint telemetry during builds
### What?
- Adding a small note to clarify the meaning of the phrase "project
root" in the documentation for next.config output, specifically in
regards to a monorepo setup
### Why?
- While doing some debugging related to a container that I cannot build
locally for compliance reasons, I had to take shots in the dark to
figure this behavior out 😄 hoping it can help the next soul who finds
themselves in a similar predicament
### How?
- Explain that in monorepos, "project root" does not mean the root of
the monorepo, but instead the root of the nextjs app
First time contributing, so I appreciate any reviews/feedback I can get
here, even for such a small PR. Thanks!
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
This doc is mainly to provide the users with information on how to opt
out of this feature. We could later remove these docs and the option
when the need to opt out is low.
---------
Co-authored-by: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
`next/legacy/image` was introduced in Next.js 13 as way to allow
developers to upgrade from 12 to 13 with minimal effort.
Now that its been 3 years, its time to deprecate `next/legacy/image` in
Next.js 16 so we can remove it in a future version.
This will print a warning the first time the component is used.
This was docs deprecated in Next.js 14 so we should begin warning in
Next.js 16 when `images.domains` config is used.
This will guide users to providing a strict `images.remotePatterns`
config ensuring only expected images can be optimized.
Add missing space before "Importing Client Components" in Lazy Loading
/app docs.
This fixes the missing link in "On this page" sidebar:
<img width="1092" height="446" alt="image"
src="https://github.com/user-attachments/assets/0981467d-ad61-494d-80b2-c0a0e323dd0b"
/>
In the current state, the first link is "Skipping SSR" (second link)
instead of "Importing Client Components"
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Use the current result of `baseline widely available` as the default
browsers.
If we used `baseline widely available` literally, then that would change
the targets even within minor versions.
PR title - docs: polish Project Structure page (grammar, consistency,
clarity)
PR description -
1) Fixes an Oxford comma in the routing files description for
consistency.
2) Normalizes heading capitalization to sentence case.
3) Corrects “Files conventions” → “File conventions”.
4) Aligns not-found.js description with earlier table (it’s not an error
boundary). Clarifies intercepting routes microcopy.
<!-- 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>
### What?
Move persistent caching for `next build` into a separate config option: `turbopackPersistentCachingForBuild`.
And `next dev` to `turbopackPersistentCachingForDev`.
### What?
Improves the contribution guide (`01-contribution-guide.mdx`) by fixing
a typo and clarifying wording for JavaScript files with JSX code.
### Why?
This is my first time ontributing to open source, i've taken my time to
read the contribution guide and noticed this small inconsisntency. My
motivation was to start small by fixing this issue and make a
contribution, with the intention of following up with greater
improvements later. This change also helps make the documentation
clearer for new contributors and keeps it aligned with the Next.js style
guide.
### How?
**Before:**
> - Make sure to use `js` extension with JSX code at JavaScript files.
**After:**
> - Make sure to use `.js` extension for JavaScript files with **JSX**
code.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
https://github.com/vercel/next.js/pull/77850 moved `experimental.turbo`
option to `turbopack`, but `moduleIds` is intended for debugging, in
line with `turbopackSourceMaps` and `turbopackMinify`, so move to
`experimental.turbopackModuleIds`.
- In development, it's "named" by default, and making it "deterministic"
breaks HMR.
- In production, it's "deterministic" by default, and making it "named"
blows up bundle sizes and exposes your internal project structure in the
module ID strings.
We have found many Next.js users are confused why images keep
revalidating so frequently (increasing cpu and cost).
The reason is usually that their upstream source images are missing the
`cache-control` header and thus fallback to the 60 second revalidation
default. This its not a great default since most images don't change
frequently.
This PR is a breaking change to bump the `images.minimumCacheTTL` config
from 60 (1 min) to 14400 (4 hours).
Why 4 hours? Because its long enough to take advantage of the durable
cache, but short enough that changing or deleting the upstream src image
will take effect on the same day.
For advanced use cases where images are changing frequently, developers
can change this behavior back by reducing `images.minimumCacheTTL` to a
lower value.
## Documentation Update
This PR improves the dynamic routes example in the
`project-structure.mdx` page.
### Changes
- Updated catch-all segments example:
- Before: `/shop/clothing/shoes`
- After: `/shop/clothing`
- Adjusted follow-up examples for consistency:
- `/shop/a`, `/shop/a/b` → `/shop/clothing`, `/shop/clothing/shirts`
### Why
- Provides a clearer and more intuitive demonstration of how catch-all
segments work.
- Keeps the example consistent with other dynamic routes documentation.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
In error messages and in docs for `'use cache'` and related APIs, we now
guide users to the `experimental.cacheComponents` config instead of
`experimental.useCache`.
closes NAR-410
This option was renamed/stabilized from `experimental.turbo` to `turbopack` in 15.3.
The app router page title/path was correct, but pages router had the wrong thing.
Let me know if I should add a redirect for this somewhere?
Follow up to https://github.com/vercel/next.js/pull/83246#discussion_r2366553689
Discussed this with @lukesandberg and we can't find a place where it would be very useful, it seems it might've been useful with the old builtin condition syntax (which I removed).
It also looks like maybe I forgot to actually wire this up to anything? Whoops. Whelp, now it's gone.
~I'm looking for review/feedback, but **DO NOT MERGE UNTIL NEXT 16.0 IS RELEASED.** These APIs are not available on 15.5, and merging it now would be confusing to users. If you want to try it out, use a recent canary release.~ I've been informed that docs are not currently tracking canary, so this is safe to merge.
Documented the new configuration syntax added in https://github.com/vercel/next.js/pull/82857 that should ship with Next 16.0.
## Rendered
<details>
<summary>Toggle</summary>
<img src="https://app.graphite.dev/user-attachments/assets/b2404001-6e3f-47c9-9704-160fcfb1438d.png" width=1000>
</details>
Without the `| null`, the following error appears during compilation:
```
TS2322: Type RefObject<HTMLDivElement | null> is not assignable to type RefObject<HTMLDivElement>
Type HTMLDivElement | null is not assignable to type HTMLDivElement
Type null is not assignable to type HTMLDivElement
```
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
- Added a Note to the Middleware docs explaining that when
`pageExtensions` are customized (e.g. `.page.ts`), the Middleware file
should be named `middleware.page.ts` or `middleware.page.js`.
- Updated wording so `middleware.ts/js` is described as the default
filename, not a strict requirement.
<!-- 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?
-Added a callout note to middleware.mdx stating that if pageExtensions
is customized (e.g., .page.ts), the Middleware file should also match
(middleware.page.ts/js).
-Updated the language from “must” → “default is” for filename clarity.
### Why?
-Developers customizing pageExtensions were misled by the existing docs,
which implied middleware.ts/js was always required.
-This PR prevents confusion when Middleware isn’t recognized after a
pageExtensions change.
### How?
Edited docs/app/api-reference/file-conventions/middleware.mdx.
Inserted a > **Note** block right after the paragraph explaining where
to create the middleware file.
Closes NEXT-
Fixes#84008
-->
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
We have dropped the example linked in this page. I'll re-evaluate later
if the section is still enough for a dev to understand how to set CORS
related headers.
### What?
This PR fixes a missing comma in the function parameter in
`03-api-reference/03-file-conventions/layout.mdx`.
The comma between `children` and `params` parameters was missing in the
documentation example, showing incorrect syntax.
### Why?
The missing comma in the documentation example shows invalid
JavaScript/TypeScript syntax.
### How?
- Added missing comma after `children` parameter .
**Before:**
```tsx filename="app/dashboard/[team]/layout.tsx" switcher
export default async function Layout({
children
params,
}: {
```
**After:**
```tsx filename="app/dashboard/[team]/layout.tsx" switcher
export default async function Layout({
children,
params,
}: {
children: React.ReactNode
```
This PR adds docs for using Node.js native TS resolver for
`next.config.ts`. It states:
- Supports Node.js native TS resolver
- Why use it
- How to use it
- Restrictions
- Why use `next.config.mts`
I didn't mention how much it's faster compared to the legacy resolver
(~68% faster in the hello world app -
[link](https://github.com/vercel/next.js/pull/83240)) because the
experience may vary for users.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Abdón Rodríguez <a@abdonrd.com>
Steven
