ember-codemod-v1-to-v2

Codemod to convert Ember addons to v2 addon format

Usage

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

Step 1. Quickly migrate to v2 format.

cd <path/to/your/project>
pnpx 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.
• Convert templates to strict mode.
• Update dependencies.
• Switch npm or yarn to pnpm.

Step 2. Review the addon package.

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

Step 3. Review the test-app package.

• [x] Update configuration files.1
• [x] Rename the remaining instances of dummy to test-app.
• [x] 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.cjs (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.

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.

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

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

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

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

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

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.

pnpx 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>

If you'd rather start over, you can use create-v2-addon-repo.

Compatibility

• Node.js v22 or above

Contributing

See the Contributing guide for details.

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.