tessl/npm-clack--prompts

Effortlessly build beautiful command-line apps - an opinionated, pre-styled wrapper around @clack/core

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Session Management

Name: tessl/npm-clack--prompts
Author: tessl

Flow control utilities for managing prompt sessions with consistent visual styling and proper session boundaries.

Capabilities

Session Introduction

Display a styled introduction message to begin a prompt session.

/**
 * Displays a session introduction message with consistent styling
 * @param title - Optional title text for the introduction
 */
function intro(title?: string): void;

Usage Examples:

import { intro } from "@clack/prompts";

// Basic introduction
intro("Welcome to My CLI");

// Introduction with application name
intro("create-awesome-app");

// Introduction without title (displays just the visual separator)
intro();

The intro function prints a visually distinct header that marks the beginning of an interactive session, helping users understand when the CLI is starting its interactive phase.

Session Conclusion

Display a styled conclusion message to end a prompt session.

/**
 * Displays a session conclusion message with consistent styling
 * @param message - Optional message text for the conclusion
 */
function outro(message?: string): void;

Usage Examples:

import { outro } from "@clack/prompts";

// Success conclusion
outro("Project created successfully! 🎉");

// Simple conclusion
outro("All done!");

// Conclusion with instructions
outro("Run 'npm start' to begin development");

// Visual separator only
outro();

The outro function provides a clear visual end to the interactive session, often used to display success messages or next steps.

Cancellation Message

Display a styled cancellation message when operations are cancelled.

/**
 * Displays a cancellation message with error styling
 * @param message - Optional cancellation message (defaults to empty)
 */
function cancel(message?: string): void;

Usage Examples:

import { cancel, isCancel, text } from "@clack/prompts";

const name = await text({
  message: "What's your name?",
});

if (isCancel(name)) {
  cancel("Operation cancelled by user");
  process.exit(0);
}

// Custom cancellation message
if (someErrorCondition) {
  cancel("Setup failed - missing required dependencies");
  process.exit(1);
}

// Simple cancellation
cancel("Cancelled");

The cancel function displays a red-styled error message, typically used when users press Ctrl+C or when operations fail.

Information Notes

Display styled information boxes with optional titles.

/**
 * Displays a styled information note in a bordered box
 * @param message - The note content (defaults to empty)
 * @param title - Optional title for the note box (defaults to empty)
 */
function note(message?: string, title?: string): void;

Usage Examples:

import { note } from "@clack/prompts";

// Simple note
note("This will install dependencies and configure your project");

// Note with title
note(
  "Make sure you have Node.js 16+ installed\nSome features require npm 8+",
  "Prerequisites"
);

// Multi-line note
note(`
Installation complete!

Next steps:
1. cd my-project
2. npm start
3. Open http://localhost:3000
`, "Success");

// Title-only note
note("", "Important Notice");

The note function creates a visually distinct bordered box that's perfect for displaying important information, warnings, or instructions during the CLI flow.

Session Flow Patterns

Basic Session

import { intro, outro, text, isCancel, cancel } from "@clack/prompts";

// Start session
intro("My CLI Tool");

// Interactive prompts...
const name = await text({ message: "Project name:" });
if (isCancel(name)) {
  cancel("Setup cancelled");
  process.exit(0);
}

// End session
outro("Setup complete!");

Session with Information

import { intro, note, outro, confirm } from "@clack/prompts";

intro("Database Migration Tool");

note(
  "This will update your database schema\nMake sure you have a backup!",
  "Warning"
);

const proceed = await confirm({
  message: "Continue with migration?",
  initialValue: false,
});

if (proceed) {
  // Perform migration...
  outro("Migration completed successfully");
} else {
  cancel("Migration cancelled");
}

Error Handling Session

import { intro, outro, cancel, text, isCancel } from "@clack/prompts";

intro("Project Generator");

try {
  const projectName = await text({
    message: "Project name:",
    validate: (value) => {
      if (!value) return "Project name is required";
      if (!/^[a-z0-9-]+$/.test(value)) {
        return "Use lowercase letters, numbers, and hyphens only";
      }
    }
  });

  if (isCancel(projectName)) {
    cancel("Generation cancelled");
    process.exit(0);
  }

  // Generate project...
  outro(`Project '${projectName}' created successfully!`);

} catch (error) {
  cancel(`Generation failed: ${error.message}`);
  process.exit(1);
}

Visual Styling

All session management functions use consistent visual styling:

intro: Displays a top border character to mark session start
outro: Shows a bottom border with the message
cancel: Uses red styling to indicate errors/cancellation
note: Creates a bordered box with optional title styling

The visual elements automatically adapt to terminal capabilities (Unicode vs ASCII fallbacks) and integrate seamlessly with the overall @clack/prompts aesthetic.

Best Practices

Always use intro/outro pairs to clearly define session boundaries
Handle cancellation consistently by checking isCancel() after each prompt
Use notes for important information that users need to see before proceeding
Provide clear cancellation messages to help users understand what happened
Exit appropriately with process.exit(0) for cancellation and process.exit(1) for errors