unplugin-build-meta

March 27, 2026 · View on GitHub

Import build metadata into your JavaScript/TypeScript projects for Vite, Webpack, Rollup, esbuild and more. Powered by unplugin.

Install

npm install -D unplugin-build-meta

Usage

Tip

You can view all examples here.

Vite

// vite.config.ts
import buildMeta from "unplugin-build-meta/vite";

export default defineConfig({
  plugins: [
    buildMeta({ /* options */ }),
  ],
});

Rollup

// rollup.config.js
import buildMeta from "unplugin-build-meta/rollup";

export default {
  plugins: [
    buildMeta({ /* options */ }),
  ],
};

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require("unplugin-build-meta/webpack").default({ /* options */ }),
  ],
};

Nuxt

// nuxt.config.js
export default defineNuxtConfig({
  modules: [
    ["unplugin-build-meta/nuxt", { /* options */ }]
  ],
});

Astro

// astro.config.mjs
import { defineConfig } from "astro/config";
import buildMeta from "unplugin-build-meta/astro";

// https://astro.build/config
export default defineConfig({
  integrations: [
    buildMeta({
      /* options */
    })
  ]
});

esbuild

// esbuild.config.js
import { build } from "esbuild";
import buildMeta from "unplugin-build-meta/esbuild";

build({
  /* ... */
  plugins: [
    buildMeta({
      /* options */
    }),
  ],
});

Rspack

// rspack.config.mjs
import rspack from "@rspack/core";
import buildMeta from "unplugin-build-meta/rspack";

/** @type {import('@rspack/core').Configuration} */
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      template: "./index.html"
    }),
    buildMeta()
  ],
};

Rolldown (Experimental)

// rolldown.config.js
import { defineConfig } from "rolldown";
import buildMeta from "unplugin-build-meta/rolldown";

export default defineConfig({
  input: "./index.js",
  plugins: [
    buildMeta({
      /* options */
    }),
  ],
});

Configuration

buildMeta({
  // Whether to enable the git module (enabled by default)
  git: true,

  // Additional custom modules to include
  extraModules: [
    // Your custom modules here
  ]
});

By default, the git module is enabled. You can:

Disable the git module by setting git: false
Add custom modules using the extraModules array
Create custom modules using defineBuildMetaModule

Modules

Git Module

The git module provides access to repository metadata from your code.

Import it in your code:

// Import all git metadata
import * as git from "virtual:build-meta/git";

// Or import specific values
import { branch, sha, shortSha } from "virtual:build-meta/git";

Available properties (all properties are nullable):

Property	Type	Description
`branch`	`string \| null`	Current git branch name
`sha`	`string \| null`	Full git commit hash
`shortSha`	`string \| null`	First 10 characters of the commit hash
`latestCommitMessage`	`string \| null`	Latest commit message
`commitAuthorName`	`string \| null`	Commit author name
`commitAuthorEmail`	`string \| null`	Commit author email
`commitAuthorDate`	`string \| null`	Commit author date
`commitCommitterName`	`string \| null`	Committer name
`commitCommitterEmail`	`string \| null`	Committer email
`commitCommitterDate`	`string \| null`	Committer date
`tag`	`string \| null`	Current tag (if any)
`tags`	`string[] \| null`	All tags pointing at current commit
`lastTag`	`string \| null`	Latest tag in the repository
`repositoryUrl`	`string \| null`	Repository URL (for GitHub repositories)

Runtime Module

The runtime module provides access to Node.js runtime information from your code.

Import it in your code:

// Import all runtime information
import * as runtime from "virtual:build-meta/runtime";

// Or import specific values
import { arch, platform, versions } from "virtual:build-meta/runtime";

Available properties:

Property	Type	Description
`platform`	`NodeJS.Platform`	The operating system platform (e.g., 'linux', 'darwin', 'win32')
`arch`	`NodeJS.Architecture`	The CPU architecture (e.g., 'x64', 'arm64')
`versions`	`NodeJS.ProcessVersions`	Version strings of Node.js and its dependencies

TypeScript

To get proper type support, make sure to include the type declarations:

{
  "compilerOptions": {
    "types": [
      "unplugin-build-meta/types"
    ]
  }
}

📄 License

Published under MIT License.