From f5b45d068b395265dbbfddc3936a4226445d9f9e Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:25:03 +0100 Subject: [PATCH 01/10] content(learn cli): WIP --- ...t-input-from-the-command-line-in-nodejs.md | 44 +-------------- ...-read-environment-variables-from-nodejs.md | 7 +++ .../how-to-use-the-nodejs-repl.md | 14 ++++- ...output-to-the-command-line-using-nodejs.md | 53 +++++++------------ ...un-nodejs-scripts-from-the-command-line.md | 4 +- 5 files changed, 43 insertions(+), 79 deletions(-) diff --git a/apps/site/pages/en/learn/command-line/accept-input-from-the-command-line-in-nodejs.md b/apps/site/pages/en/learn/command-line/accept-input-from-the-command-line-in-nodejs.md index 99a040434ca79..0fc85bc6fc5b1 100644 --- a/apps/site/pages/en/learn/command-line/accept-input-from-the-command-line-in-nodejs.md +++ b/apps/site/pages/en/learn/command-line/accept-input-from-the-command-line-in-nodejs.md @@ -8,7 +8,7 @@ authors: flaviocopes, MylesBorins, fhemberger, LaRuaNa, ahmadawais How to make a Node.js CLI program interactive? -Node.js since version 7 provides the [`readline` module](https://nodejs.org/api/readline.html) to perform exactly this: get input from a readable stream such as the `process.stdin` stream, which during the execution of a Node.js program is the terminal input, one line at a time. +Node.js since version 7 provides the [`readline` module](https://nodejs.org/docs/latest-v22.x/api/readline.html) to perform exactly this: get input from a readable stream such as the `process.stdin` stream, which during the execution of a Node.js program is the terminal input, one line at a time. ```cjs const readline = require('node:readline'); @@ -47,45 +47,3 @@ In this callback function, we close the readline interface. `readline` offers several other methods, please check them out on the package documentation linked above. If you need to require a password, it's best not to echo it back, but instead show a `*` symbol. - -The simplest way is to use the [`readline-sync` package](https://www.npmjs.com/package/readline-sync) which is very similar in terms of the API and handles this out of the box. - -A more complete and abstract solution is provided by the [Inquirer.js package](https://github.com/SBoudrias/Inquirer.js). - -You can install it using `npm install inquirer`, and then you can replicate the above code like this: - -```cjs -const inquirer = require('inquirer'); - -const questions = [ - { - type: 'input', - name: 'name', - message: "What's your name?", - }, -]; - -inquirer.prompt(questions).then(answers => { - console.log(`Hi ${answers.name}!`); -}); -``` - -```mjs -import inquirer from 'inquirer'; - -const questions = [ - { - type: 'input', - name: 'name', - message: "What's your name?", - }, -]; - -inquirer.prompt(questions).then(answers => { - console.log(`Hi ${answers.name}!`); -}); -``` - -Inquirer.js lets you do many things like asking multiple choices, having radio buttons, confirmations, and more. - -It's worth knowing all the alternatives, especially the built-in ones provided by Node.js, but if you plan to take CLI input to the next level, Inquirer.js is an optimal choice. diff --git a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md index 17bef93701006..94ca098b114fc 100644 --- a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md +++ b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md @@ -57,3 +57,10 @@ node --env-file=.env --env-file=.development.env app.js ``` > Note: if the same variable is defined in the environment and in the file, the value from the environment takes precedence. + +But there may be a problem: if the file doesn't exist, it will return an error. +To avoid this, you can use the `--env-file-if-exists` flag. + +```bash +node --env-file-if-exists=.env app.js +``` diff --git a/apps/site/pages/en/learn/command-line/how-to-use-the-nodejs-repl.md b/apps/site/pages/en/learn/command-line/how-to-use-the-nodejs-repl.md index 99c84bf0260c6..f29a61d91db63 100644 --- a/apps/site/pages/en/learn/command-line/how-to-use-the-nodejs-repl.md +++ b/apps/site/pages/en/learn/command-line/how-to-use-the-nodejs-repl.md @@ -1,11 +1,17 @@ --- title: How to use the Node.js REPL layout: learn -authors: flaviocopes, MylesBorins, fhemberger, LaRuaNa, ahmadawais, vaishnav-mk +authors: flaviocopes, MylesBorins, fhemberger, LaRuaNa, ahmadawais, vaishnav-mk, AugustinMauyroy --- # How to use the Node.js REPL +## What is the Node.js REPL? + +Node.js comes with a built-in REPL (Read-Eval-Print Loop) environment that allows you to execute JavaScript code interactively. The REPL is accessible through the terminal and is a great way to test out small pieces of code. + +## How to use the Node.js REPL + The `node` command is the one we use to run our Node.js scripts: ```bash @@ -112,10 +118,14 @@ If you type `.break` at the end of a line, the multiline mode will stop and the We can import the REPL in a JavaScript file using `repl`. -```js +```cjs const repl = require('node:repl'); ``` +```mjs +import repl from 'node:repl'; +``` + Using the repl variable we can perform various operations. To start the REPL command prompt, type in the following line diff --git a/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md b/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md index 294ea5056c837..ebf9801b49d4b 100644 --- a/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md +++ b/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md @@ -1,14 +1,14 @@ --- title: Output to the command line using Node.js layout: learn -authors: flaviocopes, potch, MylesBorins, fhemberger, LaRuaNa, amiller-gh, ahmadawais +authors: flaviocopes, potch, MylesBorins, fhemberger, LaRuaNa, amiller-gh, ahmadawais, AugustinMauroy --- # Output to the command line using Node.js ### Basic output using the console module -Node.js provides a [`console` module](https://nodejs.org/api/console.html) which provides tons of very useful ways to interact with the command line. +Node.js provides a [`console` module](https://nodejs.org/docs/latest-v22.x/api/console.html) which provides tons of very useful ways to interact with the command line. It is basically the same as the `console` object you find in the browser. @@ -168,44 +168,31 @@ It will not appear in the console, but it will appear in the error log. ### Color the output -You can color the output of your text in the console by using [escape sequences](https://gist.github.com/iamnewton/8754917). An escape sequence is a set of characters that identifies a color. +> **NOTE** +> This part of the resource is designed with version 22.11 which notes `styleText` as ‘Active development’. -Example: - -```js -console.log('\x1b[33m%s\x1b[0m', 'hi!'); -``` +In many cases, you will be tempted to paste certain text to get a nice output at the terminal. -You can try that in the Node.js REPL, and it will print `hi!` in yellow. +There is a `styleText` function provided by the `node:util` module. Let's discover how to use it. -However, this is the low-level way to do this. The simplest way to go about coloring the console output is by using a library. [Chalk](https://github.com/chalk/chalk) is such a library, and in addition to coloring it also helps with other styling facilities, like making text bold, italic or underlined. - -You install it with `npm install chalk`, then you can use it: - -```js -const chalk = require('chalk'); +First of all, you need to import the `styleText` function from the `node:util` module: -console.log(chalk.yellow('hi!')); +```esm +import { styleText } from 'node:util'; ``` -Using `chalk.yellow` is much more convenient than trying to remember the escape codes, and the code is much more readable. - -Check the project link posted above for more usage examples. - -### Create a progress bar - -[Progress](https://www.npmjs.com/package/progress) is an awesome package to create a progress bar in the console. Install it using `npm install progress` +```cjs +const { styleText } = require('node:util'); +``` -This snippet creates a 10-step progress bar, and every 100ms one step is completed. When the bar completes we clear the interval: +Then, you can use it to style your text: ```js -const ProgressBar = require('progress'); - -const bar = new ProgressBar(':bar', { total: 10 }); -const timer = setInterval(() => { - bar.tick(); - if (bar.complete) { - clearInterval(timer); - } -}, 100); +console.log( + styleText(['red'], 'This is red text ') + + styleText(['green, bold'], 'and this is green bold text ') + + 'this is normal text' +); ``` + +The first argument is an array of styles, and the second argument is the text you want to style. We invite you to read [the docs](https://nodejs.org/docs/latest-v22.x/api/util.html#utilstyletextformat-text-options) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index 93ffaf15b73cf..a6b4edf4fa394 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -56,4 +56,6 @@ node --watch app.js ``` So when you change the file, the application will restart automatically. -Read the [`--watch` flag documentation](https://nodejs.org/docs/latest/api/cli.html#--watch). +Read the [`--watch` flag documentation](https://nodejs.org/docs/latest-v22.x/api/cli.html#--watch). + +## Run a task with node.js From 4b767d9f5e3db97dd268a52f6e75fdb2b9adc1ae Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:33:35 +0100 Subject: [PATCH 02/10] content(learn cli): introduce --- ...un-nodejs-scripts-from-the-command-line.md | 50 +++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index a6b4edf4fa394..4fc9459f8d91b 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -48,8 +48,8 @@ node -e "console.log(123)" ## Restart the application automatically -As of nodejs V16, there is a built-in option to automatically restart the application when a file changes. This is useful for development purposes. -To use this feature, you need to pass the `--watch' flag to nodejs. +As of Node.js V16, there is a built-in option to automatically restart the application when a file changes. This is useful for development purposes. +To use this feature, you need to pass the `--watch` flag to Node.js. ```bash node --watch app.js @@ -58,4 +58,48 @@ node --watch app.js So when you change the file, the application will restart automatically. Read the [`--watch` flag documentation](https://nodejs.org/docs/latest-v22.x/api/cli.html#--watch). -## Run a task with node.js +## Run a task with Node.js + +Node.js provides a built-in task runner that allows you to execute specific commands defined in your `package.json` file. This can be particularly useful for automating repetitive tasks such as running tests, building your project, or linting your code. + +### Using the `--run` flag + +The `--run` flag allows you to run a specified command from the `scripts` section of your `package.json` file. For example, if you have the following `package.json`: + +```json +{ + "type": "module", + "scripts": { + "start": "node app.js", + "dev": "node --run -- --watch", + "test": "node --test", + } +} +``` + +You can run the `test` script using the `--run` flag: + +```bash +node --run test +``` + +### Passing arguments to the command + +Let's explain the `dev` key in the `scripts` object of the `package.json` file. + +The syntaxt `-- --another-argument` is used to pass arguments to the command. In this case, the `--watch` argument is passed to the `dev` script. + +```bash +node --run dev +``` + +### Environment variables + +The `--run` flag sets specific environment variables that can be useful for your scripts: + +- `NODE_RUN_SCRIPT_NAME`: The name of the script being run. +- `NODE_RUN_PACKAGE_JSON_PATH`: The path to the `package.json` file being processed. + +### Intentional limitations + +The Node.js task runner is intentionally more limited compared to other task runners like `npm run` or `yarn run`. It focuses on performance and simplicity, omitting features like running `pre` or `post` scripts. This makes it suitable for straightforward tasks but may not cover all use cases. From 623a5c1922a49a5f11c8816249b1b2a305fc4c4a Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:36:35 +0100 Subject: [PATCH 03/10] content(learn cli): add link --- .../command-line/run-nodejs-scripts-from-the-command-line.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index 4fc9459f8d91b..17c68942ce905 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -64,7 +64,7 @@ Node.js provides a built-in task runner that allows you to execute specific comm ### Using the `--run` flag -The `--run` flag allows you to run a specified command from the `scripts` section of your `package.json` file. For example, if you have the following `package.json`: +The [`--run`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--run) flag allows you to run a specified command from the `scripts` section of your `package.json` file. For example, if you have the following `package.json`: ```json { From 13ec0c1d9f62ec5b7620212cb65f1cc5ab67170c Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:43:59 +0100 Subject: [PATCH 04/10] content(learn cli): fix link --- .../how-to-read-environment-variables-from-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md index 94ca098b114fc..04642aa592dc2 100644 --- a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md +++ b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md @@ -27,7 +27,7 @@ process.env.USER_KEY; // "foobar" In the same way you can access any custom environment variable you set. -Node.js 20 introduced **experimental** [support for .env files](https://nodejs.org/dist/latest-v20.x/docs/api/cli.html#--env-fileconfig). +Node.js 20 introduced **experimental** [support for .env files](https://nodejs.org/dist/latest-v22.x/docs/api/cli.html#--env-fileconfig). Now, you can use the `--env-file` flag to specify an environment file when running your Node.js application. Here's an example `.env` file and how to access its variables using `process.env`. From 917ea31f4db41904fd19e5f31191ca2c5c85a33f Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:47:11 +0100 Subject: [PATCH 05/10] content(learn cli): add shebang link --- .../command-line/run-nodejs-scripts-from-the-command-line.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index 17c68942ce905..153f7ff5e8df6 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -14,7 +14,7 @@ If your main Node.js application file is `app.js`, you can call it by typing: node app.js ``` -Above, you are explicitly telling the shell to run your script with `node`. You can also embed this information into your JavaScript file with a "shebang" line. The "shebang" is the first line in the file, and tells the OS which interpreter to use for running the script. Below is the first line of JavaScript: +Above, you are explicitly telling the shell to run your script with `node`. You can also embed this information into your JavaScript file with a ["shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix)) line. The "shebang" is the first line in the file, and tells the OS which interpreter to use for running the script. Below is the first line of JavaScript: ```js #!/usr/bin/node From 1584fbc07da0875e646dec3efe9845ac8d3160ee Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:49:52 +0100 Subject: [PATCH 06/10] content(learn cli): clarify process global object --- .../how-to-read-environment-variables-from-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md index 04642aa592dc2..e30a18b495d8b 100644 --- a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md +++ b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md @@ -16,7 +16,7 @@ USER_ID=239482 USER_KEY=foobar node app.js That will pass the user `USER_ID` as **239482** and the `USER_KEY` as **foobar**. This is suitable for testing, however for production, you will probably be configuring some bash scripts to export variables. -> Note: `process` does not require a "require", it's automatically available. +> Note: `process` does not need to be imported, it is a global object in Node.js. Here is an example that accesses the `USER_ID` and `USER_KEY` environment variables, which we set in above code. From 1dbbe1676d5182f9186b00b71618d7d1f5582963 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 11:10:33 +0100 Subject: [PATCH 07/10] content(learn cli): fix --- .../command-line/output-to-the-command-line-using-nodejs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md b/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md index ebf9801b49d4b..6362249f7ece9 100644 --- a/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md +++ b/apps/site/pages/en/learn/command-line/output-to-the-command-line-using-nodejs.md @@ -21,6 +21,7 @@ You can pass multiple variables to `console.log`, for example: ```js const x = 'x'; const y = 'y'; + console.log(x, y); ``` @@ -177,7 +178,7 @@ There is a `styleText` function provided by the `node:util` module. Let's discov First of all, you need to import the `styleText` function from the `node:util` module: -```esm +```mjs import { styleText } from 'node:util'; ``` From a2031d68aaf92c53c22e7c5eaece056824aab93b Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Mon, 2 Dec 2024 11:16:41 +0100 Subject: [PATCH 08/10] fix: code format --- .../command-line/run-nodejs-scripts-from-the-command-line.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index 153f7ff5e8df6..cd64f060f1c36 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -14,7 +14,7 @@ If your main Node.js application file is `app.js`, you can call it by typing: node app.js ``` -Above, you are explicitly telling the shell to run your script with `node`. You can also embed this information into your JavaScript file with a ["shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix)) line. The "shebang" is the first line in the file, and tells the OS which interpreter to use for running the script. Below is the first line of JavaScript: +Above, you are explicitly telling the shell to run your script with `node`. You can also embed this information into your JavaScript file with a ["shebang"]() line. The "shebang" is the first line in the file, and tells the OS which interpreter to use for running the script. Below is the first line of JavaScript: ```js #!/usr/bin/node @@ -72,7 +72,7 @@ The [`--run`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--run) flag allo "scripts": { "start": "node app.js", "dev": "node --run -- --watch", - "test": "node --test", + "test": "node --test" } } ``` From 37699f60f5950cd284948a96dec8c2b7975338dd Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Mon, 2 Dec 2024 11:29:03 +0100 Subject: [PATCH 09/10] fix typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Augustin Mauroy --- .../command-line/run-nodejs-scripts-from-the-command-line.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md index cd64f060f1c36..d2a68883b7e8c 100644 --- a/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/apps/site/pages/en/learn/command-line/run-nodejs-scripts-from-the-command-line.md @@ -87,7 +87,7 @@ node --run test Let's explain the `dev` key in the `scripts` object of the `package.json` file. -The syntaxt `-- --another-argument` is used to pass arguments to the command. In this case, the `--watch` argument is passed to the `dev` script. +The syntax `-- --another-argument` is used to pass arguments to the command. In this case, the `--watch` argument is passed to the `dev` script. ```bash node --run dev From 60239c44480789983c3d7a51e020809ca2dbb454 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Mon, 16 Dec 2024 17:45:50 +0100 Subject: [PATCH 10/10] rephrase sentences Co-authored-by: Ruy Adorno Signed-off-by: Augustin Mauroy --- .../how-to-read-environment-variables-from-nodejs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md index e30a18b495d8b..d4d84c6c2e04d 100644 --- a/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md +++ b/apps/site/pages/en/learn/command-line/how-to-read-environment-variables-from-nodejs.md @@ -58,8 +58,8 @@ node --env-file=.env --env-file=.development.env app.js > Note: if the same variable is defined in the environment and in the file, the value from the environment takes precedence. -But there may be a problem: if the file doesn't exist, it will return an error. -To avoid this, you can use the `--env-file-if-exists` flag. +In case you want to optionally read from a `.env` file, it's possible to avoid +throwing an error if the file is missing using the `--env-file-if-exists` flag. ```bash node --env-file-if-exists=.env app.js