Support suspense in next dynamic (#27611)

### Changes
#### Feature
* Adopt `React.lazy` into `next/dynamic`, enable it when `options.suspense` is `true`
* Support `next/dynamic` with `suspense=true` in SSR and SSG

#### Tests

| Scenario | Case | Behavior |
|:----:|:----:|:----:|
| basics | react 17 or 18 by default | dev/build error or pass |
| blocking rendering | `reactRoot: true` + `concurrentFeatures: false` | dev/build pass |
| concurrent rendering | `reactRoot: true` + `concurrentFeatures: true` | dev/build pass | 


## Feature

- [x] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [x] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

Author: huozhi

packages/next/build/webpack-config.ts

@@ -769,9 +769,9 @@ export default async function getBaseWebpackConfig(
 
     if (isLocal) {
       // Makes sure dist/shared and dist/server are not bundled
-      // we need to process shared/lib/router/router so that
-      // the DefinePlugin can inject process.env values
-      const isNextExternal = /next[/\\]dist[/\\](shared|server)[/\\](?!lib[/\\]router[/\\]router)/.test(
+      // we need to process shared `router/router` and `dynamic`,
+      // so that the DefinePlugin can inject process.env values
+      const isNextExternal = /next[/\\]dist[/\\](shared|server)[/\\](?!lib[/\\](router[/\\]router|dynamic))/.test(
         res
       )
 
@@ -1185,6 +1185,9 @@ export default async function getBaseWebpackConfig(
           config.reactStrictMode
         ),
         'process.env.__NEXT_REACT_ROOT': JSON.stringify(hasReactRoot),
+        'process.env.__NEXT_CONCURRENT_FEATURES': JSON.stringify(
+          config.experimental.concurrentFeatures && hasReactRoot
+        ),
         'process.env.__NEXT_OPTIMIZE_FONTS': JSON.stringify(
           config.optimizeFonts && !dev
         ),

packages/next/export/index.ts

@@ -380,6 +380,7 @@ export default async function exportApp(
       disableOptimizedLoading: nextConfig.experimental.disableOptimizedLoading,
       // TODO: We should support dynamic HTML too
       requireStaticHTML: true,
+      concurrentFeatures: nextConfig.experimental.concurrentFeatures,
     }
 
     const { serverRuntimeConfig, publicRuntimeConfig } = nextConfig

packages/next/shared/lib/dynamic.tsx

@@ -33,19 +33,24 @@ export type LoadableBaseOptions<P = {}> = LoadableGeneratedOptions & {
   ssr?: boolean
 }
 
+export type LoadableSuspenseOptions<P = {}> = {
+  loader: Loader<P>
+  suspense?: boolean
+}
+
 export type LoadableOptions<P = {}> = LoadableBaseOptions<P>
 
 export type DynamicOptions<P = {}> = LoadableBaseOptions<P>
 
 export type LoadableFn<P = {}> = (
-  opts: LoadableOptions<P>
+  opts: LoadableOptions<P> | LoadableSuspenseOptions<P>
 ) => React.ComponentType<P>
 
 export type LoadableComponent<P = {}> = React.ComponentType<P>
 
 export function noSSR<P = {}>(
   LoadableInitializer: LoadableFn<P>,
-  loadableOptions: LoadableOptions<P>
+  loadableOptions: LoadableBaseOptions<P>
 ): React.ComponentType<P> {
   // Removing webpack and modules means react-loadable won't try preloading
   delete loadableOptions.webpack
@@ -63,8 +68,6 @@ export function noSSR<P = {}>(
   )
 }
 
-// function dynamic<P = {}, O extends DynamicOptions>(options: O):
-
 export default function dynamic<P = {}>(
   dynamicOptions: DynamicOptions<P> | Loader<P>,
   options?: DynamicOptions<P>
@@ -110,6 +113,21 @@ export default function dynamic<P = {}>(
   // Support for passing options, eg: dynamic(import('../hello-world'), {loading: () => <p>Loading something</p>})
   loadableOptions = { ...loadableOptions, ...options }
 
+  const suspenseOptions = loadableOptions as LoadableSuspenseOptions<P>
+  if (!process.env.__NEXT_CONCURRENT_FEATURES) {
+    // Error if react root is not enabled and `suspense` option is set to true
+    if (!process.env.__NEXT_REACT_ROOT && suspenseOptions.suspense) {
+      // TODO: add error doc when this feature is stable
+      throw new Error(
+        `Disallowed suspense option usage with next/dynamic in blocking mode`
+      )
+    }
+    suspenseOptions.suspense = false
+  }
+  if (suspenseOptions.suspense) {
+    return loadableFn(suspenseOptions)
+  }
+
   // coming from build/babel/plugins/react-loadable-plugin.js
   if (loadableOptions.loadableGenerated) {
     loadableOptions = {

packages/next/shared/lib/loadable.js

@@ -66,12 +66,16 @@ function createLoadableComponent(loadFn, options) {
       timeout: null,
       webpack: null,
       modules: null,
+      suspense: false,
     },
     options
   )
 
-  let subscription = null
+  if (opts.suspense) {
+    opts.lazy = React.lazy(opts.loader)
+  }
 
+  let subscription = null
   function init() {
     if (!subscription) {
       const sub = new LoadableSubscription(loadFn, opts)
@@ -86,7 +90,7 @@ function createLoadableComponent(loadFn, options) {
   }
 
   // Server only
-  if (typeof window === 'undefined') {
+  if (typeof window === 'undefined' && !opts.suspense) {
     ALL_INITIALIZERS.push(init)
   }
 
@@ -95,7 +99,8 @@ function createLoadableComponent(loadFn, options) {
     !initialized &&
     typeof window !== 'undefined' &&
     typeof opts.webpack === 'function' &&
-    typeof require.resolveWeak === 'function'
+    typeof require.resolveWeak === 'function' &&
+    !opts.suspense
   ) {
     const moduleIds = opts.webpack()
     READY_INITIALIZERS.push((ids) => {
@@ -107,12 +112,11 @@ function createLoadableComponent(loadFn, options) {
     })
   }
 
-  const LoadableComponent = (props, ref) => {
+  function LoadableImpl(props, ref) {
     init()
 
     const context = React.useContext(LoadableContext)
     const state = useSubscription(subscription)
-
     React.useImperativeHandle(
       ref,
       () => ({
@@ -144,7 +148,12 @@ function createLoadableComponent(loadFn, options) {
     }, [props, state])
   }
 
-  LoadableComponent.preload = () => init()
+  function LazyImpl(props, ref) {
+    return React.createElement(opts.lazy, { ...props, ref })
+  }
+
+  const LoadableComponent = opts.suspense ? LazyImpl : LoadableImpl
+  LoadableComponent.preload = () => !opts.suspense && init()
   LoadableComponent.displayName = 'LoadableComponent'
 
   return React.forwardRef(LoadableComponent)

test/integration/chunking/test/index.test.js

@@ -84,7 +84,6 @@ describe('Chunking', () => {
 
   it('should execute the build manifest', async () => {
     const html = await renderViaHTTP(appPort, '/')
-    console.log(html)
     const $ = cheerio.load(html)
     expect(
       Array.from($('script'))

test/integration/react-18/app/components/bar.js

@@ -0,0 +1,24 @@
+import { Suspense } from 'react'
+import dynamic from 'next/dynamic'
+import { useCachedPromise } from './promise-cache'
+
+const Foo = dynamic(() => import('./foo'), {
+  suspense: true,
+})
+
+export default function Bar() {
+  useCachedPromise(
+    'bar',
+    () => new Promise((resolve) => setTimeout(resolve, 300)),
+    true
+  )
+
+  return (
+    <div>
+      bar
+      <Suspense fallback={'oof'}>
+        <Foo />
+      </Suspense>
+    </div>
+  )
+}

test/integration/react-18/app/components/dynamic-hello.js

@@ -0,0 +1,18 @@
+import { Suspense } from 'react'
+import dynamic from 'next/dynamic'
+
+let ssr
+const suspense = false
+
+const Hello = dynamic(() => import('./hello'), {
+  ssr,
+  suspense,
+})
+
+export default function DynamicHello(props) {
+  return (
+    <Suspense fallback={'loading'}>
+      <Hello {...props} />
+    </Suspense>
+  )
+}

test/integration/react-18/app/components/foo.js

@@ -0,0 +1,3 @@
+export default function Foo() {
+  return 'foo'
+}

test/integration/react-18/app/components/hello.js

@@ -0,0 +1,13 @@
+import React from 'react'
+import ReactDOM from 'react-dom'
+import { useCachedPromise } from './promise-cache'
+
+export default function Hello({ name, thrown = false }) {
+  useCachedPromise(
+    name,
+    () => new Promise((resolve) => setTimeout(resolve, 200)),
+    thrown
+  )
+
+  return <p>hello {ReactDOM.version}</p>
+}

test/integration/react-18/app/components/promise-cache.js

@@ -0,0 +1,37 @@
+import React from 'react'
+
+const PromiseCacheContext = React.createContext(null)
+
+export const cache = new Map()
+export const PromiseCacheProvider = PromiseCacheContext.Provider
+
+export function useCachedPromise(key, fn, thrown = false) {
+  const cache = React.useContext(PromiseCacheContext)
+
+  if (!thrown) return undefined
+  let entry = cache.get(key)
+  if (!entry) {
+    entry = {
+      status: 'PENDING',
+      value: fn().then(
+        (value) => {
+          cache.set(key, {
+            status: 'RESOLVED',
+            value,
+          })
+        },
+        (err) => {
+          cache.set(key, {
+            status: 'REJECTED',
+            value: err,
+          })
+        }
+      ),
+    }
+    cache.set(key, entry)
+  }
+  if (['PENDING', 'REJECTED'].includes(entry.status)) {
+    throw entry.value
+  }
+  return entry.value
+}