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
## History
We used to pass `onLoad` through directly to the underlying img so `onLoadingComplete` was introduced in order to handle the case when `placeholder="blur"` was used and `onLoad` would trigger before the placeholder was removed.
We have since changed the behavior of `onLoad` so that it acts the same as `onLoadingComplete` and therefore `onLoadingComplete` is no longer needed.
## What is this PR doing?
This PR marks `onLoadingComplete` as deprecated in favor of `onLoad`. In the future, we may remove `onLoadingComplete`.
Upgraded dotenv to v16. Breaking changes are:
- Multiline parsing support
- Support inline comments
- Backtick support
[See their changelog](https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md)
## Feature
- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`
Co-authored-by: Balázs Orbán <18369201+balazsorban44@users.noreply.github.com>
### What?
BREAKING CHANGE: Bump the minimum required Node.js version.
### Why?
Node.js 16 has reached end-of-life in September.
Bumped to `18.18.2` since it contained some security-related patches: https://nodejs.org/en/blog/vulnerability/october-2023-security-releases
### How?
Bumped `engines` where needed, upgraded the workflows.
This will allow us to remove quite a few polyfills, I'll open separate PRs for those.
Fixed a typo -
docs/04-architechture/supported-browsers.mdx
Changes(s) made -
Fixed a typo for improving clarity
[includes -> include]
'your dependencies includes' -> 'your dependencies include'
Please review and merge it.
Based on feedback from #56603, the `/` can be interpreted as file paths instead of filename separators / delimiters. We'll change them to use pipes `|` instead.
Fixed the example functions in the documentation to use `async` in order to use `await` within the function body.
Co-authored-by: Michael Novotny <446260+manovotny@users.noreply.github.com>
### What?
Update documentation on dynamic routing to clarify the use of segment names within file names, rather than referring to them as "folder names".
### Why?
The original documentation used the example term `folderName` when it was referencing dynamic segment names within filenames. The paths being described here are file names but not folders, and end in a file extension. This could confuse readers and developers, especially those new to Next.js, leading to potential misunderstandings and misconfigurations. Perhaps folderName was a relic of a different example wrapping a folder name to do a nested path or other configuration? But here it seems out of place.
### How?
- Reviewed the provided documentation sections on dynamic routing.
- Replaced references to "folderName" with a different term "segmentName".
- Ensured the examples provided in the documentation correctly showcase the use of segment names within filenames.
IMO there is not enough of an indicator that client components render on the server on full page loads towards the top of the documentation page. I've seen plenty of experienced devs totally miss this critical info and get stuck on a problem due to a lack of understanding. Putting at least some kind of indicator above the fold would help with that.
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
When trying to update my own website to use App Router, I found the current Next.js Docs were missing specifics to get it working (most notably, no mention of `pageExtensions`). Coupled with community feedback, we decided to revisit and rework the entire page.
The page has been walked through and tested on brand new create-next-app projects for both App and Pages Routers to ensure completeness.
Closes [DX-2095](https://linear.app/vercel/issue/DX-2095/improve-nextjs-mdx-docs)
Rendered pages while running locally, in case they are more helpful in seeings the changes and different between routers.
### App Router
### Pages Router
The link to the useSearchParams ref within the File Conventions > layout.js page currently links to the useParams ref, which is wrong and may lead to confusion as the useParams and useSearchParams APIs operate differently.
TypeScript 5.2 now supports `Response.json` (https://github.com/microsoft/TypeScript/issues/52841). That means, if we just need to return a JSON `Response`, we no longer need to import `NextResponse`. This PR updates all such instances in the documentation to use `Response.json`.
This will be the recommended way of passing extra arguments to a Server Action. A couple of reasons behind:
- This is better than putting a hidden `<input hidden value={userId}/>` because that will appear in the SSR'd HTML as full text and cannot be encoded. With `.bind`, we can handle that in the future.
- This is better than event callbacks `onSubmit={(e) => { await updateUser(userId, e.target.formData) }}` as this supports progressive enhancement.
- This is better than re-creating a new action `action={async (formData) => { "use server"; return updateUser(userId, formData) }}` as inlined `"use server"` only works in Server Components.
In "app/actions.ts" the function is named like create(), but in "app/add-form.tsx" file "createTodo" function is imported and used. This is related to TypeScript examples, .js files are ok.
### What?
Renamed a function.
### Why?
There are two example files in docs ([Error Handling](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#error-handling) section) and the `app/add-form.tsx` is importing function `create` from `app/actions.ts` by another name (`createTodo`).
### How?
Fixed by renaming function to `createTodo`, to match .js file with the same example.
### Why?
Whenever I run `create-next-app` and reach this question
```
Would you like to customize the default import alias? No / Yes
```
I always have to select "No", because I don't remember what this default import alias here is. [It _is_ documented to be `@/*`](https://nextjs.org/docs/app/api-reference/create-next-app#non-interactive), but the documentation is relatively hidden and not many people know about it – it's also easy to forget.
Even more confusingly, the next question ("What import alias would you like configured?") doesn't have this `@/*` as the default answer, but the user's last choice as the default answer instead (which could be different from `@/*` – making people wonder if Next.js changed their defaults overnight).
I suppose it would be better to just make it clear in the prompt itself, so people with skill issues who happen to forget that default value (like me) can still confidently select "Yes" if they want `@/*`, without having to do "No" and manually type `@/*` again.
### How
```diff
- Would you like to customize the default import alias?
+ Would you like to customize the default import alias (@/*)?
```
as many developers are moving to bun, its a good idea that it also be included as an installation method.
Co-authored-by: Steven <229881+styfle@users.noreply.github.com>
### What?
Fixing a little mistake in the documentation, where the placement of the `extension` option for `createMDX()` was described as being inside the `options` property:
```ts
const withMDX = createMDX({
options: {
extension: /\.mdx?$/,
```
But it's actually a property of its own:
```ts
const withMDX = createMDX({
extension: /\.mdx?$/,
```
I confirmed that the latter is correct because:
- It solves an issue I was having: Unable to import `.md` files
- On the same docs page, there's another place where it mentions this `extension` option and the code example is correct there
- The option is described in a similar issue, such as https://github.com/vercel/next.js/issues/45431#issuecomment-1410363864
Issue: https://github.com/vercel/next.js/issues/53888
Added "not-found.js" information to error.mdx after the `global-error.js`. Please approve.
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
```
Pages and Layouts
The Pages Router has a file-system based router built on the [concept of pages](https://nextjs.org/docs/pages/building-your-application/routing/pages-and-layouts).
```
Change requested:
Here `concept of pages` hyperlinks routes to the current page. This bit confusing for someone trying to learn next.js. removing the hyperlink to the text would make clear.
## Why?
Although the left padding makes the output looks good in the terminal, it causes this weird alignment in almost all bug reports:
```yaml
Operating System:
Platform: win32
Arch: x64
Version: Windows 10 Pro
Binaries:
Node: 18.12.0
npm: N/A
Yarn: N/A
pnpm: N/A
Relevant Packages:
next: 13.5.2-canary.2
eslint-config-next: 13.5.2
react: 18.2.0
react-dom: 18.2.0
typescript: 5.2.2
Next.js Config:
output: N/A
```
If I want it to look nice in the bug report
```yaml
Operating System:
Platform: darwin
Arch: arm64
Version: Darwin Kernel Version 23.0.0: Thu Aug 17 21:23:02 PDT 2023; root:xnu-10002.1.11~3/RELEASE_ARM64_T8112
Binaries:
Node: 20.3.1
npm: 9.6.7
Yarn: 1.22.19
pnpm: 8.6.12
Relevant Packages:
next: 13.5.2
eslint-config-next: N/A
react: 18.2.0
react-dom: 18.2.0
typescript: 5.2.2
Next.js Config:
output: N/A
```
I have to paste this to a text editor and manually remove the first four spaces on every lines.
### How?
This PR removes that four-space padding to make future bug reports look a bit nicer.
- Removes a line from next docs that is no longer accurate:
> Currently, if a route uses a Server Action, it is required to render
dynamically.
According
With the release of Next.js 13.5, Server Actions now work with fully
static routes (including revalidating data with ISR).
<!-- 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>
While an import may work on initial load, fast refresh fails, and also this can also cause issues when trying to deploy your project to Vercel, resulting in your component not being found.
This could save people time when they run into this issue, and I wish this small nuance, would've been in the docs.
Co-authored-by: Steven <229881+styfle@users.noreply.github.com>
- remove the slash before `pathname` (already included in the value).
- add `search` and `hash` values in redirected url:
- retains these values on redirect
- they already have `?` and `#` respectively
Co-authored-by: Balázs Orbán <18369201+balazsorban44@users.noreply.github.com>
[As of Bun v1.0.0](https://bun.sh/blog/bun-v1.0#changelog-since-v0-8), `bun dev` runs the "dev" script from package.json. Therefore, as with Yarn and pnpm, the "run" command is not necessary.
This PR changes the `create-next-app` README templates to show `bun dev` instead of `bun run dev`.
### What?
Follow-up of #54926.
While that PR's main fix is no longer necessary due to the removal of render workers, I figure that some changes are nice-to-have and have isolated them into this PR. This includes fixing `appUrl` and `networkUrl` in `start-server`, fixing docs and removing some unnecessary template literals in `turbopack-warning`.
### How?
`appUrl` now tries to use `hostname` instead of `actualHostname` (an address like `example.com` seems to be more useful here than an IP like `xxx.xxx.xxx.xxx`), and `networkUrl` is now prefixed with `http://`.
Other simple changes include fixing docs.
Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>
This PR clarifies `isrMemoryCacheSize` value units. Units is not obvious
due to `Defaults to 50MB` comment and lack of TSDoc comments
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
The `libsql` package is a fork of `better-sqlite3` that powers the Turso database client. Let's add `libsql` to the list of external packages, like `better-sqlite3`, so that people don't have to add extra configuration for their Next.js applications.
nonce's are limited to characters found in base64 encoding, uuids contain '-' which breaks the spec,
converting to a base64 string after generating simplifies this
---
This was a bit gotcha in our project, there are a few tools that only expect there to be a single `-` and do a split based off it (so when there are >1 they fail)
## Rules for nonce's
- The nonce must be unique for each HTTP response
- The nonce should be generated using a cryptographically secure random generator
- The nonce should have sufficient length, aim for at least 128 bits of entropy (32 hex characters, or about 24 base64 characters).
- Script tags that have a nonce attribute must not have any untrusted / unescaped variables within them.
- The characters that can be used in the nonce string are limited to the characters found in base64 encoding.
Ports content from the Pages and Layouts section about templates and formats to match other API reference pages.
Co-authored-by: Michael Novotny <446260+manovotny@users.noreply.github.com>
> Layouts do not have access to the current route segment(s). To access route segments, you can use useSelectedLayoutSegment or useSelectedLayoutSegments in a Client Component.
The term "current" is confusing.
It should be only the route segments under the layout. For example: `app/layout.tsx` can not access `app/[slug]`.
Missing word in client component page in docs when discussing the effect of "use client" on a client component's children and imported components. Not sure if 'children' is the appropriate word or whether there should be a reference to imported components too.
Update the code snippet for configuring API Routes to include `maxDuration` as an option.
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
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
### What?
Clarify the "Forms and Mutations" docs.
### Why?
This may be opinionated, but I believe this section of the docs starts out assuming that the user knows how the `<form>` HTML works. Coming from the client side React world, most developers are used to using state in forms. Clarifying that this data is accessible via the standard web API [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) is essential for both transitioning developers and new developers.
### What?
This adds to the docs a guide for migrating a Vite application to
Next.js. It also contains a section that lists the reasons why one would
want to switch from Vite to Next.js.
### Why?
This guide is helpful for developers that want to switch to Next.js but
don't know how difficult that would be and how to do it. The "Why?" list
is also helpful to developers who haven't yet been convinced to switch
or need help formulating the reasons to switch to decision-makers.
This guide was [first published on the Inngest
blog](https://www.inngest.com/blog/migrating-from-vite-to-nextjs). To
our own surprise, we were able to [migrate from Vite to
Next.js](https://github.com/inngest/inngest/pull/479) our [Dev Server
app](https://github.com/inngest/inngest/tree/main#the-inngest-dev-server)
in less than a day, which motivated us to share our learnings with the
community.
### How?
The guide aims to have the minimum number of steps to get a working
Next.js application so that
the reader can then adopt Next.js features incrementally. This means the
migration of the router isn't part of this guide. However, this would be
something valuable to document at a later time so that the reader can
also learn how to migrate to the App Router and get all the Next.js
benefits.
## What?
- Updated the heading structure in the documentation to maintain a consistent hierarchy.
- All primary points now use `###` for better readability and understanding of content structure.
## Why?
While reviewing the documentation, I noticed that the heading levels were inconsistent between sections 1, 2, and 3-5.
for internal:
https://vercel.slack.com/archives/C03S8ED1DKM/p1691700057242999
### Problem
- The existing [`redirect()`
function](https://nextjs.org/docs/app/api-reference/functions/redirect)
can't control the status code.
- The existing [`redirect()`
function](https://nextjs.org/docs/app/api-reference/functions/redirect)
returns a 307 HTTP redirect response while it returns a 308-equivalent
meta tag `<meta http-equiv="refresh" content="0;url=/foo"/>` in
streaming response (e.g., suspense boundary), making the behavior
inconsistent.
### Solution
Adding a new `permanentRedirect()` function and changing the meta tag
default accordingly.
| func | HTTP status | meta tag |
|---|:---:|---|
| `redirect()` | 307 | `<meta http-equiv="refresh"
content="1;url=/foo"/>` |
| `permanentRedirect()` | 308 | `<meta http-equiv="refresh"
content="0;url=/foo"/>` |
ref.
https://developers.google.com/search/docs/crawling-indexing/301-redirects
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
add if statement, because typescript throws error: revalidatePath require `string`, but `searchParams.get('path')` returns `string|null` type
Co-authored-by: JJ Kasper <22380829+ijjk@users.noreply.github.com>
https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations
Some of the code blocks where I only specified TS code snippets aren't
working with JS as well (when there are no types). I think I might have
incorrectly assumed you could leave those out. So added the JS snippets
in here (same code, just different file names).
This PR is a larger change to documentation to make the following
updates:
- Deconstructs [Server
Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions)
into "Forms and Mutations" and an API reference
- Removes content in place of future React API documentation pages
- Removes outdated [Building
Forms](https://nextjs.org/docs/pages/building-your-application/data-fetching/building-forms)
docs from the Pages Router and adds conditional content for both routes
in "Forms and Mutations"
- Adds TypeScript code blocks to API Routes page, recommends Route
Handlers for isomorphic signatures.
- Updates `revalidatePath` and `revalidateTag` docs to have a Server
Actions example.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Hello!
I recently tried to cache the `.next/cache` directory in a GitHub action following what was said in the documentation and realized that hashing the source files didn't work properly.
This problem also occured in [next-cache](https://github.com/jongwooo/next-cache) and was fixed by [this PR](https://github.com/jongwooo/next-cache/pull/17).
This PR simply changes the example from the documentation to apply the same fix (stop using brackets in the patterns passed to `hashFiles`).
Hope it helps!
### 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
This PR adds missing parameters to the `useSelectedLayoutSegment` & `useSelectedLayoutSegments` hooks since they take *optional* `parallelRoutesKey`.
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
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>
Fixed `next/jest.js` import in documentation. without `.js` it show this error
```
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'F:\React\my-project\node_modules\next\jest' imported from F:\React\my-project\jest.config.mjs
Did you mean to import next/jest.js?
at new NodeError (node:internal/errors:399:5)
at finalizeResolution (node:internal/modules/esm/resolve:326:11)
at moduleResolve (node:internal/modules/esm/resolve:945:10)
at defaultResolve (node:internal/modules/esm/resolve:1153:11)
at nextResolve (node:internal/modules/esm/loader:163:28)
at ESMLoader.resolve (node:internal/modules/esm/loader:838:30)
at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
at link (node:internal/modules/esm/module_job:76:36)
```
### Why?
Many developers are asking how to add internationalized routing in the App Router as it works in the Pages Router. [next-i18n-router](https://www.npmjs.com/package/next-i18n-router) is a very helpful package that fully solves this challenge.
### How?
Unlike the example provided in these Next.js i18n docs, [next-i18n-router](https://www.npmjs.com/package/next-i18n-router) does not require nesting all pages in a `[lang]` dynamic segment. It also allows for the default language to be accessible without a locale prefix in the path (just like in the Pages Router).
It includes locale detection based on the `accept-language` header as recommended in the Next.js docs, as well as support for the `NEXT_LOCALE` cookie to set a user's preferred language (just like in the Pages Router).
Clarify what status code is returned when streaming, and in relation to `redirect` and `not-found`.
Relates to: https://github.com/vercel/next.js/pull/54361
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
Fixes: https://vercel.slack.com/archives/C03S9JCH2Q5/p1692619927373449
- Updates wording on nesting, to say it's not the actual output, but rather how `template.js` nests between `layout.js` and its children.
- Remove mention of animations, needs further clarification.
Hello,
I just make this PR because the `/me.png` example is not in "remote images" section but in "local images", that's why I propose to edit this :)
Thank you!
### 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
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.
When implementing `opengraph-image` in my [personal-site-project](https://github.com/kylemcd/personal-site). I was consistently running into issues where custom fonts would either only work locally or only work on vercel. To me it seemed like differences in pathing in `edge` vs `nodejs` runtimes. After digging around I found issue #48081, more specifically [this comment](https://github.com/vercel/next.js/issues/48081#issuecomment-1565842740) where moving the `fetch` for the font into the `Image` function solved the issue.
I'm not sure if this is 100% the correct fix, or if this is an issue that needs to be solved in another way. If that's not the case this PR updates the documentation around `opengraph-image` to have the fetch for custom fonts inside of the `Image` function.
Added a switcher on a code snippet under heading -> `Using Cookies`, just like the other code snippets on this page got one..
(For those who don't know what a switcher is -> It's just a simple functionality for changing `typescript` code to `javascript` and vice-versa, kind of a UI feature for better experience`
Co-authored-by: Balázs Orbán <18369201+balazsorban44@users.noreply.github.com>
Previous of after (before in linked issue)
```
❯ pnpm add --save-dev @next/eslint-plugin-next
Already up to date
Progress: resolved 525, reused 517, downloaded 0, added 0, done
Done in 6.4s
```
Resolves#53937
Adds support for base64-encoded `placeholder`. Enables using placeholders without the "blur" effect.
Fixes#47639
- [x] Add support for DataURL placeholder
- [x] Add tests
- [x] Update docs
Co-authored-by: Steven <229881+styfle@users.noreply.github.com>
## 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>
You can technically get similar ISR behavior setting the `Cache-Control` in `getServerSideProps()`, but this won't be automatically bypassed when enabling Preview Mode or Draft Mode so this PR adds that to the documentation.
x-ref: [slack discussion](https://vercel.slack.com/archives/C03S8ED1DKM/p1691514209722429)
