Hello guys, Today I will write a tutorial how to create a professional library and make your library published in NPM Package. I know there is a lot similar tutorial like this, but I will make this tutorial more systematic and more explanation to help you understand more easier.

Study Case

In this tutorial, Assume that you are will be create a library name text-obfuscator. text-obfuscator is just a simple library to obfuscate the text.

Pre Software Requirement

  1. Visual Studio Code
  2. Git

Install Visual Studio Code

We will going to use Visual Studio Code, but actualy you are able to use any IDE to code. I use Visual Studio Code because this is the top popular editor in the world. Visual Studio Code is Free, you can download it from here and follow the step to install it.

Install Git

Git is the version control software to help you manage your repository of your project in Github. Git is an open source project so you are free to download it from here and follow the step from it website to install it.

Pre Account Requirement

Before we start to create a library. You have to register on 4 resources, it is:

  1. Github
  2. Travis
  3. Coveralls
  4. NPMJS

Create an account to Github

Visit to Github and register your account in there. After you are finished to register, then you have to create your first repository. For example if your username is aalfiann, then if your repository name is text-obfuscator so your full link to your repository is https://github.com/aalfiann/text-obfuscator.

Clone your Repository

To clone your repository, you just go visit to https://github.com/aalfiann/text-obfuscator then on the top-right there is green button name Clone or Download, just click on it then copy the url from textbox, so your git link is https://github.com/aalfiann/text-obfuscator.git.

After you have the git link, now open your Visual Studio Code, then press CTRL+SHIFT+P, paste the git link, wait for a second then you will get popup message to Open this Repository, just click it. Now you will open the project which is has been already connected with your repository on Github.

Now just minimize your Visual Studio Code and go for the next step below.

Create an account to Travis

Visit to Travis then make a registration first in there. After register is done, now go to Settings. Then on top-left you will see the green button name Sync Account, just click it. Wait for a second, after sync progress is done, now you will see your repository name is appearing on the right box. Okay, that is enough for now, we will continue this later to trigger the build test after the source code is uploaded on github.

Create an account to Coveralls

Visit to Coveralls then make a registration first in there. After register is done, now go to Add New Repo. Then on top-right you will see button name Sync Repo, just click on it. Wait for a second, then your repository name will be appear in there. You will see gray button OFF, then click it to make coveralls listen to your repository in realtime to detect whats changes from your repository in Github.

Create an account to NPMJS

Visit to NPMJS to create your account. You have to register to NPM website because this is required to publish your package library in NPM. After you are successfully register, just leave it, you can logout because later we will login to NPM through command from Terminal.

Making a library

After you follow all the steps above, now we go back to open your minimized Visual Studio Code. You will see that your project is still empty. So follow the next step below to making your first library.

NPM Init

The first thing to do is you have to open the terminal from Visual Studio Code, then run command below

1
$ npm init

Then follow all the steps, for the test part just enter it, so you have no script test as for now. We will configure it later in the next step.

Configure Unit Test

I have write the full article about create unit test at here. Just follow all steps from it. Once it done, you can go for next step below.

Create structure library

Structure can be anything, but for a standard which is many people use is like this:

  • src/
  • test/
  • .gitignore
  • .travis.yml
  • LICENSE
  • package-lock.json
  • package.json
  • README.md

Note:

  • src/ directory is your source code library.
  • test/ directory is your unit test file.

Create the source code

