The _requirement_ to export a `generateStaticParams` to get static cache
behavior _after_ build time was _really_ surprising behavior for me, and
I think others:
* https://github.com/vercel/next.js/issues/62195#issuecomment-1952091312
*
https://github.com/vercel/next.js/discussions/57961#discussioncomment-8491488
Potentially this is a bug, and not something that should be fixed with
documentation?
I don't understand next.js caching enough to make that determination, so
instead I'm proposing these changes to docs which might be encountered
by folks who are surprised by this cache behavior.
One point in favor of this being a bug: The CLI reports that a route is
`SSG` enabled in the build output, but doesn't actually cache post-build
page renders if this export is missing.
@awinogrodzki made a demo repo showing this behavior, as described
[here](https://github.com/vercel/next.js/discussions/57961#discussioncomment-7468144).
---------
Co-authored-by: Delba de Oliveira <delbabrown@gmail.com>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: samcx <sam@vercel.com>
### What
Optimizing the static generation for dynamic metadata routes
If you're not using `generateSitemaps()` or `generateSitemaps()`, you
don't need to change any file conventions.
If you're using multi sitemap routes, make sure the returned `id`
properties from `generateSitemaps()` don't need to contain `.xml`, since
we'll always append one for you.
Analyzing the exports of metadata routes and determine if we need to
make them as dynamic routes.
### Why
Previously, users are struggling with the multi routes of sitemap or
images.
For sitemap, the `.xml` extension in url doesn't get appended
consistently to the multi sitemap route between dev and prod.
For image routes, the generated image routes are always dynamic routes
which cannot get static optimized.
The reason is that we need to always generate a catch-all route (such as
`/icon/[[...id]]` to handle both single route case (e.g. without
`generateImageMetadata`, representing url `/icon`) or multi route (e.g.
with `generateImageMetadata`, representing url `/icon/[id]`), only
catch-all routes can do it. This approach fail the static optimization
and make mapping url pretty difficult as parsing the file to check the
module exports has to be done before it.
#### Benifits
For image routes urls, this approach could help on static generation
such as single `/opengraph-image` route can be treated as static, and
then it can get static optimized if possible.
**Before**: `/opengraph-image/[[...id]]` cannot be optimized
**After**: single route `/opengraph-image` and multi-route
`/opengraph-image/[id]` are both possible to be statically optimized
For sitemap, since we removed appending `.xml` for dynamic routes, it’s
hard for users to have `/sitemap.xml` url with dynamic route convention
`sitemap.js` . But users desire smooth migration and flexibility.
**Before**: In v15 rc we removed the `.xml` appending that `sitemap.js`
will generate url `/sitemap` makes users hard to migrate, as users need
to re-submit the new sitemap url.
**After**: Now we'll consistently generate the `.xml`. Single route will
become `/sitemap.xml`, and multi route will become `/sitemap/[id].xml`.
It's still better than v15 as the urls generation is consistent, no
difference between dev and prod.
Here's the url generation comparsion
#### Before
All the routes are dynamic which cannot be optimized, we only had a
hacky optimization for prodution build multi-routes sitemap routes
| | only default export | `export generateImageMetadata()` | `export
generateSitemaps()` |
| -- | -- | -- | -- |
| opengraph-image.js | /opengraph-image/[[...id]] |
/opengraph-image[[...id]]/ | /opengraph-image/[[...id]] |
| sitemap.js | /sitemap/[[...id]] | /sitemap/[[...id]] | dev:
`/sitemap/[[...id]]` prod: `/sitemap/[id]` |
#### After
Most of the single route will are to get statically optimized now, and
the multi-routes sitemap are able to get SSG now
| | only default export | `export generateImageMetadata()` | `export
generateSitemaps()` |
| -- | -- | -- | -- |
| opengraph-image.js | /opengraph-image | /opengraph-image/[id] | - |
| sitemap.js | /sitemap.xml | - | /sitemap/[id].xml |
Next.js will have less overhead of mapping urls, we can easily multiply
the urls generation simply based on file conventions.
x-ref: feedback from #65507Closes#66232
### Why?
Importing `tailwind/tailwind.css` is not possible right now with
turbopack, and there's no reason it needs to be marked as external.
### How?
Closes PACK-3013
Fixes#64837
Using `overflow: hidden` on the image's parent element is not necessary,
as the image is already set to be the same dimensions as its parent with
no overflow, and `object-fit` only changes the image aspect ratio & crop
within those dimensions.
Co-authored-by: Steven <steven@ceriously.com>
### What?
Adds a videos example to the `openGraph` object in `metadata`.
### Why?
I came to the docs looking for `openGraph` video info and luckily
checked in the actual type definitions to find it was there and easy to
add. Figured some others would come looking for it as well and would be
good to have a quick example in the docs.
---------
Co-authored-by: Sam Ko <sam@vercel.com>
One-word 'checkout' is a noun or adjective that refers to the act of
taking items out of a store after paying for them. 2. Two-words 'check
out' is a verb that refers to request someone to look at something.
Corrected the spelling of "checkout" to "check out" in the documentation
to improve readability and accuracy. This change ensures proper usage of
the phrase when referring to the installation guide.
<!-- 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>
In the discord server, people were confused whether maxAge accepts in
second or millisecond. It would be worth specifying it
---------
Co-authored-by: Sam Ko <sam@vercel.com>
### What
Removing the `/[...catchall]/<metadata image convention>.js` case from
docs
### Why
Since og image and icon routes are using catch-all routes to handle the
both single or multiple routes. For instance:
`app/opengraph-image.js` can possibly generate two cases:
- single route: `/opengraph-image`
- multi routes with `generateImageMetadata()`: `/opengraph-image/[id]`
We're not able to detect if there's `generateImageMetadata` defined in
the file before mapping the routes, and decided to create the different
routes to either `/opengraph-image` or `/opengraph-image/[id]`. That's
why we're using a catch-all routes to handle them rn.
Related #48106
Related #57349
### What?
This fixes the "Migrating from Create React App" guide and add some
minor improvements
### Why?
The existing guide was broken due to `next start` not working anymore
when using `output: 'export'` and because the TypeScript configuration
was outdated.
### How?
I've validated the guide by going through each steps on [this
PR](https://github.com/IGassmann/cra-to-nextjs/pull/1).
---------
Co-authored-by: Lee Robinson <me@leerob.io>
### Why?
The current wording leaves room for questions/misinterpretations like:
- What does "use `src/`" mean? Does this affect my build, like compile
`src/*.ts` to `lib/*.js`?
- Oh, I can customize import aliases to use @ for project root instead
of doing relative everywhere? I'll choose Yes!
I think the proposed wording clarifies ^
---------
Co-authored-by: Sam Ko <sam@vercel.com>
Alternative to https://github.com/vercel/next.js/pull/65867 this
stabilizes our `swrDelta` config that allows customizing the
`stale-while-revalidate` period that is included in the `Cache-Control`
header for ISR enabled routes.
This is not a breaking change itself as no default value is provided as
is the case already.
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>
