webpack-split-by-path

2.0.0 verified Sat Apr 25 auth: no javascript maintenance

Webpack plugin to split an entry bundle into multiple smaller bundles based on absolute file paths. v2.0.1 is the latest stable version, compatible with webpack 2. v1.0.0 supports webpack 1. This plugin was largely superseded by webpack's built-in splitChunks in webpack 4+. It is based on split-by-name-webpack-plugin but uses absolute paths instead of module names. Useful for vendor bundle extraction in legacy webpack 1/2 projects.

Common errors

error Module not found: Error: Cannot resolve module 'webpack-split-by-path' ↓

cause Missing npm install or wrong package name.

fix

Run 'npm install webpack-split-by-path' and ensure it's in package.json dependencies.

error TypeError: SplitByPathPlugin is not a constructor ↓

cause Incorrect import: using named export instead of default export.

fix

Use 'const SplitByPathPlugin = require("webpack-split-by-path")' instead of destructuring.

error Configuration file found but error: Cannot find module 'webpack-split-by-path' ↓

cause Global webpack install not finding local plugin.

fix

Run webpack from the project directory with local installation, or use npx webpack.

error Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Plugin instantiation options are incorrect, such as wrong 'chunks' array structure.

fix

Ensure chunks are an array of { name: string, path: string } objects with absolute paths.

error WebpackOptionsValidationError: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Plugin configuration option 'ignoreChunks' is misspelled or used incorrectly.

fix

Use 'ignoreChunks' as a string or array of chunk names to ignore.

Warnings

deprecated Webpack 4+ recommends using built-in splitChunks optimization instead of this plugin. This plugin is a maintenance-only adaptation for webpack 2. ↓

fix Use optimization.splitChunks in webpack.config.js instead.

breaking The plugin configuration uses absolute paths, which can break when moving the project to a different directory or CI environment. ↓

fix Use path.resolve with __dirname to define absolute paths relative to project root.

gotcha The 'ignore' option expects absolute paths, not relative. Relative paths will silently fail to ignore modules. ↓

fix Use path.join(__dirname, 'relative/path') for ignore paths.

gotcha Multiple chunks can match the same module; only the first matching bucket is used. Order of buckets matters. ↓

fix Place more specific paths before broader paths in the chunks array.

deprecated Plugin is not actively maintained. Last release was 2.0.1 in 2017. ↓

fix Consider migrating to webpack 4+ splitChunks.

Install

npm install webpack-split-by-path

yarn add webpack-split-by-path

pnpm add webpack-split-by-path

Imports

SplitByPathPlugin

wrong

import SplitByPathPlugin from 'webpack-split-by-path';

correct

const SplitByPathPlugin = require('webpack-split-by-path');

Plugin uses CommonJS exports; no ES module or TypeScript types exist.

SplitByPathPlugin

wrong

const { SplitByPathPlugin } = require('webpack-split-by-path');

correct

const { SplitByPathPlugin } = require('webpack-split-by-path');

Named import works but default import is used in docs; both are the same object.

Quickstart

Shows a minimal webpack configuration using SplitByPathPlugin to separate node_modules into a vendor chunk and a components chunk from the app entry.

// Example webpack.config.js using webpack-split-by-path
const path = require('path');
const SplitByPathPlugin = require('webpack-split-by-path');

module.exports = {
  context: __dirname,
  entry: {
    app: './app.js'
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name]-[chunkhash].js',
    chunkFilename: '[name]-[chunkhash].js'
  },
  plugins: [
    new SplitByPathPlugin([
      {
        name: 'vendor',
        path: path.resolve(__dirname, 'node_modules')
      },
      {
        name: 'components',
        path: path.resolve(__dirname, 'src/components')
      }
    ], {
      manifest: 'app-entry'
    })
  ]
};