Node.js

Node.js is a platform built on Chrome's JavaScript runtime for easy building of fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.

Debian packages to install

2018-01-22: please enumerate exactly which Debian packages to install, to get the following commands to work correctly

Packaging modules

On Debian systems up to and including Stretch and Buster (Debian 9 and 10), Node.js modules are located in:

/usr/lib/nodejs/<module_name>

For Debian Bullseye (11), Node.js modules might be located (but this is yet to be decided):

/usr/share/node/<module_name>
/usr/lib/<arch triplet>/node/<module_name>
/usr/lib/node/<module_name>

For more information about packaging a node module for Debian (and the reasons for the change of location for nodejs modules) please take a look at these pages:

debian/watch policy

Some upstream authors don't publish the same versions in Npmjs and Github tags. To be sure to be consistent between node modules, it is recommended to use Npmjs versions. With uscan ≥ 2.18.6 (stable backport at least), you can use searchmode=plain to parse npmjs versions. Example:

version=4
opts="searchmode=plain" \
  https://registry.npmjs.org/aes-js https://registry.npmjs.com/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@

Complex modules

For complex modules, which have many dependencies to be satisfied, you may want to track your work in this wiki in order to keep javascript team updated about.

For more information, please take a look at Tasks page. Take also a look at How to group many modules in one package.

Generated Files

You should remove all generated files from source tarball and generate them during debian package build process using tools in debian. See Javascript/Repacking for steps to exclude generated files and Javascript/Nodejs#Using_build_tools_like_grunt for using different build tools in debian during debian package build process.

Browser vs Node

Javascript was initially used for client side scripting on the browsers. Then nodejs came, which made using javascript on the servers also possible. Most widely used version of javascript today is called ECMA Script 5 or ES5.

Minified javascript

Javascript is usually minified to reduce size. uglifyjs is a tool than can minify javascript. It removes extra space, reduce variable names among other things.

In debian, if we ship a minified js file, we should include the corresponding non minified code also. To guarantee the non minified code is corresponding to the minified code is, to run uglifyjs during build.

Module bundling or browserification or webpacking

Minification is the simplest code transformation we have. There are other transformations too. nodejs supports modules, but it is very inefficient in a browser (http/2 will change this situation which allows parallel requests). Also there are some functionality only present in nodejs but not in browser environment. So using tools like browserify, webpack or rollup, code written for nodejs can be transformed to run on the browser. We need to run this transformation also during build. How To Bring Node.js Modules to the Browser ?

ES6 and transpiling

There is one more type of transformation that is common. They have created a new version of Javascript with new syntax, more functionality built in, it is called ES6 or ES2015. But since browsers and nodejs still don't support es6 fully, we have to convert ES6 to ES5. babel and buble are tools to do that. webpack and rollup has plugins to do ES6 to ES5 transformation.

Using build tools like grunt

Grunt

   1 override_dh_auto_build:
   2         grunt build

Gulp

   1 override_dh_auto_build:
   2         gulp build

Babel

   1 override_dh_auto_build:
   2         babeljs src -d lib

Webpack

Use this as debian/webpack.config.js

   1 'use strict';
   2 
   3 var fs = require('fs');
   4 var path = require('path');
   5 var webpack = require('webpack');
   6 
   7 var config = {
   8 
   9   target: 'web',
  10   resolve: {
  11     modules: ['/usr/lib/nodejs', '.'],
  12   },
  13   resolveLoader: {
  14     modules: ['/usr/lib/nodejs'],
  15   },
  16   node: {
  17     fs: 'empty'
  18   },
  19   output: {
  20     libraryTarget: 'umd'
  21   },
  22   module: { rules: [ { use: [ 'babel-loader' ] } ] }
  23 }
  24 
  25 module.exports = config;

and call webpack from debian/rules

   1 override_dh_auto_build:
   2         webpack --config debian/webpack.config.js lib/Yaml.js dist/Yaml.js --output-library=Yaml

Rollup

   1 override_dh_auto_build:
   2         rollup -c

You will need to use rollup-plugin-commonjs module if you get Unresolved dependencies in rollup output like in the example below

index → build/d3.js...
(!) Unresolved dependencies
https://github.com/rollup/rollup/wiki/Troubleshooting#treating-module-as-external-dependency
d3-array (imported by index.js)

Make sure these are added as build dependencies and you use commonjs plugin like in node-d3-fetch

Browserify

Cake

   1 override_dh_auto_build:
   2         cake.coffeescript build

TODO: make debhelper autodetect grunt, gulp and cake.