Publish a VueJS component on NPM (it’s not scary)

Step 0 — Your Vue project

This step deals with the basic project setup. Feel free to skip ahead for packaging-specific steps.

npm install -g @vue/cli
vue create my-project
# use default options
cd my-project
git remote add origin https://github.com/username/my-project.git
git push -u origin master
npm run serve
package.json
readme.md
LICENSE
src/
App.vue
MyComponent.vue
main.js
dist/
.gitignore

Step 1 — Configure the package.json file

Publishing a library is closer to bookkeeping than to rocket science. It pays to properly set up and document your library. What’s the point if others cannot find it or cannot make sense of it? Or if you don’t fix bugs because the overhead of updating the package is too great?

{
"name": "my-component",
"version": "0.1.0",
"description": "Describes my component",
"author": {
"name": "My Name",
"email": "optional@email.com"
},
"repository": "https://github.com/username/project",
"bugs": "https://github.com/username/vproject/issues",
"keywords": ["words", "go", "here"],
"license": "MIT",
"private": false,
"files": ["dist"],
"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"build:npm": "vue-cli-service build --target lib --name myComponent src/MyComponent.vue",
},
"main": "dist/myComponent.umd.js",
"unpkg": "dist/myComponent.umd.min.js",
...}
  • name — Name for the package that will appear in NPM.
  • version — Semantic version. We will get to that in step 3.
  • description, author, repository, bugs, keywords, license — Additional info for use in NPM.
  • private true or false. NPM will try to publish publicly, and that will fail if you have the package set to private.
  • files — Determines what files and folders will be published by NPM. If this option is not set, it will look at the .gitignore (or .npmignore, but we have none) file for inspiration. That will cause your source code and not the built bundles to be published. Exactly the opposite of what we want.
  • scripts.build:npm — This is the build script for the package, powered by vue-cli-service: --target lib sets the build target to a library and --name myComponent sets the basic filename.
npm run build:npm  # Building for production as library (commonjs,umd,umd-min)...
myComponent.common.js
myComponent.common.js.map
myComponent.umd.js
myComponent.umd.js.map
myComponent.umd.min.js
myComponent.umd.min.js.map

Step 2 — Add a proper readme

A proper readme is very important. Research shows that 65% of potential users will base their view of a library on the readme and 90% will leave frustrated if they cannot find instructions on how to install and use it [I completely made this up].

  • Can you tell me what problem it solves in two sentences?
  • How do I install it?
  • How do I use / interact with it?
  • Which license is applied?
  • Can you show me examples of the thing at work?
  • How does it work under the hood?
  • Project status: builds / tests?
  • How can I contribute?
  • Which technologies have been used?

Step 3 — Versioning

This is one I kept postponing for my own projects, but turn out to be really convenient and easy. NPM even automatically integrates with Git tags, so you do not have to duplicate efforts or even run the risk of your version numbers getting out of sync.

# Make sure the working directory is clean
git add -A
git commit -m "Changes"
# Increment semantic version with npm
npm version patch -m "Bump the version number"
git tag
# v0.1.1
git push --follow-tags

Step 4 — Publish and use

To publish on npmjs.com, you need a free npm account. Create it from the command line:

npm adduser
npm login
npm run build:npm
npm publish
npm install my-component
<script src=”https://unpkg.com/my-component@latest/dist/myComponent.umd.min.js"></script>

Remark: please no source code in libraries

I have seen libraries that send all the source code, demo files, etc to NPM. Please don’t do that, you are giving NPM a bad name.

  • Libraries are for compiled code that is optimized for production
  • Version control systems (such as Github) are for the underlying source code.
Example of a library that has it all
npm show vue repository

Remark: things that bit me in the browser

Property names with capitals

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Roy Prins

Roy Prins

A developing full-stack web developer