prompts

Prompts Project Introduction

Prompts is a lightweight and user-friendly tool designed for creating interactive command-line interface (CLI) prompts. Built to be both aesthetically pleasing and functional, it offers developers a simple way to gather information from users via the command line. The following sections provide a detailed overview of its features, installation process, usage examples, API, and the various types of prompts it supports.

Features

1. Simplicity: Prompts operates without any large dependencies and is not fragmented into numerous small modules, ensuring simplicity and ease of use.
2. User-Friendliness: With a focus on creating beautiful CLI interfaces, Prompts employs layouts and colors that enhance user interaction.
3. Promise-Based: Utilizing JavaScript promises and async/await, Prompts eliminates the complexities of callback functions.
4. Flexibility: Each prompt can function independently, allowing for flexibility in use.
5. Testability: Developers can programmatically submit answers, which facilitates testing.
6. Unified Experience: Users are provided with a consistent interface across all prompt types.

Installation

To integrate Prompts into a Node.js environment, simply use the following npm command:

$ npm install --save prompts

Note that Prompts requires Node.js version 14 or higher.

Usage

Here's a basic example of how you can use Prompts within a Node.js application:

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'number',
    name: 'value',
    message: 'How old are you?',
    validate: value => value < 18 ? `Nightclub is 18+ only` : true
  });

  console.log(response); // => { value: 24 }
})();

This example demonstrates how to ask simple questions using a number prompt and implements a basic validation function.

Examples

Single Prompt

A single prompt example might look like this:

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'text',
    name: 'meaning',
    message: 'What is the meaning of life?'
  });

  console.log(response.meaning);
})();

Prompt Chain

Multiple prompts can be linked in a chain, ensuring each prompt has a unique name to prevent data overwriting:

const prompts = require('prompts');

const questions = [
  {
    type: 'text',
    name: 'username',
    message: 'What is your GitHub username?'
  },
  {
    type: 'number',
    name: 'age',
    message: 'How old are you?'
  },
  {
    type: 'text',
    name: 'about',
    message: 'Tell something about yourself',
    initial: 'Why should I?'
  }
];

(async () => {
  const response = await prompts(questions);
})();

Dynamic Prompts

Prompts can be dynamic, adapting based on previous answers:

const prompts = require('prompts');

const questions = [
  {
    type: 'text',
    name: 'dish',
    message: 'Do you like pizza?'
  },
  {
    type: prev => prev == 'pizza' ? 'text' : null,
    name: 'topping',
    message: 'Name a topping'
  }
];

(async () => {
  const response = await prompts(questions);
})();

API

Prompts provides an API that allows developers to define prompt objects and manage responses programmatically. Key options include:

• onSubmit: Callback upon prompt submission, allowing for actions based on user responses.
• onCancel: Callback for handling cancellations, providing an opportunity to manage interrupted interactions.
• override: Pre-answer questions, practical for automation or testing with predefined inputs.
• inject: Programmatic response injection, ideal for testing the application's behavior with controlled inputs.

Prompt Objects and Types

Prompts supports several prompt types, each designed for specific input requirements, including:

• Text: For free text input.
• Password: Secured input with disguised characters.
• Invisible: Input that's not displayed on the screen.
• Number: For numeric values with optional range and validation.
• Confirm: Yes or no questions.
• List: Captures lists of items.
• Toggle: A switch prompt allowing binary choices.
• Select and Multiselect: For single or multiple choice options.
• Autocomplete: Inputs with auto-suggestions.

Each prompt object can be customized with properties such as type, name, message, initial, and more, making Prompts a highly adaptable tool for gathering user input.

In summary, the Prompts project provides a robust and straightforward mechanism for developing interactive command-line applications, offering a blend of simplicity, flexibility, and a unified user experience.