Skip to content

Turborepo, Nx and Lerna

Turborepo, Nx and Lerna run tasks on top of a package manager’s workspace. skif lints that workspace: the members come from the package manager’s declaration (pnpm-workspace.yaml or the workspaces of package.json), and lerna.json only when nothing else declares them (workspace patterns). From the task runner’s own files, skif reads what names dependencies, binaries and entry files.

skif lints the whole workspace from its root. Started in a member, it lints the workspace that lists the member (root), so run it once, at the root, not as a task of every package. To report on some packages only, pass -W <name or dir>; the analysis still covers the whole workspace.

Add a root script:

{
"scripts": {
"lint:deps": "skif"
},
"devDependencies": {
"@polylint/skif": "<version>"
}
}

With Turborepo, register it as a root task in turbo.json and run turbo run lint:deps:

{
"tasks": {
"//#lint:deps": { "cache": false }
}
}

skif reads files of every package, so a cached result can be stale; "cache": false avoids that. With Nx, run the script with the package manager (pnpm lint:deps), or as an nx:run-commands target of the root project, whose command skif reads as a script of the root.

In CI, run skif at the repository root with the GitHub Action or the npm package, next to the task runner, not through it:

- uses: actions/checkout@v7
- uses: polylint/skif@v0.8

What skif reads:

  • Scripts that run turbo. turbo is a binary the scripts use, so the package that provides it is used. Its arguments are task names, filters, pkg#task and arguments passed after --, never binaries or files, for every subcommand (turbo run, turbo watch, turbo prune, turbo gen, …).
  • Generators. When the package or one of its ancestors depends on turbo or @turbo/gen, the turbo plugin makes turbo/generators/config.{ts,js,cjs,mts,mjs} and plopfile.{ts,js,cjs,mts,mjs} of each package entries, so what they import is used.
  • The turborepo dependency family. unsynced-dependency-family checks turbo, turbo-ignore, @turbo/gen, eslint-config-turbo and eslint-plugin-turbo as one family by default.
  • packageManager. Turborepo 2 needs the root package.json to declare the package manager; root-package-manager-field reports a root without packageManager or devEngines.packageManager.
  • turbo prune --docker output. A recursive run (skif -r) skips the json and full trees of a directory without a package.json that holds a lockfile next to them (out/ by default), since both copy packages of the workspace. Start the run in that directory to lint them.

What skif does not read: the content of turbo.json and turbo.jsonc. Tasks, dependsOn, inputs, outputs, env and globalDependencies name no dependency or entry, so a code file named only there (a hash input) is judged like any other file and can be unused-files. Task names in scripts are not checked against the tasks turbo.json or the members define.

What skif reads, when the nx plugin is enabled (nx, @nx/* or @nrwl/* is a dependency of the package or an ancestor, or [js.plugins] nx = true):

  • nx.json: the packages of plugins, of executor keys of targetDefaults and of generators.
  • The nx key of package.json and every project.json a package owns, in any directory: executors, generators, command and nx:run-commands targets (read as scripts that run in the workspace root or in their cwd), target options that name entries (main, additionalEntryPoints) and tool configs (jestConfig, tsConfig, eslintConfig, …), and the {workspaceRoot} and {projectRoot} tokens.
  • Local plugins, executors and generators, named by a path or a paths alias of the root tsconfig.base.json, and the implementation, batchImplementation and factory files of their collections.
  • In an integrated workspace, each project without a package.json is a scope of the root: the tool configs in its directory (vite.config.ts, index.html, eslint.config.mjs, jest.config.ts, .babelrc, tsconfig.json) are read, and what they name counts for the root.
  • The root jest.config.ts that calls getJestProjects() or getJestProjectsAsync() reads each project’s Jest config, and nxE2EPreset() in a Cypress config gives the preset’s support and spec files.
  • nx exec -- <cmd> is walked as a command of the package. nx run and nx run-many take task names.

The details are under Nx workspaces and in ADR 0011.

missing-package-manifest does not report an Nx project (a directory with a project.json), or a grouping directory such as libs/cart under ["libs/*", "libs/*/*"] whose content is only selected members.

What skif does not read, or reads partly:

  • Nx’s project graph. skif does not run nx show projects; it finds projects by their project.json, below no gitignored or hidden directory, node_modules or build output.
  • A local plugin’s alias that the root tsconfig inherits through extends: only the root tsconfig’s own paths are read.
  • A plugin with no config file and no default entries in an integrated project runs there only when a target of the project runs the tool’s Nx executor (@nx/vite:build, @nrwl/vite:*). An executor whose package has another name does not apply the tool’s config-less conventions.
  • A buildable library whose package.json is not a workspace member is a separate project, as any directory with its own manifest: its files are not analysed.

Lerna 9 removed lerna bootstrap, lerna add and lerna link; the package manager installs and links the members.

What skif reads:

  • lerna.json next to the root package.json: its packages declare the members, and its npmClient names the package manager, only when no package-manager declaration exists. Otherwise skif follows the package manager.
  • lerna-packages-mismatch reports when packages selects other packages than the package manager’s declaration. Lerna reads its own packages first, then pnpm-workspace.yaml when npmClient is pnpm, then the workspaces of package.json, so lerna run and lerna publish would act on a different set than the one installed.
  • stale-lerna-config reports useWorkspaces and a missing version in lerna.json (rejected by Lerna 7 and later) and scripts that run lerna bootstrap, lerna add or lerna link (removed in Lerna 9). The release is read from node_modules/lerna, else from the root package.json; without one, nothing is reported.
  • lerna exec [flags] [--] <cmd> is walked as a command of the package, so lerna exec -- rimraf dist uses rimraf and an unlisted binary there is reported. lerna run <task> takes task names.

See Lerna for the precedence in full and ADR 0011.

A workspace dependency can exist only to order tasks: Turborepo’s ^build and Nx’s task dependencies follow it. When the member it names has none of main, module, exports, bin, browser, types and typings and owns no code file (a tooling, asset or style package), nothing can import it, and unused-dependencies and unused-dev-dependencies do not report it.

A member with a module entry or code is judged as before. When a package lists such a member only for task order, record that with a reason:

[js.workspaces."apps/web"]
ignore-dependencies = [
{ name = "@acme/config", reason = "listed so that turbo builds it first" },
]
  • turbo.json content is not read (above).
  • Nx: aliases inherited through extends, executors of another package name, and non-member buildable libraries (above).
  • A dependency on a member without a module entry and without code is never reported, also when it is stale.
  • A Lerna installed outside the root node_modules and not declared at the root is not seen, so stale-lerna-config stays silent.