@regru/webpack-babel-multi-target-plugin weekly downloads statistics

webpack-babel-multi-target-plugin

This project, inspired by Phil Walton's article Deploying es2015 Code in Production Today, adds tooling to simplify the additional configuration with a Webpack plugin, BabelMultiTargetPlugin.

Setup and Configuration

Using the plugin requires making a few small changes to your existing webpack configuration:

• Replace any instances of 'babel-loader' with BabelMultiTargetPlugin.loader()

  • Do not use a Loader configuration object here - see Options Reference below for information on customizing options for 'babel-loader'

• Set resolve.mainFields to favor modern ES modules, which allows webpack to load the most modern source possible. There are several intersecting de-facto standards flying around, so this should cover as much as possible:

mainFields: [

  // rxjs and Angular Package Format
  // these are generally shipped as a higher ES language level than `module`
  'es2015',
  'esm2015',
  'fesm2015',

  // current leading de-facto standard - see https://github.com/rollup/rollup/wiki/pkg.module
  'module',

  // previous de-facto standard, superceded by `module`, but still in use by some packages
  'jsnext:main',

  // Angular Package Format - lower ES level
  'esm5',
  'fesm5',

  // standard package.json fields
  'browser',
  'main',
],

• Add an instance of BabelMultiTargetPlugin to the webpack configuration's plugins property

• BabelMultiTargetPlugin does not require any configuration - but can be customized (see Options Reference below)

• Remove any .babelrc - see Options Reference below for setting preset options

• Remove any references to babel-loader from your package.json - it is a direct dependency of webpack-babel-multi-target-plugin, and may cause unexpected issues if there are duplicate instances due to a version mismatch

• TypeScript

  • Loader rules must use BabelMultiTargetPlugin.loader() after your compiler loader (remember, loaders are run bottom to top)
  • Set tsconfig to target es6 or higher

• Vue

  • Replace 'vue-loader' with BabelMultiTargetPlugin.loader('vue-loader')

Upgrading from v1.x

• Change usages of BabelMultiTargetPlugin.loader to BabelMultiTargetPlugin.loader()

Usage with ES6 Dynamic Imports (including Angular "Lazy" Routes)

When using ES6's import(...) syntax, you may use Webpack's built-in chunk naming syntax to control the naming of the resulting chunk:

import(/* webpackChunkName: "my-dynamic-import" */'./some-other-module')

When working with imports that use an expression within the import syntax, BabelMultiTargetPlugin adds the [resource] tag to allow better control over the naming of the resulting chunk. The [resource] tag will be replaced by the relative path of the imported module, minus the file extension.

/*
 * ./src/
 *   - plugins
 *     - a
 *       plugin.js
*      - b
*        plugin.js
 *  
 */

// ./src/loader.js
import(/* webpackChunkName: "[resource]" */`./plugins/${plugin}/plugin.js`)

In the above example, the resulting chunks for the plugin files would be (depending on the target configuration):

• a-plugin.js (legacy bundle for ./src/plugins/a/plugin.js)
• a-plugin.modern.js (modern bundle for ./src/plugins/a/plugin.js)
• b-plugin.js (legacy bundle for ./src/plugins/b/plugin.js)
• b-plugin.modern.js (modern bundle for ./src/plugins/b/plugin.js)

Naming Angular Lazy Routes

Adding the included NamedLazyChunksPlugin will allow similar human-friendly chunk naming for Angular lazy routes:

// webpack.config.js

const BabelMultiTargetPlugin = require('webpack-babel-multi-target-plugin').BabelMultiTargetPlugin
const NamedLazyChunksPlugin =  require('webpack-babel-multi-target-plugin').NamedLazyChunksPlugin

module.exports = {
  ...
  
  plugins: [
    new BabelMultiTargetPlugin(),
    new NamedLazyChunksPlugin(),
  ],
}

NamedLazyChunkPlugin can also be used with plain ES6 Dynamic Imports as an alternative to Webpack's chunk naming syntax.

Configuration Defaults

BabelMultiTargetPlugin does not require any options to be set. The default behavior is:

• Generate "modern" and "legacy" bundles.

• The "modern" bundle assets will have their filenames appended with .modern, while the "legacy" bundle assets will remain the same. This enables these assets to be deployed without breaking anything since it will still have the required polyfills.

• "modern" browsers are the last 2 versions of each browser, excluding versions that don't support <script type="module">

Options Reference…