Skip to content

Latest commit

 

History

History
61 lines (32 loc) · 2.91 KB

17-015.md

File metadata and controls

61 lines (32 loc) · 2.91 KB
Raw
date
Thu Aug 17 2017 11:15:28 GMT+1000 (AEST)

node app design principles

Some opinions I've formed from past experiences developing / maintaining / deploying node apps. Work-in-progress :)

Minimum viable README

README should contain just enough to get started. All power-user stuff can go in docs/.

Crash early with good descriptions

If there is an env var that the app needs to run, or a database connection, or a setup step was missed, the app should crash immediately and give an informative description of what is missing.

Node on the host, docker for others

There is some appeal to running the entire stack in docker, but I'm not convinced it's an optimal dev environment.

The recommended middle-ground here is:

  • Run all node stuff on the host machine. Use nvm to ensure node / npm version consistency.
  • Other parts of the stack (mysql, redis, elasticsearch, etc) can run in docker

Snapshot tests first

By starting with jest snapshot tests first, we'll get broad coverage with minimal manual effort.

We can consider replacing them with unit tests as solid expectations emerge.

Minimal flowtype

Just enough to run. It's easy to get carried away with putting annotations on everything, and although there is some value in this, it quickly reaches the point of diminishing returns (in our case at least).

Here's a rule-of-thumb process to follow:

  • if you put // @flow at the top of the module, does it pass? If yes, then that's great. We should be able to maintain this.

  • if there are only a few type warnings, let's add the necessary annotations

  • if there are more than just a few type warnings, or other significant complications, remove the // @flow directive. We can revisit this later. And there are probably better ways to refactor rather than adding 50 annotations to the file (eg. refactor some functions into a separate flow-checked module).

Control dependencies

The app should not depend on anything that is outside of its control.

For example, if there's an npm package we need, it must be in the package.json with a restricted version. Don't assume global installs for critical tools.

If the app depends on some other software to run (like a database) it needs to be included in docker-compose config. Even if a dev needs to run the software locally and not in docker for some reason, they can at least ensure they have the correct version.

Avoid unnecessary dependencies

Avoid adding weight to the deps unnecessarily. Something like nodemon is a convenience layer, and is not a foundational part of how we build or test the app. So it should be installed globally, as an opt-in, rather than as a dependency.

Single dir for source code

All source code goes in src.

We are using babel-register in development, but for production we'll run babel as part of a build step. It's easiest to do this if everything is in the one place.