simple-node-package
Simple Node.js package used for a tutorial : Starting with NPM
Starting with NPM
Let's create our first Node.js module
NPM is the package manager of Node.js and all packages are stored in a public registry :
https://registry.npmjs.org
.
But to find one, use the website https://npmjs.org/.
NodeJs introduced this manager since version 0.6.3.
It manage dependencies and other configurations trough a package.json
file.
Today, there is a least 560K+ packages : that's a lot!
You also can store packages in private NPM registry : useful inside enterprises.
pre-requisites
In order to use NPM, we need to install Node.js if not already done.
You can sudo apt-get install nodejs nodejs-dev nodejs-legacy
on Ubuntu,
or download Node.js.
search in the registry
You may want a package to do some stuff : look first in the registry, someone probably worked on that. Go to find a package on https://npmjs.org/
If not, find a name for your package and check if it is already taken :
$ npm view my-package
npm ERR! 404 Registry returned 404 for GET on http://registry.npmjs.org/
If npm displays a 404 error, the package does not exists, you can create it.
create your repository
Before creating the package, start to create a repository on github or other repository manager. Then, clone it in your working directory :
$ mkdir my-first-npm-package
$ cd my-first-npm-package
$ git clone git@github.com:USER/my-first-npm-package.git
First script with node
You can execute a javascript file using node like this :
$ node index.js
simple-node-package started
where index.js
contains :
console.log('simple-node-package started');
As we can see, the message simple-node-package started
is logged.
So, use this way to create a script that do something right now.
Imagine :
$ node display-the-date.js
2017-09-27T14:21:01.755Z
where display-the-date.js
contains :
console.log(new Date());
Now execute the script using the Node.js REPL.
Its a Javascript prompt called REPL for Read Eval Print Loop.
It works in a way like your browser javascript console does but with node features.
The most important thing to know is the import of your module with require('./file.js')
.
It loads your javascript file.
Just do :
$ node
> var module = require('./index.js');
simple-node-package started
undefined
The same log message is displayed. Use CTRL+C twice to exit REPL (exit before try again if you change your script).
Be careful :
require
is a function that will load synchronously the indicated module.
Once the first load is done, it will cache the script, so if we load it a second time, it is not re-loaded :
> var module = require('./index.js');
simple-node-package started
undefined
> var module = require('./index.js');
undefined
Depending your code, you may have some side effects if you code wrong.
Exporting some stuff
Now there is a magic keyword with node : module.exports
or exports
.
It permit to exports whatever you want, like literal, object, function, ...
Try with index.js
:
module.exports = 'myExport';
And import it:
$ node
> var module = require('./index.js');
simple-node-package started
undefined
> module
'myExport'
Here module
equals 'myExport'
string.
Now imagine exporting a function :
module.exports = function(moduleArgument) {
console.log('moduleArgument is', moduleArgument);
return 'moduleResult';
};
And try it :
$ node
> var module = require('./index.js');
simple-node-package started
undefined
> module
[Function]
We can see that module
is a (our) function and if we execute it with an argument 'moduleParameter'
:
> module('moduleParameter')
moduleArgument is moduleParameter
'moduleResult'
There is a log message that indicates our first argument and the returned value 'moduleResult'
More useful script
Now we will export something more useful : a module with some utility functions, an addition and multiplication functions.
We start with our index.js
file :
module.exports = function (coefficient) {
// no coefficient means coefficient of 1
if (!coefficient && coefficient !== 0) {
coefficient = 1;
}
console.log('moduleArgument coefficient is', coefficient);
this.coefficient = coefficient;
return {
addition: addition.bind(this),
multiplication: multiplication.bind(this)
}
};
function addition(x, y) {
return this.coefficient * (x + y);
}
function multiplication(x, y) {
return this.coefficient * x * y;
}
Here the function used for the module return an object of functions :
{
addition: addition.bind(this),
multiplication: multiplication.bind(this)
}
So when after importing our module with the coefficient
parameter,
you can call addition
or multiplication
functions.
Let's try to use it :
> var module = require('./index.js');
simple-node-package started
undefined
>
> module().addition(1,1)
moduleArgument coefficient is 1
2
> module(2).addition(1,1)
moduleArgument coefficient is 2
4
> var coef4 = module(4)
moduleArgument coefficient is 4
undefined
> coef4.multiplication(2,2)
16
Finally, our module parameter coefficient
is useful for our entire module
and we benefit of these two functions you can use elsewhere, even in another NPM module.
create a package
We are now ready to create the package with npm init
. Don't forget to add a README.md
:
it will appears on the NPM registry to describe the package.
It will ask a couple of questions as the package name, version, description, author, keywords and repository :
$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.
See `npm help json` for definitive documentation on these fields
and exactly what they do.
Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.
Press ^C at any time to quit.
name: (simple-node-package) simple-node-package
version: (1.0.0) 0.0.0
description: simple node module with an addition and a multiplication methods
entry point: (index.js)
test command:
git repository: (https://github.com/kirakishin/simple-node-package.git)
keywords: addition, multiplication
author: **@**
license: (ISC) MIT
About to write to C:\git\github\kirakishin\simple-node-package\package.json:
{
"name": "simple-node-package",
"version": "0.0.0",
"description": "simple node module with an addition and a multiplication methods",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "git+https://github.com/kirakishin/simple-node-package.git"
},
"keywords": [
"addition",
"multiplication"
],
"author": "**@**",
"license": "MIT",
"bugs": {
"url": "https://github.com/kirakishin/simple-node-package/issues"
},
"homepage": "https://github.com/kirakishin/simple-node-package#readme"
}
Is this ok? (yes) yes
Once finished, the package.json
file is created.
You can edit it by changing the name or adding some tests.
Now take our previous script display-the-date.js
:
$ node display-the-date.js
2017-09-27T14:21:01.755Z
So, you can execute it through a NPM script by adding a start
script in package.json
:
{
[...]
"scripts": {
"start": "node display-the-date.js"
},
[...]
}
And try :
$ npm start
> simple-node-package@0.0.0 start /home/kirakishin/simple-node-package
> node display-the-date.js
2017-09-27T14:21:01.755Z
publish your package
If you never used the NPM public registry, you must add your account :
$ npm adduser <USER>
Now add new files and commit it :
$ git add index.js package.json README.md display-the-date.js
$ git commit -a -m "chore(init): first init"
$ npm version minor
$ git push && git push --tags
Then publish your package on the registry :
npm publish
that's all !
Few words
In an open source World, check first if anyone already done the thing you want. If not, do it and share!
We saw how to create a node module, use it, and publish it:
- NPM is a package manager and comes with Node.js
-
https://npmjs.org/
is the NPM website to find packages in the NPM registry -
http://registry.npmjs.org/
is the NPM registry where packages are stored - you also can use a private NPM registry inside your organization
- start a node script with
node script.js
- exports things from your module with
module.exports = 'exportedThing'
- use REPL from node to send commands like
console.log('hello')
- use
var module = require('./index.js')
to import the module fromindex.js
- then use it with
var ask = module(42); var response = ask.bigQuestion('all')
- and see the answer to everything in the universe
On github : https://github.com/kirakishin/simple-node-package
Package on NPM : https://www.npmjs.com/package/simple-node-package
Medium : https://medium.com/p/68f9db195865