Webpack Version File Plugin

0.1.7 · abandoned · verified Wed Apr 22

This Webpack plugin, `webpack-version-file`, generates a file (typically `version.txt`) containing crucial project metadata such as the package name, version number, and build date during the Webpack compilation process. It is particularly useful for tracking which version of an application is deployed in various environments, aiding in debugging and support. The plugin, currently at version `0.1.7` (last updated in 2017), is considered abandoned. It utilizes EJS for templating, allowing extensive customization of the output file's content using data from `package.json`, predefined variables like `buildDate`, and custom data passed via its options. Its simplicity and direct integration into the Webpack build lifecycle were its key differentiators, though its lack of maintenance is a significant concern for modern Webpack and Node.js environments.

Common errors

```
TypeError: Class constructor VersionFile cannot be invoked without 'new'
```
cause Attempting to call the plugin constructor `VersionFile()` directly without the `new` keyword.

fix Ensure you instantiate the plugin using `new VersionFile()` within your Webpack plugins array in `webpack.config.js`.
```
Module not found: Error: Can't resolve 'webpack-version-file' in '...'
```
cause The `webpack-version-file` package is not installed as a development dependency, or Webpack cannot locate it in `node_modules`.

fix Run `npm install --save-dev webpack-version-file` or `yarn add --dev webpack-version-file` in your project's root directory to install the package.
```
Error: ENOENT: no such file or directory, open '...' (for 'package' or 'template' option)
```
cause The path specified for the `package` or `template` option in the plugin configuration is incorrect, or the file does not exist at the given path.

fix Verify that the file paths provided to the `package` and `template` options are correct and accessible. It's best practice to use `path.resolve(__dirname, 'file.json')` for robust, absolute path resolution.

Warnings

gotcha The 'webpack-version-file' package has not been updated in over seven years (last release 0.1.7 in 2017) and is considered abandoned. It may not be compatible with recent Webpack versions (v5+) or modern Node.js environments, and will not receive security patches or bug fixes.
Fix: Consider alternative solutions for injecting version information, such as Webpack's built-in `webpack.DefinePlugin` for in-bundle definitions, or more actively maintained version file generation plugins. Alternatively, fork the repository and maintain it yourself if its specific features are critical.
gotcha This plugin is a CommonJS module and uses `require()`. Directly importing it using ES Modules `import` syntax in a pure ESM environment may lead to errors without proper Webpack configuration (e.g., using `resolve.fallback` for Node.js built-ins) or a CommonJS wrapper.
Fix: Always use `const VersionFile = require('webpack-version-file');` in your Webpack configuration file. Ensure your Webpack configuration is set up to correctly handle CommonJS modules, especially if your project primarily uses ESM.
gotcha The plugin relies on EJS templating. Ensure template syntax is correct, and all variables referenced (e.g., `<%= variable %>`) are either derived from `package.json`, predefined (`buildDate`), or explicitly passed via the `data` option. Unresolved variables will render as empty or undefined in the output.
Fix: Verify EJS template syntax is correct. Cross-reference all template variables with the fields available in your `package.json`, the predefined `buildDate`, and any custom data provided in the `data` option. Temporarily simplify your template or log the `data` object to debug rendering issues.

Install

npm install webpack-version-file npm
yarn add webpack-version-file yarn
pnpm add webpack-version-file pnpm

Imports

VersionFile
wrong:
```
import VersionFile from 'webpack-version-file';
```
correct:
```
const VersionFile = require('webpack-version-file');
```
This plugin is distributed as a CommonJS module. Direct ESM import via 'import' statements may not work without a CommonJS wrapper or specific bundler configuration in modern pure ESM environments.
new VersionFile()
wrong:
```
VersionFile();
```
correct:
```
new VersionFile({ output: './build/version.txt' })
```
The plugin is a class and must be instantiated with the 'new' keyword when added to the Webpack plugins array.

Quickstart

Demonstrates how to configure `webpack-version-file` in a Webpack setup, generating a `version.txt` file alongside your bundle with project metadata and custom environment data using a custom EJS template.

const path = require('path');
const VersionFile = require('webpack-version-file');

module.exports = {
  entry: './src/index.js', // Your application's entry point
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new VersionFile({
      output: path.resolve(__dirname, 'dist', 'version.txt'),
      package: path.resolve(__dirname, 'package.json'),
      template: './version.ejs', // Path to your custom EJS template file
      data: {
        buildUser: process.env.USER ?? 'anonymous',
        gitCommit: process.env.GITHUB_SHA ?? 'N/A'
      },
      verbose: true,
    })
  ],
  mode: 'development' // or 'production'
};

// To run this example, create a file named 'version.ejs' in your project root:
// <%= name %>@<%= version %>
// Built by: <%= buildUser %>
// Commit: <%= gitCommit %>
// Build date: <%= buildDate %>
// License: <%= license %>
// Environment: <%= process.env.NODE_ENV ?? 'development' %>

view raw JSON →