eslint-plugin-lockfile

An ESLint plugin to lint your npm ecosystem lockfiles for security and consistency issues.

This plugin supports lockfiles from npm, yarn, pnpm, bun, and vlt package managers.

Installation

npm install eslint-plugin-lockfile --save-dev

Configuration

Flat Config (ESLint 9+)

// eslint.config.js
import lockfile from 'eslint-plugin-lockfile';

export default [
	lockfile.configs.recommended,
];

Legacy Config (ESLint 8)

{
	"extends": ["plugin:lockfile/recommended-legacy"]
}

Manual Configuration

// eslint.config.js
import lockfile from 'eslint-plugin-lockfile';

export default [
	{
		files: ['**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml', '**/bun.lock', '**/bun.lockb', '**/vlt-lock.json'],
		plugins: { lockfile },
		rules: {
			'lockfile/flavor': ['error', 'npm'],
			'lockfile/version': 'error',
			'lockfile/integrity': 'error',
			'lockfile/registry': 'error',
			'lockfile/non-registry-specifiers': 'error',
			'lockfile/binary-conflicts': 'error',
		},
	},
];

Supported Package Managers

| Package Manager | Lockfile(s) | |-----------------|-------------| | npm | package-lock.json, npm-shrinkwrap.json | | yarn | yarn.lock | | pnpm | pnpm-lock.yaml | | bun | bun.lock, bun.lockb | | vlt | vlt-lock.json |

Rules

| Name | Description | | :--- | :---------- | | binary-conflicts | Detect binary name conflicts between packages | | flavor | Enforce allowed lockfile formats | | integrity | Enforce integrity values in lockfiles | | non-registry-specifiers | Warn on dependencies from non-registry sources | | registry | Enforce allowed registries in lockfiles | | version | Enforce lockfile version |

lockfile/flavor

Enforces which lockfile formats are allowed in your project. This helps ensure your team uses a consistent package manager.

// Allow only npm lockfiles
'lockfile/flavor': ['error', 'npm']

// Allow npm or yarn
'lockfile/flavor': ['error', ['npm', 'yarn']]

// Allow specific lockfile variants
'lockfile/flavor': ['error', [{ name: 'npm', files: ['package-lock.json'] }]]

lockfile/version

Enforces lockfile versions to ensure consistency across environments.

// Default: latest versions for each package manager
'lockfile/version': 'error'

// Specific versions
'lockfile/version': ['error', { npm: 3, yarn: 2, pnpm: '9.0' }]

Valid versions:

• npm: 1, 2, 3
• yarn: 1, 2
• pnpm: '5.3', '5.4', '6.0', '6.1', '7.0', '9.0'
• bun: 0, 1
• vlt: 0

lockfile/integrity

Ensures all packages have integrity hashes and verifies they match the actual package tarballs. This protects against supply chain attacks.

// Default: allow all standard algorithms
'lockfile/integrity': 'error'

// Require specific algorithms
'lockfile/integrity': ['error', ['sha512', 'sha384']]

lockfile/registry

Enforces that all packages come from allowed registries. Useful for security policies and private registry enforcement.

// Default: uses npm config registry
'lockfile/registry': 'error'

// Single registry
'lockfile/registry': ['error', 'https://registry.npmjs.org']

// Multiple registries
'lockfile/registry': ['error', ['https://registry.npmjs.org', 'https://npm.pkg.github.com']]

// Per-package registry mapping
'lockfile/registry': ['error', {
	'https://registry.npmjs.org': true,  // Default for all packages
	'https://npm.pkg.github.com': ['@myorg/*'],  // Specific packages
}]

lockfile/non-registry-specifiers

Warns when packages are installed from non-registry sources like GitHub URLs, git URLs, or local file paths. These can bypass integrity checks.

// Warn on all non-registry specifiers
'lockfile/non-registry-specifiers': 'error'

// Ignore specific specifiers with explanation
'lockfile/non-registry-specifiers': ['error', {
	ignore: [
		{
			specifier: 'github:user/repo#commit',
			explanation: 'Required for unreleased bug fix',
		},
	],
}]

lockfile/binary-conflicts

Detects when multiple packages provide command-line binaries with the same name, which can cause non-deterministic behavior.

'lockfile/binary-conflicts': 'error'

CLI

For a standalone CLI that doesn't require ESLint configuration, see lintlock.

Tests

Clone the repo, npm install, and run npm test.

License

MIT