Merge branch 'canary' into dynamic-suspense-without-ssr

docs/advanced-features/ci-build-caching.md

@@ -0,0 +1,129 @@
+---
+description: Learn how to configure CI to cache Next.js builds
+---
+
+# Continuous Integration (CI) Build Caching
+
+To improve build performance, Next.js saves a cache to `.next/cache` that is shared between builds.
+
+To take advantage of this cache in Continuous Integration (CI) environments, your CI workflow will need to be configured to correctly persist the cache between builds.
+
+> If your CI is not configured to persist `.next/cache` between builds, you may see a [No Cache Detected](https://nextjs.org/docs/messages/no-cache) error.
+
+Here are some example cache configurations for common CI providers:
+
+## Vercel
+
+Next.js caching is automatically configured for you. There's no action required on your part.
+
+## CircleCI
+
+Edit your `save_cache` step in `.circleci/config.yml` to include `.next/cache`:
+
+```yaml
+steps:
+  - save_cache:
+      key: dependency-cache-{{ checksum "yarn.lock" }}
+      paths:
+        - ./node_modules
+        - ./.next/cache
+```
+
+If you do not have a `save_cache` key, please follow CircleCI's [documentation on setting up build caching](https://circleci.com/docs/2.0/caching/).
+
+## Travis CI
+
+Add or merge the following into your `.travis.yml`:
+
+```yaml
+cache:
+  directories:
+    - $HOME/.cache/yarn
+    - node_modules
+    - .next/cache
+```
+
+## GitLab CI
+
+Add or merge the following into your `.gitlab-ci.yml`:
+
+```yaml
+cache:
+  key: ${CI_COMMIT_REF_SLUG}
+  paths:
+    - node_modules/
+    - .next/cache/
+```
+
+## Netlify CI
+
+Use [Netlify Plugins](https://www.netlify.com/products/build/plugins/) with [`@netlify/plugin-nextjs`](https://www.npmjs.com/package/@netlify/plugin-nextjs).
+
+## AWS CodeBuild
+
+Add (or merge in) the following to your `buildspec.yml`:
+
+```yaml
+cache:
+  paths:
+    - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i`
+    - '.next/cache/**/*' # Cache Next.js for faster application rebuilds
+```
+
+## GitHub Actions
+
+Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file:
+
+```yaml
+uses: actions/cache@v2
+with:
+  # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node
+  path: |
+    ~/.npm
+    ${{ github.workspace }}/.next/cache
+  # Generate a new cache whenever packages or source files change.
+  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+  # If source files changed but packages didn't, rebuild from a prior cache.
+  restore-keys: |
+    ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
+```
+
+## Bitbucket Pipelines
+
+Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`):
+
+```yaml
+definitions:
+  caches:
+    nextcache: .next/cache
+```
+
+Then reference it in the `caches` section of your pipeline's `step`:
+
+```yaml
+- step:
+    name: your_step_name
+    caches:
+      - node
+      - nextcache
+```
+
+## Heroku
+
+Using Heroku's [custom cache](https://devcenter.heroku.com/articles/nodejs-support#custom-caching), add a `cacheDirectories` array in your top-level package.json:
+
+```javascript
+"cacheDirectories": [".next/cache"]
+```
+
+## Azure Pipelines
+
+Using Azure Pipelines' [Cache task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/cache), add the following task to your pipeline yaml file somewhere prior to the task that executes `next build`:
+
+```yaml
+- task: Cache@2
+  displayName: 'Cache .next/cache'
+  inputs:
+    key: next | $(Agent.OS) | yarn.lock
+    path: '$(System.DefaultWorkingDirectory)/.next/cache'
+```

docs/advanced-features/react-18/switchable-runtime.md

@@ -2,6 +2,8 @@
 
 By default, Next.js uses Node.js as the runtime for page rendering, including pre-rendering and server-side rendering.
 
+> Note: `runtime` option only effects pages but not middleware
+
 If you have [React 18](/docs/advanced-features/react-18/overview) installed, there is a new experimental feature that lets you switch the page runtime between Node.js and the [Edge Runtime](/docs/api-reference/edge-runtime). Changing the runtime affects [SSR streaming](/docs/advanced-features/react-18/streaming) and [Server Components](/docs/advanced-features/react-18/server-components) features, as well.
 
 ## Global Runtime Option

docs/advanced-features/source-maps.md

@@ -4,7 +4,9 @@ description: Enables browser source map generation during the production build.
 
 # Source Maps
 
-Source Maps are enabled by default during development. During production builds, they are disabled as generating source maps can significantly increase build times and memory usage while being generated.
+Source Maps are enabled by default during development. During production builds, they are disabled to prevent you leaking your source on the client, unless you specifically opt in with the configuration flag.
+
+## Configuration flag
 
 Next.js provides a configuration flag you can use to enable browser source map generation during the production build:
 

docs/api-reference/next.config.js/custom-webpack-config.md

@@ -4,6 +4,8 @@ description: Extend the default webpack config added by Next.js.
 
 # Custom Webpack Config
 
+> Note: changes to webpack config are not covered by semver so proceed at your own risk
+
 Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
 
 - [CSS imports](/docs/basic-features/built-in-css-support.md#adding-a-global-stylesheet)
@@ -22,7 +24,10 @@ In order to extend our usage of `webpack`, you can define a function that extend
 
 ```js
 module.exports = {
-  webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
+  webpack: (
+    config,
+    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
+  ) => {
     // Important: return the modified config
     return config
   },
@@ -36,7 +41,7 @@ The second argument to the `webpack` function is an object with the following pr
 - `buildId`: `String` - The build id, used as a unique identifier between builds
 - `dev`: `Boolean` - Indicates if the compilation will be done in development
 - `isServer`: `Boolean` - It's `true` for server-side compilation, and `false` for client-side compilation
-- `nextRuntime`: `String` - The target runtime for server-side compilation; either `"edge"` or `"nodejs"`
+- `nextRuntime`: `String | undefined` - The target runtime for server-side compilation; either `"edge"` or `"nodejs"`, it's `undefined` for client-side compilation.
 - `defaultLoaders`: `Object` - Default loaders used internally by Next.js:
   - `babel`: `Object` - Default `babel-loader` configuration
 
@@ -64,6 +69,10 @@ module.exports = {
 }
 ```
 
+#### `nextRuntime`
+
+Notice that `isServer` is `true` when `nextRuntime` is `"edge"` or `"nodejs"`, nextRuntime "`edge`" is currently for middleware and server components in edge runtime only.
+
 ## Related
 
 <div class="card">

docs/api-reference/next.config.js/runtime-configuration.md

@@ -26,7 +26,7 @@ Place any server-only runtime config under `serverRuntimeConfig`.
 
 Anything accessible to both client and server-side code should be under `publicRuntimeConfig`.
 
-> A page that relies on `publicRuntimeConfig` **must** use `getInitialProps` to opt-out of [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md). Runtime configuration won't be available to any page (or component in a page) without `getInitialProps`.
+> A page that relies on `publicRuntimeConfig` **must** use `getInitialProps` or `getServerSideProps` or your application must have a [Custom App](/docs/advanced-features/custom-app.md) with `getInitialProps` to opt-out of [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md). Runtime configuration won't be available to any page (or component in a page) without being server-side rendered.
 
 To get access to the runtime configs in your app use `next/config`, like so:
 

docs/api-reference/next/router.md

@@ -466,7 +466,7 @@ export default function MyApp({ Component, pageProps }) {
 
 ## Potential ESLint errors
 
-Certain methods accessible on the `router` object return a Promise. If you have the ESLint rule, [no-floating-promises](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/no-floating-promises.md) enabled, consider disabling it either globally, or for the affected line.
+Certain methods accessible on the `router` object return a Promise. If you have the ESLint rule, [no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises) enabled, consider disabling it either globally, or for the affected line.
 
 If your application needs this rule, you should either `void` the promise – or use an `async` function, `await` the Promise, then void the function call. **This is not applicable when the method is called from inside an `onClick` handler**.
 

docs/api-reference/next/streaming.md

@@ -6,54 +6,6 @@ description: Streaming related APIs to build Next.js apps in streaming SSR or wi
 
 The experimental `next/streaming` module provides streaming related APIs to port the existing functionality of Next.js apps to streaming scenarios and facilitate the usage of React Server Components.
 
-## unstable_useWebVitalsReport
-
-Next.js provides an `_app` component-level function, [`reportWebVitals`](docs/advanced-features/measuring-performance), for tracking performance metrics. With Server Components, you may have a pure server-side custom `_app` component (which doesn't run client effects) so the existing API won't work.
-
-With the new `unstable_useWebVitalsReport` API, you're able to track [Core Web Vitals](https://nextjs.org/learn/seo/web-performance) in client components:
-
-```jsx
-// pages/_app.js
-import { unstable_useWebVitalsReport } from 'next/streaming'
-
-export default function Home() {
-  unstable_useWebVitalsReport((data) => {
-    console.log(data)
-  })
-
-  return <div>Home Page</div>
-}
-```
-
-This method could also be used to replace statically exported `reportWebVitals` functions in your existing `_app`:
-
-```jsx
-// pages/_app.server.js
-import Layout from '../components/layout.client.js'
-
-export default function App({ children }) {
-  return <Layout>{children}</Layout>
-}
-```
-
-```jsx
-// components/layout.client.js
-import { unstable_useWebVitalsReport } from 'next/streaming'
-
-export default function Layout() {
-  unstable_useWebVitalsReport((data) => {
-    console.log(data)
-  })
-
-  return (
-    <div className="container">
-      <h1>Hello</h1>
-      <div className="main">{children}</div>
-    </div>
-  )
-}
-```
-
 ## unstable_useRefreshRoot
 
 Since Server Components are rendered on the server-side, in some cases you might need to partially refresh content from the server.

docs/api-routes/api-middlewares.md

@@ -165,9 +165,8 @@ export const setCookie = (
   const stringValue =
     typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value)
 
-  if ('maxAge' in options) {
-    options.expires = new Date(Date.now() + options.maxAge)
-    options.maxAge /= 1000
+  if (typeof options.maxAge === 'number') {
+    options.expires = new Date(Date.now() + options.maxAge * 1000)
   }
 
   res.setHeader('Set-Cookie', serialize(name, stringValue, options))

docs/basic-features/built-in-css-support.md

@@ -189,10 +189,10 @@ For example, using the exported `primaryColor` Sass variable:
 
 ```scss
 /* variables.module.scss */
-$primary-color: #64FF00
+$primary-color: #64ff00;
 
 :export {
-  primaryColor: $primary-color
+  primaryColor: $primary-color;
 }
 ```
 

docs/deployment.md

@@ -98,6 +98,29 @@ Next.js will automatically load the latest version of your application in the ba
 
 **Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version.
 
+## Manual Graceful shutdowns
+
+Sometimes you might want to run some cleanup code on process signals like `SIGTERM` or `SIGINT`.
+
+You can do that by setting the env variable `NEXT_MANUAL_SIG_HANDLE` to `true` and then register a handler for that signal inside your `_document.js` file.
+
+```js
+// pages/_document.js
+
+if (process.env.NEXT_MANUAL_SIG_HANDLE) {
+  // this should be added in your custom _document
+  process.on('SIGTERM', () => {
+    console.log('Received SIGTERM: ', 'cleaning up')
+    process.exit(0)
+  })
+
+  process.on('SIGINT', () => {
+    console.log('Received SIGINT: ', 'cleaning up')
+    process.exit(0)
+  })
+}
+```
+
 ## Related
 
 For more information on what to do next, we recommend the following sections:

docs/manifest.json

@@ -258,6 +258,10 @@
               "title": "`src` Directory",
               "path": "/docs/advanced-features/src-directory.md"
             },
+            {
+              "title": "CI Build Caching",
+              "path": "/docs/advanced-features/ci-build-caching.md"
+            },
             {
               "title": "Multi Zones",
               "path": "/docs/advanced-features/multi-zones.md"

errors/manifest.json

@@ -638,14 +638,6 @@
           "title": "opening-an-issue",
           "path": "/errors/opening-an-issue.md"
         },
-        {
-          "title": "multiple-flush-effects",
-          "path": "/errors/multiple-flush-effects.md"
-        },
-        {
-          "title": "client-flush-effects",
-          "path": "/errors/client-flush-effects.md"
-        },
         {
           "title": "import-next",
           "path": "/errors/import-next.md"