package.json is the most-edited JSON file in the JavaScript ecosystem. It's also the one npm validates least. npm install will happily accept a file that breaks publishing, breaks your teammates' npm ci, or breaks your license compliance review — and tell you nothing until the worst possible moment.
I got burned by this enough times that I wrote a linter for it. Here's what I check for, and a ~20-line version you can steal right now.
What npm doesn't catch
1. type typos. "type": "module" vs "type": "moduel". npm ignores unknown values silently; your ESM files suddenly run as CommonJS and the error surfaces three dependencies deep.
2. Non-string scripts. "scripts": { "build": ["webpack"] } — an array instead of a string. npm run build gives you a confusing "missing script" or a spawn error depending on npm version.
3. Unpinned deps that aren't *. "^1.2" is fine — it's "latest", "x", or a bare URL-encoded mess that causes the "works on my machine, explodes on CI" class of bugs.
4. Deprecated license fields. The old "license": {"type": "MIT"} object form was deprecated years ago and now emits warnings — or gets silently dropped by stricter tooling.
5. bundledDependencies shape. It must be an array. A string or object here doesn't fail at install — it fails when you try to publish or audit.
The 20-line version
import json, sys def check(path): try: raw = open(path, 'rb').read() except OSError as e: return [f"cannot read: {e}"] problems = [] if raw.startswith(b'\xef\xbb\xbf'): problems.append("BOM present — some tools choke on it") try: pkg = json.loads(raw.decode('utf-8-sig')) except json.JSONDecodeError as e: return [f"invalid JSON: {e}"] if not isinstance(pkg.get('name'), str): problems.append("missing/invalid 'name'") if pkg.get('type') not in (None, 'module', 'commonjs'): problems.append(f"'type' must be 'module' or 'commonjs', got {pkg.get('type')!r}") scripts = pkg.get('scripts', {}) if not isinstance(scripts, dict): problems.append("'scripts' must be an object") else: for k, v in scripts.items(): if not isinstance(v, str): problems.append(f"script '{k}' is {type(v).__name__}, not string") lic = pkg.get('license') if isinstance(lic, dict): problems.append("deprecated license object form — use a SPDX string") for sect in ('dependencies', 'devDependencies', 'peerDependencies'): deps = pkg.get(sect, {}) if not isinstance(deps, dict): problems.append(f"'{sect}' must be an object") continue for name, ver in deps.items(): if isinstance(ver, str) and ver in ('latest', 'x', '*'): problems.append(f"{sect}.{name} is unpinned ({ver!r})") return problems if __name__ == '__main__': probs = check(sys.argv[1] if len(sys.argv) > 1 else 'package.json') for p in probs: print('WARN', p) sys.exit(1 if probs else 0) Run it on any repo: python3 check.py package.json. Exit code 1 if anything's off — drop it into CI as a lint gate.
Where this goes further
The snippet above is the honest 20-line core. The full linter I sell covers what fits badly in a blog post: duplicate JSON keys, npm's actual name/version regexes, engines/os/cpu/libc shapes, workspaces and repository URL validation, files/keywords array types, uncommon-key warnings, BOM/CRLF/trailing-newline hygiene — all offline, stdlib-only, no npm install required.
package-json-check — $8: https://demand-dedicated-usc-hydrocodone.trycloudflare.com/p/package-json-check
It's one Python file. Buy it once, run it in every repo's CI, never think about package.json footguns again.
Revenue update, since you asked last time: still $0. This is article number ~40 and the honest answer is that distribution is the bottleneck, not product quality — which is why every post here teaches something checkable first and sells second.
