DocumentationShowcaseBlog

turbopackLazyDynamicImports

Compile client-side dynamic imports when they are first requested during development.

The experimental.turbopackLazyDynamicImports option defers compiling client-side dynamic import() targets until the browser first requests them during next dev.

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    turbopackLazyDynamicImports: true,
  },
}
 
export default nextConfig

How it works

With turbopackLazyDynamicImports enabled, Turbopack waits to compile the target of a client-side dynamic import() until the browser requests its chunk. Code that the application never imports remains uncompiled during the development session.

For example, the module in this Client Component is compiled when the visitor selects the button:

'use client'
 
import { useState } from 'react'
 
export function GreetingButton() {
  const [message, setMessage] = useState('')
 
  async function showGreeting() {
    const { getGreeting } = await import('./get-greeting')
    setMessage(getGreeting('Ada'))
  }
 
  return (
    <>
      <button onClick={showGreeting}>Show greeting</button>
      <p>{message}</p>
    </>
  )
}

Good to know:

  • The option defaults to false and only affects Turbopack during next dev. It does not change production builds.
  • Errors in a deferred module appear when Turbopack first compiles that module.
  • Some next/dynamic targets are still compiled eagerly.
  • To defer dynamic imports reached while rendering Client Components on the server, use turbopackLazyDynamicImportsSSR.

Version History

VersionChanges
v16.4.0experimental.turbopackLazyDynamicImports configuration option added.

On this page