Run a Nx repository with Putnami
@putnami/nx turns each project of a Nx workspace into a Putnami project,
with an edge to each project Nx says it depends on. Putnami selects what a
change affects and gives the verdict. The mode decides who runs the targets
and who caches them.
| Mode | Build, test and lint | Cache |
|---|---|---|
import |
A TypeScript project's targets whose script runs only bun build, bun test, vitest, jest or biome, a bare eslint lint, a build script that runs tsc alone, its @nx/vite:test or @nx/jest:jest test target, and the @nx/eslint:lint executor without other options, run as @putnami/typescript tasks; every other target runs nx run |
Putnami's, for the imported tasks; Nx's for the rest |
delegate |
Every target runs nx run <project>:<target> |
Nx's, local or Nx Cloud; Putnami caches nothing |
Adopt it
@putnami/nx is not published yet: until its first release, putnami init --from nx stops at the extension install, after it has written the workspace
files, and a workspace loads the extension from a source checkout.
At the root of the repository, where nx.json lies:
putnami init --from nxIn a terminal, init asks for the mode, with import preselected. Without a
terminal, in CI or from an agent, it imports. --mode import or
--mode delegate skips the question:
putnami init --from nx --mode delegateinit writes a workspace that declares @putnami/nx, records the mode in
options["@putnami/nx"].mode, installs the extension and runs
putnami projects sync. In import mode, the sync declares
@putnami/typescript only when a target moves to it, and init then
installs it: its workspace install runs the package manager the repository
declares, npm, pnpm, Yarn or Bun, which keeps its lockfile. When no target
moves, init installs nothing more, leaves the lockfile as it was, and says
that --mode delegate gives the same result (ADR 0017 of tooling/stacks).
The projects come from the graph Nx resolves, in this order:
- The graph export
graph.jsonat the root, when the repository has one (nx graph --file=graph.json). - The graph the repository's own Nx resolves: the sync runs
node_modules/.bin/nx graph --file=<temporary file>at the root. This graph holds the edges Nx infers from imports and the targets its plugins infer. Annx graphthat fails fails the sync andvalidate. nx.json, eachproject.jsonand each workspacepackage.json, when neither exists, such as before the dependencies are installed. This read misses what Nx infers, so the sync andvalidatewarn withnx.graph_static.
The sync lists each target no Putnami task runs: one line per target name
that several projects share, such as test:lib, with the count and the first
three projects. Map a named target to a task
gives such a target a task.
Rerun it
Rerun putnami init --from nx in the workspace it wrote to see what a sync
would change, such as after switching mode: it prints the diff of each
putnami.json and the mode change, and writes nothing. A switch to import
mode previews the targets that move to @putnami/typescript, and the
workspace config that declares it when one does. --apply records the mode
and synchronizes:
putnami init --from nx --mode delegate --applyWhat the sync writes
putnami projects sync runs the extension's sync task, in the mode the
workspace records. It writes in each project's putnami.json:
| Member | Value |
|---|---|
extensions |
@putnami/nx, and @putnami/typescript for an imported TypeScript project, beside any other extension the file names: a putnami.json that names extensions is claimed by those alone. The sync owns @putnami/typescript there: one written by hand on a project it does not import is removed at the next sync |
dependencies |
The project ID of each Nx project it depends on, such as /packages/pricing; a dependency on a project that is no Nx project is kept |
disable.jobs |
build, test or lint when the project has no such target and no target mapped to it; in import mode @putnami/nx:<task> for a target @putnami/typescript runs, and @putnami/typescript:<task> for one that keeps running through Nx. The sync owns these entries: one written by hand is replaced at the next sync |
commands.<task>.dependsOn |
In import mode, for each build, test or lint target that moved to @putnami/typescript, the dependsOn Nx resolves for it: the target's own, else its targetDefaults entry in nx.json, with "..." standing for that entry's list. ^build, ^test and ^lint stay as they are, and build, test or lint name the project's own target, so a moved test waits for the builds Nx would have run first. Any other entry, such as codegen or an object naming projects, is listed and not written. A target that keeps running through nx run writes none: Nx follows dependsOn itself. The sync owns this member for build, test and lint: one written by hand is replaced at the next sync, and every other command's is kept |
options.@putnami/nx.tasks.test.reports |
The JUnit and Cobertura or LCOV files the project's jest or vitest configuration names, relative to the project |
options.@putnami/nx.tasks.<task>.steps |
One nx run step per target the workspace maps to the task, on a project with no target named after it. The sync owns steps of that shape: it replaces one written by hand, and keeps steps with another argument, which are the project's own |
options.@putnami/typescript:test.runner |
In import mode, vitest or jest when @putnami/typescript runs a test target of that runner. The sync owns it: it removes it when the target no longer maps to Vitest or Jest |
options.@putnami/typescript.lint.linter |
eslint when the lint target @putnami/typescript takes over runs ESLint. The sync owns the value only while it is eslint: it removes it when the target no longer lints with ESLint, and keeps a biome the project chose |
options.@putnami/typescript.runtime |
node for an imported TypeScript project whose package.json start script runs node, or whose Nx serve target runs the @nx/js:node executor, so putnami serve, run and package --docker run it on Node. The sync writes it when the project declares no runtime and never changes one it declares |
It keeps every other member, and rewrites a file only when a member it owns changes, with two-space indentation and sorted keys. A project that left the graph loses the extension and what the sync owns.
Each edge the sync writes is Nx's project graph's (build-graph), in both
modes: the probe attributes it so, and workspace.declared_edge does not warn
about it and putnami deps prune does not remove it, even when no source file
imports the project.
The sync lists, with the reason, each target it maps to no Putnami task:
- a target other than
build,testandlint, such asserveore2e, that the workspace maps to no task: it still runs withnx run <project>:<target>; - in import mode, a
build,testorlinttarget of a project that is not TypeScript, or that runs something other than what@putnami/typescriptruns, which keeps running through Nx; - a delegated
testwhose configuration names no report: its result is the exit code alone.
Map a named target to a task
A Nx project often names its targets by variant, such as test:lib and
test:eslint, and Nx does not say which of them tests and which lints.
options["@putnami/nx"].targets in putnami.workspace.json maps a target
name to the task that runs it, build, test or lint:
{
"options": {
"@putnami/nx": {
"mode": "delegate",
"targets": {
"test:lib": "test",
"test:eslint": "lint",
"test:oxlint": "lint"
}
}
}
}Run putnami projects sync after an edit of the mapping. On each project
that has a mapped target and no target named after the task, the sync keeps
the task on and writes its steps in the project's putnami.json, one
nx run per mapped target, in name order:
{
"options": {
"@putnami/nx": {
"tasks": {
"lint": {
"steps": [
["npx", "--no", "nx", "run", "{component}:test:eslint", "--outputStyle=static"],
["npx", "--no", "nx", "run", "{component}:test:oxlint", "--outputStyle=static"]
]
}
}
}
}
}putnami lint then runs test:eslint, then test:oxlint, on each affected
project, and stops at the first that fails
(ADR 0005).
- A mapped target runs through
nx runin both modes: import mode does not move it to@putnami/typescript. To move it, name the target after its task in Nx. - A target named after the task outranks a mapped one: on a project with
testandtest:lib, the test task runstest, and the sync liststest:libwith that reason, on one line for the projects that share it. - A mapped test reads the reports the project's jest or vitest
configuration names, as a
testtarget does. Several targets mapped totestrun one after the other, and each one's exit code counts; when they write the same report file, the test and coverage summary is the last one's. Give each its own report path, or map one of them. - An entry that names a target no project has is reported as
nx.target_unmatched. A value other thanbuild,testorlint, or an entry for a target namedbuild,testorlint, fails the sync andvalidate, and nothing is written. - A target with no entry keeps its line in the sync's list.
Import mode
A project is TypeScript when it holds package.json and a tsconfig*.json
or a .ts source. @putnami/typescript takes over a target only when the
target's script, or nx:run-commands command, runs only what its task
runs, with no other command chained to it, or when it is a test target of an
executor that starts Vitest or Jest, so no target changes the tool that checks
it:
| Task | @putnami/typescript runs |
Script or command it takes over |
|---|---|---|
build |
bun build, or the project's tsc |
bun build …; a package.json build script that runs tsc alone; an @nx/js:tsc target whose emit the tsc build reproduces |
test |
The project's runner: bun test, Vitest or Jest |
bun test, vitest, jest, npx vitest or npx jest, with no argument but run, --coverage, --ci, --passWithNoTests and the like; the @nx/vite:test, @nx/vitest:test and @nx/jest:jest executors |
lint |
Biome, or the project's ESLint | biome …; eslint or eslint . alone, plainly or through npx, bunx, pnpm exec or yarn; or the @nx/eslint:lint executor with no option but lintFilePatterns naming the project root |
The test task keeps the project's runner, and reads its configuration, as the test command describes; the sync records the runner of an executor target, which leaves no script to read it from.
A build moves with its tsc (see
A library built with tsc)
when it runs the project's package.json build script and that script
runs tsc alone, or when its executor is @nx/js:tsc and the tsc build
writes what the executor writes
(ADR 0004).
The executor sets the config's outDir to its outputPath and its rootDir
to its rootDir option, else the project root, writes a package.json and
copies assets, so the sync reads its options as nx run passes them, the
targetDefaults entry of nx.json for @nx/js:tsc, else for build, else
for a glob that matches it, then the target, then its
defaultConfiguration, and maps it when:
- it sets no
assetsand notransformers, setsgeneratePackageJsontofalse, and sets no option beyondmain,tsConfig,outputPath,rootDir,clean,watchand the ones that only shape thepackage.jsonit no longer writes (external, which inlines dependencies, keeps it on Nx); - its
tsConfigis the config thetscbuild compiles: the one the project'sbuildscript names, which must runtscalone, elsetsconfig.lib.json, elsetsconfig.json; - its
outputPathis that config'soutDir, inside the project, and itsrootDir, else the project root, is therootDirthe config declares; - the build writes no
.tsbuildinfo, or the config names it withtsBuildInfoFile.
A library generated with outputPath {projectRoot}/dist,
generatePackageJson false and a tsconfig.lib.json with "rootDir": "src" and "outDir": "dist" moves once its rootDir option is
{projectRoot}/src. The sync then writes
options["@putnami/typescript"].compiler = "tsc" in the project's
putnami.json when the project sets none, since no build script selects
the tsc build, records that in options["@putnami/nx"].typescriptCompiler,
and removes only a value it wrote once the target no longer maps. A project
that sets another compiler keeps the target on Nx. Every other
@nx/js:tsc target keeps running through Nx, listed with the first
condition it fails, such as the legacy outputPath dist/<project> at the
workspace root. So does a tsc command an nx:run-commands target runs,
such as the build target the @nx/js/typescript plugin infers.
The TypeScript lint runs ESLint over the project with its configuration and
no command-line argument (ADR 0003):
an ESLint target with arguments or options, such as --max-warnings 0 or
maxWarnings, would lose them, so it stays on Nx and the sync lists it. The
sync reads an @nx/eslint:lint target's options in project.json or the nx
member of package.json, under the targetDefaults of nx.json for lint
and for the executor; a target with configurations, or one it cannot find,
stays on Nx. Move the options to the ESLint configuration and rerun the sync.
A prettier target, any other tsc command, a script that chains another
command such as eslint . && prettier --check ., and every other target an
Nx executor runs, such as @nx/webpack:webpack, keeps running through Nx,
and the sync lists it. One extension runs each task, so
no Putnami cache sits over Nx's.
An import also adopts Putnami's TypeScript conventions (D-066) on each
TypeScript project it hands to @putnami/typescript, so the projects that
depend on it build against its sources:
- A private
package.jsonwhose build moves to the Bun build, that declares noexports, whose top-levelmainortypesnames a file outsidesrc/, and whose project holdssrc/index.ts, gains"exports": { ".": "./src/index.ts" }: the Bun build writes nothing in the project. Atscbuild, or one that stays on Nx, writes the output itsmainnames, so its entry stays. Abun buildwhose entry the sync does not rewrite stays on Nx, and the sync lists it with its reason: a package that is not private, one whoseexportsname a build output, and one with nosrc/index.ts. - A test moves with
types: falseinoptions["@putnami/typescript:test"], since its script type-checked nothing. When a lint moves,putnami lint --impactedlints the projects a change touches, not their dependents, and the sync says so. - A lint whose script passes no write flag (
--write,--fix,--apply) moves withfix: falseinoptions["@putnami/typescript:lint"]: it checks and rewrites no file. When a Biome lint moves and the repository root holds nobiome.jsonorbiome.jsonc, the sync writes a rootbiome.jsonthat sets nothing, so the lint keeps Biome's defaults, and lists it. - A project with no
tsconfig*.jsongets atsconfig.jsonthat extends the root's. A project that holds another one, such astsconfig.lib.json, keeps its configuration, which Jest or ESLint may read.
The sync lists each file it writes, and a dry run shows its diff.
Import some projects of a delegated workspace
In delegate mode, options["@putnami/nx"].import lists project paths and
globs, such as /packages/pricing or /packages/*: a leading / is
ignored, and *, ? and [...] match within one path segment. The sync
writes each project an entry selects as import mode writes it, and every
other project as delegate mode writes it. Import mode reads no list.
putnami init --from nx --import /packages/pricing --applyadds the entry and synchronizes; the sync declares @putnami/typescript when
a target of an imported project moves to it. Without --apply it previews. An entry that selects no project is reported as
nx.import_unmatched. The sync job's import parameter outranks the option,
as mode does, so a preview reads the list it would record.
What a task runs
Each delegated task first compares npx --no -- nx --version with the nx
version the root package.json states in devDependencies or
dependencies. The -- hands --version to Nx: without it, npm's npx
answers with npm's own version. Another version fails the task with
stacks.toolchain_mismatch; toolchain.check: "warn" in
options["@putnami/nx"] of putnami.workspace.json runs every project anyway,
and a project's own putnami.json outranks it. The task then runs at the
workspace root:
npx --no nx run <project>:<target> --outputStyle=staticA task that runs mapped targets runs that
command once per target, with the target's name. npx --no runs the
repository's own Nx and never downloads one. Nx's
dependsOn runs the upstream targets, and Nx's cache answers them. Each task
depends only on its project's graph step, which runs nothing: a change runs
Nx on its project and the projects that depend on it. Putnami's cache is off
for every task, and the result records delegatedTo: nx.
The test task removes the reports the sync names before its run, then reads
them into the test and coverage summary. A path that names <rootDir> is
read from the project; under @nx/jest, jest-junit writes its
outputDirectory from the workspace root.
Keep the graph current
Nx infers edges from imports, so an import can change the graph with no
change to a manifest. putnami validate compares each project's
putnami.json with what a sync would write, and fails with nx.sync_stale
when one would change. Run putnami projects sync and commit the result.