This PR stabilizes the previously introduced experimental config options
for providing a custom cache handler (for both ISR as well as the Data
Cache) and for disabling or configuring the in-memory cache size. The
example usage would be as follows:
```js
// next.config.js
module.exports = {
cacheHandler: require.resolve('./cache-handler.js'),
cacheMaxMemorySize: 0 // disable default in-memory caching
}
```
This PR also updates the documentation to better reflect how to use the
custom cache handler when self-hosting. Further information will be
added in a following PR that also includes a full example of a custom
cache handler that implements `revalidateTag` as well as passing in
custom cache tags. The API reference docs have been updated here, as
well as a version history added.
I also noticed that we currently have two duplicated versions of the ISR
docs in the Pages Router docs: both for rendering and for data fetching.
Data Fetching is the correct location for this page. There were no other
references to the rendering version in the docs, so that must have been
an accident. I'll need to a get a redirect going for that regardless.
Tests have been updated for `cacheHandler` and I added a new test for
`cacheMaxMemorySize`.
---------
Co-authored-by: Jiachi Liu <inbox@huozhi.im>
Based on feedback from https://github.com/vercel/next.js/issues/47793, I
made some improvements around the geolocation docs. Specifically around
`request.ip`, `request.geo`, and how to access these values. I noticed
there was a bit of a divergence, as some of the `NextRequest` and
`NextResponse` docs were split out for the App Router section, but not
all.
This PR finishes that swing by removing the previous catch-all for
`next/server` in the Pages Router docs and splits them into individual
docs pages.
Wrote a lil' thread about this:
https://twitter.com/leeerob/status/1736543599339172121
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
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
- [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>
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>
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`.
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.
```
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.
[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`.
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>
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>
