When publishing to npm, declaring dependencies can be tricky

Here are a few suggestions for declaring npm package dependencies in 2022:

1. This may seem obvious, but in most cases, dependencies should be located in package.json. Nobody I know wants to type more than:
   npm i -s packagename
   They definitely don’t want to read documentation when it doesn’t work.
2. Don’t specify exact versions. Instead, reference (and test with!) minimum versions via ^ or ~. For example, if the package works with any release of version 2 of the dependency, use “^2.0.0” instead of “^2.1.5.” Leave the rest up to npm.
3. When referencing a package that has several actively maintained major versions, list each compatible version, e.g., “^1.0.0|^2.0.0”. This is common with popular packages like React and @hapi packages; thankfully, these packages are rare.
4. Peer dependencies are confusing, don’t work consistently across major npm versions, and don’t work with some ‘Node as a service’ providers like RunKit. Only declare them if you have to.
5. The no-optional flag for npm ci applies to every dependency. Therefore, declaring optional dependencies is pointless since few users of your package will be able to exclude them.
6. package-lock.json should be considered harmful. All users of your package maintain their own package-lock.json. In fact, there’s a downside to saving package-lock.json to GitHub: Dependabot etc. will eventually flag it for vulnerabilities unnecessarily.