This configures the default client router cache `staleTime.dynamic`
value to be `0`.
This means that:
- Navigating between pages will always fire off a network request to get
RSC data for the page segment, rather than restoring from router cache
- Loading states will remain cached for 5 minutes (or whatever
`config.experimental.staleTimes.static` is set to)
- Shared layout data will continue to remain cached due to [partial
rendering](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering)
- Back/forward behavior will still restore from cache to ensure the
browser can restore scroll position.
It's possible to opt-out of this, and into the previous behavior, by
setting the
[`staleTimes`](https://nextjs.org/docs/app/api-reference/next-config-js/staleTimes)
config in `next.config.js`:
```js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
staleTimes: {
dynamic: 30
},
},
}
module.exports = nextConfig
```
<!-- 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 #
-->
## Background
Currently route handlers will be attempted to statically generate the
same as normal pages in app router. If a route handler accessed dynamic
data such as `cookies()`, `headers()`, `req.url`, or similar we would
bail from this static generation but this didn't handle the case where
you would do data fetching via a non-fetch based library e.g. `redis` or
even using `Date.now()` or `Math.random()` so users would expect these
to be run every request like normal API endpoints but they would be
static so wouldn't be executed again after a build.
## New Behavior
As discussed this disable the default static generation handling for
route handlers as we've seen this confuse our users since in most cases
when creating a route handler you are handling dynamic workloads. This
doesn't remove the ability to static generate route handlers though as
you can still manually specify:
If you specify `export const revalidate = 1` we will still bail if
dynamic data is accessed to prevent accidental `revalidate` configuring
but this can be avoided via `force-static` being used as well.
```js
export const dynamic = 'force-static'
// or
export const dynamic = 'error'
// or
export const revalidate = false
// or
export const revalidate = 1 // value great than 0
// or
export const generateStaticParams() {}
```
---------
Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>
This PR addresses an issue where the `dev` script in `package.json` was
not correctly updated to use the `--turbo` option when specified. The
changes ensure that the `dev` script is set to `next dev --turbo` if the
`turbo` option is enabled.
### Changes:
1. **Function Modification**:
- Updated the `modifyPackageJson` function to include a check for the
`turbo` parameter.
- If `turbo` is true, the `dev` script in `package.json` is set to `next
dev --turbo`.
- If `turbo` is false, the `dev` script remains `next dev`.
2. **Integration in App Creation**:
- Integrated the `modifyPackageJson` function into the app creation
process to ensure the `dev` script is correctly set based on the `turbo`
parameter.
### Testing:
- Verified that the `dev` script in `package.json` is correctly updated
to `next dev --turbo` when the `turbo` option is enabled.
- Ensured that the `dev` script remains `next dev` when the `turbo`
option is not enabled.
### Related Issues:
- Fixes#65924
### Notes:
- This change ensures that developers opting to use Turbopack for
development will have the correct script set up automatically.
---------
Signed-off-by: Arindam Majumder <arindammajumder2020@gmail.com>
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: devjiwonchoi <devjiwonchoi@gmail.com>
Co-authored-by: Jiachi Liu <inbox@huozhi.im>
Co-authored-by: Sam Ko <sam@vercel.com>
The useFormState hook was renamed to useActionState in react 19. At this
moment react 19 is still in Canary, it would be hard for beginners to
realise this.
Mentioning the fact of it being renamed will ideally help new people.
---------
Co-authored-by: Sam Ko <sam@vercel.com>
### What?
Replace `twitter.com` links in the docs with `x.com`
### Why?
Now that Twitter (twitter.com) has officially moved to the x.com domain
### How?
- Replace the link, then click on the link to make sure there are no
problems
Closes NEXT-
Fixes#65916
---------
Co-authored-by: Sam Ko <sam@vercel.com>
App router [does not
support](https://nextjs.org/docs/messages/app-dir-dynamic-href) dynamic
hrefs: removing it from the app router docs, and only having it in the
pages router docs.
Fixes#65505
---------
Co-authored-by: samcx <sam@vercel.com>
This pull request introduces type-only imports to the examples across
several documentation sections.
By specifying `import type`, we clarify that certain imports are used
only for type checking and not as part of the executable code, improving
the overall documentation precision.
Co-authored-by: Diogo Capela <d.capela@wearin.tech>
### BREAKING CHANGE
This changes the behavior of the default image `loader` so that
[`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#as_a_response_header_for_the_main_body)
header is now `attachment` for added protection since the API can serve
arbitrary remote images.
The new default value, `attachment`, forces the browser to download the
image when visiting directly. This is particularly important when
`dangerouslyAllowSVG` is true. Most users will not notice the change
since visiting pages won't behave any differently, only visiting images
directly.
Users can switch back to the old behavior by configuring `inline` in
next.config.js
```js
module.exports = {
images: {
contentDispositionType: 'inline',
},
}
In the authentication section, React's "Server Actions" are mentioned
and linked to server-components. I think that's wrong and the link was
intended to go to the "Server Actions and Mutations" page. This fixes
the issue.
Co-authored-by: Sam Ko <sam@vercel.com>
Explain more details about default `metadataBase` (where `metadataBase`
is not defined) when it's on Vercel deployment
x-ref: https://github.com/vercel/next.js/pull/65089
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
We've seen too many instances of folks accidentally committing their
`.env` files that I feel it's time to make this change.
Up until now, Next.js has recommended that you use `.env.local` when
working locally to store your environment variables. Some developers do
intentionally want to commit their `.env` file without secret values to
source control. However, the ecosystem is fragmented on `.local`
support.
There are tools which require secrets values that do _not_ support
`.local` and require using `.env`. This means that it's possible to dump
your secret values into a `.env` file and commit to source control,
thinking that the defaults would have you covered.
This change updates the defaults for `create-next-app` to ignore all
`.env` files by default. If you want to commit then, you opt-in by
modifying your `.gitignore`, versus the opposite.
Related: https://x.com/complexlity/status/1755890800527892716
---------
Co-authored-by: Sam Ko <sam@vercel.com>
## Why?
Adding an `--empty` flag so we can easily create an empty Create Next
App template.
Closes NEXT-3367
---------
Co-authored-by: Ahmed Abdelbaset <A7med3bdulBaset@gmail.com>
### What
Remove the auto appending `.xml` extension to the sitemap routes when
it's a dynamic route.
### Why
Previously we were adding `.xml` to `/[...paths/]sitemap` routes, but
the bad part is when you use it to generate multiple sitemaps with
`generateSitemaps` in format like `/[...paths/]sitemap.xml/[id]`, which
doesn't look good in url format and it can be inferred as xml with
content-type. Hence we don't need to add `.xml` in the url.
Before this change it could also result into the different url between
dev and prod:
dev: `/sitemap.xml/[id]`
prod: `/sitemap/[id].xml`
Now it's going to be aligned as `/sitemap/[id]`. Users can add extension
flexiblely.
Closes NEXT-3357
This PR promotes and renames experimental configuration options related
to server bundling:
- `serverComponentsExternalPackages` -> `serverExternalPackages`
- `bundlePagesExternals` -> `bundlePagesRouterDependencies`
Existing docs for `serverComponentsExternalPackages` was changed.
New docs for `bundlePagesRouterDependencies` were added.
Closes NEXT-3332
When revalidating a page that corresponds with a dynamic path and when
using the “type” parameter, eg `revalidatePath(“/dynamic/1”, “page”)`
corresponding with `/dynamic/[id]`, the wrong cache tags would be
checked to determine if a revalidation occurred.
This is because the “derived” cache tags created for a
`/dynamic/[id]/page` are:
- /dynamic/[id]/layout
- /dynamic/[id]/page
Additionally, a tag is added for the current canonical URL, so the final
tag would be:
- /dynamic/1
Thus a fetch on `/dynamic/1` would be tagged with the following:
- /layout
- /dynamic/layout
- /dynamic/[id]/layout
- /dynamic/[id]/page
- /dynamic/1
Calling `revalidatePath(“/dynamic/1”, “page”)` would signal to
revalidate caches tagged `/dynamic/1/page` in the current logic.
However, this tag doesn’t exist given the above, so it would be a no-op
and wouldn't properly re-invoke the fetch.
This updates the docs to explicitly call out that if you are attempting
to revalidate a path that corresponds with a dynamic page, that you
should not provide a "type" argument.
Fixes#62071
Closes NEXT-3302
### What?
Fix export function name on docs/routing/layouts-and-templates
### Why?
The way it is, it will return an error to the user following the
tutorial: `Unsupported Server Component type: undefined / next js 13`
### How?
- Change `Links()` function export to `NavLinks()`
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
The import path of the context is different. Does this cause ambiguity?
I'm not sure if this is intentional by the author.
---------
Co-authored-by: Sam Ko <sam@vercel.com>
The example here only updates the pathname, but the redirect path is
determined by taking the `req.nextUrl` object and stringifying it, which
means it would return the wrong redirect location.
Closes NEXT-3260
### Improving Documentation
In the auth section, there are references to the encrypt and decrypt
functions, but no import is used in the examples. This PR adds imports
for clarifies that these functions are not built in Javascript.
### Improving Documentation
### What?
Improving Documentation
### Why?
missing import of `MetadataRoute` in one of the code examples
### How?
Add the import
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
### What?
Corrects the Bun install command (again) on [this
page](https://nextjs.org/docs/app/api-reference/create-next-app#interactive)
of the docs.
### Why?
The Bun instructions were originally created in
7e16538485 with a correct command to
create a new Next.js project with Bun: `bunx create-next-app`.
Then, it was changed to `bunx create next-app` in
2ab4a443a2, which isn't correct because
`bunx` acts like `npx` and tries to run a nonexistent package called
`create`, specifying `next-app` as its argument.
This change was reverted in a42efae49d two
weeks ago, and a PR from today (#64972) reverts that correction.
Both `bunx create-next-app` and `bun create next-app` work on my machine
as of Bun 1.0. `bunx create-next-app` is analogous to `npx
create-next-app`, and `bun create next-app` is the same as `npm create
next-app`.
| Command | Correct? | Similar NPM command | Note |
|---|---|---|---|
| `bun create next-app` | ✅ | `npm create next-app` |
My proposed change |
| `bunx create-next-app` | ✅ | `npx create-next-app` |
|
| `bunx create next-app` | ❌ | `npx create next-app` (incorrect) |
Currently listed in the Next.js docs |
| `bun create-next-app` | ❌ | `npm create-next-app` (incorrect) | |
I think this confusion is caused by having two valid ways to run
`create-next-app` with two very similar syntaxes. **It could be
beneficial to include a note explaining the two correct syntaxes** to
avoid future confusion, but for now, I have just changed `bunx` -> `bun`
to keep the command similar to `yarn` and `pnpm`.
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 #
-->
This is related to the issue I encountered at
https://github.com/vercel/next.js/issues/63492.
The same problem from the issue exists in the App router and requires
this additional configuration (otherwise, users must manually add
`isolated-vm` (https://github.com/laverdet/isolated-vm) to their
`experimental.serverComponentsExternalPackages`).
Given how popular this package is, and based on a suggestion from
@feedthejim that I add this entry, I decided to raise this PR.
### Adding a feature
- Related issues/discussions are linked using `fixes #number`: yes
- Documentation added: yes
This change allows disabling automatic `npm install`(or other supported
package managers).
Installing NextJS dependencies takes a long time and results in 0.5GB on
disk inside `node_modules`, it's not always what you want as sometimes
it's useful to delay dependency installation to a later time.
<!-- 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>
### What?
This PR fixes OpenGraph generation code with local assets in Node.js
runtime. Also adds some notes on file location.
The updated code is validated with my project on vercel.
### Why?
I tried loading a file in `public` folder(say `./public/og.png`). The
Node.js local assets example code did work locally with `next start` but
failed with error message `Error: ENOENT: no such file or directory`
when deployed to vercel.
Then I found out the trick here is the relative path. On my local
machine the CWD is the root folder so the relative path works, And it
seems the CWD is somewhat different on vercel runtime. Then I tried
using `process.cwd()` to get the CWD and construct a absolute path, this
has been validated with my project on vercel.
Also it's worthy to note where the local assets should be placed, so
that devs could be less confused.
---------
Co-authored-by: Steven <steven@ceriously.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
### What
Closes PACK-2978, requires https://github.com/vercel/turbo/pull/8005.
PR extends existing mdxRs config from accepting object as well in
addition to current boolean flag, mainly to allow to specify what kind
of markdown types will be used between gfm and commonmark.
The `params` example in the docs for `default.js` have the slot/params
in the wrong order, giving the impression that you can deeply nest
`default` slots.
This clarifies that the params received by a slot are based on the
dynamic params leading up to the segment containing the slot.
Fixes#64708
Closes NEXT-3160
The `@appsignal/nodejs` instrumentation package fails to load in Next.js
14 due to Webpack failing to bundle its Node.js native extension. Adding
it to the server components external packages list fixes this issue.
Part of https://github.com/appsignal/appsignal-nodejs/issues/1014.
### What?
Adds a Node.js example for using assets with `ImageResponse` to create
og images.
### Why?
The only examples available use `new URL` and `fetch` which does not
work when the runtime is using Node.js.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Clarify best practices for implementing authentication in Next.js,
including what Next.js and React features to use and when. With the
minimum number of tools, we'll try to teach authentication from first
principles (simple password + email), then recommend Next.js-compatible
libraries, and further resources.
**Authentication:**
- [x] Forms and Server Actions
- [x] Server-side form validation and early returns
- [x] Form errors with `useFormStatus()`
- [x] Pending states with `useFormState()`
**Session Management:**
- [x] Stateless Sessions
- [x] Database Sessions
- [x] Setting cookies on the server
- [x] `cookies()`
- [x] `sever-only`
**Authorization:**
- [x] Optimistic vs. secure checks
- [x] Middleware for optimistic checks
- [x] Performance caveats - what not to do
- [x] DAL - centralizing data requests, verifying auth state close to
the data source
- [x] `redirect()`
- [x] DTO - returning the minimum data, preventing exposure on the
client
- [x] Recommendations for:
- [x] Server Components
- [x] Partial rendering and `layout` caveats
- [x] Server Actions
- [x] Route Handlers
DX Content: ["What is the right way to do
authentication?"](https://www.notion.so/vercel/00b2a5121a264939a5d4d10f76b36954?v=cac009672f9d411f900f41a0c3971702&p=2a80e8d450f54ea58da5cf8b42c15ac1&pm=s).
Test Example: https://github.com/vercel-labs/app-router-auth/pull/1
This is how I currently visualize it, this diagram is not meant for
users, but to help clarify our current understanding. What am I missing?
---------
Co-authored-by: Michael Novotny <manovotny@gmail.com>
Co-authored-by: Anthony Shew <anthonyshew@gmail.com>
Co-authored-by: Lee Robinson <me@leerob.io>
### 🤔 What's in there?
We've deprecated config's `analyticsId` in 14.1.1 [almost 3 months
ago](https://github.com/vercel/next.js/releases/tag/v14.1.1-canary.2).
Users can opt in fot `@vercel/speed-insights`, or use
`useReportWebVitals` to report to any provider they'd like.
This PR:
- removes `analyticsId` key from configuration
- stops setting `__NEXT_PUBLIC_ANALYTICS_ID` env variable when the key
was present
- stops injecting `performance-relayer` file, when the variable is set
- cleans up related test code.
`fetchCache` is a more fine-grained segment level cache-control
configuration that most people shouldn't have to use. Current semantics
of `dynamic = "force-dynamic"` will still treat the fetch as cacheable
unless explicitly overriding it in the fetch, or setting a segment level
`fetchCache`.
The `dynamic` cache configuration should be seen as a "top-level"
configuration, while more fine-grained controls should inherit logical
defaults from the top-level. Otherwise this forces people to opt-into
the `fetchCache` configuration, or manually override each `fetch` call,
which isn't what you'd expect when forcing a segment to be dynamic.
This will default to not attempting to cache the fetch when
`force-dynamic` is used. As a result, I had to update one of the
`app-static` tests to use `revalidate: 0` rather than `force-dynamic`,
as the revalidate behavior is slightly different in that it won't modify
the revalidation time on a fetch if it's non-zero.
Closes NEXT-2067
## Why?
When you do, →
```
const router = useRouter()
console.log('[test] router =', router.query.slug)
```
the value of `router.query.slug` should be undefined in this instance.
(screenshot from current docs)
it should be `slug: undefined`.
### Improving Documentation
mistake in the docs.
action should not be apply on the button.
only formAction or onClick is allow.
---------
Co-authored-by: Sam Ko <sam@vercel.com>
