Ember CLI Deploy Revision Data

3.0.0 · active · verified Wed Apr 22

The `ember-cli-deploy-revision-data` package is an `ember-cli-deploy` plugin designed to generate unique revision data for Ember application deployments. This data typically includes a `revisionKey`, often derived from a file hash (like `index.html`), git commit, or versioning information, and a timestamp. This allows other `ember-cli-deploy` plugins to track and utilize specific build revisions for purposes like caching, atomic deployments, or revision previews. The current stable version is 3.0.0, which updated dependencies and tightened Node.js version requirements (now 14.x, 16.x, 18.x, or >=20). As an Ember ecosystem plugin, its release cadence is generally tied to Ember CLI and Node.js LTS cycles. Key differentiators include its configurable data generation strategies (e.g., `file-hash`, `git-tag-commit`, `version-commit`), its seamless integration into the `ember-cli-deploy` pipeline, and its ability to provide idempotent revision keys, crucial for reliable cache invalidation and atomic deployments.

Common errors

```
ENOENT: no such file or directory, stat 'dist/index.html'
```
cause The `file-hash` data generator (default) could not find the `index.html` file in the expected `distDir`. This typically means `ember-cli-deploy-build` did not run successfully or the `filePattern`/`distDir` options are incorrect.

fix Ensure `ember-cli-deploy-build` is installed and configured to run before `revision-data` in your `config/deploy.js` pipeline. Verify the `filePattern` and `distDir` configuration options match your build output. Run `ember deploy --verbose` to inspect the pipeline execution.
```
Error: This plugin relies on Git information but no Git repository was found. Please ensure you are running this within a Git repository.
```
cause You are using a `git-tag-commit` or `git-commit` data generator type, but the deployment environment does not have a Git repository initialized or accessible.

fix If deploying in a Git-managed project, ensure `.git` directory is present and accessible. If you're in a CI environment, ensure the repository is fully cloned (not a shallow clone without history). Alternatively, change the `type` configuration option to `file-hash` or `version-commit` if Git-based revision data is not strictly required.
```
Error: The 'ember-cli-deploy-revision-data' plugin requires Node.js version X.x.x or higher, but you are running Y.y.y.
```
cause Your Node.js environment does not meet the `engines` requirement specified in the package's `package.json` file. This is a common breaking change across major versions.

fix Upgrade your Node.js version to one supported by the plugin (e.g., `14.x || 16.x || 18.x || >= 20` for v3.0.0). Use a Node Version Manager like `nvm` to easily switch Node.js versions.

Warnings

breaking Version 3.0.0 introduced breaking changes related to dependency updates and increased Node.js version requirements. Projects upgrading from v2.x must ensure their Node.js environment meets the new minimums (14.x || 16.x || 18.x || >= 20).
Fix: Update your Node.js environment to version 14.x, 16.x, 18.x, or >= 20. Review your `package.json` dependencies and update them as recommended by `npm outdated` or `yarn outdated`.
breaking Version 2.0.0-beta.0 (which led to 2.0.0) raised the minimum Node.js version to 12. Prior to this, older Node.js versions might have been supported. Subsequent v3.0.0 further increased this requirement.
Fix: Upgrade your Node.js environment to at least version 12 to meet the `engines` requirements. For v3.0.0 and above, further Node.js upgrades are required.
breaking Older versions (e.g., v1.0.0-beta.0) involved upgrades to `ember-cli` and a shift to being a Node-only addon, along with replacing deprecated internal Ember CLI promise utilities with `rsvp`. This could impact projects running on very old Ember CLI versions or relying on specific internal addon behaviors.
Fix: Consult the `ember-cli-deploy` upgrade guides and `ember-cli` documentation for migrating to newer versions. Ensure `rsvp` is correctly integrated if you have custom logic relying on promise utilities.
gotcha When configuring the `scm` option, the default example `require('./lib/scm-data-generators')['git']` references an internal module path. Relying on such internal paths directly in your configuration can lead to breaking changes in patch or minor versions, as internal module structures are not part of the public API contract.
Fix: Avoid direct `require` statements to internal plugin paths. If custom SCM or data generation logic is required, consider implementing and providing your own custom class as described in the documentation, or contribute to the plugin if a widely useful feature is missing.
gotcha Using `git-tag-commit` or `git-commit` data generators requires a valid Git repository context. In CI/CD environments, ensure that the Git repository is properly cloned and accessible, including its full history (e.g., by ensuring a non-shallow clone). Partial Git information can lead to incomplete `revisionKey` generation.
Fix: Verify that your CI/CD setup performs a full Git clone (e.g., `git clone --depth=infinity` if necessary). Check CI logs for any Git-related errors. If Git information is not critical, consider using the `file-hash` or `version-commit` generators instead.

