Comprehensive Guide to Fixing "Module not found: can't resolve popper.js" Error in React Projects with Bootstrap

Error Context and Root Cause Analysis

When integrating Bootstrap into React development environments, developers frequently encounter the compilation error "Module not found: can't resolve popper.js". This issue stems from Bootstrap's dependency management mechanism, particularly how its JavaScript components rely on third-party libraries.

Bootstrap Dependency Structure Explained

Bootstrap 4 employs a peer dependency model for handling external libraries required by its JavaScript functionality. Specifically, Popper.js is essential for Bootstrap's interactive components like popovers and tooltips, but Bootstrap doesn't bundle this library internally. This design allows developers to optionally install JavaScript dependencies based on actual needs—if a project only requires Bootstrap's CSS styling, these JavaScript libraries can be omitted.

In the provided code example:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import 'bootstrap/dist/css/bootstrap.css';
import './index.css';

global.jQuery = require('jquery');
require('bootstrap');

When require('bootstrap') executes, Bootstrap attempts to load Popper.js. If this library isn't installed, the aforementioned error is triggered. jQuery similarly requires separate installation as a peer dependency.

Solution: Installing the Correct Popper Package

Depending on the Bootstrap version used in your project, different Popper packages must be installed:

Bootstrap 4 Solution

For projects using Bootstrap 4, install the complete Popper.js library:

npm install popper.js --save

This command adds Popper.js to the dependencies section of your project's package.json file, ensuring proper resolution of Bootstrap's dependencies during build processes.

Bootstrap 5 Solution

Bootstrap 5 changes its Popper dependency requirements, no longer needing the full Popper.js but rather the lighter Popper.js Core:

npm install @popperjs/core --save

This shift reflects frontend libraries' evolution toward modularity and on-demand loading. @popperjs/core provides Popper's core functionality without unnecessary add-ons, better suiting modern web application needs.

Dependency Management Best Practices

When managing Bootstrap dependencies in React projects, follow these steps:

1. Identify the Bootstrap version used (4.x or 5.x)
2. Install the corresponding Popper package based on the version
3. Ensure jQuery is installed (required for Bootstrap 4, optional for Bootstrap 5)
4. Properly configure global variables and import order in entry files

For Bootstrap 4 projects, the complete dependency installation command should be:

npm install bootstrap jquery popper.js --save

For Bootstrap 5 projects, if jQuery isn't needed, install only:

npm install bootstrap @popperjs/core --save

Error Troubleshooting and Verification

After installation, verify the issue is resolved by:

1. Checking if package.json contains the correct dependencies
2. Running npm list popper.js or npm list @popperjs/core to confirm successful installation
3. Restarting the development server and checking if compilation errors disappear
4. Testing Bootstrap's JavaScript components (like modals and dropdowns) for proper functionality

Architectural Design Considerations

Bootstrap's peer dependency design has several advantages:

• Flexibility: Allows developers to use only CSS portions, reducing unnecessary JavaScript bundle size
• Version Control: Enables independent control over dependency library versions, avoiding conflicts
• Tree-Shaking Optimization: Modern bundlers can better perform tree-shaking to eliminate unused code

However, this design increases configuration complexity, especially for beginners. Understanding peer dependency concepts is crucial for modern frontend development, with similar dependency patterns appearing in other popular frameworks.

Compatibility Considerations

When migrating projects or upgrading Bootstrap versions, note:

• Bootstrap 4 to 5 upgrades involve Popper dependency changes
• Some third-party React Bootstrap components may have specific Popper version requirements
• In team projects, document these dependencies clearly

By properly understanding and managing these dependencies, developers can leverage Bootstrap's powerful features while maintaining project maintainability and performance optimization.