# package-linter

> A linter for npm dependencies in a repository

Latest version **1.0.0-alpha.7** (published 2026-04-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install package-linter
pnpm add package-linter
yarn add package-linter
bun add package-linter
```

Provides the command `packagelint`.

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0-alpha.7 |
| Published | 2026-04-20 |
| First published | 2022-07-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.5.0 |
| Dependencies | 6 |
| Unpacked size | 128.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Michael Loughry |
| Maintainers | mloughry |

## Links

- npm: https://www.npmjs.com/package/package-linter
- Repository: https://github.com/Microsoft/package-linter
- Homepage: https://github.com/Microsoft/package-linter#readme
- Issues: https://github.com/Microsoft/package-linter/issues
- npm.io page: https://npm.io/package/package-linter

## Dependencies (6)

- [ajv](https://npm.io/package/ajv.md) ^8.11.0
- [yargs](https://npm.io/package/yargs.md) ^17.5.1
- [globby](https://npm.io/package/globby.md) ^13.1.2
- [semver](https://npm.io/package/semver.md) ^7.3.7
- [cosmiconfig](https://npm.io/package/cosmiconfig.md) ^7.0.1
- [@yarnpkg/lockfile](https://npm.io/package/@yarnpkg/lockfile.md) ^1.1.0

## Recent versions

- 1.0.0-alpha.7 (latest) — 2026-04-20
- 1.0.0-alpha.6 — 2024-08-15
- 1.0.0-alpha.5 — 2023-04-20
- 1.0.0-alpha.4 — 2022-08-16
- 1.0.0-alpha.3 — 2022-07-21
- 1.0.0-alpha.2 — 2022-07-20
- 1.0.0-alpha.1 — 2022-07-20
- 1.0.0-alpha.0 — 2022-07-19

## README

# package-lint

A tool to lint your packages and dependencies automatically.

## Installation

If using `npm`:

```
npm install -D package-lint
```

If using `yarn`:

```
yarn add -D package-lint
```

## Usage

### CLI

```
packagelint [--createExceptions]
```

#### Arguments:

- `--createExceptions`: When specified, each error will specify a JSON entry you can add to your [exceptions file](#exceptionsdisable-directives) to disable the error.

### API

You can invoke the linter programatically like so:

```typescript
import { runLinter } from "package-lint";

const results = runLinter({
  config: {
    rules: {
      "some-rule": "error",
    },
    errorOnUnusedExceptions: true,
  },
  exceptions: { configFilePath: ".packageLintExceptions.json" },
});
```

#### Argument

`runLinter` takes one argument of type [`RuntimeApiArgs`](./src/types//RuntimeApiArgs.ts).

- `args` ([`CliArgs`](./src/types/CliArgs.ts) | `undefined`) -- allows you to specify [arguments normally passed in via the CLI](#arguments)
- `config` (`{ configFilePath: string }` | [`Configuration`](./src/types/Configuration.ts) | `undefined`) -- You can either specify a path to a configuration file, or specify the [configuration](#configuration-format) inline.
- `exceptions` (`{ configFilePath: string }` | [`RuleDisableFile`](./src/types/RuleDisableDirective.ts) | `undefined`) -- You can either specify a path to an exceptions file, or specify the [exceptions](#exceptionsdisable-directives) inline.

## Configuration

`packagelint` uses [`cosmiconfig`](https://github.com/davidtheclark/cosmiconfig#readme) for it's configuation. You can specify your configuartion file as any of the following:

- `package.json` field `packagelint`
- `.packagelintrc`
- `.packagelintrc.json`
- `.packagelintrc.yaml`
- `.packagelintrc.yml`
- `.packagelintrc.js`
- `.packagelintrc.cjs`
- `packagelint.config.js`
- `packagelint.config.cjs`

### Configuration format

The type [`Configuration`](./src/types/Configuration.ts) descripes the shape of the configuartion file.

- `rules`: A `Record<string, RuleEntry>` object that lists rules to run:
  - The key is the name of the rule, either one part of this package (`<rule name>`) or one from [another package](#building-your-own-rules) (`<package name>/<rule name>`)
  - The value is either `RuleSeverity` (`"error" | "warn" | "off"`), or a tuple of `[RuleSeverity, <rule options>]`, where `<rule options>` is defined by each rule.
- `errorOnUnusedExceptions`: An optional `boolean` that, when `true`, will cause `packagelint` to error when an [exception](#exceptionsdisable-directives) is specified that doesn't map to any error thrown by a rule during the run.
- `excludePaths`: An optional `string[]` of glob patterns for directories to exclude from `package.json` discovery. For example, `["**/fixtures/**", "**/test/**"]` will skip any `package.json` files found in those directories.

## Exceptions/disable directives

Since it is not possible to specify exceptions (sometimes called "disable directives" in other linters) directly in the JSON (particularly for external dependencies), all exceptions are specified in a separate file.

`packagelint` uses [`cosmiconfig`](https://github.com/davidtheclark/cosmiconfig#readme) for this. You can specify your exception file as any of the following:

- `package.json` field `packagelintexceptions`
- `.packagelintexceptionsrc`
- `.packagelintexceptionsrc.json`
- `.packagelintexceptionsrc.yaml`
- `.packagelintexceptionsrc.yml`
- `.packagelintexceptionsrc.js`
- `.packagelintexceptionsrc.cjs`
- `packagelintexceptions.config.js`
- `packagelintexceptions.config.cjs`

### Exception Format

The type [`RuleDisableFile`](./src/types/RuleDisableDirective.ts) describes the shape of the configuration file, which is an array of objects that match one or more aspects of a rule error (`ruleName`, `packageName`, `packageVersion`, or `jsonPath`). Any rule error that matches all _specified_ fields will be suppressed. Each entry can also specify a `justification` for the exception.

## Built-in rules

- `forbid-dependency` - Forbid specific dependencies or version ranges thereof from being included in the dependency tree
  - Options: `{ packageName: string | RegExp; semver?: string; }[]`
    - `packageName` can be a `string` or a `RegExp` to match against the name of a package
    - `semver` is a [semantic versioning](https://semver.org/) string that, when specified, restrict errors only to versions of `packageName` that match the semver string.
- `list-all-dependencies-in-root-package-json` - In a workspace repository, ensures that all external dependencies listed in indivdual packages are listed in the repository's root `package.json` with matching versions
- `no-duplicate-packages` - Reports an error when there are multiple copies (likely of two or more versions) of a dependency.
- `no-pinned-dependency` - Reports an error when a package has a dependency on a single version (eg., no `^` or `~` semver range) of another dependency.
- `no-tagged-versions` - Reports an error when a package has a dependency on a tagged version (eg., `1.0.0-beta.0`) of a dependency

## Building your own rules

> TODO: Fill this in

### Testing

> TODO: Fill this in

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.

---
_Source: https://npm.io/package/package-linter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._