Simple Code Frame

1.3.0 · active · verified Sun Apr 19

Simple Code Frame is a lightweight JavaScript utility designed for generating structured code frames, primarily used in error reporting or diagnostic tools. Its current stable version is 1.3.0. Unlike more comprehensive alternatives like `@babel/code-frame`, `simple-code-frame` distinguishes itself by operating directly on raw string input without requiring an AST parser. This focused design makes it exceptionally small and performant for tasks that only involve highlighting specific lines and columns within arbitrary text. The library ships with TypeScript types, providing a good developer experience for both JavaScript and TypeScript projects. Releases appear to follow a moderate cadence, adding features like `maxWidth` for line truncation and colored output in recent minor versions. It is suitable for environments where parsing overhead is undesirable, focusing solely on visual presentation of code context.

Common errors

```
TypeError: code.split is not a function
```
cause The `code` argument passed to `createCodeFrame` was not a string.

fix Ensure the first argument passed to `createCodeFrame` is always a string containing the source code.
```
TypeError: Cannot read properties of undefined (reading 'split')
```
cause Similar to `code.split is not a function`, this typically means `code` was `null`, `undefined`, or some other non-string value where the library expected a string.

fix Verify that the `code` input parameter is a valid string before calling `createCodeFrame`.

Warnings

gotcha Line and column numbers for `createCodeFrame` are 1-based, not 0-based. Providing 0 for either will not correctly target the first line/column.
Fix: Always use 1-based indexing for line and column arguments to ensure correct highlighting.
gotcha When the `line` or `column` argument points to a location outside the bounds of the provided code string, the code frame will still be generated but the marker ('>' and '^') might not appear, leading to unexpected output without an explicit error.
Fix: Validate line and column inputs against the actual content length or lines count if precise highlighting is critical.
gotcha Colored output (using `highlightColor`) may not display correctly in terminals that do not support ANSI escape codes, or if the `NO_COLOR` environment variable is set. The library does not force colors.
Fix: Ensure the terminal supports ANSI colors or avoid using `highlightColor` option in environments where color support is uncertain or undesired.
gotcha The `maxWidth` option truncates lines with an ellipsis ('...') if they exceed the specified width. This only applies to the highlighted line and its context, not the entire source.
Fix: Test different `maxWidth` values to find an appropriate balance between readability and conciseness for your specific use case.

Install

npm install simple-code-frame npm
yarn add simple-code-frame yarn
pnpm add simple-code-frame pnpm

Imports

createCodeFrame
wrong:
```
import createCodeFrame from 'simple-code-frame';
```
correct:
```
import { createCodeFrame } from 'simple-code-frame';
```
The primary function `createCodeFrame` is a named export. Default import is incorrect.
createCodeFrame (CJS)
wrong:
```
const createCodeFrame = require('simple-code-frame');
```
correct:
```
const { createCodeFrame } = require('simple-code-frame');
```
For CommonJS environments, `createCodeFrame` is a named property of the module export.
Types
```
import type { CodeFrameOptions } from 'simple-code-frame';
```
TypeScript types for options and return values are available as named exports.

Quickstart

Demonstrates generating a code frame for a specific line and column, including options for highlighting and message, and usage of `maxWidth` for truncation.

import { createCodeFrame } from 'simple-code-frame';

const sourceCode = `function greet(name) {
  console.log('Hello, ' + name + '!');
  throw new Error('Something went wrong');
}

greet('World');`;

// Simulate an error at line 3, column 9
const errorFrame = createCodeFrame(sourceCode, 3, 9, {
  highlightColor: 'red',
  message: 'Error here!'
});

console.log(errorFrame);

// Example with maxWidth and no message
const longLineCode = `const veryLongVariableName = 'This is a very long string that should be truncated by maxWidth.';
console.log(veryLongVariableName);`;
const truncatedFrame = createCodeFrame(longLineCode, 1, 1, { maxWidth: 50 });
console.log('\n--- Truncated Frame ---\n');
console.log(truncatedFrame);

view raw JSON →