Externals

Exclude dependencies from the output bundles

The externals configuration option provides a way to exclude dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer’s environment.

Basic Configuration

webpack.config.js

module.exports = {
  externals: {
    react: 'React',
    jquery: 'jQuery'
  }
};

Use Cases

• Libraries: When building a library, you don’t want to bundle dependencies
• CDN: Using dependencies from a CDN instead of bundling them
• Micro-frontends: Sharing dependencies between multiple apps
• Node.js: Excluding Node.js built-in modules

Externals Option

externals · string | object | function | RegExp | array

Define dependencies that should not be bundled.

externals: {
  lodash: 'lodash',
  react: 'React'
}

String Format

webpack.config.js

module.exports = {
  externals: {
    // Property: Module to exclude
    // Value: Global variable name
    react: 'React',
    'react-dom': 'ReactDOM',
    jquery: 'jQuery',
    lodash: '_'
  }
};

In your code:

import React from 'react'; // Uses global window.React
import $ from 'jquery'; // Uses global window.jQuery

Different Module Types

CommonJS

externals: {
  react: 'commonjs react' // require('react')
}

CommonJS2

externals: {
  react: 'commonjs2 react' // module.exports = require('react')
}

AMD

externals: {
  react: 'amd react' // define(['react'], ...)
}

UMD

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

Module (ESM)

externals: {
  react: 'module react' // import from 'react'
}

Array Format

Externalize multiple modules:

webpack.config.js

module.exports = {
  externals: ['react', 'react-dom', 'lodash']
};

This assumes the global variable name matches the module name.

RegExp Format

Match modules with a regular expression:

webpack.config.js

module.exports = {
  externals: /^(@company\/.+|lodash)$/
};

Example: Externalize all @company/* packages:

externals: /^@company\//

Function Format

Dynamically determine externals:

webpack.config.js

module.exports = {
  externals: function({ context, request }, callback) {
    // Externalize all modules in node_modules
    if (/^[a-z\-0-9]+$/.test(request)) {
      return callback(null, 'commonjs ' + request);
    }
    
    // Not an external
    callback();
  }
};

Async function:

externals: async function({ context, request }) {
  if (request === 'special-module') {
    return 'commonjs special-module';
  }
}

Combined Formats

Use multiple formats together:

webpack.config.js

module.exports = {
  externals: [
    {
      // Specific modules
      react: 'React',
      lodash: '_'
    },
    // All modules matching pattern
    /^@company\//,
    // Dynamic function
    function({ request }, callback) {
      if (request.startsWith('legacy-')) {
        return callback(null, 'var ' + request);
      }
      callback();
    }
  ]
};

Externals Type

externalsType · string

Specify the default type for externals.

externalsType: 'commonjs' // or 'var', 'module', 'umd', etc.

Options: 'var', 'module', 'assign', 'this', 'window', 'self', 'global', 'commonjs', 'commonjs2', 'amd', 'umd', 'jsonp', 'system', 'promise', 'import', 'script'

webpack.config.js

module.exports = {
  externalsType: 'commonjs',
  externals: {
    react: 'react' // Treated as 'commonjs react'
  }
};

Externals Presets

externalsPresets · object

Enable presets for common external scenarios.

externalsPresets: {
  node: true, // Externalize Node.js built-ins
  web: true,  // Externalize http(s):// imports
  electron: true,
  electronMain: true,
  electronPreload: true,
  electronRenderer: true
}

Node.js Preset

webpack.config.js

module.exports = {
  externalsPresets: {
    node: true // Treats node built-ins as externals
  }
};

Web Preset

webpack.config.js

module.exports = {
  externalsPresets: {
    web: true // Treats http(s):// and std: imports as externals
  }
};

Common Patterns

Library Development

webpack.config.js

module.exports = {
  externals: {
    react: {
      root: 'React',
      commonjs2: 'react',
      commonjs: 'react',
      amd: 'react'
    },
    'react-dom': {
      root: 'ReactDOM',
      commonjs2: 'react-dom',
      commonjs: 'react-dom',
      amd: 'react-dom'
    }
  },
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd'
    }
  }
};

Node.js Application

Externalize all node_modules:

webpack.config.js

const nodeExternals = require('webpack-node-externals');

module.exports = {
  target: 'node',
  externalsPresets: { node: true },
  externals: [nodeExternals()]
};

Manual approach:

webpack.config.js

const fs = require('fs');

module.exports = {
  target: 'node',
  externals: [
    function ({ context, request }, callback) {
      if (/node_modules/.test(context)) {
        return callback(null, 'commonjs ' + request);
      }
      callback();
    }
  ]
};

CDN Dependencies

webpack.config.js

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM'
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: 'src/index.html',
      cdn: {
        js: [
          'https://unpkg.com/react@18/umd/react.production.min.js',
          'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js'
        ]
      }
    })
  ]
};

HTML template:

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="root"></div>
  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
</body>
</html>

Micro-Frontends

webpack.config.js

const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'app1',
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true }
      }
    })
  ],
  externals: {
    // Additional externals if needed
  }
};

Electron Application

webpack.config.js

module.exports = {
  target: 'electron-renderer',
  externalsPresets: {
    electron: true,
    electronRenderer: true
  },
  externals: {
    // Additional electron modules
    'electron-store': 'commonjs electron-store'
  }
};

Dynamic Import Externals

webpack.config.js

module.exports = {
  externalsType: 'import',
  externals: {
    'big-library': 'https://cdn.example.com/big-library.js'
  }
};

Usage:

import('big-library').then(lib => {
  // Use library
});

Layer-Specific Externals

webpack.config.js

module.exports = {
  externals: {
    byLayer: {
      'client': {
        react: 'React'
      },
      'server': {
        express: 'commonjs express'
      }
    }
  }
};

Testing Externals

When testing, you may need to mock externals:

webpack.test.js

module.exports = {
  externals: {
    // No externals for tests - bundle everything
  }
};

Or use Jest configuration:

jest.config.js

module.exports = {
  moduleNameMapper: {
    '^react$': '<rootDir>/node_modules/react'
  }
};

Troubleshooting

External Not Found

Make sure the external is available in the runtime environment:

<!-- Include before your bundle -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="your-bundle.js"></script>

Wrong Global Name

Check the library’s documentation for the correct global variable name:

// Wrong
externals: { react: 'react' }

// Correct
externals: { react: 'React' }

TypeScript Externals

Install type definitions for externalized packages:

npm install --save-dev @types/react @types/react-dom