lirantal / nodejs-cli-apps-best-practices Goto Github PK

I was about to open a PR that adds notes specific to distinguishing STDOUT from STDERR. However, the concept would have been dispersed among many other items:

• Enable structured output
• Informational errors
• Provide debug mode

As the topic of stdout vs stderr is big enough, I think it probably warrants its own line-item.

Key point: STDERR is for more than just error output. It's for all diagnostic output.

I want to translate the Chinese version.

Would be nice if someone would like to contribute a section on CLIs supporting help.

My points to make would be:

• A CLI should support -h and --help to provide help
• A CLI should show this help if it is ran without arguments (unless it is possible for it to execute well without them)
• Provide help for sub-commands when those are being used
• When conflicting args are both provided a clear message should indicate so

This all should be embodied in one item about supporting help.

Document other resources like:

1. https://clig.dev/
2. https://primer.style/cli/getting-started/principles

as additional educational material

Expected scope of work for this issue:

• The README currently has 8 sections
• Let's add a new section called: 10 Appendix: CLI educational resources
• In it, let's document the above suggested resources
• Let's not do the other section's format of "DO and OTHERWISE" because it doesn't fit. Instead, should we use a table to document them with some other properties, or perhaps just a bulleted list? Happy to go with whatever makes the most sense and we can change later.

It is recommended to use Crowdin to improve the efficiency of project internationalization.

What are your thoughts around organizing the layouts a bit differently?

Some feedback I received is around:

• Getting rid of the collapsible content such as in Details or Recommended packages part and then just defaulting to that content being visible straight-out.
• Adding a TL;DR for the top of the guide instead of the short intro, is that more helpful or not much of a change of what we have today?
• Should we add more space between items and also between end/beginning of sections?
• I want to add a contributors section too based on https://allcontributors.org/

This could be a new topic. The CLI application should remove it's internal configuration files (if there are any) when uninstalling the package. We can use NPM's pre or post uninstall script for this purpose.

https://docs.npmjs.com/misc/scripts

As written in https://docs.npmjs.com/cli/v8/using-npm/scripts#a-note-on-a-lack-of-npm-uninstall-scripts the uninstall lifecycle scripts are not implemented and will not function since v7. Due to that chapter 2.3 Cleanup configuration files chapter should be removed as it does not work since npm v7

According to https://nodejs.org/en/about/releases/

• node 14 the maintenance LTS, which comes with npm v6, is supported until 2023-04-30.
• node 16 the active LTS, which comes with npm v8, is supported until 2024-04-30.

Hello, I am someone who found this post very appealing. Thank you for sharing such a wonderful piece.
I am interested in translating this content into Korean and wanted to inquire about it.

Thank you.

up-to-date Node.js runtime features that should be addressed throughout this guide are:

1. colors using import { styleText } from 'node:util'
2. Node.js own command-line argument parsing

I think this is an important practice to keep the published package size small. Sometimes package authors accidentally include their development configuration, spec files, etc. part of the published package. I've done it once 🙆‍♂️

For more details on this topic - https://medium.com/@nodejs/publishing-npm-packages-c4c615a0fc6b

Hi everyone,

GitLocalize is giving me some trouble after a few weeks of inactivity in Spanish translations. It seems it isn´t maintaining the structure of the .md file.

Has anyone had this problem? How have they solved it?

My idea to solve it would be in this case not to work via GitLocalize and create a PR.

What do you think about change the import type of the modules from "require" to "import"? The new versions of NodeJS we can already work like this.

For example: https://github.com/lirantal/nodejs-cli-apps-best-practices#31-accept-input-as-stdin

import readline from "readline";

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

rl.question("What do you think of Node.js? ", answer => {
// TODO: Log the answer in a database
console.log(`Thank you for your valuable feedback: ${answer}`);

rl.close();
});

As a counterpoint to the suggestion with 'empathetic CLIs', having a CLI that may suddenly block for STDIN is not friendly or empathetic. It does not account for an invocation that be run un-attended (ie on a build server, or scheduled cron job). Indeed, I would go so far as to say that any single CLI command should always be interactive or never be interactive; not sometimes.

It's also worth noting that an invocation that has STDOUT piped to its STDIN will start consuming that STDIN as if from the user if it attempts to switch to interactive mode based on some ambiguity. That is almost certainly not what the author nor user wants.

VHS - helpful CLI automation that is useful for demos or screen recording of the terminal https://github.com/charmbracelet/vhs

Looking for someone who would be interesting to contribute a new item on proper version usage.

My take on it would be around:

• A program should support --version and -v to inspect the installed version

Further info that can be elaborated in details: A program may choose to show its version when being run in order to easily surface the version to users. Example of this is Yarn.

Add the following badge to the repository which refers to the Crowdin translation service this repository uses:

[![Crowdin](https://badges.crowdin.net/nodejs-cli-apps-best-practices/localized.svg)](https://crowdin.com/project/nodejs-cli-apps-best-practices)

Feature a new section to include popular tools to build CLIs, such as:

1. oclif
2. inquirer
3. ink
4. blessed

Expected scope of work for this issue:

• The README currently has 8 sections
• Let's add a new section called: 9 Appendix: CLI Frameworks
• In it, let's document the above suggested frameworks
• Let's not do the other section's format of "DO and OTHERWISE" because it doesn't fit. Instead, I suggest we create a table with the library name, another column for the npm package, and another column for the github repo. We can add another column that has badges of current stars and npm downloads. Anything else you can think of that would be helpful?

[EDIT] Removing the storage aspect of this issue, as it's been already addressed, so the focus will only be on authentication.