wehub-resource-sync
63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# @nx/devkit
|
|
|
|
## Architecture
|
|
|
|
`@nx/devkit` serves two purposes: it **re-exports** core types and utilities from the `nx` package, and it **defines its own utilities** that are useful for plugin authors but aren't needed by `nx` core itself.
|
|
|
|
### Entry Point Structure
|
|
|
|
```
|
|
@nx/devkit (index.ts)
|
|
├── re-exports: nx/src/devkit-exports (stable public API)
|
|
├── exports: ./public-api (plugin-author utilities defined in devkit)
|
|
│ └── may import from: nx/src/devkit-internals (NOT re-exported to consumers)
|
|
│
|
|
├── @nx/devkit/testing → nx/src/devkit-testing-exports
|
|
├── @nx/devkit/ngcli-adapter → nx/src/adapter/ngcli-adapter
|
|
└── @nx/devkit/internal → nx/src/devkit-internals (subset)
|
|
```
|
|
|
|
## Version Compatibility Contract
|
|
|
|
**This is the most important thing to understand when modifying devkit or its nx entry points.**
|
|
|
|
`@nx/devkit` supports `nx` at the current major version **+/- 1 major version**. The `peerDependencies` in `package.json` encode this — e.g. `"nx": ">= 21 <= 23"` means `@nx/devkit@22` works with `nx@21`, `nx@22`, and `nx@23`.
|
|
|
|
### What This Means for Changes
|
|
|
|
#### `nx/src/devkit-exports.ts` (the public API surface)
|
|
|
|
- Everything exported here becomes the public API of `@nx/devkit`.
|
|
- **Minimize additions** — the file has a warning: "STOP! Try hard to not add to this API."
|
|
- New exports are safe for current consumers but adding then removing them creates breaking changes.
|
|
|
|
#### `nx/src/devkit-internals.ts` (semi-private bridge)
|
|
|
|
- These are used **internally** by `@nx/devkit`'s own implementation code (e.g. `packages/devkit/src/`).
|
|
- They are **NOT** part of `@nx/devkit`'s public API.
|
|
- The file warns: "These may not be available in certain versions of Nx, so be sure to check them first."
|
|
- **When `@nx/devkit` code imports from `devkit-internals`, it must handle the case where that export doesn't exist** in an older supported `nx` version. Guard with runtime checks or ensure the export has existed since the oldest supported major.
|
|
|
|
#### `packages/devkit/public-api.ts` (plugin-author utilities owned by devkit)
|
|
|
|
- Utilities implemented in `packages/devkit/src/` that are useful for plugin authors but not needed by `nx` core (e.g. `formatFiles`, `generateFiles`, `parseTargetString`).
|
|
- These are **defined here, not re-exported from `nx`** — devkit is the source of truth for this code.
|
|
- Code here may import from `nx/src/devkit-internals` — same version-guarding rules apply.
|
|
|
|
### Practical Guidelines
|
|
|
|
1. **Adding a new export to `devkit-exports.ts`**: This is a public API addition. Keep the surface area small. Once published, removing it is a breaking change.
|
|
2. **Adding a new export to `devkit-internals.ts`**: Safe to add, but any `@nx/devkit` code consuming it must account for older `nx` versions where it won't exist.
|
|
3. **Removing an export from either file**: Only safe if no published `@nx/devkit` version within the supported range depends on it.
|
|
4. **Changing the signature of an existing export**: Must remain compatible across all supported `nx` major versions.
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
| ------------------------------------------- | -------------------------------------------------------------------------- |
|
|
| `packages/devkit/index.ts` | Main entry point — re-exports from `nx` + `public-api` |
|
|
| `packages/devkit/public-api.ts` | Plugin-author utilities owned by devkit (formatFiles, generateFiles, etc.) |
|
|
| `packages/nx/src/devkit-exports.ts` | Stable public API surface exposed through `@nx/devkit` |
|
|
| `packages/nx/src/devkit-internals.ts` | Semi-private internals used by devkit's implementation |
|
|
| `packages/nx/src/devkit-testing-exports.ts` | Testing utilities for `@nx/devkit/testing` |
|