esbuild-plugin-version-injector

An esbuild plugin to inject your application's version number or today's date into your files

This plugin was inspired by rollup-plugin-version-injector

Table of Contents

esbuild-plugin-version-injector

Description

There are many ways to export a constant that holds your package variable, from loading your own package.json through a fs.readFile, importing the package.json directly, or manually updating a constant on every bump. However all of these have their downsides, and this plugin aims to solve that.

fs.readFile is an addition file operation that the end-user's system has to deal with and causes slow downs.
importing the package.json directly can cause issues with interoperability between CJS and ESM as the latter requires JSON assertions.
- Alternatively when using a bundler that inlines the package.json code that means the bundle ends up increasing in size unnecessarily for only having to include the version field
Manually updating a constant on every bump is a chore and can be easily forgotten.

This plugin aims to solve all of these issues by injecting the version number and/or today's date directly into your built JavaScript files during the bundling step provided by esbuild. This plugin can therefore work with many of the famous bundlers such as esbuild directly, tsup, vite, or other bundlers that also use esbuild under the hood.

Installation

You can use the following command to install this package, or replace npm install -D with your package manager of choice.

npm install -D esbuild-plugin-version-injector

Usage

With `esbuild`

Add the plugin to your esbuild options, i.e.:

const esbuild = require('esbuild');
const { resolve } = require('path');
const {
  esbuildPluginVersionInjector
} = require('esbuild-plugin-version-injector');

await esbuild.build({
  format: 'cjs',
  entryPoints: [resolve(__dirname, './src/index.ts')],
  outdir: resolve(__dirname, './dist'),
  plugins: [esbuildPluginVersionInjector()]
});

With `tsup`

Add the plugin to your tsup.config.ts, i.e.:

import { defineConfig } from 'tsup';
import { resolve } from 'path';
import { esbuildPluginVersionInjector } from 'esbuild-plugin-version-injector';

await defineConfig({
  format: ['cjs'],
  entry: ['./src/index.ts'],
  outDir: './dist',
  esbuildPlugins: [esbuildPluginVersionInjector()]
});

File Injection examples

JavaScript / TypeScript

/**
 * The current version that you are currently using.
 *
 * Note to developers: This needs to explicitly be `string` so it is not typed as a "const string" that gets injected by esbuild
 */
// eslint-disable-next-line @typescript-eslint/no-inferrable-types
export const version: string = '[VI]{{inject}}[/VI]';

JSON

{
  "version": "[VI]{{inject}}[/VI]"
}

CSS

.myClass {
  content: '[VI]{{inject}}[/VI]';
}

A note regarding using CSS preprocessors (SASS / LESS / Stylus / etc): When using a CSS preprocessor you might be using an esbuild plugin like esbuild-sass-plugin. This causes the CSS to be processed before this plugin can inject the version number and at the moment esbuild now will no longer pass the file to be processed by this plugin. To solve this you will have to build your code twice with esbuild, once with the CSS preprocessor plugin and once with this plugin. This can be done by using the build function twice, or by using the buildSync function twice. An example of this can be found at the test to cover this case here.

Text

This document is for version [VI]{{inject}}[/VI]

Options

The plugin accepts the following options:

versionOrCurrentDate: One of 'version', 'current-date' or one of the entries of the VersionOrCurrentDate enum. Defaults to 'version'. This determines what format to inject into your built files. If this is set to current-date then the current date in the ISO 8601 will be inserted instead of the package.json version.
injectTag: The tag that should be searched for and replaced across your code. Defaults to '[VI]{{inject}}[/VI]'. This can be any string, but it is recommended to use something that is unlikely to be used in your code.
packageJsonPath The relative path to your package.json file. Defaults to './package.json'. This is used to read the version number from your package.json file.
filter: This is an advanced use-case option with which you can filter which files esbuild should apply this plugin on
namespace: This is an advanced use-case option through which the esbuild namespace can be configured

Buy us some doughnuts

Favware projects are and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Ko-fi, Paypal, Patreon, GitHub Sponsorships, and various cryptocurrencies. You can use the buttons below to donate through your method of choice.

Donate With	Address
Ko-fi	Click Here
Patreon	Click Here
PayPal	Click Here
GitHub Sponsors	Click Here
Bitcoin	`1E643TNif2MTh75rugepmXuq35Tck4TnE5`
Ethereum	`0xF653F666903cd8739030D2721bF01095896F5D6E`
LiteCoin	`LZHvBkaJqKJRa8N7Dyu41Jd1PDBAofCik6`

Contributors

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed!