Merge branch 'canary' into fix-next-node-buildin-module-error-message

docs/api-reference/next/image.md

@@ -50,19 +50,19 @@ When using an external URL, you must add it to
 
 The `width` property can represent either the _rendered_ width or _original_ width in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.
 
-When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `width` property represents the _rendered_ width in pixels, so it will affect how large the image appears.
+When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"`, the `width` property represents the _rendered_ width in pixels, so it will affect how large the image appears.
 
-When using `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes`, the `width` property represents the _original_ width in pixels, so it will only affect the aspect ratio.
+When using `layout="responsive"`, `layout="fill"`, the `width` property represents the _original_ width in pixels, so it will only affect the aspect ratio.
 
 The `width` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`.
 
 ### height
 
 The `height` property can represent either the _rendered_ height or _original_ height in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.
 
-When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"` without `sizes`, the `height` property represents the _rendered_ height in pixels, so it will affect how large the image appears.
+When using `layout="intrinsic"`, `layout="fixed"`, or `layout="raw"`, the `height` property represents the _rendered_ height in pixels, so it will affect how large the image appears.
 
-When using `layout="responsive"`, `layout="fill"`, or `layout="raw"` with `sizes`, the `height` property represents the _original_ height in pixels, so it will only affect the aspect ratio.
+When using `layout="responsive"`, `layout="fill"`, the `height` property represents the _original_ height in pixels, so it will only affect the aspect ratio.
 
 The `height` property is required, except for [statically imported images](#local-images), or those with `layout="fill"`.
 
@@ -94,8 +94,7 @@ The layout behavior of the image as the viewport changes size.
   - This is usually paired with the [`objectFit`](#objectFit) property.
   - Ensure the parent element has `position: relative` in their stylesheet.
 - When `raw`[\*](#experimental-raw-layout-mode), the image will be rendered as a single image element with no wrappers, sizers or other responsive behavior.
-  - If your image styling will change the size of a `raw` image, you should include the `sizes` property for proper image serving. Otherwise your image will receive a fixed height and width.
-  - The other layout modes are optimized for performance and should cover nearly all use cases. It is recommended to try to use those modes before using `raw`.
+  - If your image styling will change the size of a `raw` image, you should include the `sizes` property for proper image serving. Otherwise your image will be requested as though it has fixed width and height.
 - [Demo background image](https://image-component.nextjs.gallery/background)
 
 ### loader
@@ -181,6 +180,8 @@ Allows [passing CSS styles](https://reactjs.org/docs/dom-elements.html#style) to
 
 Note that all `layout` modes other than `"raw"`[\*](#experimental-raw-layout-mode) apply their own styles to the image element, and these automatic styles take precedence over the `style` prop.
 
+Also keep in mind that the required `width` and `height` props can interact with your styling. If you use styling to modify an image's `width`, you must set the `height="auto"` style as well, or your image will be distorted.
+
 ### objectFit
 
 Defines how the image will fit into its parent container when using `layout="fill"`.
@@ -493,10 +494,6 @@ module.exports = {
 }
 ```
 
-> Note on CLS with `layout="raw"`:
-> It is possible to cause [layout shift](https://web.dev/cls/) with the image component in `raw` mode. If you include a `sizes` property, the image component will not pass `height` and `width` attributes to the image, to allow you to apply your own responsive sizing.
-> An [aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) style property is automatically applied to prevent layout shift, but this won't apply on [older browsers](https://caniuse.com/mdn-css_properties_aspect-ratio).
-
 ### Animated Images
 
 The default [loader](#loader) will automatically bypass Image Optimization for animated images and serve the image as-is.

docs/basic-features/data-fetching/incremental-static-regeneration.md

@@ -171,6 +171,29 @@ export async function getStaticProps() {
 }
 ```
 
+## Self-hosting ISR
+
+Incremental Static Regeneration (ISR) works on [self-hosted Next.js sites](/docs/deployment.md#self-hosting) out of the box when you use `next start`.
+
+You can use this approach when deploying to container orchestrators such as [Kubernetes](https://kubernetes.io/) or [HashiCorp Nomad](https://www.nomadproject.io/). By default, generated assets will be stored in-memory on each pod. This means that each pod will have its own copy of the static files. Stale data may be shown until that specific pod is hit by a request.
+
+To ensure consistency across all pods, you can disable in-memory caching. This will inform the Next.js server to only leverage assets generated by ISR in the file system.
+
+You can use a shared network mount in your Kubernetes pods (or similar setup) to reuse the same file-system cache between different containers. By sharing the same mount, the `.next` folder which contains the `next/image` cache will also be shared and re-used.
+
+To disable in-memory caching, set `isrMemoryCacheSize` to `0` in your `next.config.js` file:
+
+```js
+module.exports = {
+  experimental: {
+    // Defaults to 50MB
+    isrMemoryCacheSize: 0,
+  },
+}
+```
+
+> **Note:** You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
+
 ## Related
 
 For more information on what to do next, we recommend the following sections:

docs/basic-features/font-optimization.md

@@ -16,6 +16,7 @@ By default, Next.js will automatically inline font CSS at build time, eliminatin
 />
 
 // After
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
 <style data-href="https://fonts.googleapis.com/css2?family=Inter&display=optional">
   @font-face{font-family:'Inter';font-style:normal...
 </style>

examples/with-edgedb/.eslintignore

@@ -0,0 +1 @@
+dbschema/edgeql-js

examples/with-edgedb/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+.vscode
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel
+
+# query builder
+dbschema/edgeql-js

examples/with-edgedb/README.md

@@ -0,0 +1,150 @@
+# Full-stack EdgeDB + Next.js application
+
+A simple blog application built with Next.js, TypeScript, [React](https://reactjs.org/), and [EdgeDB](https://www.edgedb.com/docs) on the backend.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/with-edgedb&project-name=with-edgedb&repository-name=with-edgedb&env=EDGEDB_DSN)
+
+## How to use
+
+### Download the example project
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+
+```bash
+npx create-next-app --example with-edgedb with-edgedb-app
+# or
+yarn create next-app --example with-edgedb with-edgedb-app
+# or
+pnpm create next-app -- --example with-edgedb with-edgedb-app
+```
+
+Then `cd` into the created directory.
+
+```bash
+$ cd with-edgedb-app
+```
+
+### Install the CLI
+
+First install the EdgeDB CLI if you haven't already.
+
+```bash
+# macOS/Linux
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.edgedb.com | sh
+
+# Windows (Powershell)
+$ iwr https://ps1.edgedb.com -useb | iex
+```
+
+### Initialize the EdgeDB project
+
+Initialize the project with the following CLI command:
+
+```bash
+$ edgedb project init
+```
+
+After you follow the prompts, this command will spin up a local EdgeDB instance and apply all the migrations inside `dbschema/migrations`. Now that the project is initialized, all EdgeDB clients initialized inside the project directory will connect to this instance automatically—no need for environment variables or hard-coded configuration. ([Read more about projects here.](https://www.edgedb.com/docs/guides/projects))
+
+### Install dependencies
+
+Install npm dependencies:
+
+```bash
+$  npm install
+# or
+$  yarn
+```
+
+### Generate the query builder
+
+This project uses the EdgeQL query builder for TypeScript. This tool can express any EdgeQL query in a code-first way and infers a static return type. Generate it with the following command:
+
+```bash
+$ npx edgeql-js
+```
+
+The query builder consists of several files that are generated into the `dbschema/edgeql-js` directory. Import it like so:
+
+```ts
+import e from './dbschema/edgeql-js'
+```
+
+### Seed the database
+
+```bash
+$ npx ts-node seed.ts
+```
+
+### Start the app
+
+```bash
+$ yarn dev
+```
+
+The application should now be running on http://localhost:3000.
+
+## Notes
+
+#### packages structure
+
+- `/`: See all published posts
+- `/drafts`: See all drafts
+- `/create`: Form to create new draft
+- `/blog/:id`: See either an edit page or a published post, depending on the publish status of the post.
+
+#### API structure
+
+- `POST /api/post`: Create a new post
+  - Body: `{title: string; content: string; authorName: string}`
+- `PATCH /api/post/:id`: Update a post by `id`
+  - Body: `{title?: string; content?: string;}`
+- `PUT /api/publish/:id`: Publish a post by `id`
+- `DELETE /api/post/:id`: Delete a post by `id`
+
+## Evolving the app
+
+Evolving the application typically requires three steps:
+
+1. Update the schema in `dbschema/default.esdl`
+2. Generate a new migration with `edgedb migration create`
+3. Apply the migration with `edgedb migrate`
+4. Regenerate the query builder with `npx edgeql-js`
+5. Update the application code, as needed.
+
+## Deployment
+
+To deploy this application, deploy EdgeDB to your preferred cloud provider:
+
+- [AWS](https://www.edgedb.com/docs/guides/deployment/aws_aurora_ecs)
+- [Google Cloud](https://www.edgedb.com/docs/guides/deployment/gcp)
+- [Azure](https://www.edgedb.com/docs/guides/deployment/azure_flexibleserver)
+- [DigitalOcean](https://www.edgedb.com/docs/guides/deployment/digitalocean)
+- [Fly.io](https://www.edgedb.com/docs/guides/deployment/fly_io)
+- [Docker](https://www.edgedb.com/docs/guides/deployment/docker) (cloud-agnostic)
+
+Then:
+
+1. Find your instance's DSN (AKA connection string). The exact instructions for this depend on which cloud you are deploying to.
+
+2. Use this DSN to migrate your remote instance to the latest schema. Run this command from inside your project directory.
+
+```
+edgedb migrate --dsn <your-instance-dsn> --tls-security insecure
+```
+
+You have to disable TLS checks with `--tls-security insecure`. All EdgeDB instances use TLS by default, but configuring it is out of scope of this project.
+
+3. Deploy this app to Vercel with the button above. You'll be prompted to provide a value for `EDGEDB_DSN`, the value from the previous step.
+
+4. Open the application at the deployment URL supplied by Vercel.
+
+## Next steps
+
+- Check out the [EdgeDB docs](https://www.edgedb.com/docs)
+- Join the EdgeDB [Discord server](https://edgedb.com/p/discord)
+- Check out the code on [GitHub](https://github.com/edgedb/edgedb)

examples/with-edgedb/client.ts

@@ -0,0 +1,9 @@
+import { createClient } from 'edgedb'
+import e from './dbschema/edgeql-js'
+
+// reads value of EDGEDB_DSN automatically
+export const client = createClient({
+  // TLS configuration is beyond the scope of this example project
+  tlsSecurity: 'insecure',
+})
+export { e }

examples/with-edgedb/components/Header.tsx

@@ -0,0 +1,55 @@
+import React from 'react'
+import Link from 'next/link'
+
+const Header: React.FC = () => {
+  return (
+    <nav>
+      <div className="left">
+        <Link href="/">
+          <a>Blog</a>
+        </Link>
+        <Link href="/drafts">
+          <a>Drafts</a>
+        </Link>
+      </div>
+      <div className="right">
+        <Link href="/create">
+          <a>+ New draft</a>
+        </Link>
+      </div>
+      <style jsx>{`
+        nav {
+          display: flex;
+          padding: 2rem;
+          align-items: center;
+        }
+
+        .bold {
+          font-weight: bold;
+        }
+
+        a {
+          text-decoration: none;
+          color: #000;
+          display: inline-block;
+        }
+
+        a + a {
+          margin-left: 1rem;
+        }
+
+        .right {
+          margin-left: auto;
+        }
+
+        .right a {
+          border: 2px solid black;
+          padding: 0.5rem 1rem;
+          border-radius: 3px;
+        }
+      `}</style>
+    </nav>
+  )
+}
+
+export default Header