Now create new file name text-obfuscator.js inside src/ directory.
Just paste this code and saved it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
/*!
* TextObfuscator v1.0.2 ES6 [NodeJS or Browser]
* https://github.com/aalfiann/text-obfuscator
*
* Copyright 2019 M ABD AZIZ ALFIAN
* Released under the MIT license
* https://github.com/aalfiann/text-obfuscator/blob/master/LICENSE
*/
"use strict";
var TextObfuscator = {

/**
* Determine value is string
* @param {string} value
* @return {bool}
*/
_isString: function (value) {
return typeof value === 'string' || value instanceof String;
},

/**
* Make chunk array (start from first char)
* @param {string} value this is the text value
* @param {string|integer} size this is the size of chunked text value
* @return {array}
*/
_make: function(value,size=1) {
size = parseInt(size);
var i = 0, o = 0, numChunks = Math.ceil(value.length / size), chunks = new Array(numChunks);
for(i, o; i < numChunks; ++i, o += size) {
chunks[i] = value.substr(o, size);
}
return chunks;
},

/**
* Make chunk array reverse (start from last char)
* @param {string} value this is the text value
* @param {string|integer} size this is the size of chunked text value
* @return {array}
*/
_remake: function(value,size=1) {
size = parseInt(size);
var i = 0, len = value.length, data = this._make(value,size), datalen = data.length, chunks = new Array(datalen), last = data[datalen-1].length;
for (;i<datalen;i++) {
if(len>=size) {
chunks[i] = value.substr((len-size),size);
len -= size;
} else {
chunks[i] = value.substr(0,last);
}
}
return chunks;
},

/**
* Encode or Obfuscate the text
* @param {string} value this is the text value to be encoded
* @param {string|integer} size this is the size of text to obfuscate
* @return {string}
*/
encode: function(value,size=1) {
var result = '';
size = parseInt(size);
if(!this._isString(value)) throw new Error('Value must be string');
var data = this._make(value,size), len = data.length;
while(len) {
--len;
result += data[len];
}
return result;
},

/**
* Decode or deobfuscate the text
* @param {string} value this is the encoded text
* @param {string|integer} size this is the size of text to deobfuscate
* @return {string}
*/
decode: function(value,size=1) {
var result = '';
size = parseInt(size);
if(!this._isString(value)) throw new Error('Value must be string');
var data = this._remake(value,size), i = 0, len = data.length;
for(;i<len;i++) {
result += data[i];
}
return result;
}

};

if (typeof window === "undefined") {
module.exports = TextObfuscator;
}

Now you have already the source code of your library.

Create unit test file

Now create a file name obfuscator.js in test/ directory.
Just paste with this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
const assert = require('assert');
const TextObfuscator = require('../src/text-obfuscator');

describe('obfuscator test', function() {

it('value must be string', function() {
assert.throws(function(){
TextObfuscator.encode([]);
},Error);
});

it('isString helper', function() {
assert.equal(TextObfuscator._isString('abc'),true);
assert.equal(TextObfuscator._isString(1),false);
assert.equal(TextObfuscator._isString([]),false);
assert.equal(TextObfuscator._isString({}),false);
assert.equal(TextObfuscator._isString(true),false);
assert.equal(TextObfuscator._isString(false),false);
assert.equal(TextObfuscator._isString(null),false);
assert.equal(TextObfuscator._isString(undefined),false);
});

it('make chunk array', function() {
assert.deepEqual(TextObfuscator._make('abcdefghijklmnopqrstuvwxyz',3),
[ 'abc', 'def', 'ghi', 'jkl', 'mno', 'pqr', 'stu', 'vwx', 'yz' ]);
});

it('remake reversed chunk array', function() {
assert.deepEqual(TextObfuscator._remake('abcdefghijklmnopqrstuvwxyz',3),
[ 'xyz', 'uvw', 'rst', 'opq', 'lmn', 'ijk', 'fgh', 'cde', 'ab' ]);
});

it('make chunk array like simple reverse', function() {
assert.deepEqual(TextObfuscator._make('abcdefghijklmnopqrstuvwxyz'),
[ 'a','b','c', 'd','e','f', 'g','h','i', 'j','k','l', 'm','n','o', 'p','q','r', 's','t','u', 'v','w','x', 'y','z' ]);
});

it('remake reversed chunk array like simple reverse', function() {
assert.deepEqual(TextObfuscator._remake('abcdefghijklmnopqrstuvwxyz'),
[ 'z','y','x', 'w','v','u', 't','s','r', 'q','p','o', 'n','m','l', 'k','j','i', 'h','g','f', 'e','d','c', 'b','a' ]);
});

it('obfuscate the text', function() {
assert.equal(TextObfuscator.encode('abcdefghijklmnopqrstuvwxyz',2),'yzwxuvstqropmnklijghefcdab');
});

it('deobfuscate text', function() {
assert.equal(TextObfuscator.decode('yzwxuvstqropmnklijghefcdab',2),'abcdefghijklmnopqrstuvwxyz');
});

it('obfuscate only works with string', function() {
assert.throws(function(){
TextObfuscator.encode(['12345']);
},Error);
});

it('deobfuscate only works with string', function() {
assert.throws(function(){
TextObfuscator.decode(['54321']);
},Error);
});

});

