As mentioned in the new-added error messages, and the [linked
resources](https://react.dev/reference/react/use-server#:~:text=Because%20the%20underlying%20network%20calls%20are%20always%20asynchronous%2C%20%27use%20server%27%20can%20only%20be%20used%20on%20async%20functions.):
> Because the underlying network calls are always asynchronous, 'use
server' can only be used on async functions.
> https://react.dev/reference/react/use-server
It's a requirement that only async functions are allowed to be exported
and annotated with `'use server'`. Currently, we already have compiler
check so this will already error:
```js
'use server'
export function foo () {} // missing async
```
However, since exported values can be very dynamic the compiler can't
catch all mistakes like that. We also have a runtime check for all
exports in a `'use server'` function, but it only covers `typeof value
=== 'function'`.
This PR adds a stricter check for "use server" annotated values to also
make sure they're async functions (`value.constructor.name ===
'AsyncFunction'`).
That said, there are still cases like synchronously returning a promise
to make a function "async", but it's still very different by definition.
For example:
```js
const f = async () => { throw 1; return 1 }
const g = () => { throw 1; return Promise.resolve(1) }
```
Where `g()` can be synchronously caught (`try { g() } catch {}`) but
`f()` can't even if they have the same types. If we allow `g` to be a
Server Action, this behavior is no longer always true but depending on
where it's called (server or client).
Closes#62727.
### What?
An unactionable error is thrown when `headers()`, `cookies()` or other
Dynamic API functions are called outside the render/request context.
This PR clarifies what the user can do to fix the problem.
### Why?
The current error is hard to understand
> Error: Invariant: `cookies` expects to have requestAsyncStorage, none
available.
### How?
I am adding a dedicated error page and rephrasing the error message.
Closes NEXT-2509
### 🧐 What's in there?
`config.analyticsId` is a rarely-used mechanism, initially intended to
Next.js users hosting their application themselves and willing to report
Core Web Vitals to Vercel Speed Insights.
This platform specific mechanism can be replaced with the built-in
[`useReportWebVitals`](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals).
### 🧪 How to test?
1. make a new Next.js app
1. define env variable `VERCEL_ANALYTICS_ID` to a dummy value
1. start your application in dev mode:
```shell
⚠ config.analyticsId is deprecated and will be removed in next major
version. Read more:
https://nextjs.org/docs/messages/deprecated-analyticsid
▲ Next.js 14.0.5-canary.58
- Local: http://localhost:3000
✓ Ready in 917ms
```
1. build your application:
```shell
▲ Next.js 14.0.5-canary.58
Creating an optimized production build ...
✓ Compiled successfully
Linting and checking validity of types .
⚠ The Next.js plugin was not detected in your ESLint configuration. See
https://nextjs.org/docs/basic-features/eslint#migrating-existing-config
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (4/4)
⚠ `config.analyticsId` is deprecated and will be removed in next major
version. Read more:
https://nextjs.org/docs/messages/deprecated-analyticsid
```
1. remove the env variable, add a `next.config.js` file with a dummy
`analyticsId` variable:
```js
module.exports = { analyticsId: "UA-12345678-9" };
```
1. start your application in dev mode: it'll issue the same warning.
1. build your application: it'll issue the same warning.
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
`experimental.missingSuspenseWithCSRBailout` should be enabled by
default to help users to disciver unwrapped suspense boundaries.
Add more notes in the error doc about deprecation and temporary
workaround to disable it.
Closes NEXT-2157
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
This reapplies the `experimental.missingSuspenseWithCSRBailout` option
to bail out during build if there was a missing suspense boundary when
using something that bails out to client side rendering (like
`useSearchParams()`). See #57642
Closes [NEXT-1770](https://linear.app/vercel/issue/NEXT-1770)
This PR introduces 2 experimental options for doing more work in the
webpack build in parallel instead of in serial. These options may
improve the performance of builds at the cost of more memory.
`parallelServerAndEdgeCompiles`: This option kicks off the builds for
both `server` and `edge-server` at the same time instead of waiting for
each to complete before the next one. In applications that have many
server and edge functions, this can increase performance by doing that
work in parallel. This can be used with `next build` or `next
experimental-compile`.
`parallelServerBuildTraces`: This option starts the server build traces
as soon as the server compile completes and runs it in the background
while the other compilations are happening. With this option enabled,
some unnecessary work may be done since ordinarily the client
compilation provides information that can reduce the amount of tracing
necessary. However, since it is in parallel with the other work, it may
still result in a faster build in total at the cost of more memory. This
option is already the default when using `next experimental-compile` but
can now be used when `next build` is used also.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
### What?
This PR adds a new flag called
`experimental.missingSuspenseWithCSRBailout`.
### Why?
Via this PR we can break a build when calling `useSearchParams` without
wrapping it in a suspense boundary.
If no suspense boundaries are present, Next.js must avoid doing SSR and
defer the entire page's rendering to the client. This is not a great
default. Instead, we will now break the build so that you are forced to
add a boundary.
### How?
Add an experimental flag. If a `BailoutToCSRError` error is thrown and
this flag is enabled, the build should fail and log an error, instead of
showing a warning and bail the entire page to client-side rendering.
Closes NEXT-1770
---------
Co-authored-by: Balázs Orbán <info@balazsorban.com>
Co-authored-by: Wyatt Johnson <accounts+github@wyattjoh.ca>
Based on feedback from https://github.com/vercel/next.js/issues/47793, I
made some improvements around the geolocation docs. Specifically around
`request.ip`, `request.geo`, and how to access these values. I noticed
there was a bit of a divergence, as some of the `NextRequest` and
`NextResponse` docs were split out for the App Router section, but not
all.
This PR finishes that swing by removing the previous catch-all for
`next/server` in the Pages Router docs and splits them into individual
docs pages.
Wrote a lil' thread about this:
https://twitter.com/leeerob/status/1736543599339172121
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
The "postpone" terminology is internal to React and can be used for more
things than just this. It's also a mechanism we may or may not rely on.
---------
Co-authored-by: Zack Tanner <zacktanner@gmail.com>
Fixes a broken link, shortens the title, and adds another possible way
to resolve the error.
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
When postpone is caught by user code, this will cause PPR not to properly prerender the static parts and thus we need to fail the build. This also adds some messaging about how to fix the error.
Prior to this change, catching code that would normally trigger `postpone ` would silently fail, but the build outputs would be incorrect as there's no postpone data available.
Relands #57477 with additional tests & fixes
This PR enables the `experimental.webpackBuildWorker` to be on by
default. This flag enables logic inside Next.js to run the compilation
in an isolated worker. The reason for this is that the webpack
compilation process retains a lot of memory for the whole duration of
the build process because it uses some packages that leak. We don't need
it for the rest of the process so it's best to use it in a worker and
leave the memory to be used for static generation.
This will improve memory usage during build, avoiding OOMs caused by
webpack exceeding memory.
<!-- 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
### Adding or Updating Examples
- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
### 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: JJ Kasper <jj@jjsweb.site>
when calls to `maybePostpone` throw but there's no postpone state, we want to handle those errors differently so that we can provide clearer messaging around how to prevent them, while still retaining any errors that were re-thrown by the user.
ex:
We already had `domains` as "not recommended" but this PR marks it as "deprecated" and prints a warning if its detected.
I also updated all examples to switch from `domains` to `remotePatterns`.
### What?
Moving maintenance to a separate repository.
### Why?
I want to make these actions reusable in other projects as they seem to work well in the Next.js repository.
### How?
The code is moved to https://github.com/balazsorban44/nissuer
I tested it on my fork, and all the following functionality is preserved: https://github.com/balazsorban44/next.js/issues/56
- [x] Close/lock/comment without a valid reproduction link
- [x] Minimize "+1"
- [x] Add labels based on user selection
- [x] Add comment based on the maintainer's label (eg.: "please add a complete reproduction")
There's been some confusion on the correct way to add a `nonce`, so took the opportunity here to:
- Add a new docs page for Content Security Policy
- Explained how to generate a `nonce` with Middleware
- Showed how to consume the `nonce` in a route with `headers`
- Updated the `with-strict-csp` example
- Update the `nonce` error message page
- Backlinked to the new page in a few places in the docs
We initially wrote the [React
page](https://nextjs.org/docs/getting-started/react-essentials) to
introduce Server Components in the App Router, but over time, some
implementation details have changed, and the information has become
stale. The React team is working on adding new docs, so I'd like to
change the narrative on the Next.js docs from "client vs. server
components" to "writing code for the server and for the client" - and
link back to the React documentation when it becomes available.
As React developers, we're very familiar with writing code for the
client, it's nice and simple. But doing so comes at the expense of not
being familiar with the server. The aim of these docs is to help
developers become proficient in both the client and server environments.
I'd like to take it back to the foundations, and not use abstractions
like SSG and CSR, MPAs or SPAs, as those terms come with their own set
of assumptions that make it harder to understand how RSC works. Instead,
we'll focus on the request lifecycle, show how application code flows
from the server to the client, and discuss the trade-offs of doing
operations in each environment.
- [x] Page: Rendering Fundamentals
- [x] Environments: Client and Server
- [x] Request-response lifecycle
- [x] Network Boundary
- [x] Page: Server Components
- [x] Benefits and use cases of server rendering
- [x] How to use Server Components in Next.js
- [x] How Server Components are rendered
- [x] Static Rendering
- [x] Dynamic Rendering
- [x] Streaming
- [x] Page: Client Components
- [x] Benefits and use cases of client rendering
- [x] How to use Client Components in Next.js
- [x] How Client Components are rendered
- [x] Initial vs. Subsquent navigation
- [x] Page: Composition Patterns
- [x] When to use client and server components
- [x] Server Component Patterns
- [x] Client Component Patterns
- [x] Interleaving Client and Server Components
- [ ] ~Diagrams~ will follow up with new PR.
- [x] Set up redirects: https://github.com/vercel/front/pull/24917
---------
Co-authored-by: Térence Hollander <hollanderterence@gmail.com>
Co-authored-by: shawnthwei <32075290+shawnthwei@users.noreply.github.com>
Co-authored-by: Michael Novotny <manovotny@gmail.com>
Partial fix for #54012: do not generate a blur image in the image loader when the image is detected to be animated, rather than returning the *entire* animated image as the blur image.
## For Contributors
### Improving Documentation
- [x] Run `pnpm prettier-fix` to fix formatting issues before opening the PR.
- [x] Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide
### What?
Add instructions for using `bun/bunx` where relevant. I only added mentions where npm/yarn/pnpm were all already listed.
### Why
Bun can be used as a runtime-agnostic [package manager](https://bun.sh/package-manager) and script runner in any project with a `package.json`.
(Sorry, I probably should have consolidated this with https://github.com/vercel/next.js/pull/53467)
Co-authored-by: Steven <229881+styfle@users.noreply.github.com>
When using imports from `next/headers` in a layout or page,
`StaticGenerationBailout` will throw an error to indicate Next.js should
fallback to dynamic rendering. However, when async context is lost, this
error is uncaught and leads to a confusing error message at build time.
This attempts to improve DX surrounding this error by linking out to a
page that explains when it might happen. I've also tweaked
`StaticGenerationBailout` to always throw a fully descriptive reason as
opposed to just `DynamicServerError: Dynamic server usage: cookies`
Closes NEXT-1181
Fixes#49373
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
This PR document the caching semantics in Next.js, how they interact, and what APIs affect them. We're also taking the opportunity to consolidate terminology, remove duplicate content, and update sections of the docs that relate to caching.
### Documentation
- [x] Create a new section for caching
- [x] Explain how the different caching mechanisms work
- [x] Request Memoization (React Cache)
- [x] Persistent Data Cache
- [x] Persistent Full Route Cache
- [x] In-memory, client-side Router Cache
- [x] Document how different APIs affect caching
- [x] Document cache interactions
- [x] Clean up stale information in the other docs sections
- [x] Routing Section
- [x] Move advanced navigation topics from fundamentals to **How Navigation Works** section
- [x] Rewrite the **How Navigation Works** section
- [x] Rendering Section
- [x] Simplify fundamentals page
- [x] Rewrite the **Static and Dynamic Rendering** pages
- [ ] ~Create a page to explain how **Client and Server Components** are rendered~. Moved to this PR: https://github.com/vercel/next.js/pull/51579
- [x] Data fetching section
- [x] Consolidate data fetching story for fetching, caching, and revalidating
- [x] Clarify data fetching story with 3rd party libraries and React `cache`
- [x] Create **Data Fetching Patterns** page
- [x] Document other related behaviors:
- [x] Update information on scroll position for back/forward navigation
- [x] Remove the concepts of **soft and hard navigation**
- [x] Remove the concepts of **static and dynamic data fetching**
- [x] Use consistent terminology **runtime** 👉🏼 **request time**. Runtime for Edge and Node.js, request time to describe when dynamic stuff happens
- [x] `generateStaticParams` being able to seed the Full Route Cache
- [x] Polish 💅🏼
---
### Related PRs:
- Diagrams: https://github.com/vercel/front/pull/24142
- Redirects: https://github.com/vercel/front/pull/24179
Peter Briggs