CLI Welcome Header

3.0.1 · active · verified Wed Apr 22

cli-welcome is a Node.js library specifically designed for creating customizable welcome headers in Command Line Interface (CLI) applications. It allows developers to display essential information such as the application's title, a tagline, a description, and its version number. The library provides styling options including configurable background and text colors, and text bolding. Currently stable at version 3.0.1, the package maintains an active release cadence with frequent patch and minor updates, while major versions introduce more significant changes. It ships with comprehensive TypeScript type definitions, ensuring seamless integration and type-safety within modern TypeScript projects. Its primary differentiator is simplifying the process of establishing a consistent, branded, and informative initial display for CLI tools without requiring extensive manual console styling or external dependencies.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) context.

fix Change `const welcome = require('cli-welcome');` to `import welcome from 'cli-welcome';`. Ensure your Node.js environment is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: welcome is not a function
```
cause Incorrect import statement for the `welcome` function (e.g., trying a named import when it's a default export) or attempting to call a non-function.

fix For ESM, use `import welcome from 'cli-welcome';`. For CommonJS, use `const welcome = require('cli-welcome');`. Verify that you are calling `welcome` with an options object, as shown in the quickstart.
```
TypeError: Cannot read properties of undefined (reading 'name')
```
cause When dynamically loading `package.json`, the file might not be found or parsed correctly, leading to `packageJson` being `undefined` or an unexpected value.

fix Ensure `package.json` exists at the expected path (`process.cwd()`) and is readable. Add robust error handling (e.g., `try-catch`) around `readFileSync` and `JSON.parse` operations.

Warnings

breaking Version 2.0.0 introduced breaking changes by deprecating and removing `heading` and `sub` options. The `title` and `description` options also changed their configuration method, now exclusively accepted as properties within the main options object.
Fix: Migrate your welcome header configuration to use the unified `options` object. Ensure `title` and `description` are properties of this object and remove any usage of `heading` or `sub`.
gotcha When using `cli-welcome` in a Node.js ESM module, `require()` is not defined by default. Attempting to use `const welcome = require('cli-welcome');` will throw a `ReferenceError`.
Fix: For ESM projects, use `import welcome from 'cli-welcome';`. Ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension.
gotcha Version 2.2.2 removed Scarf, a telemetry component, from the package. While not a breaking change in functionality, users relying on or expecting Scarf's presence should be aware of its removal.
Fix: No fix needed, but be aware that usage analytics via Scarf are no longer collected by `cli-welcome` itself.

Install

npm install cli-welcome npm
yarn add cli-welcome yarn
pnpm add cli-welcome pnpm

Imports

welcome
wrong:
```
import { welcome } from 'cli-welcome';
```
correct:
```
import welcome from 'cli-welcome';
```
The primary `welcome` function is the default export in ESM. Attempting a named import will result in an undefined symbol.
welcome (CommonJS)
wrong:
```
const { welcome } = require('cli-welcome');
```
correct:
```
const welcome = require('cli-welcome');
```
For CommonJS, the module exports the `welcome` function directly. Destructuring it may lead to `undefined` in some setups.
Options type
```
import type { Options } from 'cli-welcome';
```
Import TypeScript types separately for type checking without bundling the runtime code.

Quickstart

This quickstart demonstrates how to import and use `cli-welcome` with dynamic application details from `package.json`.

import welcome from 'cli-welcome';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';

// Dynamically load package.json for application details.
const packageJsonPath = join(process.cwd(), 'package.json');
const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));

welcome({
  title: packageJson.name || 'My CLI App',
  tagLine: 'A powerful tool for your daily tasks',
  description: packageJson.description || 'This CLI helps you manage your projects efficiently.',
  bgColor: '#6A788D',
  color: '#ffffff',
  bold: true,
  clear: true,
  version: `v${packageJson.version}`
});

console.log('Your CLI application logic starts here...');

view raw JSON →