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:
- Part 1: Overview of the Node.js reference architecture
- Part 2: Loggin
- Part 3: Code consistency
- Part 4: GraphQL
- Part 5: Building good containers
- Part 6: Choosing web frameworks
- Part 7: Code coverage
- Part 8: Typescript
- Part 9: Securing Node.js applications
- Part 10: Accessibility
- Part 11: Typical development workflows
- Part 12: npm development
- Part 13: Problem determination
- Part 14: Testing
- Part 15: Transaction handling
- Part 16: Load balancing, threading, and scaling
- Part 17: CI/CD best practices in Node.js
- Part 18: Wrapping up
Why code consistency matters
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.
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
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:
"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.
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.