@tactical-ddd/nx 0.0.1-alpha.0 → 0.0.1-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# @tactical-ddd/nx
|
|
2
|
+
|
|
3
|
+
`@tactical-ddd/nx` is a collection of Nx generators for scaffolding and enforcing Domain-Driven Design (DDD) architectures inside your Nx monorepo.
|
|
4
|
+
|
|
5
|
+
The suite is being built out incrementally. Generators currently available:
|
|
6
|
+
|
|
7
|
+
- [`shared-kernel`](#shared-kernel-generator) — scaffolds the Shared Kernel, the agnostic foundation reused by every other module.
|
|
8
|
+
|
|
9
|
+
> More generators (e.g. `domain`) are planned. This document covers the generators shipped today.
|
|
10
|
+
|
|
11
|
+
## Shared Kernel Generator
|
|
12
|
+
|
|
13
|
+
The `shared-kernel` generator is designed to automatically deploy the **Shared Kernel** within your Nx monorepo. This forms the absolute foundation of the entire application architecture, containing completely agnostic (not tied to any specific business domain) code that is reused across all other modules in the system.
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
To run the generator, execute the following command in the root of your workspace:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
nx g @tactical-ddd/nx:shared-kernel
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The generator checks for the existence of libraries before creating them, making it safe to run multiple times to restore missing kernel layers.
|
|
24
|
+
|
|
25
|
+
## Architecture & Folder Structure
|
|
26
|
+
|
|
27
|
+
The generator creates three core libraries inside the `libs/shared/` directory:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
libs/shared/
|
|
31
|
+
├── contracts/ # Global types, DTOs, and interfaces (no implementation)
|
|
32
|
+
├── utils/ # Pure helpers and utility functions
|
|
33
|
+
└── infrastructure/ # API clients, storage adapters, and loggers
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### 1. 📦 contracts
|
|
37
|
+
|
|
38
|
+
**Nx Tags:** `scope:shared`, `type:contracts`
|
|
39
|
+
|
|
40
|
+
This is the lowest and most abstract layer of the application. It establishes the "social contracts" between different parts of the system and the backend.
|
|
41
|
+
|
|
42
|
+
- **What's inside:** Global TypeScript interfaces, data types, validation schemas (Zod/Yup), API response shapes (DTOs), and global domain event structures.
|
|
43
|
+
- **Features:** This library is generated without a unit test runner (`unitTestRunner: 'none'`) because it contains strictly compile-time types and interfaces that carry no executable logic.
|
|
44
|
+
- **Import Rule:** It is strictly forbidden to import anything into this library from any other modules in the workspace.
|
|
45
|
+
|
|
46
|
+
### 2. 🛠 utils
|
|
47
|
+
|
|
48
|
+
**Nx Tags:** `scope:shared`, `type:utils`
|
|
49
|
+
|
|
50
|
+
A layer of general-purpose utilities designed to solve purely technical computation and data transformation tasks.
|
|
51
|
+
|
|
52
|
+
- **What's inside:** Pure functions for strings, arrays, date formatting, mathematical calculations, and custom domain-agnostic RxJS operators.
|
|
53
|
+
- **Features:** Functions in this library must not have side effects and must remain decoupled from the application state.
|
|
54
|
+
- **Import Rule:** Can only import types from `libs/shared/contracts`.
|
|
55
|
+
|
|
56
|
+
### 3. 🌐 infrastructure
|
|
57
|
+
|
|
58
|
+
**Nx Tags:** `scope:shared`, `type:infrastructure`
|
|
59
|
+
|
|
60
|
+
The I/O (Input/Output) implementation layer that integrates your system with the outside world. This is the technical heart of your application's infrastructure.
|
|
61
|
+
|
|
62
|
+
- **What's inside:**
|
|
63
|
+
- HTTP/WebSocket client configurations (Axios instances, Fetch wrappers).
|
|
64
|
+
- Base wrappers for browser storage (localStorage, IndexedDB).
|
|
65
|
+
- Third-party service integrations (Sentry clients for logging, analytics trackers).
|
|
66
|
+
- State management configurations (`@tanstack/query-core` / base cache providers).
|
|
67
|
+
- **Import Rule:** Can freely import contracts from `libs/shared/contracts` and pure helpers from `libs/shared/utils`.
|
|
68
|
+
|
|
69
|
+
## Module Boundaries & Isolation Rules
|
|
70
|
+
|
|
71
|
+
The generator automatically tags these projects with `scope:shared`. In your root linter configuration (`eslint.config.js`), strict boundaries are enforced for these tags:
|
|
72
|
+
|
|
73
|
+
1. **Isolation from Business Logic:** Code inside `libs/shared/*` never and under no circumstances can import code from business domains (`libs/auth/*`, `libs/payments/*`, etc.). The shared kernel is completely isolated from business logic.
|
|
74
|
+
2. **Linear Layer Dependencies:** A strict hierarchy is maintained within the kernel itself:
|
|
75
|
+
- `contracts` knows about no one.
|
|
76
|
+
- `utils` only knows about `contracts`.
|
|
77
|
+
- `infrastructure` knows about both `contracts` and `utils`.
|