Ember-CLI Addon Tree Cache Key Builder

2.0.0 · maintenance · verified Wed Apr 22

The `calculate-cache-key-for-tree` package is a low-level utility specifically designed for Ember-CLI's build pipeline to enhance performance and enable caching of intermediate build artifacts. Currently at stable version 2.0.0, its release cadence is typically infrequent, tied closely to major or minor releases of Ember-CLI itself, as it serves a foundational role within the build system. This utility is critical for addon developers who implement custom `treeFor` or `treeFor*` hooks, allowing them to provide a cache key that prevents redundant processing of unchanged addon trees by the Broccoli build system. It generates a unique identifier based on factors like the addon's name, its `package.json` contents, and the specific tree type being processed (e.g., `addon`, `vendor`, `templates`). Unlike general-purpose caching libraries, its key differentiator is its tightly integrated and specialized function within the Ember-CLI addon ecosystem, primarily utilized internally by `EmberAddon` instances rather than directly by most application developers.

Common errors

```
TypeError: calculateCacheKeyForTree is not a function
```
cause Attempting to use `calculateCacheKeyForTree` after an incorrect ES module named import, or trying to destructure a CommonJS default export.

fix If using ES Modules, ensure you're using a default import: `import calculateCacheKeyForTree from 'calculate-cache-key-for-tree';`. If using CommonJS, use `const calculateCacheKeyForTree = require('calculate-cache-key-for-tree');`. This package exports a default function.
```
Error: Path must be a string. Received undefined
```
cause One of the path-related arguments passed to `calculateCacheKeyForTree` (e.g., `baseDir`) was `undefined` or `null`.

fix Ensure all required arguments, especially paths and object properties (like `package.json` contents), are valid strings or objects before passing them to the function. Double-check the source where these values are derived.

Warnings

gotcha This package has specific Node.js engine requirements (6.* || 8.* || >= 10.*). Using it with unsupported Node.js versions may lead to build failures or unexpected behavior. Always ensure your environment matches the specified engines. The package is fundamental to Ember-CLI's build process.
Fix: Ensure your Node.js version is compatible with the `engines` field specified in the `package.json`. Use `nvm` or similar tools to manage Node.js versions effectively.
gotcha This package is an internal utility primarily for Ember-CLI's core build processes and addon authors implementing custom `treeFor` hooks. Direct usage by application developers is uncommon and generally not recommended, as its API is tailored for the Ember-CLI build context.
Fix: Application developers should rely on Ember-CLI's standard build and caching mechanisms. Only addon authors with advanced needs for optimizing `treeFor` methods should consider direct interaction with this package, following Ember.js RFCs and documentation.

Install

npm install calculate-cache-key-for-tree npm
yarn add calculate-cache-key-for-tree yarn
pnpm add calculate-cache-key-for-tree pnpm

Imports

calculateCacheKeyForTree

wrong:

import { calculateCacheKeyForTree } from 'calculate-cache-key-for-tree';
// Or incorrect default import:
import * as calculateCacheKeyForTree from 'calculate-cache-key-for-tree';

correct:

import calculateCacheKeyForTree from 'calculate-cache-key-for-tree';

This package primarily exports a default function. While modern Node.js supports ESM `import`, CommonJS `require` is historically prevalent for this utility within Ember-CLI contexts.

calculateCacheKeyForTree (CommonJS)
```
const calculateCacheKeyForTree = require('calculate-cache-key-for-tree');
```
Most common usage within Ember-CLI's internal Node.js modules.

Quickstart

This example demonstrates how to import and use `calculate-cache-key-for-tree` to generate a cache key for an Ember-CLI addon's build tree. It simulates the context of an addon's root directory and `package.json` to produce a deterministic key used for build caching.

const calculateCacheKeyForTree = require('calculate-cache-key-for-tree');
const path = require('path');

// Simulate an addon's package.json content
const addonPkg = {
  name: 'my-ember-addon',
  version: '1.0.0',
  dependencies: {
    'lodash': '^4.17.21'
  }
};

// Simulate the base directory of the addon
const addonRoot = path.resolve('./node_modules/my-ember-addon');

// The tree type, e.g., 'addon', 'app', 'vendor', 'templates', etc.
const treeType = 'addon';

// Calculate the cache key for a specific addon tree
// The arguments are typically (baseDir, packageName, packageJsonContent, treeType)
// The actual arguments for the package itself, when used directly, might vary slightly
// from Addon.prototype.cacheKeyForTree which uses `this.name`, `this.pkg`, `treeType`.
const cacheKey = calculateCacheKeyForTree(addonRoot, addonPkg.name, addonPkg, treeType);

console.log(`Cache Key for '${addonPkg.name}' (treeType: '${treeType}'):`);
console.log(cacheKey);

// Example of how Ember-CLI's Addon class might use it (simplified):
class EmberAddon {
  constructor(root, pkg, name) {
    this.root = root;
    this.pkg = pkg;
    this.name = name;
  }

  cacheKeyForTree(treeType) {
    // Internally calls the utility with its own context
    return calculateCacheKeyForTree(this.root, this.name, this.pkg, treeType);
  }
}

const myAddon = new EmberAddon(addonRoot, addonPkg, addonPkg.name);
const addonTreeCacheKey = myAddon.cacheKeyForTree('addon');
console.log(`Cache Key via simulated Addon instance: ${addonTreeCacheKey}`);

view raw JSON →