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.
ember install ember-cli-app-versionThe 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');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>The addon consists of several integrated components:
index.js file hooks into Ember CLI's build process to extract version information from package.json and git metadata{{app-version}} helper for displaying version information in templatesThe {{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 -->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"]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"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
};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}`
};
}/** 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;
}The addon gracefully handles various edge cases:
The template helper never throws errors and will return the full version string if parsing fails.