Awesome
@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 --pnpm
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.
Example:
ember addon my-addon -b @embroider/addon-blueprint --pnpm
cd my-addon
--npm
Sets up the new addon with npm
as a default.
Example:
ember addon my-addon -b @embroider/addon-blueprint --npm
cd my-addon
--yarn
Sets up the new addon with yarn
as a default.
Example:
ember addon my-addon -b @embroider/addon-blueprint --yarn
cd my-addon
--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
--typescript
Sets up the new addon with typescript
support.
Example:
ember addon my-addon -b @embroider/addon-blueprint --typescript
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 rootpackage.json
anymore to start both the addon's build and the test app in watch mode. So you would have to run thatstart
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 thelint: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.