Skip to content

Commit b4af746

Browse files
committed
update readme
1 parent 90299e8 commit b4af746

1 file changed

Lines changed: 3 additions & 145 deletions

File tree

README.md

Lines changed: 3 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# @embroider/addon-blueprint
1+
# @ember/addon-blueprint
22

33
Blueprint for scaffolding ember v2 addons
44

@@ -8,14 +8,12 @@ this blog post [Migrating an Ember addon to the next-gen v2 format
88

99
## WIP
1010

11-
This is still work in progress.
12-
13-
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!
11+
This is still work in progress but we are aiming for this to be the new default for when someone generates an addon with `ember addon super-addon-name`. This will need an RFC to change the default but if you notice anything that you would like to be imporoved with this blueprint please open an issue to discuss, you don't need to wait for the RFC process to give us feedback.
1412

1513
## Usage
1614

1715
```bash
18-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --pnpm
16+
pnpm dlx ember-cli@latest addon my-addon -b @ember/addon-blueprint --pnpm
1917
```
2018

2119
### Options
@@ -45,74 +43,6 @@ npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --npm
4543
cd my-addon
4644
```
4745

48-
#### `--yarn`
49-
50-
Sets up the new addon with `yarn` as a default.
51-
52-
Example:
53-
54-
```bash
55-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --yarn
56-
cd my-addon
57-
```
58-
59-
#### `--addon-location`
60-
61-
The location / folder name of the addon can be customized via `--addon-location`.
62-
63-
Examples:
64-
65-
```bash
66-
ember addon my-addon -b @embroider/addon-blueprint --addon-location=packages/the-addon
67-
# generates
68-
# my-addon/packages/the-addon
69-
```
70-
71-
#### `--test-app-location`
72-
73-
The location / folder name of the addon can be customized via `--test-app-location`.
74-
75-
Examples:
76-
77-
```bash
78-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --test-app-location=test-app
79-
# generates
80-
# my-addon/test-app
81-
```
82-
83-
By default, `{test app name}` will be used.
84-
85-
#### `--test-app-name`
86-
87-
The name of the test-app can be customized via `--test-app-name`.
88-
89-
Examples:
90-
91-
```bash
92-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --test-app-name=test-app-for-my-addon
93-
# generates
94-
# my-addon/test-app-for-my-addon
95-
```
96-
97-
By default, `test-app` will be used.
98-
99-
#### `--addon-only`
100-
101-
Will only create the addon, similar to the v1 addon behavior of `ember addon my-addon`.
102-
This is useful for incremental migrations of v1 addons to v2 addons where the process from the
103-
[Porting Addons to V2](https://github.com/embroider-build/embroider/blob/main/PORTING-ADDONS-TO-V2.md)
104-
guide.
105-
106-
```bash
107-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint --addon-only
108-
# generates non-monorepo:
109-
# my-addon/
110-
# .git
111-
# package.json
112-
```
113-
114-
For incremental migration in monorepos, you'll want to also supply the `--skip-git` flag.
115-
11646
#### `--typescript`
11747

11848
Sets up the new addon with [`typescript`](https://www.typescriptlang.org/) support.
@@ -129,78 +59,6 @@ The blueprint supports `ember-cli-update` to update your addon with any changes
12959

13060
For additional instructions, please consult its [documentation](https://github.com/ember-cli/ember-cli-update).
13161

132-
### In existing monorepos
133-
134-
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.
135-
136-
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.
137-
138-
Some more things to pay attention to:
139-
140-
- Pass the package manager option ( `--npm`, `--yarn`, `--pnpm`) that you already use!
141-
- Make sure that the chosen addon and test-app locations are all covered by the configured workspace layout of your package manager!
142-
- 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.
143-
- 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).
144-
- 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.
145-
- 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.
146-
147-
Some examples...
148-
149-
#### Group by name
150-
151-
We group by the name of the addon, the addon's package and its test app are co-located sub-folders:
152-
153-
```
154-
project-monorepo
155-
└── addons
156-
├── my-addon
157-
│ ├── package
158-
│ └── test-app
159-
└── ...
160-
```
161-
162-
[//]: # '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*'
163-
164-
To generate this run:
165-
166-
```bash
167-
cd project-monorepo
168-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint \
169-
--skip-git \
170-
--skip-npm \
171-
--addon-location="addons/my-addon/package" \
172-
--test-app-name="test-app-for-my-addon" \
173-
--test-app-location="addons/my-addon/test-app"
174-
```
175-
176-
#### Group by type
177-
178-
Addons and test-apps are separated:
179-
180-
```
181-
project-monorepo
182-
├── addons
183-
│ ├── my-addon
184-
│ └── ...
185-
└── tests
186-
├── my-addon
187-
└── ...
188-
```
189-
190-
[//]: # '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*'
191-
192-
To generate this run:
193-
194-
```bash
195-
cd project-monorepo
196-
npx ember-cli@latest addon my-addon -b @embroider/addon-blueprint \
197-
--skip-git \
198-
--skip-npm \
199-
--addon-location="addons/my-addon" \
200-
--test-app-name="test-app-for-my-addon" \
201-
--test-app-location="tests/my-addon"
202-
```
203-
20462
## License
20563

20664
This project is licensed under the [MIT License](LICENSE.md).

0 commit comments

Comments
 (0)