jelhan/addon-blueprint

Blueprint for v2-formatted Ember addons

@embroider/addon-blueprint

Blueprint for scaffolding ember v2 addons

For migrating a v1 addon to a v2 addon, you may follow Porting Addons to V2 and this blog post Migrating an Ember addon to the next-gen v2 format .

WIP

This is still work in progress.

The blueprint contains a number of assumptions, e.g. using a monorepo using (yarn or npm) workspaces, with separate workspaces for the addon and the test-app. But there is plenty of room for bikeshedding here, so if you have suggestions about better ways to set this up, then please file an issue to discuss!

Usage

ember addon my-addon -b @embroider/addon-blueprint --yarn

Options

For all these options, you'll see a warning printed from ember-cli about unsupported options. ember-cli doesn't have a way to detect if flags are used by a blueprint.

--pnpm

Sets up the new addon with pnpm as a default package manager. Note, that because ember-cli doesn't support this flag, you'll need to also add --skip-npm (which skips install).

Example:

ember addon my-addon -b @embroider/addon-blueprint --pnpm --skip-npm
cd my-addon
pnpm install

--npm

Sets up the new addon with npm as a default. Note, that because ember-cli doesn't support this flag, you'll need to also add --skip-npm (which skips install).

Example:

ember addon my-addon -b @embroider/addon-blueprint --npm --skip-npm
cd my-addon
npm install

--yarn

Sets up the new addon with yarn as a default.

Example:

ember addon my-addon -b @embroider/addon-blueprint --yarn
cd my-addon
yarn install

--addon-location

The location / folder name of the addon can be customized via --addon-location.

Examples:

ember addon my-addon -b @embroider/addon-blueprint --addon-location=packages/the-addon
# generates
#   my-addon/packages/the-addon

--test-app-location

The location / folder name of the addon can be customized via --test-app-location.

Examples:

ember addon my-addon -b @embroider/addon-blueprint --test-app-location=test-app
# generates
#   my-addon/test-app

By default, {test app name} will be used.

--test-app-name

The name of the test-app can be customized via --test-app-name.

Examples:

ember addon my-addon -b @embroider/addon-blueprint --test-app-name=test-app-for-my-addon
# generates
#   my-addon/test-app-for-my-addon

By default, test-app will be used.

--addon-only

Will only create the addon, similar to the v1 addon behavior of ember addon my-addon. This is useful for incremental migrations of v1 addons to v2 addons where the process from the Porting Addons to V2 guide.

ember addon my-addon -b @embroider/addon-blueprint --addon-only
# generates non-monorepo:
#   my-addon/
#     .git
#     package.json

For incremental migration in monorepos, you'll want to also supply the --skip-git flag.

--release-it

If you want release-it behavior, (specifically provided by create-rwjblue-release-it-setup), use the --release-it flag

ember addon my-addon -b @embroider/addon-blueprint --yarn --release-it

Updating the addon

The blueprint supports ember-cli-update to update your addon with any changes that occurred in the blueprint since you created the addon. So to update your addons boilerplate, simply run ember-cli-update (or npx ember-cli-update if you haven't installed it globally).

For additional instructions, please consult its documentation.

In existing monorepos

To generate a new v2 addon inside an existing monorepo, cd to that repo's directory and run the command as usual. The blueprint will auto-detect an existing package.json and adapt to it. Specifically it will not create or override any files at the root folder, like the package.json itself.

Most likely though you would not want to use the default locations for the addon and the test app. Instead you should establish a convention how multiple addons and test-apps are located. With the aforementioned path options you can then make the blueprint emit the packages in the correct place.

Some more things to pay attention to:

• Pass the package manager option ( --npm, --yarn, --pnpm) that you already use!
• Make sure that the chosen addon and test-app locations are all covered by the configured workspace layout of your package manager!
• Each package should have a distinct name, so make provide unique names for your test apps instead of the default test-app by using the --test-app-name option.
• There is no start script at the root package.json anymore to start both the addon's build and the test app in watch mode. So you would have to run that start script with your package manager in both locations in parallel (separate terminal windows/tabs).
• Pass the skip-git option to not auto-commit the generated files. Most likely there will be things to adapt to you specific requirements before committing.
• The blueprint will omit all files usually generated at the root folder, including .prettierrc.js, and instead use whatever you have already defined in your existing monorepo. So you should run the lint:fix script for both the addon and the test-app, and eventually address any non-fixable linting issues or other configuration conventions related to your specific setup.

Some examples...

Group by name

We group by the name of the addon, the addon's package and its test app are co-located sub-folders:

project-monorepo
└── addons
    ├── my-addon
    │   ├── package
    │   └── test-app
    └── ...

To generate this run:

cd project-monorepo
ember addon my-addon -b @embroider/addon-blueprint \
  --skip-git \
  --skip-npm \
  --addon-location="addons/my-addon/package" \
  --test-app-name="test-app-for-my-addon" \
  --test-app-location="addons/my-addon/test-app"

Group by type

Addons and test-apps are separated:

project-monorepo
├── addons
│   ├── my-addon
│   └── ...
└── tests
    ├── my-addon
    └── ...

To generate this run:

cd project-monorepo
ember addon my-addon -b @embroider/addon-blueprint \
  --skip-git \
  --skip-npm \
  --addon-location="addons/my-addon" \
  --test-app-name="test-app-for-my-addon" \
  --test-app-location="tests/my-addon"

License

This project is licensed under the MIT License.