tessl/npm-ember-cli-app-version

Ember CLI addon that adds app version display functionality to applications and Ember Inspector

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Ember CLI App Version

Name: tessl/npm-ember-cli-app-version
Author: tessl

Ember CLI App Version is an Ember addon that automatically adds your app's version information to the Ember Inspector's INFO tab and provides a template helper for displaying version information in your application. It intelligently combines package.json version data with git repository metadata to create comprehensive version strings.

Package Information

Package Name: ember-cli-app-version
Package Type: npm (Ember CLI addon)
Language: JavaScript
Installation: ember install ember-cli-app-version

Core Imports

The addon automatically installs its components when added to an Ember project. No explicit imports are needed for basic functionality.

For programmatic access to the helper function:

import { appVersion } from 'your-app-name/helpers/app-version';

For accessing utility regular expressions:

import { 
  versionRegExp, 
  versionExtendedRegExp, 
  shaRegExp 
} from 'ember-cli-app-version/utils/regexp';

For creating custom initializers:

import initializerFactory from 'ember-cli-app-version/initializer-factory';

For build-time version generation:

const { gitRepoVersion } = require('ember-cli-app-version');

Basic Usage

Once installed, the addon automatically registers your app's version with Ember Inspector. Use the {{app-version}} helper in templates to display version information:

<!-- Display full version string (e.g., "2.1.0+4a8b9c12") -->
<p>Version: {{app-version}}</p>

<!-- Display only version number (e.g., "2.1.0") -->
<p>Version: {{app-version versionOnly=true}}</p>

<!-- Display extended version with pre-release info (e.g., "2.1.0-beta.1") -->
<p>Version: {{app-version versionOnly=true showExtended=true}}</p>

<!-- Display only git SHA (e.g., "4a8b9c12") -->
<p>Commit: {{app-version shaOnly=true}}</p>

Architecture

The addon consists of several integrated components:

Build-time Configuration: The main index.js file hooks into Ember CLI's build process to extract version information from package.json and git metadata
Template Helper: Provides the {{app-version}} helper for displaying version information in templates
Inspector Integration: Automatically registers the app with Ember Inspector's library registry
Utility Functions: Regular expression patterns for parsing version strings
Version Detection: Intelligent version string construction combining package.json version with git SHA when available

Capabilities

Template Helper

The {{app-version}} helper displays version information in Ember templates with various formatting options.

/**
 * Template helper function that extracts and formats version information
 * @param _ - Positional parameters (unused)
 * @param hash - Named parameters for controlling output format (defaults to empty object)
 * @returns Formatted version string based on options
 */
function appVersion(_, hash = {}): string;

interface AppVersionOptions {
  /** Display only the version number without git SHA */
  versionOnly?: boolean;
  /** Display only the git SHA without version number */
  shaOnly?: boolean; 
  /** When used with versionOnly, includes pre-release identifiers */
  showExtended?: boolean;
  /** Backwards compatible alias for versionOnly */
  hideSha?: boolean;
  /** Backwards compatible alias for shaOnly */
  hideVersion?: boolean;
}

Usage Examples:

<!-- Full version with SHA -->
{{app-version}}
<!-- Output: "2.1.0+4a8b9c12" -->

<!-- Version only -->
{{app-version versionOnly=true}}
<!-- Output: "2.1.0" -->

<!-- Extended version with pre-release info -->
{{app-version versionOnly=true showExtended=true}}
<!-- Output: "2.1.0-beta.1" -->

<!-- SHA only -->
{{app-version shaOnly=true}}
<!-- Output: "4a8b9c12" -->

<!-- Backwards compatible versions -->
{{app-version hideSha=true}}
<!-- Same as versionOnly=true -->

{{app-version hideVersion=true}}
<!-- Same as shaOnly=true -->

Version String Parsing

Regular expression utilities for parsing and extracting parts of version strings.

/** Matches semantic version format (e.g., "1.2.3") */
const versionRegExp: RegExp;

/** Matches extended version with pre-release identifiers (e.g., "1.2.3-alpha.1") */
const versionExtendedRegExp: RegExp;

