{"id":17000,"library":"ember-cli-version-checker","title":"Ember CLI Version Checker","description":"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.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/ember-cli-version-checker","tags":["javascript"],"install":[{"cmd":"npm install ember-cli-version-checker","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-version-checker","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-version-checker","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import VersionChecker from 'ember-cli-version-checker';","symbol":"VersionChecker","correct":"const VersionChecker = require('ember-cli-version-checker');"},{"note":"Methods are accessed on an instance of VersionChecker, which must be initialized with the `this.project` object from an Ember CLI addon context.","symbol":"VersionChecker instance methods (e.g., .for, .satisfies, .gte, .assertAbove)","correct":"const checker = new VersionChecker(this.project);\nconst dep = checker.for('ember-cli');\nif (dep.gte('2.0.0')) { /* ... */ }"}],"quickstart":{"code":"const path = require('path');\nconst VersionChecker = require('ember-cli-version-checker');\n\n// This code would typically reside in an Ember CLI addon's index.js file\n// inside the module.exports object.\nmodule.exports = {\n  name: 'my-awesome-addon',\n\n  init() {\n    this._super.init.apply(this, arguments);\n    const checker = new VersionChecker(this.project);\n\n    // Assert a minimum Ember CLI version\n    checker.for('ember-cli').assertAbove('2.13.0', '`my-awesome-addon` requires Ember CLI >= 2.13.0');\n\n    const emberDep = checker.for('ember');\n    if (!emberDep.exists()) {\n      console.warn('Ember.js not found in project dependencies. This addon may not function correctly.');\n    }\n\n    console.log(`Ember version: ${emberDep.version || 'N/A'}`);\n  },\n\n  treeForAddonTemplates(tree) {\n    const checker = new VersionChecker(this.project);\n    const emberDep = checker.for('ember');\n\n    const baseTemplatesPath = path.join(this.root, 'addon/templates');\n\n    // Conditionally provide templates based on Ember version\n    if (emberDep.satisfies('>= 3.0.0')) {\n      return this.treeGenerator(path.join(baseTemplatesPath, 'modern'));\n    } else if (emberDep.satisfies('>= 2.0.0')) {\n      return this.treeGenerator(path.join(baseTemplatesPath, 'classic'));\n    } else {\n      // Fallback for older Ember versions or non-existent Ember\n      return this.treeGenerator(path.join(baseTemplatesPath, 'legacy'));\n    }\n  }\n};","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 12.x LTS or higher).","message":"This package requires Node.js version `10.* || >= 12.*`. Usage with unsupported Node.js versions will result in errors.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure `new VersionChecker(this.project)` is called from within an Ember CLI addon's environment where `this.project` is available.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prioritize checking NPM dependencies. If you still rely on Bower, consider migrating to NPM/Yarn.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<5.0.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `VersionChecker` is called with `new VersionChecker(this.project)` within the scope of an Ember CLI addon or similar project context.","cause":"The `VersionChecker` was instantiated without a valid `this.project` object, which provides the necessary context for dependency resolution.","error":"TypeError: Cannot read properties of undefined (reading 'addonPackages')"},{"fix":"The user of your addon needs to upgrade the specified dependency in their application's `package.json` to meet the minimum version requirement.","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.","error":"Error: To use [your-addon-name] you must have [dependency-name] [minimum-version]"},{"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`.","cause":"The specified dependency (e.g., 'ember-cli-qunit') was not found in the consuming application's `node_modules` or `package.json`.","error":"Dependency version is 'undefined' or a method like '.exists()' returns false unexpectedly."}],"ecosystem":"npm","meta_description":null}