From 3262440873a76ecd1df1f760fec67b407acdbac6 Mon Sep 17 00:00:00 2001 From: github-actions Date: Thu, 25 Jul 2024 00:44:17 +0000 Subject: [PATCH] Sync docs from Next.js Changes: sending incremental file list 02-app/01-building-your-application/04-caching/index.mdx 02-app/01-building-your-application/05-styling/02-tailwind-css.mdx 02-app/01-building-your-application/06-optimizing/10-open-telemetry.mdx 02-app/01-building-your-application/06-optimizing/12-third-party-libraries.mdx 02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx 02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx 02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx 02-app/02-api-reference/05-next-config-js/staleTimes.mdx 03-pages/01-building-your-application/09-deploying/04-ci-build-caching.mdx sent 159,144 bytes received 1,309 bytes 320,906.00 bytes/sec total size is 1,792,414 speedup is 11.17 --- .../04-caching/index.mdx | 8 +-- .../05-styling/02-tailwind-css.mdx | 24 +++++++- .../06-optimizing/10-open-telemetry.mdx | 4 +- .../12-third-party-libraries.mdx | 14 ++--- .../11-upgrading/04-app-router-migration.mdx | 2 +- .../01-metadata/opengraph-image.mdx | 60 ++++++++++++++++++- .../01-metadata/sitemap.mdx | 10 ++-- .../05-next-config-js/staleTimes.mdx | 13 ++-- .../09-deploying/04-ci-build-caching.mdx | 2 +- 9 files changed, 105 insertions(+), 32 deletions(-) diff --git a/origin/canary/docs/02-app/01-building-your-application/04-caching/index.mdx b/origin/canary/docs/02-app/01-building-your-application/04-caching/index.mdx index aec4bbb..fa20314 100644 --- a/origin/canary/docs/02-app/01-building-your-application/04-caching/index.mdx +++ b/origin/canary/docs/02-app/01-building-your-application/04-caching/index.mdx @@ -335,13 +335,13 @@ With the Router Cache: The cache is stored in the browser's temporary memory. Two factors determine how long the router cache lasts: - **Session**: The cache persists across navigation. However, it's cleared on page refresh. -- **Automatic Invalidation Period**: The cache of layouts and loading states is automatically invalidated after a specific time. The duration depends on how the resource was [prefetched](/docs/app/api-reference/components/link#prefetch): - - **Default Prefetching** (`prefetch={null}` or unspecified): 0 seconds - - **Full Prefetching**: (`prefetch={true}` or `router.prefetch`): 5 minutes +- **Automatic Invalidation Period**: The cache of layouts and loading states is automatically invalidated after a specific time. The duration depends on how the resource was [prefetched](/docs/app/api-reference/components/link#prefetch), and if the resource was [statically generated](/docs/app/building-your-application/rendering/server-components#static-rendering-default): + - **Default Prefetching** (`prefetch={null}` or unspecified): not cached for dynamic pages, 5 minutes for static pages. + - **Full Prefetching** (`prefetch={true}` or `router.prefetch`): 5 minutes for both static & dynamic pages. While a page refresh will clear **all** cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched. -> **Good to know**: The experimental [`staleTimes`](/docs/app/api-reference/next-config-js/staleTimes) config option can be used to enable caching of page segments. +> **Good to know**: The experimental [`staleTimes`](/docs/app/api-reference/next-config-js/staleTimes) config option can be used to adjust the automatic invalidation times mentioned above. ### Invalidation diff --git a/origin/canary/docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx b/origin/canary/docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx index 41de287..bb42615 100644 --- a/origin/canary/docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx +++ b/origin/canary/docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx @@ -29,9 +29,29 @@ npx tailwindcss init -p ## Configuring Tailwind -Inside `tailwind.config.js`, add paths to the files that will use Tailwind CSS class names: +Inside your Tailwind configuration file, add paths to the files that will use Tailwind class names: -```js filename="tailwind.config.js" +```ts filename="tailwind.config.ts" switcher +import type { Config } from 'tailwindcss' + +const config: Config = { + content: [ + './app/**/*.{js,ts,jsx,tsx,mdx}', // Note the addition of the `app` directory. + './pages/**/*.{js,ts,jsx,tsx,mdx}', + './components/**/*.{js,ts,jsx,tsx,mdx}', + + // Or if using `src` directory: + './src/**/*.{js,ts,jsx,tsx,mdx}', + ], + theme: { + extend: {}, + }, + plugins: [], +} +export default config +``` + +```js filename="tailwind.config.js" switcher /** @type {import('tailwindcss').Config} */ module.exports = { content: [ diff --git a/origin/canary/docs/02-app/01-building-your-application/06-optimizing/10-open-telemetry.mdx b/origin/canary/docs/02-app/01-building-your-application/06-optimizing/10-open-telemetry.mdx index 42efc9f..55eeac6 100644 --- a/origin/canary/docs/02-app/01-building-your-application/06-optimizing/10-open-telemetry.mdx +++ b/origin/canary/docs/02-app/01-building-your-application/06-optimizing/10-open-telemetry.mdx @@ -27,10 +27,10 @@ That's why we prepared a package `@vercel/otel` that helps you get started quick ### Using `@vercel/otel` -To get started, you must install `@vercel/otel`: +To get started, install the following packages: ```bash filename="Terminal" -npm install @vercel/otel +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation ``` diff --git a/origin/canary/docs/02-app/01-building-your-application/06-optimizing/12-third-party-libraries.mdx b/origin/canary/docs/02-app/01-building-your-application/06-optimizing/12-third-party-libraries.mdx index 2003c26..bb0095a 100644 --- a/origin/canary/docs/02-app/01-building-your-application/06-optimizing/12-third-party-libraries.mdx +++ b/origin/canary/docs/02-app/01-building-your-application/06-optimizing/12-third-party-libraries.mdx @@ -168,13 +168,13 @@ different variables and events that can be passed into the function. Options to pass to the Google Tag Manager. For a full list of options, read the [Google Tag Manager docs](https://developers.google.com/tag-platform/tag-manager/datalayer). -| Name | Type | Description | -| --------------- | -------- | ------------------------------------------------------------------------------- | -| `gtmId` | Required | Your GTM container ID. Usually starts with `GTM-`. | -| `dataLayer` | Optional | Data layer array to instantiate the container with. Defaults to an empty array. | -| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. | -| `auth` | Optional | Value of authentication parameter (`gtm_auth`) for environment snippets. | -| `preview` | Optional | Value of preview parameter (`gtm_preview`) for environment snippets. | +| Name | Type | Description | +| --------------- | -------- | ------------------------------------------------------------------------ | +| `gtmId` | Required | Your GTM container ID. Usually starts with `GTM-`. | +| `dataLayer` | Optional | Data layer object to instantiate the container with. | +| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. | +| `auth` | Optional | Value of authentication parameter (`gtm_auth`) for environment snippets. | +| `preview` | Optional | Value of preview parameter (`gtm_preview`) for environment snippets. | ### Google Analytics diff --git a/origin/canary/docs/02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx b/origin/canary/docs/02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx index 3511d95..3d8c046 100644 --- a/origin/canary/docs/02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx +++ b/origin/canary/docs/02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx @@ -435,7 +435,7 @@ In `app`, you should use the three new hooks imported from `next/navigation`: [` - The new `useRouter` hook is imported from `next/navigation` and has different behavior to the `useRouter` hook in `pages` which is imported from `next/router`. - The [`useRouter` hook imported from `next/router`](/docs/pages/api-reference/functions/use-router) is not supported in the `app` directory but can continue to be used in the `pages` directory. - The new `useRouter` does not return the `pathname` string. Use the separate `usePathname` hook instead. -- The new `useRouter` does not return the `query` object. Use the separate `useSearchParams` hook instead. +- The new `useRouter` does not return the `query` object. Search parameters and dynamic route parameters are now separate. Use the `useSearchParams` and `useParams` hooks instead. - You can use `useSearchParams` and `usePathname` together to listen to page changes. See the [Router Events](/docs/app/api-reference/functions/use-router#router-events) section for more details. - These new hooks are only supported in Client Components. They cannot be used in Server Components. diff --git a/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx b/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx index 4c622b4..035716e 100644 --- a/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx +++ b/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx @@ -93,6 +93,8 @@ The easiest way to generate an image is to use the [ImageResponse](/docs/app/api ```tsx filename="app/about/opengraph-image.tsx" switcher import { ImageResponse } from 'next/og' +export const runtime = 'edge' + // Image metadata export const alt = 'About Acme' export const size = { @@ -147,6 +149,8 @@ export default async function Image() { ```jsx filename="app/about/opengraph-image.js" switcher import { ImageResponse } from 'next/og' +export const runtime = 'edge' + // Image metadata export const alt = 'About Acme' export const size = { @@ -397,13 +401,38 @@ export default async function Image({ params }) { This example uses the Edge runtime to fetch a local image on the file system and passes it as an `ArrayBuffer` to the `src` attribute of an `` element. The local asset should be placed relative to the example source file location. +```tsx filename="app/opengraph-image.tsx" switcher +import { ImageResponse } from 'next/og' + +export const runtime = 'edge' + +export default async function Image() { + const logoSrc = await fetch(new URL('./logo.png', import.meta.url)).then( + (res) => res.arrayBuffer() + ) + + return new ImageResponse( + ( +
+ +
+ ) + ) +} +``` + ```jsx filename="app/opengraph-image.js" switcher import { ImageResponse } from 'next/og' -import { readFile } from 'node:fs/promises' export const runtime = 'edge' -export async function GET() { +export default async function Image() { const logoSrc = await fetch(new URL('./logo.png', import.meta.url)).then( (res) => res.arrayBuffer() ) @@ -428,12 +457,37 @@ export async function GET() { This example uses the Node.js runtime to fetch a local image on the file system and passes it as an `ArrayBuffer` to the `src` attribute of an `` element. The local asset should be placed relative to the root of your project, rather than the location of the example source file. +```tsx filename="app/opengraph-image.tsx" switcher +import { ImageResponse } from 'next/og' +import { join } from 'node:path' +import { readFile } from 'node:fs/promises' + +export default async function Image() { + const logoData = await readFile(join(process.cwd(), 'logo.png')) + const logoSrc = Uint8Array.from(logoData).buffer + + return new ImageResponse( + ( +
+ +
+ ) + ) +} +``` + ```jsx filename="app/opengraph-image.js" switcher import { ImageResponse } from 'next/og' import { join } from 'node:path' import { readFile } from 'node:fs/promises' -export async function GET() { +export default async function Image() { const logoData = await readFile(join(process.cwd(), 'logo.png')) const logoSrc = Uint8Array.from(logoData).buffer diff --git a/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx b/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx index 54cc76a..8a10c89 100644 --- a/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx +++ b/origin/canary/docs/02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx @@ -293,8 +293,8 @@ type Sitemap = Array<{ ## Version History -| Version | Changes | -| --------- | ------------------------------------------------------------ | -| `v14.2.0` | Add localizations support. | -| `v13.4.5` | Add `changeFrequency` and `priority` attributes to sitemaps. | -| `v13.3.0` | `sitemap` introduced. | +| Version | Changes | +| ---------- | ------------------------------------------------------------ | +| `v14.2.0` | Add localizations support. | +| `v13.4.14` | Add `changeFrequency` and `priority` attributes to sitemaps. | +| `v13.3.0` | `sitemap` introduced. | diff --git a/origin/canary/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx b/origin/canary/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx index 53576eb..2327656 100644 --- a/origin/canary/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx +++ b/origin/canary/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx @@ -25,9 +25,9 @@ module.exports = nextConfig The `static` and `dynamic` properties correspond with the time period (in seconds) based on different types of [link prefetching](/docs/app/api-reference/components/link#prefetch). -- The `dynamic` property is used when the `prefetch` prop on `Link` is left unspecified or is set to `false`. +- The `dynamic` property is used when the page is neither statically generated nor fully prefetched (i.e., with prefetch={true}). - Default: 0 seconds (not cached) -- The `static` property is used when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](/docs/app/building-your-application/caching#routerprefetch). +- The `static` property is used for statically generated pages, or when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](/docs/app/building-your-application/caching#routerprefetch). - Default: 5 minutes > **Good to know:** @@ -35,13 +35,12 @@ The `static` and `dynamic` properties correspond with the time period (in second > - [Loading boundaries](/docs/app/api-reference/file-conventions/loading) are considered reusable for the `static` period defined in this configuration. > - This doesn't affect [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), **meaning shared layouts won't automatically be refetched on every navigation, only the page segment that changes.** > - This doesn't change [back/forward caching](/docs/app/building-your-application/caching#client-side-router-cache) behavior to prevent layout shift and to prevent losing the browser scroll position. -> - The different properties of this config refer to variable levels of "liveness" and are unrelated to whether the segment itself is opting into static or dynamic rendering. In other words, the current `static` default of 5 minutes suggests that data feels static by virtue of it being revalidated infrequently. You can learn more about the Client Router Cache [here](/docs/app/building-your-application/caching#client-side-router-cache). ### Version History -| Version | Changes | -| --------- | ------------------------------------------------------------------ | -| `v15.0.0` | `staleTimes` enables and configures the duration for page segments | -| `v14.2.0` | experimental `staleTimes` introduced | +| Version | Changes | +| --------- | ------------------------------------------------------ | +| `v15.0.0` | The "dynamic" staleTime default changed from 30s to 0s | +| `v14.2.0` | experimental `staleTimes` introduced | diff --git a/origin/canary/docs/03-pages/01-building-your-application/09-deploying/04-ci-build-caching.mdx b/origin/canary/docs/03-pages/01-building-your-application/09-deploying/04-ci-build-caching.mdx index ca6a154..0f65780 100644 --- a/origin/canary/docs/03-pages/01-building-your-application/09-deploying/04-ci-build-caching.mdx +++ b/origin/canary/docs/03-pages/01-building-your-application/09-deploying/04-ci-build-caching.mdx @@ -13,7 +13,7 @@ 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. +Next.js caching is automatically configured for you. There's no action required on your part. If you are using Turborepo on Vercel, [learn more here](https://vercel.com/docs/monorepos/turborepo). ## CircleCI