DocumentationShowcaseBlog

turbopackLazyDynamicImportsSSR

Compile dynamic imports when server rendering first reaches them during development.

The experimental.turbopackLazyDynamicImportsSSR option defers compiling dynamic imports until server rendering first reaches them during next dev.

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

How it works

Client Components can use lazy to load a component dynamically. With turbopackLazyDynamicImportsSSR enabled, Turbopack compiles the imported component when a server render first reaches it. A target that is not rendered remains uncompiled.

In the following example, Turbopack compiles Preview when showPreview is true during server rendering:

'use client'
 
import { lazy } from 'react'
 
const Preview = lazy(() => import('./preview-panel'))
 
export function MaybePreview({ showPreview }: { showPreview: boolean }) {
  return showPreview ? <Preview /> : null
}

Good to know:

  • The option defaults to false and only affects the Node.js runtime with Turbopack during next dev. It does not change production builds.
  • To defer client-side dynamic imports until the browser requests them, use turbopackLazyDynamicImports.

Version History

VersionChanges
v16.4.0experimental.turbopackLazyDynamicImportsSSR configuration option added.

On this page