Skip to content

Commit 2f46c9c

Browse files
cyrilletuzicyrilletuzi
committed
doc
1 parent 4d9c3ab commit 2f46c9c

20 files changed

+2233
-0
lines changed

‎walkthroughs/advancedOptions.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Angular Schematics - Advanced options
2+
3+
> 💎 **Pro edition**
4+
>
5+
> You love this extension? Thank you! But it represents months of *unpaid* work by a single contributor. So these features are only available in the Pro Edition.
6+
>
7+
> **[Learn more about the Pro edition and try it for free](https://cyrilletuzi.gumroad.com/l/schematicspro/1million)**
8+
>
9+
> ⚡️ To celebrate 1 million installations, the Pro edition is currently 50% off for a limited time.
10+
11+
The Pro edition includes the following advanced options:
12+
- standalone components imports automation
13+
- entry files export automation
14+
- interceptor provider automation
15+
16+
<br>
17+
18+
## Standalone components done right
19+
20+
Angular 14 introduced standalone components, with the official intent to simplify things by getting rid of NgModules. But it also means that now, you have to import everything single component, directive or pipe you use in every component.
21+
22+
The Pro edition allows you to directly pick the components, directives and pipes you need.
23+
24+
Currently, it supports:
25+
- Angular (NgIf, NgFor, RouterLink, FormsModule,...)
26+
- Ionic module and standalone components
27+
- Material modules and standalone components
28+
- PrimeNG modules
29+
- Kendo Angular modules
30+
- @ngx-translate/core
31+
- @ng-select/ng-select
32+
- @ng-bootstrap/ng-bootstrap
33+
- ngx-bootstrap
34+
- @asymmetrik/ngx-leaflet
35+
- @ngxs/form-plugin
36+
- angular-gridster2
37+
- highcharts-angular
38+
- ng-zorro-antd
39+
- ng2-charts
40+
- ng2-dragula
41+
- ng2-file-upload
42+
- ngx-clipboard
43+
- ngx-color-picker
44+
- ngx-countdown
45+
- ngx-echarts
46+
- ngx-file-drop
47+
- ngx-highlightjs
48+
- ngx-infinite-scroll
49+
- ngx-pagination
50+
- ngx-quill
51+
- ngx-spinner
52+
53+
And if your project uses other Angular libraries you would like to be added, just ask in [GitHub issues](https://github.com/cyrilletuzi/vscode-angular-schematics/issues/new/choose), with the "Pro edition - New standalone import" form!
54+
55+
<br>
56+
57+
## Entry files export automation
58+
59+
If your project uses entry files (`index.ts`, sometimes called "barrels"), how many times did you forget to export a new thing you added?
60+
61+
With the Pro edition, when generating something inside a folder with an entry file, you will be asked if it is public or private: if you choose "Public", the newly generated thing will automatically be added to the `index.ts` exports.
62+
63+
<br>
64+
65+
## Interceptor provider automation
66+
67+
An interceptor class alone does nothing. To be used, it must be added to a provider, what the Pro edition does automatically.
68+
69+
<br>
70+
71+
💎 **[Try the Pro edition for free](https://cyrilletuzi.gumroad.com/l/schematicspro/1million)** 💎
72+
73+
<br>
74+
75+
## Other guides
76+
77+
- [Documentation homepage](./documentation.md)
78+
- [First generation](./firstGeneration.md)
79+
- [Troubleshooting](./troubleshooting.md)
80+
- [Configuration](./configuration.md)
81+
- [Additional schematics 💎](./advancedSchematics.md)
82+
- [Legacy features 💎](./legacy.md)
83+
- [Custom schematics 💎](./customSchematics.md)
84+
- [Test schematics 💎](./testing.md)
85+
- [Predefined paths 💎](./predefinedPaths.md)
86+
87+
<br>

‎walkthroughs/advancedSchematics.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Angular Schematics - Additional schematics
2+
3+
> 💎 **Pro edition**
4+
>
5+
> You love this extension? Thank you! But it represents months of *unpaid* work by a single contributor. So these features are only available in the Pro Edition.
6+
>
7+
> **[Learn more about the Pro edition and try it for free](https://cyrilletuzi.gumroad.com/l/schematicspro/1million)**
8+
>
9+
> ⚡️ To celebrate 1 million installations, the Pro edition is currently 50% off for a limited time.
10+
11+
<br>
12+
13+
The additional schematics you get with the Pro edition include:
14+
- page
15+
- routes
16+
- synchronous reactive service with signal
17+
- asynchronous reactive service with RxJS
18+
- Material (dialog, table)
19+
- just ask for more!
20+
21+
## Page
22+
23+
How often did you forget to associate your page component to a route? It is the most missing schematic of the Angular CLI, and the Pro edition brings it to you.
24+
25+
The page schematic adds a special `Page` component type, with a `route` option to automatically add the route.
26+
27+
By default, for better application performances, pages are generated as lazy loaded components. But you can disable lazy loading in the configuration helper.
28+
29+
<br>
30+
31+
## Synchronous reactive service with signal
32+
33+
Angular 16 introduced signals to simplify reactivity management, but reactivity will always be a complex topic. So the Pro edition brings you a synchronous reactive service schematic with the new signal API, with documentation included.
34+
35+
<br>
36+
37+
## Asynchronous reactive service with RxJS
38+
39+
Signals are great but are synchronous, which does not fit to every situations. RxJS is still needed in some cases, and is more difficult to handle. So the Pro edition brings you an asynchronous reactive service schematic with RxJS with a normalized, simple and documented API to use.
40+
41+
<br>
42+
43+
## Just ask for more!
44+
45+
If you are a user of the Pro edition and you would like to have other schematics for Angular, Ionic or an Angular related library, just ask on [GitHub discussions](https://github.com/cyrilletuzi/vscode-angular-schematics/discussions).
46+
47+
<br>
48+
49+
💎 **[Try the Pro edition for free](https://cyrilletuzi.gumroad.com/l/schematicspro/1million)** 💎
50+
51+
<br>
52+
53+
## Other guides
54+
55+
- [Documentation homepage](./documentation.md)
56+
- [First generation](./firstGeneration.md)
57+
- [Troubleshooting](./troubleshooting.md)
58+
- [Configuration](./configuration.md)
59+
- [Advanced options 💎](./advancedOptions.md)
60+
- [Legacy features 💎](./legacy.md)
61+
- [Custom schematics 💎](./customSchematics.md)
62+
- [Test schematics 💎](./testing.md)
63+
- [Predefined paths 💎](./predefinedPaths.md)
64+
65+
<br>

‎walkthroughs/configuration.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Angular Schematics - Configuration
2+
3+
Some common options can be customized in a one click with the configuration helper:
4+
5+
- Copy settings from angular.json
6+
- Enable SCSS, Sass or Less styles ⚙️
7+
- Disable styles ⚙️
8+
- Enable external HTML templates ⚙️
9+
- Enable single file components (SFC) ⚙️
10+
- Enable or disable ngOnInit ⚙️
11+
- Disable change detection optimization ⚙️
12+
- Disable lazy loading ⚙️
13+
- Disable block CSS display ⚙️
14+
- Enable shadow DOM ⚙️
15+
- Set the selector prefix ⚙️
16+
- Force NgModules 💎
17+
- Force class interceptors 💎
18+
- Force class guards and resolvers 💎
19+
- Disabled predefined schematics 💎
20+
21+
⚙️ = in the Pro edition 💎, configurable per Angular project
22+
23+
**You can access the configuration helper at any time from the Angular logo on the left sidebar**, or from the VS Code menu:
24+
1. View
25+
2. Command Palette
26+
3. search "configuration"
27+
4. choose "Angular Schematics: Configuration helper"
28+
29+
<br>
30+
31+
## Where is configuration stored?
32+
33+
This extension stores the configuration in VS Code *workspace* settings. It means:
34+
- it is applied only to the current opened project
35+
- if you commit the `.vscode/settings.json` file (and you should), all your team will benefit from it
36+
- the configuration helper assists you to set the initial settings, if you want to change them afterwards, just edit the `.vscode/settings.json` file
37+
38+
<br>
39+
40+
## Copy settings from angular.json
41+
42+
This extension uses its own configuration. But if you have an *official and valid* `angular.json` with some `schematics` settings, the extension can copy them. It should detect the following settings:
43+
- SCSS, Sass or Less styles
44+
- no style
45+
- external HTML templates
46+
- single file components (SFC)
47+
- change detection optimization
48+
- shadow DOM
49+
50+
<br>
51+
52+
## Enable SCSS, Sass or Less styles
53+
54+
For projects with a design system still using CSS preprocessors (like SCSS for Angular Material or PrimeNG).
55+
56+
<br>
57+
58+
## Disable styles
59+
60+
For projects not using styles in components and pages because of alternative tools (like Tailwind CSS).
61+
62+
<br>
63+
64+
## Enable external HTML templates
65+
66+
Unlike the Angular CLI, inline HTML templates are the default in this extension because:
67+
- less files (separation of concerns is not separation of files)
68+
- it is easier to see the data bindings connections between the HTML and the class
69+
- it draws attention to the template length, to keep each component as small as possible
70+
- the official [Angular Language Service extension](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template) provides the same coloration and autocompletion as in HTML files
71+
72+
But you can switch to external HTML templates if you prefer.
73+
74+
<br>
75+
76+
## Enable single file components (SFC)
77+
78+
Some may want to go even further with single file components (inline HTML, inline styles and no subfolder).
79+
80+
<br>
81+
82+
## Enable or disable ngOnInit
83+
84+
By default in this extension:
85+
- components does not include `ngOnInit()` (because most pure components should not handle such logic)
86+
- pages includes `ngOnInit()` (because pages have to handle logic)
87+
88+
But you can enable or disable ngOnInit() as you wish.
89+
90+
<br>
91+
92+
## Disable change detection optimization
93+
94+
With the introduction of signals in Angular 16, the good practice is to optimize the change detection strategy of all components and pages to `OnPush`.
95+
96+
If your project uses Angular <=15, or if you or your team are not yet comfortable with these topics, you can disable the change detection optimization in pages and/or in components.
97+
98+
<br>
99+
100+
## Disable lazy loading
101+
102+
By default, for better application performances, pages are generated as lazy loaded components. But you can disable lazy loading.
103+
104+
<br>
105+
106+
## Disable block CSS display
107+
108+
Web components have an `inline` CSS display by default. It is a flaw of the standard, as 99% of components are in fact used as `block`s. So when generating components, `:host { display: block; }` is automatically added in styles, but you can disable it.
109+
110+
<br>
111+
112+
## Enable shadow DOM
113+
114+
For projects ready to use native shadow DOM view encapsulation.
115+
116+
<br>
117+
118+
## Set the selector prefix
119+
120+
Angular default prefix selector for components, directives and pipes is `app`.
121+
122+
If you want a different one, this is the only setting for which the extension uses the official `angular.json` `prefix` configuration, because this one is simple to get and in an Angular CLI monorepo, it can differ from one application or library to another.
123+
124+
<details>
125+
<summary>Example of angular.json</summary>
126+
127+
```json
128+
{
129+
"version": 1,
130+
"projects": {
131+
"some-app": {
132+
"projectType": "application",
133+
"prefix": "app"
134+
},
135+
"some-lib": {
136+
"projectType": "library",
137+
"prefix": "mycompany",
138+
}
139+
}
140+
}
141+
```
142+
</details>
143+
144+
But it requires a *valid and official* `angular.json`, which is not the case in all projects. Only such cases, set the selector prefix via the extension configuration helper. It will be global to the workspace.
145+
146+
<br>
147+
148+
## 💎 Force NgModules
149+
150+
In the Pro edition, if your project uses Angular <=13 or is not ready for standalone components yet.
151+
152+
<br>
153+
154+
## 💎 Class interceptors
155+
156+
In the Pro edition, if your project uses Angular <=14 or is not ready for functional interceptors yet.
157+
158+
<br>
159+
160+
## 💎 Class guards and resolvers
161+
162+
In the Pro edition, if your project uses Angular <=14.1 or is not ready for functional guards and resolvers yet. Note [class guards and resolvers are officially deprecated](https://angular.io/guide/deprecations#router-class-and-injection-token-guards) by Angular and planned for removal.
163+
164+
<br>
165+
166+
## 💎 Disable predefined schematics
167+
168+
In the Pro edition, if some of the predefined schematics do not suit your project, you can disable them, and even replace them with your own custom schematics.
169+
170+
<br>
171+
172+
💎 **[Try the Pro edition for free](https://cyrilletuzi.gumroad.com/l/schematicspro/1million)** 💎
173+
174+
<br>
175+
176+
## Other guides
177+
178+
- [Documentation homepage](./documentation.md)
179+
- [First generation](./firstGeneration.md)
180+
- [Troubleshooting](./troubleshooting.md)
181+
- [Additional schematics 💎](./advancedSchematics.md)
182+
- [Advanced options 💎](./advancedOptions.md)
183+
- [Legacy features 💎](./legacy.md)
184+
- [Custom schematics 💎](./customSchematics.md)
185+
- [Test schematics 💎](./testing.md)
186+
- [Predefined paths 💎](./predefinedPaths.md)
187+
188+
<br>

0 commit comments

Comments
 (0)