Skip to content

Commit 4b63110

Browse files
manfredsteyermanfredsteyer
committed
docs: add readme
1 parent a76c3dd commit 4b63110

File tree

3 files changed

+125
-112
lines changed

3 files changed

+125
-112
lines changed

‎README.md

Lines changed: 2 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,3 @@
1+
# @angular-architects/ddd -- DDD Plugin for Nx
12

2-
3-
# DddPlugin
4-
5-
This project was generated using [Nx](https://nx.dev).
6-
7-
<p style="text-align: center;"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="450"></p>
8-
9-
🔎 **Smart, Fast and Extensible Build System**
10-
11-
## Quick Start & Documentation
12-
13-
[Nx Documentation](https://nx.dev/angular)
14-
15-
[10-minute video showing all Nx features](https://nx.dev/getting-started/intro)
16-
17-
[Interactive Tutorial](https://nx.dev/react-tutorial/01-create-application)
18-
19-
## Adding capabilities to your workspace
20-
21-
Nx supports many plugins which add capabilities for developing different types of applications and different tools.
22-
23-
These capabilities include generating applications, libraries, etc as well as the devtools to test, and build projects as well.
24-
25-
Below are our core plugins:
26-
27-
- [Angular](https://angular.io)
28-
- `ng add @nrwl/angular`
29-
- [React](https://reactjs.org)
30-
- `ng add @nrwl/react`
31-
- Web (no framework frontends)
32-
- `ng add @nrwl/web`
33-
- [Nest](https://nestjs.com)
34-
- `ng add @nrwl/nest`
35-
- [Express](https://expressjs.com)
36-
- `ng add @nrwl/express`
37-
- [Node](https://nodejs.org)
38-
- `ng add @nrwl/node`
39-
40-
There are also many [community plugins](https://nx.dev/community) you could add.
41-
42-
## Generate an application
43-
44-
Run `ng g @nrwl/angular:app my-app` to generate an application.
45-
46-
> You can use any of the plugins above to generate applications as well.
47-
48-
When using Nx, you can create multiple applications and libraries in the same workspace.
49-
50-
## Generate a library
51-
52-
Run `ng g @nrwl/angular:lib my-lib` to generate a library.
53-
54-
> You can also use any of the plugins above to generate libraries as well.
55-
56-
Libraries are shareable across libraries and applications. They can be imported from `@ddd-plugin/mylib`.
57-
58-
## Development server
59-
60-
Run `ng serve my-app` for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
61-
62-
## Code scaffolding
63-
64-
Run `ng g component my-component --project=my-app` to generate a new component.
65-
66-
## Build
67-
68-
Run `ng build my-app` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build.
69-
70-
## Running unit tests
71-
72-
Run `ng test my-app` to execute the unit tests via [Jest](https://jestjs.io).
73-
74-
Run `nx affected:test` to execute the unit tests affected by a change.
75-
76-
## Running end-to-end tests
77-
78-
Run `ng e2e my-app` to execute the end-to-end tests via [Cypress](https://www.cypress.io).
79-
80-
Run `nx affected:e2e` to execute the end-to-end tests affected by a change.
81-
82-
## Understand your workspace
83-
84-
Run `nx graph` to see a diagram of the dependencies of your projects.
85-
86-
## Further help
87-
88-
Visit the [Nx Documentation](https://nx.dev/angular) to learn more.
89-
90-
91-
92-
93-
94-
95-
## ☁ Nx Cloud
96-
97-
### Distributed Computation Caching & Distributed Task Execution
98-
99-
<p style="text-align: center;"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-cloud-card.png"></p>
100-
101-
Nx Cloud pairs with Nx in order to enable you to build and test code more rapidly, by up to 10 times. Even teams that are new to Nx can connect to Nx Cloud and start saving time instantly.
102-
103-
Teams using Nx gain the advantage of building full-stack applications with their preferred framework alongside Nx’s advanced code generation and project dependency graph, plus a unified experience for both frontend and backend developers.
104-
105-
Visit [Nx Cloud](https://nx.app/) to learn more.
3+
see [libs/ddd/readme.md](libs/ddd/README.md)

‎libs/ddd/README.md

Lines changed: 122 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,127 @@
1-
# ddd
1+
# @angular-architects/ddd -- DDD Plugin for Nx
22

3-
This library was generated with [Nx](https://nx.dev).
3+
This plugin installs some schematics which automate slicing your Nx workspace into domains and layers according to Nrwl's best practices and our ideas about [client-side DDD with Angular](https://www.softwarearchitekt.at/aktuelles/sustainable-angular-architectures-1/):
44

5-
## Building
5+
![domains and layers](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd.png?raw=true)
66

7-
Run `nx build ddd` to build the library.
7+
The generated access restrictions prevent unwanted access between libraries respecting layers and domains:
88

9-
## Running unit tests
9+
![access restrictions](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/linting-2.png?raw=true)
1010

11-
Run `nx test ddd` to execute the unit tests via [Jest](https://jestjs.io).
11+
## Features
12+
13+
- 🗺️ Generating domains with domain libraries including a facades, models, and data services
14+
- ⚙️ Generating feature libraries including a feature components using the facades
15+
- 🙅‍♂️ Adding linting rules for access restrictions between domains as proposed by Nrwl
16+
- 🙅‍♀️ Adding linting rules for access restrictions between layers as proposed by Nrwl (supports tslint and eslint)
17+
- 🔥 Optionally generates skeleton for NGRX and integrates it into the DDD design (`--ngrx` switch)
18+
- 💥 Supports Standalone Components
19+
20+
### Features Overview Video
21+
22+
<a href="https://www.youtube.com/watch?v=39JLXMEE7Ds" target="_blank">![Screenshot of Overview Video](https://i.imgur.com/VlTRE80.png)</a>
23+
24+
## Usage
25+
26+
Add this plugin to a Nx workspace:
27+
28+
```
29+
npm i @angular-architects/ddd
30+
ng g @angular-architects/ddd:init
31+
```
32+
33+
Instead, you can also use ng add, however, Nx currently emits a warning when using ng add:
34+
35+
```
36+
ng add @angular-architects/ddd
37+
```
38+
39+
Add domains and features manually:
40+
41+
```
42+
ng g @angular-architects/ddd:domain booking --addApp
43+
ng g @angular-architects/ddd:domain boarding --addApp
44+
ng g @angular-architects/ddd:feature search --domain booking --entity flight
45+
ng g @angular-architects/ddd:feature cancel --domain booking
46+
ng g @angular-architects/ddd:feature manage --domain boarding
47+
```
48+
49+
For NGRX support, just add the `--ngrx` switch:
50+
51+
```
52+
ng g @angular-architects/ddd:domain luggage --addApp --ngrx
53+
ng g @angular-architects/ddd:feature checkin --domain luggage --entity luggage-list --ngrx
54+
[...]
55+
```
56+
57+
This example assumes that you have an app `flight-app` in place.
58+
59+
These schematics also wire up the individual libs. To see the result, create a dependency graph:
60+
61+
```
62+
npm run dep-graph
63+
```
64+
65+
![dependency graph](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd.png?raw=true)
66+
67+
To see that the skeleton works end-to-end, call the generated feature component in your `app.component.html`:
68+
69+
```html
70+
<booking-search></booking-search>
71+
```
72+
73+
You don't need any TypeScript or Angular imports. The plugin already took care about that. After running the example, you should see something like this:
74+
75+
![Result proving that the generated skeleton works end-to-end](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/result.png?raw=true)
76+
77+
## Standalone Components
78+
79+
All generators have a switch ``--standalone`` to support Standalone Components:
80+
81+
```
82+
ng g @angular-architects/ddd:domain booking --addApp --standalone
83+
84+
ng g @angular-architects/ddd:feature search --domain booking --entity flight --standalone
85+
```
86+
87+
Don't mix Standalone Components and traditional ones within the same domain.
88+
89+
## Generated Structure
90+
91+
The included schematics generate a folder for each domain. This folder contains feature libs as well as a library with the domain logic:
92+
93+
![Folder per Domain](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd-libs.png?raw=true)
94+
95+
The domain layer is subdivided into three parts:
96+
97+
![Structured Domain Layer](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/domain-layer.png?raw=true)
98+
99+
### Generated Structure for Domain Library
100+
101+
- **application:** Contains application services. This is a DDD term for what we call facades in Angular nowadays. They orchestrate everything for a use case given so that a feature component only needs to communicate with one such facade. Also, it hides details for state management. While the generates facades just use a `BehaviorSubject`, feel free to add a library like NGRX underneath. As such a modifications changes nothing from the component's perspective, you can use facades to introduce NGRX later on demand.
102+
- **entities:** Client-side data model including logic operating on it (like validations).
103+
- **infrastructure:** Services for communicating with the backend.
104+
105+
## Consider Automatically Checking Access Restrictions
106+
107+
As the access restrictions defined with Nx use linting, you can check against them at the command line too. Hence, you might consider including this into your automated build process.
108+
109+
![Access restrictions via linting](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/linting-3.png?raw=true)
110+
111+
## Example Application
112+
113+
see https://github.com/angular-architects/ddd-demo
114+
115+
## Credits
116+
117+
- [Nx](https://nx.dev/web)
118+
- [Nrwl's eBook about monorepos and best practices](https://go.nrwl.io/angular-enterprise-monorepo-patterns-new-book)
119+
- [Recording of session about this architecture](https://www.youtube.com/watch?v=94HFD391zkE&t=1s)
120+
- [Article series about DDD with Angular](https://www.softwarearchitekt.at/aktuelles/sustainable-angular-architectures-1/)
121+
- [Our eBook on Angular and architectures](https://leanpub.com/enterprise-angular)
122+
- [Thomas Burlison's article about facades in Angular](https://medium.com/@thomasburlesonIA/push-based-architectures-with-rxjs-81b327d7c32d)
123+
124+
## More
125+
126+
- [Angular Architecture Workshop](https://www.angulararchitects.io/en/angular-workshops/advanced-angular-enterprise-architecture-incl-ivy/)
127+
- [Follow us on Twitter](https://twitter.com/ManfredSteyer)

‎libs/ddd/package.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@angular-architects/ddd",
3-
"version": "2.0.0",
3+
"version": "2.1.0",
44
"license": "MIT",
55
"author": "Manfred Steyer",
66
"description": "Nx plugin for structuring a monorepo with domains and layers",
@@ -14,5 +14,4 @@
1414
"main": "src/index.js",
1515
"schematics": "./collection.json",
1616
"generators": "./collection.json"
17-
1817
}

0 commit comments

Comments
 (0)