Utility Script Patterns

Common patterns for writing Node.js utility scripts — file I/O, globbing, colored output, interactive prompts, and spinners.

Recipe

Quick-reference recipe card — copy-paste ready.

# Install the standard utility-script toolkit
npm install --save-dev \
  fast-glob \
  chalk \
  @inquirer/prompts \
  ora
 
# Node built-ins — no install needed
#   node:fs/promises   — async file I/O
#   node:path          — cross-platform paths
#   node:url           — fileURLToPath for __dirname in ESM

// Minimal skeleton
import { readFile, writeFile } from "node:fs/promises";
import fg from "fast-glob";
import chalk from "chalk";
import { confirm } from "@inquirer/prompts";
import ora from "ora";

When to reach for this: Any CLI utility, codemod, build step, or maintenance script where you need progress feedback and safe file operations.

Working Example

// scripts/process-ts-files.ts
import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import fg from "fast-glob";
import chalk from "chalk";
import { confirm } from "@inquirer/prompts";
import ora from "ora";
 
async function main(): Promise<void> {
  // 1. Find files
  const files = await fg("src/**/*.ts", {
    ignore: ["**/*.d.ts", "**/node_modules/**"],
    absolute: true,
  });
 
  console.log(chalk.cyan(`Found ${files.length} TypeScript files.`));
 
  if (files.length === 0) {
    console.log(chalk.yellow("Nothing to do."));
    return;
  }
 
  // 2. Confirm with the user
  const proceed = await confirm({
    message: `Process ${files.length} files?`,
    default: false,
  });
 
  if (!proceed) {
    console.log(chalk.gray("Aborted."));
    return;
  }
 
  // 3. Process with a spinner
  const spinner = ora("Processing files...").start();
  let changed = 0;
 
  try {
    for (const file of files) {
      const contents = await readFile(file, "utf8");
      const next = contents.replace(/\r\n/g, "\n");
      if (next !== contents) {
        await writeFile(file, next, "utf8");
        changed += 1;
      }
      spinner.text = `Processing ${path.basename(file)}`;
    }
    spinner.succeed(chalk.green(`Normalized ${changed} file(s).`));
  } catch (err) {
    spinner.fail(chalk.red("Processing failed."));
    throw err;
  }
}
 
main().catch((err: unknown) => {
  console.error(chalk.red("Script error:"), err);
  process.exitCode = 1;
});

What this demonstrates:

• Async file I/O via node:fs/promises (never readFileSync in an async script)
• fast-glob for fast, flexible file matching with ignore patterns
• @inquirer/prompts named-function API (replaces the legacy inquirer.prompt() object API)
• ora spinner with dynamic text updates and succeed / fail states
• Proper error handling that sets process.exitCode instead of calling process.exit()

Deep Dive

How It Works

• node:fs/promises exposes all fs functions as promise-returning variants. No need for util.promisify anymore.
• fast-glob is the fastest widely-used glob library for Node. It returns a plain string[] by default (or Entry[] with objectMode: true).
• chalk v5 is ESM-only. If you're on CommonJS, either pin to chalk v4 or convert your project to ESM.
• @inquirer/prompts is the modern replacement for the monolithic inquirer package. Each prompt (input, confirm, select, checkbox) is imported as a named function that returns a promise.
• ora writes to stderr by default and detects TTY to disable animations in CI. You can force state via { isEnabled: process.stdout.isTTY }.

Variations

Reading and writing JSON files:

import { readFile, writeFile } from "node:fs/promises";
 
interface Config {
  name: string;
  version: string;
}
 
const raw = await readFile("config.json", "utf8");
const config = JSON.parse(raw) as Config;
config.version = "2.0.0";
await writeFile("config.json", JSON.stringify(config, null, 2) + "\n");

Stream-based processing for large files:

import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";
 
const rl = createInterface({
  input: createReadStream("huge.log"),
  crlfDelay: Infinity,
});
 
for await (const line of rl) {
  // process one line at a time — memory stays flat
}

Recursive directory walking without a glob library:

import { readdir } from "node:fs/promises";
 
// Node 20+ supports recursive: true
const entries = await readdir("src", { recursive: true, withFileTypes: true });
const files = entries.filter((e) => e.isFile()).map((e) => e.name);

Progress bars with cli-progress:

import cliProgress from "cli-progress";
 
const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
bar.start(files.length, 0);
for (const file of files) {
  await process(file);
  bar.increment();
}
bar.stop();

Detecting TTY to silence decoration in CI:

const isInteractive = process.stdout.isTTY && !process.env.CI;
const spinner = ora({ text: "Working...", isEnabled: isInteractive });

Template strings with chalk:

console.log(`${chalk.bold.blue("info")} Found ${chalk.yellow(files.length)} files`);

TypeScript Notes

• fs.readFile(path, "utf8") returns Promise<string>. Without the encoding, it returns Promise<Buffer>. Always pass "utf8" when you want a string.
• fast-glob returns Promise<string[]> when called without options. With { objectMode: true } it returns Promise<Entry[]>.
• @inquirer/prompts infers return types from the prompt: confirm() returns Promise<boolean>, input() returns Promise<string>, and select<T>() accepts a generic for the choice value.
• Type the top-level script error handler as (err: unknown) and narrow before logging.

Gotchas

Things that will bite you. Each gotcha includes what goes wrong, why it happens, and the fix.

• Using fs.readFileSync in an async script — Blocks the event loop, defeats concurrency, and makes spinners stutter. Fix: Use import { readFile } from "node:fs/promises" and await it. Sync APIs are only appropriate in startup code before any async work.

• Forgetting to await an fs.promises call — writeFile(path, data) without await returns an unhandled promise. The script exits before the write completes, silently losing data. Fix: Always await, and enable @typescript-eslint/no-floating-promises to catch this at lint time.

• Chalk colors not appearing in CI — Chalk auto-detects TTY and disables colors in non-interactive environments. Logs in GitHub Actions or CircleCI appear uncolored by design. Fix: Set FORCE_COLOR=1 as an env var in CI, or use new Chalk(\{ level: 3 \}) to force color level.

• Relative vs absolute paths in glob — fast-glob returns paths relative to cwd by default. Passing those to fs.readFile works only if the script is run from the same directory. Fix: Use { absolute: true } or resolve manually with path.resolve(process.cwd(), file).

• Emoji breaking Windows terminals — Legacy cmd.exe and older PowerShell render emoji as garbled bytes. Fix: Detect Windows via process.platform === "win32" and fall back to ASCII, or require Windows Terminal (UTF-8 by default).

• Calling process.exit() before writes flush — process.exit(1) terminates immediately, truncating stdout and pending fs.writeFile calls. Fix: Set process.exitCode = 1 and let the event loop drain naturally.

Alternatives

Other ways to solve the same problem — and when each is the better choice.

FAQs

Related

• ESLint for Node.js Scripts — lint your scripts with type-aware rules
• Git Utilities — shell tooling for automation scripts
• TypeScript Basics — tsconfig for Node projects
• Environment Variables — loading config into scripts