Sherif Linter for Monorepos

1.11.1 · active · verified Sun Apr 19

Sherif is an opinionated, zero-config linter designed specifically for TypeScript and JavaScript monorepos. It enforces a set of rules to standardize the developer experience and prevent common regressions in multi-package repositories. The current stable version is `1.11.1`, with new minor versions being released frequently, indicating active development. A key differentiator is its performance; it's written in Rust, runs very fast, and doesn't require `node_modules` to be installed to function, making it efficient for CI/CD pipelines. It supports all major package managers including PNPM, Bun, NPM, and Yarn, and is primarily intended to be run as a CLI tool.

Common errors

```
Command 'sherif' not found
```
cause Sherif is a CLI tool and not installed globally, or the `npx`/`dlx` command was not used.

fix Run Sherif using a package manager's executor: `npx sherif` (npm), `bunx sherif` (Bun), or `pnpm dlx sherif` (PNPM). If installed globally, ensure it's in your PATH.
```
Autofix is disabled in CI environments. Please run locally or use '--select' for relevant rules.
```
cause Attempting to use `sherif --fix` within a continuous integration pipeline, where automatic modifications are prevented.

fix To enable autofix in CI for rules like `multiple-dependency-versions`, explicitly add `--select highest` or `--select lowest` to your command. For other rules, run `sherif --fix` locally and commit the changes.
```
Missing configuration field: 'sherif'. Expected a 'sherif' object in root package.json for options 'fix', 'select', 'noInstall', 'failOnWarnings', 'ignoreDependency', 'ignorePackage'.
```
cause The `sherif` configuration block is missing from the root `package.json`, or the field names within it are incorrect (e.g., kebab-case instead of camelCase).

fix Add a `sherif` object to your root `package.json` with configuration options specified in `camelCase`, for example: `"sherif": { "failOnWarnings": false }`.
```
Multiple versions found for dependency 'react': ['18.0.0', '18.2.0']. Please choose one interactively or use '--select highest|lowest'.
```
cause The `multiple-dependency-versions` rule was triggered with `--fix` in a non-interactive environment (like CI) without the `--select` flag.

fix When running in non-interactive contexts, append `--select highest` or `--select lowest` to the `sherif --fix` command to automatically resolve version conflicts.

Warnings

breaking The official GitHub Action (`QuiiBz/sherif`) was updated to use Node.js v24. If your CI environment is still running Node.js v20 or older, this change will cause the action to fail or behave unexpectedly.
Fix: Upgrade your GitHub Actions runner or `setup-node` step to use Node.js v24 or higher for the Sherif action to function correctly. Alternatively, use the `npx` method with a specific Node.js version.
gotcha Running `sherif --fix` is automatically disabled in CI environments (where the `$CI` environment variable is set). This prevents unexpected modifications to your repository in automated pipelines.
Fix: To fix issues in CI, you must either run Sherif locally with `--fix` and commit the changes, or, for rules like `multiple-dependency-versions`, use the `--select highest` or `--select lowest` flag in CI to enable automated fixes without interactivity.
gotcha For non-interactive environments (e.g., CI/CD) and when using the `multiple-dependency-versions` rule with `--fix`, Sherif will prompt for version selection by default. This will cause the process to hang.
Fix: Always combine `--fix` with `--select highest` or `--select lowest` when running in non-interactive environments or CI to automatically choose a version without user input.
gotcha When configuring Sherif in the root `package.json`, the options must be provided in `camelCase` (e.g., `failOnWarnings`), whereas the equivalent CLI arguments use `kebab-case` (e.g., `--fail-on-warnings`). Mismatched casing will result in the configuration being ignored.
Fix: Ensure that all options defined under the `sherif` field in `package.json` adhere to `camelCase` naming conventions.
gotcha The `sherif-linux-x64-musl` package is a specific pre-compiled binary for Linux x64 with musl libc. Directly installing this package might not work on other operating systems or architectures.
Fix: For general usage, it is recommended to invoke Sherif using your package manager's `dlx` command (e.g., `npx sherif@latest`, `pnpm dlx sherif@latest`), which handles platform-specific binary selection automatically.
gotcha It is strongly recommended to pin Sherif to a specific version (e.g., `sherif@1.11.1`) in CI/CD pipelines instead of using `sherif@latest`. Using `@latest` can lead to unexpected behavior or breaking changes with new releases, potentially failing your builds.
Fix: Always specify a fixed version number when running Sherif in CI, for example, `npx sherif@1.11.1` or `uses: QuiiBz/sherif@v1.11.1`.

Install

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

Imports

sherif (CLI)
wrong:
```
import sherif from 'sherif-linux-x64-musl'
```
correct:
```
npx sherif@1.11.1
```
Sherif is a CLI tool and not intended for direct programmatic import in JavaScript/TypeScript. It should be executed via `npx`, `bunx`, `pnpm dlx`, or as a pre-installed binary.
Sherif Configuration
wrong:
```
import { SherifConfig } from 'sherif-linux-x64-musl'
```
correct:
```
/* package.json */
{
  "sherif": {
    "fix": false,
    "select": "highest"
  }
}
```
Configuration is provided as a `sherif` field in the root `package.json` using camelCase keys, not through a direct JS/TS import.
GitHub Action
wrong:
```
import { SherifAction } from 'sherif-linux-x64-musl'
```
correct:
```
uses: QuiiBz/sherif@v1
```
Sherif can be integrated into GitHub Actions using the dedicated `QuiiBz/sherif@v1` action, not as a JavaScript module.

Quickstart

This quickstart demonstrates how to install and run Sherif in a monorepo, including an example `package.json` configuration, and how to use the `--fix` and `--select` flags for automated issue resolution.

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

// To run the linter:
pnpm dlx sherif@latest

// To run the linter and automatically fix issues, selecting the highest version for dependencies:
pnpm dlx sherif@latest --fix --select highest

view raw JSON →