How am I releasing a Javascript Module?

This article explains how I am writing Javascript libraries for the Browser based on my personnal experience.

I tend to think this is the most suited solution in terms of maintenance, readability and scalability for my needs. You are welcome to share your personnal experience by dropping a comment.

Treat your Javascript Module as a Product

When I am writing a Javascript code, I am always treating it as a product in itself. This means, it will have its own repo, its own dev cycle, its own version number, its own issues.

Automatation

It is really important to have automation even in your dev environment, otherwise you could end up with different configuration between your CI environment and your dev workstation. So please, use the exact setup in both otherwise I would give you this:

Picture taken from codinghorror

I personally use Grunt to automate my "build", tests, minifications,... tasks.

Autome your coding style

It is important that any developer in your team use the same formating syntax, it helps readability and maintainability. To avoid this task to become a burden we have enforce it with jsHint and the JsFormat plugin for sublime. When saving the file, it automatically formats the style using our configuration and when "building" the file, jsHint would make sure that the code meets the quality level we have decided. About coding style, I personnaly like idiomatic.js.

commonJS

All the code I am writing use the commonJS style. It has the advantage to let you run your javascript in a node.js environment which will let you share codes between server and client easily. This could be quite important if you are a full-stack dev using node.js.

Split your code into mutiple files/modules

By using commonJS style, it is also very easy for me to spread code into different files and having a structure which make sense. A model folder for my object, a controller folder, a helper folder... At the end all those files are put together with the help of the index.js file (called the main file in npm).

Isolate the DOM

I always try to keep all DOM related tasks in their own files or even module(s) even if I use something like Zepto or jQuery. Multiple reason for that:

  • When reaching the end of the development cycle for my javascript module, I have a look at that DOM layer and see how much I am relying on my DOM library. If I see nothing really complicated there, I just use vanilla Javascript for DOM related work. Here is a small guide who could help you getting rid of jQuery or Zepto: you might not need jQuery.

  • By knowing which part of the code is relying on the DOM, you could extract the rest in another module. As this module won't have any DOM related work, you could easily use it inside a node.js environment.

Build your file

As you know, if you attach a commonJS file in your browser, that won't work very well. In order to make it, I am using a tool called Browserify. It will generate for me a file that can be used by the browser without changing my codes.

Use NPM

Do not be scare to use NPM and publish your code in the registry. Ideally, a javascript module should only be an index.js which points to different NPM modules + some DOM related files if the module needs it. This would enforce code re-use accross your project and ease the testing of each module.

At the end, you will end-up with a framework which would enforce code re-use and consitency for your development team.

Data layer

I always gateher my ajax calls and create Repositories to pull the data. This repository could point to a local storage or to some HTTP endpoints, at the end it won't really matter.

When I am not using a library like Backbone, Angular,... I try to stay away from the jQuery ajax and prefer to use something like superagent. As you would notice, I do not like big libraries which does everything, I prefer to use granular libraries which focus on solving only "one problem" at the time. Superagent also has the advantage to have the exact same API in node.js.

Testing your module

Inside a repository for a Javascript Module, I will always only have unit tests. No smoke tests.

About tooling, I am generally using, mocha as testing framework and should for assertions. I alwo use sinon for spying or mocking the server.

Divide your tests in 2 parts

  • The ones that can be run in node.js.

Why would you need to have a browser open if you don't need it.

  • The ones that need a browser

Obviously, if you write a module for the browser, you will need it at some point.

Open a browser only if you need it

For the browser tests, I use phantomJS in order to prevent me opening a browser each time I need to execute my tests. If you use mocha and grunt (like me), you could even use the mocha-phantomJS to automate the execution.

Let X-Browser tests to your CI

I rarely execute my browser tests using a specific browser. I let the CI doing this. Generally, I would have a selenium task defined which will open each "runner" I have for my browser tests and let selnium doing the testing for me. I would open my browser only in case of problems reported by the CI.

Comments

Tests well written are generally the best source of documention. A nice README.MD is also a good start. If you have none of both, I would start with that.

When done, I would advise your to use the docBlockR format with the help of a plugin and use a tool like YUI doc to automatically generate your API reference.

I only put docBlockR comments on the public method. When I want to mark the developer attention about a comment, I just use an inline comment. Having fewer comments accross the code, let the developer focus on the comments which really matter.

Conclusion

In order to express everything explained in that blog post, I have created a repo that is "ready" to welcome your code.

https://github.com/dervalp/structurejs

Of course, those are my personnal tastes and I would encourage you to adapt it to your needs. And what about you? How do you generally write javascript for the browser?

comments powered by Disqus