CLI Source Code Preview

1.1.0 · active · verified Wed Apr 22

cli-source-preview is a JavaScript utility designed to render syntax-highlighted source code snippets directly in the command-line interface. It's particularly useful for enhancing error messages or debug outputs by providing relevant code context, complete with line numbers and customizable colorization. The current stable version is 1.1.0. This package offers a focused solution for presenting code in a terminal environment, distinguishing itself by integrating `chalk` for robust ASCII color support. Developers can specify single lines, line ranges, or even precise line/column positions for the preview, with options to control the number of surrounding context lines and the line delimiter. Given its specific utility and the current version, it's maintained to ensure compatibility and address any critical bugs, rather than undergoing frequent feature-driven releases.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require('cli-source-preview')` inside a JavaScript file that Node.js is treating as an ES Module (e.g., due to `"type": "module"` in `package.json` or a `.mjs` extension).

fix Rename your file to a `.cjs` extension, or ensure your `package.json` specifies `"type": "commonjs"`. Alternatively, use dynamic `import()` if you need to load a CJS module from an ESM context: `const preview = await import('cli-source-preview');` (note: this still imports the CJS default, which is the `preview` function itself, so `preview.default` might be needed if not destructured).
```
Error: Cannot find module 'cli-source-preview'
```
cause The `cli-source-preview` package has not been installed or cannot be resolved by the Node.js module loader.

fix Run `npm install cli-source-preview` in your project directory. If it's installed globally, ensure your Node.js `require` path includes global modules, or install it locally.

Warnings

breaking The package `cli-source-preview` v1.x is strictly CommonJS (CJS) and does not provide ES Module (ESM) exports. Attempting to `import` it in an ESM context will result in a runtime error.
Fix: Use `const preview = require('cli-source-preview');` in CJS files. For ESM projects, consider using a CJS-compatible wrapper or a bundler that can handle CJS modules.
gotcha The package depends on `chalk` for its CLI coloring. Ensure `chalk` is correctly installed in your project. Mismatched or missing `chalk` versions might lead to unexpected styling or runtime errors if `cli-source-preview`'s internal `chalk` dependency cannot be resolved.
gotcha The `line` argument for the `preview` function is `Mixed` and can accept a number, an array `[start, end]`, or an object `{ line, column }`. Providing incorrect types or out-of-bounds line/column numbers might lead to unexpected output or errors, though the library generally handles basic out-of-bounds gracefully by adjusting the preview range.
Fix: Always validate input line numbers and ranges against the `source` string's actual line count to prevent unexpected behavior.

Install

npm install cli-source-preview npm
yarn add cli-source-preview yarn
pnpm add cli-source-preview pnpm

Imports

preview
wrong:
```
import preview from 'cli-source-preview'
```
correct:
```
const preview = require('cli-source-preview')
```
The `cli-source-preview` package (v1.x) is CommonJS-only and does not export ES Modules. Use `require`.
preview.readSource
wrong:
```
import { readSource } from 'cli-source-preview'
```
correct:
```
const preview = require('cli-source-preview'); const readSource = preview.readSource;
```
`readSource` is a method on the default `preview` export, not a named export. It is also CommonJS-only.

Quickstart

This quickstart demonstrates how to install and use `cli-source-preview` to highlight and preview different sections of a source code string, including single lines, line ranges, and specific line/column positions.

const preview = require('cli-source-preview');

const source = `
'use strict'

const chalk = require('chalk')

const PREVIEW_OPTS = {
  offset: 5,
  lineNumber: true,
  delimiter: '\n'
}
const DELIMITER = '-'.repeat(40)

function rightPad (text, width) {
  return text + (width > text.length ? ' '.repeat(width - text.length) : '')
}
`;

// Preview line 10
console.log('--- Preview line 10 ---');
console.log(preview(source, 10));

// Preview lines 5 to 8
console.log('\n--- Preview lines 5-8 ---');
console.log(preview(source, [5, 8]));

// Preview line 12, column 6
console.log('\n--- Preview line 12:6 ---');
console.log(preview(source, { line: 12, column: 6}));

view raw JSON →