Home

Welcome to the npdc wiki!

Environment

The npolar JavaScript development environment is running on Node.js with npm (Node package manager) for dependency management, gulp as build tool and browserify as bundler.

Node

Installation can be done via your OS package manager or via https://nodejs.org/

npm

Each moudle is described by a package.json which can be generated by npm init. This file is where the module states it's dependencies. The npm CLI is used to manage dependencies, see https://www.npmjs.com/ for details. Remember to use a local npm folder to avoid having to sudo install all global packages. Add prefix=${HOME}/.npm-packages to ~/.npmrc before install. More node module best practices: https://github.com/mattdesl/module-best-practices

gulp

Gulp is a taskrunner that validates our code, runs tests, bundles, minifies and deploys our applications. All npdc apps use the same gulp configuration located in th npdc-gulp repo. http://gulpjs.com/

Browserify

Browserify is a bundling tool lets us use the Node.js module system in the browser. It basically finds all require(...) statements in your code and concatenates files together to create a single app bundle. http://browserify.org/

JSHint

JSHint is a static code analyzer that help us find errors in code and enforce coding conventions. JSHint is ran in the gulp build process but can also be configured to run on file save in most editors. The configuration for JSHint is located in .jshintrc in npdc-gulp. JSHint will start looking for this file in the same directory as the file that's being linted. If not found, it will move one level up the directory tree all the way up to the filesystem root. So just symlink this file to your home folder and enable jshint in your editor and you should be all set!

Sass

CSS with superpowers (http://sass-lang.com/). Like js it has a linter config in npdc-gulp, symlink it to home or other parent folder of all npdc- projects.

Testing

We use mocha test framework (http://mochajs.org/) with should.js syntax (http://shouldjs.github.io/) for unit testing. Tests live alongside the source code and as long as their filenames end with *Spec.js they are automatically picked up by gulp.

Development workflow

Clone or create a new git repo, all repos need the following files and folders:

• src/
  • app.js
  • index.html
• .gitignore
• package.json
• gulpfile.js

Once you have that you should:

1. npm install to get all dependencies
2. gulp to run the development environment

You can list all available gulp tasks with gulp --tasks and run each one individually. e.g. gulp lint.

Working on app and dependency simultaneously

Say you want to work on angular-npolar together with you app. Easy! npm link sets up symlinks for you.

1. npm link in angular-npolar
2. npm link angular-npolar in your app

Details at https://docs.npmjs.com/cli/link

To revert back to using the dependency declared in package.json use npm unlink followed by npm update.

Release and deploy

Deploy is done with gulp tasks deploy-test or release.

deploy-test

Does just that, builds and deploys to test environment.

release

This task has a bit more going on, it builds, bumps semver version, tags and deploys.

Angular

Our applications are built with Angular.js v1.x https://angularjs.org/ There are some notable design decisions with regard to angular.

The template cache

A Browserify transform bundles all our views in the app bundle and registers them in the $tempalteCahce service (https://docs.angularjs.org/api/ng/service/$templateCache). This is a optimization to avoid having to get views over http.

Dependency injection

Angular has a powerful DI system which we gladly utilize. The DI syntax in angular comes in two flavors, a verbose version and a not so verbose version. Of course we want to use the non verbose version but that is not compatible with minifying the code. The solution is to use the non verbose version + a annotation (still less verbose).

A function with angular DI should look like this:

/**
* @ngInject
*/
var MyController = function ($scope, $controller, MyModel) { ... }

Coding conventions

Apart from the rules set up in JSHint, we follow Dogge: http://javascript.crockford.com/code.html

ES2015

The stack has support for ES2015 via babel. To ensure crossbrowser compatability core.js is bundled with the app.