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.
Running skif
Section titled “Running skif”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.8Turborepo
Section titled “Turborepo”What skif reads:
- Scripts that run
turbo.turbois a binary the scripts use, so the package that provides it is used. Its arguments are task names, filters,pkg#taskand 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
turboor@turbo/gen, theturboplugin makesturbo/generators/config.{ts,js,cjs,mts,mjs}andplopfile.{ts,js,cjs,mts,mjs}of each package entries, so what they import is used. - The
turborepodependency family.unsynced-dependency-familychecksturbo,turbo-ignore,@turbo/gen,eslint-config-turboandeslint-plugin-turboas one family by default. packageManager. Turborepo 2 needs the rootpackage.jsonto declare the package manager;root-package-manager-fieldreports a root withoutpackageManagerordevEngines.packageManager.turbo prune --dockeroutput. A recursive run (skif -r) skips thejsonandfulltrees of a directory without apackage.jsonthat 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 ofplugins, of executor keys oftargetDefaultsand ofgenerators.- The
nxkey ofpackage.jsonand everyproject.jsona package owns, in any directory: executors, generators,commandandnx:run-commandstargets (read as scripts that run in the workspace root or in theircwd), 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
pathsalias of the roottsconfig.base.json, and theimplementation,batchImplementationandfactoryfiles of their collections. - In an integrated workspace, each project without a
package.jsonis 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.tsthat callsgetJestProjects()orgetJestProjectsAsync()reads each project’s Jest config, andnxE2EPreset()in a Cypress config gives the preset’s support and spec files. nx exec -- <cmd>is walked as a command of the package.nx runandnx run-manytake 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 theirproject.json, below no gitignored or hidden directory,node_modulesor build output. - A local plugin’s alias that the root tsconfig inherits through
extends: only the root tsconfig’s ownpathsare 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.jsonis 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.jsonnext to the rootpackage.json: itspackagesdeclare the members, and itsnpmClientnames the package manager, only when no package-manager declaration exists. Otherwise skif follows the package manager.lerna-packages-mismatchreports whenpackagesselects other packages than the package manager’s declaration. Lerna reads its ownpackagesfirst, thenpnpm-workspace.yamlwhennpmClientispnpm, then theworkspacesofpackage.json, solerna runandlerna publishwould act on a different set than the one installed.stale-lerna-configreportsuseWorkspacesand a missingversioninlerna.json(rejected by Lerna 7 and later) and scripts that runlerna bootstrap,lerna addorlerna link(removed in Lerna 9). The release is read fromnode_modules/lerna, else from the rootpackage.json; without one, nothing is reported.lerna exec [flags] [--] <cmd>is walked as a command of the package, solerna exec -- rimraf distusesrimrafand an unlisted binary there is reported.lerna run <task>takes task names.
See Lerna for the precedence in full and ADR 0011.
Task-ordering dependencies
Section titled “Task-ordering dependencies”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" },]Known limits
Section titled “Known limits”turbo.jsoncontent 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_modulesand not declared at the root is not seen, sostale-lerna-configstays silent.