Async Code Splitting¶

When you require/import a JavaScript or CSS module, Webpack compiles that code into the final JavaScript or CSS file. Usually, that’s exactly what you want. But what if you only need to use a piece of code under certain conditions? For example, what if you want to use video.js to play a video, but only once a user has clicked a link:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// assets/js/app.js

import $ from 'jquery';
// a fictional "large" module (e.g. it imports video.js internally)
import VideoPlayer from './components/VideoPlayer';

$('.js-open-video').on('click', function() {
    // use the larger VideoPlayer module
    const player = new VideoPlayer('some-element');
});

In this example, the VideoPlayer module and everything it imports will be packaged into the final, built JavaScript file, even though it may not be very common for someone to actually need it. A better solution is to use dynamic imports: load the code via AJAX when it’s needed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// assets/js/app.js

import $ from 'jquery';

$('.js-open-video').on('click', function() {
    // you could start a loading animation here

    // use import() as a function - it returns a Promise
    import('./components/VideoPlayer').then(({ default: VideoPlayer }) => {
        // you could stop a loading animation here

        // use the larger VideoPlayer module
        const player = new VideoPlayer('some-element');

    }).catch(error => 'An error occurred while loading the component');
});

By using import() like a function, the module will be downloaded async and the .then() callback will be executed when it’s finished. The VideoPlayer argument to the callback will be the loaded module. In other words, it works like normal AJAX calls! Behind the scenes, Webpack will package the VideoPlayer module into a separate file (e.g. 0.js) so it can be downloaded. All the details are handled for you.

The { default: VideoPlayer } part may look strange. When using the async import, your .then() callback is passed an object, where the actual module is on a .default key. There are reasons why this is done, but it does look quirky. The { default: VideoPlayer } code makes sure that the VideoPlayer module we want is read from this .default property.

For more details and configuration options, see dynamic imports on Webpack’s documentation.