goldbergyoni / nodebestpractices Goto Github PK

A few things that come up on projects I have in multiple languages are listed above, but more on them below:

1. Refactoring: I honestly hardly see any of this in the "newer" languages, but there are several books on Java refactoring as well as some on PHP and Python. Here is a good list: https://refactoring.guru. This could fit well in the Code Quality section. There are also good tools like: https://codeclimate.com/ to be used.

2. A few architectures of the top of my head are MV* and Clean/Hex Architecture. Plus adding links to functional and OOP paradigms for NodeJS would be helpful for users to see when and why to use certain choices. The Project Structure section is great, but there is still more to add on as you get larger.

3. Slightly out of scope, but if you are developing Nodejs, you probably have a few APIs which could use could System Design: https://github.com/donnemartin/system-design-primer

I'd be happy to PR if any of these are of interest.

Wanted to add this resource and the name:

https://8thlight.com/blog/uncle-bob/2011/09/30/Screaming-Architecture.html

I'd like to work on the security best practices section. Apart from independent modules/npm solutions already stated in the main README what do you think would be further important aspects? I think of adding important tips for the crypto core module first.

First of all, thanks for compiling this list. However, it's not clear quite who you are targeting since much of this advice is specific to some situation.

Take for instance 1.1 Structure your solution by components. That makes sense for large enterprise codebases, or codebases with a lot of components that are heavily re-used, but there are also a lot of codebases where that makes no sense (a todo app, a calculator app, a multiplayer game server, etc)

Likewise, the guide gives heavy advice that is Express specific. Express is a great framework for a lot of cases, but probably not larger Enterprise ones.

It's important to understand that all programming practices have their time and place, and are effectively tradeoffs. Typescript adds in sane consistent types for large codebases, but brings with it severe complexity in small ones. Functional Programming is great for functional problems, but probably isn't a good choice for building an RPG engine in.

This guide seems to miss this point. Instead of saying "If your situation is this, then a good solution is that", it simply says "Always use Express, a component layout, etc".

Since commit messages are an important part of coding practice, I think it would be useful to include that too.

I go by these rules

https://github.com/i0natan/nodebestpractices/tree/chinese-translation

@mattjin - Chinese translation can be officially kicked-off. You're the lead! I'll be at your disposal should you need anything. A branch was created (link below), you should have permissions to it, everyone else must PR before changing anything there.

I would ask/recommend only 2 important guidelines:

1. Keep the same content & formatting - the focus is on translation, should anyone want to modify the content or the graphics - let's PR first in English and them translate to Chinese
2. Duplicate pages - the content should be translated over a page duplication. Readme.MD became Readme.chinese.MD, all other files should be duplicated similarly. So the number of English & Chinese pages should be the same. Will create a bold link from the English home page to the Chinese home page (with bold credit of course...)

https://github.com/i0natan/nodebestpractices/tree/chinese-translation

The code style suggests two contradicting advice: (a) "Name Your Functions" - avoid anonymous functions VS (b) "Use => Arrow Functions".

Both make sense, the first is easier to diagnose, second is more fluid when prototyping. Given that trade-off, this repository mission is recommending the better option. Would love to hear the community take and make a vote/call

Thank you! Thats so awesome!

I guess it's off-topic. I promise I dont write off-topic issues often! But this time I did. It's great repo!

Updates

• Update top badges with Node version and last update date
• Ensure all translations are aligned with the English version

Flowers
@ymhtut
@cwar

Stars
@js-kyle

I've written these simply (at work atm), so you'd have to reword them if you're going to add it to the README.

• There is significant overhead when accessing environment variables during runtime, so avoid referencing process.env per HTTP request in your server code.

• Don't transpile your code in-memory at runtime (e.g. with transpilers like babel-register or ts-node), as they have to transpile everything and consume a lot of memory. Rather, pre-transpile your code before pushing to production.

