npm package
@clack/prompts review
Use @clack/prompts for a person-facing setup command if you are willing to own cancellation and the final write boundary.
Printing 'cancelled' does not necessarily stop a Clack wizard. If a group onCancel callback returns normally, the loop continues to the next prompt. @clack/prompts is a pre-styled wrapper around @clack/core for interactive JavaScript command-line apps. It supplies questions, session messages and progress output. Use it to collect a setup plan from a person, then keep file writes behind an explicit cancellation and confirmation boundary.
Use @clack/prompts for a person-facing setup command if you are willing to own cancellation and the final write boundary. Start by making the cancel path stop your wizard before connecting it to filesystem work.
Answers from our run
@clack/prompts or prompts: which should you use?
prompts: Choose prompts when named answer overrides are central to your wizard. Its version-pinned README documents prompts.override; the existing prompts guide covers that different answer-object workflow at https://mrkeyoor.com/libs/prompts/. Use @clack/prompts for a person-facing setup command if you are willing to own cancellation and the final write boundary.
When should you not use @clack/prompts?
Your command must run unattended and you have no time to build a noninteractive input path. A question-driven interface is the wrong default for that job.
Use it if
Skip it if
Setup reality
Install the reviewed version with npm install @clack/prompts@1.9.0 and put the examples in an .mjs file, or an ESM project. The package declares Node >= 20.12.0. Its published metadata points the default export condition at dist/index.mjs and includes TypeScript declarations at dist/index.d.mts. This guide inspected the version-specific metadata, README, release notes and group implementation. We did not install the package or execute these snippets. They are documentation-based illustrations, not a compatibility, accessibility or performance test.
Check process.stdin.isTTY before starting an interactive path. Decide what your command should do when it has no terminal: accept explicit arguments or fail with a useful message. The example guard below chooses failure. Keep prompt output and any machine-readable output contract separate in your own command design. An answer collected interactively still needs application validation before it becomes a path, a shell argument or a file write. A masked password field changes what the terminal displays; don't print its returned value in logs.
Cancellation needs more care than the visual design suggests. For an individual question, call isCancel on its result before consuming it. In group, each callback receives earlier results and the implementation awaits prompts in key order. If a group onCancel callback returns normally, the loop continues to the next prompt. The implementation even assigns the string 'canceled' to that result before continuing. Throwing an application-specific error from onCancel stops this path, and an outer catch can set the exit status. Printing cancel() alone is not that exit policy. Keep side effects out of question callbacks and perform them only after the whole plan is accepted.
Version 1.9.0 adds an accessible spinner mode that emits static, append-only output. Use spinner({ accessible: true }) when that output format suits your users, then check the actual terminal and assistive technology you support. A spinner reports work; it does not perform an installation or recover from a failed write. The example stops it with a failure message when the operation throws.
Ratings below are editorial judgments on a 1 to 5 scale: 1 means weak evidence of suitability, 3 means useful documented support with material limits, and 5 means broad support with few identified gaps. API stability considers the published interface and release changes, docs quality considers runnable-looking explanations and inconsistencies, maintenance considers shipped fixes, and ecosystem considers integration surface. These are source-based assessments. Adoption, compatibility across runtimes and long-term support are unmeasured here, so none earns a rating from download or star counts.
Patterns
Refuse an unattended question session guard-terminal
if (!process.stdin.isTTY) {
throw new Error('Interactive terminal required. Pass a config file instead.');
}
const p = await import('@clack/prompts');
p.intro('Project setup');This is application policy, not a Clack fallback mode. Implement the promised config path in your command before advertising it to users.
Collect a name before using it text-with-cancel
import { text, isCancel, cancel } from '@clack/prompts';
const project = await text({
message: 'Project name?',
initialValue: 'my-app',
validate: value => value?.trim() ? undefined : 'Enter a name.'
});
if (isCancel(project)) {
cancel('Setup cancelled.');
throw new Error('Setup cancelled');
}
const name = project.trim();Check the result before calling string methods. This only rejects blank names; it does not make a name safe to use as a filesystem path.
Ask for permission to proceed confirm-plan
import { confirm, isCancel } from '@clack/prompts';
const approved = await confirm({
message: 'Create files from the reviewed plan?',
initialValue: false
});
if (isCancel(approved) || !approved) {
throw new Error('No files created');
}
// Perform application writes only after this point.A negative answer and cancellation both stop this illustration. Showing a confirmation cannot undo side effects that already happened in earlier callbacks.
Choose a template by stable value select-value
import { select, isCancel } from '@clack/prompts';
const template = await select({
message: 'Template?',
options: [
{ value: 'minimal', label: 'Minimal' },
{ value: 'service', label: 'Service' }
]
});
if (isCancel(template)) throw new Error('Setup cancelled');The result is the option value, not its label. Keep those values stable if saved configuration will depend on them.
Allow an empty feature selection optional-features
import { multiselect, isCancel } from '@clack/prompts';
const features = await multiselect({
message: 'Optional features?',
options: [
{ value: 'lint', label: 'Lint' },
{ value: 'tests', label: 'Tests' }
],
required: false
});
if (isCancel(features)) throw new Error('Setup cancelled');required: false allows the user to proceed without any optional tools. An empty selection is a valid plan, not cancellation.
Collect a masked secret without logging it masked-input
import { password, isCancel } from '@clack/prompts';
const secret = await password({
message: 'Service token?',
mask: '*',
validate: value => value ? undefined : 'Enter a token.'
});
if (isCancel(secret)) throw new Error('Setup cancelled');
// Pass secret directly to the component that needs it.Masking affects display while typing. Treat the returned string as a secret and keep it out of debug logs and generated public files.
Stop a group instead of continuing after cancel group-cancel-boundary
import * as p from '@clack/prompts';
class SetupCancelled extends Error {}
try {
const plan = await p.group({
project: () => p.text({ message: 'Project name?' }),
template: ({ results }) => p.select({
message: `Template for ${results.project}?`,
options: [
{ value: 'minimal', label: 'Minimal' },
{ value: 'service', label: 'Service' }
]
})
}, {
onCancel() {
p.cancel('Setup cancelled.');
throw new SetupCancelled();
}
});
p.outro(`Plan collected for ${plan.project}. No files written yet.`);
} catch (error) {
if (!(error instanceof SetupCancelled)) throw error;
process.exitCode = 130;
}The pinned group loop continues if onCancel merely returns. Throwing stops this illustration; the outer catch handles only that cancellation error. Do not put writes in these question callbacks.
Search a supplied list of templates search-options
import { autocomplete, isCancel } from '@clack/prompts';
const template = await autocomplete({
message: 'Find a template',
placeholder: 'Type to search...',
options: [
{ value: 'minimal', label: 'Minimal' },
{ value: 'service', label: 'Service' },
{ value: 'docs', label: 'Documentation' }
]
});
if (isCancel(template)) throw new Error('Setup cancelled');This supplies a local options array. It does not implement fetching a remote template catalog or retrying a failed network request.
Report work with static spinner output static-spinner
import { spinner } from '@clack/prompts';
import { mkdir } from 'node:fs/promises';
const status = spinner({ accessible: true });
status.start('Creating output directory');
try {
await mkdir('./generated-project', { recursive: true });
status.stop('Output directory ready');
} catch (error) {
status.stop('Could not create output directory');
throw error;
}This standalone illustration creates a directory. In a wizard, run it only after the plan is accepted. accessible: true requests the static output format added in 1.9.0; we have not tested it with a screen reader.
Finish with a truthful status message session-messages
import { intro, log, outro } from '@clack/prompts';
intro('Project setup');
log.info('Reading the setup plan.');
log.warn('Existing files need an explicit overwrite policy.');
outro('Planning example complete. No project files written.');These functions display messages. Change the final message to match what your command actually completed, and never report a successful write from a catch block.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| prompts | npm | Choose prompts when named answer overrides are central to your wizard. Its version-pinned README documents prompts.override; the existing prompts guide covers that different answer-object workflow at https://mrkeyoor.com/libs/prompts/. |
| enquirer | npm | Consider enquirer when extensibility is a selection criterion. Its npm description explicitly positions it for extensible prompt systems; evaluate the customization you need before choosing it over Clack styling. |
More cli & tooling guides
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.