{"id":15476,"library":"prebuild-webpack-plugin","title":"Prebuild Webpack Plugin","description":"Prebuild Webpack Plugin is a utility designed to execute file processing and I/O operations before a webpack build commences. It currently stands at stable version 1.1.1, with a history of steady, active development and releases addressing issues and improving performance. This plugin distinguishes itself by offering dedicated `build` and `watch` hooks that fire before the initial webpack compilation and on subsequent rebuilds, respectively. It supports file matching via minimatch patterns, allowing for targeted pre-processing. A key feature is the ability to explicitly add matched files to webpack's dependency tree and specific handling for complex build environments like Next.js through the `compilationNameFilter` option, enabling users to optimize for client-side or server-side compilations. It is particularly useful for scenarios requiring data transformation or external resource fetching prior to bundling, providing a flexible interface for such tasks.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/hashicorp/prebuild-webpack-plugin","tags":["javascript","webpack","prebuild","build","watch"],"install":[{"cmd":"npm install prebuild-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add prebuild-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add prebuild-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"As a webpack plugin, webpack itself is a fundamental peer dependency for its operation. It is expected to be provided by the consuming project to avoid duplicate installations and ensure compatibility.","package":"webpack","optional":false}],"imports":[{"note":"Since v1.0.0, the plugin is the default export. Prior to v1.0.0, it was a named export `PrebuildWebpackPlugin` from the scoped package `@hashicorp/prebuild-webpack-plugin`. Ensure you are importing the default export directly.","wrong":"import { PrebuildWebpackPlugin } from 'prebuild-webpack-plugin';","symbol":"PrebuildPlugin","correct":"import PrebuildPlugin from 'prebuild-webpack-plugin';"},{"note":"For CommonJS, the default export of `prebuild-webpack-plugin` is directly assigned. The old `@hashicorp` scoped package and named export are deprecated since v1.0.0.","wrong":"const { PrebuildWebpackPlugin } = require('@hashicorp/prebuild-webpack-plugin');","symbol":"PrebuildPlugin (CommonJS)","correct":"const PrebuildPlugin = require('prebuild-webpack-plugin');"}],"quickstart":{"code":"const PrebuildPlugin = require('prebuild-webpack-plugin');\nconst path = require('path');\nconst fs = require('fs/promises');\n\nmodule.exports = {\n  // ... webpack config ...\n  plugins: [\n    new PrebuildPlugin({\n      build: async (compiler, compilation, matchedFiles) => {\n        console.log('Prebuild phase started!');\n        // Example: Read and log content of matched markdown files\n        for (const file of matchedFiles) {\n          const content = await fs.readFile(file, 'utf8');\n          console.log(`Prebuilt content of ${path.basename(file)}:\\n${content.substring(0, 100)}...`);\n        }\n        console.log('Prebuild phase completed!');\n      },\n      watch: async (compiler, compilation, changedFile) => {\n        console.log(`File changed in watch mode: ${changedFile}`);\n        // Example: Process the changed file on each rebuild\n        if (changedFile.endsWith('.md')) {\n          const content = await fs.readFile(changedFile, 'utf8');\n          console.log(`Watch-mode processing for ${path.basename(changedFile)}:\\n${content.substring(0, 50)}...`);\n        }\n      },\n      files: { \n        pattern: '**/*.md', \n        options: { cwd: path.resolve(__dirname, 'src') }, \n        addFilesAsDependencies: true \n      },\n      clearCacheOnUpdate: false\n    }),\n  ],\n};","lang":"javascript","description":"This quickstart demonstrates how to integrate `PrebuildPlugin` into a webpack configuration. It sets up `build` and `watch` hooks to process markdown files in the `src` directory before the initial build and upon subsequent changes, logging their content. It also configures file matching and adds matched files as webpack dependencies."},"warnings":[{"fix":"Update your `package.json` dependencies and `import`/`require` statements to use the new package name: `prebuild-webpack-plugin`.","message":"The npm package name changed from `@hashicorp/prebuild-webpack-plugin` to `prebuild-webpack-plugin`. Projects using the old package name will fail to resolve the module.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Change your import statement from `import { PrebuildWebpackPlugin } from '...'` to `import PrebuildPlugin from '...'` for ESM, or `const PrebuildPlugin = require('...')` for CommonJS.","message":"The plugin's export method changed from a named export (`PrebuildWebpackPlugin`) to a default export. Incorrect import statements will lead to errors like `TypeError: PrebuildPlugin is not a constructor`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.1.0 or later. If you need to explicitly replicate the old behavior (i.e., resolve the original path of a symlink), pass `realpath: true` to `files.options`.","message":"When using symlinks with the `files` matching option, unusual behavior could occur prior to v1.1.0, specifically regarding how file paths were resolved.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Use `clearCacheOnUpdate: true` only when strictly necessary for dynamic file additions in development. For static file sets or less frequent additions, it's more performant to restart the build process.","message":"Enabling the `clearCacheOnUpdate` option to handle newly added files in watch mode incurs a 'reasonably large performance penalty' because it forces a re-read of the entire file tree on every watch event.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the `compilationNameFilter` option to specify which webpack compilation should execute the plugin's logic. For Next.js, you might pass `'client'` to run only for the client-side build.","message":"In multi-compilation environments like Next.js, the plugin might execute its logic multiple times (e.g., once for the client and once for the server) leading to redundant work.","severity":"gotcha","affected_versions":">=0.0.4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update your import statement to `import PrebuildPlugin from 'prebuild-webpack-plugin';` for ESM or `const PrebuildPlugin = require('prebuild-webpack-plugin');` for CommonJS.","cause":"Attempting to import `PrebuildWebpackPlugin` as a named export after v1.0.0, when it became a default export.","error":"TypeError: (0, prebuild_webpack_plugin_1.PrebuildWebpackPlugin) is not a constructor"},{"fix":"Update your `package.json` to use `prebuild-webpack-plugin` and ensure all import/require statements also use the new package name.","cause":"The package name changed in v1.0.0, but the old scoped package name is still being referenced.","error":"Error: Cannot find module '@hashicorp/prebuild-webpack-plugin'"},{"fix":"For development workflows where new files are frequently added, set `clearCacheOnUpdate: true` in the plugin options. Be aware of the potential performance impact. For production builds or less dynamic scenarios, restart the webpack process after adding new files.","cause":"By default, the plugin caches the file tree from initial bootup. Newly added files are not automatically detected in subsequent watch runs unless `clearCacheOnUpdate` is enabled.","error":"Files added to the watched directory are not being detected by the 'watch' hook, or 'matchedFiles' in 'build' is missing new entries after adding new files without restarting."}],"ecosystem":"npm"}