Probably most appropriate under Going To Production Practices. Dependency caching is using an on premise caching proxy such as Artifactory or Nexus in which to pull NodeJS dependencies for production pipelines.

Real world scenario where this has actually saved my company from halting productivity: leftpad being unpublished affected many companies where caching would have insulated them from the problem.

@BrunoScheufler @lirantal

I'm excited to Kick-off the security best practices section. Our goal is to reach a 20+ bullets security checklist that is highly comprehensive and curated. We work on this branch that already contains 14 titles

I suggest the following workflow:

A. TOC first: Write the bullets title – each can add, remark on the titles themselves until we reach a comprehensive list that is MECE (mutually exclusive and collaboratively exhausting). Note that going by our content guidelines we don’t include general security principle that can be found easily in many articles – we focus on bullets that can be correlated directly to Node. Generic security advice are grouped under a single bullet

B. Finalize the bibliography – gather a list of 5-10 great sources that explain the topics. This is needed to quote articles and include nice visuals. Liran’s book is, of course, a great candidate as a primary source for great content

@liran – we shall soon add a bibliography section to the repo, your book can appear there if you will

C. Write the content (inner pages) – assign topics to write, each writes as many topics that he can (0-20 😊)

D. Language proof – Bruno will revise the content grammar and the overall lexical quality

E. Promotion – publish as medium/hacker-noon article, SEO tricks, send to Node weekly, Node Twitter, reddit and many other techniques we constantly use successfully

How does this plan sounds like?

https://github.com/i0natan/nodebestpractices/blob/korean-translation/README.md

@XoDNr - Korean translation can be officially kicked-off. You're the lead! I'll be at your disposal should you need anything. A branch was created (link below), you should have permissions to it, everyone else must PR before changing anything there.

I would ask/recommend only 2 important guidelines:

Keep the same content & formatting - the focus is on translation, should anyone want to modify the content or the graphics - let's PR first in English and them translate to Korean
Duplicate pages - the content should be translated over a page duplication. Readme.MD became Readme.korean.MD, all other files should be duplicated similarly. So the number of English & Korean pages should be the same. Will create a bold link from the English home page to the Korean home page (with bold credit of course...)

https://github.com/i0natan/nodebestpractices/blob/korean-translation/README.md

@idori @refack @BrunoScheufler @lirantal

good work :)

https://twitter.com/nodepractices/status/964228269208981509

p.s. 20 first Node.JS GitHub packages (in terms of stars)

rc is a more popular config tool than nconf and config, is used by many rock-solid tools out there, and checks all the boxes you require. I'd suggest recommending it for config management.

I'd love to see a simple todo or a chat web app made with these best practices in mind 😄

@grafiktr - Turkish translation can be officially kicked-off. You're the lead! I'll be at your disposal should you need anything. Please create a branch for this work and PR to master once it's 100% done. Once we load it, will put your name on top of the Turkish page

