The npm community forum has been discontinued.
To discuss usage of npm, visit the GitHub Support Community.
Add comments to package.json and package-lock.json
I don’t think the docs are very clear on the specific purpose of these 2 files. Specifically how they relate to each other. Since they share a near identical name, a reader would think there is a relationship two the two and thus this relationship should be illustrated in the documents.
Would would be really useful is to know how node searches these 2 json files for the dependencies. Does one always occur before the other? How do duplicate dependencies get resolved? For example what if package-lock.json has ‘express’ in it but also so does your package.json. These questions and confusion can be avoided with a little bit more clarity from people that know this stuff really well.
I am not sure which docs you have seen. This one is about how purpose and usage of lock files and probably answers your questions:
And these two are more focused on the file format: