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>
- [x] Rename page from `forms-and-mutations` to
`server-actions-and-mutations` to account for examples that don't use
forms.
- [x] Split `/pages` and `/app` content to make easier to edit
- [x] Add Security Section
- [x] Recommend tainting
- [x] Closures and encryption
- [x] Overwriting encryption keys
- [x] CSRF protection | Allowed Origins
- [x] Add examples for Server Actions being called outside forms
- [x] `useEffect`
- [x] Event handlers
- [ ] ~3rd party libraries~
- [x] More form examples
- [x] Add note on calling actions in `<button>` and `<input> `
- [x] Add `.bind` example | Recommend bind over hidden input field
- [x] Recommend `try/catch` for error handling
- [x] Create `serverActions` next.config.js page
- [x] Document `allowedOrigins`
- [x] Document `bodySizeLimit`
- [x] Add note on Server Actions flag for < v14
- [x] Update error message links
- [x] Remove Server Actions from API reference as it's a React feature.
E.g. We don't have API references for Server Components.
- [ ] Set up redirects:
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Shu Ding <g@shud.in>
Co-authored-by: Michael Novotny <manovotny@gmail.com>
### What?
Calling `redirect` or `permanentRedirect` with a route handler used by a server action will result in that POST request following the redirect. This could result in unexpected behavior, such as re-submitting an action (in the case where the redirected URL makes use of the same server action).
### Why?
By spec, 307 and 308 status codes will attempt to reuse the original request method & body on the redirected URL.
### How?
In all cases when calling a `redirect` handler inside of an action, we'll return a `303 See Other` response which is a typical status code when redirecting to a success / confirmation page as a result of a POST/PUT.
The other option would be to use 301 / 302 status codes, but since we're already doing a 303 status code [here](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/action-handler.ts#L603), this aligns the behavior for the route handler case.
Closes NEXT-1733
See also: https://github.com/vercel/next.js/issues/51592#issuecomment-1810212676
[Slack x-ref](https://vercel.slack.com/archives/C03S8ED1DKM/p1700060786749079)
Closing: https://github.com/vercel/feedback/issues/47084
- The example previously showed `export const revalidate` being called
from a `utils` file, whereas we want to call it from a route segment
(layout or page)
* Add docs link to the warning, add codemod link to viewport docs section
* Only log the warning once after the metadata resolving process, this will avoid multiple duplicated logs showing for one page.
Closes NEXT-1723
We've heard confusion around Route Handlers being cached by default for
`GET`s. While we do have a section on this in the docs, I've made this
more explicit by making the examples default to dynamic, while
mentioning the defaults.
Adds a bit more clarity that while the edge runtime certainly enables
faster startups than the Node.js runtime (by being in general lighter),
it does not mean the additional user code added will not affect the boot
time. Hello world might be instant but I believe "low" better reflects
that it _will_ grow with user code added.
### What?
This pull request integrates the exemplary setup for a self-hosted Next.js application utilizing Redis as a shared cache storage. The solution supports caching at both the App and Pages routers in default and standalone modes, as well as partial pre-rendering, facilitated by the [`@neshca/cache-handler`](https://github.com/caching-tools/next-shared-cache/tree/canary/packages/cache-handler) package. The package enables customizing cache handlers and replacing the default cache provided by Next.js seamlessly.
### Why?
The motivation behind this pull request is to provide an example demonstrating how Redis can be used as a shared cache in a self-hosted environment, thereby improving the scalability of hosting multiple instances of a Next.js application.
### Description
Adds config for experimental PPR support
### Related Issue(s)/Incident
Prior art: #57444
### Best Way to Test
Visit → docs/app/api-reference/next-config-js/partial-prerendering
Co-authored-by: Amy Burns <5012825+timeyoutakeit@users.noreply.github.com>
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
This PR is a combination of many months of feedback from the community
on how to self-host with Next.js. It's became clear talking to many of
y'all that there is confusion about if all features are supported when
self-hosting, and what implications this has when using third-party
providers.
The deployment docs now clarify that all features are supported when
self-hosting. However, this comes with important notes. First, we're
building a standard deployment output, not adapters. We want these docs
to ensure that if you follow what's described on this page, you're going
to have a good experience with Next.js and will be able to take
advantage of all features. Previously, we had to add caveats in here
about different providers and their level of support. We are not doing
that anymore.
Instead, we're providing further details on different features and how
they can be configured when self-hosting. These docs have existed in
other locations (e.g. the specific API pages in our docs), but I've
combined and simplified them here so there's one page you need to read
to learn about all of the options. If you self-host Next.js anywhere
with a Node.js server, Docker container, or static HTML export, all of
the following features will work as expected. Further, we've added other
specifics around self-hosting ISR / Data Cache and configuring your
caching location, which is important when self-hosting with Kubernetes.
Finally, there has been a common feature request to allow runtime
environment variables, rather than statically inlining the values during
the build. While this was possible with `getServerSideProps` in the
Pages Router, if the value needed to be used on the component body, this
option didn't work, as it needed to be serialized and forwarded to the
component. With the App Router, this problem is solved, since Server
Components can render entirely on the server. Thus, when dynamically
rendering, you can just use `process.env.MY_VALUE` and it works.
I also toned down the Vercel section, because, it was a bit much TBH.
Related: https://github.com/vercel/next.js/pull/57953
---------
Co-authored-by: Ahmed Abdelbaset <A7med3bdulBaset@gmail.com>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
### What?
continuation of https://github.com/vercel/next.js/pull/57851, since it is from a remote branch that I don't have access to write.
Co-authored-by: Maia Teegarden <2865858+padmaia@users.noreply.github.com>
Co-authored-by: Tim Neutkens <6324199+timneutkens@users.noreply.github.com>
Fix bug in example code. Loading with `'` can not be built with the default ESLint rules:
```ssh
./src/app/reviews/loading.tsx
4:15 Error: `'` can be escaped with `'`, `‘`, `'`, `’`. react/no-unescaped-entities
4:26 Error: `'` can be escaped with `'`, `‘`, `'`, `’`. react/no-unescaped-entities
```
Scope all `serverActions` config in one group "serverActions" to make it
more semantics
---------
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
This PR removes the wasm target for the next-swc build for the next major version. The main motivation is that Turbopack does not support targeting wasm yet, and it would be a significant amount of work to add. We plan to make Turbopack the default zero-config experience in a minor version, possibly before we are able to support a wasm target, so we need to make this breaking change now. We also plan to make more improvements to the webpack experience with shared Rust code, which we have so far been blocked from implementing because of the current wasm restrictions. We would like to support a wasm target again in the future, but cannot say at this time when that would be.
Closes WEB-1865
This PR adds the codemods transforming certain fields from `metadata`
export to `viewport` export, will still preserve rest metadata export
properties. We don't cover `generateMetadata` to `generateViewport` as
there might be more complex logic inside the function which is hard to
apply the codemods rules.
TLDR: Codemods for #57302
* Should show `ImageResponse` is deprecated if you still import from `"next/server"`
<img width="708" alt="image" src="https://github.com/vercel/next.js/assets/4800338/38f9b9db-2cfb-48ec-99cc-08e7d1477155">
* If you build it will fail to compile, this might not be super ideal but at least it's not working. For pure js it will throw errors.
```ts
./app/icon.tsx:7:10
Type error: Only a void function can be called with the 'new' keyword.
5 |
6 | export default function icon() {
> 7 | return new ImageResponse(
| ^
8 | (
9 | <div
10 | style={{
ELIFECYCLE Command failed with exit code 1.
```
Remove the experimental `serverActions` flag
Co-authored-by: Shu Ding <3676859+shuding@users.noreply.github.com>
Co-authored-by: Jiachi Liu <4800338+huozhi@users.noreply.github.com>
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`.
### Story
Since we introduced `ImageResponse` into `next/server` export, there're a few libraries relying on `next/server` that accidentally ended up with bundling og image into the bundle. As og package is quite large that could easily raise the size concern for middleware, edge runtime routes.
### Struggles
We've done optimizations. The tree-shaking strategies are tricky, we tried modularize imports and also optimize cjs require/exports to make sure you're not including og package into bundle if it's not being used. However, it's still not 100% can handle all the bundle optimization cases, such as `import {..} from "next/server.js"` could also ended up with the cjs bundle that failed the tree-shaking.
### Move on
So we decide to move og `ImageResponse` into a separate export `next/og`
Closes NEXT-1660