Now assume that you already have the unit test file.

Make run your unit test

To run your unit test, just run this command into terminal.

1
npm test

Now you will get the result like this.

You will see that there uncovered line with yellow color, it means that you have test it line but it was still for one condition, there is still another conditions which is are not tested yet. Unfortunately it can not be tested because it must be tested on browser. Ah I forgot to tell you that the text-obfuscator is could be run in NodeJS or Browser. Because on the last line there is condition for window which is it must be tested on browser, so that is why unit test is missed for one line.

Create README.md

README is the file that you should give the information detail about the project. For this example you can just paste with this below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# text-obfuscator
[![NPM](https://nodei.co/npm/text-obfuscator.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/text-obfuscator/)

[![npm version](https://img.shields.io/npm/v/text-obfuscator.svg?style=flat-square)](https://www.npmjs.org/package/text-obfuscator)
[![Build Status](https://travis-ci.org/aalfiann/text-obfuscator.svg?branch=master)](https://travis-ci.org/aalfiann/text-obfuscator)
[![Coverage Status](https://coveralls.io/repos/github/aalfiann/text-obfuscator/badge.svg?branch=master)](https://coveralls.io/github/aalfiann/text-obfuscator?branch=master)
[![Known Vulnerabilities](https://snyk.io//test/github/aalfiann/text-obfuscator/badge.svg?targetFile=package.json)](https://snyk.io//test/github/aalfiann/text-obfuscator?targetFile=package.json)
[![dependencies Status](https://david-dm.org/aalfiann/text-obfuscator/status.svg)](https://david-dm.org/aalfiann/text-obfuscator)
![License](https://img.shields.io/npm/l/text-obfuscator)
![NPM download/month](https://img.shields.io/npm/dm/text-obfuscator.svg)
![NPM download total](https://img.shields.io/npm/dt/text-obfuscator.svg)
Simple Text Obfuscator for NodeJS or Browser.

Because sometimes we want to obfuscate a text in client browser for `key`, `id`, `base64`, etc.

Note:

  • You can see that you could put the badge into README.md file.

Push into github

After everything is done, now you can go push your source code into Github by this command.

1
2
3
git add .
git commit -m "first commit"
git push -u origin master

Trigger Build in Travis

After your source code is successfully uploaded into github, now go visit to Travis-Settings. Then click on your repository name, then on the top-right there is button name More options just click on it. Then the dropdown will apearing and there is Trigger build menu, so just click on it.

Now the build test will be running for a minute, just wait for it. Once it done, you can go for the next step below.

Publish into NPM Package

When build is passed, you can just publish it into NPM Package by this command.

1
2
$ npm login
$ npm publish

Yeah that is done, now your package you can view it on https://www.npmjs.com/package/text-obfuscator.

Conclusion

Sorry there is no much image for the step, because trust me the register for an account is very simple even for a newbie.

Also the study case is a real library which was created for professional use. Actually I was use this text-obfuscator library for many important projects.

For more detail you can check the source code is available on https://github.com/aalfiann/text-obfuscator.

Hope you are able to create your own library and publish it on your NPM Package. Feel free to ask if you are have problem or miss understanding about this tutorial.

Thank You.