中文
devexamples
← Debugging Guides

阅读中文版本

Rollup/Rollup-based: Unresolved dependencies warning

Fix Rollup "Unresolved dependencies" warnings by marking externals, adding the node-resolve plugin, and setting the correct output format.

intermediatedebuggingrollupbuildbundler

Symptoms

  • "x" is imported by "y", but could not be resolved
  • The warning repeats and the bundle silently omits a dependency
  • Runtime errors about undefined exports follow the build

Possible causes

  • The dependency is not marked external for a library build
  • The @rollup/plugin-node-resolve plugin is missing
  • A package relies on CommonJS that needs @rollup/plugin-commonjs
  • The entry does not match the tool that wraps Rollup (e.g., Vite config)

Diagnosis steps

Read the import chain in the warning

Interpretation

It shows which file imported the unresolved specifier, localising the dependency.

Add node-resolve to test resolution

Interpretation

If adding the plugin clears the warning, resolution was the gap.

Decide external versus bundled

Interpretation

Libraries should mark peer dependencies external; applications should bundle them.

Root cause

Rollup resolves only relative imports by default. Bare package specifiers are treated as external unless the node-resolve plugin is configured, so they are left unresolved. For CommonJS packages, the commonjs plugin is also required. The warning becomes a runtime error when the omitted dependency is needed at load time.

Fix

Add @rollup/plugin-node-resolve (and commonjs) for application builds, and declare external for library builds so peers are not bundled. Ensure the output format matches consumers, and when using a wrapper like Vite, configure resolution in the wrapper's options rather than a separate Rollup config.

Verify the fix

Rebuild; the "Unresolved dependencies" warnings are gone, the bundle contains the expected modules, and running it produces no undefined-import errors.

Symptoms

Rollup logs "x" is imported by "y", but could not be resolved. The bundle may still emit, then fail at runtime because a dependency was silently excluded.

Diagnosis

Read the import chain and test resolution:

import { nodeResolve } from '@rollup/plugin-node-resolve';
export default { input: 'src/index.js', plugins: [nodeResolve()] };

Fix

Configure resolution or externals:

import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/index.js',
  plugins: [nodeResolve(), commonjs()],
  external: ['react', 'react-dom'],  // for a library
};

Verification

Rebuild; warnings disappear, the bundle includes the intended modules, and loading it produces no undefined-export errors, confirming resolution and externals are correct.

Warnings That Become Outages

Rollup treats unresolved imports as warnings and continues, so a build can succeed while quietly omitting a dependency that only fails when that code runs. Treating these warnings as errors in CI prevents shipping a bundle with a missing module. The distinction between external and bundled matters for libraries: marking a peer dependency external keeps the bundle lean, but falsely marking an application dependency external defers the failure to runtime. Reading the import chain in the warning tells you which file introduced the dependency and whether it belongs in the bundle at all.