Unstable Cache has always had a very lacking documentation page, even
though it adding its own new feature ``key parts`` . Its a normal
occurrence for us in the NextJS Discord to see new people and more
advanced users question what is the use of key parts, since the example
in the docs. was very lacking.
I have made a few changes, like adding a much more functional example
which showcases all the features of unstable cache, and also a small
difference section between tags and key parts.
---------
Co-authored-by: Sam Ko <sam@vercel.com>
## Why?
Add clarification that you need the experimental config:
```
module.exports = withMDX({
experimental: {
mdxRs: true,
},
})
```
when using [Turbopack](https://nextjs.org/docs/architecture/turbopack).
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
…d not in another place.
"create-next-app" in apostrophe was mentioned twice but one with link
and second without link which didn't sync together for me. So, I added
the same link to the second one, maybe I am wrong.
<!-- 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: Jiwon Choi <devjiwonchoi@gmail.com>
### What?
I replaced `let` with `const` for `useState`.
### Why?
Since in these examples, it doesn't need to be a `let`, as it doesn't do
any reassignment.
add (Experimental) to title for `unstable_rethrow` to match all other
`unstable_` functions
### Fixing a bug
- Related issues linked using `fixes #66966`
<img width="1287" alt="image"
src="https://github.com/vercel/next.js/assets/147033096/5a790b63-30c9-4605-b0e8-73899afb8e59">
## For Maintainers
`unstable_rethrow` has a different title scheme compared to all other
`unstable_` functions this is just a quick fix for this since it was
bugging me.
Closes NEXT-66966
Fixes#66966
---------
Co-authored-by: Sam Ko <sam@vercel.com>
### What?
This PR adds [Lingui](https://lingui.dev) to the list of i18n resources
on the
[Internationalization](https://nextjs.org/docs/app/building-your-application/routing/internationalization#resources)
page for the App Router.
### Why?
Recently, Lingui got some great improvements regarding RSC support. We
also have a new separate article [Lingui with React Server
Components](https://lingui.dev/tutorials/react-rsc) and sample projects
that show how to use Lingui for i18n in Next.js project with App Router
(by @vonovak).
So I think it would be great to add Lingui to this list.
### How?
Add a new list item.
Co-authored-by: Sam Ko <sam@vercel.com>
Fix: Correct URL generation in sitemap to use product.id
- Updated sitemap function to correctly use product.id for URL
generation instead of id.
- Ensured each product's URL is accurately reflected in the sitemap
output.
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.