{"id":17215,"library":"ember-cli-update","title":"Ember CLI Project Updater","description":"Ember CLI Update is a command-line tool designed to help developers update their Ember.js application and addon boilerplate code to newer versions. It differentiates itself significantly from the default `ember init` command by applying a granular diff of changes between blueprint versions, thereby preserving existing user modifications and additions, rather than resetting the project to a clean slate. The tool supports updating official Ember CLI blueprints (e.g., `app`, `addon`, `glimmer`) as well as custom addon blueprints. The current stable version is 3.0.1, released on 2025-10-07. While there isn't a fixed release cadence, updates typically align with major Ember CLI blueprint changes and address bug fixes. Key differentiators include its non-destructive diffing approach, the ability to target specific Ember CLI versions for updates, and integrated support for automatically running applicable codemods to assist with broader code migrations.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/ember-cli-update","tags":["javascript","ember.js","ember-cli"],"install":[{"cmd":"npm install ember-cli-update","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-update","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-update","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"ember-cli-update is a thin wrapper around boilerplate-update for its core diffing and updating logic.","package":"boilerplate-update","optional":false}],"imports":[{"note":"Installs the CLI globally, allowing direct invocation as `ember-cli-update`. While `npm install -g` often works, `pnpm` is the recommended package manager for Ember projects.","wrong":"npm install -g ember-cli-update\nember-cli-update","symbol":"Global CLI Invocation","correct":"pnpm add -g ember-cli-update\nember-cli-update"},{"note":"Installs as an Ember CLI addon, integrating the command into `ember update`. This requires `ember-cli` to be present. Crucially, the installation's `package.json` changes must be committed before running `ember update` to avoid errors.","wrong":"ember update","symbol":"Local Ember CLI Command Invocation","correct":"ember install ember-cli-update\n# Commit package.json changes FIRST\ngit add package.json package-lock.json || yarn.lock || pnpm-lock.yaml\ngit commit -m \"Install ember-cli-update\"\nember update"},{"note":"This command should typically be run *after* the initial `ember-cli-update` or `ember update` command has completed and any merge conflicts have been resolved, to ensure codemods apply correctly to the updated boilerplate.","wrong":"ember-cli-update --run-codemods # before resolving conflicts","symbol":"Running Codemods","correct":"ember-cli-update --run-codemods"}],"quickstart":{"code":"git init\npnpm init -y\npnpm add -D ember-cli@latest ember-cli-update\nnpx ember new my-ember-app --skip-npm --skip-git\ncd my-ember-app\ngit add .\ngit commit -m \"Initial Ember app\"\n\n# Simulate some changes (e.g., in app.js)\necho \"// Custom comment\" >> app/app.js\n\n# Update to the latest version (assuming a new version is available)\nember update\n\n# If merge conflicts arise, resolve them manually or use a merge tool\n# For example, if app.js has conflicts, you'd edit it then:\n# git add app/app.js\n# git commit -m \"Resolve conflicts after update\"\n\n# Then, run codemods if any are applicable for the version jump\nember update --run-codemods\n\n# Verify the update\nnpx ember s","lang":"bash","description":"Demonstrates initializing an Ember project, making a small change, then updating it to the latest Ember CLI version and running associated codemods using the local `ember update` command."},"warnings":[{"fix":"Ensure your development environment uses Node.js v20 or newer before upgrading to ember-cli-update v3.x.","message":"Version 3.0.0 of ember-cli-update dropped support for Node.js versions older than 20.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always invoke `ember-cli-update` as a global command (`ember-cli-update`) or via `ember update` after installing it as a project addon (`ember install ember-cli-update`).","message":"Version 2.0.0 removed the deprecated ability to run as an `ember addon` command.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"The tool will warn users attempting to upgrade past 6.7.0. Users should be prepared for manual steps or consult Ember CLI documentation for migrating to Vite after the boilerplate update.","message":"Upgrading Ember CLI projects past version 6.7.0 with `ember-cli-update` might not automatically handle the transition to Vite-based builds.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Commit or stash all uncommitted changes in your project before attempting an update. This ensures a clean state for applying diffs and resolving potential conflicts.","message":"Your Git working directory must be clean before running `ember-cli-update` or `ember update`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"After running `ember install ember-cli-update`, stage and commit your `package.json` (and lockfile) changes to Git. Only then proceed with `ember update`.","message":"When installing `ember-cli-update` as a local addon (`ember install ember-cli-update`), you must commit the `package.json` changes *before* running `ember update`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"You will likely need to manually resolve conflicts using your preferred Git tools. The `--resolve-conflicts` option can launch your system's git merge tool automatically if conflicts are found.","message":"Merge conflicts are common during updates, especially in projects with custom modifications.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Perform the base update, resolve any file conflicts, commit those changes, and *then* run `ember-cli-update --run-codemods` to ensure codemods apply correctly to the updated codebase.","message":"Running codemods (`--run-codemods`) should typically be done after the initial boilerplate update and *after* all merge conflicts have been resolved.","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":"After running `ember install ember-cli-update`, use `git add package.json package-lock.json && git commit -m \"Install ember-cli-update\"` (or similar for other lockfiles) before executing `ember update`.","cause":"The `ember update` command (when installed locally) expects the `package.json` changes from its own installation to be committed before proceeding.","error":"Error: You must commit your package.json before running ember update"},{"fix":"Manually open the conflicting files (marked by Git with `<<<<<<<`, `=======`, `>>>>>>>`), resolve the differences, save the files, then `git add` the resolved files and `git commit` your changes. Alternatively, run `ember-cli-update --resolve-conflicts` to launch your configured Git merge tool.","cause":"The update process found differences between your project's files and the new blueprint version that Git could not automatically merge.","error":"Conflicts detected, please resolve them and commit the result"},{"fix":"Ensure that your `package.json` includes a `\"name\": \"your-project-name\"` field. This bug was fixed in `v2.0.1`, so upgrading `ember-cli-update` to `v2.0.1` or newer will also resolve it.","cause":"This can occur in older versions of `ember-cli-update` if the `name` field is missing from your project's `package.json` file.","error":"Cannot read property 'name' of undefined (or similar error related to projectName)"}],"ecosystem":"npm","meta_description":null}