Awesome
<div align="center">esbuild-plugin-version-injector
An esbuild plugin to inject your application's version number or today's date into your files
</div>This plugin was inspired by rollup-plugin-version-injector
Table of Contents
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 theVersionOrCurrentDate
enum. Defaults to'version'
. This determines what format to inject into your built files. If this is set tocurrent-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!
<a href="https://github.com/favware/esbuild-plugin-version-injector/graphs/contributors"> <img src="https://contrib.rocks/image?repo=favware/esbuild-plugin-version-injector" /> </a>