11 Javascript/Node.js Project Survival Tipps

So as a freelance developer I end up in Node.js based projects a lot. Most of these have some base properties in common

  • Modern Javascript mostly using Babel to create a bundle and then run in a browser.
  • “Fat Frameworks” in terms of base package sizes. Most of them contain everything from models to routing to templating.
  • Lots of integration testing. Means you need a complete browser to really test your app.
  • You have access to the world on npm and bower modules
  • Some kind of cli program to scaffold routes, models or start tests.
  • Legacy needs to be supported aka old IE and Safari just because customer wants it

I have done projects in this style with: backbone.js, Marionette.js, Angular 1, Angular 2, all versions of polymer, meteor.js and some I surely fail to remember. So here are some tipps to get you going in a project context.

  1. No shenanigans — If you have not done yet a project with the framework just do not decide on the most fancy of extensions upfront. Do not change the template language, do not exchange the routing, just don’t get fancy. No fancy extra event X and no reactive version of Y. Just don’t. Get the job done first. Use them when you know better. Avoid gulp and grunt if you can, don’t use a shitload of babel plugins
  2. Use small modules or packages — The tight coupling to window or the document makes testing code based on “frameworks” heavy lifting. So if you e.g. create a “car configurator” web application, I suggest to codify the configurator, which is a relative straightforward set of rules, as a independent commonJS node module and re use it via require/npm or another mechanism that is ok to you and the framework. This way the tests around the framework revolve to “is all this working together in a browser context” — minus anything that tests the framework and minus anything the tests the configurator en detail — these things happen in the package/module.
  3. Standardize Modules/Packages — You can use a git template to define the standards for any module. Here you can codify a bit of smart automation that help developers to get started with a “greenfield” project that has everything in place: Automation, Coding Standards etc. TDD these and keep em independent from browser integrations. Its totally ok to replace or re-do code that is already in your framework for this. The packages should have not to many dependencies in the end.
  4. Deploy first — When starting the project, the first task should be a empty hello world application that you deploy to all targets. At some point you only change the production target. But make sure you have everything in place. Now you have to decide when to deploy and in the node.js world, you an use git in combinations with tags and semver to set up a simple mechanic that says “for new semver/tag in git, deploy to target”. Start simple and extend from here. Just write the most simple deploy.
  5. Build 3rd party code as vendor asset — Some 3rd party code comes from npm and gets “babeld”, I suggest to apply different and more lax rules for babel here. Not every piece of code will survive every transpile. You can even create the asset IN the consumed package. So your fat ap just consumes more already compiled js assets. If you fllow this tipp, you have a app.js and a vendor.js in your main app. Do not build vendor.js on every build, just when something there changed.
  6. Re-Use Tests as Post-Deploy Checks — Some parts of the test code, especially this addressing the “frontend app” are a good source for re-use. Tests can get environment variables passed and some frameworks support tags. Combine these 2 and make your devops happy.
  7. A warning is a error — This addresses the app running in the browser, the babel build, tests or even Linting. If you follow “deploy first”, you should have a automation pipeline in place, this must break on any warning. At least in your development browser, this should be a thing that is simple to do. If you spend 3 days fixing warnings in your “Hello World App” review the framework for reasons. Give the “Hello World” a test in the worst browsers in your “browser list” as well. Probably IE, Opera and Safari are candidates. Think of a way to test a base app in as many browsers that you have on a predefined target list. Use Saucelabs or any other provider using full browser automation if you refrain from setting up a test environment yourself.
  8. Client Side Error Logging — At least for development try log errors in clients to a specialized system. This can probably be google analytics but more specialized tools exist. You can couple your apps error logging to these systems easily via the frameworks event handlers in error cases. Make sure you can distinguish test, development, and production stages as well as semver versions of the app itself.
  9. Review and improve results and development workflow — In retrospectives or any other kind of Kaizen process, just make sure you address your tools. Remember, it is a development team and as political as things become, the dev team must always improve and work on the tools that are required to build what we need to build. So talk about it and improve it. Be radical here. if its not shipped yet, you should/must be able to do refactorings of smaller and bigger portions of the code easily. Make sure this is the case or otherwise development will slow down when more features are added. At least try to resemble the same kind of speed you had in “the beginning”. If you don’t: You will pay dearly with bugtickets, overnighters and working weekends. Do not fear updates of frameworks and node.js. Apart from some really major breaks, the new version of frameworks get into focus and old versions tend to get patches, but devs just loose interest. So as long as you have hands on the code and the project is going on: use this way of improvement.
  10. 12 factor app is not only a warm suggestion — I found using the “12 factor app” principles a good guideline to simplify the integration of code and the deploy target. I refrain from checking in stuff into the “app” repo that can be seen as “configuration”.
  11. I18n is a thing — Most frontend apps that I know have a i18n component, just to translate text, but there is more to it. Some hints: Yes you might be working for the german market, but your customer could be on holiday in new York City and trying to use your app. Spare yourself the extra task and at least follow one of the many checklists to see how big this is. Do not blame anything else for the properties of the worldwide web please and do it right.

Other notable mentions

  • Aim Fast test runs — More milliseconds than seconds
  • No HTML Errors — Just because things tend to work better if you follow standards correctly
  • Write docs — There are other developers on the team
  • automate changelogs and releases even more — And help by adhering to a commit message standard