Webpack Plugin for Linked Package Builds

0.4.0 · active · verified Tue Apr 21

This webpack plugin automates the build process for symlinked packages within `node_modules`, typically created using `npm link` or `yarn link`. Designed to streamline local development workflows, it ensures that any changes made to a linked package with a build step (e.g., TypeScript compilation, Babel transpilation) are automatically reflected in the consuming project's webpack compilation without manual intervention. The current stable version is `0.4.0`. Its primary differentiator is solving the common problem of forgetting to rebuild local packages during active development, providing a hands-off solution by integrating directly into the webpack build cycle. This package targets a specific niche within front-end and full-stack development that heavily relies on local package linking for monorepos or component library development.

Common errors

```
Error: Script 'build' not found in package 'your-linked-package'
```
cause The linked package 'your-linked-package' does not have a 'build' script defined in its `package.json` file, but the plugin tried to execute it.

fix Add a 'build' script to the `scripts` section of `your-linked-package/package.json`, or configure the `webpack-build-linked-packages` plugin with a different `scriptName` that *does* exist in all relevant linked packages (e.g., `new WebpackBuildLinkedPackages({ scriptName: 'prepare' })`).
```
Webpack compilation fails without a clear error from the plugin, but linked package changes aren't reflected.
```
cause The plugin might not be correctly configured, or the linked package itself isn't properly symlinked or its build script is not working as expected when run independently.

fix 1. Double-check that `new WebpackBuildLinkedPackages()` is included in your `plugins` array in `webpack.config.js`. 2. Verify `npm link` or `yarn link` created actual symlinks in `node_modules`. 3. Manually run `npm run <scriptName>` (e.g., `npm run build`) in your linked package's directory to ensure its build script works standalone.

Warnings

gotcha The plugin runs an `npm run-script` command. If the specified `scriptName` does not exist in a linked package's `package.json`, it will result in an error during the webpack compilation. This can halt your build process.
Fix: Ensure all linked packages have the specified `scriptName` (defaulting to 'build') defined in their `scripts` section of `package.json`. If a package doesn't need a build script, you might need to conditionally apply the plugin or ensure a no-op script exists.
gotcha The plugin invokes `npm run-script` for each linked package. If a linked package's build script is slow or resource-intensive, it can significantly increase your webpack compilation times, especially during watch mode or frequent rebuilds.
Fix: Optimize the build scripts within your linked packages for speed. Consider caching strategies or only running essential steps. If performance becomes a critical issue, manually triggering builds for linked packages might be necessary instead of relying on this plugin for every change.
gotcha This plugin only addresses symlinked packages in `node_modules` (e.g., from `npm link` or `yarn link`). It will not run scripts for packages installed via other methods like `file:` protocol in `package.json` or private npm registries without symlinking.
Fix: Verify that your local package dependencies are indeed symlinked in `node_modules`. Use `ls -l node_modules/your-linked-package` to check for symbolic links. If you are using other local dependency management strategies, this plugin may not be suitable.

Install

npm install webpack-build-linked-packages npm
yarn add webpack-build-linked-packages yarn
pnpm add webpack-build-linked-packages pnpm

Imports

WebpackBuildLinkedPackages
wrong:
```
import WebpackBuildLinkedPackages from 'webpack-build-linked-packages';
```
correct:
```
const WebpackBuildLinkedPackages = require('webpack-build-linked-packages');
```
This package is primarily designed for CommonJS environments as indicated by its documentation and usage examples. While Node.js supports ESM, webpack configurations often remain CJS. Directly `import`ing might fail if the consumer's webpack config isn't transpiled for ESM.
Plugin Instance
```
new WebpackBuildLinkedPackages({ scriptName: 'build' })
```
The plugin is instantiated with an options object. The `scriptName` option (defaulting to 'build') specifies which npm script to run in linked packages.

Quickstart

This quickstart demonstrates how to integrate the plugin into a basic webpack configuration, ensuring that `npm link`-ed packages have their `prepare` script executed during the webpack build process.

const WebpackBuildLinkedPackages = require('webpack-build-linked-packages');
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  plugins: [
    new WebpackBuildLinkedPackages({
      // Optionally specify a different script name than 'build'
      scriptName: 'prepare' // Example: run 'npm run prepare' in linked packages
    })
  ],
  // Typical webpack config setup
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

view raw JSON →