{"id":16971,"library":"cli-welcome","title":"CLI Welcome Header","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ahmadawais/cli-welcome","tags":["javascript","cli-welcome","Ahmad Awais","ahmadawais","typescript"],"install":[{"cmd":"npm install cli-welcome","lang":"bash","label":"npm"},{"cmd":"yarn add cli-welcome","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-welcome","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `welcome` function is the default export in ESM. Attempting a named import will result in an undefined symbol.","wrong":"import { welcome } from 'cli-welcome';","symbol":"welcome","correct":"import welcome from 'cli-welcome';"},{"note":"For CommonJS, the module exports the `welcome` function directly. Destructuring it may lead to `undefined` in some setups.","wrong":"const { welcome } = require('cli-welcome');","symbol":"welcome (CommonJS)","correct":"const welcome = require('cli-welcome');"},{"note":"Import TypeScript types separately for type checking without bundling the runtime code.","symbol":"Options type","correct":"import type { Options } from 'cli-welcome';"}],"quickstart":{"code":"import welcome from 'cli-welcome';\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\n// Dynamically load package.json for application details.\nconst packageJsonPath = join(process.cwd(), 'package.json');\nconst packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));\n\nwelcome({\n  title: packageJson.name || 'My CLI App',\n  tagLine: 'A powerful tool for your daily tasks',\n  description: packageJson.description || 'This CLI helps you manage your projects efficiently.',\n  bgColor: '#6A788D',\n  color: '#ffffff',\n  bold: true,\n  clear: true,\n  version: `v${packageJson.version}`\n});\n\nconsole.log('Your CLI application logic starts here...');","lang":"typescript","description":"This quickstart demonstrates how to import and use `cli-welcome` with dynamic application details from `package.json`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For ESM projects, use `import welcome from 'cli-welcome';`. Ensure your `package.json` has `\"type\": \"module\"` or your file uses the `.mjs` extension.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"No fix needed, but be aware that usage analytics via Scarf are no longer collected by `cli-welcome` itself.","message":"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.","severity":"gotcha","affected_versions":">=2.2.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) context.","error":"ReferenceError: require is not defined"},{"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.","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.","error":"TypeError: welcome is not a function"},{"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.","cause":"When dynamically loading `package.json`, the file might not be found or parsed correctly, leading to `packageJson` being `undefined` or an unexpected value.","error":"TypeError: Cannot read properties of undefined (reading 'name')"}],"ecosystem":"npm","meta_description":null}