Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vite Plugin
✓ import Info from 'unplugin-info/vite';
✗ import { Info } from 'unplugin-info/vite'; // Incorrect named import
const Info = require('unplugin-info/vite'); // CommonJS import in ESM context
The Vite integration exports a default function. Ensure you're in an ESM context for `import` statements.
Webpack Plugin
✓ require('unplugin-info/webpack')();
✗ import Info from 'unplugin-info/webpack'; // Webpack config typically uses CommonJS for plugin instantiation
Info(); // Missing call to the default function
Webpack configurations often use CommonJS `require`. The module exports a function that needs to be called to instantiate the plugin.
Nuxt Module
✓ modules: ['unplugin-info/nuxt']
✗ import Info from 'unplugin-info/nuxt'; // Not how Nuxt modules are typically registered
modules: [Info]
Nuxt modules are typically registered as a string path in the `modules` array. Options are passed via the top-level `info` key in `nuxt.config.ts`.
TypeScript Types
✓ /// <reference types="unplugin-info/client" />
// or in tsconfig.json
"types": ["unplugin-info/client"]
✗ import { BuildInfo } from 'unplugin-info/client'; // Incorrect import of ambient types
To get type inference for the virtual modules (e.g., `~build/info`), you need to reference the client types either via a triple-slash directive in a `.d.ts` file or by adding `unplugin-info/client` to the `types` array in your `tsconfig.json`.
This quickstart demonstrates configuring `unplugin-info` with Vite and then accessing the generated build, Git, CI, and package information within a client-side TypeScript file. It shows how to include custom data and environment variables.
import { defineConfig } from 'vite';
import Info from 'unplugin-info/vite';
// vite.config.ts
export default defineConfig({
plugins: [
Info({
/**
* Customize what information to include
*
* @default true
*/
git: true, // Includes Git commit SHA, branch, etc.
buildTime: true, // Includes the build timestamp
ci: true, // Includes CI environment variables
packageJson: true, // Includes package.json version
/**
* Custom information to add to the virtual module
*/
custom: {
myCustomKey: 'myCustomValue',
envVar: process.env.MY_ENV_VAR ?? ''
}
})
]
});
// src/main.ts (or any client-side file)
// Make sure to add "unplugin-info/client" to your tsconfig.json
import buildInfo from '~build/info';
import buildGit from '~build/git';
import buildCI from '~build/ci';
import buildPackage from '~build/package';
console.log('Application Build Info:', buildInfo);
console.log('Git Info:', buildGit);
console.log('CI Info:', buildCI);
console.log('Package Info:', buildPackage);
document.getElementById('app')!.innerHTML = `
<h1>App Info</h1>
<p>Build Time: ${new Date(buildInfo.time).toLocaleString()}</p>
<p>Git Commit: ${buildGit.shortHash}</p>
<p>CI: ${buildCI.name || 'Local'}</p>
<p>Version: ${buildPackage.version}</p>
<p>Custom: ${buildInfo.custom.myCustomKey} - ${buildInfo.custom.envVar}</p>
`;
Errors
Common errors & fixes
Cannot find module '~build/info' or its corresponding type declarations.
TypeScript compiler is unaware of the virtual module types.
fixAdd `"unplugin-info/client"` to the `types` array in `tsconfig.json` or add `/// <reference types="unplugin-info/client" />` to a `.d.ts` file.
ReferenceError: BuildInfo is not defined (or similar for other virtual modules)
Attempting to use `BuildInfo` (or `BuildGit`, etc.) as a global variable instead of importing the virtual module.
fixCorrectly import the virtual module using `import buildInfo from '~build/info';` (or `~build/git`, etc.) as an ESM import.
Rollup failed to resolve import "unplugin-info/vite" from "vite.config.ts".
Incorrect import path for the specific bundler plugin.
fixVerify the correct import path for your bundler, e.g., `import Info from 'unplugin-info/vite';` for Vite, `require('unplugin-info/webpack')` for Webpack, etc. Ensure the package is installed. Audit
Dependencies
@nuxt/kitoptionalRequired for Nuxt module integration.
@nuxt/schemaoptionalRequired for Nuxt module integration and type inference.
@rspack/coreoptionalRequired when using with Rspack.
esbuildoptionalRequired when using with esbuild.
rollupoptionalRequired when using with Rollup (or bundlers like Vite that use Rollup internally).
viteoptionalRequired when using with Vite.
webpackoptionalRequired when using with Webpack or compatible tools like Vue CLI/Quasar (webpack mode).