version-badge

The VersionBadge and PackageBadge components display package name, version, and git hash information in a compact inline badge. They are designed for use within this documentation framework itself.

Important: These components are part of the doc-site framework's internal tooling. Libraries documented by this site should not depend on or inherit from these badge components. The dependency flows one way only: the doc site depends on the library — never the reverse. Use this component as a reference implementation if you need similar functionality in your own project.

Preview

Package + version

starter-kitv0.1.0

Version only

0.1.0

With git hash

starter-kitv0.1.0

a1b2c3d

VersionBadge (auto)

doc-site-starter-kitv0.1.0

Usage

There are two components: PackageBadge (low-level, explicit props) and VersionBadge (high-level, boolean flags that read from build-time constants).

PackageBadge

Pass explicit values for full control:

import { PackageBadge } from '../components/VersionBadge'

<PackageBadge
  packageName="my-lib"
  packageFullName="@org/my-lib"
  versionText="v1.2.3"
  gitHash="a1b2c3d"
  linkable
/>

VersionBadge

Toggle display flags — values are read automatically from build-time constants or package.json:

import { VersionBadge } from '../components/VersionBadge'

{/* Show package name + version with "v" prefix */}
<VersionBadge package version prefix />

{/* Version only, no link */}
<VersionBadge version />

{/* Everything: package, version, git hash, all clickable */}
<VersionBadge package version prefix hash linkable />

Build-time constants

The VersionBadge reads from three compile-time constants that can be injected via Vite's define option:

Constant	Fallback	Description
PACKAGE_VERSION	package.json version	The package version string
PACKAGE_NAME	package.json name	The full package name (scoped or unscoped)
GIT_HASH	"unknown"	Short git commit hash for the current build

Configure these in vite.config.ts:

vite.config.ts

export default defineConfig({
  define: {
    __PACKAGE_VERSION__: JSON.stringify(process.env.npm_package_version),
    __PACKAGE_NAME__: JSON.stringify(process.env.npm_package_name),
    __GIT_HASH__: JSON.stringify(process.env.GIT_HASH || 'unknown'),
  },
  // ... other config
})

Props

PackageBadgeProps

Prop	Type	Default	Description
packageName	string	—	Short package name displayed in the primary slot
packageFullName	string	—	Full npm package name used for the version link
versionText	string	—	Version string to display (e.g. "v1.2.3")
linkable	boolean	true	Whether version and hash link to npm / GitHub
gitHash	string	—	Git commit hash to display after the version

VersionBadgeProps

Prop	Type	Default	Description
package	boolean	false	Show the package name
version	boolean	false	Show the version number
prefix	boolean	false	Prepend "v" to the version string
hash	boolean	false	Show the git commit hash
linkable	boolean	false	Make version and hash clickable (npm / GitHub links)