@teaminverso/version-modal

A complete version management solution for all Inverso projects, providing automatic version detection, broadcasting, and display through a convenient Shift+V modal.

Features

• 🔄 Automatic Version Detection: Git-based version detection using commit hashes and tags
• 📡 Version Broadcasting: Exposes /health endpoints with version information
• 🖥️ Version Display: Shift+V modal showing all product versions
• 🔗 API Integration: Centralized version collection and distribution
• ⚡ Zero Configuration: Works across Dashboard, Convertify, and API with minimal setup
• 🎨 Chakra UI Integration: Beautiful, accessible modal component
• 🚀 Deploy-Ready: Works with Dokku, Heroku, and other platforms out of the box

Installation

Install the package from npm:

npm install @teaminverso/version-modal
# or
yarn add @teaminverso/version-modal

Quick Start

Frontend (React with Chakra UI)

import { VersionModal } from '@teaminverso/version-modal'

function App() {
  return (
    <ChakraProvider theme={theme}>
      {/* Your app content */}
      
      {/* Add version modal - press Shift+V to open */}
      <VersionModal 
        serviceName="Dashboard"
        apiConfig={{
          baseUrl: "https://api.inverso.app",
          endpoint: "/v1/version"
        }}
      />
    </ChakraProvider>
  )
}

Backend (Express.js API)

const { createHealthEndpoint, createVersionRouter } = require('@teaminverso/version-modal/backend')

// Add health endpoint
app.get('/health', createHealthEndpoint({ serviceName: 'api' }))

// Add version collection endpoint
app.use('/v1', createVersionRouter({
  // Optional: manually configured services
  services: [
    { name: 'dashboard', envVar: 'REACT_APP_DASHBOARD_URL' },
    { name: 'convertify', envVar: 'REACT_APP_CONVERTIFY_URL' },
    { name: 'convertify-plus', envVar: 'REACT_APP_CONVERTIFY_PLUS_URL' }
  ],
  // Enable automatic service discovery from environment variables (default: true)
  useEnvDiscovery: true
}))

Build Integration

Add to your package.json:

{
  "scripts": {
    "generate-version": "node scripts/generate-version-info.js",
    "prebuild": "npm run generate-version",
    "predev": "npm run generate-version"
  }
}

Copy the version generation script to your project:

# Copy from node_modules
cp node_modules/@teaminverso/version-modal/scripts/generate-version-info.js scripts/

API Reference

Components

<VersionModal>

Main React component for displaying version information.

Props:

• serviceName (string): Name of the current service (e.g., "Dashboard")
• apiConfig (object, optional): Configuration for fetching API versions
  • baseUrl (string): API base URL
  • endpoint (string): Version endpoint path (default: "/version")
  • headers (object): Additional request headers
• shortcutKey (string): Keyboard shortcut key (default: "v" for Shift+V)
• modalTitle (string): Modal title (default: "Version Info")
• disabled (boolean): Disable the modal (default: false)

Hooks

useVersionInfo(apiConfig, shouldFetch)

Hook for fetching version information.

Returns:

• apiVersions: Object containing versions from all services (including current service)
• isLoading: Loading state for API requests
• error: Error message if API fetch fails

Environment Variables

The package automatically discovers service URLs from the following environment variables:

# Service URLs (used for version collection)
REACT_APP_CONVERTIFY_URL=http://localhost:3001
REACT_APP_CONVERTIFY_PLUS_URL=http://localhost:3002
REACT_APP_NOTIFY_URL=http://localhost:3003
REACT_APP_NOTIFY_PLUS_URL=http://localhost:3004

Each service URL will have /health appended to create the health endpoint URL.

Backend Utilities

createHealthEndpoint(options)

Creates Express middleware for /health endpoint.

Options:

• serviceName (string): Service name (default: "api")
• versionPath (string): Custom path to version.json file

createVersionRouter(options)

Creates Express router for collecting versions from multiple services.

Options:

• services (array): Optional array of additional service health endpoint URLs
• timeout (number): Request timeout in milliseconds (default: 5000)
• useEnvDiscovery (boolean): Whether to discover services from environment variables (default: true)
• includeSelf (boolean): Whether to include this API's version (default: true)
• includeSelf (boolean): Include current service version (default: true)

Broadcasting Utilities

setupVersionBroadcasting(options)

Automatically sets up version broadcasting for your project type.

Options:

• serviceName (string): Service name
• method (string): Broadcasting method ("auto", "static", "public", "express")
• versionInfo (object): Custom version info (optional)

Project Setup Examples

React/Vue Frontend

1. Install the package
2. Add version generation to build process
3. Copy the generation script
4. Add the VersionModal component

npm install @teaminverso/version-modal
cp node_modules/@teaminverso/version-modal/scripts/generate-version-info.js scripts/

Update package.json:

{
  "scripts": {
    "prebuild": "node scripts/generate-version-info.js"
  }
}

Express.js API

1. Install the package
2. Add health and version endpoints
3. Set up version generation

const { createHealthEndpoint, createVersionRouter } = require('@teaminverso/version-modal/backend')

app.get('/health', createHealthEndpoint({ serviceName: 'api' }))
app.use('/api/v1', createVersionRouter({
  services: [
    { name: 'dashboard', envVar: 'REACT_APP_DASHBOARD_URL' },
    { name: 'convertify', envVar: 'REACT_APP_CONVERTIFY_URL' }
  ],
  useEnvDiscovery: true
}))

Deployment

The package automatically works with:

• Dokku: Uses GIT_REV environment variable
• Heroku: Uses SOURCE_VERSION environment variable
• Local Development: Uses git commands directly
• Other Platforms: Fallback to environment variables

No additional buildpacks or configuration needed!

Version Detection Logic

1. Tagged Releases: Shows tag name (e.g., v1.0.0)
2. Development: Shows commit hash (e.g., abc1234)
3. Deployment: Uses platform-provided environment variables
4. Fallback: Uses "unknown" if no version info available

Troubleshooting

Version shows "unknown"

• Ensure version generation script runs during build
• Check that environment variables are available in deployment
• Verify git is available during local development

Modal not opening with Shift+V

• Check browser console for JavaScript errors
• Ensure ChakraProvider wraps your app
• Verify no conflicts with browser shortcuts

API versions not loading

• Check network tab for failed requests
• Verify API endpoint URLs and authentication
• Check CORS configuration

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Make changes
4. Build: npm run build
5. Test in a project: npm link

License

MIT © Team Inverso