diff --git a/docs/01-app/02-guides/lazy-loading.mdx b/docs/01-app/02-guides/lazy-loading.mdx index 00258e3edd851..b36651ce4a51f 100644 --- a/docs/01-app/02-guides/lazy-loading.mdx +++ b/docs/01-app/02-guides/lazy-loading.mdx @@ -8,6 +8,8 @@ description: Lazy load imported libraries and React Components to improve your a [Lazy loading](https://developer.mozilla.org/docs/Web/Performance/Lazy_loading) in Next.js helps improve the initial loading performance of an application by decreasing the amount of JavaScript needed to render a route. + + It allows you to defer loading of **Client Components** and imported libraries, and only include them in the client bundle when they're needed. For example, you might want to defer loading a modal until a user clicks to open it. There are two ways you can implement lazy loading in Next.js: @@ -23,8 +25,6 @@ By default, Server Components are automatically [code split](https://developer.m ## Examples - - ### Importing Client Components ```jsx filename="app/page.js" @@ -176,7 +176,11 @@ const ClientComponent = dynamic(() => -By using `next/dynamic`, the header component will not be included in the page's initial JavaScript bundle. The page will render the Suspense `fallback` first, followed by the `Header` component when the `Suspense` boundary is resolved. +## `next/dynamic` + +`next/dynamic` is a composite of [`React.lazy()`](https://react.dev/reference/react/lazy) and [Suspense](https://react.dev/reference/react/Suspense). It behaves the same way in the `app` and `pages` directories to allow for incremental migration. + +In the example below, by using `next/dynamic`, the header component will not be included in the page's initial JavaScript bundle. The page will render the Suspense `fallback` first, followed by the `Header` component when the `Suspense` boundary is resolved. ```jsx import dynamic from 'next/dynamic' @@ -192,7 +196,9 @@ export default function Home() { > **Good to know**: In `import('path/to/component')`, the path must be explicitly written. It can't be a template string nor a variable. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`. -## With named exports +## Examples + +### With named exports To dynamically import a named export, you can return it from the [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) returned by [`import()`](https://github.com/tc39/proposal-dynamic-import#example): @@ -209,7 +215,7 @@ const DynamicComponent = dynamic(() => ) ``` -## With no SSR +### With no SSR To dynamically load a component on the client side, you can use the `ssr` option to disable server-rendering. This is useful if an external dependency or component relies on browser APIs like `window`. @@ -223,7 +229,7 @@ const DynamicHeader = dynamic(() => import('../components/header'), { }) ``` -## With external libraries +### With external libraries This example uses the external library `fuse.js` for fuzzy search. The module is only loaded in the browser after the user types in the search input.