ember-codemod-v1-to-v2

Codemod to convert Ember addons to v2 addon format

Features

• Follows closely @embroider/addon-blueprint
• Preserves your code whenever possible
• Supports ember-cli-typescript and glint
• Focuses on maintainability and extensibility

Usage

For examples, see ember-container-query and ember-render-helpers.

Step 1. Quickly migrate to v2 format.

cd <path/to/your/project>
npx ember-codemod-v1-to-v2 <arguments>

Important

Before you run ember-codemod-v1-to-v2, I recommend that you address existing tech debts (one at a time). That is, treat the v2 migration as its own thing.

Here are examples of what you may want to work on first:

• Meet prerequisites for v2 addon.
• Un-pod v1 addon.
• Update dependencies.
• Switch npm or yarn to pnpm.

Step 2. Review the addon package.

• Update configuration files.¹
• Install missing dependencies.
• Relative import paths must specify the file extension .js or .ts.
• Colocate stylesheets (if any). Let each component import the relevant stylesheet in the backing class.
• Confirm that you can run all scripts in package.json.

Step 3. Review the test-app package.

• Update configuration files.¹
• Rename the remaining instances of dummy to test-app.
• Confirm that you can run all scripts in package.json.

Step 4. Review the workspace root including CI/CD.

^{1. Files such as eslint.config.mjs, .gitignore, babel.config.json (addon only), config/environment.js (test-app only), ember-cli-build.js (test-app only), package.json, rollup.config.mjs (addon only), tsconfig.json, etc.}

Arguments

In most cases, I recommend running the codemod without any arguments (i.e. allow the default values). This is to help different Ember projects converge to one layout.

Optional: Specify the addon location

By default, the package name decides where the addon package lives. Pass --addon-location to override the logic. This may be useful if you have a workspace with many addons.

npx ember-codemod-v1-to-v2 --addon-location packages/ui/button

Optional: Specify the project root

Pass --root to run the codemod on a project somewhere else (i.e. not in the current directory).

npx ember-codemod-v1-to-v2 --root <path/to/your/project>

Optional: Specify the test-app location

By default, the test-app package lives in the folder test-app. Pass --test-app-location to override the logic.

npx ember-codemod-v1-to-v2 --test-app-location docs-app

Optional: Specify the test-app name

By default, the test-app package is named test-app. Pass --test-app-name to override the logic. This may be useful if you have a workspace with many addons.

npx ember-codemod-v1-to-v2 --test-app-name test-app-for-ui-button

Limitations

The codemod is designed to cover typical uses of an Ember addon. It is not designed to cover one-off cases (e.g. caused by a custom build).

To better meet your needs, consider cloning the repo and running the codemod locally.

cd <path/to/cloned/repo>

# Compile TypeScript
pnpm build

# Run codemod
./dist/bin/ember-codemod-v1-to-v2.js --root <path/to/your/project>

You can also look at another codemod called ember-addon-migrator.

Compatibility

• Node.js v20 or above

Contributing

See the Contributing guide for details.

If you have an open-sourced addon (v1 or v2) that I can use as a reference, reach out to me on Discord at ijlee2. Please star this project so that I can gauge its importance to you and the Ember community. ⭐

Credits

The codemod steps were based on Migrating an Ember addon to the next-gen v2 format and Guide: Porting an Addon to v2. The blueprints were derived from @embroider/addon-blueprint.

License

This project is licensed under the MIT License.