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 nx

In 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 delegate

init 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:

  1. The graph export graph.json at the root, when the repository has one (nx graph --file=graph.json).
  2. 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. An nx graph that fails fails the sync and validate.
  3. nx.json, each project.json and each workspace package.json, when neither exists, such as before the dependencies are installed. This read misses what Nx infers, so the sync and validate warn with nx.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 --apply

What 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, test and lint, such as serve or e2e, that the workspace maps to no task: it still runs with nx run <project>:<target>;
  • in import mode, a build, test or lint target of a project that is not TypeScript, or that runs something other than what @putnami/typescript runs, which keeps running through Nx;
  • a delegated test whose 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 run in 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 test and test:lib, the test task runs test, and the sync lists test:lib with 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 test target does. Several targets mapped to test run 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 than build, test or lint, or an entry for a target named build, test or lint, fails the sync and validate, 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 assets and no transformers, sets generatePackageJson to false, and sets no option beyond main, tsConfig, outputPath, rootDir, clean, watch and the ones that only shape the package.json it no longer writes (external, which inlines dependencies, keeps it on Nx);
  • its tsConfig is the config the tsc build compiles: the one the project's build script names, which must run tsc alone, else tsconfig.lib.json, else tsconfig.json;
  • its outputPath is that config's outDir, inside the project, and its rootDir, else the project root, is the rootDir the config declares;
  • the build writes no .tsbuildinfo, or the config names it with tsBuildInfoFile.

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.json whose build moves to the Bun build, that declares no exports, whose top-level main or types names a file outside src/, and whose project holds src/index.ts, gains "exports": { ".": "./src/index.ts" }: the Bun build writes nothing in the project. A tsc build, or one that stays on Nx, writes the output its main names, so its entry stays. A bun build whose entry the sync does not rewrite stays on Nx, and the sync lists it with its reason: a package that is not private, one whose exports name a build output, and one with no src/index.ts.
  • A test moves with types: false in options["@putnami/typescript:test"], since its script type-checked nothing. When a lint moves, putnami lint --impacted lints 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 with fix: false in options["@putnami/typescript:lint"]: it checks and rewrites no file. When a Biome lint moves and the repository root holds no biome.json or biome.jsonc, the sync writes a root biome.json that sets nothing, so the lint keeps Biome's defaults, and lists it.
  • A project with no tsconfig*.json gets a tsconfig.json that extends the root's. A project that holds another one, such as tsconfig.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 --apply

adds 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=static

A 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.