Caveats about building npm packages

繁體中文 | English

Let's review the dumb things I've done when I was building npm packages. Here're three caveats might help you.

# Duplicate npm package

It's the dump thing happened when I was writing vuepress-plugin-disqus-comment (opens new window). The plugin name could've been vuepress-plugin-disqus. I pressed down yarn publish jovially when I finished. But looked at my terminal:

error Couldn't publish package: " You do not have permission to publish \"vuepress-plugin-disqus\". Are you logged in as the correct user?"

Stunned, but I figured it out eventually. I went to (opens new window) to search for vuepress-plugin-disqus, as I expected:

Duplicate plugin

Someone's built this plugin...

Please head (opens new window) to check whether a relevant package is built before you start burying yourself in work. I'm not telling you don't work on it, but you can at least consider whether making PRs to improve existed package or building another one from scratch.

Well, this is a more stupid thing. I wrote demo which required local program in my package, such as require("../../src/index". Since demo worked as I've expected, I published it. I'd just found out it can't work at all when I installed it to another project. Check package.json:

  "name": "vuepress-plugin-disqus-comment",
  "version": "0.2.0",
  "description": "Adding Disqus comments to VuePress",
  "keywords": ["comment", "disqus", "plugin", "vuepress"],
  "homepage": "",
  "bugs": {
    "url": ""
  "repository": {
    "type": "git",
    "url": "newsbielt703/vuepress-plugin-disqus"
  "license": "MIT",
  "author": "Billyyyyy3320 <>",
  "main": "index.js",
  "scripts": {
    "build:docs": "vuepress build docs --temp docs/.temp",
    "dev:docs": "vuepress dev docs --temp docs/.temp"
  "dependencies": {
    "vue-disqus": "^3.0.5"
  "devDependencies": {
    "vuepress": "^1.2.0",
    "vuepress-types": "^0.3.0"

And here's my directory:

├── docs
│   └──
├── package.json
├── src
│   ├── enhanceAppFile.js
│   └── index.js
└── yarn.lock

The path main indicated wasn't right at all !!

Leveraging npm link (opens new window) or yarn link (opens new window) can link a package into another project. I could've noticed that.

You may not make this low-level mistake, but remember to test you package with npm link, yarn link or even Yalc (opens new window) before publishing.

# .npmignore

There're three approaches to ignore files,.gitignore,.npmignore or the file property in package.json.

Suppose the .gitignore is something like:


node_modules and my_secret will be ignore not only by git but also by npm.

Unless there's .npmignore in your package. Let’s say you’ve written tests. Git should save the tests, whereas npm shouldn't upload them. You might want to use .npmignore in this case. If you write:


Oops, my_secret will be upload. .gitignore won't be referenced when .npmignore exists, so make sure you've put all the files or dirs which you want to exclude into .npmignore:


It's a big deal. I got to know it because of this article (opens new window).

It's worth to mention that you don't need to add node_modules to .npmignore since it'll be ignore automatically. Head npm (opens new window) for more details.

# The difference between package and module

I only understand the difference because of writing this post:

In short, a package requires a package.json to describe it. A module can just be a file or dir which can be loaded by others, and don't require a package.json. It's just like, a husky must be a dog, but a dog can be not a husky.

Head npm (opens new window) for more details.

Happy new year.