Examples

This guide provides practical examples of using Clack in different scenarios.

Basic Examples

Simple Text Input

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

const name = await text({
  message: 'What is your name?',
  placeholder: 'John Doe',
});

// isCancel is a TypeScript type guard that checks if the result is a symbol
// If true, TypeScript knows name is a symbol in this block
if (isCancel(name)) {
  console.log('Operation cancelled');
  process.exit(0);
}

console.log(`Hello, ${name}!`);

Selection Menu

import { select, isCancel } from '@clack/prompts';

const framework = await select({
  message: 'Choose a framework:',
  options: [
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue' },
    { value: 'svelte', label: 'Svelte' },
  ],
});

if (isCancel(framework)) {
  console.log('Operation cancelled');
  process.exit(0);
}

console.log(`You selected ${framework}`);

Confirmation Dialog

import { confirm } from '@clack/prompts';

const shouldProceed = await confirm({
  message: 'Do you want to continue?',
});

if (shouldProceed) {
  console.log('Proceeding...');
} else {
  console.log('Operation cancelled');
}

Advanced Examples

Project Setup Wizard

import { text, select, confirm, isCancel } from '@clack/prompts';

async function setupProject() {
  // Get project details
  const name = await text({
    message: 'Project name:',
    validate: (value) => {
      if (value.length === 0) return 'Name is required';
      return undefined;
    },
  });

  if (isCancel(name)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  const type = await select({
    message: 'Project type:',
    options: [
      { value: 'web', label: 'Web Application' },
      { value: 'cli', label: 'CLI Tool' },
      { value: 'api', label: 'API Server' },
    ],
  });

  if (isCancel(type)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  // Get additional details based on project type
  let framework;
  if (type === 'web') {
    framework = await select({
      message: 'Choose a framework:',
      options: [
        { value: 'react', label: 'React' },
        { value: 'vue', label: 'Vue' },
        { value: 'svelte', label: 'Svelte' },
      ],
    });

    if (isCancel(framework)) {
      console.log('Operation cancelled');
      process.exit(0);
    }
  }

  // Confirm setup
  const shouldProceed = await confirm({
    message: `Create ${type} project "${name}"${framework ? ` with ${framework}` : ''}?`,
  });

  if (shouldProceed) {
    // Project creation logic here
    console.log('Creating project...');
  }
}

Configuration Setup

import { text, select, confirm, isCancel } from '@clack/prompts';

interface Config {
  port: number;
  host: string | symbol;
  mode: 'development' | 'production';
  features: string[];
}

async function setupConfig(): Promise<Config> {
  const port = await text({
    message: 'Enter port number:',
    defaultValue: '3000',
    validate: (value) => {
      const num = parseInt(value);
      if (isNaN(num)) return 'Please enter a valid number';
      if (num < 1 || num > 65535) return 'Port must be between 1 and 65535';
      return undefined;
    },
  });

  if (isCancel(port)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  const host = await text({
    message: 'Enter host:',
    defaultValue: 'localhost',
  });

  if (isCancel(host)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  const mode = await select({
    message: 'Select mode:',
    options: [
      { value: 'development', label: 'Development' },
      { value: 'production', label: 'Production' },
    ],
  });

  if (isCancel(mode)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  const features = await select({
    message: 'Select features:',
    options: [
      { value: 'auth', label: 'Authentication' },
      { value: 'logging', label: 'Logging' },
      { value: 'metrics', label: 'Metrics' },
    ],
  });

  if (isCancel(features)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  return {
    port: Number(port),
    host,
    mode: mode as 'development' | 'production',
    features: [features],
  };
}

Interactive CLI Tool

import { text, select, confirm as confirmPrompt, isCancel } from '@clack/prompts';

async function cliTool() {
  while (true) {
    const action = await select({
      message: 'What would you like to do?',
      options: [
        { value: 'create', label: 'Create new item' },
        { value: 'list', label: 'List items' },
        { value: 'delete', label: 'Delete item' },
        { value: 'exit', label: 'Exit' },
      ],
    });

    if (isCancel(action)) {
      console.log('Operation cancelled');
      process.exit(0);
    }

    if (action === 'exit') break;

    switch (action) {
      case 'create': {
        const name = await text({
          message: 'Enter item name:',
        });

        if (isCancel(name)) {
          console.log('Operation cancelled');
          break;
        }

        console.log(`Created item: ${name}`);
        break;
      }
      case 'list': {
        console.log('Listing items...');
        break;
      }
      case 'delete': {
        const item = await text({
          message: 'Enter item to delete:',
        });

        if (isCancel(item)) {
          console.log('Operation cancelled');
          break;
        }

        const shouldDelete = await confirmPrompt({
          message: `Delete ${item}?`,
        });

        if (shouldDelete) {
          console.log(`Deleted ${item}`);
        }
        break;
      }
    }
  }
}

Form Validation

import { text, select, isCancel } from '@clack/prompts';

interface UserData {
  name: string;
  email: string;
  age: number;
  role: string;
}

async function collectUserData(): Promise<UserData | null> {
  const name = await text({
    message: 'Full name:',
    validate: (value) => {
      if (value.length < 2) return 'Name must be at least 2 characters';
      if (!/^[a-zA-Z\s]*$/.test(value)) return 'Name can only contain letters and spaces';
      return undefined;
    },
  });

  if (isCancel(name)) {
    console.log('Operation cancelled');
    process.exit(0);
    return null;
  }

  const email = await text({
    message: 'Email address:',
    validate: (value) => {
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      if (!emailRegex.test(value)) return 'Please enter a valid email address';
      return undefined;
    },
  });

  if (isCancel(email)) {
    console.log('Operation cancelled');
    process.exit(0);
    return null;
  }

  const ageInput = await text({
    message: 'Age:',
    validate: (value) => {
      const num = parseInt(value);
      if (isNaN(num)) return 'Please enter a valid number';
      if (num < 18 || num > 100) return 'Age must be between 18 and 100';
      return undefined;
    },
  });

  if (isCancel(ageInput)) {
    console.log('Operation cancelled');
    process.exit(0);
    return null;
  }

  const role = await select({
    message: 'Select role:',
    options: [
      { value: 'admin', label: 'Administrator' },
      { value: 'user', label: 'User' },
      { value: 'guest', label: 'Guest' },
    ],
  });

  if (isCancel(role)) {
    console.log('Operation cancelled');
    process.exit(0);
    return null;
  }

  return {
    name,
    email,
    age: parseInt(ageInput),
    role,
  };
}