On the Building Your Application: Authentication page, the formatting is
broken in the "Setting Up Middleware" section because the unordered list
is nested inside the ordered list. This is causing the unordered list
components to be numbered and throw off the ordering of the top level
list.
I made a tiny change to the markdown to make the top level steps h4
titles, and un-nested the unordered list's
Closes NEXT-61838
Fixes#61838
Co-authored-by: Sam Ko <sam@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
### 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?
Make a note about the new `$ACTION_` properties in the `formData`
### Why?
Since `next@14.1.3`, some new `$ACTION_` properties have appeared in
the`formData`, which cause validation errors when used with a strict
validation with a library such as Zod or Yup:
```tsx
// Form Client Component
export default function Form() {
const [state, formAction] = useFormState(action, {
type: 'initial',
});
return (
<form action={action}>
{/* ... */}
</form>
);
}
// Server Action
export async function action(
prevState: ServerActionReturnValue,
formData: FormData,
): Promise<ServerActionReturnValue> {
const validationResult = await schema.validate(
Object.fromEntries(formData.entries()),
);
```
The errors from Yup:
```
Errors:
- this field has unspecified keys: $ACTION_REF_1, $ACTION_1:0, $ACTION_1:1, $ACTION_KEY
```
The data in the `formData.entries()`
```js
{
'$ACTION_REF_1': '',
'$ACTION_1:0': '{"id":"59f475b...","bound":"$@1"}',
'$ACTION_1:1': '[{"type":"initial"}]',
'$ACTION_KEY': 'k187677481',
// Real form data starts here:
year: '2024',
```
### How?
Document additional properties with keys starting with the prefix
`$ACTION_`
### Alternatives Considered
Maybe these `$ACTION_` properties are not intended to be exposed to
users, and should be stripped before the `formData` reaches the Server
Action.
### Related
The documentation was originally introduced in commit
[`687239c`](687239ce76),
which was a part of this PR:
- https://github.com/vercel/next.js/pull/59080
cc @delbaoliveira
---------
Co-authored-by: Sam Ko <sam@vercel.com>
### What?
Bringing Turbopack for Next.js documentation from `turbo.build` to
`nextjs.org/docs`.
> Note: After this PR lands, there will be a subsequent PR to
`vercel/turbo` to remove these docs from `turbo.build` and redirect
here.
### Why?
Previously, this documentation was on `turbo.build`. This was confusing
because these docs weren't specific to Next.js. Rather, they are for
Next.js developers who want to configure their bundler (which happens to
be Turbopack under the hood).
We had seen a number of times that folks were unable to find loader and
configuration support for the their Next.js + Turbopack applications so
this PR should help surface that information better where folks are
looking for it.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Payload is moving to ESM, and we need to be removed from the default
list of `serverComponentsExternalPackages`.
This PR simply removes Payload from the default list. Developers can add
it back in if they are using older versions of Payload.
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
## Changes
- We need to document how that we retry until a port is found when we're
not specifying a port via the CLI (`--port`) or the `PORT` environment
variable. For example, if `3000` and `3001` are used, we will check
`3000`, `3001`, and then land on `3002`.
Closes NEXT-2731
Small update to mention TS paths when changing to src/ directory as it
is something most users will need to do.
Co-authored-by: Sam Ko <sam@vercel.com>
## Description
It made sense to improve our <picture data-single-emoji=":nextjs:"
title=":nextjs:"><img class="emoji" width="20" height="auto"
src="https://emoji.slack-edge.com/T0CAQ00TU/nextjs/2a85d633ae594556.png"
alt=":nextjs:" align="absmiddle"></picture> CLI docs after refactoring
the CLI!
## Important Changes
- Removes mention of `next export`, which was moved to `next.config.js`
- Adds mention of `--turbo`
- Adds all the expected help outputs
## Related
- https://github.com/vercel/next.js/pull/61877
- Fixes https://github.com/vercel/next.js/issues/59226
Closes NEXT-2545
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Michael Novotny <manovotny@gmail.com>
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Clarifies what passing false or undefined to the revalidate property
option of unstable_cache does.
Context: I didn't want my DB query to be cached at all, but I did use
this API because I wanted to refresh a component's data after submitting
a server action. I thought I had to pass 0, or false to get it to not
cache at all.
Co-authored-by: Sam Ko <sam@vercel.com>
Closes#62653
Finishes the job started by https://github.com/vercel/next.js/pull/58196
and updates the last remaining code example that uses `reportWebVitals`
to use `useReportWebVitals`
Co-authored-by: Sam Ko <sam@vercel.com>
Linked react docs explicitly advise not to use low-entropy values such
as phone numbers with the taintUniqueValue API.
https://react.dev/reference/react/experimental_taintUniqueValue#caveats
> Do not use taintUniqueValue to protect low-entropy values such as PIN
codes or phone numbers. If any value in a request is controlled by an
attacker, they could infer which value is tainted by enumerating all
possible values of the secret.
PS Sorry for the tiny change but this threw me off when I read it.
### What?
If the user is logged in and on the dashboard, no need to redirect.
### Why?
#62547
### How?
We still want to redirect to the dashboard from other routes, if the
user is logged in already.
Fixes#62547, also related #62548
Closes NEXT-2619
Within the document
[docs/02-app/02-api-reference/01-components/link.mdx](https://github.com/zhuyedev/next.js/blob/canary/docs/02-app/02-api-reference/01-components/link.mdx#L327),
there is an unnecessary set of `<PagesOnly>` tags, which prevents a few
sections from being displayed correctly.This issue particularly affects
the section starting with "### If the child is a custom component that
wraps an <a> tag" (in line 327) and ending just before "### Middleware"
(in line 458).
Co-authored-by: Sam Ko <sam@vercel.com>
### What?
I found a small typo in the docs.(analytics.mdx)
Missing ")" in the end of function.
### How?
Add ")" in the end.
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
### What?
When the next config has no default export, it does not inform the user
correctly, but as:
```ts
// next.config.mjs
/** @type {import('next').NextConfig} */
export const config = {
// ...
}
```
```sh
⚠ Invalid next.config.mjs options detected:
⚠ Unrecognized key(s) in object: 'config'
⚠ See more info here: https://nextjs.org/docs/messages/invalid-next-config
```
### Why?
The options within the named exported config may be inactivated without
notice.
### How?
Since we use dynamic import for the config, check if `userConfigModule`
has a `default` export, and if not, throw an error.
Also, added to the docs to address by text that the config needs a
default export.
### What?
Added a `_currentState` argument to the `authenticate` function in the
'Building Your Application' authentication documentation.
### Why?
The `useFormState` hook's first argument is a function that requires two
arguments. This adjustment ensures the `authenticate` function aligns
with the expected structure used by `useFormState`. For more details,
refer to the React documentation: [useFormState
Hook](https://react.dev/reference/react-dom/hooks/useFormState).
The current link just takes you to the definition of serialization on
MDN. I'm proposing this should link to the React docs and what they are
able to serialize because it is way more than JSON.
Changing from "components" to "_components" folder name here
"app/components/web-vitals.tsx", to be the same as previous example on
the page "app/_components/web-vitals.tsx".
Co-authored-by: Steven <steven@ceriously.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
### 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 #
-->
Hello, I noticed the following code in `link.tsx`.
```
//client/link.tsx
...
onMouseEnter(e) {
...
if (
(!prefetchEnabled || process.env.NODE_ENV === 'development') &&
isAppRouter
) {
return
}
prefetch(
...
)
},
```
It seems that when prefetch={false} is set, prefetch still occurs on
hover for page routers.
However, there is no explanation in the <Link> documentation, which
caused misleading.
I added the explanation inside PageOnly component, could you please
review it?
<!-- 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?
This caused me a ton of issues in production due to inconsistent cache.
It does not manifest itself in local development. The only reason I
figured it out was because I upgraded to the canary release and someone
added a helpful exception explaining that I shouldn't be doing what I
was doing. To hopefully help people in the future, I'm adding a blurb to
the `unstable_cache` docs.
Co-authored-by: Sam Ko <sam@vercel.com>
Updated paths in relation to `<Link />` and middleware rewrites. Feel
free to leave suggestions if needed, this has always confused me a
little bit.
**Old Version**:
For example, if you have a Dynamic Route like `/dashboard/[user]` that
you want to present differently via middleware, you would write: `<Link
href={{ pathname: '/dashboard/authed/[user]', query: { user: username }
}} as="/dashboard/[user]">Profile</Link>`.
The `as` prop should be the URL we want to display while href/pathname
is the actual path. So if we want to present something differently via
middleware, we would do so via `as`. In the example above we want to
display `/dashboard/[user]` differently but we use
`as='/dashboard/[user]'`.
On the Examples section the name was already updated but not updated on
the Selecting Session Management in Next.js
---------
Co-authored-by: Balázs Orbán <info@balazsorban.com>
### What?
Resolves issue #61695
### Why?
The `Building Your Application -> Data Fetching -> Server Actions and
Mutations` section in the Next.js documentation has a few mismatches
with respect to JS and TS codes.
---------
Co-authored-by: battuAshita <battua@iitbhilai.ac.in>
Co-authored-by: Sam Ko <sam@vercel.com>
The docs mention using a `Link` to close the modal, but navigating away
from a slot that was active won't automatically unmount unless it
matches with a new page for that slot. This is because client-side
navigations don't switch slots from active -> default. Default is only
used on a hard navigation.
I believe this example used to be in here but got removed, so I re-added
with some extra clarity.
Closes NEXT-2405
## History
Previously, we added support for `squoosh` because it was a wasm
implementation that "just worked" on all platforms when running `next
dev` for the first time. However, it was slow so we always recommended
manually installing `sharp` for production use cases running `next
build` and `next start`.
Now that [`sharp` supports
webassembly](https://sharp.pixelplumbing.com/install#webassembly), we no
longer need to maintain `squoosh`, so it can be removed. We also don't
need to make the user install sharp manually because it can be installed
under `optionalDependencies`. I left it optional in case there was some
platform that still needed to manually install the wasm variant with
`npm install --cpu=wasm32 sharp` such as codesandbox/stackblitz (I don't
believe sharp has any fallback built in yet).
Since we can guarantee `sharp`, we can also remove `get-orientation` dep
and upgrade `image-size` dep.
I also moved an [existing `sharp`
test](https://github.com/vercel/next.js/pull/56674) into its own fixture
since it was unrelated to image optimization.
## Related Issues
- Fixes https://github.com/vercel/next.js/issues/41417
- Closes https://github.com/vercel/next.js/pull/54670
- Related https://github.com/vercel/next.js/issues/54708
- Related https://github.com/vercel/next.js/issues/44804
- Related https://github.com/vercel/next.js/issues/48820
<!-- 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 #
-->
### What?
Issue - Docs: Duplicated code snippets
The code snippet is repeated, second snippet had to be with Link
component.
### How?
Replaced button with Link component.
Fixes#61434 - Docs: Duplicated code snippets
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Sam Ko <sam@vercel.com>
## Improving Documentation
### The following changes have been made to the official repository's
**Readme.md**:
- Shortened link text across the readme.
- Added additional descriptions for more details.
- Added bold text to highlight emphasis on important topics
- Changed heading sizes to indicate first headings (h1) for each section
instead of second headings (h2) which was previously being used
- Merged _'Who is using Next.js?'_ section with _'Getting Started'_
section for a more professional, cleaner look.
### The following changes have been made to the repository's
**Contribution docs**:
- Fixed two typos in the docs
---------
Co-authored-by: Sam Ko <sam@vercel.com>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Added Kinde to the authentication documentation, Its already mentioned
elsewhere in the docs just not here.
Co-authored-by: Lee Robinson <me@leerob.io>
Since we do not optimize videos, we do not need to add the hostname to
the `next.config.js` file. This PR removes the note telling the reader
to do this.
This PR adds a new docs page under the File Conventions section for
the`middleware.ts` file. It includes:
- Explanation of `middleware.ts` usage in Next.js.
- Code examples in TypeScript and JavaScript.
- Information on `matcher` function, `NextResponse`, and middleware
runtime environment.
- Version history of middleware feature updates.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Michael Novotny <manovotny@gmail.com>
## Description
- Add a sentence for clarifying redirecting in a Server Component
- Fixes https://github.com/vercel/next.js/issues/61315
Closes NEXT-2284
---------
Co-authored-by: Zack Tanner <zacktanner@gmail.com>
### What?
This PR fixes the example test provided on [Setting up Jest with
Next.js: Creating your first
test:](https://nextjs.org/docs/app/building-your-application/testing/jest#creating-your-first-test)
not passing due to Jest not being compatible with async Server
Components.
### Why?
Although it's noted at the start of the tutorial that async Server
Components aren't currently supported by Jest, the example test failing
might confuse the reader.
### How?
This PR makes the example test pass by removing async from the `<Home>`
component
Co-authored-by: Sam Ko <sam@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
### 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 #
-->
#61159 fixed the documentation by removing incorrect information stating
that the type parameter must be set to 'page' when the path contains a
dynamic segment. This PR reflects this change in the warning message,
while confirming that the condition for the warning is already correct.
Additionally, I changed the word "affect" to "effect," assuming it was a
typo. In the documentation, I corrected myself and changed the wording
from "argument is required" to "parameter is required".
Continuing from: https://github.com/vercel/next.js/pull/60806
- [x] Update **conditional routes** example to render dashboard pages
based on user's role (rather than checking if the user is logged in)
- [x] Add **tab group** example to allow each slot to be navigated
independently.
- [x] Expand the **modal** example to show full implementation
- [x] Opening the modal
- [x] Closing the modal
- [ ] Add **catch-all** slots example
Please merge after the diagrams PR:
https://github.com/vercel/front/pull/28770
---------
Co-authored-by: Zack Tanner <zacktanner@gmail.com>
The rewrites doc was missing the `.` character when specifying which
characters were used for regex matching.
<!-- 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
-->
---------
Co-authored-by: Sam Ko <sam@vercel.com>
Hello,
This PR resolves a file extension inconsistency in the 'Setting up
Vitest with Next.js' section of the Next.js documentation
(`01-vitest.mdx`).
When using next.js with JavaScript, following the
documentation(`01-vitest.mdx`) leads to issues during testing because of
the jsx extension.
This PR corrects an example code that wrongly uses a '.js' extension for
a React component, which is against Vitest's requirement for '.jsx'
extensions.
- https://github.com/vitest-dev/vitest/issues/1564
Thank you.
Co-authored-by: Sam Ko <sam@vercel.com>
formalizes the concept of dynamic APIs inside Next to allow for varying
semantics beyond just staticGenerationBailout.
### Dynamic APIs
#### `markCurrentScopeAsDynamic`
useful to bail out of default caching semantics but does not imply a
Request specific data source was read. critically, this semantic is
ignored if you are inside a cache scope
#### `trackDynamicDataAccessed`
Must be called before reading any data source that is derived from
Request specific data. Currently this is `cookies()`, `headers()`, and
`searchParams`. This kind of data access inside a cache scope is
forbidden (it always should have been, but now it will error).
#### `trackDynamicFetch`
This one is unideal but the complexity of patch-fetch's current
implementation necessitates it for now. Essentially it will postpone if
we are prerendering. Long term this should be eliminated with a refactor
of patch fetch.
### Other Improvements
Also removes the `staticGenerationBailout` implementation as it has been
replaced with more specific logic in the places it was previously being
used.
One area that has also been enhanced is the proxy for app-route modules.
Previously we proxied the Request every time however when we are doing
non-static generation executions we generally don't want the overhead of
wrapping the request. In the refactor here I also improved the runtime
performance by using static proxy handlers and I believe I also fixed a
few bugs related to `clone` and `url`
In general there has been a bit of refactoring to clarify how we should
handle various render/execution states and a reduction in implicit side
effects for proper execution.
Another callout to notice is that app-route modules do not attempt a
static generation if they are force-dynamic regardless of the PPR
setting. Previously the PPR setting would opt them into this code path
which is not necessary because PPR itself does not work for routes, only
pages.
Closes NEXT-2099
<!-- 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?
Update the edge-and-nodejs-runtime doc with a Good to Know about a
common build error involving using packages that rely on the filesystem
in an edge runtime environment.
### Why?
The docs don't mention the issue. Most github issues, articles, and SO
answers revolve around updating the next.config with a webpack key to
ignore 'fs' imports in api routes and getServerSideProps functions. This
is incorrect when the issue is using packages that rely on 'fs',
'stream', or 'path' in an edge runtime environment. Silly mistake, but
it costs people time.
### How?
Update the docs.
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Fix: function name getStaticPaths is written in getStaticProps function,
issue exist in get-static-props.mdx under pages/api-reference/functions
folder. This issue was pushed as part of -
Pull Request: 55205
Commit Id: 80fba152f2add326a1520ffd2b530d00c75983f6
Co-authored-by: JJ Kasper <jj@jjsweb.site>
I've added a new page to the Next.js docs about optimizing videos. It
covers:
- the native video and iframe tag
- displaying externally hosted videos (i.e. from youtube)
- self hosting strategies and best practices
- Video optimization techniques
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Josh Lubawy <jlubawy@gmail.com>
Co-authored-by: Balázs Orbán <info@balazsorban.com>
I think there's some form of typographical error in the
`skipMiddlewareUrlNormalize` line under the advanced middleware flags
section of the docs.
This is the line from the docs [Source
link](https://nextjs.org/docs/app/building-your-application/routing/middleware#advanced-middleware-flags):
> `skipMiddlewareUrlNormalize` allows disabling the URL normalizing
Next.js does to make handling direct visits and client-transitions the
same. There are some advanced cases where you need full control using
the original URL which this unlocks.
Corrected to:
> `skipMiddlewareUrlNormalize` allows disabling URL normalizing in
Next.js to make handling direct visits and client-transitions the same.
There are some advanced cases where you need full control using the
original URL which this unlocks.
<!-- 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: Sam Ko <sam@vercel.com>
I've updated the Next.js documentation to include a new page covering
the best practices for implementing authentication. This doc covers the
essential concepts of authentication in Next.js, focusing on practical
strategies, effective session management, and robust authorization
techniques.
Key aspects of the update:
- Core Authentication Concepts: Introduced foundational concepts of
authentication, detailing their relevance and application in Next.js
projects.
- Diverse Authentication Strategies: Expanded on various authentication
strategies, providing insights on when and how to use them effectively
in different scenarios.
- Implementing Authentication in Next.js: Guided through the
implementation process, illustrating the use of middleware, server
actions, and route handlers to create a secure and user-friendly
authentication system.
- Session Management Techniques: Discussed different approaches to
session management, highlighting their pros and cons to aid in choosing
the most suitable method for specific project needs.
- Securing Application Access: Detailed how to protect routes and manage
user permissions, ensuring that access is granted appropriately based on
user roles and authentication status.
- Next.js Compatible Solutions: Included references to several
compatible authentication solutions for Next.js, facilitating easy
integration and setup.
---------
Co-authored-by: Balázs Orbán <info@balazsorban.com>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
This PR stabilizes the previously introduced experimental config options
for providing a custom cache handler (for both ISR as well as the Data
Cache) and for disabling or configuring the in-memory cache size. The
example usage would be as follows:
```js
// next.config.js
module.exports = {
cacheHandler: require.resolve('./cache-handler.js'),
cacheMaxMemorySize: 0 // disable default in-memory caching
}
```
This PR also updates the documentation to better reflect how to use the
custom cache handler when self-hosting. Further information will be
added in a following PR that also includes a full example of a custom
cache handler that implements `revalidateTag` as well as passing in
custom cache tags. The API reference docs have been updated here, as
well as a version history added.
I also noticed that we currently have two duplicated versions of the ISR
docs in the Pages Router docs: both for rendering and for data fetching.
Data Fetching is the correct location for this page. There were no other
references to the rendering version in the docs, so that must have been
an accident. I'll need to a get a redirect going for that regardless.
Tests have been updated for `cacheHandler` and I added a new test for
`cacheMaxMemorySize`.
---------
Co-authored-by: Jiachi Liu <inbox@huozhi.im>
The following spans are either added or displayed by default:
* `NextNodeServer.findPageComponents` - page components
resolution/require
* `NextNodeServer.getLayoutOrPageModule` - load modules (webpack or
turbopack)
This would allow different apps to setup fetch instrumentation similar
to `@opentelemetry/instrumentation-http` and
`@opentelemetry/instrumentation-fetch` without duplicating fetch spans
and avoiding confusion with context propagation.
This adds documentation around the client router filter we leverage in
`pages` to allow incremental migration from `pages` to `app`. Also adds
mention of two experimental configs that can be useful for managing the
client router filter.
x-ref:
https://github.com/vercel/next.js/issues/47486#issuecomment-1889623898
Closes NEXT-2090
---------
Co-authored-by: Sam Ko <sam@vercel.com>
Reverse directory order to indicate that `src/` or the parent of `app/`
should be used.
At first I thought the correct place was the parent folder of `src/`,
this eliminates that confusion
New page outlining all options for handling redirects in Next.js, from
the simplest use cases (e.g. `redirect()` in a Server Action), to more
advanced cases (e.g. bloom filters and middleware).
- [x] `redirect`
- [x] `permanentRedirect`
- [x] `useRouter`
- [x] `next.config.js`
- [x] Middleware
- [x] Handling redirects at scale
- [x] Edge config
- [x] Bloom filter
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Addition to docs (robots.mdx) - Customize user-agent rules
For issue #59178
Docs: Guidance on allowing multiple user agent rules with varying
allow/disallow.
<!-- 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: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Sam Ko <sam@vercel.com>
Co-authored-by: Delba de Oliveira <delbabrown@gmail.com>
At the moment, `@next/third-parties` is only working on canary. This can
be a blocker for those trying it out on `latest`. This updates the
experimental note to recommend installing canary.
The note should be removed once the package is stable.
Closes: https://github.com/vercel/feedback/issues/51035
ts version has been identical to the js version
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Delba de Oliveira <delbabrown@gmail.com>
- `useSearchParams` opts the client component subtree out of static
rendering (pre-rendering), not dynamic rendering. We recommend wrapping
the component that uses `useSearchParams` in a Suspense boundary to
allow client components above it to be statically rendered (part of the
initial HTML).
Closes: https://vercel.slack.com/archives/C03S9JCH2Q5/p1704398859737719
When trying to generate my SSG docs site I couldn't figure out why the
navigation links (`href="/about`) were not mapping to the generated
files (e.g. `/out/about.html)`.
`trailingSlash` was key to converting the files to
`/out/about/index.html` to make the SSG links work properly.
I've updated the trailingSlash docs to be clear how they affect SSG
mode.
It might also make sense to add this to the SSG guide as well.
Co-authored-by: Steven <steven@ceriously.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
### 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 #
-->
### What?
A tiny correction could be made in an example in the Middleware usage
example.
### Why?
N/A
### How?
1. Verified that the actual cookie returned in the response headers
matches this.
2. Fixed the example
3. Ran `pnpm prettier-fix`
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Adds a small section to the `Optimizing: Third Party Libraries`
documentation page on tracking client-side pageviews for Google
Analytics
---------
Co-authored-by: Steven <steven@ceriously.com>
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>
Found this from build error trace while testing the change in #59569
```
docs/02-app/01-building-your-application/08-testing/02-jest.mdx": UnexpectedMDXError: Error: Build failed with 1 error:
--
_mdx_bundler_entry_point-776983b1-6900-47c0-98cc-0c35882e9532.mdx:297:0: ERROR: [plugin: @mdx-js/esbuild] Unexpected closing tag `</PageOnly>`, expected corresponding closing tag for `<PagesOnly>
```
Closes NEXT-1863
This PR updates the testing guides to use App Router and TypeScript,
also updates `/examples` to show `app` and `pages` examples.
## Overview
- [x] Create a new "Testing" section that is shared between `app` and
`pages`.
- [x] Explain the differences between E2E, unit testing, component
testing, etc.
- [x] Recommend E2E for `async` components as currently none of the
tools support it.
- [x] Update setup guides for **Cypress**, **Playwright**, and **Jest**
with latest config options, and examples for `app` and `pages`.
- [x] Add new guide for **Vitest**
- [x] Clean up `/examples`: use TS, show `app` and `pages` examples,
match docs config
## Cypress
- [x] E2E Tests
- [x] Component Testing
- [x] Client Components
- [x] Server Components
- [ ] `async` components
**Blockers:**
- TS: `Option 'bundler' can only be used when 'module' is set to
'es2015' or later`. In **tsconfig.json** compilerOptions, Next.js uses
"moduleResolution": "bundler", changing it to "node" fixes the issue but
it can have repercussions.
- https://github.com/cypress-io/cypress/issues/27731
- Version 14 is currently not supported for component testing
- https://github.com/cypress-io/cypress/issues/28185
## Playwright
- [x] E2E Tests
## Jest
- [x] Unit Testing
- [x] Client Components
- [x] Server Components
- [ ] `async` components:
https://github.com/testing-library/react-testing-library/issues/1209
- [x] 'server-only': https://github.com/vercel/next.js/pull/54891
- [x] Snapshot Testing
**Blockers:**
- TS: https://github.com/testing-library/jest-dom/issues/546
- None of the solutions in the issue work with Next.js v14.0.4 and TS v5
## Vitest
- [x] Unit Testing
- [x] Client Components
- [x] Server Components
- [ ] `async` components
- [x] 'server-only'
- [x] Update vitest example
- [x] Handles CSS, and CSS modules imports
- [x] Handles next/image
## Other
- https://github.com/vercel/next.js/issues/47448
- https://github.com/vercel/next.js/issues/47299
Implementation of feature request opened here -
https://github.com/vercel/next.js/discussions/59427
Approach:
~~We are using micromatch in the csrf protection step of actionHandler
to allow for wildcard domains passed in allowedDomains. This is the same
library used for matching domains for remote images.~~
If any of the allowed domains match the origin of the request, we skip
the downstream error thrown for csrf protection.
Edit:
Micromatch is not available in this context as it is only compatible
with Node. This codepath can be run from the edge, so we need to rely on
vanilla js compatible code only.
Instead of falling back to allowing the user to pass in a regex, which
can be somewhat insecure, we opt into continuing to use a wildcard
pattern from a configuration standpoint and instead use a simple
function that matches on wildcards using string comparison and
iteration.
Ideally, Micromatch can be retrofitted to work in non-Node settings and
this piece of code can be replaced in the future, without deprecating or
changing the next.config interface.
---------
Co-authored-by: Josh Story <story@hey.com>
