read - User Input from Stdin

5.0.1 · active · verified Sun Apr 19

The `read` package provides a utility for securely and flexibly reading user input from `stdin` in Node.js applications. It serves as an enhanced alternative to Node's built-in `readline.question()` method, offering additional features such as silent input (e.g., for passwords), character replacement during silent input, input timeouts, default values, editable default values, terminal forcing, and auto-completion via a `completer` option. As of version 5.0.1, the package is actively maintained by the npm team and targets modern Node.js environments, requiring `^20.17.0 || >=22.9.0`. Major releases (e.g., v2.0.0, v3.0.0, v4.0.0, v5.0.0) typically introduce breaking changes related to Node.js version compatibility or API shifts, with minor releases adding new features like the `history` parameter in v4.1.0. The library primarily uses a Promise-based API for handling input, reflecting modern JavaScript asynchronous patterns.

Common errors

```
TypeError: read is not a function
```
cause Attempting to destructure `read` from a default `require` import (e.g., `const read = require('read'); read({ prompt: '...' });`) or trying to use it as a default import when it's a named export.

fix For CommonJS, use named destructuring: `const { read } = require('read')`. For ESM, use named import: `import { read } from 'read'`.
```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` the `read` package in a Node.js environment where it is treated as an ES Module (e.g., in a project with `"type": "module"` in `package.json`).

fix Change your import statement from `const { read } = require('read')` to `import { read } from 'read'`.
```
ReferenceError: await is not defined
```
cause Using `await read(...)` outside of an `async` function.

fix Wrap your `await` call within an `async` function, or use `.then().catch()` with the Promise returned by `read`.

Warnings

breaking Node.js engine requirement updated. The package now requires Node.js `^20.17.0 || >=22.9.0`.
Fix: Upgrade your Node.js version to meet the specified range.
breaking Node.js engine requirement updated. The package now requires Node.js `^18.17.0 || >=20.5.0`.
Fix: Upgrade your Node.js version to meet the specified range or downgrade `read` to a compatible version.
breaking The package was converted to TypeScript and ES Modules (ESM). This change primarily affects how the package is imported and consumed, particularly for projects using CommonJS (`require`).
Fix: Update import statements from `const { read } = require('read')` to `import { read } from 'read'`. Ensure your project's `package.json` is configured for ESM (e.g., setting `"type": "module"`) or use appropriate tooling for ESM/CJS interop.
breaking The API was refactored to be Promise-only. Callback-based usage is no longer supported. The Promise resolution no longer includes the `isDefault` boolean.
Fix: Refactor code to use `async/await` or `.then().catch()` with the returned Promise. Remove any `isDefault` checks from the resolved value.
gotcha Using the `silent: true` option with non-TTY input streams (e.g., redirected input or pipes) will not truly silence input and may behave unexpectedly as raw mode cannot be reliably set. This option is most effective in interactive terminal environments.
Fix: Ensure `read` is used in an interactive terminal environment for `silent` mode to function as intended. For non-interactive scripts, consider if `silent` is appropriate or if alternative input methods are more suitable.

Install

npm install read npm
yarn add read yarn
pnpm add read pnpm

Imports

read
wrong:
```
const read = require('read')
```
correct:
```
import { read } from 'read'
```
Since v3.0.0, `read` is primarily an ES Module (ESM) package. While `require` might work due to Node.js interoperability, `import` is the idiomatic and recommended way to use it in modern Node.js environments.
ReadOptions
```
import type { ReadOptions } from 'read'
```
TypeScript types for the options object are shipped with the package since v3.0.0.

Quickstart

This example demonstrates prompting for username, a silent password input with timeout and character replacement, and an editable default value for favorite color, using the `read` function and its options.

import { read } from 'read';

async function getUserInput() {
  try {
    const username = await read({ prompt: 'Username: ' });
    console.log(`Hello, ${username}!`);

    const password = await read({
      prompt: 'Password: ',
      silent: true,
      replace: '*',
      timeout: 15000 // 15 seconds
    });
    console.log('Password received (not echoed).');

    const favoriteColor = await read({
      prompt: 'What is your favorite color? ',
      default: 'blue',
      edit: true,
    });
    console.log(`Your favorite color is: ${favoriteColor}`);

  } catch (error) {
    if (error instanceof Error && error.message === 'timed out') {
      console.error('Input timed out. Please try again.');
    } else {
      console.error('An error occurred:', error);
    }
    process.exit(1);
  }
}

getUserInput();

view raw JSON →