Ember CLI Version Checker

5.1.2 · active · verified Wed Apr 22

The `ember-cli-version-checker` package is a fundamental utility for Ember CLI addon authors. It provides a robust mechanism to programmatically determine the installed versions of NPM or (historically) Bower packages within a consuming Ember application's dependency tree. This allows addons to implement conditional logic, such as providing different features, templates, or polyfills, based on the host application's Ember CLI or Ember.js version, thus ensuring broad compatibility. The current stable version is 5.1.2, with releases occurring on an as-needed basis for bug fixes and minor enhancements rather than a fixed cadence. Its core differentiator lies in its deep integration with the Ember CLI project context, simplifying complex semver comparisons for specific dependencies.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'addonPackages')
```
cause The `VersionChecker` was instantiated without a valid `this.project` object, which provides the necessary context for dependency resolution.

fix Ensure `VersionChecker` is called with `new VersionChecker(this.project)` within the scope of an Ember CLI addon or similar project context.
```
Error: To use [your-addon-name] you must have [dependency-name] [minimum-version]
```
cause This error is intentionally thrown by `checker.for('dependency-name').assertAbove('minimum-version')` because the consuming application's dependency does not meet the specified minimum version.

fix The user of your addon needs to upgrade the specified dependency in their application's `package.json` to meet the minimum version requirement.
```
Dependency version is 'undefined' or a method like '.exists()' returns false unexpectedly.
```
cause The specified dependency (e.g., 'ember-cli-qunit') was not found in the consuming application's `node_modules` or `package.json`.

fix Verify the dependency name is spelled correctly and that it is listed in the application's `package.json` and installed via `npm install` or `yarn install`.

Warnings

breaking This package requires Node.js version `10.* || >= 12.*`. Usage with unsupported Node.js versions will result in errors.
Fix: Upgrade your Node.js environment to a compatible version (e.g., Node.js 12.x LTS or higher).
gotcha The `VersionChecker` constructor *must* be initialized with an `EmberCLIProject` instance, typically `this.project` when used within an Ember CLI addon's `index.js` file. Attempting to use it without this context will lead to runtime errors.
Fix: Ensure `new VersionChecker(this.project)` is called from within an Ember CLI addon's environment where `this.project` is available.
deprecated While `ember-cli-version-checker` still supports checking Bower dependencies via `checker.for('package', 'bower')`, Bower itself is largely deprecated in the Ember ecosystem. Focus on checking NPM dependencies.
Fix: Prioritize checking NPM dependencies. If you still rely on Bower, consider migrating to NPM/Yarn.
gotcha The `hasSingleImplementation` method had bug fixes across multiple major versions (v4.1.1, v5.0.2). If relying on this specific API, ensure you are on the latest stable version to avoid potential incorrect results.
Fix: Always use the latest stable version of `ember-cli-version-checker` (currently 5.1.2) to benefit from bug fixes and improvements, especially for `hasSingleImplementation`.

Install

npm install ember-cli-version-checker npm
yarn add ember-cli-version-checker yarn
pnpm add ember-cli-version-checker pnpm

Imports

VersionChecker
wrong:
```
import VersionChecker from 'ember-cli-version-checker';
```
correct:
```
const VersionChecker = require('ember-cli-version-checker');
```
Ember CLI addons are typically CommonJS modules. Using `require` is the standard pattern. Direct ESM import is not commonly supported or recommended in this context.
VersionChecker instance methods (e.g., .for, .satisfies, .gte, .assertAbove)
```
const checker = new VersionChecker(this.project);
const dep = checker.for('ember-cli');
if (dep.gte('2.0.0')) { /* ... */ }
```
Methods are accessed on an instance of VersionChecker, which must be initialized with the `this.project` object from an Ember CLI addon context.

Quickstart

Demonstrates initializing `VersionChecker` within an Ember CLI addon's hooks, asserting minimum dependency versions, and conditionally loading resources based on the host application's Ember.js version.

const path = require('path');
const VersionChecker = require('ember-cli-version-checker');

// This code would typically reside in an Ember CLI addon's index.js file
// inside the module.exports object.
module.exports = {
  name: 'my-awesome-addon',

  init() {
    this._super.init.apply(this, arguments);
    const checker = new VersionChecker(this.project);

    // Assert a minimum Ember CLI version
    checker.for('ember-cli').assertAbove('2.13.0', '`my-awesome-addon` requires Ember CLI >= 2.13.0');

    const emberDep = checker.for('ember');
    if (!emberDep.exists()) {
      console.warn('Ember.js not found in project dependencies. This addon may not function correctly.');
    }

    console.log(`Ember version: ${emberDep.version || 'N/A'}`);
  },

  treeForAddonTemplates(tree) {
    const checker = new VersionChecker(this.project);
    const emberDep = checker.for('ember');

    const baseTemplatesPath = path.join(this.root, 'addon/templates');

    // Conditionally provide templates based on Ember version
    if (emberDep.satisfies('>= 3.0.0')) {
      return this.treeGenerator(path.join(baseTemplatesPath, 'modern'));
    } else if (emberDep.satisfies('>= 2.0.0')) {
      return this.treeGenerator(path.join(baseTemplatesPath, 'classic'));
    } else {
      // Fallback for older Ember versions or non-existent Ember
      return this.treeGenerator(path.join(baseTemplatesPath, 'legacy'));
    }
  }
};

view raw JSON →