Webpack Lazy Loading: Dynamic import() for Code Splitting (2026)

Webpack’s import() is the secret weapon for making your JavaScript applications load faster by splitting your code into smaller chunks that are only loaded when needed.

Imagine a user lands on your e-commerce site. They see the product listings, a few recommended items, and a search bar. That’s the initial load. But what about the checkout process, the user profile settings, or the advanced search filters? These are features the user might never interact with, yet without import(), all that code is bundled up and downloaded upfront, slowing down that initial, crucial page load. import() allows you to say, "Only download the code for the user profile when they actually click on their profile icon."

Here’s how it looks in practice. Let’s say you have a UserProfile component. Instead of a static import:

// Old way: Loads UserProfile code immediately
import UserProfile from './UserProfile';

You use dynamic import():

// New way: Loads UserProfile code only when needed
const loadUserProfile = () => import('./UserProfile');

// Later, when the user clicks a profile button:
document.getElementById('profile-button').addEventListener('click', async () => {
  const UserProfile = await loadUserProfile();
  // Now render the UserProfile component
  render(UserProfile.default); // or UserProfile.component, depending on your export
});

When Webpack sees import('./UserProfile'), it automatically recognizes this as a point for code splitting. It will create a separate JavaScript file (e.g., 123.chunk.js) containing the UserProfile module and its dependencies. The initial bundle will contain a small piece of code that knows how to fetch and load 123.chunk.js on demand.

Webpack’s configuration plays a crucial role here, though often the defaults are quite sensible. The output.chunkFilename option dictates the naming convention for these dynamically imported chunks. For example:

// webpack.config.js
module.exports = {
  // ...
  output: {
    filename: '[name].bundle.js',
    chunkFilename: '[id].[contenthash].chunk.js', // This is key for dynamic imports
  },
  // ...
};

Here, [id] will be a Webpack-assigned ID for the chunk, and [contenthash] ensures that if the chunk’s content changes, its filename changes, helping with browser caching.

The import() syntax is part of the ECMAScript proposal for dynamic imports, and Webpack treats it as a signal to create a new entry point for a chunk. It doesn’t just split based on the import() call itself; it analyzes the entire module graph. If UserProfile imports moment.js and lodash, those dependencies will be included in the 123.chunk.js file. If multiple dynamic imports rely on the same module (e.g., moment.js is also needed by a DatePicker component loaded dynamically elsewhere), Webpack is smart enough to put moment.js into a shared vendor chunk that gets loaded only once.

One of the most powerful aspects of import() is its ability to be used within conditional logic. This allows for highly granular code splitting.

if (userIsAdmin) {
  import('./AdminPanel').then(AdminPanel => {
    // Load admin panel specific features
  });
} else {
  import('./PublicDashboard').then(Dashboard => {
    // Load public dashboard features
  });
}

This means the entire AdminPanel code is only downloaded if userIsAdmin is true.

The import() function returns a Promise. This means you can use async/await or .then() to handle the asynchronous loading of the module. The module that is imported is available as the default export of the resolved Promise, assuming you’re using ES Modules (export default ...). If you’re using module.exports, you’ll access it directly.

It’s not just for components. You can dynamically import any module. This is incredibly useful for loading polyfills only in browsers that need them, or for fetching large libraries like charting tools only when a user navigates to a dashboard page that displays charts.

Consider a scenario where you have a large configuration object or a set of utility functions that are only relevant for a specific user action.

const processOrder = async (orderData) => {
  const orderProcessors = await import('./orderProcessors');
  orderProcessors.validate(orderData);
  orderProcessors.charge(orderData);
  // ...
};

Webpack will create a chunk for ./orderProcessors.js and its dependencies, ensuring that code isn’t present in the initial download.

While import() is great, it’s important to understand what gets bundled together. When you import() a module, Webpack bundles that module and all of its dependencies that are not already present in other loaded chunks. This can sometimes lead to surprisingly large chunks if you’re not careful about your module dependencies. Tools like webpack-bundle-analyzer are invaluable for visualizing what’s inside each chunk and identifying opportunities for further optimization, such as splitting out common libraries into a separate vendors chunk using optimization.splitChunks.

The real magic often happens when you combine import() with routing. Most modern frontend frameworks (React Router, Vue Router, etc.) have built-in support for code-splitting routes. Instead of statically importing your page components, you use dynamic import() within your route definitions.

// Example with React Router
import { BrowserRouter as Router, Route, Switch } from 'react-router-dom';

const HomePage = React.lazy(() => import('./pages/HomePage'));
const AboutPage = React.lazy(() => import('./pages/AboutPage'));

function App() {
  return (
    <Router>
      <Switch>
        <Route exact path="/" component={HomePage} />
        <Route path="/about" component={AboutPage} />
      </Switch>
    </Router>
  );
}

Here, React.lazy is a helper that works with dynamic import() to load components for routes on demand. The browser only downloads the JavaScript for / or /about when the user navigates to that specific URL.

The most common pitfall is forgetting that the dynamically imported module will be fetched over the network. This means you need to handle loading states and potential network errors. The Promise returned by import() allows you to do this gracefully with loading spinners or fallback UI.

The next step is understanding how to optimize these dynamically loaded chunks further, particularly with shared dependencies.