clack-stepper #

A card-based stepper container for @clack/prompts. Like group(), but with back-navigation, async steps, and conditional flow.

Each step renders in a fixed terminal region with a breadcrumb header. Going back (esc/ctrl+c) clears the current card and re-renders the previous step in place.

Install #

npm install clack-stepper

Usage #

import * as p from "@clack/prompts";
import { stepper } from "clack-stepper";

p.intro("Project setup");

const result = await stepper(
  {
    name: {
      label: "Name",
      run: () => p.text({ message: "Project name?" }),
    },
    language: {
      label: "Language",
      run: ({ results }) =>
        p.select({
          message: `Language for ${results.name}?`,
          options: [
            { value: "js", label: "JavaScript" },
            { value: "py", label: "Python" },
          ],
        }),
    },
    framework: {
      label: "Framework",
      when: ({ results }) => results.language === "js",
      run: async ({ results }) => {
        const opts = await fetchFrameworks(results.language);
        return p.select({ message: "Framework?", options: opts });
      },
    },
  },
  {
    onCancel: () => {
      p.cancel("Cancelled.");
      process.exit(0);
    },
  },
);

p.outro("Done!");

API #

stepper(steps, options?) #

Returns a promise that resolves to an object keyed by step name, containing each step's result.

Step definition #

Each key in the steps object defines a step:

Property	Type	Description
label	string	Display text for the breadcrumb header.
run	(ctx) => Promise<T>	The prompt to run. Typically a @clack/prompts call.
when	(ctx) => boolean	Optional. Step is skipped when this returns false. Re-evaluated on each visit.

The ctx argument contains:

• results -- accumulated answers from completed steps (partial, typed).
• io -- I/O streams for forwarding to prompts (see Testing below).

Options #

Property	Type	Description
onCancel	({ results }) => void	Called when the user escapes past the first step.
output	Writable	Custom output stream for the stepper's chrome. Defaults to process.stdout.
promptIO	{ input?, output? }	I/O streams forwarded to step callbacks via ctx.io.

How it works #

• esc or ctrl+c on any step goes back to the previous step.
• esc on the first step triggers onCancel.
• Steps with when are re-evaluated each time the stepper reaches them, so changing an earlier answer can add or remove later steps.
• Any async work (fetching data, spinners) can happen inside run before calling a prompt.

Testing #

The stepper's logic can be tested by mocking the run functions directly:

import { stepper } from "clack-stepper";

const result = await stepper(
  {
    name: { label: "Name", run: () => Promise.resolve("my-app") },
    lang: { label: "Lang", run: () => Promise.resolve("js") },
  },
  { output: mockOutput },
);

Return a Symbol from run to simulate cancel/back-navigation.

For integration tests with real @clack/prompts, pass mock streams via promptIO and spread ctx.io into prompt options:

const result = await stepper(
  {
    name: {
      label: "Name",
      run: ({ io }) => p.text({ message: "Name?", ...io }),
    },
  },
  { output: mockOutput, promptIO: { input: mockInput, output: mockPromptOutput } },
);