[English] | Русский

@37bytes/vite-build-time-environment

This plugin allows injecting version, branch, and commit information into code during build time. This is particularly useful for:

• Version tracking in production environment
• Debugging issues across different builds
• Automating release process

Installation

npm install @37bytes/vite-build-time-environment

Usage

// vite.config.ts
import { defineConfig } from 'vite';
import createBuildTimeIdentifiersSupportPlugin from '@37bytes/vite-build-time-environment';
import packageInfo from '../package.json';

// Other parameters are pulled from environment variables
const buildTimeIdentifiersSupportPlugin = createBuildTimeIdentifiersSupportPlugin({
    packageName: packageInfo.name,
    packageVersion: packageInfo.version
});

export default defineConfig({
    // ...
    plugins: [
        buildTimeIdentifiersSupportPlugin,
        // ...
    ]
    // ...
});

Environment Variables

The plugin uses the following environment variables:

| Environment Variable | Description | Default Value When Missing | |---------------------|-------------|---------------------------| | VERSION | Build version | [unknown build version] | | BRANCH | Current Git branch | [unknown git branch] | | COMMIT_HASH | Current commit hash | [unknown commit hash] |

Environment variable names can be changed using the aliases parameter (see "Optional Parameters" section).

Parameters

Required Parameters

| Parameter | Type | Description | |-----------|------|-------------| | packageName | string | Package name | | packageVersion | string | Package version |

Optional Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | aliases.VERSION_FIELD_NAME | string | 'VERSION' | Environment variable name for build version | | aliases.BRANCH_FIELD_NAME | string | 'BRANCH' | Environment variable name for Git branch | | aliases.COMMIT_HASH_FIELD_NAME | string | 'COMMIT_HASH' | Environment variable name for commit hash |

Available Variables

After configuring the plugin, the following global variables will be available in your code:

| Variable | Description | |----------|-------------| | PACKAGE_INFO_FIELD_NAME | Package name | | PACKAGE_INFO_FIELD_VERSION | Package version | | BUILD_TIME_VARIABLES_VERSION | Build version (from environment variable) | | BUILD_TIME_VARIABLES_BRANCH | Current Git branch | | BUILD_TIME_VARIABLES_COMMIT_HASH | Current commit hash | | BUILD_TIME_VARIABLES_RELEASE_NAME | Full release name in format packageName@packageVersion+version |

Build Example

VERSION=1.0.0-beta BRANCH=feature/new-plugin COMMIT_HASH=abc123 vite build

Code Usage Example

vite-end.d.ts:

// ...
/// <reference types="@37bytes/vite-build-time-environment/client" />
// ...

export const packageInfo = {
    name: PACKAGE_INFO_FIELD_NAME,
    version: PACKAGE_INFO_FIELD_VERSION
};

export const buildTimeVariables = {
    version: BUILD_TIME_VARIABLES_VERSION,
    branch: BUILD_TIME_VARIABLES_BRANCH,
    commitHash: BUILD_TIME_VARIABLES_COMMIT_HASH,
    releaseName: BUILD_TIME_VARIABLES_RELEASE_NAME
};

Aliases Configuration Example

buildTimeIdentifiersPlugin({
    packageName: 'my-app',
    packageVersion: '1.0.0',
    aliases: {
        VERSION_FIELD_NAME: 'MY_APP_VERSION',
        BRANCH_FIELD_NAME: 'MY_APP_BRANCH',
        COMMIT_HASH_FIELD_NAME: 'MY_APP_COMMIT'
    }
})

Default Values

When corresponding environment variables are not set, the plugin uses these default values:

• For BUILD_TIME_VARIABLES_BRANCH: [unknown git branch]
• For BUILD_TIME_VARIABLES_COMMIT_HASH: [unknown commit hash]
• For BUILD_TIME_VARIABLES_VERSION: [unknown build version]