Merge branch 'canary' into record/new-features

docs/advanced-features/i18n-routing.md

@@ -137,7 +137,7 @@ You can access the locale information via the Next.js router. For example, using
 
 When [pre-rendering](/docs/basic-features/pages#static-generation-recommended) pages with `getStaticProps` or `getServerSideProps`, the locale information is provided in [the context](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) provided to the function.
 
-When leveraging `getStaticPaths`, the supported locales are provided in the context parameter of the function under `locales`.
+When leveraging `getStaticPaths`, the configured locales are provided in the context parameter of the function under `locales` and the configured defaultLocale under `defaultLocale`.
 
 ## Transition between locales
 

docs/advanced-features/module-path-aliases.md

@@ -4,6 +4,13 @@ description: Configure module path aliases that allow you to remap certain impor
 
 # Absolute Imports and Module path aliases
 
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-absolute-imports">Absolute Imports</a></li>
+  </ul>
+</details>
+
 Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4).
 
 > Note: `jsconfig.json` can be used when you don't use TypeScript

docs/advanced-features/multi-zones.md

@@ -33,8 +33,8 @@ For [Vercel](https://vercel.com/), you can use a single `vercel.json` to deploy
 {
   "version": 2,
   "builds": [
-    { "src": "blog/package.json", "use": "@now/next" },
-    { "src": "home/package.json", "use": "@now/next" }
+    { "src": "blog/package.json", "use": "@vercel/next" },
+    { "src": "home/package.json", "use": "@vercel/next" }
   ],
   "routes": [
     { "src": "/blog/_next(.*)", "dest": "blog/_next$1" },

docs/api-reference/next/image.md

@@ -0,0 +1,58 @@
+---
+description: Enable Image Optimization with the built-in Image component.
+---
+
+# next/image
+
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
+  </ul>
+</details>
+
+> Before moving forward, we recommend you to read [Image Optimization](/docs/basic-features/image-optimization.md) first.
+
+Image Optimization can be enabled via the `Image` component exported by `next/image`.
+
+For an example, consider a project with the following files:
+
+- `pages/index.js`
+- `public/me.png`
+
+We can serve an optimized image like so:
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+  return (
+    <>
+      <h1>My Homepage</h1>
+      <Image
+        src="/me.png"
+        alt="Picture of the author"
+        width={500}
+        height={500}
+      />
+      <p>Welcome to my homepage!</p>
+    </>
+  )
+}
+
+export default Home
+```
+
+`Image` accepts the following props:
+
+- `src` - The path or URL to the source image. This is required.
+- `width` - The intrinsic width of the source image in pixels. Must be an integer without a unit. Required unless `unsized` is true.
+- `height` - The intrinsic height of the source image, in pixels. Must be an integer without a unit. Required unless `unsized` is true.
+- `sizes` - Defines what proportion of the screen you expect the image to take up. Recommended, as it helps serve the correct sized image to each device. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
+- `quality` - The quality of the optimized image, an integer between 1 and 100 where 100 is the best quality. Default 75.
+- `loading` - The loading behavior. When `lazy`, defer loading the image until it reaches a calculated distance from the viewport. When `eager`, load the image immediately. Default `lazy`. [More info](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)
+- `priority` - When true, the image will be considered high priority and [preload](https://web.dev/preload-responsive-images/).
+- `unoptimized` - When true, the source image will be served as-is instead of resizing and changing quality.
+- `unsized` - When true, the `width` and `height` requirement can by bypassed. Should _not_ be used with above-the-fold images. Should _not_ be used with `priority`.
+
+All other properties on the `<Image>` component will be passed to the underlying `<img>` element.

docs/basic-features/data-fetching.md

@@ -56,6 +56,7 @@ The `context` parameter is an object containing the following keys:
 - `previewData` contains the preview data set by `setPreviewData`. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 - `locale` contains the active locale (if enabled).
 - `locales` contains all supported locales (if enabled).
+- `defaultLocale` contains the configured default locale (if enabled).
 
 `getStaticProps` should return an object with:
 
@@ -547,6 +548,9 @@ The `context` parameter is an object containing the following keys:
 - `preview`: `preview` is `true` if the page is in the preview mode and `false` otherwise. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 - `previewData`: The preview data set by `setPreviewData`. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 - `resolvedUrl`: A normalized version of the request URL that strips the `_next/data` prefix for client transitions and includes original query values.
+- `locale` contains the active locale (if enabled).
+- `locales` contains all supported locales (if enabled).
+- `defaultLocale` contains the configured default locale (if enabled).
 
 > **Note**: You can import modules in top-level scope for use in `getServerSideProps`.
 > Imports used in `getServerSideProps` will not be bundled for the client-side.

docs/basic-features/image-optimization.md

@@ -0,0 +1,120 @@
+---
+description: Next.js supports built-in image optimization, as well as third party loaders for Imgix, Cloudinary, and more! Learn more here.
+---
+
+# Image Component and Image Optimization
+
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/image-component">Image Component</a></li>
+  </ul>
+</details>
+
+Since version **10.0.0** Next.js has a built-in Image Component and Automatic Image Optimization.
+
+The Next.js Image Component (`next/image`) is an extension of the HTML `<img>` element, evolved for the modern web.
+
+The Automatic Image Optimization allows for resizing, optimizing, and serving images in modern formats like [WebP](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types). This avoids shipping large images to devices with a smaller viewport.
+
+## Image Component
+
+To add an image to your application, import the [`next/image`](/docs/api-reference/next/image.md) component:
+
+```jsx
+import Image from 'next/image'
+
+function Home() {
+  return (
+    <>
+      <h1>My Homepage</h1>
+      <Image
+        src="/me.png"
+        alt="Picture of the author"
+        width={500}
+        height={500}
+      />
+      <p>Welcome to my homepage!</p>
+    </>
+  )
+}
+
+export default Home
+```
+
+- `width` and `height` are required to prevent [Cumulative Layout Shift](https://web.dev/cls/), a [Core Web Vital](https://web.dev/vitals/) that Google is going to [use in their search ranking](https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html)
+- `width` and `height` are automatically responsive, unlike the HTML `<img>` element
+- See [`next/image`](/docs/api-reference/next/image.md) for list of available props.
+
+## Configuration
+
+You can configure Image Optimization by using the `images` property in `next.config.js`.
+
+### Device Sizes
+
+You can specify a list of device width breakpoints using the `deviceSizes` property. Since images maintain their aspect ratio using the `width` and `height` attributes of the source image, there is no need to specify height in `next.config.js` – only the width. These values will be used by the browser to determine which size image should load.
+
+```js
+module.exports = {
+  images: {
+    deviceSizes: [320, 420, 768, 1024, 1200],
+  },
+}
+```
+
+### Image Sizes
+
+You can specify a list of exact image widths using the `imageSizes` property. These widths should be different than the widths defined in `deviceSizes`. The purpose is for images that don't scale with the browser window, such as icons, badges, or profile images. If the `width` property of a [`next/image`](/docs/api-reference/next/image.md) component matches a value in `imageSizes`, the image will be rendered at that exact width.
+
+```js
+module.exports = {
+  images: {
+    imageSizes: [16, 32, 64],
+  },
+}
+```
+
+### Domains
+
+To enable Image Optimization for images hosted on an external website, use an absolute url for the Image `src` and specify which
+`domains` are allowed to be optimized. This is needed to ensure that external urls can't be abused.
+
+```js
+module.exports = {
+  images: {
+    domains: ['example.com'],
+  },
+}
+```
+
+### Loader
+
+If you want to use a cloud image provider to optimize images instead of using the Next.js' built-in image optimization, you can configure the loader and path prefix. This allows you to use relative urls for the Image `src` and automatically generate the correct absolute url for your provider.
+
+```js
+module.exports = {
+  images: {
+    loader: 'imgix',
+    path: 'https://example.com/myaccount/',
+  },
+}
+```
+
+The following Image Optimization cloud providers are supported:
+
+- When using `next start` or a custom server image optimization works automatically.
+- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel
+- [Imgix](https://www.imgix.com): `loader: 'imgix'`
+- [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
+- [Akamai](https://www.akamai.com): `loader: 'akamai'`
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+  <a href="/docs/api-reference/next/image.md">
+    <b>next/image</b>
+    <small>See all available properties for the Image component</small>
+  </a>
+</div>

docs/manifest.json

@@ -21,6 +21,10 @@
               "title": "Built-in CSS Support",
               "path": "/docs/basic-features/built-in-css-support.md"
             },
+            {
+              "title": "Image Optimization",
+              "path": "/docs/basic-features/image-optimization.md"
+            },
             {
               "title": "Fast Refresh",
               "path": "/docs/basic-features/fast-refresh.md"
@@ -180,6 +184,10 @@
             {
               "title": "Codemods",
               "path": "/docs/advanced-features/codemods.md"
+            },
+            {
+              "title": "Internationalized Routing",
+              "path": "/docs/advanced-features/i18n-routing.md"
             }
           ]
         },
@@ -216,6 +224,10 @@
           "title": "next/link",
           "path": "/docs/api-reference/next/link.md"
         },
+        {
+          "title": "next/image",
+          "path": "/docs/api-reference/next/image.md"
+        },
         {
           "title": "next/head",
           "path": "/docs/api-reference/next/head.md"

examples/i18n-routing/.gitignore

@@ -0,0 +1,34 @@
+# 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
+*.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

examples/i18n-routing/README.md

@@ -0,0 +1,23 @@
+# Internationalized Routing
+
+This example shows how to create internationalized pages using Next.js and the i18n routing feature. It shows a normal page, a non-dynamic `getStaticProps` page, a dynamic `getStaticProps` page, and a `getServerSideProps` page.
+
+For further documentation on this feature see the documentation [here](https://nextjs.org/docs/advanced-features/i18n-routing)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/amp)
+
+## How to use
+
+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 i18n-routing i18n-app
+# or
+yarn create next-app --example i18n-routing i18n-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).

examples/i18n-routing/next.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  i18n: {
+    locales: ['en', 'fr', 'nl'],
+    defaultLocale: 'en',
+  },
+}

examples/i18n-routing/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "i18n-routing",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "next",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "latest",
+    "react": "^16.7.0",
+    "react-dom": "^16.7.0"
+  },
+  "license": "MIT"
+}