/** Matches 8-character git SHA at end of string (e.g., "4a8b9c12") */
const shaRegExp: RegExp;

Usage Examples:

import { 
  versionRegExp, 
  versionExtendedRegExp, 
  shaRegExp 
} from 'ember-cli-app-version/utils/regexp';

const fullVersion = "2.1.0-beta.1+4a8b9c12";

// Extract base version
const version = fullVersion.match(versionRegExp);
// Result: ["2.1.0"]

// Extract extended version 
const extendedVersion = fullVersion.match(versionExtendedRegExp);
// Result: ["2.1.0-beta.1"]

// Extract SHA
const sha = fullVersion.match(shaRegExp);
// Result: ["4a8b9c12"]

Build-time Utilities

Utility functions for generating version strings during the build process by combining package.json data with git repository information.

/**
 * Generates version string by combining package.json version with git metadata
 * @param options - Configuration options for version generation
 * @returns Version string in format: version+sha or custom format based on options
 */
function gitRepoVersion(options?: GitRepoVersionOptions): string;

Usage Examples:

// From your ember-cli-build.js or similar build script
const { gitRepoVersion } = require('ember-cli-app-version');

// Default version with 8-character SHA
const version = gitRepoVersion();
// Result: "7.0.0+4a8b9c12"

// Version without SHA
const versionOnly = gitRepoVersion({ shaLength: 0 });
// Result: "7.0.0"

// Version with date
const versionWithDate = gitRepoVersion({ includeDate: true });
// Result: "7.0.0+4a8b9c12 2023-03-15"

Inspector Integration

Factory function for creating initializers that register apps with Ember Inspector.

/**
 * Creates an initializer function that registers the app with Ember Inspector
 * @param name - Application name
 * @param version - Application version
 * @returns Initializer function that registers with libraries registry
 */
function initializerFactory(name: string, version: string): (() => void);

Usage Example:

import initializerFactory from 'ember-cli-app-version/initializer-factory';

// Create custom initializer
const customInitializer = initializerFactory('my-app', '1.0.0');

// Use in an initializer
export default {
  name: 'My App Version',
  initialize: customInitializer
};

Build-time Configuration

The addon automatically configures version information during the build process. You can override this behavior via environment configuration.

// In config/environment.js
ENV['ember-cli-app-version'] = {
  version: 'custom-version-string'
};

Heroku Configuration Example:

For Heroku deployments where git metadata isn't available:

// In config/environment.js
if (process.env.SOURCE_VERSION) {
  const pkg = require('../package.json');
  const hash = process.env.SOURCE_VERSION.substr(0, 7);
  ENV['ember-cli-app-version'] = {
    version: `${pkg.version}+${hash}`
  };
}

Types

/** Configuration options for the app-version helper */
interface AppVersionOptions {
  /** Display only the version number without git SHA */
  versionOnly?: boolean;
  /** Display only the git SHA without version number */  
  shaOnly?: boolean;
  /** When used with versionOnly, includes pre-release identifiers */
  showExtended?: boolean;
  /** Backwards compatible alias for versionOnly */
  hideSha?: boolean;
  /** Backwards compatible alias for shaOnly */
  hideVersion?: boolean;
}

/** Configuration options for gitRepoVersion function */
interface GitRepoVersionOptions {
  /** Length of git SHA to include (default: 8, set to 0 to exclude) */
  shaLength?: number;
  /** Include git author date in version string (default: false) */
  includeDate?: boolean;
  /** Path to project directory (default: process.cwd()) */
  projectPath?: string;
}

/** Environment configuration for the addon */
interface EmberCliAppVersionConfig {
  /** Custom version string to use instead of auto-detection */
  version?: string;
}

Error Handling

The addon gracefully handles various edge cases:

Missing git repository: Falls back to package.json version only
Missing package.json: Uses git branch name or "DETACHED_HEAD"
Invalid version strings: Returns the original version string unchanged
Build environment issues: Provides configuration override options

The template helper never throws errors and will return the full version string if parsing fails.

Install with Tessl CLI

npx tessl i tessl/npm-ember-cli-app-version

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/ember-cli-app-version@7.0.x
Publish Source: CLI
Badge