Ember CLI Project Updater

3.0.1 · active · verified Wed Apr 22

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.

Common errors

```
Error: You must commit your package.json before running ember update
```
cause The `ember update` command (when installed locally) expects the `package.json` changes from its own installation to be committed before proceeding.

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`.
```
Conflicts detected, please resolve them and commit the result
```
cause The update process found differences between your project's files and the new blueprint version that Git could not automatically merge.

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.
```
Cannot read property 'name' of undefined (or similar error related to projectName)
```
cause This can occur in older versions of `ember-cli-update` if the `name` field is missing from your project's `package.json` file.

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.

Warnings

breaking Version 3.0.0 of ember-cli-update dropped support for Node.js versions older than 20.
Fix: Ensure your development environment uses Node.js v20 or newer before upgrading to ember-cli-update v3.x.
breaking Version 2.0.0 removed the deprecated ability to run as an `ember addon` command.
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`).
gotcha Upgrading Ember CLI projects past version 6.7.0 with `ember-cli-update` might not automatically handle the transition to Vite-based builds.
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.
gotcha Your Git working directory must be clean before running `ember-cli-update` or `ember update`.
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.
gotcha 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`.
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`.
gotcha Merge conflicts are common during updates, especially in projects with custom modifications.
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.
gotcha Running codemods (`--run-codemods`) should typically be done after the initial boilerplate update and *after* all merge conflicts have been resolved.
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.

Install

npm install ember-cli-update npm
yarn add ember-cli-update yarn
pnpm add ember-cli-update pnpm

Imports

Global CLI Invocation
wrong:
```
npm install -g ember-cli-update
ember-cli-update
```
correct:
```
pnpm add -g ember-cli-update
ember-cli-update
```
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.
Local Ember CLI Command Invocation
wrong:
```
ember update
```
correct:
```
ember install ember-cli-update
# Commit package.json changes FIRST
git add package.json package-lock.json || yarn.lock || pnpm-lock.yaml
git commit -m "Install ember-cli-update"
ember update
```
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.
Running Codemods
wrong:
```
ember-cli-update --run-codemods # before resolving conflicts
```
correct:
```
ember-cli-update --run-codemods
```
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.

Quickstart

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.

git init
pnpm init -y
pnpm add -D ember-cli@latest ember-cli-update
npx ember new my-ember-app --skip-npm --skip-git
cd my-ember-app
git add .
git commit -m "Initial Ember app"

# Simulate some changes (e.g., in app.js)
echo "// Custom comment" >> app/app.js

# Update to the latest version (assuming a new version is available)
ember update

# If merge conflicts arise, resolve them manually or use a merge tool
# For example, if app.js has conflicts, you'd edit it then:
# git add app/app.js
# git commit -m "Resolve conflicts after update"

# Then, run codemods if any are applicable for the version jump
ember update --run-codemods

# Verify the update
npx ember s

view raw JSON →