# Build a CLI Tool with Node.js That Solves a Real Problem ## Course Overview & Learning Outcomes Every time you set up a new project, you type the same sequence of commands: create the folder, initialize npm, create the entry file, add a `.gitignore`, maybe stub out a config file. Five minutes of mechanical work, over and over. If you have caught yourself writing a cheat sheet just to remember your own setup ritual, that is a signal -- you should be running one command instead. Node.js has everything you need to build that command. No framework required. The standard library and a handful of npm packages are enough to go from "I type this constantly" to "I have a tool that does it for me." By the end of this guide, you will be able to: 1. Build a fully functional CLI tool from scratch using Node.js 2. Parse arguments and flags with Commander.js for a professional interface 3. Add interactive prompts, colored output, spinners, and progress bars 4. Handle errors gracefully so users never see a raw stack trace 5. Write automated tests that verify your CLI works correctly 6. Publish your tool to npm so anyone can install and use it **Prerequisites**: Basic JavaScript knowledge, Node.js installed (v18+), familiarity with the terminal. **What we are building**: A project scaffolding tool called `scaffold` that creates new Node.js projects with configurable templates, license selection, and optional TypeScript support. By the final module, you will have a published, tested, production-quality CLI. --- ## Module 1: Foundations -- Your First CLI This module covers the fundamentals of how CLI tools work in Node.js. You will go from a single-file script to a properly structured command with argument parsing, help text, and installability. ### Lesson: Understanding process.argv and the Shebang Line The fastest path to a working CLI is a single file that reads `process.argv`. That array always starts with two entries you do not control -- the path to `node` and the path to your script -- so your actual arguments begin at index 2. ```js #!/usr/bin/env node const args = process.argv.slice(2); const name = args[0] || 'world'; console.log(`Hello, ${name}!`); ``` Save this as `cli.js`, run `chmod +x cli.js`, and execute it with `node cli.js` or `./cli.js`. Pass a name: `./cli.js vybecoding`. That is it -- you have a CLI. The shebang line (`#!/usr/bin/env node`) tells your shell to use whatever `node` binary is on the PATH, so the script runs directly without prefixing `node` every time. It matters when you install the tool globally later. Let us look at what `process.argv` actually contains: ```js #!/usr/bin/env node // Run: ./cli.js build --output dist --verbose console.log(process.argv); // [ // '/usr/local/bin/node', // '/home/user/projects/scaffold/cli.js', // 'build', // '--output', // 'dist', // '--verbose' // ] ``` You could parse this manually, and for a tool with exactly one argument and no flags, that is fine. But the moment you need to distinguish `--dry-run` from `--output=dist` from positional arguments, manual parsing becomes brittle. That is where argument parsing libraries come in. Before moving to a library, understand the conventions that every CLI follows: - **Positional arguments**: `scaffold init my-app` -- `init` is a command, `my-app` is a positional arg - **Short flags**: `-v`, `-f` -- single dash, single letter - **Long flags**: `--verbose`, `--force` -- double dash, full word - **Flag values**: `--output dist` or `--output=dist` -- both forms should work - **Double dash**: `--` signals "everything after this is a positional argument, not a flag" ### Lesson: Parsing Arguments with Commander.js Parsing `process.argv` manually falls apart the moment you add flags. The `commander` package handles this cleanly and has been the standard choice for years with over 100 million weekly downloads. Start by initializing your project and installing Commander: ```bash mkdir scaffold && cd scaffold npm init -y npm install commander ``` Update your `package.json` to use ES modules: ```json { "name": "scaffold", "version": "1.0.0", "type": "module", "bin": { "scaffold": "./cli.js" } } ``` Now build the real tool: ```js #!/usr/bin/env node import { program } from 'commander'; import { mkdirSync, writeFileSync } 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('--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(); ``` This is where the tool becomes genuinely useful. The `init` command accepts a project name as a required positional argument and optional flags. Commander handles the parsing, validates that the required argument is present, and wires `--help` automatically. Running `scaffold --help` or `scaffold init --help` gives your users a usage guide you did not have to write. Notice the `--license ` option with a default value of `'MIT'`. Commander supports three flag patterns: ```js // Boolean flag -- present or absent .option('--ts', 'Add TypeScript config') // Flag with required value .option('--license ', 'Set license type', 'MIT') // Flag with optional value .option('--output [dir]', 'Output directory', '.') ``` The angle brackets mean the value is required if the flag is used. Square brackets mean it is optional. ### Lesson: Making Your Tool Installable A tool only you can run by typing `node /home/you/projects/scaffold/cli.js` is not really a tool -- it is a script with extra steps. Two additions turn it into a proper command available anywhere on your system. First, make sure your `package.json` has a `bin` field: ```json { "name": "scaffold", "version": "1.0.0", "type": "module", "bin": { "scaffold": "./cli.js" }, "files": [ "cli.js", "src/" ] } ``` The `bin` field maps command names to scripts. You can have multiple commands from one package: ```json { "bin": { "scaffold": "./cli.js", "sc": "./cli.js" } } ``` Now link it for local development: ```bash npm link ``` npm creates a symlink in your global bin folder pointing to your script, so `scaffold init my-app` works from any directory. Test it: ```bash # From any directory scaffold --version # 1.0.0 scaffold --help # 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 scaffold init my-app --ts # Created my-app ``` The `files` array in `package.json` controls what gets included when you eventually publish to npm. Without it, npm includes everything except what is in `.gitignore`. Being explicit keeps your package small -- users do not need your test files or documentation to run the tool. When you are done developing and want to clean up the global link: ```bash npm unlink -g scaffold ``` --- ## Module 2: Interactive Prompts and User Input Not every input belongs on the command line. When your tool needs to ask questions, gather preferences, or confirm destructive operations, interactive prompts are the right interface. This module covers how to build conversational CLIs that guide users through complex workflows. ### Lesson: Adding Interactive Prompts with Inquirer Some tools need to ask questions. When you do not know in advance what the user wants -- which template to use, what license to apply, whether to overwrite an existing directory -- prompts are the right interface. The `inquirer` package gives you a clean API for single inputs, selections, and confirmations. Install it: ```bash npm install inquirer ``` Now update your `init` command to use prompts: ```js #!/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(); ``` The overwrite check before doing any file operations is worth paying attention to. Destructive operations -- overwriting files, deleting directories, making network requests -- should always confirm with the user unless a `--force` flag is explicitly set. This is the pattern professional CLIs follow: fast when the user knows what they want, careful when there is risk of data loss. The action handler is now `async`, which is required the moment you `await` a prompt. Commander supports async action handlers transparently, so this is a one-word change with no other setup. ### Lesson: Advanced Prompt Patterns Inquirer supports far more than yes/no questions and lists. Here are the prompt types you will use most often, combined into a single setup flow: ```js async function gatherProjectConfig(projectName) { const answers = await inquirer.prompt([ { type: 'list', name: 'template', message: '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: '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: 'Project description:', default: `A new ${projectName} project`, }, { type: 'input', name: 'author', message: 'Author:', validate: (input) => { if (input.trim().length === 0) { return 'Author name is required'; } return true; }, }, { type: 'list', name: 'license', message: '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 to notice: **Validation**: The `validate` function returns `true` for valid input or an error message string. Inquirer will re-prompt until the user provides valid input. **Conditional prompts**: Use the `when` property to show prompts only when previous answers meet certain conditions: ```js { type: 'input', name: 'dockerPort', message: 'Container port:', default: '3000', when: (answers) => answers.features.includes('docker'), } ``` **Transforming input**: Use `filter` to normalize input before storing it: ```js { type: 'input', name: 'packageName', message: 'Package name:', filter: (input) => input.toLowerCase().replace(/\s+/g, '-'), } ``` The combination of flags and prompts is the professional pattern: power users pass everything on the command line (`scaffold init my-app --ts --license MIT --force`), while newcomers get guided through the setup interactively. Both paths produce the same result. ### Lesson: Building a Template System Now that you can gather user preferences, you need to act on them. A template system maps choices to file structures. Here is a clean pattern: ```js 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'], }, }; 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 || [], }; } ``` This pattern scales well. Adding a new template means adding an object to the `templates` map -- no changes to the prompt logic, no changes to the file-writing code. Each template declares exactly what it needs: directories, files, and dependencies. --- ## Module 3: Error Handling and User Experience A tool that works is good. A tool that works and feels good to use is great. This module covers the visual and behavioral polish that separates hobby scripts from professional CLI tools: colored output, spinners, progress bars, and error handling that actually helps the user. ### Lesson: Colored Output with Chalk Terminal output is monochrome by default, which makes it hard to scan. When everything is the same color, errors blend into success messages and warnings disappear into informational text. The `chalk` package solves this with a simple API for terminal colors. Install it: ```bash npm install chalk ``` ```js import chalk from 'chalk'; // Basic colors 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...')); // Bold, dim, underline console.log(chalk.bold.green('BUILD PASSED')); console.log(chalk.dim('(this step is optional)')); console.log(chalk.underline('https://docs.example.com')); // Combine styles console.log(chalk.bgRed.white.bold(' ERROR ') + ' Something went wrong'); // Template literals work naturally const projectName = 'my-app'; console.log(`Created ${chalk.bold(projectName)} in ${chalk.dim('0.3s')}`); ``` Build a small logger utility for your CLI that enforces consistent color usage: ```js // 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: // 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`); ``` Output: ``` [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 ``` One rule: never use color as the sole indicator of meaning. Some users have color-blind terminals or pipe output to files (which strips ANSI codes). Always pair color with text -- "Error:" not just red text. ### Lesson: Spinners and Progress Indicators with Ora When your tool does work that takes more than a second -- installing dependencies, making HTTP requests, processing files -- the user needs feedback that something is happening. A silent terminal feels broken. The `ora` package gives you clean loading spinners. Install it: ```bash npm install ora ``` ```js 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; } } 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 } } ``` The `spinner.succeed()`, `spinner.fail()`, and `spinner.warn()` methods replace the spinner with a colored symbol and final message. This gives users a clean log of what happened: ``` ✔ Created directory structure ✔ Installed 3 dependencies ✔ Git repository initialized ⚠ ESLint config skipped (no config template) ``` For longer operations where you can measure progress, update the spinner text: ```js 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`); ``` A key detail: set `stdio: 'pipe'` when running child processes while a spinner is active. Without it, the child process output will interleave with the spinner animation and produce garbled text. ### Lesson: Graceful Error Handling Raw stack traces are for developers, not users. When your CLI encounters an error, the user needs to know what went wrong and what to do about it. Here is a pattern for structured error handling: ```js // 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); } // 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); } // Unexpected errors -- show stack trace for bug reports 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); } ``` Use it in your commands: ```js 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); } }); ``` Also handle unhandled rejections and uncaught exceptions at the top level of your CLI entry point: ```js // 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 }); ``` The exit code matters. `0` means success, `1` means general error, `2` means misuse of command, `130` means interrupted by Ctrl+C. Other tools and scripts that call your CLI rely on these codes to determine what happened. --- ## Module 4: Testing Your CLI A CLI without tests is a CLI you are afraid to change. This module covers how to write automated tests for command-line tools, from testing individual functions to running the full CLI as a subprocess and checking its output. ### Lesson: Unit Testing CLI Logic The key to testable CLIs is separating logic from I/O. Your commands should call functions that can be tested independently -- do not put business logic directly inside Commander action handlers. Install your test runner: ```bash npm install --save-dev vitest ``` Add the test script to `package.json`: ```json { "scripts": { "test": "vitest run", "test:watch": "vitest" } } ``` First, extract your core logic into testable functions: ```js // 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 }; } ``` Now test these functions directly: ```js // tests/project.test.js import { describe, it, expect, beforeEach, afterEach } 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'); }); }); describe('createProject', () => { const testDir = 'test-scaffold-output'; afterEach(() => { // Clean up test artifacts if (existsSync(testDir)) { rmSync(testDir, { recursive: true, force: true }); } }); it('creates project directory structure', () => { createProject(testDir); expect(existsSync(testDir)).toBe(true); expect(existsSync(`${testDir}/src`)).toBe(true); expect(existsSync(`${testDir}/src/index.js`)).toBe(true); expect(existsSync(`${testDir}/package.json`)).toBe(true); expect(existsSync(`${testDir}/.gitignore`)).toBe(true); }); it('writes valid package.json', () => { createProject(testDir, { license: 'ISC' }); const content = readFileSync(`${testDir}/package.json`, 'utf-8'); const pkg = JSON.parse(content); expect(pkg.name).toBe(testDir); expect(pkg.license).toBe('ISC'); }); it('throws if directory exists without force flag', () => { createProject(testDir); expect(() => createProject(testDir)).toThrow('already exists'); }); it('overwrites with force flag', () => { createProject(testDir); expect(() => createProject(testDir, { force: true })).not.toThrow(); }); }); ``` Run the tests: ```bash npm test ``` The pattern here is clear: the Commander action handler becomes a thin wrapper that calls `validateProjectName`, `gatherProjectConfig` (prompts), and `createProject`. Each piece is independently testable. ### Lesson: Integration Testing -- Running the CLI as a Subprocess Unit tests verify individual functions, but you also need to verify that the full CLI works end-to-end: that it parses arguments correctly, produces the right output, and returns the correct exit code. The `child_process` module lets you run your CLI as a subprocess and inspect the results. ```js // tests/cli.test.js import { describe, it, expect, afterEach } from 'vitest'; import { execSync, 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, }; } } describe('CLI integration', () => { afterEach(() => { if (existsSync(TEST_DIR)) { rmSync(TEST_DIR, { recursive: true, force: true }); } }); 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'); }); it('fails with no command', () => { const { stdout } = runCLI([]); // Commander shows help when no command is given expect(stdout).toContain('Usage'); }); it('fails with unknown command', () => { const result = runCLI(['unknown']); expect(result.exitCode).not.toBe(0); }); it('creates project with init command', () => { // Note: This test works for non-interactive mode. // For interactive prompts, you would need to pipe input // or use a --no-interactive flag. 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); }); }); ``` A few important details about integration testing CLIs: **Timeout**: Always set a timeout. A bug in your prompt logic can cause the test to hang forever waiting for input that never comes. **Non-interactive mode**: For testability, add a `--no-interactive` or `--ci` flag that skips all prompts and uses defaults. Many real-world CLIs do this: ```js 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); } // ... }); ``` **Exit codes**: Always verify exit codes, not just output text. A command that prints an error message but exits with code 0 will silently pass in CI pipelines. --- ## Module 5: Publishing to npm You have a working, tested CLI tool. Now it is time to share it with the world. Publishing to npm makes your tool installable with a single command: `npm install -g scaffold`. This module covers everything from preparing your package to managing releases. ### Lesson: Preparing Your Package for Publication Before publishing, your `package.json` needs several fields that npm uses for discovery and documentation: ```json { "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**: If the simple name is taken (and it probably is), use a scoped name: `@yourname/scaffold`. Scoped packages are free and avoid naming conflicts. **files**: This is an allowlist of what gets included in the published package. Without it, npm includes everything not in `.gitignore`. Always be explicit -- your users do not need test files, documentation, or CI configs. **engines**: Declares the minimum Node.js version. npm will warn (or error, with `engine-strict`) if someone tries to install on an incompatible version. **prepublishOnly**: This script runs before every `npm publish`. Making it run your tests ensures you never publish broken code. Check what will actually be published: ```bash npm pack --dry-run ``` This lists every file that would be included in the tarball. Review it carefully. Common mistakes: - Including `.env` files with secrets - Including `node_modules` (should always be in `.gitignore`) - Including large test fixtures or screenshots - Forgetting to include a required source file Create a `.npmignore` file if you need fine-grained control beyond `files`: ``` # .npmignore tests/ coverage/ .github/ *.test.js .env* ``` ### Lesson: Publishing and Version Management Create an npm account if you do not have one: ```bash npm adduser ``` Verify you are logged in: ```bash npm whoami ``` Do a dry run first to see what would happen: ```bash npm publish --dry-run ``` If everything looks correct, publish: ```bash # For scoped packages, public access is required on first publish npm publish --access public ``` Your package is now live. Anyone can install it: ```bash npm install -g @yourname/scaffold ``` For subsequent releases, follow semantic versioning: ```bash # Bug fixes (1.0.0 -> 1.0.1) npm version patch # New features, backwards compatible (1.0.0 -> 1.1.0) npm version minor # Breaking changes (1.0.0 -> 2.0.0) npm version major ``` `npm version` does three things: updates `package.json`, creates a git commit, and creates a git tag. Then push and publish: ```bash git push && git push --tags npm publish ``` Automate this with a release script in `package.json`: ```json { "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" } } ``` ### Lesson: Post-Publication -- Maintenance and Best Practices Publishing is not the end. Here are the practices that separate maintained packages from abandoned ones. **Add a README that works on npm**: npm renders your README on the package page. Include a clear install command, a usage example, and a feature list: ```markdown # @yourname/scaffold Scaffold new Node.js projects with configurable templates. ## Install npm install -g @yourname/scaffold ## Usage 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 ``` **Deprecate old versions when needed**: ```bash npm deprecate @yourname/scaffold@"< 1.0.0" "Please upgrade to 1.x" ``` **Monitor for issues**: Add an `engines` field so users on incompatible Node.js versions get warnings. Add `peerDependencies` if your tool relies on other globally installed tools. **Add a changelog**: Create `CHANGELOG.md` and update it with every release. Users read changelogs before upgrading. ```markdown # 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 ``` **Test before every release**: The `prepublishOnly` script handles this, but also test the installed package: ```bash # Pack locally and test the actual tarball npm pack npm install -g ./yourname-scaffold-1.0.0.tgz scaffold init test-project # Verify it works npm uninstall -g @yourname/scaffold ``` This catches a common mistake: your tool works in development (where all dev dependencies are available) but fails when installed (where only production dependencies are present). The `npm pack` plus global install workflow is the only way to catch this before your users do. --- ## Where to Go Next You now have a complete CLI tool that is tested, polished, and published. Here are directions to explore: **Node.js `child_process` docs** -- The real power of a CLI is orchestrating other commands. `execSync` and `spawnSync` from Node's built-in `child_process` module let you run `git init`, `npm install`, or any shell command from inside your tool. The official Node.js docs on `child_process` are thorough and the API is stable -- worth reading once so you understand when to use `exec` vs `spawn` and why the difference matters for streaming output. **Configuration files** -- Tools like ESLint and Prettier read from config files (`.eslintrc`, `prettier.config.js`). The `cosmiconfig` package lets your CLI read configuration from `package.json`, `.scaffoldrc`, `scaffold.config.js`, or environment variables with zero custom code. **Plugin systems** -- Once your tool has a user base, they will want to extend it. Study how Babel, ESLint, and Vite handle plugins. The simplest pattern: plugins export a function that receives your tool's context and returns modifications. **`pkg` or `bun build --compile`** -- If you want to distribute a single executable binary that does not require Node.js to be installed, both `pkg` (by Vercel) and Bun's `--compile` flag can bundle your script and its dependencies into a standalone binary for macOS, Linux, and Windows. This is how you go from "npm package" to "download and run" distribution. **GitHub Actions for CI/CD** -- Automate testing and publishing. Run tests on every push, and publish to npm automatically when you create a GitHub release. The `npm publish` action needs an NPM_TOKEN secret configured in your repository settings.