Install

npm install ember-cli-deploy-revision-data npm
yarn add ember-cli-deploy-revision-data yarn
pnpm add ember-cli-deploy-revision-data pnpm

Imports

EmberCliDeployRevisionDataPlugin
wrong:
```
import { EmberCliDeployRevisionDataPlugin } from 'ember-cli-deploy-revision-data';
```
correct:
```
const EmberCliDeployRevisionDataPlugin = require('ember-cli-deploy-revision-data');
```
This package is an Ember CLI Addon/Plugin that primarily operates within the Node.js environment via CommonJS exports. Direct programmatic interaction with its exported module is typically for advanced use cases like testing or building meta-addons, not for application-level imports. The primary usage for application developers is via `ember install` and configuration in `config/deploy.js`.
gitScmDataGenerator
wrong:
```
import { git } from 'ember-cli-deploy-revision-data/lib/scm-data-generators';
```
correct:
```
const gitScmDataGenerator = require('ember-cli-deploy-revision-data/lib/scm-data-generators')['git'];
```
This demonstrates how the default Git SCM data generator is referenced within the plugin's internal configuration (e.g., in `config/deploy.js` for custom `scm` options). Accessing internal modules directly via `require` is generally discouraged as their paths and exports are not part of the public API and may change in patch or minor releases. ESM `import` syntax is typically not supported for these internal CommonJS modules.
configObject
wrong:
```
import { revisionData } from 'ember-cli-deploy-revision-data/config';
// This is not how Ember CLI Addon configuration is imported or accessed directly.
```
correct:
```
// In config/deploy.js
module.exports = function(deployTarget) {
  let ENV = {
    'revision-data': {
      type: 'git-commit',
      filePattern: 'dist/my-app.html'
    }
  };
  return ENV;
};
```
Configuration for `ember-cli-deploy-revision-data` is done through the `ENV['revision-data']` object in your project's `config/deploy.js` file, which is a CommonJS module. This isn't a direct JavaScript import of a symbol from the package itself, but rather a declarative configuration pattern defined by `ember-cli-deploy` for its plugins.

Quickstart

This quickstart demonstrates how to install `ember-cli-deploy-revision-data` and configure it in your `config/deploy.js` to generate a `revisionKey` based on the `index.html` file hash, then run a basic deployment.

/* config/deploy.js */
module.exports = function(deployTarget) {
  let ENV = {
    build: {},
    'revision-data': {
      type: 'file-hash', // or 'git-tag-commit', 'git-commit', 'version-commit'
      filePattern: 'index.html', // default, can be customized
      distDir: function(context) {
        return context.distDir; // Uses context provided by ember-cli-deploy-build
      },
      distFiles: function(context) {
        return context.distFiles; // Uses context provided by ember-cli-deploy-build
      }
    }
  };

  // Example for a production deployment target
  if (deployTarget === 'production') {
    // Specific production settings can go here
    ENV.build.environment = 'production';
  }

  return ENV;
};

// In your terminal:
// Ensure ember-cli-deploy-build is installed first
// $ ember install ember-cli-deploy-build

// Install this plugin
// $ ember install ember-cli-deploy-revision-data

// Run the deployment pipeline
// $ ember deploy

view raw JSON →