nrwl--nx/packages/devkit/CLAUDE.md

@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