ember-codemod-v1-to-v2

Codemod to convert Ember addons to v2 addon format

Features

Scaffolds files according to @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 the 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 the 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 .eslintrc.js, .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 v18 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.

ijlee2/ember-codemod-v1-to-v2