diff --git a/docs/01-app/01-getting-started/01-installation.mdx b/docs/01-app/01-getting-started/01-installation.mdx index 0204f6097c152..d908a77928304 100644 --- a/docs/01-app/01-getting-started/01-installation.mdx +++ b/docs/01-app/01-getting-started/01-installation.mdx @@ -214,10 +214,6 @@ You can optionally create a [`public` folder](/docs/app/building-your-applicatio Next.js comes with built-in TypeScript support. To add TypeScript to your project, rename a file to `.ts` / `.tsx`. Run `next dev`, Next.js will automatically install the necessary dependencies and add a `tsconfig.json` file with the recommended config options. -> **Good to know**: -> -> - If you already have a `jsconfig.json` file, copy the `paths` compiler option from the old `jsconfig.json` into the new `tsconfig.json` file, and delete the old `jsconfig.json` file. - ### IDE Plugin diff --git a/docs/01-app/01-getting-started/03-layouts-and-pages.mdx b/docs/01-app/01-getting-started/03-layouts-and-pages.mdx index 480039afcda69..89b1e9ad12ffb 100644 --- a/docs/01-app/01-getting-started/03-layouts-and-pages.mdx +++ b/docs/01-app/01-getting-started/03-layouts-and-pages.mdx @@ -3,6 +3,8 @@ title: How to create layouts and pages nav_title: Layouts and Pages description: Create your first pages and layouts, and link between them. related: + title: API Reference + description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/api-reference/file-conventions/layout - app/api-reference/file-conventions/page @@ -168,7 +170,7 @@ export default function Page() { } ``` -> **Good to know**: Wrapping a folder name in square brackets (e.g. `[slug]`) creates a special **dynamic route segment** used to generate multiple pages from data. This is useful for blog posts, product pages, etc. Learn more about [dynamic segments](/docs/app/building-your-application/routing/dynamic-routes). +> **Good to know**: Wrapping a folder name in square brackets (e.g. `[slug]`) creates a special [dynamic route segment](/docs/app/building-your-application/routing/dynamic-routes) used to generate multiple pages from data. This is useful for blog posts, product pages, etc. ## Nesting layouts @@ -208,7 +210,7 @@ You can use the [`` component](/docs/app/api-reference/components/link) to For example, to generate a list of blog posts, import `` from `next/link` and pass a `href` prop to the component: -```tsx filename="app/ui/post.tsx" highlight={1,6} switcher +```tsx filename="app/ui/post.tsx" highlight={1,10} switcher import Link from 'next/link' export default async function Post({ post }) { @@ -226,7 +228,7 @@ export default async function Post({ post }) { } ``` -```jsx filename="app/ui/post.js" highlight={1,6} switcher +```jsx filename="app/ui/post.js" highlight={1,10} switcher import Link from 'next/link' export default async function Post({ post }) { diff --git a/docs/01-app/01-getting-started/04-images-and-fonts.mdx b/docs/01-app/01-getting-started/04-images-and-fonts.mdx index 9715d517f2513..fca6760c3bba2 100644 --- a/docs/01-app/01-getting-started/04-images-and-fonts.mdx +++ b/docs/01-app/01-getting-started/04-images-and-fonts.mdx @@ -3,12 +3,14 @@ title: How to optimize images and fonts nav_title: Images and Fonts description: Learn how to optimize images and fonts. related: + title: API Reference + description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/api-reference/components/font - app/api-reference/components/image --- -Next.js comes with automatic image and font optimizations for better performance and user experience. This page will guide you through how to start using them. +Next.js comes with automatic image and font optimization for better performance and user experience. This page will guide you through how to start using them. ## Handling static assets @@ -27,7 +29,7 @@ You can store static files, like images and fonts, under a folder called `public The Next.js [``](/docs/app/building-your-application/optimizing/images) component extends the HTML `` element to provide: - **Size optimization:** Automatically serving correctly sized images for each device, using modern image formats like WebP and AVIF. -- **Visual stability:** Preventing [layout shift](/learn/seo/web-performance/cls) automatically when images are loading. +- **Visual stability:** Preventing [layout shift](https://web.dev/articles/cls) automatically when images are loading. - **Faster page loads:** Only loading images when they enter the viewport using native browser lazy loading, with optional blur-up placeholders. - **Asset flexibility:** Resizing images on-demand, even images stored on remote servers. @@ -91,7 +93,7 @@ export default function Page() { } ``` -Next.js will automatically determine the intrinsic [`width`](/docs/app/api-reference/components/image#width) and [`height`](/docs/app/api-reference/components/image#height) of your image based on the imported file. These values are used to determine the image ratio and prevent [Cumulative Layout Shift](https://nextjs.org/learn/seo/web-performance/cls) while your image is loading. +Next.js will automatically determine the intrinsic [`width`](/docs/app/api-reference/components/image#width) and [`height`](/docs/app/api-reference/components/image#height) of your image based on the imported file. These values are used to determine the image ratio and prevent [Cumulative Layout Shift](https://web.dev/articles/cls) while your image is loading. ### Remote images @@ -127,9 +129,9 @@ export default function Page() { } ``` -Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width), [`height`](/docs/app/api-reference/components/image#height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. The `width` and `height` attributes are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in. But `width` and `height` do _not_ determine the rendered size of the image file. +Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width), [`height`](/docs/app/api-reference/components/image#height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. The `width` and `height` attributes are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in. -Then, to safely allow images from remote servers, you need to define a list of supported URL patterns in `next.config.js`. Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket: +Then, to safely allow images from remote servers, you need to define a list of supported URL patterns in [`next.config.js`](/docs/app/api-reference/config/next-config-js). Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket: ```ts filename="next.config.js" switcher import { NextConfig } from 'next' @@ -167,17 +169,15 @@ module.exports = { } ``` -Learn more about Image Optimization in the [API Reference](/docs/app/api-reference/components/image). - ## Optimizing fonts The [`next/font`](/docs/app/api-reference/components/font) module automatically optimizes your fonts and removes external network requests for improved privacy and performance. It includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with no layout shift. -To start using `next/font`, import it from `next/font/local` or `next/font/google` (depending on whether you're using a [Google](#google-fonts) or [local](#local-fonts) font), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to. +To start using `next/font`, import it from [`next/font/local`](#local-fonts) or [`next/font/google`](#google-fonts), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to. For example: -```tsx filename="app/layout.tsx" switcher +```tsx filename="app/layout.tsx" highlight={1,3-5,9} switcher import { Geist } from 'next/font/google' const geist = Geist({ @@ -193,7 +193,7 @@ export default function Layout({ children }: { children: React.ReactNode }) { } ``` -```jsx filename="app/layout.js" switcher +```jsx filename="app/layout.js" highlight={1,3-5,9} switcher import { Geist } from 'next/font/google' const geist = Geist({ @@ -211,14 +211,14 @@ export default function Layout({ children }) { ### Google fonts -You can automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.** +You can automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment, meaning no requests are sent to Google by the browser when the user visits your site. -To start using a Google Font, import it from `next/font/google` as a function. +To start using a Google Font, import your chosen font from `next/font/google`: ```tsx filename="app/layout.tsx" switcher -import { Inter } from 'next/font/google' +import { Geist } from 'next/font/google' -const inter = Inter({ +const geist = Geist({ subsets: ['latin'], }) @@ -228,7 +228,7 @@ export default function RootLayout({ children: React.ReactNode }) { return ( - + {children} ) @@ -236,15 +236,15 @@ export default function RootLayout({ ``` ```jsx filename="app/layout.js" switcher -import { Inter } from 'next/font/google' +import { Geist } from 'next/font/google' -const inter = Inter({ +const geist = Geist({ subsets: ['latin'], }) export default function RootLayout({ children }) { return ( - + {children} ) @@ -274,7 +274,7 @@ export default function RootLayout({ } ``` -```jsx filename="app/layout.js" switcher +```jsx filename="app/layout.js" highlight={1,3-5,9} switcher import { Roboto } from 'next/font/google' const roboto = Roboto({ @@ -293,7 +293,7 @@ export default function RootLayout({ children }) { ### Local fonts -To use a local font, import `next/font/local` and specify the `src` of your local font file in the [`public` folder](#handling-static-assets). +To use a local font, import your font from `next/font/local` and specify the `src` of your local font file in the [`public` folder](#handling-static-assets). ```tsx filename="app/layout.tsx" switcher import localFont from 'next/font/local' @@ -359,5 +359,3 @@ const roboto = localFont({ ], }) ``` - -Learn more about Font Optimization in the [API Reference](/docs/app/api-reference/components/font). diff --git a/docs/01-app/01-getting-started/05-css-and-styling.mdx b/docs/01-app/01-getting-started/05-css-and-styling.mdx index d50348c9979bf..742cc20aadeaf 100644 --- a/docs/01-app/01-getting-started/05-css-and-styling.mdx +++ b/docs/01-app/01-getting-started/05-css-and-styling.mdx @@ -3,6 +3,8 @@ title: How to use CSS in your application nav_title: CSS and Styling description: Learn about the different ways to add CSS to your application, including CSS Modules, Global CSS, Tailwind CSS, and more. related: + title: API Reference + description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/api-reference/config/next-config-js/sassOptions - architecture/nextjs-compiler @@ -47,12 +49,6 @@ export default function Page({ children }) { } ``` -> **Good to know:** -> -> - CSS Modules are only enabled for files with the `.module.css` and `.module.sass` extensions. -> - In production, all CSS Module files will be automatically concatenated into minified and code-split `.css` files. -> - These `.css` files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded for your application to paint. - ## Global CSS You can use global CSS to apply styles across your application. @@ -118,13 +114,12 @@ npx tailwindcss init -p Inside your Tailwind configuration file, add paths to the files that will use the Tailwind class names: -```ts filename="tailwind.config.ts" switcher +```ts filename="tailwind.config.ts" highlight={5-7} switcher import type { Config } from 'tailwindcss' const config: Config = { content: [ './app/**/*.{js,ts,jsx,tsx,mdx}', - './components/**/*.{js,ts,jsx,tsx,mdx}', // Or if using `src` directory: './src/**/*.{js,ts,jsx,tsx,mdx}', ], @@ -136,12 +131,11 @@ const config: Config = { export default config ``` -```js filename="tailwind.config.js" switcher +```js filename="tailwind.config.js" highlight={4-6} switcher /** @type {import('tailwindcss').Config} */ module.exports = { content: [ './app/**/*.{js,ts,jsx,tsx,mdx}', - './components/**/*.{js,ts,jsx,tsx,mdx}', // Or if using `src` directory: './src/**/*.{js,ts,jsx,tsx,mdx}', ], @@ -152,11 +146,9 @@ module.exports = { } ``` -You do not need to modify `postcss.config.js`. - ### Using Tailwind -Add the [Tailwind directives](https://tailwindcss.com/docs/functions-and-directives#directives) to your [Global Stylesheet](#global-css), for example: +Add the [Tailwind directives](https://tailwindcss.com/docs/functions-and-directives#directives) to your [Global Stylesheet](#global-css): ```css filename="app/globals.css" @tailwind base; @@ -164,7 +156,7 @@ Add the [Tailwind directives](https://tailwindcss.com/docs/functions-and-directi @tailwind utilities; ``` -Then, import the styles in the root layout: +Then, import the styles in the [root layout](/docs/app/api-reference/file-conventions/layout#root-layouts): ```tsx filename="app/layout.tsx" switcher import type { Metadata } from 'next' @@ -208,7 +200,7 @@ export default function RootLayout({ children }) { } ``` -Lastly, you can write Tailwind's utility classes in your application. +Lastly, you can start writing Tailwind's utility classes in your application. ```tsx filename="app/page.tsx" switcher export default function Page() { @@ -238,7 +230,7 @@ npm install --save-dev sass ### Customizing Sass options -If you want to configure your Sass options, use `sassOptions` in `next.config.js`. +If you want to configure your Sass options, use the [`sassOptions`](/docs/app/api-reference/config/next-config-js/sassOptions) option in `next.config.js`. ```ts filename="next.config.ts" switcher import type { NextConfig } from 'next' @@ -264,8 +256,6 @@ const nextConfig = { module.exports = nextConfig ``` -Learn more about the `sassOptions` configuration in the [API Reference](/docs/app/api-reference/config/next-config-js/sassOptions). - ## CSS-in-JS > **Warning:** CSS-in-JS libraries which require runtime JavaScript are not currently supported in React Server Components. Using CSS-in-JS with newer React features like Server Components and Streaming requires library authors to support the latest version of React. diff --git a/docs/01-app/01-getting-started/06-data-fetching-and-streaming.mdx b/docs/01-app/01-getting-started/06-data-fetching-and-streaming.mdx index 9c6632a4c53c1..71bd6bfa35ac7 100644 --- a/docs/01-app/01-getting-started/06-data-fetching-and-streaming.mdx +++ b/docs/01-app/01-getting-started/06-data-fetching-and-streaming.mdx @@ -3,6 +3,8 @@ title: How to fetch data and stream nav_title: Fetching data and streaming description: Start fetching data and streaming content in your application. related: + title: API Reference + description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/api-reference/functions/fetch - app/api-reference/file-conventions/loading @@ -87,6 +89,13 @@ export default async function Page() { ### Client Components +There are two ways to fetch data in Client Components, using: + +1. React's [`use` hook](https://react.dev/reference/react/use) +2. A community library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/latest) + +#### With the `use` hook + You can use React's [`use` hook](https://react.dev/reference/react/use) to [stream](#streaming) data from the server to client. Start by fetching data in your Server component, and pass the promise to your Client Component as prop: ```tsx filename="app/blog/page.tsx" switcher @@ -159,7 +168,9 @@ export default function Posts({ posts }) { In the example above, you need to wrap the `` component in a [`` boundary](https://react.dev/reference/react/Suspense). This means the fallback will be shown while the promise is being resolved. Learn more about [streaming](#streaming). -Alternatively, you can use a community library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/latest). These libraries have their own semantics for caching, streaming, and other features. For example: +#### Community libraries + +You can use a community library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/latest) to fetch data in Client Components. These libraries have their own semantics for caching, streaming, and other features. For example, with SWR: ```tsx filename="app/blog/page.tsx" switcher 'use client'