Introduction to the Node.js reference architecture, Part 3: Code consistency

 

May 17, 2021
Lucas Holmquist
Related topics:
Node.jsOpen source
Related products:
Red Hat build of Node.js

Welcome back to our ongoing series about the Node.js reference architecture. Part 1 introduced what the Node.js reference architecture is all about, and Part 2 took a look at logging. In this article, we will dive into code consistency and how to enforce it with a linter tool like ESLint.

Read the series so far:

Why code consistency matters

One critical aspect of working on JavaScript projects effectively as a team is having consistency in the formatting of your code. This ensures that when different team members collaborate on the shared codebase, they know what coding patterns to expect, allowing them to work more efficiently. A lack of consistency increases the learning curve for developers and can potentially detract from the main project goal.

When the Node.js teams at Red Hat and IBM started the discussion on code consistency, it quickly became apparent that this is an area where people have strong opinions, and one size does not fit all. It's amazing how much time you can spend talking about the right place for a bracket!

The one thing we could agree on, though, is the importance of using a consistent style within a project and enforcing it through automation.

ESLint

In surveying the tools used across Red Hat and IBM to check and enforce code consistency, ESLint quickly surfaced as the most popular choice. This configurable linter tool analyzes code to identify JavaScript patterns and maintain quality.

While we found that different teams used different code styles, many of them reported that they used ESLint to get the job done. ESLint is an open source project hosted by the OpenJS Foundation, confirming it as a solid choice with open governance. We know we'll always have the opportunity to contribute fixes and get involved with the project.

ESLint comes with many pre-existing code style configurations that you can easily add to your projects. Using one of these shareable configurations has many benefits. By using an existing config, you can avoid "reinventing the wheel"; someone else has probably already created the configuration you are looking for. Another advantage is that new team members (or open source contributors) might already be familiar with the config you are using, enabling them to get up to speed more quickly.

Here are a few common configurations to help you get started:

A complete list can be found on npmjs.org using this query.

Note we do not recommend any particular code style or ESLint config. It's more important that you choose one standard and that you apply it consistently across your organization. If that is not possible, then you should at least make sure it's used consistently across related projects.

At this point, I must admit we did not really spend that much time talking about where the brackets should go. But that is one of the reasons we suggest looking at one of the existing configs: Adopting existing best practices saves a lot of time (and arguments) so you can spend that time coding instead.

Adding ESLint to your Node.js project

Based on the advice in the reference architecture, the Red Hat Node.js team recently updated the NodeShift project to use ESLint.

Adding ESLint to your project is a pretty straightforward process. In fact, ESLint has a wizard that you can run on the command line interface to get you started. You can run:

$ npx eslint --init

and then follow the prompts. This post won’t go into the specifics of the init wizard, but you can find more information in the ESLint documentation.

Our team likes using semi-colons, so we decided to use the semistandard config. It was easy to install by running the following command:

$ npx install-peerdeps --dev eslint-config-semistandard

Then, in our .eslintrc.json file, we made sure to extend semistandard:

{
  "extends": "semistandard",
  "rules": {
    "prefer-const": "error",
    "block-scoped-var": "error",
    "prefer-template": "warn",
    "no-unneeded-ternary": "warn",
    "no-use-before-define": [
      "error",
      "nofunc"
    ]
  }
}

You will notice that we have some custom rules set up as well. If you have custom rules for your project, this is where you should put them.

Automating the code linter

Having a linter in place is great, but it is only effective if you run it. While you can run the eslint command manually to check your code consistency, remembering to run it that way can become burdensome and error-prone. The best approach is to set up some type of automation.

The first step is to create an npm script like pretest that will make sure linting happens before your tests are run. That script might look something like this:

  "scripts": {
      "pretest": "eslint --ignore-path .gitignore ."
  }

Notice that we are telling ESLint to ignore paths that are contained in our .gitignore file, so make sure the node_modules folder and other derived files are included in that ignore file. Using an npm script like this easily integrates into most continuous integration (CI) platforms.

Another alternative is to configure hooks so that the linter runs before the code is committed. Libraries like Husky can help with this workflow. Just be sure that these precommit checks don't take too long, or your developers might complain.

Conclusion

It is critical to make sure you enforce consistent code standards across all your projects so that your team can collaborate efficiently. The best way to keep up with that task is to use a linter and automate it as part of your workflow. We recommend ESLint, but you are free to choose whatever tool you want—as long as you have something.

The next installment in this series on the Node.js reference architecture looks at GraphQL in the Node.js ecosystem.

Visit the GitHub project to explore sections that might be covered in future articles. If you want to learn more about what Red Hat is up to on the Node.js front, check out our Node.js landing page.

Last updated: February 11, 2024