The Node.js Best Practices list curates other articles, and its own counts slip

A curated list, not a framework, and the tree says so

What goldbergyoni/nodebestpractices holds is a document. The top level is a LICENSE, an assets/ directory for the checkbox images, a sections/ directory, a .operations/ folder holding the writing guidelines contributors are pointed at, an .all-contributorsrc file, a package.json, and twelve README files for the different languages. There is no library, no module and no application to build.

The README states the method plainly: the repository is a summary and curation of top-ranked Node.js best practice content, plus material written by collaborators, and more than 80 best practices, style guides and architectural tips are presented. New issues and pull requests are created every day to keep the book current. Most bullets carry a Read More link that expands on the practice with code examples and quotes from selected blogs.

That link-out is the design decision. A numbered list that paraphrases someone else's argument and then sends you to the argument fails differently from a list that states rules on its own authority: when the two disagree, the primary source is the one you can check.

Counts in parentheses disagree with the items listed under them

The table of contents puts a number in the heading of each section, and the numbers are maintained by hand inside a collapsible summary block. Two of the first three disagree with what follows them.

The Error Handling Practices heading reads 2. Error Handling Practices (12), then enumerates 2.1 through 2.13. The Code Style Practices heading reads 3. Code Style Practices (12), and also runs to 3.13, ending with the newly tagged Avoid effects outside of functions. The Project Architecture Practices heading reads (6) and does list six items.

A wrong count here is not fatal, but it is the first number a reader uses. The count is how you decide whether to read a section now or bookmark it, and it is what a script scrapes to report coverage. The related sloppiness sits in the link text: item 2.3 is labelled Distinguish operational vs programmer errors while its href still points at the older wording, #-23-distinguish-catastrophic-errors-from-operational-errors. Somebody reworded the heading and regenerated neither the count nor the anchor. Anyone linking into a section from their own notes should test the fragment first.

Filtering the 2026 edition means browser find on the inline tags

The repository advertises a way to read only what changed. The 2026 edition is described as modernized to 2026, with text edits, new recommended libraries and some new best practices, and the instruction is direct: already visited before, search for the #new or #updated tags for new content only. A third tag, #strategic, marks the items the author considers load bearing, and it appears on practices such as extending the built-in Error object, handling errors centrally rather than in a middleware, exiting the process gracefully, using ESLint, and using async await instead of callbacks.

The limitation is that there is no index. These are inline spans inside one Markdown file, so the filter is a text search in whatever viewer you happen to be using. The repository publishes no GitHub releases, and no item carries its own date, so a bullet marked #updated tells you it changed at some point in the edition cycle, not when. The only dated marker in the project is the July 2026 in the repository description. If you are diffing guidance your team follows, keep your own dated copy; the list will not tell you which of two versions you are looking at.

The tree carries three translations the README does not list

Translation status is tracked in prose, and the prose has fallen behind the files. The README offers seven ready translations: CN, FR, BR, RU, PL, JA and EU. It then adds a parenthetical that ES, HE, KR and TR are in progress.

The repository tree lists twelve README files. Seven match the ready list. The other three are README.hebrew.md, README.korean.md and README.indonesian.md. Two of those, Hebrew and Korean, are the ones the README still calls in progress, so the files are present while the text says the work is unfinished. Indonesian is a different failure: it is in the tree and named nowhere in the README, so a reader who wants it never learns it exists, and a translator for it cannot tell whether someone is already working on it.

The consequence is wasted effort and stale trust, and nothing here fails loudly, because these are hand-maintained Markdown files rather than a generated pipeline. The fix is one line of README text, and the only way to know whether it has been applied is to look at the tree.

package.json declares gen-html.js and ISC, and the repository has neither

The package manifest is where this project is most misleading, because it looks like a published package. It is not. Three fields are wrong in ways that matter:

  "version": "1.0.0",
  "description": "[✔]: assets/images/checkbox-small-blue.png",
  "main": "gen-html.js",
  "license": "ISC"

The description field holds a markdown image reference, the same checkbox graphic that appears at the top of the README. The main field names gen-html.js, and no such file appears at the top level of the repository, so nothing can be required from this package. The version is 1.0.0, which reads as a released artifact when the repository has no releases at all.

The licence field has the longer tail. The repository is published under CC-BY-SA-4.0, a content licence carrying attribution and share-alike terms, while package.json declares ISC, a short permissive software licence. Any tool that reads the manifest gets a different string from the one in the LICENSE file, and nothing in the repository explains which governs a redistribution of the text. That is a discrepancy to raise with the project, not a licensing opinion.

The only command that runs is markdownlint, and it skips sections/

This is the whole tutorial. Get the repository from the address in the package manifest, then run the one script it defines:

git clone https://github.com/goldbergyoni/nodebestpractices.git

markdownlint ./README*.md

There is one dependency, markdownlint-cli at ^0.18.0, and the lint script is that pattern and nothing else. Two consequences follow from the shape of the glob. The star is shallow, so it matches the twelve README files at the root and does not descend into sections/, which is where the practice text lives. And the top level of the repository carries no markdownlint configuration file, so the linter runs on its built-in defaults rather than a rule set anybody chose for this project.

For a contributor that means editing a practice inside sections/ produces no lint signal, while editing a translation produces a signal measured against rules the repository never opted into. Do not treat a clean lint run as evidence that your change is correct.

Practica.js holds the example code, and this repository holds none

The README anticipates the obvious objection, that a list of practices is easy to agree with and hard to apply, and it points at an answer: Practica.js, described as an application example and boilerplate, marked beta, where you can see some practices in action. That is the right move, and it also draws the boundary of this repository precisely.

The practical consequence is that this repository cannot answer a question about behaviour. Ask it how a layered component structure interacts with error handling and it will point you at two numbered bullets written by different people at different times, with no example connecting them. Ask Practica.js and you get code, at the cost of leaving this repository and accepting a beta label.

So the division of labour is: this book tells you what, Practica.js shows you how, and no single place gives you both with a working test. If you are adopting these practices rather than reading them for interest, use the #strategic tag to decide which of the eighty-plus items deserve that effort before you start assembling it.

Editorial conclusion

Read it as a map, not a standard. It earns that role because each bullet links out to the article it summarises, and it marks the advice it considers most consequential with the #strategic tag. Do not treat the counts in the table of contents as a reading plan, because two of the first three sections disagree with their own item numbers, and do not install anything from this repository: the entry point in package.json is absent, the declared licence does not match the LICENSE file, and the example code is in Practica.js. Before citing this list in a team standard, check the date on the practice you are quoting, since the repository publishes no releases and the only marker is the July 2026 edition named in its description.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository