Externals - webpack

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

Documentation Index

​Basic Configuration

​Use Cases

​Externals Option

​String Format

​Different Module Types

​CommonJS

​CommonJS2

​AMD

​UMD

​Module (ESM)

​Array Format

​RegExp Format

​Function Format

​Combined Formats

​Externals Type

​Externals Presets

​Node.js Preset

​Web Preset

​Common Patterns

​Library Development

​Node.js Application

​CDN Dependencies

​Micro-Frontends

​Electron Application

​Dynamic Import Externals

​Layer-Specific Externals

​Testing Externals

​Troubleshooting

​External Not Found

​Wrong Global Name

​TypeScript Externals

Basic Configuration

Use Cases

Externals Option

String Format

Different Module Types

CommonJS

CommonJS2

AMD

UMD

Module (ESM)

Array Format

RegExp Format

Function Format

Combined Formats

Externals Type

Externals Presets

Node.js Preset

Web Preset

Common Patterns

Library Development

Node.js Application

CDN Dependencies

Micro-Frontends

Electron Application

Dynamic Import Externals

Layer-Specific Externals

Testing Externals

Troubleshooting

External Not Found

Wrong Global Name

TypeScript Externals