Top NPM Package.json Mistakes that Open Source Authors Make — And How to Fix Them
JavaScript is the most popular language used on GitHub today, in large part thanks to the variety of open-source packages available in the NPM index. Code published on NPM can reach an audience of millions of developers, from open-source hobbyists to large commercial enterprises.
As an open-source author who wants to grow your user community, it’s important to configure your package in NPM properly. A minor mistake in license or ownership data could block your package from being adopted by downstream users, or worse, get them into legal hot water!
In a recent study — detailed below — I found that almost half of the NPM packages used by a major open-source project have significant errors and omissions in NPM metadata or upstream code.
What’s the issue?
NPM relies on a file inside your project called package.json to discover author names, license terms, and other important data about your project. NPM’s official documentation describes the format of this file.
If the information in package.json is missing or incorrect, then potential users might bypass your project. Or worse, they might begin to use it, and then later discover that they must cut your package out of their codebase.
This can happen, for example, if you forget to clarify what open-source license applies to your project, or who its main contributors are.
The fixes for these problems are usually simple, like adding a standard LICENSE file or tweaking a few pieces of metadata.
An Automated Solution
A brief message about my new startup: I founded CorePlane to develop AI-powered tools to help developers and users of open-source software. We’re about to announce an automated solution to these NPM packaging woes — free for open-source projects, and seamlessly integrated with your GitHub workflow.
Now, back to the NPM action!
Case Study
I recently scanned the JavaScript dependencies of Mattermost, one of the top open-source projects on GitHub, to check how well NPM package maintainers follow best practices.
Out of 119 first-order dependencies, almost half had significant errors or omissions in package.json. These ranged from security issues like using http:// instead of https:// for project URLs, to problems that could trigger legal trouble for users of your package, like missing or incorrect license data.
22% of NPM packages are missing author and contributor names
It’s important for users of your package to know who authored it. Also, you should be credited properly for your work!
Be sure to specify an “author” in package.json. For projects with more than one author, you can also provide a list of “contributors”.
Examples of packages that are missing authorship data:
- Core-js https://github.com/zloirock/core-js
- React-native-recyclerview-list https://github.com/godness84/react-native-recyclerview-list
12% of NPM packages use an insecure URL for the homepage or repo
The pitfalls of insecure HTTP URLs are well known. Secure web hosting is easy to get now, thanks to services like Let’s Encrypt and cloud hosts like GitHub and CloudFlare that offer free secure HTTP for open-source projects.
Don’t let hackers launch a man-in-the-middle attack against users of your project. Use https:// URLs for all project and repo links.
Examples of packages with insecure http:// links in package.json:
- Commonmark.js https://github.com/commonmark/commonmark.js
- Underscore https://github.com/jashkenas/underscore
6% of NPM packages have no LICENSE file in the upstream source
The best practice for licensing your open-source project is to include the full text of a standard open-source license in a file called LICENSE in the root directory of your project. (some alternative filenames are also okay, like LICENSE.txt or LICENSE.md).
Platforms like GitHub and users of your package often use automated tools to check compliance with open-source licenses. Putting the full license text in a standard location is the best way to ensure these tools will identify your license.
I noticed that several packages specify an open-source license in a non-standard way. For example, some just name a license in the README.md file. This prevents most platforms and tools from recognizing the license terms of your package, which may limit its adoption among compliance-focused users.
Examples of packages that are missing a standard LICENSE file:
- ESLint-plugin-header https://github.com/Stuk/eslint-plugin-header
- React-native-image-gallery https://github.com/archriss/react-native-image-gallery
5% of NPM packages list a missing or incorrect license
A more serious problem is packages that specify no license at all, or list a license in NPM different from the one in the actual upstream LICENSE file.
If you publish an open-source project, make sure to pick a standard license and apply it both to your code and the NPM registry.
Examples of packages that have no license, or list the wrong license in NPM:
- React-native-document-picker https://github.com/Elyx0/react-native-document-picker
- React-native-image-picker https://github.com/react-community/react-native-image-picker (edit: now fixed)
3% of NPM packages are missing a link to the source repository
Users of your package need to know where to find the original source code to send patches or submit bug reports. Plus, for projects hosted on GitHub, automated tools can better understand your code when the GitHub repo is linked from NPM.
Be sure to specify a “repository” in your package.json following the recommended format in the NPM documentation.
Examples of packages that are missing a “repository” link in package.json:
- React-native-cookies https://github.com/joeferraro/react-native-cookies
- Redux-action-buffer https://github.com/rt2zz/redux-action-buffer
Summary
Here are the top take-away tips for NPM package maintainers:
- List an “author” or “contributors” in package.json
- Ensure all URLs are https://
- Keep your open-source license in a standard location, preferably a file named LICENSE in the project root
- Ensure package.json lists the same license
- Include a link to the source repository in package.json
Finally, please sign up below for early access to CorePlane’s free automated tools for open source projects!
