Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/embroider-build/addon-blueprint
Blueprint for v2-formatted Ember addons
https://github.com/embroider-build/addon-blueprint
addon blueprint ember emberjs hacktoberfest javascript lib library npm package project scaffold testing typescript
Last synced: 1 day ago
JSON representation
Blueprint for v2-formatted Ember addons
- Host: GitHub
- URL: https://github.com/embroider-build/addon-blueprint
- Owner: embroider-build
- License: mit
- Created: 2022-01-18T20:29:56.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-10T21:47:30.000Z (11 days ago)
- Last Synced: 2025-01-12T20:05:55.630Z (9 days ago)
- Topics: addon, blueprint, ember, emberjs, hacktoberfest, javascript, lib, library, npm, package, project, scaffold, testing, typescript
- Language: TypeScript
- Homepage:
- Size: 1.27 MB
- Stars: 30
- Watchers: 9
- Forks: 28
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# @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](https://github.com/embroider-build/embroider/blob/main/PORTING-ADDONS-TO-V2.md)_ and
this blog post [Migrating an Ember addon to the next-gen v2 format
](https://www.kaliber5.de/de/blog/v2-addon_en).
## 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
```bash
npx ember-cli@latest 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`](https://pnpm.io/) as a default package manager.
Example:
```bash
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --pnpm
cd my-addon
```
#### `--npm`
Sets up the new addon with `npm` as a default.
Example:
```bash
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --npm
cd my-addon
```
#### `--yarn`
Sets up the new addon with `yarn` as a default.
Example:
```bash
npx ember-cli@latest 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:
```bash
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:
```bash
npx ember-cli@latest 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:
```bash
npx ember-cli@latest 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](https://github.com/embroider-build/embroider/blob/main/PORTING-ADDONS-TO-V2.md)
guide.
```bash
npx ember-cli@latest 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.
#### `--typescript`
Sets up the new addon with [`typescript`](https://www.typescriptlang.org/) support.
Example:
```bash
npx ember-cli@latest 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](https://github.com/ember-cli/ember-cli-update).
### 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 edit this: https://tree.nathanfriend.io/?s=(%27options!(%27fancy!true~fullPath3~trailingSlash3~rootDot3)~4(%274%27project-monorepo02addons05my-addon0*5package0*5test-app05...%27)~version!%271%27)*%20%200%5Cn5-%203!false4source!5*2%0154320*'
To generate this run:
```bash
cd project-monorepo
npx ember-cli@latest 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 edit this: https://tree.nathanfriend.io/?s=(%27options!(%27fancy!true~fullPath2~trailingSlash2~rootDot2)~5(%275%27project-monorepo04738904test39%27)~version!%271%27)*0640862!false3s*my-74-%205source!6%20%207addon8%5Cn9*...%01987654320*'
To generate this run:
```bash
cd project-monorepo
npx ember-cli@latest 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](LICENSE.md).