Prebuild Webpack Plugin

Common errors

• TypeError: (0, prebuild_webpack_plugin_1.PrebuildWebpackPlugin) is not a constructor

  cause Attempting to import `PrebuildWebpackPlugin` as a named export after v1.0.0, when it became a default export.
  fix Update your import statement to `import PrebuildPlugin from 'prebuild-webpack-plugin';` for ESM or `const PrebuildPlugin = require('prebuild-webpack-plugin');` for CommonJS.

• Error: Cannot find module '@hashicorp/prebuild-webpack-plugin'

  cause The package name changed in v1.0.0, but the old scoped package name is still being referenced.
  fix Update your `package.json` to use `prebuild-webpack-plugin` and ensure all import/require statements also use the new package name.

• 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.

  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.
  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.

Warnings

• breaking 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.
  Fix: Update your `package.json` dependencies and `import`/`require` statements to use the new package name: `prebuild-webpack-plugin`.
• breaking 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`.
  Fix: Change your import statement from `import { PrebuildWebpackPlugin } from '...'` to `import PrebuildPlugin from '...'` for ESM, or `const PrebuildPlugin = require('...')` for CommonJS.
• gotcha When using symlinks with the `files` matching option, unusual behavior could occur prior to v1.1.0, specifically regarding how file paths were resolved.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install prebuild-webpack-plugin npm
• yarn add prebuild-webpack-plugin yarn
• pnpm add prebuild-webpack-plugin pnpm

Imports

• PrebuildPlugin
  wrong:

  import { PrebuildWebpackPlugin } from 'prebuild-webpack-plugin';

  correct:

  import PrebuildPlugin from 'prebuild-webpack-plugin';

  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.
• PrebuildPlugin (CommonJS)
  wrong:

  const { PrebuildWebpackPlugin } = require('@hashicorp/prebuild-webpack-plugin');

  correct:

  const PrebuildPlugin = require('prebuild-webpack-plugin');

  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.

Quickstart

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.

const PrebuildPlugin = require('prebuild-webpack-plugin');
const path = require('path');
const fs = require('fs/promises');

module.exports = {
  // ... webpack config ...
  plugins: [
    new PrebuildPlugin({
      build: async (compiler, compilation, matchedFiles) => {
        console.log('Prebuild phase started!');
        // Example: Read and log content of matched markdown files
        for (const file of matchedFiles) {
          const content = await fs.readFile(file, 'utf8');
          console.log(`Prebuilt content of ${path.basename(file)}:\n${content.substring(0, 100)}...`);
        }
        console.log('Prebuild phase completed!');
      },
      watch: async (compiler, compilation, changedFile) => {
        console.log(`File changed in watch mode: ${changedFile}`);
        // Example: Process the changed file on each rebuild
        if (changedFile.endsWith('.md')) {
          const content = await fs.readFile(changedFile, 'utf8');
          console.log(`Watch-mode processing for ${path.basename(changedFile)}:\n${content.substring(0, 50)}...`);
        }
      },
      files: { 
        pattern: '**/*.md', 
        options: { cwd: path.resolve(__dirname, 'src') }, 
        addFilesAsDependencies: true 
      },
      clearCacheOnUpdate: false
    }),
  ],
};