{"id":16956,"library":"calculate-cache-key-for-tree","title":"Ember-CLI Addon Tree Cache Key Builder","description":"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.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/ember-cli/calculate-cache-key-for-tree","tags":["javascript"],"install":[{"cmd":"npm install calculate-cache-key-for-tree","lang":"bash","label":"npm"},{"cmd":"yarn add calculate-cache-key-for-tree","lang":"bash","label":"yarn"},{"cmd":"pnpm add calculate-cache-key-for-tree","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { calculateCacheKeyForTree } from 'calculate-cache-key-for-tree';\n// Or incorrect default import:\nimport * as calculateCacheKeyForTree from 'calculate-cache-key-for-tree';","symbol":"calculateCacheKeyForTree","correct":"import calculateCacheKeyForTree from 'calculate-cache-key-for-tree';"},{"note":"Most common usage within Ember-CLI's internal Node.js modules.","symbol":"calculateCacheKeyForTree (CommonJS)","correct":"const calculateCacheKeyForTree = require('calculate-cache-key-for-tree');"}],"quickstart":{"code":"const calculateCacheKeyForTree = require('calculate-cache-key-for-tree');\nconst path = require('path');\n\n// Simulate an addon's package.json content\nconst addonPkg = {\n  name: 'my-ember-addon',\n  version: '1.0.0',\n  dependencies: {\n    'lodash': '^4.17.21'\n  }\n};\n\n// Simulate the base directory of the addon\nconst addonRoot = path.resolve('./node_modules/my-ember-addon');\n\n// The tree type, e.g., 'addon', 'app', 'vendor', 'templates', etc.\nconst treeType = 'addon';\n\n// Calculate the cache key for a specific addon tree\n// The arguments are typically (baseDir, packageName, packageJsonContent, treeType)\n// The actual arguments for the package itself, when used directly, might vary slightly\n// from Addon.prototype.cacheKeyForTree which uses `this.name`, `this.pkg`, `treeType`.\nconst cacheKey = calculateCacheKeyForTree(addonRoot, addonPkg.name, addonPkg, treeType);\n\nconsole.log(`Cache Key for '${addonPkg.name}' (treeType: '${treeType}'):`);\nconsole.log(cacheKey);\n\n// Example of how Ember-CLI's Addon class might use it (simplified):\nclass EmberAddon {\n  constructor(root, pkg, name) {\n    this.root = root;\n    this.pkg = pkg;\n    this.name = name;\n  }\n\n  cacheKeyForTree(treeType) {\n    // Internally calls the utility with its own context\n    return calculateCacheKeyForTree(this.root, this.name, this.pkg, treeType);\n  }\n}\n\nconst myAddon = new EmberAddon(addonRoot, addonPkg, addonPkg.name);\nconst addonTreeCacheKey = myAddon.cacheKeyForTree('addon');\nconsole.log(`Cache Key via simulated Addon instance: ${addonTreeCacheKey}`);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `calculateCacheKeyForTree` after an incorrect ES module named import, or trying to destructure a CommonJS default export.","error":"TypeError: calculateCacheKeyForTree is not a function"},{"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.","cause":"One of the path-related arguments passed to `calculateCacheKeyForTree` (e.g., `baseDir`) was `undefined` or `null`.","error":"Error: Path must be a string. Received undefined"}],"ecosystem":"npm","meta_description":null}