I would ask/recommend only 2 important guidelines (if something isn't clear - please let us know and will be glad to do it for you):

Keep the same content & formatting - the focus is on translation, should anyone want to modify the content or the graphics - let's PR first in English and them translate to Turkish
Duplicate pages - the content should be translated over a page duplication. Readme.MD became Readme.turkish.MD, all other files should be duplicated similarly. So the number of English & Turkish pages should be the same. Will create a bold link from the English home page to the Turkish home page (with bold credit of course...).

Do we really need to use specific component's name as a prefix, for example: ' user/userAPI', is that essential? could we use ' user/API'?

https://github.com/i0natan/nodebestpractices/tree/russian-translation

@demid5111 - Russian translation can be officially kicked-off. You're the lead! I'll be at your disposal should you need anything. A branch was created (link below), you should have permissions to it, everyone else must PR before changing anything there.

I would ask/recommend only 2 important guidelines:

Keep the same content & formatting - the focus is on translation, should anyone want to modify the content or the graphics - let's PR first in English and them translate to Spanish
Duplicate pages - the content should be translated over a page duplication. Readme.MD became Readme.russian.MD, all other files should be duplicated similarly. So the number of English & Russian pages should be the same. You already have readme.russian.md & sections/breakintcomponents.russian.md - kindly create all other page duplication (feel free to ping should you need help). Will create a bold link from the English home page to the Russian home page (with bold credit of course...).

https://github.com/i0natan/nodebestpractices/tree/russian-translation

After 3.9 I suggest to put required current folder notation:

Node.js required the ./ notation when you are requiring a module that is in the same folder. With multiple requires from different folders, you can easily put your self into writing it differently every time.

Always put the ./ notation in front of requires.

// Avoid
module.exports.ModuleInTheSameFolder = require('./ModuleInTheSameFolder');
module.exports.ModuleInAnotherFolder = require('../ModuleInAnotherFolder');
module.exports.AnotherModuleInAnotherFolder = require('../../../AnotherModuleInAnotherFolder');

// Do
module.exports.ModuleInTheSameFolder = require('./ModuleInTheSameFolder');
module.exports.ModuleInAnotherFolder = require('./../ModuleInAnotherFolder');
module.exports.AnotherModuleInAnotherFolder = require('./../../../AnotherModuleInAnotherFolder');

Great job gathering all that into a single place :)

Regarding project structure in chapters 1.1. and 1.2. , are there any article links or public repos where we could witness such implementations?

The entire page seems like it was kinda copy pasted out of a template and does not provide any meaningful information.

The one paragraph explainer is mostly a quote but the next section is almost the same quote
with no working links to the original article.

There is no links to the actual tools being recommended

The last paragraph is not an nginx config as the title suggests nor relevant to this topic

