Why do I have to list my peerDependencies as externals in the webpack config when creating a package?

Question

I was creating an npm package in React, using create-react-app. Since react and react-dom are assumed to be in the host project, I listed them as peerDependencies and devDependencies in my package.json.

I learned that this way the two still get bundled, and to prevent that I have to list them in the externals of the webpack config, which I did succesfully:

externals: {        
  react: {          
      commonjs: 'react',          
      commonjs2: 'react',          
      amd: 'React',          
      root: 'React',      
  },      
  'react-dom': {          
      commonjs: 'react-dom',          
      commonjs2: 'react-dom',          
      amd: 'ReactDOM',          
      root: 'ReactDOM',      
  },  
},

My question is: why do I have to go through this second step? Shouldn't listing them as peerDependencies be sufficient? And if not, how do peerDependencies differ from the regular dependencies in that case?

Answer 1

Peer dependencies are understood by npm, externals are understood by webpack. Both mean the same thing, but are dealt with by entirely different pieces of software.

While running npm install will not install any peer dependencies, webpack will still try to walk the dependency tree to try and find them if they are referenced in the code. Marking them as external tells webpack to explicitly ignore them and not attempt to walk that dependency branch, even if those peer dependencies have been installed.