Add Import trace for requested module when it fails to resolve (verce…

…l#27840)

Co-authored-by: Steven <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

errors/module-not-found.md

@@ -0,0 +1,151 @@
+# Module Not Found
+
+#### Why This Error Occurred
+
+A module not found error can occur for many different reasons:
+
+- The module you're trying to import is not installed in your dependencies
+- The module you're trying to import is in a different directory
+- The module you're trying to import has a different casing
+- The module you're trying to import uses Node.js specific modules, for example `dns`, outside of `getStaticProps` / `getStaticPaths` / `getServerSideProps`
+
+#### Possible Ways to Fix It
+
+##### The module you're trying to import is not installed in your dependencies
+
+When importing a module from [npm](https://npmjs.com) this module has to be installed locally.
+
+For example when importing the `swr` package:
+
+```js
+import useSWR from 'swr'
+```
+
+The `swr` module has to be installed using a package manager.
+
+- When using `npm`: `npm install swr`
+- When using `yarn`: `yarn add swr`
+
+##### The module you're trying to import is in a different directory
+
+Make sure that the path you're importing refers to the right directory and file.
+
+##### The module you're trying to import has a different casing
+
+Make sure the casing of the file is correct.
+
+Example:
+
+```js
+// components/MyComponent.js
+export default function MyComponent() {
+  return <h1>Hello</h1>
+}
+```
+
+```js
+// pages/index.js
+// Note how `components/MyComponent` exists but `Mycomponent` without the capital `c` is imported
+import MyComponent from '../components/Mycomponent'
+```
+
+Incorrect casing will lead to build failures on case-sensitive environments like most Linux-based continuous integration and can cause issues with Fast Refresh.
+
+##### The module you're trying to import uses Node.js specific modules
+
+`getStaticProps`, `getStaticPaths`, and `getServerSideProps` allow for using modules that can only run in the Node.js environment. This allows you to do direct database queries or reading data from Redis to name a few examples.
+
+The tree shaking only runs on top level pages, so it can't be relied on in separate React components.
+
+You can verify the tree shaking on [next-code-elimination.vercel.app](https://next-code-elimination.vercel.app/).
+
+Example of correctly tree shaken code:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+import redis from '../lib/redis'
+
+export async function getStaticProps() {
+  const message = await redis.get('message')
+  return {
+    message,
+  }
+}
+
+export default function Home({ message }) {
+  return <h1>{message}</h1>
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+export default redis
+```
+
+```js
+// pages/index.js
+// Redis is a Node.js specific library that can't run in the browser
+// Trying to use it in code that runs on both Node.js and the browser will result in a module not found error for modules that ioredis relies on
+// If you run into such an error it's recommended to move the code to `getStaticProps` or `getServerSideProps` as those methods guarantee that the code is only run in Node.js.
+import redis from '../lib/redis'
+import { useEffect, useState } from 'react'
+
+export default function Home() {
+  const [message, setMessage] = useState()
+  useEffect(() => {
+    redis.get('message').then((result) => {
+      setMessage(result)
+    })
+  }, [])
+  return <h1>{message}</h1>
+}
+```
+
+Example of code that would break:
+
+```js
+// lib/redis.js
+import Redis from 'ioredis'
+
+// Modules that hold Node.js-only code can't also export React components
+// Tree shaking of getStaticProps/getStaticPaths/getServerSideProps is ran only on page files
+const redis = new Redis(process.env.REDIS_URL)
+
+export function MyComponent() {
+  return <h1>Hello</h1>
+}
+
+export default redis
+```
+
+```js
+// pages/index.js
+// In practice you'll want to refactor the `MyComponent` to be a separate file so that tree shaking ensures that specific import is not included for the browser compilation
+import redis, { MyComponent } from '../lib/redis'
+
+export async function getStaticProps() {
+  const message = await redis.get('message')
+  return {
+    message,
+  }
+}
+
+export default function Home() {
+  return <MyComponent />
+}
+```

packages/next/build/webpack/plugins/wellknown-errors-plugin/parseNotFoundError.ts

@@ -1,9 +1,51 @@
 import Chalk from 'chalk'
 import { SimpleWebpackError } from './simpleWebpackError'
 import { createOriginalStackFrame } from '@next/react-dev-overlay/lib/middleware'
+import { isWebpack5 } from 'next/dist/compiled/webpack/webpack'
+import path from 'path'
 
 const chalk = new Chalk.constructor({ enabled: true })
 
+// Based on https://github.com/webpack/webpack/blob/fcdd04a833943394bbb0a9eeb54a962a24cc7e41/lib/stats/DefaultStatsFactoryPlugin.js#L422-L431
+/*
+Copyright JS Foundation and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+*/
+function getModuleTrace(input: any, compilation: any) {
+  const visitedModules = new Set()
+  const moduleTrace = []
+  let current = input.module
+  while (current) {
+    if (visitedModules.has(current)) break // circular (technically impossible, but who knows)
+    visitedModules.add(current)
+    const origin = compilation.moduleGraph.getIssuer(current)
+    if (!origin) break
+    moduleTrace.push({ origin, module: current })
+    current = origin
+  }
+
+  return moduleTrace
+}
+
 export async function getNotFoundError(
   compilation: any,
   input: any,
@@ -36,11 +78,38 @@ export async function getNotFoundError(
       .replace(/ in '.*?'/, '')
       .replace(/Can't resolve '(.*)'/, `Can't resolve '${chalk.green('$1')}'`)
 
+    const importTrace = () => {
+      if (!isWebpack5) {
+        return ''
+      }
+
+      let importTraceLine = '\nImport trace for requested module:\n'
+      const moduleTrace = getModuleTrace(input, compilation)
+
+      for (const { origin } of moduleTrace) {
+        if (!origin.resource) {
+          continue
+        }
+        const filePath = path.relative(
+          compilation.options.context,
+          origin.resource
+        )
+        importTraceLine += `./${filePath}\n`
+      }
+
+      return importTraceLine + '\n'
+    }
+
+    const frame = result.originalCodeFrame ?? ''
+
     const message =
       chalk.red.bold('Module not found') +
       `: ${errorMessage}` +
       '\n' +
-      result.originalCodeFrame
+      frame +
+      (frame !== '' ? '\n' : '') +
+      importTrace() +
+      '\nhttps://nextjs.org/docs/messages/module-not-found'
 
     return new SimpleWebpackError(
       `${chalk.cyan(fileName)}:${chalk.yellow(

test/acceptance/ReactRefreshLogBox.dev.test.js

@@ -705,12 +705,14 @@ test('unterminated JSX', async () => {
   await cleanup()
 })
 
-test('Module not found', async () => {
-  const [session, cleanup] = await sandbox()
-
-  await session.patch(
-    'index.js',
-    `import Comp from 'b'
+// Module trace is only available with webpack 5
+if (!process.env.NEXT_PRIVATE_TEST_WEBPACK4_MODE) {
+  test('Module not found', async () => {
+    const [session, cleanup] = await sandbox()
+
+    await session.patch(
+      'index.js',
+      `import Comp from 'b'
       export default function Oops() {
         return (
           <div>
@@ -719,23 +721,28 @@ test('Module not found', async () => {
         )
       }
     `
-  )
+    )
 
-  expect(await session.hasRedbox(true)).toBe(true)
+    expect(await session.hasRedbox(true)).toBe(true)
 
-  const source = await session.getRedboxSource()
-  expect(source).toMatchInlineSnapshot(`
+    const source = await session.getRedboxSource()
+    expect(source).toMatchInlineSnapshot(`
     "./index.js:1:0
     Module not found: Can't resolve 'b'
     > 1 | import Comp from 'b'
       2 |       export default function Oops() {
       3 |         return (
-      4 |           <div>"
-  `)
+      4 |           <div>
+    
+    Import trace for requested module:
+    ./pages/index.js
 
-  await cleanup()
-})
+    https://nextjs.org/docs/messages/module-not-found"
+  `)
 
+    await cleanup()
+  })
+}
 test('conversion to class component (1)', async () => {
   const [session, cleanup] = await sandbox()
 
@@ -1634,3 +1641,56 @@ test('_document syntax error shows logbox', async () => {
   expect(await session.hasRedbox()).toBe(false)
   await cleanup()
 })
+
+// Module trace is only available with webpack 5
+if (!process.env.NEXT_PRIVATE_TEST_WEBPACK4_MODE) {
+  test('Node.js builtins', async () => {
+    const [session, cleanup] = await sandbox(
+      undefined,
+      new Map([
+        [
+          'node_modules/my-package/index.js',
+          `
+          const dns = require('dns')
+          module.exports = dns
+        `,
+        ],
+        [
+          'node_modules/my-package/package.json',
+          `
+          {
+            "name": "my-package",
+            "version": "0.0.1"
+          }
+        `,
+        ],
+      ]),
+      undefined,
+      /ready - started server on/i
+    )
+
+    await session.patch(
+      'index.js',
+      `
+      import pkg from 'my-package'
+
+      export default function Hello() {
+        return (pkg ? <h1>Package loaded</h1> : <h1>Package did not load</h1>)
+      }
+    `
+    )
+    expect(await session.hasRedbox(true)).toBe(true)
+    expect(await session.getRedboxSource()).toMatchInlineSnapshot(`
+        "./node_modules/my-package/index.js:2:0
+        Module not found: Can't resolve 'dns'
+        
+        Import trace for requested module:
+        ./index.js
+        ./pages/index.js
+        
+        https://nextjs.org/docs/messages/module-not-found"
+  `)
+
+    await cleanup()
+  })
+}