Sherif Linter for Monorepos

1.11.1 · active · verified Sun Apr 19

Sherif is an opinionated, zero-config linter specifically designed for TypeScript and JavaScript monorepos. Written in Rust for speed, it efficiently enforces consistency and prevents common regressions across multiple packages without requiring `node_modules` to be installed. It supports all major package managers (PNPM, Bun, NPM, Yarn) and is ideal for CI/CD environments. The current stable version is 1.11.1, with frequent minor releases indicating active development. Its key differentiators include its zero-configuration approach, high performance due to its Rust implementation, and comprehensive monorepo-specific rules, such as checking for multiple dependency versions or package manager consistency.

Common errors

```
Command not found: sherif
```
cause Sherif is a CLI tool and not globally installed, or `npx`/`dlx` is not correctly invoking it.

fix Ensure you are using `npx sherif` (or `pnpm dlx sherif`, `bunx sherif`, `yarn dlx sherif`) to run the command without global installation. Verify your `PATH` if attempting a direct global execution.
```
Autofix did not run in my CI/CD pipeline.
```
cause Sherif's `--fix` flag is automatically disabled when the `$CI` environment variable is detected to prevent unintended changes in automated builds.

fix Autofix should be run locally by developers before committing code. If an autofix step is required in CI, it usually indicates a deviation from best practices for CI/CD or needs to be explicitly enabled in a non-standard way (not recommended).
```
Error: multiple-dependency-versions rule: Dependency 'foo' has multiple versions across packages: 1.0.0, 1.2.0, 2.0.0
```
cause The `multiple-dependency-versions` rule detects inconsistencies in dependency versions across different packages within your monorepo.

fix Run `sherif --fix` to interactively select a canonical version for each conflicting dependency. For non-interactive environments, use `sherif --fix --select highest` or `sherif --fix --select lowest` to automatically resolve conflicts.
```
Node.js 20 actions are deprecated. Please update the action to use Node.js 24. For more information see https://github.blog/changelog/2023-09-22-github-actions-update-to-node-20/
```
cause The GitHub Action `QuiiBz/sherif@v1` upgraded its internal Node.js runtime requirement to v24 in Sherif v1.11.0, making it incompatible with workflows still using Node.js v20 or older for the action step.

fix Update your workflow to use `actions/setup-node@v4` (or newer) to configure Node.js v24 for the action or ensure the GitHub Actions runner environment provides Node.js 24.

Warnings

breaking The official GitHub Action for Sherif (`QuiiBz/sherif@v1`) now requires Node.js v24 for execution. If your CI runner is configured with an older Node.js version, the action will fail.
Fix: Update your GitHub Actions workflow to use `actions/setup-node@v4` or higher with `node-version: 24` or ensure your runner environment provides Node.js v24.
gotcha Sherif's `--fix` (autofix) functionality is automatically disabled in CI environments when the `$CI` environment variable is set. This prevents unintended modifications to your codebase during automated checks.
Fix: To fix issues in CI, run Sherif locally with `--fix`. If you need to perform an autofix step in CI (e.g., as part of a pre-commit check), you must explicitly run it in a non-CI environment or manage the changes outside the typical linting flow.
gotcha When running Sherif in CI, it is strongly recommended to specify a pinned version (e.g., `npx sherif@1.11.1` or `version: '1.11.1'` in the GitHub Action) instead of `@latest`. Using `@latest` can lead to unexpected regressions if a new Sherif release introduces breaking changes or new rules.
Fix: Always pin the Sherif version in your CI scripts and GitHub Actions workflows to ensure consistent behavior across builds.
gotcha By default, Sherif will exit with a non-zero code (`1`) only if error-level issues are found. If only warnings are present, it exits with `0`. This might cause CI pipelines to pass even with warnings.
Fix: Use the `--fail-on-warnings` flag (or `failOnWarnings: true` in `package.json` config) to force Sherif to exit with code `1` if any warnings are found, ensuring stricter CI enforcement.
gotcha When using `--fix` for the `multiple-dependency-versions` rule, Sherif interactively prompts the user to select which version to standardize on. This interactive prompt will block non-interactive environments like CI/CD.
Fix: In non-interactive environments, use the `--select highest` or `--select lowest` flag in conjunction with `--fix` to automatically choose the highest or lowest version for all conflicting dependencies. This bypasses the interactive prompt.

Install

npm install sherif-linux-x64 npm
yarn add sherif-linux-x64 yarn
pnpm add sherif-linux-x64 pnpm

Imports

CLI Invocation (recommended)
wrong:
```
npm install -g sherif; sherif
```
correct:
```
npx sherif@latest
```
Sherif is primarily used as a CLI tool via `npx` or package manager equivalents (`bunx`, `pnpm dlx`, `yarn dlx`) for temporary, version-controlled execution. Installing globally is not recommended as it bypasses version pinning.
CLI Invocation (version-pinned)
wrong:
```
npx sherif --fix
```
correct:
```
npx sherif@1.11.1 --fix
```
For CI/CD or production environments, always pin to a specific version to ensure reproducible builds and prevent unexpected regressions from new releases. `npx sherif@latest` should generally be avoided in CI.
GitHub Action
wrong:
```
uses: QuiiBz/sherif@v1
```
correct:
```
uses: QuiiBz/sherif@v1
with:
  version: 'v1.11.1'
```
When using the GitHub Action, explicitly specifying the `version` input is highly recommended. The `v1` major version tag for the action might automatically update, but pinning the `version` input ensures stability across CI runs. The action automatically searches for a `sherif` script in `package.json`.
Configuration in package.json
wrong:
```
{
  "name": "my-monorepo-root",
  "config": {
    "sherif": {
      "fix": false
    }
  }
}
```
correct:
```
{
  "name": "my-monorepo-root",
  "sherif": {
    "fix": false,
    "select": "highest"
  }
}
```
Sherif supports configuration directly in the root `package.json` under the `sherif` field. CLI arguments take precedence over `package.json` configuration.

Quickstart

Demonstrates how to set up Sherif in a monorepo's root `package.json` with scripts for linting and autofixing, including basic configuration options. It shows invoking Sherif via a `package.json` script.

{
  "name": "my-monorepo",
  "version": "1.0.0",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "lint:monorepo": "sherif",
    "lint:monorepo:fix": "sherif --fix"
  },
  "sherif": {
    "failOnWarnings": false,
    "ignoreRule": [
      "root-package-manager-field"
    ]
  }
}

// Create a dummy package to lint
// packages/ui/package.json
// {"name": "@my-monorepo/ui", "version": "1.0.0", "dependencies": {"lodash": "^4.17.21"}}

// Run from your monorepo root
npm install # or pnpm install, bun install, yarn install
npm run lint:monorepo
npm run lint:monorepo:fix

view raw JSON →