If I understand the content right the title should be changed to -
`Use tools that automatically detect vulnerable dependencies'
Since the original title sounds more like some kind of automatic penetration testing tool.
This is probably should be done way before production so the section is not really correct

I'll try to submit a pull request with changes but this should probably be part of the security section and not production and following this issue #33 it seem like this section is not going to be available anytime soon

https://github.com/i0natan/nodebestpractices/blob/c0e1264dfe2161986a8c91e3df7df8d1d51b8785/sections/errorhandling/asyncerrorhandling.md#code-example--using-promises-to-catch-errors

This example has a syntax error:

doWork()
 .then(doWork)
 .then(doOtherWork)
 .then((result) => doWork)
 .catch((error) => throw error) // SyntaxError: Unexpected token throw
 .then(verify);

throw is a statement, it should be wrapped in {}:

 .catch((error) => {throw error;})

Hey, in https://github.com/i0natan/nodebestpractices/blob/master/sections/errorhandling/catchunhandledpromiserejection.md and in the README you mention that exceptions are swallowed by default - but that hasn't been the case for a while :)

I can dig up the PR where we changed the default to log if you'd like - I think it was in 7.6

Sorry for miss label. [question]

It would be nice to include information about the best practice regarding managing dependencies in a node app.

Either by using dependency injection, a dependency injection utility or just using CommonJS.

@mattjin

@idori who's putting the translation links in the home page asks which Chinese did we translate: simplified chinese \ traditional chinese?

Why not subclassing error ?

class AppError extends Error{
    constructor(name, httpCode, description, isOperational){
        super(description);
        this.httpCode = httpCode;
        this.name = name;
        //...other properties assigned here
    }

    toString(){
        return `${this.name} - ${this.httpCode}`
    }
}

(function one(){
    (function two(){
        try {
            throw new AppError("this is an error !", 200, 'This is the error message');
        } catch (error) {
            console.error(`${error}`);
            console.error(error.message);
            console.error(error.stack);
        }
    })()
})()

Hi

I saw your section "3.4 Don't Forget the Semicolon"

Don't forget that the semicolon "cannot save you".

Indeed, look at this code:

function aaa() {
    return
    {
        test: 1
    };
}
aaa()

If you run it, you will have ... undefined !!
Because the "{" of the json response is not on the same line of the return statement.

So, prefer using Eslint with adapted rules to avoid this kind of issue.

A cool video too to show more: https://www.youtube.com/watch?v=Qlr-FGbhKaI

Regards

@idori I don't think GitHub have Google-analytics style features, maybe we can use a pixel-analytics by putting an opaque image on our home page and then connect it with some analytics platform? any chance you can lead this check?

This is a common mistake but your guide on point 5.3 says

Your poor single thread will keep busy doing networking tasks instead of dealing with your application core and performance will degrade accordingly

While the general advice is good, this is not correct to the Node engine fundamentals. Node uses a single thread for event busing (libuv) but is still running multiple threads in the threadpool for assigning out events. See:

https://www.codingeek.com/tutorials/nodejs/is-nodejs-single-threaded/

https://www.quora.com/Is-Node-js-single-threaded

https://medium.com/@nodejs_recipes/is-nodejs-really-single-threaded-59f1845dfa69

Also note that there's a second part to this advice: You can run high CPU tasks on their own threads away from the event thread (but that's probably non-standard advice since it's much more complex than running such things in the reverse proxy).

Hey, I am quite new to this initiative. However eager to participate and translate to Russian. What should I do next?

I'm suggesting a new best practice under the code style practices: Avoid backward relative path

Context: it's common to see developers referring code in far-away folders - require('../../othercomponents/file.js')

Problem: encapsulation code smell + maintainability issue

What do you think?

https://github.com/i0natan/nodebestpractices/blob/spanish-translation/README.md

@eduardomontalvo - Spanish translation can be officially kicked-off. You're the lead! I'll be at your disposal should you need anything. A branch was created (link below), you should have permissions to it, everyone else must PR before changing anything there.

I would ask/recommend only 2 important guidelines:

Keep the same content & formatting - the focus is on translation, should anyone want to modify the content or the graphics - let's PR first in English and them translate to Spanish
Duplicate pages - the content should be translated over a page duplication. Readme.MD became Readme.spanish.MD, all other files should be duplicated similarly. So the number of English & Spanish pages should be the same. Will create a bold link from the English home page to the Spanish home page (with bold credit of course...)

https://github.com/i0natan/nodebestpractices/blob/spanish-translation/README.md

@refack @idori @BrunoScheufler

I suggest adding a section below - 'Credits' with logos of all the companies and blogs which unconsciously contributed ideas. This is not only a fair act but also a great way to (a) communicate that the knowledge here summarizes a lot of sources (b) brand it as de-facto best practices list that aggregates any other

what do you think?

I've found that working with JS data structures in an immutable way has significantly improved application performance.

Oversimplified example:

// mutation operation
const list = []
list.push('foo')

// immutable operation
let list = []
list = list.concat('foo')

While it may seem counter-intuitive in terms of working with completely new objects/values, when operating inside of complex loops/algorithms it has made both understanding what's happening to the data far easier to comprehend, as well you avoid scenarios where mutations can be far reaching and difficult to trace.

My team has successfully adopted this approach with one of our production APIs, and found it quite significantly improved performance.

We then took it a step further and use @substack's deep-freeze module as a simple safe guard against mutations.

This is one example I have, I'll see about digging up some more and/or finding decent articles that help make this more than just anecdotal :) .

If you want i can help with french translation...

Call for Hebrew translator who are willing to contribute and translate the guide to Hebrew.

Branch was created here:
https://github.com/i0natan/nodebestpractices/blob/hebrew-translation/README.hebrew.md

cc @idori

I recommend CC BY-SA 4.0 which AFAIK is equivalent to what Wikipedia use.

// for const name we use UPPERCASE
    const CONFIG = {
      key: 'value'
    };

I would like to mention that this is legacy since first versions of fortran.
It didn't have const's!
So for all registries/variables that we didn't wanna ppl to change we started using UPPERCASE notation.
Again: it was just because language didn't support const!

It's not nice to see that this legacy lives on 30+ years, even when most major languages/compilers understand const word.

Also most editors understand word const and display it different than variables (let, var).

I would postulate to drop 30+ years legacy, and rethink how we are doing things, and change:

// for const name we use UPPERCASE
const CONFIG = {
      key: 'value'
};

to

const config = {
   key: 'value'
}

Hey, I wanted to propose a simple note on this section: 3.7 Prefer const over let. Ditch the var

Using const for arrays and objects doesn't mean that those can't change. Indeed, you can push/concat/whatever (doesn't matter if it's a mutable or immutable method) an array being a const.

Happens the same on objects, you can update the keys inside an object declared by a const.

Two sections mention ESLint with similar text. This is redundant.

Guideline-based resources for web application security

• Twelve-Factor-App Config
• JWT Blacklisting
• Unsafe RegEx
• Avoid Eval

General web application security resources for Node.js

• RisingStack Node.js Security Checklist
• OWASP Web Application Security Checklist
• OWASP Top Ten Project
• @lirantal's Node.js security presentation
• Express Official Security Best Practices
• Node Security Presentation

NPM Packages created to secure Node.js web applications

• Helmet
• Express Validator
• Express Rate Limit
• Mongoose
• Sequelize
• Validator.js

Miscellaneous resources

• Node Security Platform (nsp)
• Snyk
• Sqreen
• Node.js VM core module to run code in a sandbox

This list is still in draft stage and to be continuously updated

Hello Guys.
I'm reading the practices and I'm really enjoying it, congratulations to the work. But I came across an interesting case: "well, there is a framework for that, it's called NPM"

Would not it be more correct and more understandable to use the term tool? "well, there is a tool for that, it's called NPM"

What about adding best practices for file naming? I have recently been struggling with it a bit and went with all lower-case for my recent projects.

The most common practice I think is to have the name of the file reflect the javascript function or class name that is being exported. But I believe the filesystem should be seen as a separate domain from code. Especially since some OS implementations are case insensitive by default, like Mac OS.

This can lead to problems because code executing fine on Mac OS might break on Linux or Windows systems, because there is a mistake in some casing. Then when you try to correct it, git (by default) doesn't see the change in filename. So you end up renaming it twice.

I went with kebab-case-naming and I am very happy that I never have to think about a filename anymore, but I still have a bit of a hard time convincing other people that it is a good idea. The kebab style seems to be the standard in NPM module imports, so to me it makes sense to keep it consistent across the whole codebase.

The only downside I can think of is that it is now not always apparent from a filename if it contains a class or a function. But by structuring files in components (like the guide suggests) and choosing names carefully, this hasn't been any issue for me so far. Also I work a lot with React and Typescript, and then the jsx/tsx and js/ts file extension already gives you a better idea what kind of thing your are looking at.

In any case, I think file naming should have best practices defined, because I believe it's not just a matter of taste, like some people think of semi-colons.

it would be nice to have also an example with async/await in the error management section.

Hello,

The section about Testing: 4. Testing And Overall Quality Practices.

I would explain what's wrong with mocks and when you should only use stubs.
and probably add the Testing pyramid, where canaries covers prod and runs like a cron, e2e covers everything but are slow, integration tests and unit tests.

Can you give a multilingual version by your freedom such as Chinese？

@i0natan Working on a large Node.JS project lately, I'm facing an issue of "deleting" data feature of my web application.

Since every piece of data is valuable, it wouldn't be physically/completely deleted from database, but instead "cached", "archived", "hidden" or so on ...

My struggle is what is the best practice to handle this situation, and I'd love to see a section on this great repository about this matter.

I was thinking that if someone with experience in using gitbook or hexo could make a version of this repository and use github pages to host it then it would be easier to navigate and read the guide.

Checkout these websites for inspiration

Example with gitbook

• redux documentation

Example with hexo

• vuejs documentation