[How2Tips] How to create and publish an open source javascript library

David is one of the most experienced KNP devs. Since 2013 he is Lead Dev, trainer and speaker here at KNP Labs. After a PhP period, he switched to JS, his Dada, his troll, his passion... He also published some nice FOSS contributions... for example a little lib that will help you to boost your react app. In the following article he will explain how to publish an open source JS library.

Before starting : You must have `npm` or `yarn` installed on your environment with a working version of  `nodejs` of course.

The package.json

First thing first, if you want to publish an open source library, everything you have to do is to generate and edit the `package.json` file : Let's take an example with an imaginary `champion` lib :

# We create the directory of our lib :
$ mkdir champion
# We generate a new package.json inside this lib :
$ cd champion
$ npm init

Npm will ask some questions about your project, answer it now or later, it does not matter. Now you should have something like this inside your package.json :

json
{
// This is the name of you library
"name": "champion",
// This is the version (you should increment it before each publication)
"version": "1.0.0",
// A short but intense description of your projet
"description": "",
// This is your library entry point. When someone will install
// your lib and require it with `require('champion')` or
// import * as Champion from 'champion' this is the file
// that will be served ! !CAREFULL! IT MUST BE WRITTEN
// IN ES5 (no arrow functions, import / export, etc ...)
"main": "index.js",
// This is some usefull script. We will see some usage later
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
// The author (you can put your name / surname / email)
"author": "",
// This is the livence of your library
"license": "ISC"
}

Publishing your lib

In the folder of your library :

# Login to the npm registry (if you don't don't have an ccount it's not a big deal
# a new one will be created automatically )
$ npm login
# Then publish your lib :
$ npm publish

That's it !

Testing your lib locally

You can `link` locally your lib :

# This command will build and put your lib inside your $HOME/.node_modules
$ npm link

Then in any other local projects :

# We have linked it before. Npm will first take a look inside
# your $HOME/.node_modules before trying to fetch the library from
# the internet. If the version are exactly the same then it will
# use the local library and install it like any other library.
$ npm install champion

Coding in ES6

You can install `webpack`, `browserify` or any bundle tools in development and code your projet in `ES6`. Be sure to compile all your `src/` folder inside a `build/` or `dist/` or anything else. Then you have the ability to hook the publishing process :

# Adding a bundle tool only in dev :
$ npm install --dev webpack
# Or with yarn :
$ yarn add --dev webpack

And now we can setup a build script :

json
{
"name": "champion",
"version": "1.0.0",
"description": "",
// Change this main to point to the compiled directory index :
"main": "build/index.js",
"scripts": {
// This script will be launched on your machine just
// before `npm publish`. All the created files, directories
// during this script will be send to the npm registry
// allowing your `build/index.js` to be present and ready
// to rock.
"prepublish": "webpack src dist"
},
"author": "",
"license": "ISC",
// Of course your dev dependencies :
"devDependencies": {
"webpack": "^4.35.0"
}
}

There is plenty more scripts which you may find useful in the official documentation

Publishing Types

If you want your library to be popular and maintainable it's always a good argument to add some `typing`. The most popular typing tool today is `typescript`.

You can create a `champion.d.ts` file anywhere you want and put your library types in there (or directly code with typescript). Then you just have to specify where your types are in your `package.json` :

// Using the types key
"types": "path/to/champion.d.ts"
// or the typings key (both are working) :
"typings": "path/to/champion.d.ts"

Writing `.d.ts` definition file is not that hard :)

Ignoring files to publish

If you have installed your lib inside some projet and you noticed that you have published all your tests with your lib (wich is rarely a good idea) then the `.npmignore` file in the root folder of your lib is probably missing  :

// .npmignore
tests/

The previous lines will remove any references to `tests/` in the published package (it's working the same way as a `.gitignore` file).

Curious to go further or work with us ? => hello@knplabs.com