node package manager
Easy collaboration. Discover, share, and reuse code in your team. Create a free org »

zip-client-side-js

Client side UI modules

  • Packaged via browserify
  • Watched via Grunt

Development

Grunt processes now run local javascript concatenation, minification, sass compilation as well as our custom module browserification.

Grunt prerequisites:

  • Install latest node.js from nodejs.org
  • Install grunt globally (probably requiring sudo). More information on grunt is at gruntjs.com. Run the following commands from the src directory containing the Gruntfile.js and the main package.json:
npm install -g grunt-cli

Then install all the packages we use for development. Our client side packages are in the zaplabs directory and are published to npm as private modules under our organization zaplabs, so they are all downloaded and installed under the zaplabs namespace. These are all listed as production dependencies since their version is shrinkwrapped.

npm install

npm private packages

We publish our modules to npm as private packages, front end devs should each have an account so they can see the modules here https://www.npmjs.com/org/zaplabs

You need to login to npm on the command line to install and publish our private packages:

npm login

Updating a module

Our bundle files are created by our grunt tasks, the main file is global.js, the source file for it is in ui-module-bundles/global.js. That is just a list of requires. Our local module source code is in zaplabs/, we modify the source and publish it to npm.

When in a module directory like: src/main/webapp/WEB-INF/zaplabs/autocomplete after you have modified the module source and are ready to publish:

npm version patch

Will bump the version number of your module

npm publish

Will push the latest version of your module to npm.

If you are just testing module changes you can directly modify the installed version in nodejs/node_modules and repackage your changes with grunt to locally test your updates but you need to copy these changes over to the git tracked source module files outside of node_modules to save the changes.

After the lastest version of your module is published to npm install the latest version of your module while updating shrinkwrap as described below:

Managing dependencies with shrinkwrap

We use npm shrinkwrap to keep track of a locked own list of specific versions of each package so we can reliably recreate the exact code we released at any time. Using this package influences what happens when you run npm install, it will install the exact version of every package specified in the npm-shrinkwrap.json. Each time you update the package.json by deliberately updating a package the shrinkwrap file will also be automatically updated.

If you have not updated a module since we started using shrinkwrap run the shrinkwrap command once so your system knows

It is helpful to do a manual check each time you want to generate files:

npm outdated

That will tell you if any of the modules we depend on need to be updated. The main thing to be concerned about are our private packages unde @zaplabs. If any of these are out of date you should update it and save the update to change our package.json before regenerating any of the client side concatenated files we distribute.

Since the npm-shrinkwrap.json file exists the default behavior of npm install is modified to respect the versions in the shrinkwrap file so if you want to deliberately update a package you should modify it with the save argument like:

npm update --save

Which will automatically update the shrinkwrap file, doing the update command without save will not update shrinkwrap successful output will be:

wrote npm-shrinkwrap.json
zip-client-side-js@1.0.0 /Users/ahans/dev/longisland/src/main/webapp/WEB-INF/nodejs
└── @zaplabs/autocomplete@1.0.15

You can also deliberately install specific version of a package if you wanted to to major version update, also use the save command here to make sure shrinkwrap gets the change:

npm install @zaplabs/autocomplete@1.0.14 --save

Shrink Wrap not working as advertised?

Usually performing installs and updates will have shrinkwrap automatically update with no problems but we noticed that when you perform an install or update command and it gives you an error message, even something usually innocuous like telling you that you have unnecessary modules present will make the automatic shrinkwrap process fail, then reinstalling that specific module will not update shrinkwrap either.

The solution to this is to completely uninstall the module that you were trying to update using the save argument, then reinstall it using save, this will restore shrinkwrap to a normal state.

Testing

Using tape with faucet to get colors on TAP output. So you'll need to install the faucet package globally to receive the piped test output:

sudo npm install -g faucet

Then you can run the test scripts with

npm test

You can write a unit test and package it with your module. An example module with a unit tests using Tape is zaplabs/expandable-drawers/test/

Additional information

In order to make use of the source maps modify your local tomcat configuration to tell it to serve files with the .map extension

Add the following mime mapping to conf/web.xml in your tomcat install directory:

<mime-mapping>
  <extension>map</extension>
  <mime-type>application/javascript</mime-type>
</mime-mapping>

Wiki pages with more information on our client side code development: