Understanding process.argv and the Shebang Line

Welcome to the foundational module of creating your first Command Line Interface (CLI) tool using Node.js. In this lesson, you'll learn how to transform a simple Node.js script into a fully functional CLI application. We'll cover the basics of reading command-line arguments with process.argv, utilizing the shebang line for seamless execution, and understanding CLI conventions.

Getting Started with process.argv

The quickest way to build a working CLI in Node.js is by leveraging the process.argv array. This array contains all the command-line arguments passed to your script. However, it starts with two entries you don't control: the path to the Node.js executable and the path to your script. Therefore, your actual arguments begin at index 2.

Here's a simple example to illustrate:

#!/usr/bin/env node

const args = process.argv.slice(2);
const name = args[0] || 'world';

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

Save this code as cli.js, make it executable with chmod +x cli.js, and run it using node cli.js or directly with ./cli.js. You can pass a name as an argument: ./cli.js vybecoding. Congratulations, you've just created a basic CLI!

The Shebang Line

The shebang line (#!/usr/bin/env node) at the top of your script is crucial. It instructs the shell to use the Node.js interpreter found in your system's PATH, allowing you to execute the script without explicitly typing node. This becomes particularly important when you install your CLI tool globally.

Exploring process.argv

Let's dive deeper into what process.argv contains. Consider the following example:

#!/usr/bin/env node

// Run: ./cli.js build --output dist --verbose
console.log(process.argv);
// Output:
// [
//   '/usr/local/bin/node',
//   '/home/user/projects/scaffold/cli.js',
//   'build',
//   '--output',
//   'dist',
//   '--verbose'
// ]

In this example, process.argv holds the paths to the Node.js executable and the script, followed by the actual arguments: build, --output, dist, and --verbose.

Manual Parsing vs. Libraries

While you can manually parse these arguments for simple use cases, such as a single argument without flags, this approach quickly becomes cumbersome and error-prone as complexity increases. For instance, distinguishing between --dry-run, --output=dist, and positional arguments can be challenging. This is where argument parsing libraries come in handy.

CLI Argument Conventions

Before diving into libraries, it's essential to understand the conventions that most CLI tools follow:

• Positional Arguments: These are arguments that appear in a specific order. For example, in scaffold init my-app, init is a command, and my-app is a positional argument.
• Short Flags: Single-character flags prefixed with a single dash, like -v or -f.
• Long Flags: Full-word flags prefixed with a double dash, such as --verbose or --force.
• Flag Values: Flags can have associated values, either separated by a space (--output dist) or an equals sign (--output=dist). Both forms should be supported.
• Double Dash (--): This signals that everything following it is a positional argument, not a flag.

Conclusion

In this lesson, you've learned how to create a basic CLI tool using Node.js by reading command-line arguments with process.argv and utilizing the shebang line for ease of execution. Understanding CLI conventions is crucial as you move towards more complex tools. In the next lessons, we'll explore argument parsing libraries that simplify handling command-line inputs, allowing you to build robust and user-friendly CLI applications. Keep experimenting and building — the CLI world is at your fingertips!

Parsing Arguments with Commander.js

Creating command-line interfaces (CLI) can be daunting, especially when it comes to parsing command-line arguments. Manually handling process.argv quickly becomes unwieldy as your CLI grows in complexity. Enter commander.js—a robust library that simplifies argument parsing and has become a staple in the developer toolkit, boasting over 100 million weekly downloads. In this lesson, you'll learn how to leverage Commander to build a practical CLI tool for scaffolding new Node.js projects.

Setting Up Your Project

Before diving into coding, let's set up your project environment and install the necessary packages.

Initialize Your Project

First, create a new directory for your project and initialize it with npm:

mkdir scaffold && cd scaffold
npm init -y

Install Commander

Next, install Commander to handle argument parsing:

npm install commander

Configure Your package.json

To ensure your project uses ES modules, update your package.json as follows:

{
  "name": "scaffold",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "scaffold": "./cli.js"
  }
}

Building Your CLI Tool

With the setup complete, it's time to build a functional CLI tool that scaffolds new Node.js projects.

Create the CLI Script

Create a new file named cli.js and start by importing the necessary modules:

#!/usr/bin/env node

import { program } from 'commander';
import { mkdirSync, writeFileSync } from 'fs';
import { join } from 'path';

Define the Command and Options

Utilize Commander to define your CLI's command structure and options:

program
  .name('scaffold')
  .description('Scaffold a new Node.js project')
  .version('1.0.0');

program
  .command('init ')
  .description('Create a new project directory with boilerplate')
  .option('--ts', 'Add TypeScript config')
  .option('--license ', 'Set license type', 'MIT')
  .action((projectName, options) => {
    mkdirSync(projectName, { recursive: true });
    mkdirSync(join(projectName, 'src'), { recursive: true });

    const pkg = {
      name: projectName,
      version: '0.1.0',
      type: 'module',
      main: 'src/index.js',
      license: options.license,
    };

    writeFileSync(
      join(projectName, 'package.json'),
      JSON.stringify(pkg, null, 2)
    );

    writeFileSync(join(projectName, 'src/index.js'), '// Entry point\n');
    writeFileSync(join(projectName, '.gitignore'), 'node_modules\n');

    if (options.ts) {
      const tsConfig = {
        compilerOptions: {
          target: 'ESNext',
          module: 'NodeNext',
          moduleResolution: 'NodeNext',
          strict: true,
          outDir: './dist',
          rootDir: './src',
        },
      };
      writeFileSync(
        join(projectName, 'tsconfig.json'),
        JSON.stringify(tsConfig, null, 2)
      );
    }

    console.log(`Created ${projectName}`);
  });

program.parse();

Understanding Command Options

Commander makes it easy to define and handle various types of command-line options:

• Boolean Flags: These are either present or absent.

.option('--ts', 'Add TypeScript config')

• Flags with Required Values: These require a value when used.

.option('--license ', 'Set license type', 'MIT')

• Flags with Optional Values: These can have an optional value.

.option('--output [dir]', 'Output directory', '.')

Angle brackets () indicate that a value is required, while square brackets ([dir]) mean the value is optional.

Conclusion

By following this guide, you've built a simple yet powerful CLI tool using Commander.js. This tool can scaffold new Node.js projects with optional TypeScript configuration and customizable license types. Commander handles argument parsing, validation, and even generates helpful usage guides automatically. This approach not only saves you time but also ensures your CLI is robust and user-friendly. As you expand your CLI's functionality, Commander will continue to provide a solid foundation for managing complex argument parsing with ease.

Making Your Tool Installable

Creating a command-line tool that only you can run by typing node /home/you/projects/scaffold/cli.js is more of a personal script than a universally accessible tool. To transform it into a command that can be executed from anywhere on your system, you'll need to make a couple of key additions. This lesson will guide you through the process of making your CLI tool installable and usable globally.

Step 1: Define Your Command in package.json

The first step is to ensure your package.json file includes a bin field. This field maps command names to their corresponding script files, allowing you to define one or more commands for your package.

Here's an example configuration:

{
  "name": "scaffold",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "scaffold": "./cli.js"
  },
  "files": [
    "cli.js",
    "src/"
  ]
}

Multiple Commands

If you want to offer multiple commands from a single package, simply extend the bin field:

{
  "bin": {
    "scaffold": "./cli.js",
    "sc": "./cli.js"
  }
}

This setup allows users to run your tool using either scaffold or sc.

Step 2: Link Your Tool for Local Development

To test your CLI tool locally and make it available globally on your system, use the npm link command. This command creates a symbolic link in your global node_modules directory, pointing to your script.

Run the following command in your project directory:

npm link

Now, you can execute your command from any directory. Let's verify that it works:

# Check the version
scaffold --version
# Output: 1.0.0

# Display help information
scaffold --help
# Output:
# Usage: scaffold [options] [command]
#
# Scaffold a new Node.js project
#
# Options:
#   -V, --version   output the version number
#   -h, --help      display help for command
#
# Commands:
#   init [options]   Create a new project directory with boilerplate
#   help [command]                display help for command

# Initialize a new project
scaffold init my-app --ts
# Output: Created my-app

Step 3: Manage Published Files

The files array in your package.json specifies which files should be included when you publish your package to npm. By default, npm includes everything except what's in your .gitignore. However, explicitly listing the files ensures that only the necessary components are included, keeping your package lightweight and efficient.

Step 4: Clean Up After Development

Once you're finished with local development and no longer need the global link, you can remove it using:

npm unlink -g scaffold

This command will clean up the symbolic link, ensuring your global environment remains tidy.

Conclusion

By following these steps, you've transformed your script into a globally accessible command-line tool. This process not only makes your tool more professional but also prepares it for distribution and use by others. Remember, defining your commands in package.json, linking for local development, managing published files, and cleaning up after development are all crucial steps in making your CLI tool installable and user-friendly. Now, you're ready to share your tool with the world!

Adding Interactive Prompts with Inquirer

Creating command-line interfaces (CLIs) that are both intuitive and responsive to user needs is an art. When your application requires user input—whether to select templates, choose licenses, or confirm potentially destructive actions—interactive prompts become essential. This lesson will guide you through leveraging the inquirer package to build dynamic, conversational CLIs that enhance user experience and streamline complex workflows.

Why Use Interactive Prompts?

Not every decision can be predetermined. When your CLI needs to interact with users to gather preferences or confirm actions, static command-line arguments fall short. Interactive prompts offer a flexible and user-friendly way to collect input, making your tool more adaptable and user-centric. The inquirer package provides a robust API to handle various input types, including single inputs, selections, and confirmations, seamlessly.

Setting Up Inquirer

To get started, you need to install the inquirer package. This package will enable you to create interactive prompts within your CLI application.

npm install inquirer

Enhancing Your CLI with Inquirer

Let's enhance a basic CLI tool to include interactive prompts using inquirer. We'll update the init command to guide users through setting up a new Node.js project.

Step-by-Step Implementation

Here's how you can integrate inquirer into your CLI:

#!/usr/bin/env node

import { program } from 'commander';
import inquirer from 'inquirer';
import { mkdirSync, writeFileSync, existsSync } from 'fs';
import { join } from 'path';

program
  .name('scaffold')
  .description('Scaffold a new Node.js project')
  .version('1.0.0');

program
  .command('init ')
  .description('Create a new project directory with boilerplate')
  .option('--ts', 'Add TypeScript config')
  .option('--force', 'Skip confirmation prompts')
  .action(async (projectName, options) => {
    if (existsSync(projectName) && !options.force) {
      const { overwrite } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'overwrite',
          message: `Directory "${projectName}" already exists. Overwrite?`,
          default: false,
        },
      ]);

      if (!overwrite) {
        console.log('Aborted.');
        process.exit(0);
      }
    }

    const { license } = await inquirer.prompt([
      {
        type: 'list',
        name: 'license',
        message: 'Choose a license:',
        choices: ['MIT', 'Apache-2.0', 'ISC', 'None'],
      },
    ]);

    mkdirSync(projectName, { recursive: true });
    mkdirSync(join(projectName, 'src'), { recursive: true });

    const pkg = {
      name: projectName,
      version: '0.1.0',
      type: 'module',
      main: 'src/index.js',
      license: license === 'None' ? 'UNLICENSED' : license,
    };

    writeFileSync(
      join(projectName, 'package.json'),
      JSON.stringify(pkg, null, 2)
    );

    writeFileSync(join(projectName, 'src/index.js'), '// Entry point\n');
    writeFileSync(join(projectName, '.gitignore'), 'node_modules\n');

    if (options.ts) {
      const tsConfig = {
        compilerOptions: {
          target: 'ESNext',
          module: 'NodeNext',
          strict: true,
        },
      };
      writeFileSync(
        join(projectName, 'tsconfig.json'),
        JSON.stringify(tsConfig, null, 2)
      );
    }

    console.log(`\nCreated ${projectName} (${pkg.license})`);
    console.log(`  cd ${projectName} && npm install`);
  });

program.parse();

Key Considerations

• Overwrite Confirmation: Before performing any file operations, especially those that might overwrite existing files, it’s crucial to confirm with the user. This is a best practice to prevent accidental data loss. The --force flag allows experienced users to bypass these confirmations for faster execution.

• Async Action Handlers: The action handler is defined as async to accommodate the await calls for prompts. This change is straightforward with Commander, which natively supports asynchronous handlers.

Conclusion

Incorporating interactive prompts into your CLI not only enhances user interaction but also safeguards against unintended actions. By using inquirer, you can create a more engaging and responsive command-line experience. Remember, a well-designed CLI is both powerful and user-friendly, guiding users through complex tasks with ease and clarity. As you continue to develop your CLI tools, keep user experience at the forefront, leveraging interactive prompts to create intuitive and efficient workflows.

Advanced Prompt Patterns

In this lesson, you'll explore advanced techniques for creating interactive command-line prompts using the Inquirer.js library. By the end, you'll be able to craft sophisticated user input flows that cater to both novice and experienced users, enhancing the flexibility and usability of your CLI applications.

Comprehensive Setup Flow

Inquirer.js offers a variety of prompt types beyond simple yes/no questions and lists. Below is a streamlined configuration flow that demonstrates some of the most commonly used prompt types in a single function:

async function gatherProjectConfig(projectName) {
  const answers = await inquirer.prompt([
    {
      type: 'list',
      name: 'template',
      message: 'Select a project template:',
      choices: [
        { name: 'Minimal (just an entry file)', value: 'minimal' },
        { name: 'API Server (Express + routes)', value: 'api' },
        { name: 'Library (src + tests + build)', value: 'library' },
      ],
    },
    {
      type: 'checkbox',
      name: 'features',
      message: 'Choose additional features:',
      choices: [
        { name: 'TypeScript', value: 'typescript' },
        { name: 'ESLint + Prettier', value: 'linting' },
        { name: 'Jest testing', value: 'testing' },
        { name: 'GitHub Actions CI', value: 'ci' },
        { name: 'Docker support', value: 'docker' },
      ],
    },
    {
      type: 'input',
      name: 'description',
      message: 'Provide a project description:',
      default: `A new ${projectName} project`,
    },
    {
      type: 'input',
      name: 'author',
      message: 'Enter the author name:',
      validate: (input) => input.trim().length > 0 || 'Author name is required',
    },
    {
      type: 'list',
      name: 'license',
      message: 'Select a license:',
      choices: ['MIT', 'Apache-2.0', 'ISC', 'GPL-3.0', 'UNLICENSED'],
      default: 'MIT',
    },
    {
      type: 'confirm',
      name: 'initGit',
      message: 'Initialize a git repository?',
      default: true,
    },
  ]);

  return answers;
}

Key Patterns in Inquirer.js

Validation

Validation ensures that user input meets specific criteria before proceeding. The validate function returns true for valid input or an error message string if the input is invalid. Inquirer will continue to prompt the user until valid input is provided.

Conditional Prompts

Conditional prompts allow you to display certain questions based on previous answers. This is achieved using the when property, which evaluates a condition before deciding whether to show the prompt:

{
  type: 'input',
  name: 'dockerPort',
  message: 'Specify the container port:',
  default: '3000',
  when: (answers) => answers.features.includes('docker'),
}

Transforming Input

The filter property is used to transform or normalize user input before it is stored. This can be useful for ensuring consistent data formats:

{
  type: 'input',
  name: 'packageName',
  message: 'Enter the package name:',
  filter: (input) => input.toLowerCase().replace(/\s+/g, '-'),
}

Balancing Flexibility and Guidance

The combination of command-line flags and interactive prompts provides a professional pattern that caters to both power users and newcomers. Experienced users can quickly pass all necessary parameters via command-line flags (e.g., scaffold init my-app --ts --license MIT --force), while less experienced users benefit from a guided setup process. Both approaches lead to the same end result, ensuring a seamless user experience.

Conclusion

By leveraging advanced prompt patterns in Inquirer.js, you can create dynamic and user-friendly CLI applications. These techniques allow you to validate input, conditionally display prompts, and transform user data, all while maintaining a balance between flexibility and guidance. As you integrate these patterns into your projects, you'll empower users of all skill levels to configure their applications with ease and confidence.

Building a Template System

In this lesson, you'll learn how to build a robust template system that efficiently maps user preferences to project file structures. This system will allow you to quickly scaffold projects based on predefined templates, making it easier to manage and scale your development workflow.

Understanding the Template System

A template system is essentially a blueprint that outlines the structure and dependencies of a project. By defining templates, you can automate the creation of project directories, files, and configuration settings based on user input. This approach streamlines project setup and ensures consistency across different projects.

Let's explore a clean and scalable pattern for implementing a template system in JavaScript:

const templates = {
  minimal: {
    files: {
      'src/index.js': '// Entry point\n',
    },
    directories: ['src'],
  },
  api: {
    files: {
      'src/index.js': `import express from 'express';
import { router } from './routes/index.js';

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());
app.use('/api', router);

app.listen(PORT, () => {
  console.log(\`Server running on port \${PORT}\`);
});
`,
      'src/routes/index.js': `import { Router } from 'express';

export const router = Router();

router.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});
`,
    },
    directories: ['src', 'src/routes', 'src/middleware'],
    dependencies: ['express'],
  },
  library: {
    files: {
      'src/index.js': `export function hello(name = 'world') {
  return \`Hello, \${name}!\`;
}
`,
      'tests/index.test.js': `import { describe, it, expect } from 'vitest';
import { hello } from '../src/index.js';

describe('hello', () => {
  it('returns greeting with name', () => {
    expect(hello('Node')).toBe('Hello, Node!');
  });

  it('defaults to world', () => {
    expect(hello()).toBe('Hello, world!');
  });
});
`,
    },
    directories: ['src', 'tests'],
    devDependencies: ['vitest'],
  },
};

Implementing the Template System

The core function of our template system is createFromTemplate, which takes a project name, a template name, and a configuration object as parameters. This function will generate the necessary project structure based on the selected template.

function createFromTemplate(projectName, templateName, config) {
  const template = templates[templateName];

  // Create directories
  for (const dir of template.directories) {
    mkdirSync(join(projectName, dir), { recursive: true });
  }

  // Write template files
  for (const [filePath, content] of Object.entries(template.files)) {
    writeFileSync(join(projectName, filePath), content);
  }

  // Build package.json
  const pkg = {
    name: projectName,
    version: '0.1.0',
    description: config.description,
    type: 'module',
    main: 'src/index.js',
    author: config.author,
    license: config.license,
    scripts: {},
    dependencies: {},
    devDependencies: {},
  };

  if (templateName === 'api') {
    pkg.scripts.start = 'node src/index.js';
    pkg.scripts.dev = 'node --watch src/index.js';
  }

  if (templateName === 'library') {
    pkg.scripts.test = 'vitest run';
    pkg.scripts['test:watch'] = 'vitest';
  }

  writeFileSync(
    join(projectName, 'package.json'),
    JSON.stringify(pkg, null, 2) + '\n'
  );

  return {
    dependencies: template.dependencies || [],
    devDependencies: template.devDependencies || [],
  };
}

Key Features of the Template System

• Scalability: Adding a new template is as simple as appending an object to the templates map. This modular approach ensures that you don't need to modify the core logic when introducing new templates.
• Flexibility: Each template clearly specifies its required directories, files, and dependencies, allowing for easy customization and extension.
• Automation: By automating the creation of directories and files, the system minimizes manual setup tasks, reducing the potential for errors.

Conclusion

A well-designed template system can significantly enhance your development workflow by providing a consistent and automated way to scaffold projects. By following the pattern outlined in this lesson, you can create a scalable and flexible template system that adapts to your evolving project needs. Remember, the key to a successful template system lies in its simplicity and extensibility, allowing you to focus more on building and less on setup.

Colored Output with Chalk

In the world of command-line interfaces (CLI), functionality is paramount, but user experience is what transforms a tool from merely useful to truly exceptional. This lesson focuses on enhancing the user experience of your CLI applications by incorporating colored output using the chalk package. By the end of this lesson, you'll be able to distinguish between different types of messages—such as errors, warnings, and success notifications—at a glance, making your CLI tools more intuitive and professional.

Why Use Colored Output?

By default, terminal output is monochrome, which can make it challenging to quickly differentiate between various types of messages. Errors can blend in with success messages, and warnings might get lost among informational text. The chalk package provides a straightforward API to add color to your terminal output, making it easier to scan and understand.

Getting Started with Chalk

To begin using chalk, you'll first need to install it in your project. Open your terminal and run the following command:

npm install chalk

Once installed, you can import chalk into your JavaScript files and start adding color to your output.

Basic Color Usage

Here's how you can use chalk to colorize basic messages in your CLI:

import chalk from 'chalk';

// Basic colors for different message types
console.log(chalk.green('Success: Project created'));
console.log(chalk.red('Error: Directory already exists'));
console.log(chalk.yellow('Warning: No .gitignore found'));
console.log(chalk.cyan('Info: Installing dependencies...'));

Enhancing Text with Styles

chalk also allows you to apply styles such as bold, dim, and underline to your text, enhancing readability and emphasis:

// Applying styles to text
console.log(chalk.bold.green('BUILD PASSED'));
console.log(chalk.dim('(this step is optional)'));
console.log(chalk.underline('https://docs.example.com'));

Combining Colors and Styles

You can combine multiple styles and colors to create more impactful messages:

// Combining styles and colors
console.log(chalk.bgRed.white.bold(' ERROR ') + ' Something went wrong');

Using Template Literals with Chalk

Template literals work seamlessly with chalk, allowing you to embed styled text within strings:

const projectName = 'my-app';
console.log(`Created ${chalk.bold(projectName)} in ${chalk.dim('0.3s')}`);

Building a Consistent Logger Utility

To maintain consistency in your CLI's output, consider building a small logger utility that standardizes color usage across your application:

// src/logger.js
import chalk from 'chalk';

export const log = {
  info: (msg) => console.log(chalk.cyan('info') + '  ' + msg),
  success: (msg) => console.log(chalk.green('done') + '  ' + msg),
  warn: (msg) => console.log(chalk.yellow('warn') + '  ' + msg),
  error: (msg) => console.error(chalk.red('error') + ' ' + msg),
  step: (num, total, msg) =>
    console.log(chalk.dim(`[${num}/${total}]`) + ' ' + msg),
};

// Usage examples
log.step(1, 4, 'Creating directory structure');
log.step(2, 4, 'Writing package.json');
log.step(3, 4, 'Initializing git repository');
log.step(4, 4, 'Installing dependencies');
log.success(`Project ${chalk.bold('my-app')} is ready`);

Sample Output

When you run the logger utility, you'll see output like this:

[1/4] Creating directory structure
[2/4] Writing package.json
[3/4] Initializing git repository
[4/4] Installing dependencies
done  Project my-app is ready

Best Practices for Using Color

While color can significantly enhance the user experience, it's important to use it wisely:

• Avoid Sole Reliance on Color: Never use color as the only means of conveying information. Some users may have color-blind terminals or might pipe output to files, which strips ANSI codes. Always pair color with descriptive text, such as "Error:" instead of relying solely on red text.

Conclusion

Incorporating colored output into your CLI tools with chalk not only improves readability but also enhances the overall user experience. By following best practices and using a consistent approach to color usage, you can create professional and user-friendly command-line applications. Remember, the goal is to make your tools not just work, but feel great to use.

Spinners and Progress Indicators with Ora

In the world of command-line tools, user experience often hinges on providing clear feedback during operations. When your application performs tasks like installing dependencies, making HTTP requests, or processing files, users need to know that something is happening. A silent terminal can feel unresponsive or broken. Enter ora, a powerful package that offers elegant loading spinners to enhance user feedback.

Getting Started with Ora

To integrate ora into your project, start by installing the package:

npm install ora

Implementing Spinners for Asynchronous Tasks

Let's explore how to use ora to provide feedback during asynchronous operations, such as installing dependencies or initializing a Git repository.

Installing Dependencies with Feedback

When installing dependencies, it's crucial to inform users about the ongoing process. Here's how you can achieve this using ora:

import ora from 'ora';
import { execSync } from 'child_process';

async function installDependencies(projectDir, deps) {
  if (deps.length === 0) return;

  const spinner = ora({
    text: `Installing ${deps.join(', ')}`,
    color: 'cyan',
  }).start();

  try {
    execSync(`npm install ${deps.join(' ')}`, {
      cwd: projectDir,
      stdio: 'pipe', // Suppress npm output
    });
    spinner.succeed(`Installed ${deps.length} dependencies`);
  } catch (error) {
    spinner.fail('Failed to install dependencies');
    throw error;
  }
}

Initializing a Git Repository

Similarly, you can use ora to provide feedback when setting up a Git repository:

async function initGitRepo(projectDir) {
  const spinner = ora('Initializing git repository').start();

  try {
    execSync('git init', { cwd: projectDir, stdio: 'pipe' });
    execSync('git add -A', { cwd: projectDir, stdio: 'pipe' });
    execSync('git commit -m "Initial commit"', {
      cwd: projectDir,
      stdio: 'pipe',
    });
    spinner.succeed('Git repository initialized');
  } catch (error) {
    spinner.warn('Git init failed (git may not be installed)');
    // Non-fatal -- continue without git
  }
}

Understanding Spinner Methods

The ora package provides several methods to update the spinner's status:

• spinner.succeed(): Replaces the spinner with a success symbol and message.
• spinner.fail(): Replaces the spinner with a failure symbol and message.
• spinner.warn(): Replaces the spinner with a warning symbol and message.

These methods help create a clean, readable log of the operations performed:

✔ Created directory structure
✔ Installed 3 dependencies
✔ Git repository initialized
⚠ ESLint config skipped (no config template)

Updating Spinner Text for Progress

For operations where progress can be measured, dynamically update the spinner text to reflect the current state:

const spinner = ora('Processing files').start();

const files = getFilesToProcess();
for (let i = 0; i < files.length; i++) {
  spinner.text = `Processing file ${i + 1}/${files.length}: ${files[i]}`;
  await processFile(files[i]);
}

spinner.succeed(`Processed ${files.length} files`);

Best Practices for Using Ora

When running child processes while a spinner is active, set stdio: 'pipe'. This prevents the child process output from interleaving with the spinner animation, which can otherwise result in garbled text.

Conclusion

Incorporating ora into your command-line tools significantly enhances user experience by providing clear, real-time feedback during operations. By using spinners effectively, you can keep users informed and engaged, transforming potentially confusing silent periods into transparent, interactive experiences. As you integrate ora into your projects, remember to handle errors gracefully and update spinner text dynamically to reflect progress accurately.

Graceful Error Handling

When developing command-line interfaces (CLI), providing users with clear and actionable error messages is crucial for a positive user experience. Raw stack traces are invaluable for developers but can be confusing for end users. This lesson will guide you through implementing a structured error handling pattern in your CLI applications, ensuring users understand what went wrong and how to resolve it.

Implementing Structured Error Handling

To manage errors gracefully, we will define a custom error class and a handler function. This approach allows us to categorize errors and provide specific guidance to users.

// src/errors.js
import chalk from 'chalk';

export class CLIError extends Error {
  constructor(message, { code, suggestion } = {}) {
    super(message);
    this.name = 'CLIError';
    this.code = code || 'UNKNOWN_ERROR';
    this.suggestion = suggestion;
  }
}

export function handleError(error) {
  if (error instanceof CLIError) {
    console.error('\n' + chalk.red.bold('Error: ') + error.message);
    if (error.suggestion) {
      console.error(chalk.dim('  Suggestion: ') + error.suggestion);
    }
    process.exit(1);
  }

  // Handle specific Node.js errors
  if (error.code === 'EACCES') {
    console.error('\n' + chalk.red.bold('Permission denied: ') + error.path);
    console.error(chalk.dim('  Try running with appropriate permissions or choose a different directory.'));
    process.exit(1);
  }

  if (error.code === 'ENOSPC') {
    console.error('\n' + chalk.red.bold('No space left on device.'));
    console.error(chalk.dim('  Free up disk space and try again.'));
    process.exit(1);
  }

  // Handle unexpected errors by showing a stack trace
  console.error('\n' + chalk.red.bold('Unexpected error:'));
  console.error(error.stack || error.message);
  console.error(chalk.dim('\n  This is a bug. Please report it at:'));
  console.error(chalk.dim('  https://github.com/yourname/scaffold/issues'));
  process.exit(1);
}

Integrating Error Handling in Commands

Incorporate the error handling mechanism into your CLI commands to ensure consistent error reporting.

import { CLIError, handleError } from './src/errors.js';

program
  .command('init ')
  .action(async (projectName) => {
    try {
      // Validate project name
      if (!/^[a-z0-9-_]+$/.test(projectName)) {
        throw new CLIError(`Invalid project name: "${projectName}"`, {
          code: 'INVALID_NAME',
          suggestion: 'Use only lowercase letters, numbers, hyphens, and underscores.',
        });
      }

      // Check write permissions
      if (existsSync(projectName) && !options.force) {
        throw new CLIError(`Directory "${projectName}" already exists.`, {
          code: 'DIR_EXISTS',
          suggestion: 'Use --force to overwrite or choose a different name.',
        });
      }

      await createProject(projectName);
    } catch (error) {
      handleError(error);
    }
  });

Handling Global Errors

To ensure robustness, handle unhandled rejections and uncaught exceptions at the top level of your CLI application. This prevents the application from crashing unexpectedly and provides users with a graceful exit.

// cli.js -- at the top, before any other code
process.on('uncaughtException', (error) => {
  handleError(error);
});

process.on('unhandledRejection', (reason) => {
  handleError(reason instanceof Error ? reason : new Error(String(reason)));
});

// Handle Ctrl+C gracefully
process.on('SIGINT', () => {
  console.log('\n' + chalk.dim('Interrupted. Cleaning up...'));
  // Clean up temporary files if needed
  process.exit(130); // Standard exit code for SIGINT
});

Understanding Exit Codes

Exit codes are a vital part of CLI applications, signaling the outcome of a command to other tools and scripts. Here are some standard exit codes:

• 0: Success
• 1: General error
• 2: Misuse of command
• 130: Interrupted by Ctrl+C

Using the correct exit codes helps maintain interoperability with other systems and provides clarity on the command's result.

Conclusion

Implementing structured error handling in your CLI applications enhances user experience by providing clear, actionable feedback. By defining custom error classes, handling specific Node.js errors, and managing global exceptions, you ensure your application is robust and user-friendly. Remember to use appropriate exit codes to communicate the status of your commands effectively. With these practices, you empower users to resolve issues independently, fostering a more intuitive interaction with your CLI tools.

Unit Testing CLI Logic

In the world of software development, a command-line interface (CLI) without tests is a ticking time bomb. Changes become daunting, and confidence in your tool diminishes. This lesson will guide you through the process of writing automated tests for your CLI applications. You'll learn how to test individual functions and execute your CLI as a subprocess to verify its output, ensuring your CLI is robust and maintainable.

The Foundation of Testable CLIs

The cornerstone of a testable CLI is the separation of logic from input/output operations. By isolating your business logic into functions that can be independently tested, you avoid embedding complex logic directly within your command handlers. This separation not only enhances testability but also promotes cleaner, more maintainable code.

Setting Up Your Testing Environment

To get started with testing, you'll need a test runner. We'll use Vitest, a fast and lightweight testing framework for JavaScript.

Install Vitest as a development dependency:

npm install --save-dev vitest

Next, add test scripts to your package.json file to facilitate running your tests:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

Extracting Core Logic

Begin by extracting your CLI's core logic into functions that can be easily tested. Here's an example of how you might structure your project logic:

// src/project.js
import { mkdirSync, writeFileSync, existsSync } from 'fs';
import { join } from 'path';

export function validateProjectName(name) {
  if (!name || name.trim().length === 0) {
    return { valid: false, reason: 'Project name cannot be empty' };
  }
  if (!/^[a-z0-9][a-z0-9-_]*$/.test(name)) {
    return {
      valid: false,
      reason: 'Name must start with a letter or number and contain only lowercase letters, numbers, hyphens, and underscores',
    };
  }
  if (name.length > 214) {
    return {
      valid: false,
      reason: 'Name must be 214 characters or fewer (npm limit)',
    };
  }
  return { valid: true };
}

export function buildPackageJson(projectName, config = {}) {
  return {
    name: projectName,
    version: config.version || '0.1.0',
    description: config.description || '',
    type: 'module',
    main: 'src/index.js',
    scripts: config.scripts || {},
    author: config.author || '',
    license: config.license || 'MIT',
  };
}

export function createProject(projectName, config = {}) {
  if (existsSync(projectName) && !config.force) {
    throw new Error(`Directory "${projectName}" already exists`);
  }

  mkdirSync(projectName, { recursive: true });
  mkdirSync(join(projectName, 'src'), { recursive: true });

  const pkg = buildPackageJson(projectName, config);
  writeFileSync(
    join(projectName, 'package.json'),
    JSON.stringify(pkg, null, 2) + '\n'
  );
  writeFileSync(join(projectName, 'src/index.js'), '// Entry point\n');
  writeFileSync(join(projectName, '.gitignore'), 'node_modules\n');

  return { projectDir: projectName, packageJson: pkg };
}

Writing Tests for Your Functions

With your core logic extracted, you can now write tests to ensure each function behaves as expected. Here's how you can test the functions in your project:

// tests/project.test.js
import { describe, it, expect } from 'vitest';
import { rmSync, existsSync, readFileSync } from 'fs';
import { validateProjectName, buildPackageJson, createProject } from '../src/project.js';

describe('validateProjectName', () => {
  it('accepts valid names', () => {
    expect(validateProjectName('my-app').valid).toBe(true);
    expect(validateProjectName('app123').valid).toBe(true);
    expect(validateProjectName('my_tool').valid).toBe(true);
  });

  it('rejects empty names', () => {
    const result = validateProjectName('');
    expect(result.valid).toBe(false);
    expect(result.reason).toContain('empty');
  });

  it('rejects names with uppercase letters', () => {
    const result = validateProjectName('MyApp');
    expect(result.valid).toBe(false);
  });

  it('rejects names starting with a hyphen', () => {
    const result = validateProjectName('-my-app');
    expect(result.valid).toBe(false);
  });

  it('rejects names with spaces', () => {
    const result = validateProjectName('my app');
    expect(result.valid).toBe(false);
  });
});

describe('buildPackageJson', () => {
  it('creates valid package.json structure', () => {
    const pkg = buildPackageJson('test-app');
    expect(pkg.name).toBe('test-app');
    expect(pkg.version).toBe('0.1.0');
    expect(pkg.type).toBe('module');
    expect(pkg.license).toBe('MIT');
  });

  it('applies custom config', () => {
    const pkg = buildPackageJson('test-app', {
      version: '1.0.0',
      license: 'Apache-2.0',
      author: 'Test User',
    });
    expect(pkg.version).toBe('1.0.0');
    expect(pkg.license).toBe('Apache-2.0');
    expect(pkg.author).toBe('Test User');
  });
});

Conclusion

By following this guide, you've learned how to effectively unit test your CLI logic. Separating logic from I/O, extracting testable functions, and writing comprehensive tests are key practices that will make your CLI application more reliable and easier to maintain. As you continue to develop your CLI tools, remember that robust testing is not just a safety net—it's a catalyst for innovation, allowing you to iterate and improve with confidence. Keep testing and happy coding!

Integration Testing: Running the CLI as a Subprocess

In the world of software development, unit tests are crucial for verifying the functionality of individual components. However, to ensure your Command Line Interface (CLI) application operates seamlessly from end to end, integration testing becomes essential. This involves checking that your CLI correctly parses arguments, produces the expected output, and returns the appropriate exit codes. In this lesson, we'll explore how to leverage the child_process module to run your CLI as a subprocess and validate its behavior.

Setting Up Your Integration Tests

To begin, you'll need to set up a test suite that can execute your CLI commands and inspect their results. We'll use the vitest testing framework along with Node.js's child_process module to achieve this.

// tests/cli.test.js
import { describe, it, expect, afterEach } from 'vitest';
import { execFileSync } from 'child_process';
import { existsSync, rmSync, readFileSync } from 'fs';
import { resolve } from 'path';

const CLI_PATH = resolve('./cli.js');
const TEST_DIR = 'test-cli-integration';

function runCLI(args, options = {}) {
  try {
    const stdout = execFileSync('node', [CLI_PATH, ...args], {
      encoding: 'utf-8',
      timeout: 30000,
      ...options,
    });
    return { stdout, exitCode: 0 };
  } catch (error) {
    return {
      stdout: error.stdout || '',
      stderr: error.stderr || '',
      exitCode: error.status,
    };
  }
}

Cleaning Up After Tests

To ensure a clean slate for each test, we'll remove any test directories created during the process.

afterEach(() => {
  if (existsSync(TEST_DIR)) {
    rmSync(TEST_DIR, { recursive: true, force: true });
  }
});

Writing Integration Tests

Verifying CLI Output

Start by testing basic commands like --version and --help to ensure they produce the expected output.

describe('CLI integration', () => {
  it('displays version', () => {
    const { stdout } = runCLI(['--version']);
    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
  });

  it('displays help', () => {
    const { stdout } = runCLI(['--help']);
    expect(stdout).toContain('scaffold');
    expect(stdout).toContain('Scaffold a new Node.js project');
    expect(stdout).toContain('init');
  });

  it('displays command-specific help', () => {
    const { stdout } = runCLI(['init', '--help']);
    expect(stdout).toContain('projectName');
    expect(stdout).toContain('--ts');
  });
});

Handling Invalid Commands

Test scenarios where the user provides no command or an unknown command to ensure your CLI handles errors gracefully.

it('fails with no command', () => {
  const { stdout } = runCLI([]);
  expect(stdout).toContain('Usage');
});

it('fails with unknown command', () => {
  const result = runCLI(['unknown']);
  expect(result.exitCode).not.toBe(0);
});

Testing Command Execution

For commands that perform actions, such as creating a project, verify both the exit code and the side effects (e.g., files created).

it('creates project with init command', () => {
  const { stdout, exitCode } = runCLI([
    'init', TEST_DIR, '--force', '--license', 'MIT',
  ]);
  expect(exitCode).toBe(0);
  expect(existsSync(TEST_DIR)).toBe(true);

  const pkg = JSON.parse(
    readFileSync(`${TEST_DIR}/package.json`, 'utf-8')
  );
  expect(pkg.name).toBe(TEST_DIR);
});

Best Practices for CLI Integration Testing

Set a Timeout

Always set a timeout for your tests. This prevents them from hanging indefinitely due to unexpected input prompts or logic errors.

Implement Non-Interactive Mode

To facilitate testing, consider adding a --no-interactive or --ci flag to bypass prompts and use default values. This is a common practice in many real-world CLIs.

program
  .command('init ')
  .option('--no-interactive', 'Skip prompts, use defaults')
  .action(async (projectName, options) => {
    let config;
    if (options.interactive === false) {
      config = { license: 'MIT', template: 'minimal' };
    } else {
      config = await gatherProjectConfig(projectName);
    }
    // ...
  });

Verify Exit Codes

In addition to checking output, always verify exit codes. A command that prints an error but exits with code 0 can silently pass in CI pipelines, leading to undetected failures.

Conclusion

Integration testing your CLI ensures that it functions correctly as a cohesive unit, providing confidence that your application will perform as expected in production environments. By running your CLI as a subprocess and validating its behavior, you can catch issues early and maintain a robust, reliable tool. Remember to set timeouts, implement non-interactive modes, and verify exit codes to enhance the effectiveness of your tests. Happy testing!

Preparing Your Package for Publication

Congratulations! You've developed and tested a robust CLI tool. Now, it's time to share your creation with the world by publishing it to npm. This will allow users to install your tool effortlessly with a single command: npm install -g scaffold. In this lesson, we'll guide you through the essential steps to prepare your package for publication and manage its releases effectively.

Configuring Your package.json

Before you can publish your package, it's crucial to ensure that your package.json file is properly configured. This file contains metadata that npm uses for package discovery and documentation. Here's a sample configuration:

{
  "name": "@yourname/scaffold",
  "version": "1.0.0",
  "description": "Scaffold new Node.js projects with configurable templates",
  "type": "module",
  "main": "src/index.js",
  "bin": {
    "scaffold": "./cli.js"
  },
  "files": [
    "cli.js",
    "src/"
  ],
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "prepublishOnly": "npm test"
  },
  "keywords": [
    "cli",
    "scaffold",
    "generator",
    "nodejs",
    "project-generator",
    "boilerplate"
  ],
  "author": "Your Name ",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/scaffold.git"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Key Fields Explained

• name: Choose a unique name for your package. If the name you want is already taken, consider using a scoped name like @yourname/scaffold. Scoped packages help avoid naming conflicts and are free to use.

• files: This field specifies which files should be included in the published package. By default, npm includes everything not in .gitignore. Be explicit about what you include to avoid unnecessary files like tests or documentation.

• engines: Specify the minimum Node.js version your package supports. This helps users avoid compatibility issues. npm will warn users if they try to install your package on an incompatible Node.js version.

• prepublishOnly: This script runs before every npm publish command. Use it to run your tests and ensure that you never publish broken code.

Verifying Your Package Contents

Before you publish, it's important to verify what will actually be included in your package. Use the following command to simulate the packaging process:

npm pack --dry-run

This command lists every file that would be included in the tarball. Review this list carefully to avoid common pitfalls, such as:

• Accidentally including .env files with sensitive information
• Including node_modules, which should be ignored
• Including large test fixtures or unnecessary assets
• Forgetting to include essential source files

Fine-Tuning with .npmignore

If you need more control over which files are excluded from your package, create a .npmignore file. This file works similarly to .gitignore but specifically for npm:

# .npmignore
tests/
coverage/
.github/
*.test.js
.env*

Conclusion

Publishing your package to npm is a rewarding step in sharing your work with the developer community. By carefully preparing your package.json and verifying your package contents, you ensure a smooth publishing process. Remember to use .npmignore for fine-grained control over your package's contents. With these practices, you'll deliver a polished, professional package that users can rely on.

Now, you're ready to publish your package and make your CLI tool available to developers worldwide. Happy coding!

Publishing and Version Management

Welcome to the world of npm publishing! In this guide, you'll learn how to publish your package to npm and manage its versions effectively. By the end of this lesson, you'll be equipped to share your code with the world and maintain it with confidence.

Setting Up Your npm Account

Before you can publish a package, you need an npm account. If you haven't created one yet, follow these steps:

npm adduser

This command will prompt you to enter your username, password, and email address. Once you've successfully logged in, you can verify your login status with:

npm whoami

This will display your npm username, confirming that you're ready to publish.

Preparing to Publish

Before making your package live, it's wise to perform a dry run. This simulates the publish process without actually uploading your package, allowing you to catch any potential issues:

npm publish --dry-run

Review the output carefully. If everything appears correct, you're ready to proceed with the actual publishing.

Publishing Your Package

To publish your package, use the following command. Note that if you're publishing a scoped package for the first time, you'll need to set it as public:

npm publish --access public

Congratulations! Your package is now live on npm, and anyone can install it using:

npm install -g @yourname/scaffold

Managing Versions with Semantic Versioning

As you continue to develop your package, you'll need to release updates. Adhering to semantic versioning ensures that users understand the nature of changes in each release. Here's how to manage different types of updates:

Bug Fixes

For small patches and bug fixes that don't affect the API, increment the patch version:

npm version patch

New Features

For new features that are backward compatible, increment the minor version:

npm version minor

Breaking Changes

For changes that break backward compatibility, increment the major version:

npm version major

The npm version command updates your package.json, creates a git commit, and tags the commit with the new version number.

Finalizing the Release

After updating the version, push your changes to your git repository and publish the new version:

git push && git push --tags
npm publish

Automating Releases

To streamline your release process, consider adding scripts to your package.json. This automation reduces the risk of human error and speeds up your workflow:

{
  "scripts": {
    "release:patch": "npm version patch && git push && git push --tags && npm publish",
    "release:minor": "npm version minor && git push && git push --tags && npm publish",
    "release:major": "npm version major && git push && git push --tags && npm publish"
  }
}

With these scripts, you can release updates with a single command, ensuring consistency and efficiency.

Conclusion

Publishing and version management are crucial skills for any developer looking to share their work with the community. By following these steps, you can confidently publish your npm packages and manage their versions using best practices. Happy coding and happy publishing!

Post-Publication: Maintenance and Best Practices

Publishing your package to npm is just the beginning. To ensure your package remains useful and relevant, you need to adopt maintenance practices that distinguish well-maintained packages from those that are abandoned. This guide will walk you through essential post-publication practices to keep your npm package in top shape.

Crafting an Effective README for npm

Your README file is the first point of contact for users visiting your package page on npm. A well-structured README not only informs but also engages potential users. Here’s what to include:

# @yourname/scaffold

Scaffold new Node.js projects with configurable templates.

## Install

bash

npm install -g @yourname/scaffold

## Usage

bash

scaffold init my-app

scaffold init my-app --ts --license Apache-2.0

## Features

- Multiple project templates (minimal, API, library)
- TypeScript support
- Interactive setup wizard
- Git initialization
- License selection

Key Components of a README

• Installation Instructions: Provide a clear and concise command to install your package.
• Usage Examples: Demonstrate how to use your package with practical examples.
• Feature List: Highlight key features to showcase what your package offers.

Deprecating Old Versions

As your package evolves, you might need to deprecate older versions to encourage users to upgrade. Use the following command to deprecate versions:

npm deprecate @yourname/scaffold@"< 1.0.0" "Please upgrade to 1.x"

Deprecation messages guide users to the latest and most secure versions of your package.

Monitoring Compatibility and Dependencies

To ensure your package works seamlessly across different environments, consider the following:

• Engines Field: Specify compatible Node.js versions in your package.json to warn users on incompatible versions.
• Peer Dependencies: Declare any globally required tools your package depends on.

Maintaining a Changelog

A detailed changelog is invaluable for users to track changes and decide when to upgrade. Create a CHANGELOG.md file and update it with every release:

# Changelog

## 1.1.0 (2026-03-22)
- Added: API server template
- Added: Docker support option
- Fixed: Incorrect .gitignore contents

## 1.0.0 (2026-03-15)
- Initial release
- Minimal and library templates
- TypeScript support
- Interactive setup wizard

Benefits of a Changelog

• Transparency: Users can easily see what's new or changed.
• Upgrade Guidance: Helps users understand the impact of upgrading.

Testing Before Every Release

Before releasing a new version, thorough testing is crucial. Utilize the prepublishOnly script, but also manually test the packaged version:

# Pack locally and test the tarball
npm pack
npm install -g ./yourname-scaffold-1.0.0.tgz
scaffold init test-project
# Verify functionality
npm uninstall -g @yourname/scaffold

Why Test the Packaged Version?

Testing the packaged version ensures that your tool functions correctly outside the development environment, where only production dependencies are available. This step prevents users from encountering issues post-installation.

Where to Go Next

With your CLI tool polished and published, consider exploring these advanced topics to further enhance your package:

Node.js child_process Module

Unlock the full potential of your CLI by orchestrating other commands. The child_process module in Node.js provides execSync and spawnSync for running shell commands like git init or npm install. Familiarize yourself with the Node.js documentation to understand the nuances of exec vs spawn.

Configuration Management

Tools like ESLint and Prettier utilize configuration files for customization. The cosmiconfig package allows your CLI to read configurations from various sources like package.json, .scaffoldrc, or environment variables without additional code.

Implementing Plugin Systems

As your tool gains popularity, users may want to extend its functionality. Study how Babel, ESLint, and Vite handle plugins. A simple pattern involves plugins exporting a function that modifies your tool's context.

Distributing as a Standalone Binary

To distribute your tool as a single executable, consider using pkg by Vercel or Bun's --compile flag. These tools bundle your script and dependencies into a standalone binary for macOS, Linux, and Windows, making it accessible without requiring Node.js.

Automating with GitHub Actions

Streamline your development workflow with GitHub Actions for continuous integration and deployment. Automate testing on every push and publish to npm automatically upon creating a GitHub release. Ensure you configure an NPM_TOKEN secret in your repository settings for the npm publish action.

Conclusion

Maintaining a successful npm package requires ongoing effort and attention to detail. By following these best practices, you can ensure your package remains robust, user-friendly, and relevant. Engage with your users, stay informed about new tools and techniques, and continue to refine your package for long-term success.