handlebars4code/src/readme/browserify.md

library and NPM module that extends Handlebars with Helpers for Code Generation in a specific programming language (e.g. Javascript)

## Quick Start for Developers
The followning description might be helpful if you want to browserify the module in the build. The build process is defined with script `build.js`.

## Build and Compress with Browserify, Watchify, UglifyJS
The NodeJS modules can use `require()`-command. Browsers cannot execute the `require()`-command and other node specific programming features.
* `Browserify` loads the file `___PKG_MAIN___` as input file and resolves e.g. the `require()`-command and creates an output file in `dist/___PKG_NAME___.js`
* `Watchify` observes any changes in the source files in `src/` and starts on the event of changes the build process of the file `___PKG_MAIN___` as input file and creates an output file in `dist/___PKG_NAME___.js`.
* `UglifyJS` compresses the code in `dist` and takes the file `dist/___PKG_NAME___.js` and generates the compressed library in `dist/___PKG_NAME___.min.js`. The same is applied for `docs/js/___PKG_NAME___.js` and the output is `docs/js/___PKG_NAME___.min.js`. The compression of the source code can be perform without a total build by `npm run compress`.
* The main browserify command creates a standalone library that can be used in the browser and it assign `___PKG_EXPORTVAR___` to the `window` object by
```shell
  browserify src/main.js --standalone window > dist/___PKG_NAME___.js
```

### Browserify and Watchify
Browserify and Watchify are used in this repository to control the WebApp-javascript development with the required Javascript libraries installed with [NPM Node.js](https://docs.npmjs.com/getting-started/installing-node) and similar framework world that greatly improve your javascript workflow: Using them, you no longer need to micro-manage your script tags but instead you just declare the libraries each of your client-side modules is using - or you can even create your own reusable modules! Also, installing (or updating) javascript libraries is as easy as running a single command!
* [Additional Information about Browserify and Watchify on GitHub](https://spapas.github.io/2015/05/27/using-browserify-watchify/)
* [Youtube Video about Browserify and Watchify by Kyle Robinson Young 2015/04/16](https://www.youtube.com/watch?v=CTAa8IcQh1U)
In this repository Browserify and Watchify are used for javascript code development with [NPM Node.js](https://docs.npmjs.com/getting-started/installing-node).

### Global Installation of Browserify, Watchify, UglifyJS and DocToc
Requirement: [NPM](https://docs.npmjs.com/getting-started/installing-node) is intalled. Now call for global installation of Browserfy, Watchify, UglifyJS and DocToc by:

`npm install -g browserify watchify uglify-js doctoc jshint lint`

This is recommended because your will not install Browserfy, Watchify and UglifyJS for all your repositories separately.
* ***Browserfy*** converts `node_modules` in a single library, that can be imported in WebApp. Browserify resolves dependencies and included the required libraries into the bundled javascript code.
* ***Watchify*** watches changes in the source code and runs the build process whenever it detects changes in the your source code.
* ***UglifyJS*** compresses the source code of `dist/___PKG_NAME___.js` into ```___PKG_NAME___.min.js``` to reduce download time and WebApp performance during load.
* ***DocToc*** is used to create a helpful table of contents in the README (see [DocToc-Installation]https://github.com/thlorenz/doctoc#installation) for further details on [NPM DocToc](https://www.npmjs.com/package/doctoc) ). Run `doctoc README.md` for updating the table of contents.
* ***jsLint*** is used to check the Javascript code, quality of code can be improved by application of jsLint

### Package Installation of Browserify and Watchify - Alternative
If your prefer that  browserify and watchify is installed with your `npm install` command, save these to modules to your dev-dependecies in your `package.json` by calling

* (Install Browsersify) `npm install browserify -g`
* (Install Watchify) `npm install watchify -g`
* (Install UglifyJS) `npm install uglify-js -g`
* (Install DocToc) `npm install doctoc -g`
* (Install jshint) `npm install jshint -g`
* (Install jshint) `npm install lint -g`

The difference between  `--save` and `--save-dev`, `-g` is, that
* `--save` indicates that the installed library/package is required in the library and the library will be added to `package.json`. If someone else installs you library all packages, that are installed with `--save` are installed recursively as well.
* development dependencies (`--save-dev`) are required  for **building** the code/library only, but not for library itself for being executed. So someone else installs you library, the `--save-dev` developement packages are not installed. If some clones your repository e.g. from GitLab, GitHub,...  with the command  `npm install` also the development packages are installed as well.
* `-g` install packages globally`watchify`, `browserify`, `uglify-js`, ... might be regarded as useful in many other packages, so for developements the installation with `npm install ... --save-dev` is replaced by `-g` option.

because they are required for the development process of the code but they are not added to the generated Javascript-bundle that are used in the WebApp ClassEditorUML. The `--save-dev` commands for `browserify` and `watchify` will install the two modules with all the the dependencies in `node_modules` and add the dev-dependencies to your `package.json`.
```json
"devDependencies": {
  "browserify": "^14.5.0",
  "watchify": "^3.9.0",
  "uglify-js": "^2.6.2",
  "doctoc":"^1.3.0",
  "lint": "^1.1.2"  
}
```
In the current repository `Browserfy` and `Watchify` are expected to be installed globally, because the `package.json` does not contain the dev-dependencies mentioned above.

### Start Watching the Files with Watchify
Watchify will trigger the `npm run build` process if files were change due to alteration of code. To start watching the files, run the npm-watch script by `npm run watch`, which is defined in `package.json`

### Source JS file and development bundle output
The main JS source file for the build process is `src/main.js`. The output library (resp. output file of build process) is stored in distrubtion library for browser based web-development in `dist/___PKG_NAME___.js`. Compressed code is generated with `UglifyJS`. It takes the `dist/___PKG_NAME___.js` as input file and creates the compressed file `dist/___PKG_NAME___.min.js`.
The compression of `dist/___PKG_NAME___.js` into `dist/___PKG_NAME___.min.js` uses `uglify-js` module and can be started by

  `npm run compress`