/components:version-badge

Implement a version badge component that displays version number, git commit, and recent changelog in a tooltip.

Context

• Framework config: !find . -maxdepth 1 ( -name "next.config." -o -name "nuxt.config." -o -name "svelte.config." -o -name "vite.config." )

• Package manager: !find . -maxdepth 1 ( -name "package.json" -o -name "bun.lockb" -o -name "pnpm-lock.yaml" )

• Styling: !find . -maxdepth 1 ( -name "tailwind.config." -o -name "postcss.config." )

• UI library: !find . -maxdepth 1 -name "components.json"

• Changelog: !find . -maxdepth 1 -name 'CHANGELOG.md'

• Version: !jq -r '.version // "unknown"' package.json

Parameters

• --check-only : Analyze project and show what would be implemented without making changes

• --location <header|footer|custom> : Specify component placement (default: header)

Overview

This command adds a version display to your application with:

• Trigger element: v1.43.0 | 004ddd9 (version + abbreviated commit)

• Tooltip: Full build info (version, commit, timestamp, branch) + recent changelog entries

• Build-time processing: Zero runtime overhead

Tech Stack Detection

Detect the project's tech stack from the context above:

Framework:

• Next.js: next.config.js or next.config.mjs or next.config.ts

• Nuxt: nuxt.config.ts or nuxt.config.js

• SvelteKit: svelte.config.js

• Vite + React: vite.config.*

• React in dependencies

• Vite + Vue: vite.config.*

• Vue in dependencies

• Create React App: react-scripts in dependencies

• Plain React: React in dependencies without specific framework

Styling:

• Tailwind CSS: tailwind.config.* or @tailwind in CSS

• CSS Modules: .module.css files

• styled-components: In dependencies

• Emotion: @emotion/* in dependencies

• Plain CSS: Fallback

UI Library:

• shadcn/ui: components.json with shadcn config

• Radix UI: @radix-ui/* in dependencies

• Headless UI: @headlessui/* in dependencies

• None: Use native implementation

Execution

Execute this version badge implementation workflow:

Step 1: Analyze project

Read package.json to identify dependencies. Check for framework config files, styling configuration, and existing component patterns.

Step 2: Create changelog parser script

Create a build-time script that parses CHANGELOG.md :

Location: scripts/parse-changelog.mjs (or appropriate location)

// Script should: // 1. Read CHANGELOG.md // 2. Extract last 2 versions with their changes // 3. Categorize changes (feat, fix, perf, breaking) // 4. Output as JSON for NEXT_PUBLIC_CHANGELOG (or equivalent)

Change type icons:

Type Icon Description

feat sparkles New feature

fix bug Bug fix

perf zap Performance improvement

breaking warning Breaking change

Limits:

• Max 3 features per version

• Max 2 other changes per version

• Last 2 versions only

Step 3: Configure build pipeline

Based on framework, add build-time environment variables:

Next.js (next.config.mjs ):

const buildInfo = { version: process.env.npm_package_version || 'dev', commit: process.env.VERCEL_GIT_COMMIT_SHA || process.env.GITHUB_SHA || 'local', branch: process.env.VERCEL_GIT_COMMIT_REF || process.env.GITHUB_REF_NAME || 'local', buildTime: new Date().toISOString(), };

export default { env: { NEXT_PUBLIC_BUILD_INFO: JSON.stringify(buildInfo), // NEXT_PUBLIC_CHANGELOG set by parse-changelog.mjs }, };

Vite (vite.config.ts ):

export default defineConfig({ define: { 'import.meta.env.VITE_BUILD_INFO': JSON.stringify(buildInfo), }, });

Step 4: Create component

Create the version badge component appropriate for the detected framework:

Component structure:

src/components/ version-badge/ version-badge.tsx # Main component version-badge.css # Styles (if not using Tailwind) index.ts # Export

Features to implement:

Trigger display:

• Version number from build info

• Abbreviated commit SHA (7 chars)

• Subtle styling: text-[10px] text-muted-foreground/60

• Hover brightening for affordance

• Hidden when no build info (local dev)

Tooltip content:

• Build Information section with table layout

• Recent Changes section with categorized items

• Proper keyboard accessibility

Accessibility:

• Focusable button trigger

• aria-label with version info

• Focus ring styling

• Both hover and focus trigger tooltip

• Screen reader friendly content

Step 5: Integrate component

Add the component to the appropriate location:

Common locations:

• Header/navbar (most common)

• Footer

• Settings page

• About modal

Default: Place below the main title in header, for both desktop and mobile nav.

Component Variants

React + Tailwind + shadcn/ui

Uses Tooltip from shadcn/ui, cn utility for class merging.

React + Tailwind (no UI library)

Native implementation with Radix Tooltip or custom tooltip.

Vue 3 + Tailwind

Vue component with Teleport for tooltip positioning.

Svelte + Tailwind

Svelte component with actions for tooltip behavior.

Plain CSS

Generates CSS with custom properties for theming.

Build Script Template

#!/usr/bin/env node /**

• parse-changelog.mjs
• Parses CHANGELOG.md and outputs JSON for the version badge tooltip */

import { readFileSync, existsSync } from 'fs';

const CHANGELOG_PATH = './CHANGELOG.md'; const MAX_VERSIONS = 2; const MAX_FEATURES_PER_VERSION = 3; const MAX_OTHER_PER_VERSION = 2;

function parseChangelog() { if (!existsSync(CHANGELOG_PATH)) { return JSON.stringify([]); }

const content = readFileSync(CHANGELOG_PATH, 'utf-8'); const versions = [];

// Parse version headers and their changes const versionRegex = /^## [?(\d+.\d+.\d+)]?/gm; const changeRegex = /^* **(\w+):** (.+)$/gm;

// ... parsing logic ...

return JSON.stringify(versions.slice(0, MAX_VERSIONS)); }

// Output for environment variable console.log(parseChangelog());

Flags

Flag Description

--check-only

Analyze project and show what would be implemented

--location <loc>

Specify component placement (header, footer, custom)

Examples

Implement version badge with auto-detection

/components:version-badge

Check what would be implemented without changes

/components:version-badge --check-only

Place in footer instead of header

/components:version-badge --location footer

Post-Implementation

After implementing:

• Verify build: Run build command to ensure env vars are set

• Test tooltip: Check hover and keyboard accessibility

• Update CI: Ensure changelog is available during build

• Document: Add note to README about version display feature

Error Handling

• No package.json: Warn and ask for framework specification

• Unknown framework: Offer generic implementation or ask user

• No CHANGELOG.md: Component works without changelog, shows only build info

• Existing component: Ask before overwriting, offer merge strategy

See Also

• version-badge-pattern skill - Detailed pattern documentation