Enable missing suspense bailout by default (#60840)

`experimental.missingSuspenseWithCSRBailout` should be enabled by
default to help users to disciver unwrapped suspense boundaries.

Add more notes in the error doc about deprecation and temporary
workaround to disable it.

Closes NEXT-2157

---------

Co-authored-by: JJ Kasper <[email protected]>

Author: huozhi

errors/missing-suspense-with-csr-bailout.mdx

@@ -10,6 +10,8 @@ Certain methods like `useSearchParams()` opt Next.js into client-side rendering.
 
 Make sure that the method is wrapped in a suspense boundary. This way Next.js will only opt the component into client-side rendering up to the suspense boundary.
 
+> Note: There's an option `experimental.missingSuspenseWithCSRBailout` to disable the bailout behavior while you are investigating the missing suspense boundary. But it will be removed in next major version as this is a performance de-opt.
+
 ### Useful Links
 
 - [`useSearchParams`](https://nextjs.org/docs/app/api-reference/functions/use-search-params)

packages/next/src/server/config-shared.ts

@@ -387,7 +387,8 @@ export interface ExperimentalConfig {
    *
    * When this flag is set to `true`, Next.js will break the build instead of warning, to force the developer to add a suspense boundary above the method call.
    *
-   * @default false
+   * @note This flag will be removed in Next.js 15.
+   * @default true
    */
   missingSuspenseWithCSRBailout?: boolean
 }
@@ -866,7 +867,7 @@ export const defaultConfig: NextConfig = {
         ? true
         : false,
     webpackBuildWorker: undefined,
-    missingSuspenseWithCSRBailout: false,
+    missingSuspenseWithCSRBailout: true,
   },
 }
 

test/e2e/app-dir/missing-suspense-with-csr-bailout/next.config.js

@@ -1,8 +1,4 @@
 /** @type {import("next").NextConfig} */
-const config = {
-  experimental: {
-    missingSuspenseWithCSRBailout: true,
-  },
-}
+const config = {}
 
 module.exports = config

test/e2e/app-dir/params-hooks-compat/app/app/[slug]/page.js

@@ -1,5 +1,12 @@
 'use client'
 
+import { Suspense } from 'react'
 import { ParamsComponent } from '../../../shared/params-component'
 
-export default ParamsComponent
+export default function Page() {
+  return (
+    <Suspense>
+      <ParamsComponent />
+    </Suspense>
+  )
+}

test/e2e/app-dir/params-hooks-compat/shared/params-component.js

@@ -1,4 +1,3 @@
-import React from 'react'
 import { useParams, useSearchParams } from 'next/navigation'
 
 export function ParamsComponent() {

test/e2e/app-dir/shallow-routing/app/(shallow)/pushstate-new-searchparams/page.tsx

@@ -1,7 +1,9 @@
 'use client'
+
+import { Suspense } from 'react'
 import { useSearchParams } from 'next/navigation'
 
-export default function Page() {
+function InnerPage() {
   const searchParams = useSearchParams()
   return (
     <>
@@ -24,3 +26,11 @@ export default function Page() {
     </>
   )
 }
+
+export default function Page() {
+  return (
+    <Suspense>
+      <InnerPage />
+    </Suspense>
+  )
+}

test/e2e/app-dir/shallow-routing/app/(shallow)/pushstate-string-url/page.tsx

@@ -1,7 +1,9 @@
 'use client'
+
+import { Suspense } from 'react'
 import { useSearchParams } from 'next/navigation'
 
-export default function Page() {
+function InnerPage() {
   const searchParams = useSearchParams()
   return (
     <>
@@ -57,3 +59,11 @@ export default function Page() {
     </>
   )
 }
+
+export default function Page() {
+  return (
+    <Suspense>
+      <InnerPage />
+    </Suspense>
+  )
+}

test/e2e/app-dir/shallow-routing/app/(shallow)/replacestate-new-searchparams/page.tsx

@@ -1,7 +1,9 @@
 'use client'
+
+import { Suspense } from 'react'
 import { useSearchParams } from 'next/navigation'
 
-export default function Page() {
+function InnerPage() {
   const searchParams = useSearchParams()
   return (
     <>
@@ -24,3 +26,11 @@ export default function Page() {
     </>
   )
 }
+
+export default function Page() {
+  return (
+    <Suspense>
+      <InnerPage />
+    </Suspense>
+  )
+}

test/e2e/app-dir/shallow-routing/app/(shallow)/replacestate-string-url/page.tsx

@@ -1,7 +1,9 @@
 'use client'
+
+import { Suspense } from 'react'
 import { useSearchParams } from 'next/navigation'
 
-export default function Page() {
+function InnerPage() {
   const searchParams = useSearchParams()
   return (
     <>
@@ -57,3 +59,11 @@ export default function Page() {
     </>
   )
 }
+
+export default function Page() {
+  return (
+    <Suspense>
+      <InnerPage />
+    </Suspense>
+  )
+}