Merge branch 'canary' into x-use-zen-observable

Author: devknoll

docs/advanced-features/dynamic-import.md

@@ -156,3 +156,25 @@ function Home() {
 
 export default Home
 ```
+
+## With suspense
+
+Option `suspense` allows you to lazy-load a component, similar to `React.lazy` and `<Suspense>` with React 18. Note that it only works on client-side or server-side with `fallback`. Full SSR support in concurrent mode is still a work-in-progress.
+
+```jsx
+import dynamic from 'next/dynamic'
+
+const DynamicLazyComponent = dynamic(() => import('../components/hello4'), {
+  suspense: true,
+})
+
+function Home() {
+  return (
+    <div>
+      <Suspense fallback={`loading`}>
+        <DynamicLazyComponent />
+      </Suspense>
+    </div>
+  )
+}
+```

errors/invalid-dynamic-suspense.md

@@ -0,0 +1,13 @@
+# Invalid Usage of `suspense` Option of `next/dynamic`
+
+#### Why This Error Occurred
+
+`<Suspense>` is not allowed under legacy render mode when using React older than v18.
+
+#### Possible Ways to Fix It
+
+Remove `suspense: true` option in `next/dynamic` usages.
+
+### Useful Links
+
+- [Dynamic Import Suspense Usage](https://nextjs.org/docs/advanced-features/dynamic-import#with-suspense)

errors/manifest.json

@@ -151,6 +151,10 @@
           "title": "invalid-assetprefix",
           "path": "/errors/invalid-assetprefix.md"
         },
+        {
+          "title": "invalid-dynamic-suspense",
+          "path": "/errors/invalid-dynamic-suspense.md"
+        },
         {
           "title": "invalid-external-rewrite",
           "path": "/errors/invalid-external-rewrite.md"

packages/next/lib/typescript/writeAppTypeDeclarations.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs'
 import os from 'os'
 import path from 'path'
+import { fileExists } from '../file-exists'
 
 export async function writeAppTypeDeclarations(
   baseDir: string,
@@ -9,19 +10,27 @@ export async function writeAppTypeDeclarations(
   // Reference `next` types
   const appTypeDeclarations = path.join(baseDir, 'next-env.d.ts')
 
-  await fs.writeFile(
-    appTypeDeclarations,
+  const content =
     '/// <reference types="next" />' +
-      os.EOL +
-      '/// <reference types="next/types/global" />' +
-      os.EOL +
-      (imageImportsEnabled
-        ? '/// <reference types="next/image-types/global" />' + os.EOL
-        : '') +
-      os.EOL +
-      '// NOTE: This file should not be edited' +
-      os.EOL +
-      '// see https://nextjs.org/docs/basic-features/typescript for more information.' +
-      os.EOL
-  )
+    os.EOL +
+    '/// <reference types="next/types/global" />' +
+    os.EOL +
+    (imageImportsEnabled
+      ? '/// <reference types="next/image-types/global" />' + os.EOL
+      : '') +
+    os.EOL +
+    '// NOTE: This file should not be edited' +
+    os.EOL +
+    '// see https://nextjs.org/docs/basic-features/typescript for more information.' +
+    os.EOL
+
+  // Avoids a write for read-only filesystems
+  if (
+    (await fileExists(appTypeDeclarations)) &&
+    (await fs.readFile(appTypeDeclarations, 'utf8')) === content
+  ) {
+    return
+  }
+
+  await fs.writeFile(appTypeDeclarations, content)
 }

packages/next/shared/lib/dynamic.tsx

@@ -119,7 +119,7 @@ export default function dynamic<P = {}>(
     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`
+        `Invalid suspense option usage in next/dynamic. Read more: https://nextjs.org/docs/messages/invalid-dynamic-suspense`
       )
     }
   }

test/integration/react-18/test/index.test.js

@@ -87,7 +87,7 @@ describe('React 18 Support', () => {
       })
       expect(code).toBe(1)
       expect(stderr).toContain(
-        'Disallowed suspense option usage with next/dynamic'
+        'Invalid suspense option usage in next/dynamic. Read more: https://nextjs.org/docs/messages/invalid-dynamic-suspense'
       )
     })
   })
@@ -130,7 +130,7 @@ describe('Basics', () => {
     const html = await renderViaHTTP(appPort, '/suspense/unwrapped')
     unwrappedPage.restore()
     await killApp(app)
-    // expect(html).toContain('Disallowed suspense option usage with next/dynamic')
+
     expect(html).toContain(
       'A React component suspended while rendering, but no fallback UI was specified'
     )

test/integration/typescript-app-type-declarations/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/types/global" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

test/integration/typescript-app-type-declarations/pages/index.tsx

@@ -0,0 +1,3 @@
+export default function Index() {
+  return <div />
+}

test/integration/typescript-app-type-declarations/test/index.test.js

@@ -0,0 +1,61 @@
+/* eslint-env jest */
+
+import { join } from 'path'
+import { findPort, launchApp, killApp } from 'next-test-utils'
+import { promises as fs } from 'fs'
+
+jest.setTimeout(1000 * 60 * 2)
+
+const appDir = join(__dirname, '..')
+const appTypeDeclarations = join(appDir, 'next-env.d.ts')
+
+describe('TypeScript App Type Declarations', () => {
+  it('should write a new next-env.d.ts if none exist', async () => {
+    const prevContent = await fs.readFile(appTypeDeclarations, 'utf8')
+    try {
+      await fs.unlink(appTypeDeclarations)
+      const appPort = await findPort()
+      let app
+      try {
+        app = await launchApp(appDir, appPort, {})
+        const content = await fs.readFile(appTypeDeclarations, 'utf8')
+        expect(content).toEqual(prevContent)
+      } finally {
+        await killApp(app)
+      }
+    } finally {
+      await fs.writeFile(appTypeDeclarations, prevContent)
+    }
+  })
+
+  it('should overwrite next-env.d.ts if an incorrect one exists', async () => {
+    const prevContent = await fs.readFile(appTypeDeclarations, 'utf8')
+    try {
+      await fs.writeFile(appTypeDeclarations, prevContent + 'modification')
+      const appPort = await findPort()
+      let app
+      try {
+        app = await launchApp(appDir, appPort, {})
+        const content = await fs.readFile(appTypeDeclarations, 'utf8')
+        expect(content).toEqual(prevContent)
+      } finally {
+        await killApp(app)
+      }
+    } finally {
+      await fs.writeFile(appTypeDeclarations, prevContent)
+    }
+  })
+
+  it('should not touch an existing correct next-env.d.ts', async () => {
+    const prevStat = await fs.stat(appTypeDeclarations)
+    const appPort = await findPort()
+    let app
+    try {
+      app = await launchApp(appDir, appPort, {})
+      const stat = await fs.stat(appTypeDeclarations)
+      expect(stat.mtime).toEqual(prevStat.mtime)
+    } finally {
+      await killApp(app)
+    }
+  })
+})

test/integration/typescript-app-type-declarations/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "esModuleInterop": true,
+    "module": "esnext",
+    "jsx": "preserve",
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "incremental": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "exclude": ["node_modules"],
+  "include": ["next-env.d.ts", "components", "pages"]
+}