@neabyte/stackz/README.md

Beautiful stack trace formatter with source code context for JavaScript

# Stackz [![Module type: CJS+ESM](https://img.shields.io/badge/module%20type-cjs%2Besm-brightgreen)](https://github.com/NeaByteLab/Stackz) [![npm version](https://img.shields.io/npm/v/@neabyte/stackz.svg)](https://www.npmjs.org/package/@neabyte/stackz) [![JSR](https://jsr.io/badges/@neabyte/stackz)](https://jsr.io/@neabyte/stackz) [![Node.js CI](https://github.com/NeaByteLab/Stackz/actions/workflows/ci.yaml/badge.svg)](https://github.com/NeaByteLab/Stackz)

Beautiful stack trace formatter with source code context for JavaScript.

![Demo](./assets/demo.png)

## Features

- **Cross-runtime support** - Works in Deno, Node.js, Bun, and browsers
- **Source code context** - Shows actual code around error locations (detailed mode)
- **Two formatting styles** - Compact and detailed stack traces
- **ANSI colors** - Beautiful terminal output with syntax highlighting

## Installation

Choose your preferred package manager:

```bash
# npm package
npm install @neabyte/stackz

# Deno module
deno add jsr:@neabyte/stackz
```

## Usage

```typescript
import Stackz from '@neabyte/stackz'

try {
  // Your code that might throw
  throw new Error('Something went wrong')
} catch (error) {
  // Compact format without source context
  console.log(Stackz.format(error, 'compact'))
  // Detailed format with source context
  console.log(await Stackz.format(error, 'detailed'))
}
```

## Formats

### Compact

```
TypeError  Cannot read properties of undefined (reading 'property')
  → createTypeError @ index.ts:5:14
  → index.ts:15:3
```

### Detailed

```
TypeError  Cannot read properties of undefined (reading 'property')

Path: /path/to/project/index.ts:5:14
  2 |
  3 | function createTypeError() {
  4 |   const obj = undefined as any
  5     return obj.property // This will create TypeError with real stack
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  6 | }

Call Stack:
 • createTypeError → index.ts:5:14
 • anonymous → index.ts:15:3
```

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.