# Getting Started (/docs)





# Welcome to Visulima [#welcome-to-visulima]

Visulima is a collection of **40+ production-ready TypeScript packages** that solve real problems — from building CLI tools and bundling libraries, to handling errors, working with file systems, and creating APIs.

Every package is:

* **TypeScript-first** with full type safety
* **Zero or minimal dependencies** where possible
* **Cross-runtime** — Node.js, Bun, Deno, and Edge support
* **Well-tested** and maintained in a single monorepo

## Quick Start [#quick-start]

Install any package with your preferred package manager:

<CodeBlockTabs defaultValue="pnpm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @visulima/<package-name>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="npm">
    ```bash
    npm install @visulima/<package-name>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @visulima/<package-name>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @visulima/<package-name>
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Popular Packages [#popular-packages]

<Cards>
  <Card title="Cerebro" description="Extensible CLI framework" href="/docs/packages/cerebro" />

  <Card title="Pail" description="Configurable logger for Node.js, Edge and Browser" href="/docs/packages/pail" />

  <Card title="FS" description="Human-friendly file system utilities" href="/docs/packages/fs" />

  <Card title="Error" description="Enhanced error handling with AI-powered solutions" href="/docs/packages/error" />

  <Card title="String" description="Comprehensive string manipulation" href="/docs/packages/string" />
</Cards>

## Browse by Category [#browse-by-category]

<Cards>
  <Card title="CLI & Terminal" description="Build command-line tools, format output, and manage colors" href="/docs/packages#cli--terminal" />

  <Card title="Data & Utilities" description="String manipulation, object utilities, deep cloning, and more" href="/docs/packages#data" />

  <Card title="File System" description="File I/O, path handling, config parsing, and caching" href="/docs/packages#file-system" />

  <Card title="API & Web" description="REST APIs, pagination, OpenAPI generation, and HTML utilities" href="/docs/packages#api--web" />

  <Card title="Error Handling" description="Error parsing, source maps, debugging overlays, and inspection" href="/docs/packages#error-handling" />

  <Card title="Dev Tools" description="Dev toolbar, Prisma tools, and bundling" href="/docs/packages#dev-tools" />
</Cards>

## Project Links [#project-links]

* [GitHub Repository](https://github.com/visulima/visulima) — Source code, issues, and contributions
* [Changelog](/changelog) — Release history and breaking changes
* [All Packages](/docs/packages) — Full package directory with descriptions


# API Reference (/docs/packages/ansi/api)



# API Reference [#api-reference]

Complete reference for all ANSI escape code functions organized by category.

## Cursor Control [#cursor-control]

Functions for cursor positioning, movement, and styling.

### cursorTo [#cursorto]

Move cursor to absolute position.

**Signature:**

```typescript
function cursorTo(x: number, y?: number): string;
```

**Parameters:**

* `x` (`number`) - Column position (0-based)
* `y` (`number`, optional) - Row position (0-based)

**Returns:** ANSI escape sequence string

**Example:**

```typescript
import { cursorTo } from "@visulima/ansi";
process.stdout.write(cursorTo(10, 5)); // Move to column 10, row 5
```

***

### cursorMove [#cursormove]

Move cursor relative to current position.

**Signature:**

```typescript
function cursorMove(x: number, y: number): string;
```

**Parameters:**

* `x` (`number`) - Columns to move (positive = right, negative = left)
* `y` (`number`) - Rows to move (positive = down, negative = up)

**Returns:** ANSI escape sequence string

***

### cursorUp / cursorDown / cursorForward / cursorBackward [#cursorup--cursordown--cursorforward--cursorbackward]

Move cursor in specific direction.

**Signatures:**

```typescript
function cursorUp(count?: number): string;
function cursorDown(count?: number): string;
function cursorForward(count?: number): string;
function cursorBackward(count?: number): string;
```

**Parameters:**

* `count` (`number`, optional) - Number of positions to move. Default: `1`

**Returns:** ANSI escape sequence string

***

### cursorLeft [#cursorleft]

Move cursor to leftmost position (column 0).

**Signature:**

```typescript
const cursorLeft: string;
```

**Example:**

```typescript
import { cursorLeft } from "@visulima/ansi";
process.stdout.write(cursorLeft);
```

***

### cursorSave / cursorRestore [#cursorsave--cursorrestore]

Save and restore cursor position.

**Signatures:**

```typescript
const cursorSave: string;
const cursorRestore: string;
```

**Example:**

```typescript
import { cursorSave, cursorRestore } from "@visulima/ansi";
process.stdout.write(cursorSave);
// ... do work ...
process.stdout.write(cursorRestore);
```

***

### cursorHide / cursorShow [#cursorhide--cursorshow]

Control cursor visibility.

**Signatures:**

```typescript
const cursorHide: string;
const cursorShow: string;
```

**Example:**

```typescript
import { cursorHide, cursorShow } from "@visulima/ansi";
process.stdout.write(cursorHide);
// ... do work ...
process.stdout.write(cursorShow);
```

***

### setCursorStyle [#setcursorstyle]

Set cursor appearance.

**Signature:**

```typescript
function setCursorStyle(style: CursorStyle): string;
```

**Parameters:**

* `style` (`CursorStyle`) - One of:
  * `"blinking-block"`
  * `"steady-block"`
  * `"blinking-underline"`
  * `"steady-underline"`
  * `"blinking-bar"`
  * `"steady-bar"`

**Returns:** ANSI escape sequence string

**Example:**

```typescript
import { setCursorStyle } from "@visulima/ansi";
process.stdout.write(setCursorStyle("blinking-bar"));
```

***

## Screen Manipulation [#screen-manipulation]

Functions for clearing and manipulating the screen.

### clearScreen [#clearscreen]

Clear the entire screen.

**Signature:**

```typescript
const clearScreen: string;
```

**Example:**

```typescript
import { clearScreen } from "@visulima/ansi";
process.stdout.write(clearScreen);
```

***

### eraseDown / eraseUp [#erasedown--eraseup]

Erase from cursor to end/start of screen.

**Signatures:**

```typescript
const eraseDown: string;
const eraseUp: string;
```

***

### eraseLine / eraseLineEnd / eraseLineStart [#eraseline--eraselineend--eraselinestart]

Erase line or part of line.

**Signatures:**

```typescript
const eraseLine: string;
const eraseLineEnd: string;
const eraseLineStart: string;
```

**Example:**

```typescript
import { eraseLine } from "@visulima/ansi";
process.stdout.write(eraseLine);
console.log("New line content");
```

***

### eraseLines [#eraselines]

Erase multiple lines.

**Signature:**

```typescript
function eraseLines(count: number): string;
```

**Parameters:**

* `count` (`number`) - Number of lines to erase

**Returns:** ANSI escape sequence string

***

### clearScreenAndHomeCursor [#clearscreenandhomecursor]

Clear screen and move cursor to home position (0, 0).

**Signature:**

```typescript
const clearScreenAndHomeCursor: string;
```

***

### alternativeScreenOn / alternativeScreenOff [#alternativescreenon--alternativescreenoff]

Switch between normal and alternative screen buffers.

**Signatures:**

```typescript
const alternativeScreenOn: string;
const alternativeScreenOff: string;
```

**Example:**

```typescript
import { alternativeScreenOn, alternativeScreenOff } from "@visulima/ansi";

process.stdout.write(alternativeScreenOn);
// Full-screen app here
process.stdout.write(alternativeScreenOff);
```

***

### scrollUp / scrollDown [#scrollup--scrolldown]

Scroll screen region.

**Signatures:**

```typescript
function scrollUp(count?: number): string;
function scrollDown(count?: number): string;
```

**Parameters:**

* `count` (`number`, optional) - Number of lines to scroll. Default: `1`

**Returns:** ANSI escape sequence string

***

## Hyperlinks [#hyperlinks]

### hyperlink [#hyperlink]

Create clickable hyperlink in terminal.

**Signature:**

```typescript
function hyperlink(url: string, text: string, options?: HyperlinkOptions): string;
```

**Parameters:**

* `url` (`string`) - URL to link to
* `text` (`string`) - Display text
* `options` (`HyperlinkOptions`, optional) - Additional options
  * `id` (`string`, optional) - Unique ID for the link

**Returns:** Formatted hyperlink string

**Example:**

```typescript
import { hyperlink } from "@visulima/ansi";

const link = hyperlink("https://github.com", "GitHub");
console.log(`Visit ${link} for more info`);
```

***

## Images [#images]

### image [#image]

Display image in iTerm2.

**Signature:**

```typescript
function image(buffer: Buffer | Uint8Array, options?: ImageOptions): string;
```

**Parameters:**

* `buffer` (`Buffer | Uint8Array`) - Image data
* `options` (`ImageOptions`, optional) - Display options
  * `width` (`number | string`, optional) - Width (pixels, percent, or "auto")
  * `height` (`number | string`, optional) - Height (pixels, percent, or "auto")
  * `preserveAspectRatio` (`boolean`, optional) - Preserve aspect ratio. Default: `true`
  * `inline` (`boolean`, optional) - Display inline with text. Default: `false`

**Returns:** iTerm2 image escape sequence

**Example:**

```typescript
import { image } from "@visulima/ansi";
import { readFileSync } from "fs";

const img = readFileSync("logo.png");
process.stdout.write(image(img, { width: "50%", height: "auto" }));
```

***

## Strip ANSI [#strip-ansi]

### strip [#strip]

Remove ANSI escape codes from string.

**Signature:**

```typescript
function strip(text: string): string;
```

**Parameters:**

* `text` (`string`) - String containing ANSI codes

**Returns:** String with ANSI codes removed

**Example:**

```typescript
import { strip } from "@visulima/ansi";
import { cursorUp } from "@visulima/ansi";

const withAnsi = `Hello${cursorUp(2)} World`;
const clean = strip(withAnsi);
console.log(clean); // "Hello World"
```

***

## Window Control [#window-control]

### setWindowTitle [#setwindowtitle]

Set terminal window title.

**Signature:**

```typescript
function setWindowTitle(title: string): string;
```

**Parameters:**

* `title` (`string`) - Window title

**Returns:** ANSI escape sequence string

**Example:**

```typescript
import { setWindowTitle } from "@visulima/ansi";
process.stdout.write(setWindowTitle("My App"));
```

***

### setIconName [#seticonname]

Set window icon name.

**Signature:**

```typescript
function setIconName(name: string): string;
```

**Parameters:**

* `name` (`string`) - Icon name

**Returns:** ANSI escape sequence string

***

### setIconNameAndWindowTitle [#seticonnameandwindowtitle]

Set both icon name and window title.

**Signature:**

```typescript
function setIconNameAndWindowTitle(title: string): string;
```

**Parameters:**

* `title` (`string`) - Title for both icon and window

**Returns:** ANSI escape sequence string

***

### Window Operations [#window-operations]

Control window state and position.

**Signatures:**

```typescript
const minimizeWindow: string;
const maximizeWindow: string;
const raiseWindow: string;
const lowerWindow: string;
const restoreWindow: string;
const refreshWindow: string;

function moveWindow(x: number, y: number): string;
function resizeTextAreaChars(width: number, height: number): string;
function resizeTextAreaPixels(width: number, height: number): string;
```

**Example:**

```typescript
import { maximizeWindow, moveWindow } from "@visulima/ansi";

process.stdout.write(maximizeWindow);
process.stdout.write(moveWindow(100, 100));
```

***

## Mouse Events [#mouse-events]

### Enable/Disable Mouse Tracking [#enabledisable-mouse-tracking]

**Signatures:**

```typescript
const enableNormalMouse: string;
const disableNormalMouse: string;
const enableButtonEventMouse: string;
const disableButtonEventMouse: string;
const enableAnyEventMouse: string;
const disableAnyEventMouse: string;
const enableX10Mouse: string;
const disableX10Mouse: string;
```

**Example:**

```typescript
import { enableNormalMouse, disableNormalMouse } from "@visulima/ansi";

// Enable mouse tracking
process.stdout.write(enableNormalMouse);

// ... handle mouse events ...

// Disable when done
process.stdout.write(disableNormalMouse);
```

***

## Terminal Modes [#terminal-modes]

### setMode / resetMode [#setmode--resetmode]

Set or reset terminal modes.

**Signatures:**

```typescript
function setMode(mode: string): string;
function resetMode(mode: string): string;
```

**Common Modes:**

* `"IRM"` - Insert/Replace Mode
* `"LNM"` - Line Feed/New Line Mode
* `"SRM"` - Send/Receive Mode
* `"KAM"` - Keyboard Action Mode

**Example:**

```typescript
import { setMode, resetMode } from "@visulima/ansi";

process.stdout.write(setMode("IRM"));
// ... do work in insert mode ...
process.stdout.write(resetMode("IRM"));
```

***

## Color Control [#color-control]

Set, query and reset the terminal's foreground, background and cursor colors (`OSC 10/11/12`, reset via `OSC 110/111/112`). Color strings may be X11 names (`"red"`), hex (`"#ff0000"`) or `XParseColor` strings (`"rgb:ff/00/00"`). Caller-supplied colors are sanitized to prevent escape-sequence injection.

**Signatures:**

```typescript
function setForegroundColor(color: string): string;
function setBackgroundColor(color: string): string;
function setCursorColor(color: string): string;

const requestForegroundColor: string;
const requestBackgroundColor: string;
const requestCursorColor: string;

const resetForegroundColor: string;
const resetBackgroundColor: string;
const resetCursorColor: string;
```

**Example:**

```typescript
import { setBackgroundColor, resetBackgroundColor } from "@visulima/ansi/background";

process.stdout.write(setBackgroundColor("#1e1e2e"));
// ... later ...
process.stdout.write(resetBackgroundColor);
```

***

## Shell Integration [#shell-integration]

### Working Directory (OSC 7) [#working-directory-osc-7]

Report the shell's current working directory so terminals (iTerm2, WezTerm, …) can open new tabs in the same place.

**Signature:**

```typescript
function notifyWorkingDirectory(host: string, ...paths: string[]): string;
const setWorkingDirectory: typeof notifyWorkingDirectory;
```

**Example:**

```typescript
import { notifyWorkingDirectory } from "@visulima/ansi/cwd";

process.stdout.write(notifyWorkingDirectory("", process.cwd()));
```

### FinalTerm Prompt Marks (OSC 133) [#finalterm-prompt-marks-osc-133]

Mark the structure of shell output (prompt / command / output boundaries) so terminals can offer jump-to-prompt and command-status features.

**Signatures:**

```typescript
function finalTerm(...pm: string[]): string;
function finalTermPrompt(...pm: string[]): string; // A
function finalTermCmdStart(...pm: string[]): string; // B
function finalTermCmdExecuted(...pm: string[]): string; // C
function finalTermCmdFinished(...pm: string[]): string; // D
```

***

## Notifications [#notifications]

Trigger desktop notifications using the simple `OSC 9` protocol or the extensible `OSC 99` protocol. Message, payload and metadata are sanitized to prevent escape-sequence injection.

**Signatures:**

```typescript
function notify(message: string): string; // OSC 9
function desktopNotification(payload: string, ...metadata: string[]): string; // OSC 99
```

**Example:**

```typescript
import { notify } from "@visulima/ansi/notification";

process.stdout.write(notify("Build finished"));
```

### urxvt Extensions (OSC 777) [#urxvt-extensions-osc-777]

Invoke rxvt-unicode Perl extensions.

```typescript
import urxvtExtension from "@visulima/ansi/urxvt";

process.stdout.write(urxvtExtension("notify", "title", "body"));
```

***

## Keypad Modes [#keypad-modes]

Switch the numeric keypad between application and numeric mode.

**Signatures:**

```typescript
const keypadApplicationMode: string; // DECKPAM, ESC =
const keypadNumericMode: string; // DECKPNM, ESC >
const DECKPAM: string;
const DECKPNM: string;
```

***

## Character Sets (SCS) [#character-sets-scs]

Designate a character set into one of the G0–G3 slots, plus locking-shift constants.

**Signatures:**

```typescript
function selectCharacterSet(gset: string, charset: string): string;
const SCS: typeof selectCharacterSet;

// G-set designators
const G0: string; // "("
const G1: string; // ")"
const G2: string; // "*"
const G3: string; // "+"

// Common charset identifiers
const DEC_SPECIAL_GRAPHICS: string; // "0"
const UNITED_KINGDOM: string; // "A"
const USASCII: string; // "B"

// Locking shifts
const LS0: string; // SI
const LS1: string; // SO
const LS1R: string;
const LS2: string;
const LS2R: string;
const LS3: string;
const LS3R: string;
```

**Example:**

```typescript
import { selectCharacterSet, G0, DEC_SPECIAL_GRAPHICS, USASCII } from "@visulima/ansi/charset";

process.stdout.write(selectCharacterSet(G0, DEC_SPECIAL_GRAPHICS)); // line-drawing mode
// ...
process.stdout.write(selectCharacterSet(G0, USASCII)); // back to ASCII
```

***

## Bracketed Paste [#bracketed-paste]

Markers a terminal emits around pasted text (`CSI 200~` / `CSI 201~`), plus a wrap helper.

**Signatures:**

```typescript
const bracketedPasteStart: string;
const bracketedPasteEnd: string;
function wrapBracketedPaste(text: string): string;
```

***

## Focus Events [#focus-events]

Events a terminal emits when the window gains/loses focus (DEC private mode 1004). Enable/disable reporting via `enableFocusTracking` / `disableFocusTracking` (from `@visulima/ansi/mouse`).

**Signatures:**

```typescript
const FOCUS: string; // CSI I
const BLUR: string; // CSI O
const focusInEvent: string;
const focusOutEvent: string;
```

***

## Graphics [#graphics]

Emit-only wrappers that frame already-encoded graphics payloads. They do **not** encode pixel/image data — the caller supplies encoded data (and, for Kitty, Base64 + chunking).

**Signatures:**

```typescript
// Sixel: DCS aspectRatio ; backgroundMode ; gridSize q payload ST
function sixelGraphics(aspectRatio: number, backgroundMode: number, gridSize: number, payload: string): string;

// Kitty graphics: APC _G options ; payload ST
function kittyGraphics(payload: string, ...options: string[]): string;
```

**Example:**

```typescript
import kittyGraphics from "@visulima/ansi/kitty-graphics";

// Transmit and display a Base64-encoded PNG already in `data`.
process.stdout.write(kittyGraphics(data, "a=T", "f=100"));
```

***

## Constants [#constants]

### Cursor Movement [#cursor-movement]

```typescript
const CURSOR_UP_1: string;
const CURSOR_DOWN_1: string;
const CURSOR_FORWARD_1: string;
const CURSOR_BACKWARD_1: string;
const CURSOR_TO_COLUMN_1: string;
```

### Screen Operations [#screen-operations]

```typescript
const ALT_SCREEN_ON: string;
const ALT_SCREEN_OFF: string;
const SCROLL_UP_1: string;
const SCROLL_DOWN_1: string;
```

### Cursor State [#cursor-state]

```typescript
const SAVE_CURSOR_DEC: string;
const RESTORE_CURSOR_DEC: string;
```

### Reset [#reset]

```typescript
const RESET_INITIAL_STATE: string;
const RIS: string; // Reset to Initial State
```

***

## Submodule Reference [#submodule-reference]

### Import by Category [#import-by-category]

All functions can be imported from specific submodules:

**Cursor:** `@visulima/ansi/cursor`

```typescript
import { cursorTo, cursorMove, cursorUp, cursorDown, cursorHide, cursorShow } from "@visulima/ansi/cursor";
```

**Clear:** `@visulima/ansi/clear`

```typescript
import { clearScreen, clearScreenAndHomeCursor, resetTerminal } from "@visulima/ansi/clear";
```

**Erase:** `@visulima/ansi/erase`

```typescript
import { eraseLine, eraseDown, eraseUp, eraseLines } from "@visulima/ansi/erase";
```

**Hyperlink:** `@visulima/ansi/hyperlink`

```typescript
import { hyperlink } from "@visulima/ansi/hyperlink";
```

**Image:** `@visulima/ansi/image`

```typescript
import { image } from "@visulima/ansi/image";
```

**Strip:** `@visulima/ansi/strip`

```typescript
import { strip } from "@visulima/ansi/strip";
```

**Other submodules:** `alternative-screen`, `scroll`, `title`, `window-ops`, `mouse`, `mode`, `status`, `iterm2`, `xterm`, `screen`, `passthrough`, `reset`, `background`, `cwd`, `finalterm`, `notification`, `urxvt`, `keypad`, `charset`, `paste`, `focus`, `sixel`, `kitty-graphics`

***

## Function Summary by Category [#function-summary-by-category]

| Category              | Key Functions                                                |
| --------------------- | ------------------------------------------------------------ |
| **Cursor Position**   | `cursorTo`, `cursorMove`, `cursorSave`, `cursorRestore`      |
| **Cursor Movement**   | `cursorUp`, `cursorDown`, `cursorForward`, `cursorBackward`  |
| **Cursor Visibility** | `cursorHide`, `cursorShow`, `setCursorStyle`                 |
| **Screen Clear**      | `clearScreen`, `eraseDown`, `eraseUp`                        |
| **Line Erase**        | `eraseLine`, `eraseLineEnd`, `eraseLineStart`, `eraseLines`  |
| **Screen Buffer**     | `alternativeScreenOn`, `alternativeScreenOff`                |
| **Scrolling**         | `scrollUp`, `scrollDown`                                     |
| **Hyperlinks**        | `hyperlink`                                                  |
| **Images**            | `image`                                                      |
| **Strip**             | `strip`                                                      |
| **Window**            | `setWindowTitle`, `maximizeWindow`, `moveWindow`             |
| **Mouse**             | `enableNormalMouse`, `disableNormalMouse`                    |
| **Modes**             | `setMode`, `resetMode`                                       |
| **Color**             | `setForegroundColor`, `setBackgroundColor`, `setCursorColor` |
| **Shell Integration** | `notifyWorkingDirectory`, `finalTermPrompt`                  |
| **Notifications**     | `notify`, `desktopNotification`, `urxvtExtension`            |
| **Keypad**            | `keypadApplicationMode`, `keypadNumericMode`                 |
| **Character Sets**    | `selectCharacterSet`, `SCS`                                  |
| **Paste**             | `bracketedPasteStart`, `wrapBracketedPaste`                  |
| **Focus**             | `FOCUS`, `BLUR`                                              |
| **Graphics**          | `sixelGraphics`, `kittyGraphics`                             |

***

## Terminal Support [#terminal-support]

| Feature            | iTerm2 | Terminal.app | Windows Terminal | VS Code |
| ------------------ | ------ | ------------ | ---------------- | ------- |
| Cursor Control     | ✅      | ✅            | ✅                | ✅       |
| Screen Clearing    | ✅      | ✅            | ✅                | ✅       |
| Alternative Screen | ✅      | ✅            | ✅                | ✅       |
| Hyperlinks         | ✅      | ✅            | ✅                | ✅       |
| Images             | ✅      | ❌            | ❌                | ❌       |
| Mouse Events       | ✅      | ✅            | ✅                | ✅       |
| Window Ops         | ✅      | ⚠️           | ⚠️               | ❌       |

✅ Full support | ⚠️ Partial support | ❌ Not supported

***

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/ansi/usage">
    Learn how to use these functions with examples
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/ansi)



# @visulima/ansi [#visulimaansi]

Comprehensive ANSI escape codes for terminal control. Take full control of your terminal output with cursor positioning, screen clearing, hyperlinks, images, and much more—all through simple, composable functions.

## Key Features [#key-features]

**Cursor Control**

* Position cursor anywhere on screen
* Move cursor in any direction
* Show, hide, and style cursor
* Save and restore cursor position

**Screen Manipulation**

* Clear screen or parts of it
* Alternative screen buffer support
* Scroll regions up and down
* Erase lines and characters

**Advanced Terminal Features**

* Clickable hyperlinks in terminal
* Display images (iTerm2 support)
* Mouse event tracking
* Terminal mode management
* Foreground/background/cursor color control (OSC 10/11/12)
* Shell integration (OSC 7 working directory, OSC 133 FinalTerm marks)
* Desktop notifications (OSC 9 / OSC 99 / urxvt OSC 777)
* Focus events, bracketed paste, keypad and character-set selection
* Sixel and Kitty graphics sequence wrappers

**Window and Title Control**

* Set window and icon titles
* Window operations (minimize, maximize, etc.)
* Report window state and position
* Status reporting

**Utility Functions**

* Strip ANSI codes from strings
* tmux passthrough support
* Terminal capability queries
* Cross-platform compatibility

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/ansi
```

Control the cursor:

```typescript
import { cursorUp, cursorLeft, cursorTo } from "@visulima/ansi";

// Move cursor up 2 rows and to the left
process.stdout.write(cursorUp(2) + cursorLeft);
// => '\u001B[2A\u001B[1000D'

// Move cursor to column 10, row 5
process.stdout.write(cursorTo(10, 5));
```

Clear the screen:

```typescript
import { clearScreen, eraseDown } from "@visulima/ansi";

// Clear entire screen
process.stdout.write(clearScreen);

// Clear from cursor to end of screen
process.stdout.write(eraseDown);
```

## Use Cases [#use-cases]

### Build Interactive CLI Applications [#build-interactive-cli-applications]

Create dynamic terminal UIs with precise cursor control:

```typescript
import { cursorTo, eraseLine, cursorHide, cursorShow } from "@visulima/ansi";

function updateProgress(percent: number) {
    process.stdout.write(cursorHide);
    process.stdout.write(cursorTo(0));
    process.stdout.write(eraseLine);
    process.stdout.write(`Progress: [${"=".repeat(percent / 2)}${" ".repeat(50 - percent / 2)}] ${percent}%`);

    if (percent === 100) {
        process.stdout.write("\n");
        process.stdout.write(cursorShow);
    }
}

// Simulate progress
for (let i = 0; i <= 100; i += 10) {
    updateProgress(i);
    await new Promise((resolve) => setTimeout(resolve, 200));
}
```

### Create Clickable Terminal Links [#create-clickable-terminal-links]

Add hyperlinks that work in modern terminals:

```typescript
import { hyperlink } from "@visulima/ansi";

const link = hyperlink("https://github.com/visulima", "Visit Visulima on GitHub");
console.log(link);
// Displays: Visit Visulima on GitHub (clickable in supported terminals)
```

### Display Images in Terminal [#display-images-in-terminal]

Show images directly in iTerm2:

```typescript
import { image } from "@visulima/ansi";
import { readFileSync } from "fs";

const imageData = readFileSync("logo.png");
process.stdout.write(
    image(imageData, {
        width: "50%",
        height: "auto",
    }),
);
```

### Clean ANSI Codes from Strings [#clean-ansi-codes-from-strings]

Strip ANSI codes for logging or processing:

```typescript
import { strip } from "@visulima/ansi";
import { cursorUp, cursorLeft } from "@visulima/ansi";

const withAnsi = `Hello ${cursorUp(2)}${cursorLeft} World`;
const cleaned = strip(withAnsi);

console.log(cleaned); // "Hello  World" (no ANSI codes)
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/ansi/installation">
    Learn about installation and import methods
  </Card>

  <Card title="Usage Guide" href="/docs/packages/ansi/usage">
    Explore ANSI codes organized by category
  </Card>

  <Card title="API Reference" href="/docs/packages/ansi/api">
    Complete API documentation for all functions
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package is designed for Node.js terminal applications:

* **Node.js:** ≥22.13 ≤25.x (full support)
* **Browsers:** Not applicable (terminal-specific functionality)
* **Deno/Bun:** Compatible with terminal-supporting runtimes

Requires a terminal that supports ANSI escape codes (most modern terminals).


# Installation (/docs/packages/ansi/installation)





# Installation [#installation]

Install the package using your preferred package manager:

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/ansi `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/ansi `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/ansi `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/ansi `
  </Tab>
</Tabs>

## Import Methods [#import-methods]

### Main Package Import [#main-package-import]

Import everything from the main entry point:

```typescript
import { cursorUp, cursorLeft, clearScreen, hyperlink } from "@visulima/ansi";

process.stdout.write(cursorUp(2) + cursorLeft);
process.stdout.write(clearScreen);
console.log(hyperlink("https://example.com", "Click here"));
```

### Submodule Imports [#submodule-imports]

Import from specific submodules for better tree-shaking:

```typescript
// Cursor functions
import { cursorUp, cursorLeft, cursorTo } from "@visulima/ansi/cursor";

// Screen clearing
import { clearScreen, clearScreenFromTopLeft } from "@visulima/ansi/clear";

// Erase functions
import { eraseLine, eraseDown } from "@visulima/ansi/erase";

// Hyperlinks
import { hyperlink } from "@visulima/ansi/hyperlink";

// Strip ANSI codes
import { strip } from "@visulima/ansi/strip";
```

### Available Submodules [#available-submodules]

The package provides these submodules for targeted imports:

* **`@visulima/ansi/cursor`** - Cursor positioning and movement
* **`@visulima/ansi/clear`** - Screen and line clearing
* **`@visulima/ansi/erase`** - Text erasure functions
* **`@visulima/ansi/hyperlink`** - Clickable terminal links
* **`@visulima/ansi/image`** - Image display (iTerm2)
* **`@visulima/ansi/strip`** - Strip ANSI codes
* **`@visulima/ansi/scroll`** - Scrolling control
* **`@visulima/ansi/alternative-screen`** - Alternative screen buffer
* **`@visulima/ansi/title`** - Window title control
* **`@visulima/ansi/window-ops`** - Window operations
* **`@visulima/ansi/mouse`** - Mouse event handling
* **`@visulima/ansi/mode`** - Terminal mode management
* **`@visulima/ansi/status`** - Status reporting
* **`@visulima/ansi/iterm2`** - iTerm2-specific features
* **`@visulima/ansi/xterm`** - XTerm-specific features
* **`@visulima/ansi/screen`** - Screen operations
* **`@visulima/ansi/passthrough`** - tmux/screen passthrough
* **`@visulima/ansi/reset`** - Terminal reset

### CommonJS [#commonjs]

For CommonJS environments:

```javascript
const { cursorUp, cursorLeft, clearScreen } = require("@visulima/ansi");

// Or from submodules
const { cursorUp } = require("@visulima/ansi/cursor");
```

## Requirements [#requirements]

* **Node.js:** ≥22.13 ≤25.x
* **Terminal:** ANSI escape code support (most modern terminals)
* **TypeScript:** ≥5.0 (optional, for type definitions)

## Verify Installation [#verify-installation]

Test the installation with a simple cursor movement:

```typescript
import { cursorUp, cursorLeft } from "@visulima/ansi";

// Move cursor up 2 rows and to the left
process.stdout.write(cursorUp(2) + cursorLeft);
console.log("Cursor moved!");
```

If you see the cursor move, installation was successful!

## TypeScript Support [#typescript-support]

The package includes comprehensive TypeScript type definitions:

```typescript
import type { CursorOptions } from "@visulima/ansi";
import { cursorTo, cursorMove } from "@visulima/ansi";

// Fully typed function calls
const position: string = cursorTo(10, 5);
const movement: string = cursorMove(2, 3);
```

## Terminal Compatibility [#terminal-compatibility]

ANSI escape codes work in most modern terminals:

**Full Support:**

* iTerm2 (macOS) - including images and extended features
* Terminal.app (macOS)
* GNOME Terminal (Linux)
* Konsole (Linux)
* Windows Terminal
* VS Code integrated terminal
* Hyper
* Alacritty
* Kitty

**Partial Support:**

* cmd.exe (Windows) - limited ANSI support
* PowerShell - basic ANSI support

**Not Supported:**

* Very old terminal emulators
* Non-interactive environments without TTY

To check if your terminal supports ANSI codes:

```typescript
import { cursorUp } from "@visulima/ansi";

const isTTY = process.stdout.isTTY;
const supportsAnsi = process.env.TERM !== "dumb" && isTTY;

if (supportsAnsi) {
    process.stdout.write(cursorUp(1));
} else {
    console.log("ANSI not supported");
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/ansi/usage">
    Learn how to use ANSI codes with examples
  </Card>

  <Card title="API Reference" href="/docs/packages/ansi/api">
    Explore the complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/ansi/usage)



# Usage Guide [#usage-guide]

Learn how to use ANSI escape codes to control your terminal output.

## Cursor Control [#cursor-control]

### Position Cursor [#position-cursor]

Move the cursor to specific coordinates:

```typescript
import { cursorTo } from "@visulima/ansi";

// Move to column 10, row 5
process.stdout.write(cursorTo(10, 5));
console.log("Text at position (10, 5)");

// Move to column 0 (start of line)
process.stdout.write(cursorTo(0));
console.log("Back to line start");
```

### Move Cursor Relative [#move-cursor-relative]

Move cursor relative to current position:

```typescript
import { cursorUp, cursorDown, cursorForward, cursorBackward } from "@visulima/ansi";

// Move up 3 lines
process.stdout.write(cursorUp(3));

// Move down 2 lines
process.stdout.write(cursorDown(2));

// Move forward 5 columns
process.stdout.write(cursorForward(5));

// Move backward 3 columns
process.stdout.write(cursorBackward(3));
```

Convenience shortcuts for single movements:

```typescript
import { cursorLeft, CURSOR_UP_1, CURSOR_DOWN_1 } from "@visulima/ansi";

// Move left to column 0
process.stdout.write(cursorLeft);

// Move up one line
process.stdout.write(CURSOR_UP_1);

// Move down one line
process.stdout.write(CURSOR_DOWN_1);
```

### Save and Restore Cursor [#save-and-restore-cursor]

Save cursor position and restore later:

```typescript
import { cursorSave, cursorRestore, cursorTo } from "@visulima/ansi";

// Save current position
process.stdout.write(cursorSave);

// Move somewhere else
process.stdout.write(cursorTo(20, 10));
console.log("Temporary text");

// Restore original position
process.stdout.write(cursorRestore);
console.log("Back to saved position");
```

### Show and Hide Cursor [#show-and-hide-cursor]

Control cursor visibility:

```typescript
import { cursorHide, cursorShow } from "@visulima/ansi";

// Hide cursor during operation
process.stdout.write(cursorHide);

// Do work...
console.log("Processing...");
await someLongOperation();

// Show cursor again
process.stdout.write(cursorShow);
```

### Style Cursor [#style-cursor]

Change cursor appearance:

```typescript
import { setCursorStyle } from "@visulima/ansi";

// Blinking block cursor
process.stdout.write(setCursorStyle("blinking-block"));

// Steady underline cursor
process.stdout.write(setCursorStyle("steady-underline"));

// Blinking bar cursor
process.stdout.write(setCursorStyle("blinking-bar"));
```

## Screen Manipulation [#screen-manipulation]

### Clear Screen [#clear-screen]

Clear the entire screen or parts of it:

```typescript
import { clearScreen, eraseDown, eraseUp } from "@visulima/ansi";

// Clear entire screen
process.stdout.write(clearScreen);

// Clear from cursor to end of screen
process.stdout.write(eraseDown);

// Clear from cursor to top of screen
process.stdout.write(eraseUp);
```

Clear and move cursor home:

```typescript
import { clearScreenAndHomeCursor, clearScreenFromTopLeft } from "@visulima/ansi";

// Clear and move to (0, 0)
process.stdout.write(clearScreenAndHomeCursor);

// Clear from top-left
process.stdout.write(clearScreenFromTopLeft);
```

### Clear Lines [#clear-lines]

Erase lines or parts of lines:

```typescript
import { eraseLine, eraseLineEnd, eraseLineStart } from "@visulima/ansi";

// Erase entire current line
process.stdout.write(eraseLine);

// Erase from cursor to end of line
process.stdout.write(eraseLineEnd);

// Erase from cursor to start of line
process.stdout.write(eraseLineStart);
```

Erase multiple lines:

```typescript
import { eraseLines } from "@visulima/ansi";

// Erase 3 lines
process.stdout.write(eraseLines(3));
```

### Alternative Screen [#alternative-screen]

Use alternative screen buffer (like vim/less):

```typescript
import { alternativeScreenOn, alternativeScreenOff } from "@visulima/ansi";

// Switch to alternative screen
process.stdout.write(alternativeScreenOn);

// Your full-screen app here
console.log("Full-screen interface");

// Switch back to normal screen
process.stdout.write(alternativeScreenOff);
```

### Scrolling [#scrolling]

Scroll screen regions:

```typescript
import { scrollUp, scrollDown } from "@visulima/ansi";

// Scroll up 5 lines
process.stdout.write(scrollUp(5));

// Scroll down 3 lines
process.stdout.write(scrollDown(3));
```

## Hyperlinks [#hyperlinks]

### Create Clickable Links [#create-clickable-links]

Make terminal output clickable:

```typescript
import { hyperlink } from "@visulima/ansi";

const link = hyperlink("https://github.com/visulima", "Visulima on GitHub");
console.log(`Check out ${link} for more info!`);
```

With IDs for duplicate links:

```typescript
import { hyperlink } from "@visulima/ansi";

const link1 = hyperlink("https://example.com", "Example 1", { id: "link-1" });
const link2 = hyperlink("https://example.com", "Example 2", { id: "link-2" });

console.log(link1);
console.log(link2);
```

## Images (iTerm2) [#images-iterm2]

### Display Images [#display-images]

Show images in iTerm2:

```typescript
import { image } from "@visulima/ansi";
import { readFileSync } from "fs";

const imageData = readFileSync("logo.png");

// Display image
process.stdout.write(
    image(imageData, {
        width: "50%",
        height: "auto",
        preserveAspectRatio: true,
    }),
);
```

Inline images:

```typescript
import { image } from "@visulima/ansi";
import { readFileSync } from "fs";

const icon = readFileSync("icon.png");

// Display inline with text
process.stdout.write(`Status: ${image(icon, { width: 20, height: 20, inline: true })} Complete`);
```

## Strip ANSI Codes [#strip-ansi-codes]

### Remove ANSI from Strings [#remove-ansi-from-strings]

Clean ANSI codes for logging or storage:

```typescript
import { strip } from "@visulima/ansi";
import { cursorUp, clearScreen } from "@visulima/ansi";

const withAnsi = `${clearScreen}Hello${cursorUp(2)} World`;
const cleaned = strip(withAnsi);

console.log(cleaned); // "Hello World" (no ANSI codes)
```

Useful for measuring actual text length:

```typescript
import { strip } from "@visulima/ansi";
import { hyperlink } from "@visulima/ansi";

const link = hyperlink("https://example.com", "Example");
const textOnly = strip(link);

console.log(link.length); // Long (includes ANSI codes)
console.log(textOnly.length); // 7 (just "Example")
```

## Window Control [#window-control]

### Set Window Title [#set-window-title]

Change terminal window title:

```typescript
import { setWindowTitle, setIconName } from "@visulima/ansi";

// Set window title
process.stdout.write(setWindowTitle("My CLI App"));

// Set icon name
process.stdout.write(setIconName("CLI"));
```

Set both at once:

```typescript
import { setIconNameAndWindowTitle } from "@visulima/ansi";

process.stdout.write(setIconNameAndWindowTitle("CLI App"));
```

### Window Operations [#window-operations]

Control window state (terminal support varies):

```typescript
import { minimizeWindow, maximizeWindow, raiseWindow, lowerWindow } from "@visulima/ansi";

// Minimize window
process.stdout.write(minimizeWindow);

// Maximize window
process.stdout.write(maximizeWindow);

// Bring window to front
process.stdout.write(raiseWindow);

// Send window to back
process.stdout.write(lowerWindow);
```

Move and resize window:

```typescript
import { moveWindow, resizeTextAreaChars } from "@visulima/ansi";

// Move window to position (100, 100)
process.stdout.write(moveWindow(100, 100));

// Resize to 80 columns, 24 rows
process.stdout.write(resizeTextAreaChars(80, 24));
```

## Mouse Events [#mouse-events]

### Enable Mouse Tracking [#enable-mouse-tracking]

Track mouse events in terminal:

```typescript
import { enableNormalMouse, disableNormalMouse } from "@visulima/ansi";
import { stdin } from "process";

// Enable mouse tracking
process.stdout.write(enableNormalMouse);

// Listen for mouse events
stdin.setRawMode(true);
stdin.on("data", (data) => {
    // Parse mouse event from data
    console.log("Mouse event:", data);
});

// Disable when done
process.on("exit", () => {
    process.stdout.write(disableNormalMouse);
    stdin.setRawMode(false);
});
```

Different mouse modes:

```typescript
import { enableButtonEventMouse, enableAnyEventMouse, enableX10Mouse } from "@visulima/ansi";

// Track button presses and releases
process.stdout.write(enableButtonEventMouse);

// Track all mouse movement
process.stdout.write(enableAnyEventMouse);

// Simple X10 mouse protocol
process.stdout.write(enableX10Mouse);
```

## Terminal Modes [#terminal-modes]

### Control Terminal Behavior [#control-terminal-behavior]

Enable and disable terminal modes:

```typescript
import { setMode, resetMode } from "@visulima/ansi";

// Enable insert mode
process.stdout.write(setMode("IRM"));

// Disable insert mode
process.stdout.write(resetMode("IRM"));
```

Common modes:

```typescript
import { SetLineFeedNewLineMode, ResetLineFeedNewLineMode } from "@visulima/ansi";

// Enable line feed/new line mode
process.stdout.write(SetLineFeedNewLineMode);

// Disable it
process.stdout.write(ResetLineFeedNewLineMode);
```

## Real-World Examples [#real-world-examples]

### Progress Bar [#progress-bar]

Create an updating progress bar:

```typescript
import { cursorHide, cursorShow, cursorTo, eraseLine } from "@visulima/ansi";

function showProgress(current: number, total: number) {
    const percent = Math.floor((current / total) * 100);
    const filled = Math.floor(percent / 2);
    const bar = "█".repeat(filled) + "░".repeat(50 - filled);

    process.stdout.write(cursorHide);
    process.stdout.write(cursorTo(0));
    process.stdout.write(eraseLine);
    process.stdout.write(`Progress: [${bar}] ${percent}%`);

    if (current === total) {
        process.stdout.write("\n");
        process.stdout.write(cursorShow);
    }
}

// Use it
for (let i = 0; i <= 100; i++) {
    showProgress(i, 100);
    await new Promise((resolve) => setTimeout(resolve, 50));
}
```

### Spinner Animation [#spinner-animation]

Create a loading spinner:

```typescript
import { cursorHide, cursorShow, cursorBackward, eraseLine } from "@visulima/ansi";

const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

async function spinner(message: string, duration: number) {
    process.stdout.write(cursorHide);

    let frame = 0;
    const interval = setInterval(() => {
        process.stdout.write(cursorBackward(100));
        process.stdout.write(eraseLine);
        process.stdout.write(`${frames[frame]} ${message}`);
        frame = (frame + 1) % frames.length;
    }, 80);

    await new Promise((resolve) => setTimeout(resolve, duration));

    clearInterval(interval);
    process.stdout.write(cursorBackward(100));
    process.stdout.write(eraseLine);
    process.stdout.write(cursorShow);
}

// Use it
await spinner("Loading...", 3000);
console.log("✓ Complete!");
```

### Interactive Menu [#interactive-menu]

Build a simple menu with cursor control:

```typescript
import { cursorHide, cursorShow, cursorUp, cursorTo, eraseLine } from "@visulima/ansi";

const options = ["Option 1", "Option 2", "Option 3", "Exit"];
let selected = 0;

function drawMenu() {
    console.log("\nSelect an option:");
    options.forEach((option, index) => {
        const prefix = index === selected ? ">" : " ";
        console.log(`${prefix} ${option}`);
    });
}

function updateMenu() {
    process.stdout.write(cursorUp(options.length + 1));
    process.stdout.write(cursorTo(0));

    options.forEach((option, index) => {
        process.stdout.write(eraseLine);
        const prefix = index === selected ? ">" : " ";
        console.log(`${prefix} ${option}`);
    });
}

// Initial draw
drawMenu();

// Handle keyboard input
process.stdin.setRawMode(true);
process.stdin.on("data", (data) => {
    const key = data.toString();

    if (key === "\u001b[A") {
        // Up arrow
        selected = Math.max(0, selected - 1);
        updateMenu();
    } else if (key === "\u001b[B") {
        // Down arrow
        selected = Math.min(options.length - 1, selected + 1);
        updateMenu();
    } else if (key === "\r") {
        // Enter
        console.log(`\nYou selected: ${options[selected]}`);
        process.exit(0);
    } else if (key === "\u0003") {
        // Ctrl+C
        process.exit(0);
    }
});
```

### Full-Screen App [#full-screen-app]

Create a full-screen terminal application:

```typescript
import { alternativeScreenOn, alternativeScreenOff, clearScreen, cursorTo, cursorHide, cursorShow } from "@visulima/ansi";

async function fullScreenApp() {
    // Enter alternative screen
    process.stdout.write(alternativeScreenOn);
    process.stdout.write(clearScreen);
    process.stdout.write(cursorHide);

    // Draw UI
    process.stdout.write(cursorTo(0, 0));
    console.log("┌────────────────────────────┐");
    console.log("│   My Full-Screen App       │");
    console.log("└────────────────────────────┘");

    // Wait for input
    await new Promise((resolve) => {
        process.stdin.setRawMode(true);
        process.stdin.once("data", resolve);
    });

    // Clean up
    process.stdout.write(cursorShow);
    process.stdout.write(alternativeScreenOff);
    process.stdin.setRawMode(false);
}

// Run it
await fullScreenApp();
```

### Status Updates [#status-updates]

Update status line without scrolling:

```typescript
import { cursorSave, cursorRestore, cursorTo, eraseLine } from "@visulima/ansi";

let statusLine = 0;

function setStatus(message: string) {
    process.stdout.write(cursorSave);
    process.stdout.write(cursorTo(0, statusLine));
    process.stdout.write(eraseLine);
    process.stdout.write(`Status: ${message}`);
    process.stdout.write(cursorRestore);
}

// Use it
console.log("Starting process...");
statusLine = 1;

setStatus("Initializing...");
await delay(1000);

console.log("Doing work...");

setStatus("Processing...");
await delay(2000);

setStatus("Complete!");
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/ansi/api">
    Complete API documentation for all functions
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# API Reference (/docs/packages/boxen/api)



# API Reference [#api-reference]

Complete API documentation for **@visulima/boxen**.

## Import [#import]

```typescript
import { boxen } from "@visulima/boxen";
import type { Options, BorderStyle } from "@visulima/boxen";
```

## Main Function [#main-function]

### `boxen(text: string, options?: Options): string` [#boxentext-string-options-options-string]

Create a box around text with customizable options.

**Parameters:**

* `text` (string): Content to display inside the box
* `options` (Options, optional): Configuration options

**Returns:** String containing the formatted box

**Example:**

```typescript
const box = boxen("Hello!", { padding: 1 });
console.log(box);
```

***

## Options [#options]

### `borderStyle` [#borderstyle]

Type: `string | BorderStyleObject`
Default: `"single"`

Border style to use. Can be a built-in style name or custom border characters.

**Built-in Styles:**

* `"single"` - Single line border (default)
* `"double"` - Double line border
* `"round"` - Rounded corners
* `"bold"` - Bold border
* `"singleDouble"` - Single horizontal, double vertical
* `"doubleSingle"` - Double horizontal, single vertical
* `"classic"` - Plus and pipe characters
* `"arrow"` - Arrow characters

**Custom Border:**

```typescript
{
    topLeft: string;
    topRight: string;
    bottomLeft: string;
    bottomRight: string;
    top: string;
    bottom: string;
    left: string;
    right: string;
}
```

**Example:**

```typescript
// Built-in style
boxen("text", { borderStyle: "double" });

// Custom border
boxen("text", {
    borderStyle: {
        topLeft: "╭",
        topRight: "╮",
        bottomLeft: "╰",
        bottomRight: "╯",
        top: "─",
        bottom: "─",
        left: "│",
        right: "│",
    },
});
```

***

### `borderColor` [#bordercolor]

Type: `(border: string, position: BorderPosition, length: number) => string`

Function to colorize border characters. Called for each border segment.

**Parameters:**

* `border` (string): The border character(s)
* `position` (BorderPosition): Position of the border
* `length` (number): Length of the border segment

**BorderPosition Type:**

```typescript
type BorderPosition = "topLeft" | "top" | "topRight" | "left" | "right" | "bottomLeft" | "bottom" | "bottomRight";
```

**Example:**

```typescript
import { red, green } from "@visulima/colorize";

boxen("text", {
    borderColor: (border, position) => {
        if (position.includes("top")) {
            return red(border);
        }
        return green(border);
    },
});
```

***

### `padding` [#padding]

Type: `number | number[] | PaddingObject`
Default: `0`

Space inside the box between content and border.

**Number:** Apply same padding to all sides

```typescript
{
    padding: 1;
}
```

**Array:**

```typescript
{
    padding: [1, 2];
} // top/bottom: 1, left/right: 2
{
    padding: [1, 2, 3];
} // top: 1, left/right: 2, bottom: 3
{
    padding: [1, 2, 3, 4];
} // top: 1, right: 2, bottom: 3, left: 4
```

**Object:**

```typescript
{
    padding: {
        top: 1,
        right: 2,
        bottom: 1,
        left: 2,
    }
}
```

**Example:**

```typescript
boxen("text", { padding: 1 });
boxen("text", { padding: [1, 2] });
boxen("text", { padding: { top: 1, bottom: 1 } });
```

***

### `margin` [#margin]

Type: `number | number[] | MarginObject`
Default: `0`

Space outside the box.

**Number:** Apply same margin to all sides

```typescript
{
    margin: 1;
}
```

**Array:** Same format as padding

**Object:**

```typescript
{
    margin: {
        top: 1,
        right: 2,
        bottom: 1,
        left: 2,
    }
}
```

**Example:**

```typescript
boxen("text", { margin: 1 });
boxen("text", { margin: [1, 0] }); // top/bottom only
```

***

### `textAlignment` [#textalignment]

Type: `"left" | "center" | "right"`
Default: `"left"`

Horizontal alignment of text within the box.

**Example:**

```typescript
boxen("Center me", { textAlignment: "center" });
boxen("Right align", { textAlignment: "right" });
```

***

### `headerText` [#headertext]

Type: `string`
Default: `undefined`

Text to display in the top border.

**Example:**

```typescript
boxen("Content", {
    headerText: "Title",
    headerAlignment: "center",
});
```

***

### `headerAlignment` [#headeralignment]

Type: `"left" | "center" | "right"`
Default: `"left"`

Alignment of header text in the top border.

**Example:**

```typescript
boxen("Content", {
    headerText: "Status",
    headerAlignment: "center",
});
```

***

### `footerText` [#footertext]

Type: `string`
Default: `undefined`

Text to display in the bottom border.

**Example:**

```typescript
boxen("Content", {
    footerText: "Press Enter",
    footerAlignment: "center",
});
```

***

### `footerAlignment` [#footeralignment]

Type: `"left" | "center" | "right"`
Default: `"left"`

Alignment of footer text in the bottom border.

**Example:**

```typescript
boxen("Content", {
    footerText: "v1.0.0",
    footerAlignment: "right",
});
```

***

### `width` [#width]

Type: `number | "terminal"`
Default: Automatic based on content

Fixed width for the box. Set to `"terminal"` to use full terminal width.

**Example:**

```typescript
// Fixed width (content wraps)
boxen("Long text that will wrap", { width: 20 });

// Full terminal width
boxen("Full width", { width: "terminal" });
```

***

## TypeScript Types [#typescript-types]

### `Options` [#options-1]

Complete options interface:

```typescript
interface Options {
    borderStyle?: BorderStyle | BorderStyleObject;
    borderColor?: (border: string, position: BorderPosition, length: number) => string;
    padding?: number | number[] | PaddingObject;
    margin?: number | number[] | MarginObject;
    textAlignment?: "left" | "center" | "right";
    headerText?: string;
    headerAlignment?: "left" | "center" | "right";
    footerText?: string;
    footerAlignment?: "left" | "center" | "right";
    width?: number | "terminal";
}
```

### `BorderStyle` [#borderstyle-1]

Built-in border style names:

```typescript
type BorderStyle = "single" | "double" | "round" | "bold" | "singleDouble" | "doubleSingle" | "classic" | "arrow";
```

### `BorderStyleObject` [#borderstyleobject]

Custom border characters:

```typescript
interface BorderStyleObject {
    topLeft: string;
    topRight: string;
    bottomLeft: string;
    bottomRight: string;
    top: string;
    bottom: string;
    left: string;
    right: string;
}
```

### `BorderPosition` [#borderposition]

Border segment positions:

```typescript
type BorderPosition = "topLeft" | "top" | "topRight" | "left" | "right" | "bottomLeft" | "bottom" | "bottomRight";
```

### `PaddingObject` [#paddingobject]

Padding configuration:

```typescript
interface PaddingObject {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
}
```

### `MarginObject` [#marginobject]

Margin configuration:

```typescript
interface MarginObject {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
}
```

## Complete Example [#complete-example]

```typescript
import { boxen } from "@visulima/boxen";
import type { Options } from "@visulima/boxen";
import { green, blue } from "@visulima/colorize";

const options: Options = {
    // Border
    borderStyle: "double",
    borderColor: (border, position) => {
        if (position.includes("top")) {
            return blue(border);
        }
        return green(border);
    },

    // Layout
    padding: 1,
    margin: { top: 1, bottom: 1 },
    width: 40,

    // Text
    textAlignment: "center",

    // Header/Footer
    headerText: "Status",
    headerAlignment: "center",
    footerText: "v1.0.0",
    footerAlignment: "right",
};

console.log(boxen("All options used!", options));
```


# Introduction (/docs/packages/boxen)



# @visulima/boxen [#visulimaboxen]

Create beautiful boxes in the terminal with customizable borders, padding, and alignment. Perfect for highlighting messages, creating banners, and improving CLI application aesthetics.

## Why @visulima/boxen? [#why-visulimaboxen]

Terminal boxes make your CLI output more professional and easier to read. **@visulima/boxen** provides:

* **Multiple border styles** - Single, double, round, bold, and more
* **Custom coloring** - Color different parts of the border independently
* **Flexible layout** - Configure padding, margins, and text alignment
* **Headers and footers** - Add labeled sections to your boxes
* **TypeScript support** - Full type definitions included
* **Cross-platform** - Works on Windows, macOS, and Linux

## Key Features [#key-features]

**Border Styles**

* **8 built-in styles** - single, double, round, bold, and mixed styles
* **Custom borders** - Define your own border characters
* **Position-based coloring** - Different colors for each border section

**Layout Control**

* **Padding** - Add space inside the box (top, right, bottom, left)
* **Margins** - Add space outside the box
* **Text alignment** - left, center, or right alignment
* **Fixed width** - Set maximum box width

**Headers & Footers**

* **Header text** - Add labeled headers with alignment
* **Footer text** - Add labeled footers with alignment
* **Custom positioning** - Align headers and footers independently

**Advanced Features**

* **Gradient borders** - Create colorful gradient effects
* **Multi-line support** - Automatic handling of multi-line text
* **Width calculation** - Automatic sizing based on content

## Quick Start [#quick-start]

### Installation [#installation]

```bash npm2yarn
npm install @visulima/boxen
```

### Basic Usage [#basic-usage]

```typescript
import { boxen } from "@visulima/boxen";

// Simple box
console.log(boxen("Hello, World!"));
// Output:
// ┌─────────────┐
// │Hello, World!│
// └─────────────┘

// With padding
console.log(boxen("unicorn", { padding: 1 }));
// Output:
// ┌─────────────┐
// │             │
// │   unicorn   │
// │             │
// └─────────────┘
```

## Use Cases [#use-cases]

### CLI Messages [#cli-messages]

Highlight important messages in your CLI applications:

```typescript
import { boxen } from "@visulima/boxen";
import { green, red, yellow } from "@visulima/colorize";

// Success message
console.log(
    boxen(green("✓ Build completed successfully!"), {
        padding: 1,
        borderStyle: "round",
        borderColor: () => green("─"),
    }),
);

// Error message
console.log(
    boxen(red("✗ Build failed: Missing configuration"), {
        padding: 1,
        borderStyle: "double",
        borderColor: () => red("═"),
    }),
);

// Warning message
console.log(
    boxen(yellow("⚠ Deprecated API usage detected"), {
        padding: 1,
        borderStyle: "bold",
    }),
);
```

### Application Banners [#application-banners]

Create eye-catching banners for your CLI tools:

```typescript
import { boxen } from "@visulima/boxen";
import { cyan, bold } from "@visulima/colorize";

const banner = boxen(bold(cyan("MyApp CLI v2.0.0\n")) + "Build amazing applications\n" + "https://myapp.com", {
    padding: 1,
    margin: 1,
    borderStyle: "double",
    textAlignment: "center",
});

console.log(banner);
```

### Update Notifications [#update-notifications]

Display update notifications with clear formatting:

```typescript
import { boxen } from "@visulima/boxen";
import { yellow, green } from "@visulima/colorize";

console.log(
    boxen(yellow("Update available: ") + "v2.0.0 → " + green("v2.1.0") + "\n" + "Run " + green("npm install -g myapp") + " to update", {
        padding: 1,
        margin: 1,
        borderStyle: "round",
        headerText: "Update Notification",
        headerAlignment: "center",
    }),
);
```

### Configuration Summaries [#configuration-summaries]

Display configuration or status information:

```typescript
import { boxen } from "@visulima/boxen";
import { gray, cyan } from "@visulima/colorize";

const config = [
    `${gray("Environment:")} ${cyan("production")}`,
    `${gray("Port:")} ${cyan("3000")}`,
    `${gray("Database:")} ${cyan("postgres://localhost:5432")}`,
    `${gray("Cache:")} ${cyan("enabled")}`,
].join("\n");

console.log(
    boxen(config, {
        padding: 1,
        headerText: "Server Configuration",
        headerAlignment: "center",
        footerText: "Press Ctrl+C to stop",
        footerAlignment: "center",
    }),
);
```

## Visual Examples [#visual-examples]

### Border Styles [#border-styles]

```typescript
import { boxen } from "@visulima/boxen";

// Single border (default)
boxen("single", { borderStyle: "single" });
// ┌──────┐
// │single│
// └──────┘

// Double border
boxen("double", { borderStyle: "double" });
// ╔══════╗
// ║double║
// ╚══════╝

// Round corners
boxen("round", { borderStyle: "round" });
// ╭─────╮
// │round│
// ╰─────╯

// Bold border
boxen("bold", { borderStyle: "bold" });
// ┏━━━━┓
// ┃bold┃
// ┗━━━━┛
```

### With Padding and Margins [#with-padding-and-margins]

```typescript
import { boxen } from "@visulima/boxen";

// Padding adds space inside
boxen("padded", { padding: 1 });
// ┌────────┐
// │        │
// │ padded │
// │        │
// └────────┘

// Margins add space outside
boxen("margin", { margin: 1 });
//
//   ┌──────┐
//   │margin│
//   └──────┘
//
```

### Text Alignment [#text-alignment]

```typescript
import { boxen } from "@visulima/boxen";

// Left aligned (default)
boxen("Left\nAligned\nText", { textAlignment: "left" });

// Center aligned
boxen("Center\nAligned\nText", { textAlignment: "center" });

// Right aligned
boxen("Right\nAligned\nText", { textAlignment: "right" });
```

## Comparison [#comparison]

### vs. boxen (original) [#vs-boxen-original]

| Feature                 | @visulima/boxen | boxen |
| ----------------------- | --------------- | ----- |
| Border styles           | ✅               | ✅     |
| Custom colors           | ✅               | ✅     |
| Headers/footers         | ✅               | ✅     |
| TypeScript native       | ✅               | ⚠️    |
| Position-based coloring | ✅               | ❌     |
| Gradient borders        | ✅               | ❌     |
| Modern ESM              | ✅               | ⚠️    |
| Active maintenance      | ✅               | ⚠️    |

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/boxen/installation">
    Learn how to install and set up boxen
  </Card>

  <Card title="Quick Start" href="/docs/packages/boxen/quick-start">
    Create your first terminal box in 5 minutes
  </Card>

  <Card title="Usage Guide" href="/docs/packages/boxen/usage">
    Explore all border styles and options
  </Card>

  <Card title="API Reference" href="/docs/packages/boxen/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

### Node.js [#nodejs]

* ✅ Node.js 22.13 - 25.x
* ✅ ESM and CommonJS support

### Operating Systems [#operating-systems]

* ✅ Windows (including Command Prompt and PowerShell)
* ✅ macOS
* ✅ Linux
* ✅ Any terminal with Unicode support


# Installation (/docs/packages/boxen/installation)



# Installation [#installation]

## Package Manager [#package-manager]

Install **@visulima/boxen** using your preferred package manager:

```bash npm2yarn
npm install @visulima/boxen
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0+ (optional, for TypeScript projects)
* **Terminal:** Unicode support recommended for best visual results

## Import Methods [#import-methods]

### Node.js (ESM) [#nodejs-esm]

```typescript
// Named import (recommended)
import { boxen } from "@visulima/boxen";

console.log(boxen("Hello, World!"));
```

### Node.js (CommonJS) [#nodejs-commonjs]

```javascript
// CommonJS import
const { boxen } = require("@visulima/boxen");

console.log(boxen("Hello, World!"));
```

### TypeScript [#typescript]

TypeScript definitions are included automatically:

```typescript
import { boxen } from "@visulima/boxen";
import type { Options } from "@visulima/boxen";

const options: Options = {
    padding: 1,
    borderStyle: "double",
};

console.log(boxen("Typed!", options));
```

## Optional: Color Support [#optional-color-support]

For colored borders, install **@visulima/colorize**:

```bash npm2yarn
npm install @visulima/colorize
```

Then use colors in your boxes:

```typescript
import { boxen } from "@visulima/boxen";
import { green, blue } from "@visulima/colorize";

console.log(
    boxen(green("Success!"), {
        borderColor: () => green("─"),
    }),
);
```

## Verification [#verification]

Verify your installation works correctly:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Installation successful!", {
        padding: 1,
        borderStyle: "double",
    }),
);
// Output:
// ╔═══════════════════════════╗
// ║                           ║
// ║ Installation successful!  ║
// ║                           ║
// ╚═══════════════════════════╝
```

If you see a box similar to above, installation is successful!

## Terminal Compatibility [#terminal-compatibility]

### Unicode Support [#unicode-support]

For best results, use a terminal with full Unicode support:

**Recommended Terminals:**

* ✅ Windows Terminal (Windows 10+)
* ✅ iTerm2 (macOS)
* ✅ Terminal.app (macOS)
* ✅ GNOME Terminal (Linux)
* ✅ Konsole (Linux)
* ✅ Hyper
* ✅ Alacritty

**Limited Support:**

* ⚠️ Windows Command Prompt (Windows 10+ with Unicode enabled)
* ⚠️ PowerShell (works with PowerShell 7+)

### Fallback for Limited Terminals [#fallback-for-limited-terminals]

If your terminal doesn't support Unicode box-drawing characters, use ASCII-only border styles:

```typescript
import { boxen } from "@visulima/boxen";

// Custom ASCII border
console.log(
    boxen("ASCII only", {
        borderStyle: {
            topLeft: "+",
            topRight: "+",
            bottomLeft: "+",
            bottomRight: "+",
            top: "-",
            bottom: "-",
            left: "|",
            right: "|",
        },
    }),
);
// Output:
// +----------+
// |ASCII only|
// +----------+
```

## Troubleshooting [#troubleshooting]

### Characters Not Displaying Correctly [#characters-not-displaying-correctly]

If box characters appear as question marks or squares:

1. **Check terminal encoding:**

   ```bash
   echo $LANG
   # Should show UTF-8 (e.g., en_US.UTF-8)
   ```

2. **Set UTF-8 encoding:**

   ```bash
   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8
   ```

3. **Use a different terminal** with better Unicode support

### Module Not Found [#module-not-found]

If you see `Cannot find module '@visulima/boxen'`:

```bash npm2yarn
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

### TypeScript Errors [#typescript-errors]

Ensure your `tsconfig.json` includes:

```json
{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true,
        "module": "ES2020"
    }
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Quick Start" href="/docs/packages/boxen/quick-start">
    Create your first box in 5 minutes
  </Card>

  <Card title="Usage Guide" href="/docs/packages/boxen/usage">
    Learn about all available options
  </Card>
</Cards>


# Quick Start (/docs/packages/boxen/quick-start)



# Quick Start [#quick-start]

Learn the essentials of **@visulima/boxen** in 5 minutes.

## Installation [#installation]

```bash npm2yarn
npm install @visulima/boxen
```

## Basic Box [#basic-box]

Create a simple box around text:

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("Hello, World!"));
```

Output:

```
┌─────────────┐
│Hello, World!│
└─────────────┘
```

## Add Padding [#add-padding]

Add space inside the box:

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("Padded", { padding: 1 }));
```

Output:

```
┌────────┐
│        │
│ Padded │
│        │
└────────┘
```

## Change Border Style [#change-border-style]

Use different border styles:

```typescript
import { boxen } from "@visulima/boxen";

// Double border
console.log(boxen("Double", { borderStyle: "double" }));
// Output:
// ╔══════╗
// ║Double║
// ╚══════╝

// Round corners
console.log(boxen("Round", { borderStyle: "round" }));
// Output:
// ╭─────╮
// │Round│
// ╰─────╯

// Bold border
console.log(boxen("Bold", { borderStyle: "bold" }));
// Output:
// ┏━━━━┓
// ┃Bold┃
// ┗━━━━┛
```

## Add Colors [#add-colors]

Color your boxes with @visulima/colorize:

```bash npm2yarn
npm install @visulima/colorize
```

```typescript
import { boxen } from "@visulima/boxen";
import { green, red, blue } from "@visulima/colorize";

// Colored text
console.log(boxen(green("Success!"), { padding: 1 }));

// Colored border
console.log(
    boxen("Important", {
        borderColor: () => red("─"),
        padding: 1,
    }),
);

// Both colored
console.log(
    boxen(blue("Information"), {
        borderColor: () => blue("─"),
        padding: 1,
    }),
);
```

## Add Margins [#add-margins]

Add space outside the box:

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("With margin", { margin: 1 }));
```

Output:

```

   ┌───────────┐
   │With margin│
   └───────────┘

```

## Text Alignment [#text-alignment]

Control text alignment inside the box:

```typescript
import { boxen } from "@visulima/boxen";

// Center aligned
console.log(
    boxen("Center\nAligned", {
        textAlignment: "center",
        padding: 1,
    }),
);

// Right aligned
console.log(
    boxen("Right\nAligned", {
        textAlignment: "right",
        padding: 1,
    }),
);
```

## Add Headers [#add-headers]

Add a labeled header to your box:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Important message here", {
        headerText: "Alert",
        headerAlignment: "center",
        padding: 1,
    }),
);
```

Output:

```
┌───── Alert ─────┐
│                 │
│ Important       │
│ message here    │
│                 │
└─────────────────┘
```

## Add Footers [#add-footers]

Add a footer with additional information:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Build completed successfully", {
        headerText: "Status",
        footerText: "Press any key to continue",
        footerAlignment: "center",
        padding: 1,
    }),
);
```

## Multi-line Content [#multi-line-content]

Boxes automatically handle multi-line text:

```typescript
import { boxen } from "@visulima/boxen";

const message = `Line 1
Line 2
Line 3`;

console.log(boxen(message, { padding: 1 }));
```

Output:

```
┌────────┐
│        │
│ Line 1 │
│ Line 2 │
│ Line 3 │
│        │
└────────┘
```

## Set Fixed Width [#set-fixed-width]

Control the box width:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("This text will wrap to fit within the width", {
        width: 20,
        padding: 1,
    }),
);
```

## Common Patterns [#common-patterns]

### Success Message [#success-message]

```typescript
import { boxen } from "@visulima/boxen";
import { green } from "@visulima/colorize";

console.log(
    boxen(green("✓ Build completed successfully!"), {
        padding: 1,
        borderStyle: "round",
        borderColor: () => green("─"),
    }),
);
```

### Error Message [#error-message]

```typescript
import { boxen } from "@visulima/boxen";
import { red } from "@visulima/colorize";

console.log(
    boxen(red("✗ Build failed: Missing dependencies"), {
        padding: 1,
        borderStyle: "double",
        borderColor: () => red("═"),
    }),
);
```

### Warning Message [#warning-message]

```typescript
import { boxen } from "@visulima/boxen";
import { yellow } from "@visulima/colorize";

console.log(
    boxen(yellow("⚠ Deprecation warning"), {
        padding: 1,
        borderStyle: "bold",
        borderColor: () => yellow("━"),
    }),
);
```

### Application Banner [#application-banner]

```typescript
import { boxen } from "@visulima/boxen";
import { cyan, bold } from "@visulima/colorize";

const banner = bold(cyan("MyApp CLI v1.0.0"));
const tagline = "Build amazing applications";

console.log(
    boxen(`${banner}\n${tagline}`, {
        padding: 1,
        margin: 1,
        borderStyle: "double",
        textAlignment: "center",
    }),
);
```

### Status Display [#status-display]

```typescript
import { boxen } from "@visulima/boxen";
import { green, gray } from "@visulima/colorize";

const status = [`${gray("Server:")} ${green("Running")}`, `${gray("Port:")} ${green("3000")}`, `${gray("Environment:")} ${green("production")}`].join("\n");

console.log(
    boxen(status, {
        padding: 1,
        headerText: "Server Status",
        headerAlignment: "center",
    }),
);
```

### Update Notification [#update-notification]

```typescript
import { boxen } from "@visulima/boxen";
import { yellow, green } from "@visulima/colorize";

console.log(
    boxen(`${yellow("Update available:")} v1.0.0 → ${green("v1.1.0")}\n` + `Run ${green("npm update")} to upgrade`, {
        padding: 1,
        margin: 1,
        borderStyle: "round",
        headerText: "Update",
        headerAlignment: "center",
    }),
);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/boxen/usage">
    Explore all border styles and options
  </Card>

  <Card title="API Reference" href="/docs/packages/boxen/api">
    Complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/boxen/usage)



# Usage Guide [#usage-guide]

Complete guide to using **@visulima/boxen** for creating terminal boxes.

## Border Styles [#border-styles]

### Built-in Styles [#built-in-styles]

**single** (default):

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("single", { borderStyle: "single" }));
```

Output:

```
┌──────┐
│single│
└──────┘
```

**double**:

```typescript
console.log(boxen("double", { borderStyle: "double" }));
```

Output:

```
╔══════╗
║double║
╚══════╝
```

**round**:

```typescript
console.log(boxen("round", { borderStyle: "round" }));
```

Output:

```
╭─────╮
│round│
╰─────╯
```

**bold**:

```typescript
console.log(boxen("bold", { borderStyle: "bold" }));
```

Output:

```
┏━━━━┓
┃bold┃
┗━━━━┛
```

**singleDouble** (single horizontal, double vertical):

```typescript
console.log(boxen("singleDouble", { borderStyle: "singleDouble" }));
```

Output:

```
╓────────────╖
║singleDouble║
╙────────────╜
```

**doubleSingle** (double horizontal, single vertical):

```typescript
console.log(boxen("doubleSingle", { borderStyle: "doubleSingle" }));
```

Output:

```
╒════════════╕
│doubleSingle│
╘════════════╛
```

**classic**:

```typescript
console.log(boxen("classic", { borderStyle: "classic" }));
```

Output:

```
+───────+
|classic|
+───────+
```

**arrow**:

```typescript
console.log(boxen("arrow", { borderStyle: "arrow" }));
```

Output:

```
↘↓↓↓↓↓↙
→arrow←
↗↑↑↑↑↑↖
```

### Custom Border Characters [#custom-border-characters]

Define your own border style:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("custom", {
        borderStyle: {
            topLeft: "╭",
            topRight: "╮",
            bottomLeft: "╰",
            bottomRight: "╯",
            top: "─",
            bottom: "─",
            left: "│",
            right: "│",
        },
    }),
);
```

## Padding and Margins [#padding-and-margins]

### Padding (Space Inside Box) [#padding-space-inside-box]

**Uniform padding:**

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("padded", { padding: 1 }));
```

Output:

```
┌────────┐
│        │
│ padded │
│        │
└────────┘
```

**Individual sides:**

```typescript
console.log(
    boxen("custom padding", {
        padding: {
            top: 1,
            right: 2,
            bottom: 1,
            left: 2,
        },
    }),
);
```

**Shorthand:**

```typescript
// Same as { top: 1, right: 2, bottom: 1, left: 2 }
boxen("text", { padding: [1, 2] });

// Same as { top: 1, right: 2, bottom: 3, left: 2 }
boxen("text", { padding: [1, 2, 3] });

// Same as { top: 1, right: 2, bottom: 3, left: 4 }
boxen("text", { padding: [1, 2, 3, 4] });
```

### Margins (Space Outside Box) [#margins-space-outside-box]

**Uniform margin:**

```typescript
import { boxen } from "@visulima/boxen";

console.log(boxen("margin", { margin: 1 }));
```

Output:

```

   ┌──────┐
   │margin│
   └──────┘

```

**Individual sides:**

```typescript
console.log(
    boxen("custom margin", {
        margin: {
            top: 1,
            right: 2,
            bottom: 1,
            left: 2,
        },
    }),
);
```

## Text Alignment [#text-alignment]

### Horizontal Alignment [#horizontal-alignment]

**Left aligned** (default):

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Left\nAligned\nText", {
        textAlignment: "left",
        padding: 1,
    }),
);
```

**Center aligned:**

```typescript
console.log(
    boxen("Center\nAligned\nText", {
        textAlignment: "center",
        padding: 1,
    }),
);
```

Output:

```
┌─────────┐
│         │
│  Center │
│ Aligned │
│   Text  │
│         │
└─────────┘
```

**Right aligned:**

```typescript
console.log(
    boxen("Right\nAligned\nText", {
        textAlignment: "right",
        padding: 1,
    }),
);
```

Output:

```
┌─────────┐
│         │
│   Right │
│ Aligned │
│    Text │
│         │
└─────────┘
```

## Headers and Footers [#headers-and-footers]

### Header Text [#header-text]

**Centered header:**

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Content goes here", {
        headerText: "Title",
        headerAlignment: "center",
    }),
);
```

Output:

```
┌───── Title ─────┐
│Content goes here│
└─────────────────┘
```

**Left aligned header:**

```typescript
console.log(
    boxen("Content", {
        headerText: "Left",
        headerAlignment: "left",
    }),
);
```

Output:

```
┌─ Left ──────┐
│Content      │
└─────────────┘
```

**Right aligned header:**

```typescript
console.log(
    boxen("Content", {
        headerText: "Right",
        headerAlignment: "right",
    }),
);
```

Output:

```
┌───────── Right ─┐
│Content          │
└─────────────────┘
```

### Footer Text [#footer-text]

**Centered footer:**

```typescript
console.log(
    boxen("Content", {
        footerText: "Footer",
        footerAlignment: "center",
    }),
);
```

Output:

```
┌───────────────┐
│Content        │
└─── Footer ────┘
```

### Combined Headers and Footers [#combined-headers-and-footers]

```typescript
console.log(
    boxen("Main content here", {
        headerText: "Header",
        headerAlignment: "center",
        footerText: "Footer",
        footerAlignment: "center",
        padding: 1,
    }),
);
```

Output:

```
┌──── Header ────┐
│                │
│ Main content   │
│ here           │
│                │
└──── Footer ────┘
```

## Border Coloring [#border-coloring]

### Simple Color [#simple-color]

```typescript
import { boxen } from "@visulima/boxen";
import { green } from "@visulima/colorize";

console.log(
    boxen("Success!", {
        borderColor: () => green("─"),
    }),
);
```

### Position-Based Coloring [#position-based-coloring]

Color different parts of the border independently:

```typescript
import { boxen } from "@visulima/boxen";
import { red, green, yellow, blue } from "@visulima/colorize";

console.log(
    boxen("Colorful!", {
        borderColor: (border, position) => {
            // Top border
            if (["top", "topLeft", "topRight"].includes(position)) {
                return red(border);
            }

            // Left border
            if (position === "left") {
                return yellow(border);
            }

            // Right border
            if (position === "right") {
                return green(border);
            }

            // Bottom border
            if (["bottom", "bottomLeft", "bottomRight"].includes(position)) {
                return blue(border);
            }

            return border;
        },
    }),
);
```

**Border Positions:**

* `topLeft` - Top left corner
* `top` - Top horizontal line
* `topRight` - Top right corner
* `left` - Left vertical line
* `right` - Right vertical line
* `bottomLeft` - Bottom left corner
* `bottom` - Bottom horizontal line
* `bottomRight` - Bottom right corner

### Gradient Borders [#gradient-borders]

```typescript
import { boxen } from "@visulima/boxen";
import { gradient } from "@visulima/colorize/gradient";

const gradientFn = gradient("cyan", "pink");

console.log(
    boxen("Gradient borders!", {
        borderColor: (border, position, length) => {
            return gradientFn(border);
        },
    }),
);
```

## Width Control [#width-control]

### Fixed Width [#fixed-width]

Set maximum box width:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("This is a longer text that will wrap", {
        width: 20,
    }),
);
```

Output:

```
┌──────────────────┐
│This is a longer  │
│text that will    │
│wrap              │
└──────────────────┘
```

### Full Width [#full-width]

Use terminal width:

```typescript
import { boxen } from "@visulima/boxen";

console.log(
    boxen("Full width box", {
        width: "terminal",
        textAlignment: "center",
    }),
);
```

## Advanced Examples [#advanced-examples]

### Status Box with Icons [#status-box-with-icons]

```typescript
import { boxen } from "@visulima/boxen";
import { green, red, yellow } from "@visulima/colorize";

function statusBox(status: "success" | "error" | "warning", message: string) {
    const configs = {
        success: {
            icon: "✓",
            color: green,
            border: "round",
        },
        error: {
            icon: "✗",
            color: red,
            border: "double",
        },
        warning: {
            icon: "⚠",
            color: yellow,
            border: "bold",
        },
    };

    const config = configs[status];

    return boxen(`${config.icon} ${message}`, {
        padding: 1,
        borderStyle: config.border as any,
        borderColor: () => config.color("─"),
    });
}

console.log(statusBox("success", "Build completed"));
console.log(statusBox("error", "Build failed"));
console.log(statusBox("warning", "Deprecated API"));
```

### Information Panel [#information-panel]

```typescript
import { boxen } from "@visulima/boxen";
import { gray, cyan } from "@visulima/colorize";

const info = [
    `${gray("Name:")} ${cyan("MyApp")}`,
    `${gray("Version:")} ${cyan("1.0.0")}`,
    `${gray("Status:")} ${cyan("Running")}`,
    `${gray("Port:")} ${cyan("3000")}`,
].join("\n");

console.log(
    boxen(info, {
        padding: 1,
        headerText: "Application Info",
        headerAlignment: "center",
        borderStyle: "double",
    }),
);
```

### Multi-Section Box [#multi-section-box]

```typescript
import { boxen } from "@visulima/boxen";
import { bold, dim } from "@visulima/colorize";

const sections = [
    bold("Section 1"),
    "Content for section 1",
    "",
    bold("Section 2"),
    "Content for section 2",
    "",
    dim("Note: This is a multi-section box"),
].join("\n");

console.log(
    boxen(sections, {
        padding: 1,
        headerText: "Documentation",
        footerText: "Press Enter to continue",
        footerAlignment: "center",
    }),
);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/boxen/api">
    Complete API documentation with all options
  </Card>
</Cards>


# API Reference (/docs/packages/bytes/api)



# API Reference [#api-reference]

Complete reference for all functions in the `@visulima/bytes` package.

## Array Operations [#array-operations]

### concat [#concat]

Concatenates an array of byte slices into a single slice.

**Signature:**

```typescript
function concat(arrays: Uint8Array[]): Uint8Array;
```

**Parameters:**

* `arrays` (`Uint8Array[]`) - Array of Uint8Arrays to concatenate

**Returns:** `Uint8Array` - A new Uint8Array containing all bytes from the input arrays

**Example:**

```typescript
import { concat } from "@visulima/bytes";

const result = concat([new Uint8Array([0, 1, 2]), new Uint8Array([3, 4, 5])]);
console.log(result); // Uint8Array([0, 1, 2, 3, 4, 5])
```

***

### copy [#copy]

Copies bytes from the source array to the destination array and returns the number of bytes copied.

**Signature:**

```typescript
function copy(src: Uint8Array, dst: Uint8Array, offset?: number): number;
```

**Parameters:**

* `src` (`Uint8Array`) - Source array to copy from
* `dst` (`Uint8Array`) - Destination array to copy into
* `offset` (`number`, optional) - Position in destination to start copying to. Default: `0`

**Returns:** `number` - Number of bytes copied

**Example:**

```typescript
import { copy } from "@visulima/bytes";

const src = new Uint8Array([9, 8, 7]);
const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);

const copied = copy(src, dst);
console.log(copied); // 3
console.log(dst); // Uint8Array([9, 8, 7, 3, 4, 5])
```

***

### equals [#equals]

Checks if two byte slices are equal.

**Signature:**

```typescript
function equals(a: Uint8Array, b: Uint8Array): boolean;
```

**Parameters:**

* `a` (`Uint8Array`) - First array to compare
* `b` (`Uint8Array`) - Second array to compare

**Returns:** `boolean` - `true` if arrays are equal, `false` otherwise

**Example:**

```typescript
import { equals } from "@visulima/bytes";

const a = new Uint8Array([1, 2, 3]);
const b = new Uint8Array([1, 2, 3]);

console.log(equals(a, b)); // true
```

***

### repeat [#repeat]

Returns a new byte slice composed of count repetitions of the source array.

**Signature:**

```typescript
function repeat(source: Uint8Array, count: number): Uint8Array;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to repeat
* `count` (`number`) - Number of times to repeat (must be ≥ 0)

**Returns:** `Uint8Array` - New array with repeated bytes

**Example:**

```typescript
import { repeat } from "@visulima/bytes";

const result = repeat(new Uint8Array([0, 1, 2]), 3);
console.log(result); // Uint8Array([0, 1, 2, 0, 1, 2, 0, 1, 2])
```

***

## Search Functions [#search-functions]

### indexOfNeedle [#indexofneedle]

Returns the index of the first occurrence of the needle array in the source array, or -1 if not present.

**Signature:**

```typescript
function indexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to search in
* `needle` (`Uint8Array`) - Sequence to search for
* `start` (`number`, optional) - Index to start searching from. Default: `0`

**Returns:** `number` - Index of first occurrence, or `-1` if not found

**Example:**

```typescript
import { indexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(indexOfNeedle(source, needle)); // 1
console.log(indexOfNeedle(source, needle, 2)); // 3
```

***

### lastIndexOfNeedle [#lastindexofneedle]

Returns the index of the last occurrence of the needle array in the source array, or -1 if not present.

**Signature:**

```typescript
function lastIndexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to search in
* `needle` (`Uint8Array`) - Sequence to search for
* `start` (`number`, optional) - Index to search backwards from. Default: `source.length - 1`

**Returns:** `number` - Index of last occurrence, or `-1` if not found

**Example:**

```typescript
import { lastIndexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(lastIndexOfNeedle(source, needle)); // 5
```

***

### includesNeedle [#includesneedle]

Determines whether the source array contains the needle array.

**Signature:**

```typescript
function includesNeedle(source: Uint8Array, needle: Uint8Array, start?: number): boolean;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to search in
* `needle` (`Uint8Array`) - Sequence to search for
* `start` (`number`, optional) - Index to start searching from. Default: `0`

**Returns:** `boolean` - `true` if needle is found, `false` otherwise

**Example:**

```typescript
import { includesNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(includesNeedle(source, needle)); // true
```

***

### startsWith [#startswith]

Returns true if the prefix array appears at the start of the source array, false otherwise.

**Signature:**

```typescript
function startsWith(source: Uint8Array, prefix: Uint8Array): boolean;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to check
* `prefix` (`Uint8Array`) - Prefix to look for

**Returns:** `boolean` - `true` if source starts with prefix, `false` otherwise

**Example:**

```typescript
import { startsWith } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const prefix = new Uint8Array([0, 1, 2]);

console.log(startsWith(source, prefix)); // true
```

***

### endsWith [#endswith]

Returns true if the suffix array appears at the end of the source array, false otherwise.

**Signature:**

```typescript
function endsWith(source: Uint8Array, suffix: Uint8Array): boolean;
```

**Parameters:**

* `source` (`Uint8Array`) - Array to check
* `suffix` (`Uint8Array`) - Suffix to look for

**Returns:** `boolean` - `true` if source ends with suffix, `false` otherwise

**Example:**

```typescript
import { endsWith } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const suffix = new Uint8Array([1, 2, 3]);

console.log(endsWith(source, suffix)); // true
```

***

## Type Conversion [#type-conversion]

### bufferToUint8Array [#buffertouint8array]

Converts a Node.js Buffer to a Uint8Array. Creates a new Uint8Array view on the Buffer's underlying ArrayBuffer, ensuring correct byteOffset and length.

**Signature:**

```typescript
function bufferToUint8Array(buf: Buffer): Uint8Array;
```

**Parameters:**

* `buf` (`Buffer`) - The Buffer to convert

**Returns:** `Uint8Array` - A Uint8Array view of the Buffer

**Example:**

```typescript
import { bufferToUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

const buffer = Buffer.from("Hello");
const result = bufferToUint8Array(buffer);

console.log(result); // Uint8Array([72, 101, 108, 108, 111])
```

***

### isUint8Array [#isuint8array]

Checks if a value is a Uint8Array or, in a Node.js environment, a Buffer.

**Signature:**

```typescript
function isUint8Array(x: unknown): x is Uint8Array;
```

**Parameters:**

* `x` (`unknown`) - The value to check

**Returns:** `boolean` - `true` if x is a Uint8Array or Buffer, `false` otherwise

**Example:**

```typescript
import { isUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

console.log(isUint8Array(new Uint8Array([1, 2]))); // true
console.log(isUint8Array(Buffer.from("test"))); // true (in Node.js)
console.log(isUint8Array([1, 2])); // false
```

***

### asciiToUint8Array [#asciitouint8array]

Converts an ASCII string, array of strings, or template literal to a Uint8Array. Each character is converted to its ASCII byte value (0-255). Characters outside this range will be truncated.

**Signature:**

```typescript
function asciiToUint8Array(txt: TemplateStringsArray | string | [string]): Uint8Array;
```

**Parameters:**

* `txt` (`TemplateStringsArray | string | [string]`) - Input string or template literal

**Returns:** `Uint8Array` - ASCII encoded byte array

**Example:**

```typescript
import { asciiToUint8Array } from "@visulima/bytes";

const result = asciiToUint8Array("Hello!");
console.log(result); // Uint8Array([72, 101, 108, 108, 111, 33])

// Template literal
const name = "World";
const result2 = asciiToUint8Array(`Hello ${name}`);
console.log(result2); // Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100])
```

***

### utf8ToUint8Array [#utf8touint8array]

Converts a UTF-8 string, array of strings, or template literal to a Uint8Array. Requires Node.js Buffer support.

**Signature:**

```typescript
function utf8ToUint8Array(txt: TemplateStringsArray | [string] | string): Uint8Array;
```

**Parameters:**

* `txt` (`TemplateStringsArray | [string] | string`) - Input string or template literal

**Returns:** `Uint8Array` - UTF-8 encoded byte array

**Example:**

```typescript
import { utf8ToUint8Array } from "@visulima/bytes";

// ASCII string
const result1 = utf8ToUint8Array("Hello!");
console.log(result1); // Uint8Array([72, 101, 108, 108, 111, 33])

// Multi-byte UTF-8 characters
const result2 = utf8ToUint8Array("你好");
console.log(result2); // Uint8Array([228, 189, 160, 229, 165, 189])

// Emoji
const result3 = utf8ToUint8Array("🌍");
console.log(result3); // Uint8Array([240, 159, 140, 141])
```

***

### toUint8Array [#touint8array]

Attempts to convert various data types to a Uint8Array. Supports Uint8Array (returns as is), ArrayBuffer, Array of numbers, and in Node.js also supports Buffer and strings.

**Signature:**

```typescript
function toUint8Array(data: unknown): Uint8Array;
```

**Parameters:**

* `data` (`unknown`) - The data to convert

**Returns:** `Uint8Array` - Converted byte array

**Throws:** `Error` with message `'UINT8ARRAY_INCOMPATIBLE'` if the data cannot be converted

**Example:**

```typescript
import { toUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

// From Uint8Array
console.log(toUint8Array(new Uint8Array([1, 2, 3])));
// Uint8Array([1, 2, 3])

// From ArrayBuffer
const buffer = new ArrayBuffer(3);
console.log(toUint8Array(buffer));
// Uint8Array([0, 0, 0])

// From Array of numbers
console.log(toUint8Array([4, 5, 6]));
// Uint8Array([4, 5, 6])

// From Node.js Buffer
console.log(toUint8Array(Buffer.from("Node")));
// Uint8Array([78, 111, 100, 101])

// From string (in Node.js)
console.log(toUint8Array("String"));
// Uint8Array([83, 116, 114, 105, 110, 103])

// Incompatible types throw error
try {
    toUint8Array(123);
} catch (error) {
    console.log(error.message);
    // "UINT8ARRAY_INCOMPATIBLE: Cannot convert data to Uint8Array"
}
```

***

## Function Summary [#function-summary]

| Function             | Category         | Description                       |
| -------------------- | ---------------- | --------------------------------- |
| `concat`             | Array Operations | Concatenate multiple byte arrays  |
| `copy`               | Array Operations | Copy bytes between arrays         |
| `equals`             | Array Operations | Compare arrays for equality       |
| `repeat`             | Array Operations | Repeat byte sequence              |
| `indexOfNeedle`      | Search           | Find first occurrence of sequence |
| `lastIndexOfNeedle`  | Search           | Find last occurrence of sequence  |
| `includesNeedle`     | Search           | Check if array contains sequence  |
| `startsWith`         | Search           | Check if array starts with prefix |
| `endsWith`           | Search           | Check if array ends with suffix   |
| `bufferToUint8Array` | Conversion       | Convert Buffer to Uint8Array      |
| `isUint8Array`       | Conversion       | Type check for Uint8Array         |
| `asciiToUint8Array`  | Conversion       | Convert ASCII string to bytes     |
| `utf8ToUint8Array`   | Conversion       | Convert UTF-8 string to bytes     |
| `toUint8Array`       | Conversion       | Universal converter to Uint8Array |

## TypeScript Types [#typescript-types]

The package exports TypeScript types for all functions. All functions have full type safety:

```typescript
import type { Uint8Array } from "@visulima/bytes";

// All functions are strongly typed
const arrays: Uint8Array[] = [new Uint8Array([1, 2]), new Uint8Array([3, 4])];
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/bytes/usage">
    Learn how to use these functions with detailed examples
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/bytes)



# @visulima/bytes [#visulimabytes]

Utility functions to make dealing with Uint8Arrays easier. Work with binary data like a pro—concatenate, copy, search, and convert between Uint8Arrays, Buffers, strings, and more.

## Key Features [#key-features]

**Array Operations**

* Concatenate multiple byte arrays into one
* Copy bytes between arrays with offset support
* Repeat byte sequences any number of times
* Compare byte arrays for equality

**Search and Pattern Matching**

* Find sequences within byte arrays (first/last occurrence)
* Check if arrays start or end with specific patterns
* Determine if byte sequences contain specific needles

**Type Conversion**

* Convert between Node.js Buffers and Uint8Arrays
* Transform ASCII/UTF-8 strings to byte arrays
* Universal converter for multiple data types
* Type-safe checks for Uint8Array instances

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/bytes
```

Concatenate byte arrays:

```typescript
import { concat } from "@visulima/bytes";

const a = new Uint8Array([0, 1, 2]);
const b = new Uint8Array([3, 4, 5]);
const result = concat([a, b]);

console.log(result); // Uint8Array([0, 1, 2, 3, 4, 5])
```

## Use Cases [#use-cases]

### Processing Binary Data in APIs [#processing-binary-data-in-apis]

Handle binary data from HTTP requests or file uploads:

```typescript
import { concat, toUint8Array } from "@visulima/bytes";

async function processBinaryUpload(chunks: unknown[]) {
    // Convert all chunks to Uint8Arrays
    const arrays = chunks.map((chunk) => toUint8Array(chunk));

    // Combine into single array
    const combined = concat(arrays);

    return combined;
}
```

### Search Binary Protocols [#search-binary-protocols]

Find specific byte sequences in protocol data:

```typescript
import { indexOfNeedle, startsWith } from "@visulima/bytes";

const data = new Uint8Array([0x00, 0x01, 0xff, 0xaa, 0xbb, 0x01, 0xff]);
const header = new Uint8Array([0x00, 0x01]);
const pattern = new Uint8Array([0x01, 0xff]);

// Check protocol header
if (startsWith(data, header)) {
    console.log("Valid protocol header");
}

// Find pattern position
const position = indexOfNeedle(data, pattern);
console.log(`Pattern found at position: ${position}`); // 1
```

### Convert Between Text and Binary [#convert-between-text-and-binary]

Work with string encodings in Node.js:

```typescript
import { utf8ToUint8Array, asciiToUint8Array } from "@visulima/bytes";

// UTF-8 encoding (supports emojis and international characters)
const utf8Data = utf8ToUint8Array("Hello 世界 🌍");

// ASCII encoding (fast, but only 0-255 range)
const asciiData = asciiToUint8Array("Hello World");

console.log(utf8Data); // Uint8Array with UTF-8 bytes
console.log(asciiData); // Uint8Array([72, 101, 108, 108, 111, ...])
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/bytes/installation">
    Learn how to install and import the package
  </Card>

  <Card title="Usage Guide" href="/docs/packages/bytes/usage">
    Explore all functions with detailed examples
  </Card>

  <Card title="API Reference" href="/docs/packages/bytes/api">
    Complete API documentation with parameters and types
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package works in both Node.js and browser environments:

* **Node.js:** Full support including Buffer conversion utilities
* **Browsers:** Core Uint8Array operations (Buffer-specific functions require polyfills)
* **Deno/Bun:** Compatible with all modern JavaScript runtimes

Requires Node.js ≥22.13 for full functionality.


# Installation (/docs/packages/bytes/installation)





# Installation [#installation]

Install the package using your preferred package manager:

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/bytes `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/bytes `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/bytes `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/bytes `
  </Tab>
</Tabs>

## Import Methods [#import-methods]

### ESM (Recommended) [#esm-recommended]

Import specific functions you need:

```typescript
import { concat, equals, toUint8Array } from "@visulima/bytes";
```

Import everything:

```typescript
import * as bytes from "@visulima/bytes";

bytes.concat([...]);
```

### CommonJS [#commonjs]

For CommonJS environments:

```javascript
const { concat, equals, toUint8Array } = require("@visulima/bytes");
```

## Requirements [#requirements]

* **Node.js:** ≥22.13 ≤25.x
* **TypeScript:** ≥5.0 (optional, but recommended for type safety)

## Verify Installation [#verify-installation]

Verify the package works correctly:

```typescript
import { concat } from "@visulima/bytes";

const result = concat([new Uint8Array([1, 2]), new Uint8Array([3, 4])]);

console.log(result); // Uint8Array([1, 2, 3, 4])
```

If you see the expected output, installation was successful!

## TypeScript Support [#typescript-support]

The package includes full TypeScript type definitions. No additional `@types` packages are needed.

```typescript
import type { Uint8ArrayList } from "@visulima/bytes";
import { concat } from "@visulima/bytes";

const arrays: Uint8Array[] = [new Uint8Array([1, 2]), new Uint8Array([3, 4])];

const result: Uint8Array = concat(arrays);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/bytes/usage">
    Learn how to use all available functions
  </Card>

  <Card title="API Reference" href="/docs/packages/bytes/api">
    Explore the complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/bytes/usage)



# Usage Guide [#usage-guide]

Learn how to use all functions from the `@visulima/bytes` package with detailed examples.

## Array Operations [#array-operations]

### Concatenate Byte Arrays [#concatenate-byte-arrays]

Combine multiple Uint8Arrays into a single array:

```typescript
import { concat } from "@visulima/bytes";

const a = new Uint8Array([0, 1, 2]);
const b = new Uint8Array([3, 4, 5]);
const c = new Uint8Array([6, 7, 8]);

const result = concat([a, b, c]);
console.log(result); // Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8])
```

Works with empty arrays:

```typescript
import { concat } from "@visulima/bytes";

const empty = new Uint8Array([]);
const data = new Uint8Array([1, 2, 3]);

console.log(concat([empty, data])); // Uint8Array([1, 2, 3])
console.log(concat([data, empty])); // Uint8Array([1, 2, 3])
```

### Copy Bytes Between Arrays [#copy-bytes-between-arrays]

Copy bytes from one array to another:

```typescript
import { copy } from "@visulima/bytes";

const src = new Uint8Array([9, 8, 7]);
const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);

const bytesCopied = copy(src, dst);
console.log(bytesCopied); // 3
console.log(dst); // Uint8Array([9, 8, 7, 3, 4, 5])
```

Copy with offset to control destination position:

```typescript
import { copy } from "@visulima/bytes";

const src = new Uint8Array([1, 1, 1, 1]);
const dst = new Uint8Array([0, 0, 0, 0]);

const bytesCopied = copy(src, dst, 1); // Start at index 1
console.log(bytesCopied); // 3 (only 3 bytes fit)
console.log(dst); // Uint8Array([0, 1, 1, 1])
```

### Repeat Byte Sequences [#repeat-byte-sequences]

Create repetitions of a byte array:

```typescript
import { repeat } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2]);

console.log(repeat(source, 3));
// Uint8Array([0, 1, 2, 0, 1, 2, 0, 1, 2])

console.log(repeat(source, 1));
// Uint8Array([0, 1, 2])

console.log(repeat(source, 0));
// Uint8Array([])
```

### Compare Arrays for Equality [#compare-arrays-for-equality]

Check if two byte arrays are identical:

```typescript
import { equals } from "@visulima/bytes";

const a = new Uint8Array([1, 2, 3]);
const b = new Uint8Array([1, 2, 3]);
const c = new Uint8Array([4, 5, 6]);

console.log(equals(a, b)); // true
console.log(equals(a, c)); // false
```

Works with different lengths:

```typescript
import { equals } from "@visulima/bytes";

const a = new Uint8Array([1, 2]);
const b = new Uint8Array([1, 2, 3]);

console.log(equals(a, b)); // false
```

## Search and Pattern Matching [#search-and-pattern-matching]

### Find First Occurrence [#find-first-occurrence]

Find the index of the first occurrence of a byte sequence:

```typescript
import { indexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(indexOfNeedle(source, needle)); // 1
```

Start searching from a specific position:

```typescript
import { indexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(indexOfNeedle(source, needle, 2)); // 3
console.log(indexOfNeedle(source, needle, 6)); // -1 (not found)
```

Pattern not found returns -1:

```typescript
import { indexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 3]);
const needle = new Uint8Array([5, 6]);

console.log(indexOfNeedle(source, needle)); // -1
```

### Find Last Occurrence [#find-last-occurrence]

Find the index of the last occurrence of a byte sequence:

```typescript
import { lastIndexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(lastIndexOfNeedle(source, needle)); // 5
```

Search backwards from a specific position:

```typescript
import { lastIndexOfNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(lastIndexOfNeedle(source, needle, 2)); // 1
console.log(lastIndexOfNeedle(source, needle, 6)); // 5
```

### Check if Array Contains Sequence [#check-if-array-contains-sequence]

Determine if a byte array contains a specific sequence:

```typescript
import { includesNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(includesNeedle(source, needle)); // true
console.log(includesNeedle(source, new Uint8Array([5, 6]))); // false
```

Start checking from a specific position:

```typescript
import { includesNeedle } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const needle = new Uint8Array([1, 2]);

console.log(includesNeedle(source, needle, 3)); // true
console.log(includesNeedle(source, needle, 6)); // false
```

### Check Start Pattern [#check-start-pattern]

Verify if an array starts with a specific prefix:

```typescript
import { startsWith } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const prefix = new Uint8Array([0, 1, 2]);

console.log(startsWith(source, prefix)); // true
console.log(startsWith(source, new Uint8Array([1, 2]))); // false
```

Empty prefix always matches:

```typescript
import { startsWith } from "@visulima/bytes";

const source = new Uint8Array([1, 2, 3]);
const empty = new Uint8Array([]);

console.log(startsWith(source, empty)); // true
```

### Check End Pattern [#check-end-pattern]

Verify if an array ends with a specific suffix:

```typescript
import { endsWith } from "@visulima/bytes";

const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
const suffix = new Uint8Array([1, 2, 3]);

console.log(endsWith(source, suffix)); // true
console.log(endsWith(source, new Uint8Array([2, 3]))); // true
console.log(endsWith(source, new Uint8Array([0, 1]))); // false
```

## Type Conversion [#type-conversion]

### Convert Node.js Buffer to Uint8Array [#convert-nodejs-buffer-to-uint8array]

Transform a Buffer into a Uint8Array:

```typescript
import { bufferToUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

const buffer = Buffer.from("Hello");
const uint8Array = bufferToUint8Array(buffer);

console.log(uint8Array instanceof Uint8Array); // true
console.log(uint8Array); // Uint8Array([72, 101, 108, 108, 111])
```

Respects buffer offset and length:

```typescript
import { bufferToUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

const original = Buffer.from([1, 2, 3, 4, 5]);
const sub = original.subarray(1, 4);
const result = bufferToUint8Array(sub);

console.log(result); // Uint8Array([2, 3, 4])
```

### Check if Value is Uint8Array [#check-if-value-is-uint8array]

Type-safe check for Uint8Array (including Buffers in Node.js):

```typescript
import { isUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

console.log(isUint8Array(new Uint8Array([1, 2]))); // true
console.log(isUint8Array(Buffer.from("test"))); // true (in Node.js)
console.log(isUint8Array("not a Uint8Array")); // false
console.log(isUint8Array([1, 2])); // false (plain array)
console.log(isUint8Array(new ArrayBuffer(10))); // false
```

Use with TypeScript type guards:

```typescript
import { isUint8Array } from "@visulima/bytes";

function processData(data: unknown) {
    if (isUint8Array(data)) {
        // TypeScript knows data is Uint8Array here
        console.log(data.length);
    }
}
```

### Convert ASCII Strings to Uint8Array [#convert-ascii-strings-to-uint8array]

Transform ASCII strings into byte arrays:

```typescript
import { asciiToUint8Array } from "@visulima/bytes";

const result = asciiToUint8Array("Hello!");
console.log(result); // Uint8Array([72, 101, 108, 108, 111, 33])
```

Supports template literals:

```typescript
import { asciiToUint8Array } from "@visulima/bytes";

const world = "World";
const result = asciiToUint8Array(`Hello ${world}!`);
console.log(result); // Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33])
```

Non-ASCII characters are truncated to 8 bits:

```typescript
import { asciiToUint8Array } from "@visulima/bytes";

// Characters outside 0-255 range are truncated
const result = asciiToUint8Array("你好€");
// Only lower 8 bits are kept for each character
```

### Convert UTF-8 Strings to Uint8Array [#convert-utf-8-strings-to-uint8array]

Transform UTF-8 strings into byte arrays (requires Node.js):

```typescript
import { utf8ToUint8Array } from "@visulima/bytes";

const result = utf8ToUint8Array("Hello!");
console.log(result); // Uint8Array([72, 101, 108, 108, 111, 33])

// Properly handles multi-byte characters
const chinese = utf8ToUint8Array("你好");
console.log(chinese); // Uint8Array([228, 189, 160, 229, 165, 189])

const emoji = utf8ToUint8Array("🌍");
console.log(emoji); // Uint8Array([240, 159, 140, 141])
```

Supports template literals:

```typescript
import { utf8ToUint8Array } from "@visulima/bytes";

const item = "你好";
const result = utf8ToUint8Array(`Item: ${item}`);
console.log(result); // Uint8Array([73, 116, 101, 109, 58, 32, 228, 189, 160, 229, 165, 189])
```

### Universal Type Converter [#universal-type-converter]

Convert various types to Uint8Array:

```typescript
import { toUint8Array } from "@visulima/bytes";
import { Buffer } from "node:buffer";

// From Uint8Array (returns as-is)
const u8 = new Uint8Array([1, 2, 3]);
console.log(toUint8Array(u8) === u8); // true

// From ArrayBuffer
const buffer = new ArrayBuffer(3);
const view = new Uint8Array(buffer);
view[0] = 1;
view[1] = 2;
view[2] = 3;
console.log(toUint8Array(buffer)); // Uint8Array([1, 2, 3])

// From Array of numbers
console.log(toUint8Array([4, 5, 6])); // Uint8Array([4, 5, 6])

// From Node.js Buffer
const nodeBuf = Buffer.from("Node");
console.log(toUint8Array(nodeBuf)); // Uint8Array([78, 111, 100, 101])

// From string (via Buffer.from in Node.js)
console.log(toUint8Array("String")); // Uint8Array([83, 116, 114, 105, 110, 103])
```

Throws error for incompatible types:

```typescript
import { toUint8Array } from "@visulima/bytes";

try {
    toUint8Array(123); // Not convertible
} catch (error) {
    console.log(error.message);
    // "UINT8ARRAY_INCOMPATIBLE: Cannot convert data to Uint8Array"
}

// Also throws for:
// - booleans
// - objects
// - undefined
// - arrays with non-number elements
```

## Real-World Examples [#real-world-examples]

### Validate Binary File Headers [#validate-binary-file-headers]

Check file types by examining their headers:

```typescript
import { startsWith } from "@visulima/bytes";

function isPNG(data: Uint8Array): boolean {
    const pngHeader = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
    return startsWith(data, pngHeader);
}

function isJPEG(data: Uint8Array): boolean {
    const jpegHeader = new Uint8Array([0xff, 0xd8, 0xff]);
    return startsWith(data, jpegHeader);
}

const fileData = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10 /* ... */]);
console.log(isPNG(fileData)); // true
console.log(isJPEG(fileData)); // false
```

### Build Binary Protocol Messages [#build-binary-protocol-messages]

Construct messages for binary protocols:

```typescript
import { concat } from "@visulima/bytes";

function createMessage(type: number, payload: Uint8Array): Uint8Array {
    const header = new Uint8Array([
        0xff,
        0xff, // Magic number
        type, // Message type
        payload.length >> 8, // Length high byte
        payload.length & 0xff, // Length low byte
    ]);

    return concat([header, payload]);
}

const payload = new Uint8Array([1, 2, 3, 4]);
const message = createMessage(0x01, payload);
console.log(message);
// Uint8Array([255, 255, 1, 0, 4, 1, 2, 3, 4])
```

### Process Streaming Data [#process-streaming-data]

Handle chunked binary data:

```typescript
import { concat, indexOfNeedle } from "@visulima/bytes";

const delimiter = new Uint8Array([0x0a]); // newline
let buffer = new Uint8Array([]);

function processChunk(chunk: Uint8Array): string[] {
    buffer = concat([buffer, chunk]);

    const messages: string[] = [];
    let pos: number;

    while ((pos = indexOfNeedle(buffer, delimiter)) !== -1) {
        const message = buffer.slice(0, pos);
        messages.push(new TextDecoder().decode(message));
        buffer = buffer.slice(pos + 1);
    }

    return messages;
}

// Simulate receiving chunks
const chunk1 = new Uint8Array([72, 101, 108, 108, 111, 0x0a, 87]); // "Hello\nW"
const chunk2 = new Uint8Array([111, 114, 108, 100, 0x0a]); // "orld\n"

console.log(processChunk(chunk1)); // ["Hello"]
console.log(processChunk(chunk2)); // ["World"]
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/bytes/api">
    Complete API documentation with all parameters and types
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Cli (/docs/packages/cerebro/api/cli)



# API: CLI [#api-cli]

The main CLI class for creating and managing command-line applications.

## Creating a CLI Instance [#creating-a-cli-instance]

### Constructor [#constructor]

```typescript
new Cerebro(name: string, options?: CliOptions)
```

**Parameters:**

* `name` - The CLI application name
* `options` - Optional configuration

**Example:**

```typescript
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app", {
    packageName: "my-app",
    packageVersion: "1.0.0",
    cwd: process.cwd(),
    logger: console,
    argv: process.argv.slice(2),
});
```

### Factory Function [#factory-function]

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-app", {
    packageName: "my-app",
    packageVersion: "1.0.0",
});
```

## CliOptions [#clioptions]

```typescript
interface CliOptions<T extends Console = Console> {
    argv?: ReadonlyArray<string>;
    cwd?: string;
    logger?: T;
    packageName?: string;
    packageVersion?: string;
}
```

## Methods [#methods]

### addCommand() [#addcommand]

Add a command to the CLI:

```typescript
cli.addCommand(command: Command): this
```

**Example:**

```typescript
cli.addCommand({
    name: "build",
    description: "Build the project",
    execute: ({ logger }) => {
        logger.info("Building...");
    },
});
```

### addGlobalOption() [#addglobaloption]

Add a global option available to all commands. Global options are parsed alongside
command-specific options and displayed in the help output under "Global Options".

```typescript
cli.addGlobalOption(option: OptionDefinition): this
```

**Example:**

```typescript
cli.addGlobalOption({
    name: "cwd",
    type: String,
    description: "Override working directory",
});

cli.addGlobalOption({
    name: "config",
    alias: "C",
    type: String,
    description: "Path to config file",
});
```

Throws an error if the option name or alias conflicts with a built-in global option
(`verbose`, `debug`, `help`, `quiet`, `version`, `no-color`, `color`) or a previously
added custom global option.

Global options are accessible in commands via `toolbox.options`:

```typescript
cli.addCommand({
    name: "build",
    execute: ({ options }) => {
        const cwd = options.cwd as string | undefined;
        // ...
    },
});
```

### getGlobalOptions() [#getglobaloptions]

Get all global options (built-in + custom):

```typescript
cli.getGlobalOptions(): OptionDefinition[]
```

### addPlugin() [#addplugin]

Add a plugin to extend functionality:

```typescript
cli.addPlugin(plugin: Plugin): this
```

**Example:**

```typescript
cli.addPlugin({
    name: "my-plugin",
    execute: (toolbox) => {
        toolbox.myFeature = () => {};
    },
});
```

### run() [#run]

Run the CLI application:

```typescript
cli.run(options?: CliRunOptions): Promise<void>
```

**Options:**

```typescript
interface CliRunOptions {
    shouldExitProcess?: boolean; // Default: true
    autoDispose?: boolean; // Default: true
    [key: string]: any; // Additional options
}
```

**Example:**

```typescript
await cli.run({
    shouldExitProcess: false, // Don't exit process
    autoDispose: false, // Don't cleanup
});
```

### runCommand() [#runcommand]

Execute a command programmatically:

```typescript
cli.runCommand(commandName: string, options?: RunCommandOptions): Promise<unknown>
```

**Options:**

```typescript
interface RunCommandOptions {
    argv?: string[];
    [key: string]: any;
}
```

**Example:**

```typescript
await runtime.runCommand("build", {
    argv: ["--production"],
});
```

### setDefaultCommand() [#setdefaultcommand]

Set the default command when none is provided:

```typescript
cli.setDefaultCommand(commandName: string): this
```

**Example:**

```typescript
cli.setDefaultCommand("help");
```

### setCommandSection() [#setcommandsection]

Configure help output:

```typescript
cli.setCommandSection(section: CommandSection): this
```

**Example:**

```typescript
cli.setCommandSection({
    header: "My CLI v1.0.0",
    footer: "Visit https://example.com for more info",
});
```

### getCliName() [#getcliname]

Get the CLI application name:

```typescript
cli.getCliName(): string
```

### getCommands() [#getcommands]

Get all registered commands:

```typescript
cli.getCommands(): Map<string, Command>
```

### getCwd() [#getcwd]

Get the current working directory:

```typescript
cli.getCwd(): string
```

### getPackageName() [#getpackagename]

Get the package name:

```typescript
cli.getPackageName(): string | undefined
```

### getPackageVersion() [#getpackageversion]

Get the package version:

```typescript
cli.getPackageVersion(): string | undefined
```

### getPluginManager() [#getpluginmanager]

Get the plugin manager instance:

```typescript
cli.getPluginManager(): PluginManager
```

### dispose() [#dispose]

Clean up resources:

```typescript
cli.dispose(): void
```

## Complete Example [#complete-example]

```typescript
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app", {
    packageName: "my-app",
    packageVersion: "1.0.0",
});

cli.setCommandSection({
    header: "My Awesome CLI v1.0.0",
});

cli.setDefaultCommand("help");

cli.addCommand({
    name: "hello",
    execute: ({ logger }) => {
        logger.info("Hello!");
    },
});

await cli.run();
```


# Command (/docs/packages/cerebro/api/command)



# API: Command [#api-command]

Command interface for defining CLI commands.

## Command Interface [#command-interface]

```typescript
interface Command<O extends OptionDefinition = OptionDefinition, TContext extends Toolbox = Toolbox> {
    name: string;
    /** Either `execute` or `loader` must be provided (but not both). */
    execute?: (toolbox: TContext) => Promise<void> | void;
    /** Lazily imports the handler module on first invocation. */
    loader?: () => Promise<{ default: (toolbox: TContext) => Promise<void> | void }>;
    description?: string;
    alias?: string | string[];
    argument?: ArgumentDefinition;
    options?: OptionDefinition[];
    env?: EnvDefinition[];
    hidden?: boolean;
    group?: string;
    examples?: string[] | string[][];
    usage?: Content[];
    file?: string;
    commandPath?: string[];
}
```

## Properties [#properties]

### name [#name]

**Type:** `string`\
&#x2A;*Required:** Yes

The command name used to invoke it:

```typescript
{
    name: "build"; // Invoked as: cli build
}
```

### execute [#execute]

**Type:** `(toolbox: TContext) => Promise<void> | void`\
&#x2A;*Required:** Either `execute` or `loader` must be set — not both.

The function that executes the command:

```typescript
{
    execute: ({ logger, options, argument }) => {
        // Command logic
    };
}
```

### loader [#loader]

**Type:** `() => Promise<{ default: (toolbox: TContext) => Promise<void> | void }>`\
&#x2A;*Required:** Either `execute` or `loader` must be set — not both.

Lazily imports the handler module on first invocation. The module's
**default export** is used as the handler. Help, completion, and option
validation work entirely from the metadata declared on `addCommand` and
never trigger the loader. The first invocation imports the module;
subsequent calls reuse the cached handler.

Use this for commands whose handler pulls in heavy dependencies — the
import cost is paid only when the user actually invokes the command.

```typescript
// commands/build.ts
const build: Command = {
    name: "build",
    description: "Build the project",
    options: [{ name: "output", type: String }],
    loader: () => import("./build.handler"),
};

// commands/build.handler.ts
export default async ({ logger, options }) => {
    logger.info(`Building to ${options.output ?? "dist"}`);
};
```

For modules that group multiple subcommands' handlers as named exports,
use the `lazyNamed` helper:

```typescript
import { lazyNamed } from "@visulima/cerebro";

cli.addCommand({
    name: "list",
    commandPath: ["cache"],
    loader: lazyNamed(() => import("./cache.handlers"), "cacheList"),
});
```

If the loader rejects or the resolved module has no default-exported
function, a `CommandLoaderError` is thrown.

### description [#description]

**Type:** `string`\
&#x2A;*Required:** No

Short description shown in help:

```typescript
{
    description: "Build the project for production";
}
```

### alias [#alias]

**Type:** `string | string[]`\
&#x2A;*Required:** No

Alternative names for the command:

```typescript
{
    alias: "b"; // Single alias
    // or
    alias: ["b", "compile"]; // Multiple aliases
}
```

### argument [#argument]

**Type:** `ArgumentDefinition`\
&#x2A;*Required:** No

Positional argument definition:

```typescript
{
  argument: {
    name: "file",
    type: String,
    description: "File to process",
    defaultValue: "default.txt"
  }
}
```

### options [#options]

**Type:** `OptionDefinition[]`\
&#x2A;*Required:** No

Command options:

```typescript
{
    options: [
        {
            name: "production",
            type: Boolean,
            description: "Build for production",
        },
    ];
}
```

### env [#env]

**Type:** `EnvDefinition[]`\
&#x2A;*Required:** No

Environment variables supported by this command:

```typescript
{
    env: [
        {
            name: "API_KEY",
            type: String,
            description: "API key for authentication",
        },
        {
            name: "TIMEOUT",
            type: Number,
            defaultValue: 5000,
            description: "Request timeout in milliseconds",
        },
        {
            name: "VERBOSE",
            type: Boolean,
            defaultValue: false,
            description: "Enable verbose logging",
        },
    ];
}
```

Environment variables are automatically:

* Converted to camelCase (`API_KEY` → `apiKey`)
* Type-transformed (String, Number, Boolean)
* Applied with default values if not set
* Displayed in help output (unless `hidden: true`)

Access them in `execute` via `toolbox.env`:

```typescript
execute: ({ env }) => {
    const apiKey = env.apiKey; // string | undefined
    const timeout = env.timeout; // number (5000 if not set)
    const verbose = env.verbose; // boolean (false if not set)
};
```

**See also:** [Environment Variables Guide](/docs/packages/cerebro/guides/options#environment-variables)

### hidden [#hidden]

**Type:** `boolean`\
&#x2A;*Required:** No\
&#x2A;*Default:** `false`

Hide command from help output:

```typescript
{
    hidden: true;
}
```

### group [#group]

**Type:** `string`\
&#x2A;*Required:** No

Group commands in help output:

```typescript
{
    group: "Build";
}
```

### examples [#examples]

**Type:** `string[] | string[][]`\
&#x2A;*Required:** No

Usage examples:

```typescript
{
    examples: ["build --production", "build --production --output dist"];
}
```

### usage [#usage]

**Type:** `Content[]`\
&#x2A;*Required:** No

Custom usage documentation (advanced).

### file [#file]

**Type:** `string`\
&#x2A;*Required:** No

Path to command file (for metadata).

### commandPath [#commandpath]

**Type:** `string[]`\
&#x2A;*Required:** No

Command path for nested commands. Creates hierarchical command structures.

When specified, the command can be invoked using the full path: `cli <path> <name>`.

```typescript
{
    name: "staging",
    commandPath: ["deploy"], // Invoked as: cli deploy staging
    execute: ({ logger }) => {
        logger.info("Deploying to staging...");
    }
}
```

Multi-level nesting is supported:

```typescript
{
    name: "up",
    commandPath: ["db", "migrate"], // Invoked as: cli db migrate up
    execute: ({ logger }) => {
        logger.info("Running migrations...");
    }
}
```

**Validation:**

* Each path segment must follow the same rules as command names
* Must start with a letter
* Can contain letters, numbers, hyphens, and underscores
* Cannot contain spaces or special characters

**See also:** [Nested Commands Guide](/docs/packages/cerebro/guides/commands#nested-commands)

## ArgumentDefinition [#argumentdefinition]

```typescript
interface ArgumentDefinition<T = any> {
    name: string;
    type?: TypeConstructor<T>;
    description?: string;
    defaultValue?: T;
    typeLabel?: string;
}
```

## OptionDefinition [#optiondefinition]

```typescript
interface OptionDefinition<T> {
    name: string;
    alias?: string | string[];
    type?: TypeConstructor<T>;
    description?: string;
    defaultValue?: T;
    required?: boolean;
    multiple?: boolean;
    lazyMultiple?: boolean;
    conflicts?: string | string[];
    implies?: Record<string, any>;
    hidden?: boolean;
    typeLabel?: string;
    group?: string;
}
```

## EnvDefinition [#envdefinition]

```typescript
interface EnvDefinition<T = string> {
    name: string;
    type?: EnvTypeConstructor<T>;
    description?: string;
    defaultValue?: T;
    hidden?: boolean;
    typeLabel?: string;
}
```

### Properties [#properties-1]

#### name [#name-1]

**Type:** `string`\
&#x2A;*Required:** Yes

The environment variable name (e.g., `API_KEY`, `LOG_LEVEL`). Will be converted to camelCase when accessed via `toolbox.env`.

#### type [#type]

**Type:** `EnvTypeConstructor<T>`\
&#x2A;*Required:** No

Type constructor for transforming the environment variable value:

* `String` - Keep as string
* `Number` - Parse as integer
* `Boolean` - Parse as boolean (accepts `true`, `1`, `yes`, `on` for true)

```typescript
{
    name: "PORT",
    type: Number, // Parses string to number
}
```

#### description [#description-1]

**Type:** `string`\
&#x2A;*Required:** No

Description shown in help output.

#### defaultValue [#defaultvalue]

**Type:** `T`\
&#x2A;*Required:** No

Default value used when the environment variable is not set:

```typescript
{
    name: "TIMEOUT",
    type: Number,
    defaultValue: 5000, // Used if TIMEOUT is not set
}
```

#### hidden [#hidden-1]

**Type:** `boolean`\
&#x2A;*Required:** No\
&#x2A;*Default:** `false`

Hide environment variable from help output:

```typescript
{
    name: "SECRET_KEY",
    type: String,
    hidden: true, // Won't appear in help
}
```

#### typeLabel [#typelabel]

**Type:** `string`\
&#x2A;*Required:** No

Custom type label for help output (advanced).

## Complete Example [#complete-example]

```typescript
cli.addCommand({
    name: "deploy",
    alias: "d",
    description: "Deploy the application",
    group: "Deployment",
    examples: ["deploy --env production", "deploy --env staging --dry-run"],
    argument: {
        name: "target",
        type: String,
        description: "Deployment target",
        defaultValue: "production",
    },
    options: [
        {
            name: "env",
            alias: "e",
            type: String,
            required: true,
            description: "Environment name",
        },
        {
            name: "dry-run",
            type: Boolean,
            description: "Perform a dry run",
        },
    ],
    env: [
        {
            name: "API_KEY",
            type: String,
            description: "API key for deployment",
        },
        {
            name: "TIMEOUT",
            type: Number,
            defaultValue: 30000,
            description: "Deployment timeout in milliseconds",
        },
        {
            name: "FORCE_DEPLOY",
            type: Boolean,
            defaultValue: false,
            description: "Force deployment without confirmation",
        },
    ],
    execute: async ({ argument, options, env, logger }) => {
        const target = argument[0];
        const apiKey = env.apiKey;
        const timeout = env.timeout; // 30000 if not set
        const forceDeploy = env.forceDeploy; // false if not set

        logger.info(`Deploying to ${target} (${options.env})`);
        if (forceDeploy) {
            logger.info("Force deployment enabled");
        }
    },
});
```


# API Overview (/docs/packages/cerebro/api)



# API Overview [#api-overview]

Complete API reference for Cerebro CLI framework.

## Core API [#core-api]

### createCerebro() [#createcerebro]

Create a new CLI instance:

```typescript
function createCerebro<T extends Console = Console>(name: string, options?: CliOptions<T>): Cerebro<T>;
```

**Parameters:**

* `name` - CLI application name
* `options` - Configuration options (optional)

**Returns:** Configured Cerebro instance

**Example:**

```typescript
const cli = createCerebro("my-cli", {
    packageName: "my-cli",
    packageVersion: "1.0.0",
});
```

### Cerebro Class [#cerebro-class]

Main CLI class with the following methods:

#### addCommand() [#addcommand]

Register a command:

```typescript
cli.addCommand(command: Command): void
```

#### use() [#use]

Register a plugin:

```typescript
cli.use(plugin: Plugin): void
```

#### run() [#run]

Execute the CLI:

```typescript
await cli.run(argv?: string[]): Promise<void>
```

#### setDefaultCommand() [#setdefaultcommand]

Set default command:

```typescript
cli.setDefaultCommand(name: string): void
```

#### getCommands() [#getcommands]

Get all registered commands:

```typescript
cli.getCommands(): Map<string, Command>
```

## Built-in Commands [#built-in-commands]

* `HelpCommand` - Display help text
* `VersionCommand` - Show version
* `CompletionCommand` - Shell completion
* `ReadmeCommand` - Generate README

## Built-in Plugins [#built-in-plugins]

* `errorHandlerPlugin` - Error handling
* `runtimeVersionCheckPlugin` - Version validation
* `updateNotifierPlugin` - Update notifications

## Type Definitions [#type-definitions]

* `Command` - Command definition interface (supports `execute` or `loader`)
* `CommandExecute` - Handler signature shared by `execute` and `loader`
* `LazyCommandModule` - Module shape returned by a command `loader`
* `Plugin` - Plugin definition interface
* `Toolbox` - Execution context interface
* `CliOptions` - CLI configuration options
* `OptionDefinition` - Option definition interface
* `ArgumentDefinition` - Argument definition interface
* `EnvDefinition` - Environment variable definition
* `CreateOptions` - Derive a typed options object from a kebab-case input
* `CreateEnv` - Derive a typed env object from an UPPER\_SNAKE\_CASE input
* `OptionNameToCamelCase` - String type that converts `output-dir` → `outputDir`

## Helpers [#helpers]

* `lazyNamed(load, key)` - Builds a `loader` for handlers exported as named entries from a shared module
* `createCerebro(name, options)` - Factory function for a `Cerebro` instance

## Errors [#errors]

* `CerebroError` - Base error class
* `CommandNotFoundError` - Command lookup failed
* `CommandValidationError` - Command failed validation (e.g. missing required option)
* `CommandLoaderError` - `loader` rejected or returned no default-exported function
* `ConflictingOptionsError` - Two options that conflict were both passed
* `PluginError` - A plugin threw during a lifecycle hook

## Constants [#constants]

* `VERBOSITY_QUIET` - Quiet output level
* `VERBOSITY_NORMAL` - Normal output level
* `VERBOSITY_VERBOSE` - Verbose output level
* `VERBOSITY_DEBUG` - Debug output level


# Plugin (/docs/packages/cerebro/api/plugin)



# API: Plugin [#api-plugin]

Plugin interface for extending Cerebro functionality.

## Plugin Interface [#plugin-interface]

```typescript
interface Plugin {
    name: string;
    description?: string;
    version?: string;
    dependencies?: string[];
    init?: (context: PluginContext) => Promise<void> | void;
    execute?: (toolbox: Toolbox) => Promise<void> | void;
    beforeCommand?: (toolbox: Toolbox) => Promise<void> | void;
    afterCommand?: (toolbox: Toolbox, result: unknown) => Promise<void> | void;
    onError?: (error: Error, toolbox: Toolbox) => Promise<void> | void;
}
```

## Properties [#properties]

### name [#name]

**Type:** `string`\
&#x2A;*Required:** Yes

Unique plugin name:

```typescript
{
    name: "my-plugin";
}
```

### description [#description]

**Type:** `string`\
&#x2A;*Required:** No

Plugin description:

```typescript
{
    description: "Adds file system utilities";
}
```

### version [#version]

**Type:** `string`\
&#x2A;*Required:** No

Plugin version:

```typescript
{
    version: "1.0.0";
}
```

### dependencies [#dependencies]

**Type:** `string[]`\
&#x2A;*Required:** No

Other plugins this plugin depends on:

```typescript
{
    dependencies: ["logger", "filesystem"];
}
```

## Lifecycle Hooks [#lifecycle-hooks]

### init [#init]

Called once during plugin initialization:

```typescript
{
    init: async ({ cli, cwd, logger }) => {
        // Initialize plugin
        logger.info("Plugin initialized");
    };
}
```

### execute [#execute]

Called during command execution to extend toolbox:

```typescript
{
    execute: (toolbox) => {
        toolbox.myFeature = () => {
            console.log("My feature!");
        };
    };
}
```

### beforeCommand [#beforecommand]

Called before each command executes:

```typescript
{
    beforeCommand: async (toolbox) => {
        console.log(`Executing: ${toolbox.commandName}`);
    };
}
```

### afterCommand [#aftercommand]

Called after successful command execution:

```typescript
{
    afterCommand: async (toolbox, result) => {
        console.log(`Command completed: ${result}`);
    };
}
```

### onError [#onerror]

Called when an error occurs:

```typescript
{
    onError: async (error, toolbox) => {
        console.error(`Error in ${toolbox.commandName}:`, error);
    };
}
```

## PluginContext [#plugincontext]

Context provided to `init` hook:

```typescript
interface PluginContext<T extends Console = Console> {
    cli: Cli;
    cwd: string;
    logger: T;
}
```

## Complete Example [#complete-example]

```typescript
cli.addPlugin({
    name: "http-client",
    version: "1.0.0",
    description: "HTTP client utilities",
    dependencies: ["logger"],

    init: async ({ logger }) => {
        logger.info("HTTP client plugin initialized");
    },

    execute: (toolbox) => {
        toolbox.http = {
            get: async (url: string) => {
                const response = await fetch(url);
                return response.json();
            },
            post: async (url: string, data: unknown) => {
                const response = await fetch(url, {
                    method: "POST",
                    body: JSON.stringify(data),
                });
                return response.json();
            },
        };
    },

    beforeCommand: async (toolbox) => {
        toolbox.logger.debug(`Preparing HTTP client`);
    },

    afterCommand: async (toolbox, result) => {
        toolbox.logger.debug(`Command completed`);
    },

    onError: async (error, toolbox) => {
        toolbox.logger.error(`HTTP error:`, error);
    },
});
```


# Types (/docs/packages/cerebro/api/types)



# API: Types [#api-types]

TypeScript type definitions for Cerebro.

## Core Types [#core-types]

### Cli [#cli]

Main CLI class interface:

```typescript
interface Cli {
    addCommand(command: Command): this;
    addPlugin(plugin: Plugin): this;
    run(options?: CliRunOptions): Promise<void>;
    runCommand(commandName: string, options?: RunCommandOptions): Promise<unknown>;
    setDefaultCommand(commandName: string): this;
    setCommandSection(section: CommandSection): this;
    getCliName(): string;
    getCommands(): Map<string, Command>;
    getCwd(): string;
    getPackageName(): string | undefined;
    getPackageVersion(): string | undefined;
    getPluginManager(): PluginManager;
    dispose(): void;
}
```

### Command [#command]

Command definition. Either `execute` or `loader` must be set — not both.

```typescript
interface Command<O extends OptionDefinition = OptionDefinition, TContext extends Toolbox = Toolbox> {
    name: string;
    execute?: (toolbox: TContext) => Promise<void> | void;
    loader?: () => Promise<LazyCommandModule<TContext>>;
    description?: string;
    alias?: string | string[];
    argument?: ArgumentDefinition;
    options?: OptionDefinition[];
    env?: EnvDefinition[];
    hidden?: boolean;
    group?: string;
    examples?: string[] | string[][];
    usage?: Content[];
    file?: string;
    commandPath?: string[];
}
```

### CommandExecute [#commandexecute]

Handler signature, used by both `execute` and the resolved default export of `loader`.

```typescript
type CommandExecute<TContext> = ((toolbox: TContext) => Promise<void>) | ((toolbox: TContext) => void);
```

### LazyCommandModule [#lazycommandmodule]

Module shape returned by a command `loader`.

```typescript
interface LazyCommandModule<TContext> {
    default: CommandExecute<TContext>;
}
```

### Plugin [#plugin]

Plugin definition:

```typescript
interface Plugin {
    name: string;
    description?: string;
    version?: string;
    dependencies?: string[];
    init?: (context: PluginContext) => Promise<void> | void;
    execute?: (toolbox: Toolbox) => Promise<void> | void;
    beforeCommand?: (toolbox: Toolbox) => Promise<void> | void;
    afterCommand?: (toolbox: Toolbox, result: unknown) => Promise<void> | void;
    onError?: (error: Error, toolbox: Toolbox) => Promise<void> | void;
}
```

### Toolbox [#toolbox]

Command execution context:

```typescript
interface Toolbox<T extends Console = Console> extends Cerebro.ExtensionOverrides {
    argument: string[];
    argv: Record<string, any>;
    command: Command;
    commandName: string;
    logger: T;
    options: Options;
    runtime: Cli;
}
```

## Option Types [#option-types]

### OptionDefinition [#optiondefinition]

```typescript
interface OptionDefinition<T> {
    name: string;
    alias?: string | string[];
    type?: TypeConstructor<T>;
    description?: string;
    defaultValue?: T;
    required?: boolean;
    multiple?: boolean;
    lazyMultiple?: boolean;
    conflicts?: string | string[];
    implies?: Record<string, any>;
    hidden?: boolean;
    typeLabel?: string;
    group?: string;
}
```

### ArgumentDefinition [#argumentdefinition]

```typescript
interface ArgumentDefinition<T = any> {
    name: string;
    type?: TypeConstructor<T>;
    description?: string;
    defaultValue?: T;
    typeLabel?: string;
}
```

## Configuration Types [#configuration-types]

### CliOptions [#clioptions]

```typescript
interface CliOptions<T extends Console = Console> {
    argv?: ReadonlyArray<string>;
    cwd?: string;
    logger?: T;
    packageName?: string;
    packageVersion?: string;
}
```

### CliRunOptions [#clirunoptions]

```typescript
interface CliRunOptions {
    shouldExitProcess?: boolean;
    autoDispose?: boolean;
    [key: string]: any;
}
```

### RunCommandOptions [#runcommandoptions]

```typescript
interface RunCommandOptions {
    argv?: string[];
    [key: string]: any;
}
```

### CommandSection [#commandsection]

```typescript
interface CommandSection {
    header?: string;
    footer?: string;
}
```

## Verbosity Levels [#verbosity-levels]

```typescript
type VERBOSITY_LEVEL = 16 | 32 | 64 | 128 | 256;

const VERBOSITY_QUIET = 16;
const VERBOSITY_NORMAL = 32;
const VERBOSITY_VERBOSE = 64;
const VERBOSITY_DEBUG = 128;
```

## Extending Types [#extending-types]

### Extending Toolbox [#extending-toolbox]

```typescript
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            myFeature: () => void;
            api: {
                get: (url: string) => Promise<unknown>;
            };
        }
    }
}
```

## Type Exports [#type-exports]

All types are exported from the main package:

```typescript
import type {
    Cli,
    CliOptions,
    CliRunOptions,
    RunCommandOptions,
    Command,
    CommandExecute,
    LazyCommandModule,
    EnvDefinition,
    OptionDefinition,
    ArgumentDefinition,
    Plugin,
    PluginContext,
    Toolbox,
    CreateOptions,
    CreateEnv,
    OptionNameToCamelCase,
    VERBOSITY_LEVEL,
} from "@visulima/cerebro";

// Runtime exports
import { lazyNamed } from "@visulima/cerebro";
```


# Architecture (/docs/packages/cerebro/concepts/architecture)



# Architecture [#architecture]

Understand how Cerebro is structured and how its components work together.

## Core Components [#core-components]

### CLI Instance [#cli-instance]

The `Cerebro` class is the main entry point. It manages commands, plugins, and the execution lifecycle:

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-cli", {
    packageName: "my-cli",
    packageVersion: "1.0.0",
    logger: console, // Custom logger
    cwd: process.cwd(), // Working directory
    argv: process.argv.slice(2), // Command-line arguments
});
```

### Command Registry [#command-registry]

Commands are stored in a hierarchical registry that supports:

* Flat commands (`build`, `deploy`)
* Nested commands (`db migrate`, `server start`)
* Command aliases and suggestions

### Plugin System [#plugin-system]

Plugins extend the CLI's functionality through a lifecycle-based system:

1. **Registration**: Plugins are registered with `cli.use(plugin)`
2. **Initialization**: Plugins initialize before command execution
3. **Toolbox Extension**: Plugins can add properties to the execution context
4. **Lifecycle Hooks**: Plugins can hook into pre/post execution

### Toolbox Context [#toolbox-context]

Every command receives a `toolbox` context with:

```typescript
{
  argument: string[],      // Positional arguments
  options: Record<string, any>, // Parsed options
  env: Record<string, string>,  // Environment variables
  logger: Console,         // Logger instance
  cwd: string,             // Current working directory
  // ... plugin extensions
}
```

## Execution Flow [#execution-flow]

```
1. CLI Initialization
   └─> Load configuration
   └─> Register built-in commands
   └─> Register plugins

2. Argument Parsing
   └─> Parse command name
   └─> Parse options and flags
   └─> Parse positional arguments

3. Command Resolution
   └─> Find matching command
   └─> Suggest alternatives if not found
   └─> Validate nested command paths

4. Plugin Initialization
   └─> Execute plugin setup
   └─> Extend toolbox context
   └─> Register lifecycle hooks

5. Validation
   └─> Check required options
   └─> Validate option types
   └─> Check conflicting options
   └─> Validate environment variables

6. Command Execution
   └─> Prepare toolbox context
   └─> Execute command function
   └─> Handle errors
   └─> Return exit code
```

## Design Principles [#design-principles]

### Zero Dependencies Core [#zero-dependencies-core]

Cerebro's core has minimal dependencies, with optional peer dependencies for features:

* **Core**: Command parsing, validation, execution
* **Optional**: Boxed output, advanced logging, shell completion

### Type Safety [#type-safety]

Full TypeScript support with generics for type-safe toolbox extensions:

```typescript
// Declare custom toolbox properties
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            http: {
                get: <T>(url: string) => Promise<T>;
            };
        }
    }
}

// Now http is fully typed in commands
cli.addCommand({
    name: "fetch",
    execute: async ({ http }) => {
        const data = await http.get<User>("/api/user");
        // data is typed as User
    },
});
```

### Cross-Runtime Compatibility [#cross-runtime-compatibility]

Cerebro works across Node.js, Deno, and Bun through runtime abstraction:

* Process access (`argv`, `cwd`, `env`)
* Exit handling
* Exception management

### Extensibility [#extensibility]

Three extension points:

1. **Commands**: Add new commands
2. **Plugins**: Extend functionality
3. **Toolbox**: Add custom context properties

## Command Hierarchy [#command-hierarchy]

Commands can be organized in a tree structure:

```
my-cli
├── build              # Flat command
├── deploy            # Flat command
└── db                # Command group
    ├── migrate      # Nested command
    ├── seed         # Nested command
    └── backup       # Nested command
```

Implementation:

```typescript
cli.addCommand({
    name: "db",
    description: "Database commands",
    commands: [
        { name: "migrate", execute: ({ logger }) => {} },
        { name: "seed", execute: ({ logger }) => {} },
        { name: "backup", execute: ({ logger }) => {} },
    ],
});
```

## Error Handling [#error-handling]

Cerebro provides comprehensive error handling:

* **Command Not Found**: Suggests alternatives using Levenshtein distance
* **Validation Errors**: Clear messages for invalid options
* **Execution Errors**: Captures and formats runtime errors
* **Exit Codes**: Standard Unix exit codes (0 = success, 1 = error)

```typescript
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

cli.use(
    errorHandlerPlugin({
        exitOnError: true,
        showStackTrace: false,
    }),
);
```


# Commands (/docs/packages/cerebro/concepts/commands)



# Commands [#commands]

Learn about Cerebro's command system and how to create powerful CLI commands.

## Command Structure [#command-structure]

A command is defined by its metadata and either an inline `execute` function
or a `loader` that defers handler import until invocation:

```typescript
{
  name: string,              // Command name
  description: string,       // Help text description
  argument?: ArgumentDef,    // Positional argument
  options?: OptionDef[],     // Named options/flags
  env?: EnvDef,              // Environment variables
  commandPath?: string[],    // Path for nested subcommands
  // Exactly one of:
  execute?: (toolbox) => void,                    // Inline handler
  loader?: () => Promise<{ default: handler }>,   // Lazy-imported handler
}
```

## Basic Commands [#basic-commands]

Simple command with no arguments:

```typescript
cli.addCommand({
    name: "hello",
    description: "Say hello",
    execute: ({ logger }) => {
        logger.log("Hello!");
    },
});
```

## Arguments [#arguments]

Positional arguments that come after the command name:

```typescript
cli.addCommand({
    name: "greet",
    description: "Greet someone",
    argument: {
        name: "name",
        description: "Person to greet",
        type: String,
        required: true,
    },
    execute: ({ argument, logger }) => {
        logger.log(`Hello, ${argument[0]}!`);
    },
});
```

Usage:

```bash
$ my-cli greet Alice
Hello, Alice!
```

## Options [#options]

Named options with values or flags:

```typescript
cli.addCommand({
    name: "build",
    description: "Build project",
    options: [
        {
            name: "output",
            alias: "o",
            description: "Output directory",
            type: String,
            defaultValue: "./dist",
        },
        {
            name: "production",
            alias: "p",
            description: "Production build",
            type: Boolean,
        },
        {
            name: "minify",
            description: "Minify output",
            type: Boolean,
            defaultValue: true,
        },
    ],
    execute: ({ options, logger }) => {
        logger.log(`Building to ${options.output}`);
        logger.log(`Production: ${options.production}`);
        logger.log(`Minify: ${options.minify}`);
    },
});
```

Usage:

```bash
$ my-cli build --output ./build --production
Building to ./build
Production: true
Minify: true
```

## Option Types [#option-types]

Cerebro supports multiple option types:

### String Options [#string-options]

```typescript
{
  name: "config",
  type: String,
  defaultValue: "config.json",
}
```

### Boolean Flags [#boolean-flags]

```typescript
{
  name: "verbose",
  type: Boolean,
}
```

### Number Options [#number-options]

```typescript
{
  name: "port",
  type: Number,
  defaultValue: 3000,
}
```

### Negatable Options [#negatable-options]

Options that can be negated with `--no-` prefix:

```typescript
{
  name: "color",
  type: Boolean,
  defaultValue: true,
  negatable: true, // Allows --no-color
}
```

Usage:

```bash
$ my-cli build --color      # color = true
$ my-cli build --no-color   # color = false
```

## Required Options [#required-options]

Mark options as required:

```typescript
cli.addCommand({
    name: "deploy",
    description: "Deploy application",
    options: [
        {
            name: "environment",
            alias: "e",
            description: "Target environment",
            type: String,
            required: true, // Must be provided
        },
    ],
    execute: ({ options, logger }) => {
        logger.log(`Deploying to ${options.environment}`);
    },
});
```

Error if not provided:

```bash
$ my-cli deploy
Error: Required option --environment is missing
```

## Conflicting Options [#conflicting-options]

Prevent incompatible options:

```typescript
cli.addCommand({
    name: "test",
    description: "Run tests",
    options: [
        {
            name: "watch",
            type: Boolean,
            conflicts: ["ci"], // Can't use with --ci
        },
        {
            name: "ci",
            type: Boolean,
            conflicts: ["watch"], // Can't use with --watch
        },
    ],
    execute: ({ options }) => {
        // ...
    },
});
```

## Implied Options [#implied-options]

Set default values for other options:

```typescript
{
  name: "production",
  type: Boolean,
  implies: {
    minify: true,    // Sets minify to true
    sourcemap: false, // Sets sourcemap to false
  },
}
```

## Environment Variables [#environment-variables]

Access typed environment variables:

```typescript
cli.addCommand({
    name: "deploy",
    description: "Deploy application",
    env: {
        API_KEY: {
            description: "API authentication key",
            required: true,
        },
        API_URL: {
            description: "API endpoint URL",
            required: false,
            defaultValue: "https://api.example.com",
        },
    },
    execute: ({ env, logger }) => {
        logger.log(`Deploying to ${env.API_URL}`);
        logger.log(`Using key: ${env.API_KEY}`);
    },
});
```

## Nested Commands [#nested-commands]

Create command hierarchies for better organization:

```typescript
cli.addCommand({
    name: "database",
    alias: "db",
    description: "Database management",
    commands: [
        {
            name: "migrate",
            description: "Run migrations",
            options: [
                {
                    name: "rollback",
                    type: Boolean,
                    description: "Rollback migrations",
                },
            ],
            execute: ({ options, logger }) => {
                if (options.rollback) {
                    logger.log("Rolling back migrations...");
                } else {
                    logger.log("Running migrations...");
                }
            },
        },
        {
            name: "seed",
            description: "Seed database",
            execute: ({ logger }) => {
                logger.log("Seeding database...");
            },
        },
    ],
});
```

Usage:

```bash
$ my-cli db migrate
$ my-cli db migrate --rollback
$ my-cli db seed
```

## Default Commands [#default-commands]

Set a default command when no command is specified:

```typescript
cli.setDefaultCommand("help");

// or with options
cli.addCommand({
    name: "serve",
    description: "Start server",
    isDefault: true,
    execute: ({ logger }) => {
        logger.log("Starting server...");
    },
});
```

## Command Sections [#command-sections]

Organize help output with sections:

```typescript
cli.addCommandSection({
    name: "Database",
    description: "Database management commands",
    commands: ["db:migrate", "db:seed", "db:backup"],
});
```

## Lazy Commands [#lazy-commands]

For CLIs with many subcommands or heavy per-command dependencies, defer
importing each handler until the command is actually invoked. Declare
metadata inline and point `loader` at a dynamic `import()`:

```typescript
// commands/build/index.ts
const build: Command = {
    name: "build",
    description: "Build the project",
    options: [{ name: "output", alias: "o", type: String }],
    loader: () => import("./handler"),
};
export default build;

// commands/build/handler.ts
export default ({ logger, options }) => {
    logger.info(`Building to ${options.output ?? "dist"}`);
};
```

`loader` is a zero-argument function that returns a promise resolving to
a module with a default-exported handler. Help, completion, and option
validation work entirely from the metadata you declared on `addCommand`
and never trigger the loader. The first invocation imports the module;
subsequent calls reuse the cached handler.

A command must declare either `execute` or `loader`, but not both. If a
loader rejects or returns a module without a default-exported function, a
`CommandLoaderError` is thrown.

For modules that export multiple subcommand handlers as named exports,
use the `lazyNamed` helper:

```typescript
import { lazyNamed } from "@visulima/cerebro";

cli.addCommand({
    name: "list",
    commandPath: ["cache"],
    loader: lazyNamed(() => import("./cache.handlers"), "cacheList"),
});
```


# Plugins (/docs/packages/cerebro/concepts/plugins)



# Plugins [#plugins]

Extend Cerebro's functionality with plugins that hook into the CLI lifecycle and add custom features to the toolbox.

## Plugin Structure [#plugin-structure]

A plugin is a function that returns a plugin definition:

```typescript
import type { Plugin } from "@visulima/cerebro";

const myPlugin = (): Plugin => ({
    name: "my-plugin",
    version: "1.0.0",
    register: async (context) => {
        // Initialize plugin
        context.toolbox.myFeature = {
            doSomething: () => console.log("Doing something!"),
        };
    },
});
```

## Plugin Lifecycle [#plugin-lifecycle]

### Registration [#registration]

Plugins are registered with the CLI instance:

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-cli");
cli.use(myPlugin());
```

### Initialization [#initialization]

Plugins initialize before command execution and receive a context object:

```typescript
{
  register: async (context: PluginContext) => {
    const { toolbox, cli, logger } = context;

    // Extend toolbox for commands
    toolbox.http = {
      get: async (url) => { /* ... */ },
      post: async (url, data) => { /* ... */ },
    };

    // Access CLI instance
    const commands = cli.getCommands();

    // Use logger
    logger.log("Plugin initialized");
  },
}
```

### Toolbox Extension [#toolbox-extension]

Plugins extend the toolbox that commands receive:

```typescript
// In plugin
toolbox.database = {
    connect: async () => {
        /* ... */
    },
    query: async (sql) => {
        /* ... */
    },
};

// In command
cli.addCommand({
    name: "query",
    execute: async ({ database, logger }) => {
        await database.connect();
        const result = await database.query("SELECT * FROM users");
        logger.log(result);
    },
});
```

## Type-Safe Extensions [#type-safe-extensions]

Declare custom toolbox properties for full type safety:

```typescript
// Extend the Cerebro namespace
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            http: {
                get: <T>(url: string) => Promise<T>;
                post: <T>(url: string, data: unknown) => Promise<T>;
            };
            database: {
                connect: () => Promise<void>;
                query: <T>(sql: string) => Promise<T[]>;
            };
        }
    }
}

// Create plugin
const databasePlugin = (): Plugin => ({
    name: "database",
    register: async ({ toolbox }) => {
        toolbox.database = {
            connect: async () => {
                /* ... */
            },
            query: async (sql) => {
                /* ... */
            },
        };
    },
});

// Use in commands with full autocomplete
cli.addCommand({
    name: "users",
    execute: async ({ database }) => {
        // ✅ Full type safety and autocomplete
        await database.connect();
        const users = await database.query<User>("SELECT * FROM users");
    },
});
```

## Built-in Plugins [#built-in-plugins]

### Error Handler Plugin [#error-handler-plugin]

Graceful error handling with formatted output:

```typescript
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

cli.use(
    errorHandlerPlugin({
        exitOnError: true, // Exit process on error
        showStackTrace: false, // Hide stack traces
        logErrors: true, // Log errors to console
    }),
);
```

### Runtime Version Check Plugin [#runtime-version-check-plugin]

Check Node.js/Deno/Bun version requirements:

```typescript
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";

cli.use(
    runtimeVersionCheckPlugin({
        requiredVersion: ">=18.0.0", // Minimum Node.js version
        message: "Please upgrade to Node.js 18 or higher",
    }),
);
```

### Update Notifier Plugin [#update-notifier-plugin]

Notify users of available updates:

```typescript
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

cli.use(
    updateNotifierPlugin({
        packageName: "my-cli",
        packageVersion: "1.0.0",
        checkInterval: 86400000, // Check once per day
        updateMessage: "Update available: {latest} (current: {current})",
    }),
);
```

## Custom Plugin Example [#custom-plugin-example]

Create a plugin that adds HTTP utilities:

```typescript
import type { Plugin } from "@visulima/cerebro";

// Type declaration
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            http: {
                get: <T>(url: string) => Promise<T>;
                post: <T>(url: string, data: unknown) => Promise<T>;
            };
        }
    }
}

// Plugin implementation
export const httpPlugin = (): Plugin => ({
    name: "http",
    version: "1.0.0",
    register: async ({ toolbox, logger }) => {
        logger.log("Initializing HTTP plugin");

        toolbox.http = {
            get: async <T>(url: string): Promise<T> => {
                const response = await fetch(url);
                return response.json() as Promise<T>;
            },

            post: async <T>(url: string, data: unknown): Promise<T> => {
                const response = await fetch(url, {
                    method: "POST",
                    headers: { "Content-Type": "application/json" },
                    body: JSON.stringify(data),
                });
                return response.json() as Promise<T>;
            },
        };
    },
});

// Usage
cli.use(httpPlugin());

cli.addCommand({
    name: "fetch-user",
    argument: {
        name: "id",
        type: String,
    },
    execute: async ({ argument, http, logger }) => {
        const user = await http.get<User>(`/api/users/${argument[0]}`);
        logger.log(`User: ${user.name}`);
    },
});
```

## Plugin Dependencies [#plugin-dependencies]

Plugins can depend on other plugins:

```typescript
const databasePlugin = (): Plugin => ({
    name: "database",
    dependencies: ["config"], // Requires config plugin
    register: async ({ toolbox }) => {
        const { config } = toolbox;
        toolbox.database = createDatabase(config.databaseUrl);
    },
});
```

## Plugin Best Practices [#plugin-best-practices]

### Keep Plugins Focused [#keep-plugins-focused]

Each plugin should have a single responsibility:

```typescript
// ✅ Good: Focused plugin
const configPlugin = (): Plugin => ({
    name: "config",
    register: async ({ toolbox }) => {
        toolbox.config = loadConfig();
    },
});

// ❌ Bad: Plugin does too much
const megaPlugin = (): Plugin => ({
    name: "mega",
    register: async ({ toolbox }) => {
        toolbox.config = loadConfig();
        toolbox.database = connectDatabase();
        toolbox.cache = createCache();
        toolbox.logger = createLogger();
    },
});
```

### Handle Errors Gracefully [#handle-errors-gracefully]

Plugins should not crash the CLI:

```typescript
const plugin = (): Plugin => ({
    name: "my-plugin",
    register: async ({ toolbox, logger }) => {
        try {
            toolbox.feature = await initializeFeature();
        } catch (error) {
            logger.error(`Failed to initialize feature: ${error.message}`);
            // Provide fallback
            toolbox.feature = createFallback();
        }
    },
});
```

### Document Type Extensions [#document-type-extensions]

Always provide type declarations for toolbox extensions:

```typescript
// ✅ Good: Type-safe extension
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            myFeature: {
                doSomething: () => void;
            };
        }
    }
}
```


# Configuration (/docs/packages/cerebro/configuration)



# Configuration [#configuration]

Configure Cerebro CLI instances with various options and settings.

## CLI Options [#cli-options]

Configure the CLI instance at creation:

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-cli", {
    packageName: "@company/my-cli",
    packageVersion: "1.0.0",
    logger: console,
    cwd: process.cwd(),
    argv: process.argv.slice(2),
});
```

### packageName [#packagename]

The npm package name:

```typescript
{
    packageName: "@company/my-cli";
}
```

Used by:

* Update notifier plugin
* Version command
* Help text generation

### packageVersion [#packageversion]

The package version:

```typescript
{
    packageVersion: "1.0.0";
}
```

Displayed by `--version` flag.

### logger [#logger]

Custom logger instance (default: `console`):

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail();

const cli = createCerebro("my-cli", {
    logger,
});
```

### cwd [#cwd]

Working directory (default: `process.cwd()`):

```typescript
{
    cwd: "/custom/directory";
}
```

### argv [#argv]

Command-line arguments (default: `process.argv.slice(2)`):

```typescript
{
    argv: ["build", "--production"];
}
```

## Environment Variables [#environment-variables]

### CEREBRO\_OUTPUT\_LEVEL [#cerebro_output_level]

Control output verbosity:

```bash
CEREBRO_OUTPUT_LEVEL=quiet my-cli build    # No output
CEREBRO_OUTPUT_LEVEL=normal my-cli build   # Normal output (default)
CEREBRO_OUTPUT_LEVEL=verbose my-cli build  # Verbose output
CEREBRO_OUTPUT_LEVEL=debug my-cli build    # Debug output
```

Values:

* `quiet` - No output
* `normal` - Standard output
* `verbose` - Detailed output
* `debug` - Debug information

### CEREBRO\_MIN\_NODE\_VERSION [#cerebro_min_node_version]

Override minimum Node.js version check:

```bash
CEREBRO_MIN_NODE_VERSION=16.0.0 my-cli build
```

### CEREBRO\_TERMINAL\_WIDTH [#cerebro_terminal_width]

Override terminal width detection:

```bash
CEREBRO_TERMINAL_WIDTH=120 my-cli help
```

## Plugin Configuration [#plugin-configuration]

### Error Handler [#error-handler]

```typescript
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

cli.use(
    errorHandlerPlugin({
        exitOnError: true, // Exit process on errors
        showStackTrace: false, // Hide stack traces
        logErrors: true, // Log to console
    }),
);
```

### Runtime Version Check [#runtime-version-check]

```typescript
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";

cli.use(
    runtimeVersionCheckPlugin({
        requiredVersion: ">=18.0.0",
        message: "Custom error message",
    }),
);
```

### Update Notifier [#update-notifier]

```typescript
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

cli.use(
    updateNotifierPlugin({
        packageName: "my-cli",
        packageVersion: "1.0.0",
        checkInterval: 86400000, // 24 hours in ms
        updateMessage: "Update available: {latest}",
    }),
);
```

## Command Configuration [#command-configuration]

### Global Options [#global-options]

Add options available to all commands:

```typescript
cli.addGlobalOption({
    name: "config",
    alias: "c",
    description: "Configuration file path",
    type: String,
    defaultValue: "./config.json",
});
```

### Default Command [#default-command]

Set command to run when none specified:

```typescript
cli.setDefaultCommand("help");
```

### Help Sections [#help-sections]

Organize commands in help output:

```typescript
cli.addCommandSection({
    name: "Database Commands",
    description: "Manage database operations",
    commands: ["db:migrate", "db:seed"],
});

cli.addCommandSection({
    name: "Build Commands",
    description: "Build and deploy",
    commands: ["build", "deploy"],
});
```

## Configuration Files [#configuration-files]

Create a configuration file system:

```typescript
// my-cli.config.json
{
  "output": "./dist",
  "minify": true,
  "sourcemap": false,
  "plugins": ["@my-cli/plugin-react"]
}
```

Load configuration:

```typescript
import { resolve } from "path";
import { readFileSync, existsSync } from "fs";

function loadConfig(cwd: string) {
    const configPath = resolve(cwd, "my-cli.config.json");

    if (!existsSync(configPath)) {
        return {};
    }

    return JSON.parse(readFileSync(configPath, "utf-8"));
}

cli.addCommand({
    name: "build",
    execute: async ({ cwd, logger }) => {
        const config = loadConfig(cwd);
        logger.log(`Using config:`, config);
    },
});
```

## TypeScript Configuration [#typescript-configuration]

Configure TypeScript for your CLI project:

```json
// tsconfig.json
{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ES2022",
        "moduleResolution": "bundler",
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "declaration": true,
        "declarationMap": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}
```


# Advanced Features (/docs/packages/cerebro/guides/advanced)





Learn about advanced Cerebro features for building complex CLIs.

## Command Composition [#command-composition]

Call commands from within other commands using `runtime.runCommand()`:

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        logger.info("Building...");
        await runtime.runCommand("build", {
            argv: ["--production"],
        });

        logger.info("Testing...");
        await runtime.runCommand("test", {
            argv: ["--coverage"],
        });

        logger.info("Deploying...");
    },
});
```

### Passing Arguments [#passing-arguments]

Pass arguments to called commands:

```typescript
await runtime.runCommand("copy", {
    argv: ["file1.txt", "file2.txt"],
});
```

### Passing Options [#passing-options]

Pass options to called commands:

```typescript
await runtime.runCommand("build", {
    argv: ["--production", "--output", "dist"],
});
```

### Merging Options [#merging-options]

Merge additional options:

```typescript
await runtime.runCommand("build", {
    argv: ["--production"],
    customOption: "value",
});
```

### Getting Return Values [#getting-return-values]

Commands can return values:

```typescript
cli.addCommand({
    name: "calculate",
    execute: () => {
        return 42;
    },
});

cli.addCommand({
    name: "use-calculation",
    execute: async ({ runtime }) => {
        const result = await runtime.runCommand("calculate");
        console.log(`Result: ${result}`); // 42
    },
});
```

## Custom CLI Configuration [#custom-cli-configuration]

Configure your CLI instance:

```typescript
const cli = new Cerebro("my-app", {
    packageName: "my-app",
    packageVersion: "1.0.0",
    cwd: "/custom/path",
    logger: customLogger,
    argv: process.argv.slice(2), // Custom argv
});
```

### Custom Logger [#custom-logger]

Provide a custom logger:

```typescript
const customLogger = {
    info: (...args) => console.log("[INFO]", ...args),
    error: (...args) => console.error("[ERROR]", ...args),
    warn: (...args) => console.warn("[WARN]", ...args),
    debug: (...args) => console.debug("[DEBUG]", ...args),
};

const cli = new Cerebro("my-app", {
    logger: customLogger,
});
```

## Command Sections [#command-sections]

Customize help output:

```typescript
cli.setCommandSection({
    header: "My Awesome CLI v1.0.0",
    footer: "For more info, visit https://example.com",
});
```

## Default Command [#default-command]

Set a default command when none is provided:

```typescript
cli.setDefaultCommand("help"); // Shows help by default
cli.setDefaultCommand("start"); // Runs start command by default
```

## Lazy Command Loading [#lazy-command-loading]

For CLIs with many commands or heavy per-command dependencies, the
combined startup cost of evaluating every command's module at import
time can dominate `--help` and short-running commands. Cerebro lets you
defer the handler import until the command is actually invoked.

### When to use it [#when-to-use-it]

You'll see a meaningful win when:

* You have **10+ commands** registered.
* Most commands pull in heavy transitive deps (rendering libs, AI clients,
  database drivers, …) that aren't needed for `--help` or unrelated
  commands.
* Startup time matters — interactive CLIs, frequently-invoked dev tools,
  serverless contexts.

For a tiny CLI with two subcommands and minimal deps, the difference is
noise — leave them eager.

### How it works [#how-it-works]

Replace `execute` with `loader: () => import("./handler")`. The loader
returns a promise resolving to a module whose **default export** is the
handler:

```typescript
// commands/build.ts
const build: Command = {
    name: "build",
    description: "Build the project",
    options: [{ name: "output", type: String, alias: "o" }],
    loader: () => import("./build.handler"),
};
export default build;

// commands/build.handler.ts
export default async ({ logger, options }) => {
    logger.info(`Building to ${options.output ?? "dist"}`);
};
```

Help, completion, and option validation iterate metadata only — they
never trigger loaders. The first invocation of the command imports the
handler module; the resolved handler is memoised on the command for
subsequent calls within the same process.

### Typed handlers [#typed-handlers]

Co-locate the option type with the metadata using `CreateOptions<T>`:

```typescript
// commands/build.ts
import type { Command, CreateOptions } from "@visulima/cerebro";

export type BuildOptions = CreateOptions<{
    output: string | undefined;
    production: boolean | undefined;
}>;

const build: Command = {
    name: "build",
    options: [
        { name: "output", type: String },
        { name: "production", type: Boolean },
    ],
    loader: () => import("./build.handler"),
};
export default build;

// commands/build.handler.ts
import type { Toolbox } from "@visulima/cerebro";
import type { BuildOptions } from "./index";

export default async ({ options }: Toolbox<Console, BuildOptions>) => {
    // options.output: string | undefined
    // options.production: boolean | undefined
};
```

### Shared handler modules [#shared-handler-modules]

When several subcommands of a parent share helpers, put their handlers
together as **named exports** in one module and load each via `lazyNamed`:

```typescript
// commands/cache.handlers.ts
export const cacheList: CommandExecute<Toolbox> = async (toolbox) => {
    /* … */
};
export const cacheClean: CommandExecute<Toolbox> = async (toolbox) => {
    /* … */
};

// commands/cache.ts
import { lazyNamed, type Command } from "@visulima/cerebro";

const cacheList: Command = {
    name: "list",
    commandPath: ["cache"],
    loader: lazyNamed(() => import("./cache.handlers"), "cacheList"),
};
const cacheClean: Command = {
    name: "clean",
    commandPath: ["cache"],
    loader: lazyNamed(() => import("./cache.handlers"), "cacheClean"),
};
```

The shared module is imported once (when any cache subcommand runs); each
subcommand resolves to its own named export.

### Recommended layout [#recommended-layout]

For each command, two files in a directory:

```
commands/
  build/
    index.ts     # metadata stub (cheap import: only types + the loader)
    handler.ts   # heavy imports + default-exported handler
  ...
```

Node's module resolution maps `import build from "./commands/build"` to
`./commands/build/index.ts`, so existing `cli.addCommand(buildCommand)`
calls keep working unchanged.

### Errors [#errors]

If `loader()` rejects, or the resolved module has no default-exported
function, cerebro throws a `CommandLoaderError`. The original error is
attached as `cause`.

```typescript
import { CommandLoaderError } from "@visulima/cerebro";

try {
    await cli.run({ shouldExitProcess: false });
} catch (error) {
    if (error instanceof CommandLoaderError) {
        console.error(`Failed to load ${error.commandName}:`, error.cause);
    }
}
```

## Running Without Exiting [#running-without-exiting]

For testing or programmatic use:

```typescript
await cli.run({
    shouldExitProcess: false, // Don't exit process
    autoDispose: false, // Don't cleanup automatically
});
```

## Error Handling [#error-handling]

### Custom Error Handling [#custom-error-handling]

Use plugins for custom error handling:

```typescript
cli.addPlugin({
    name: "error-handler",
    onError: async (error, toolbox) => {
        // Custom error formatting
        console.error(`❌ Error in ${toolbox.commandName}:`);
        console.error(error.message);

        // Log to file
        await logErrorToFile(error, toolbox);

        // Send to monitoring
        await sendToMonitoring(error);
    },
});
```

### Error Types [#error-types]

Cerebro provides specific error types:

```typescript
import { CommandNotFoundError, CommandValidationError } from "@visulima/cerebro";

// Handle specific errors
try {
    await cli.run();
} catch (error) {
    if (error instanceof CommandNotFoundError) {
        console.error(`Command not found: ${error.command}`);
        console.error(`Did you mean: ${error.alternatives.join(", ")}?`);
    } else if (error instanceof CommandValidationError) {
        console.error(`Validation error: ${error.message}`);
    }
}
```

## Shell Completions [#shell-completions]

Enable shell autocompletions for your CLI.

### Installation [#installation]

Install the required dependency:

<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;]">
  <Tab value="pnpm">
    `bash pnpm add @bomb.sh/tab `
  </Tab>

  <Tab value="npm">
    `bash npm install @bomb.sh/tab `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @bomb.sh/tab `
  </Tab>
</Tabs>

### Setup [#setup]

Add the completion command to your CLI:

```typescript
import completionCommand from "@visulima/cerebro/command/completion";

cli.addCommand(completionCommand);
```

Then generate completions:

```bash
cli completion --shell=zsh > ~/.zshrc
cli completion --shell=bash > ~/.bashrc
cli completion --shell=fish > ~/.config/fish/completions/cli.fish
cli completion --shell=powershell > cli.ps1
```

## README Generation [#readme-generation]

Generate comprehensive README documentation for your CLI commands automatically.

### Installation [#installation-1]

First, install the required dependency:

<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;]">
  <Tab value="pnpm">
    `bash pnpm add github-slugger `
  </Tab>

  <Tab value="npm">
    `bash npm install github-slugger `
  </Tab>

  <Tab value="yarn">
    `bash yarn add github-slugger `
  </Tab>
</Tabs>

### Setup [#setup-1]

Add the readme command to your CLI:

```typescript
import readmeCommand from "@visulima/cerebro/command/readme-generator";

cli.addCommand(readmeCommand);
```

### Basic Usage [#basic-usage]

Generate a README with all your commands:

```bash
cli readme
```

This will:

* Read or create a `README.md` file
* Generate usage examples
* List all commands with descriptions
* Create a table of contents
* Replace content between special tags: `<!-- usage -->`, `<!-- commands -->`, `<!-- toc -->`

### README Template [#readme-template]

The command uses special HTML comment tags to mark sections:

```markdown
# My CLI

<!-- usage -->
<!-- usagestop -->

<!-- commands -->
<!-- commandsstop -->

<!-- toc -->
<!-- tocstop -->
```

The `readme` command will replace content between these tags.

### Options [#options]

#### `--readme-path` [#--readme-path]

Specify a custom README file path:

```bash
cli readme --readme-path=DOCS.md
```

#### `--output-dir` [#--output-dir]

Set output directory for multi-file mode (default: `docs`):

```bash
cli readme --multi --output-dir=documentation
```

#### `--multi` [#--multi]

Generate multi-file documentation grouped by command groups:

```bash
cli readme --multi
```

This creates separate markdown files for each command group in the output directory.

#### `--aliases` [#--aliases]

Include command aliases in the command list:

```bash
cli readme --aliases
```

#### `--dry-run` [#--dry-run]

Preview what would be generated without writing files:

```bash
cli readme --dry-run
```

#### `--version` [#--version]

Specify a custom version for the generated documentation:

```bash
cli readme --version=2.0.0
```

#### `--nested-topics-depth` [#--nested-topics-depth]

Control maximum depth for nested topics in multi-file mode:

```bash
cli readme --multi --nested-topics-depth=2
```

### Example Workflow [#example-workflow]

1. **Create a README template** with the special tags:

```markdown
# My Awesome CLI

<!-- usage -->
<!-- usagestop -->

<!-- commands -->
<!-- commandsstop -->

<!-- toc -->
<!-- tocstop -->
```

2. **Add the readme command** to your CLI:

```typescript
import readmeCommand from "@visulima/cerebro/command/readme-generator";

cli.addCommand(readmeCommand);
```

3. **Generate the README**:

```bash
cli readme
```

4. **The README will be updated** with:
   * Installation and usage instructions
   * Complete command list with descriptions
   * Command documentation with options and examples
   * Table of contents

### Multi-File Documentation [#multi-file-documentation]

For larger CLIs, use multi-file mode to organize documentation:

```bash
cli readme --multi --output-dir=docs
```

This creates:

* `docs/Build.md` - Commands in the "Build" group
* `docs/Deploy.md` - Commands in the "Deploy" group
* And updates `README.md` with links to these files

### Cross-Platform Line Endings [#cross-platform-line-endings]

The `readme` command automatically handles different line ending formats (LF, CRLF, CR) and normalizes them to LF for consistent output across platforms.

## Verbosity Levels [#verbosity-levels]

Control output verbosity:

```typescript
// In your CLI options
{
  name: "verbose",
  type: Boolean,
  description: "Verbose output"
}

// Or use environment variable
process.env.CEREBRO_OUTPUT_LEVEL = "64"; // VERBOSITY_VERBOSE
```

Available levels:

* `VERBOSITY_QUIET` (16) - Minimal output
* `VERBOSITY_NORMAL` (32) - Normal output
* `VERBOSITY_VERBOSE` (64) - Verbose output
* `VERBOSITY_DEBUG` (128) - Debug output

## Command Groups [#command-groups]

Organize commands:

```typescript
cli.addCommand({
    name: "build",
    group: "Development",
    execute: () => {},
});

cli.addCommand({
    name: "test",
    group: "Development",
    execute: () => {},
});

cli.addCommand({
    name: "deploy",
    group: "Production",
    execute: () => {},
});
```

Help output will group commands accordingly.

## Multiple Commands [#multiple-commands]

Register multiple commands efficiently:

```typescript
const commands = [
    {
        name: "build",
        execute: () => {},
    },
    {
        name: "test",
        execute: () => {},
    },
    {
        name: "deploy",
        execute: () => {},
    },
];

commands.forEach((cmd) => cli.addCommand(cmd));
```

## TypeScript Best Practices [#typescript-best-practices]

### Extending Toolbox Type [#extending-toolbox-type]

```typescript
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            myFeature: () => void;
            api: {
                get: (url: string) => Promise<unknown>;
            };
        }
    }
}
```

### Typed Commands [#typed-commands]

```typescript
interface BuildOptions {
    production: boolean;
    output: string;
}

cli.addCommand({
    name: "build",
    options: [
        { name: "production", type: Boolean },
        { name: "output", type: String },
    ],
    execute: ({ options }: { options: BuildOptions }) => {
        // TypeScript knows the options structure
    },
});
```

## Performance Helpers [#performance-helpers]

Cerebro ships with two standalone helpers that run **before** the CLI framework loads.
Call them at the very top of your entry point — before `createCerebro()` and any heavy imports.

```typescript
// bin.ts
import enableCompileCache from "@visulima/cerebro/compile-cache";
import { applyHeapTuning } from "@visulima/cerebro/heap-tuning";

// 1. Tune V8 heap (may re-spawn the process and never return)
applyHeapTuning();

// 2. Enable compile cache for faster subsequent startups
enableCompileCache();

// Now load the rest of your CLI
import { createCerebro } from "@visulima/cerebro";
const cli = createCerebro("my-cli");
// ...
```

### Heap Tuning [#heap-tuning]

`applyHeapTuning()` computes optimal `--max-old-space-size` and `--max-semi-space-size`
V8 flags based on system memory. Because these flags can only be set at process startup,
the helper re-spawns the current process with the computed flags when they are missing.
After re-spawn, the flags are already present and the call becomes a no-op.

**How it works:**

* Allocates a percentage of total system RAM to V8's old-space (default: 75%)
* Applies tiered semi-space sizing for the young generation:

| Old-space (MiB) | Semi-space (MiB) |
| --------------- | ---------------- |
| ≤ 512           | 4                |
| ≤ 1024          | 8                |
| ≤ 2048          | 16               |
| ≤ 4096          | 32               |
| ≤ 8192          | 64               |
| > 8192          | log2-scaled      |

* Respects existing flags — if the user sets `NODE_OPTIONS="--max-old-space-size=4096"`, their value is kept

**Custom allocation:**

```typescript
// Use 50% of RAM instead of the default 75%
applyHeapTuning({ maxOldSpacePercent: 0.5 });
```

### Compile Cache [#compile-cache]

`enableCompileCache()` enables V8's compile cache so that subsequent runs of your CLI
skip re-parsing and re-compiling JavaScript source files. This can reduce startup time
by 30–70% for large CLI tools.

**How it works:**

1. Tries `module.enableCompileCache()` — a native Node.js 22.8+ API that stores compiled
   bytecode alongside source files for instant reuse
2. Falls back to the [`v8-compile-cache`](https://www.npmjs.com/package/v8-compile-cache) npm
   package on older Node.js versions (must be installed as a dependency)
3. If neither is available, silently does nothing

## Performance Tips [#performance-tips]

1. **Use the performance helpers above** - Heap tuning and compile cache make the biggest difference
2. **Lazy load plugins** - Only load plugins when needed
3. **Use command groups** - Organize commands for faster lookups
4. **Cache expensive operations** - Cache results in plugin `init`
5. **Minimize toolbox extensions** - Only add what's needed

## Testing [#testing]

Test your CLI commands:

```typescript
import { describe, it, expect } from "vitest";
import { Cerebro } from "@visulima/cerebro";

describe("CLI", () => {
    it("should execute command", async () => {
        const cli = new Cerebro("test-cli", {
            argv: ["hello", "World"],
        });

        const execute = vi.fn();
        cli.addCommand({
            name: "hello",
            execute,
        });

        await cli.run({ shouldExitProcess: false });

        expect(execute).toHaveBeenCalled();
    });
});
```

## Best Practices [#best-practices]

1. **Use command composition** - Break complex operations into smaller commands
2. **Handle errors gracefully** - Use error hooks and provide helpful messages
3. **Document commands** - Always include descriptions and examples
4. **Type everything** - Use TypeScript for better DX
5. **Test your CLI** - Write tests for your commands
6. **Follow CLI conventions** - Use standard option names and patterns


# Building a CLI Application (/docs/packages/cerebro/guides/building-cli)



# Building a CLI Application [#building-a-cli-application]

Learn how to build a production-ready CLI application with Cerebro from start to finish.

## Project Setup [#project-setup]

Create a new project:

```bash
mkdir my-cli && cd my-cli
npm init -y
npm install @visulima/cerebro @visulima/command-line-args @visulima/error
```

Create `src/cli.ts`:

```typescript
#!/usr/bin/env node
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-cli", {
    packageName: "my-cli",
    packageVersion: "1.0.0",
});

// Commands will go here

await cli.run();
```

Make it executable:

```bash
chmod +x src/cli.ts
```

## Add Commands [#add-commands]

Create command files in `src/commands/`:

```typescript
// src/commands/build.ts
import type { Command } from "@visulima/cerebro";

export const buildCommand: Command = {
    name: "build",
    description: "Build the project",
    options: [
        {
            name: "output",
            alias: "o",
            description: "Output directory",
            type: String,
            defaultValue: "./dist",
        },
        {
            name: "production",
            alias: "p",
            description: "Production build",
            type: Boolean,
        },
    ],
    execute: async ({ options, logger }) => {
        logger.log(`Building project...`);
        logger.log(`Output: ${options.output}`);
        logger.log(`Mode: ${options.production ? "production" : "development"}`);

        // Build logic here
        await performBuild(options);

        logger.log("Build complete!");
    },
};

async function performBuild(options: any) {
    // Your build logic
}
```

Register commands:

```typescript
// src/cli.ts
import { buildCommand } from "./commands/build";
import { deployCommand } from "./commands/deploy";

cli.addCommand(buildCommand);
cli.addCommand(deployCommand);
```

## Add Plugins [#add-plugins]

Install and use plugins:

```bash
npm install @visulima/fs @visulima/path
```

```typescript
// src/cli.ts
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

cli.use(errorHandlerPlugin({ exitOnError: true }));
cli.use(
    updateNotifierPlugin({
        packageName: "my-cli",
        packageVersion: "1.0.0",
        checkInterval: 86400000, // 24 hours
    }),
);
```

## Configuration [#configuration]

Create a configuration system:

```typescript
// src/config.ts
import { resolve } from "path";
import { readFileSync, existsSync } from "fs";

export interface Config {
    output: string;
    minify: boolean;
    sourcemap: boolean;
}

export function loadConfig(cwd: string): Config {
    const configPath = resolve(cwd, "my-cli.config.json");

    if (existsSync(configPath)) {
        const content = readFileSync(configPath, "utf-8");
        return JSON.parse(content);
    }

    return {
        output: "./dist",
        minify: false,
        sourcemap: true,
    };
}

// Use in commands
cli.addCommand({
    name: "build",
    execute: async ({ cwd, logger }) => {
        const config = loadConfig(cwd);
        logger.log(`Config: ${JSON.stringify(config, null, 2)}`);
    },
});
```

## Package for Distribution [#package-for-distribution]

Update `package.json`:

```json
{
    "name": "my-cli",
    "version": "1.0.0",
    "type": "module",
    "bin": {
        "my-cli": "./dist/cli.js"
    },
    "files": ["dist"],
    "scripts": {
        "build": "tsc",
        "prepublishOnly": "npm run build"
    },
    "dependencies": {
        "@visulima/cerebro": "^1.0.0"
    }
}
```

Build and test:

```bash
npm run build
node dist/cli.js --help
```

## Link for Local Testing [#link-for-local-testing]

Test your CLI locally:

```bash
npm link
my-cli --help
```

## Publish to npm [#publish-to-npm]

```bash
npm login
npm publish
```

Users can install and use:

```bash
npm install -g my-cli
my-cli build --production
```

## Complete Example [#complete-example]

Here's a complete production CLI:

```typescript
#!/usr/bin/env node
import { createCerebro } from "@visulima/cerebro";
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

const cli = createCerebro("project-cli", {
    packageName: "@company/project-cli",
    packageVersion: "2.1.0",
});

// Use plugins
cli.use(errorHandlerPlugin({ exitOnError: true }));

// Build command
cli.addCommand({
    name: "build",
    description: "Build the project",
    options: [
        {
            name: "output",
            alias: "o",
            type: String,
            defaultValue: "./dist",
            description: "Output directory",
        },
        {
            name: "production",
            alias: "p",
            type: Boolean,
            description: "Production mode",
        },
    ],
    execute: async ({ options, logger }) => {
        logger.log("Building...");
        // Build logic
        logger.log("Done!");
    },
});

// Deploy command with nested commands
cli.addCommand({
    name: "deploy",
    description: "Deploy application",
    commands: [
        {
            name: "staging",
            description: "Deploy to staging",
            execute: async ({ logger }) => {
                logger.log("Deploying to staging...");
            },
        },
        {
            name: "production",
            description: "Deploy to production",
            options: [
                {
                    name: "confirm",
                    type: Boolean,
                    required: true,
                    description: "Confirm production deployment",
                },
            ],
            execute: async ({ options, logger }) => {
                if (options.confirm) {
                    logger.log("Deploying to production...");
                }
            },
        },
    ],
});

await cli.run();
```


# Commands (/docs/packages/cerebro/guides/commands)



# Commands [#commands]

Commands are the core building blocks of your CLI. They define what actions users can perform.

## Basic Command [#basic-command]

A command requires at minimum a `name` and an `execute` function:

```typescript
cli.addCommand({
    name: "hello",
    execute: ({ logger }) => {
        logger.info("Hello, world!");
    },
});
```

## Command Properties [#command-properties]

### Name [#name]

The command name is used to invoke the command:

```typescript
cli.addCommand({
    name: "build", // Command invoked as: cli build
    execute: () => {},
});
```

### Description [#description]

A short description displayed in help output:

```typescript
cli.addCommand({
    name: "build",
    description: "Build the project for production",
    execute: () => {},
});
```

### Aliases [#aliases]

Provide alternative names for your command:

```typescript
cli.addCommand({
    name: "build",
    alias: "b", // Can use: cli b
    // or multiple aliases:
    // alias: ["b", "compile"],
    execute: () => {},
});
```

### Hidden Commands [#hidden-commands]

Hide commands from help output but still allow execution:

```typescript
cli.addCommand({
    name: "internal",
    hidden: true, // Won't appear in help
    execute: () => {},
});
```

### Grouped Commands [#grouped-commands]

Organize commands into groups for better help organization:

```typescript
cli.addCommand({
    name: "build",
    group: "Build", // Groups commands in help output
    execute: () => {},
});

cli.addCommand({
    name: "test",
    group: "Build",
    execute: () => {},
});
```

### Examples [#examples]

Provide usage examples for your command:

```typescript
cli.addCommand({
    name: "deploy",
    examples: ["deploy --env production", "deploy --env staging --dry-run"],
    execute: () => {},
});
```

## Command Execution [#command-execution]

The `execute` function receives a `toolbox` object with all available resources:

```typescript
cli.addCommand({
    name: "example",
    execute: ({
        argument, // Positional arguments
        options, // Parsed options
        logger, // Logger instance
        runtime, // CLI runtime (for calling other commands)
        command, // Command definition
        commandName, // Command name
        argv, // Original argv
    }) => {
        // Your command logic
    },
});
```

### Async Commands [#async-commands]

Commands can be async:

```typescript
cli.addCommand({
    name: "fetch",
    execute: async ({ logger }) => {
        const data = await fetch("https://api.example.com/data");
        logger.info("Data fetched!");
    },
});
```

### Lazy-Loaded Commands [#lazy-loaded-commands]

Use `loader` instead of `execute` to defer importing the handler module
until the command is actually invoked. Help, completion, and option
validation work from the metadata alone — they never trigger the loader.
See the [advanced guide](/docs/packages/cerebro/guides/advanced#lazy-command-loading) for the
full pattern.

```typescript
cli.addCommand({
    name: "build",
    description: "Build the project",
    options: [{ name: "output", type: String }],
    loader: () => import("./commands/build.handler"),
});

// commands/build.handler.ts
export default async ({ logger, options }) => {
    logger.info(`Building to ${options.output ?? "dist"}`);
};
```

A command must declare either `execute` or `loader`, but not both.

## Positional Arguments [#positional-arguments]

Define positional arguments using the `argument` property:

```typescript
cli.addCommand({
    name: "greet",
    argument: {
        name: "name",
        type: String,
        description: "Name to greet",
        defaultValue: "World",
    },
    execute: ({ argument }) => {
        const name = argument[0]; // Access first argument
        console.log(`Hello, ${name}!`);
    },
});
```

Usage:

```bash
cli greet Alice  # argument[0] = "Alice"
cli greet        # argument[0] = "World" (default)
```

### Multiple Arguments [#multiple-arguments]

Arguments accept multiple values by default:

```typescript
cli.addCommand({
    name: "copy",
    argument: {
        name: "files",
        type: String,
        description: "Files to copy",
    },
    execute: ({ argument }) => {
        // argument is an array of all provided values
        argument.forEach((file) => {
            console.log(`Copying ${file}...`);
        });
    },
});
```

Usage:

```bash
cli copy file1.txt file2.txt file3.txt
# argument = ["file1.txt", "file2.txt", "file3.txt"]
```

## Options [#options]

Commands can accept options (flags):

```typescript
cli.addCommand({
    name: "build",
    options: [
        {
            name: "production",
            type: Boolean,
            description: "Build for production",
        },
        {
            name: "output",
            alias: "o",
            type: String,
            description: "Output directory",
        },
    ],
    execute: ({ options }) => {
        if (options.production) {
            console.log("Building for production...");
        }
        console.log(`Output: ${options.output || "dist"}`);
    },
});
```

Usage:

```bash
cli build --production --output build
cli build -o build --production
```

See the [Options Guide](/docs/packages/cerebro/guides/options) for detailed option configuration.

## Nested Commands [#nested-commands]

Cerebro supports nested commands (subcommands) using the `commandPath` property. This allows you to create hierarchical command structures like `cli deploy staging` or `cli db migrate up`.

### Basic Nested Commands [#basic-nested-commands]

Create nested commands by specifying a `commandPath` array:

```typescript
// Parent command path: ["deploy"]
cli.addCommand({
    name: "staging",
    commandPath: ["deploy"],
    description: "Deploy to staging environment",
    execute: ({ logger }) => {
        logger.info("Deploying to staging...");
    },
});

cli.addCommand({
    name: "production",
    commandPath: ["deploy"],
    description: "Deploy to production environment",
    execute: ({ logger }) => {
        logger.info("Deploying to production...");
    },
});
```

Usage:

```bash
cli deploy staging
cli deploy production
```

### Multi-Level Nested Commands [#multi-level-nested-commands]

You can nest commands multiple levels deep:

```typescript
cli.addCommand({
    name: "up",
    commandPath: ["db", "migrate"],
    description: "Run database migrations",
    execute: ({ logger }) => {
        logger.info("Running migrations...");
    },
});

cli.addCommand({
    name: "down",
    commandPath: ["db", "migrate"],
    description: "Rollback database migrations",
    execute: ({ logger }) => {
        logger.info("Rolling back migrations...");
    },
});

cli.addCommand({
    name: "status",
    commandPath: ["db", "migrate"],
    description: "Show migration status",
    execute: ({ logger }) => {
        logger.info("Migration status...");
    },
});
```

Usage:

```bash
cli db migrate up
cli db migrate down
cli db migrate status
```

### Nested Commands with Options [#nested-commands-with-options]

Nested commands support all the same features as flat commands, including options:

```typescript
cli.addCommand({
    name: "production",
    commandPath: ["deploy"],
    description: "Deploy to production environment",
    options: [
        {
            name: "dry-run",
            type: Boolean,
            description: "Show what would be deployed without deploying",
        },
        {
            name: "tag",
            alias: "t",
            type: String,
            description: "Deployment tag",
        },
    ],
    execute: ({ options, logger }) => {
        if (options["dry-run"]) {
            logger.info("Dry run: Would deploy to production");
            return;
        }

        logger.info(`Deploying to production with tag: ${options.tag || "latest"}`);
    },
});
```

Usage:

```bash
cli deploy production --dry-run
cli deploy production --tag v1.0.0
cli deploy production -t v1.0.0 --dry-run
```

### Flat and Nested Commands Together [#flat-and-nested-commands-together]

You can mix flat and nested commands in the same CLI:

```typescript
// Flat command
cli.addCommand({
    name: "build",
    description: "Build the project",
    execute: ({ logger }) => {
        logger.info("Building...");
    },
});

// Nested command with same name (different path)
cli.addCommand({
    name: "build",
    commandPath: ["docker"],
    description: "Build Docker image",
    execute: ({ logger }) => {
        logger.info("Building Docker image...");
    },
});
```

Usage:

```bash
cli build              # Runs flat "build" command
cli docker build       # Runs nested "docker build" command
```

### Calling Nested Commands Programmatically [#calling-nested-commands-programmatically]

Use `runtime.runCommand()` with the full command path:

```typescript
cli.addCommand({
    name: "deploy-all",
    execute: async ({ runtime, logger }) => {
        logger.info("Deploying to all environments...");

        // Call nested commands programmatically
        await runtime.runCommand("deploy staging");
        await runtime.runCommand("deploy production");
    },
});
```

You can also call nested commands from within other nested commands:

```typescript
cli.addCommand({
    name: "staging",
    commandPath: ["deploy"],
    execute: async ({ runtime, logger }) => {
        logger.info("Preparing staging deployment...");
        await runtime.runCommand("build", { argv: ["--production"] });
        logger.info("Deploying to staging...");
    },
});
```

### Help Output [#help-output]

Nested commands are automatically displayed in help with their full path:

```bash
cli help
```

Output will show:

```
Available Commands
  deploy staging       Deploy to staging environment
  deploy production    Deploy to production environment
  db migrate up        Run database migrations
  db migrate down     Rollback database migrations
```

### Command Path Validation [#command-path-validation]

Command path segments are validated the same way as command names:

* Must start with a letter
* Can contain letters, numbers, hyphens, and underscores
* Cannot contain spaces or special characters

```typescript
// ✅ Valid
cli.addCommand({
    name: "staging",
    commandPath: ["deploy"], // Valid
    execute: () => {},
});

// ❌ Invalid - path segment must start with a letter
cli.addCommand({
    name: "test",
    commandPath: ["-invalid"], // Will throw error
    execute: () => {},
});
```

## Calling Other Commands [#calling-other-commands]

Commands can call other commands programmatically:

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        logger.info("Building...");
        await runtime.runCommand("build", {
            argv: ["--production"],
        });

        logger.info("Testing...");
        await runtime.runCommand("test");

        logger.info("Deploying...");
    },
});
```

The `runCommand` method allows you to:

* Pass arguments via `argv` array
* Merge additional options
* Get return values from commands
* Call nested commands using full path (e.g., `"deploy staging"`)

```typescript
const result = await runtime.runCommand("build", {
    argv: ["--production"],
    customOption: "value",
});

// Call nested commands
await runtime.runCommand("deploy staging");
await runtime.runCommand("db migrate up");
```

## Error Handling [#error-handling]

Commands can throw errors which are caught by Cerebro's error handling:

```typescript
cli.addCommand({
    name: "process",
    execute: ({ options }) => {
        if (!options.file) {
            throw new Error("File option is required");
        }
        // Process file...
    },
});
```

Errors are automatically handled and displayed to the user. See [Plugins Guide](/docs/packages/cerebro/guides/plugins) for custom error handling.

## Complete Example [#complete-example]

```typescript
cli.addCommand({
    name: "deploy",
    alias: "d",
    description: "Deploy the application",
    group: "Deployment",
    examples: ["deploy --env production", "deploy --env staging --dry-run"],
    argument: {
        name: "target",
        type: String,
        description: "Deployment target",
        defaultValue: "production",
    },
    options: [
        {
            name: "env",
            alias: "e",
            type: String,
            description: "Environment",
            required: true,
        },
        {
            name: "dry-run",
            type: Boolean,
            description: "Perform a dry run",
        },
    ],
    execute: async ({ argument, options, logger, runtime }) => {
        const target = argument[0];

        logger.info(`Deploying to ${target} environment...`);

        if (options.dryRun) {
            logger.info("Dry run mode - no changes will be made");
            return;
        }

        // Build first
        await runtime.runCommand("build", { argv: ["--production"] });

        // Deploy
        logger.info("Deployment complete!");
    },
});
```


# Comparison with Popular CLIs (/docs/packages/cerebro/guides/comparison)





When choosing a CLI framework, it's important to understand how Cerebro compares to other popular options. This guide provides a detailed comparison to help you make an informed decision.

## Quick Comparison Table [#quick-comparison-table]

| Feature                 | Cerebro             | Commander   | Yargs       | Oclif       | Meow   | CAC         | Cleye       |
| ----------------------- | ------------------- | ----------- | ----------- | ----------- | ------ | ----------- | ----------- |
| **TypeScript First**    | ✅ Excellent         | ⚠️ Partial  | ⚠️ Partial  | ✅ Good      | ❌ No   | ❌ No        | ✅ Excellent |
| **Plugin System**       | ✅ Built-in          | ❌ No        | ❌ No        | ✅ Built-in  | ❌ No   | ❌ No        | ❌ No        |
| **Performance**         | ✅ Fast              | ⚠️ Moderate | ⚠️ Moderate | ⚠️ Moderate | ✅ Fast | ✅ Very Fast | ✅ Fast      |
| **Zero Config**         | ✅ Yes               | ✅ Yes       | ✅ Yes       | ❌ No        | ✅ Yes  | ✅ Yes       | ✅ Yes       |
| **Shell Completions**   | ✅ Built-in (Plugin) | ⚠️ Plugin   | ⚠️ Plugin   | ✅ Built-in  | ❌ No   | ❌ No        | ❌ No        |
| **Command Composition** | ✅ Yes               | ❌ No        | ❌ No        | ✅ Yes       | ❌ No   | ❌ No        | ❌ No        |
| **Nested/Subcommands**  | ✅ Yes               | ✅ Yes       | ✅ Yes       | ✅ Yes       | ❌ No   | ✅ Yes       | ❌ No        |
| **Bundle Size**         | ✅ Small             | ⚠️ Medium   | ⚠️ Large    | ⚠️ Large    | ✅ Tiny | ✅ Tiny      | ✅ Small     |
| **Learning Curve**      | ✅ Easy              | ✅ Easy      | ⚠️ Moderate | ⚠️ Steep    | ✅ Easy | ✅ Easy      | ✅ Easy      |

## Detailed Comparisons [#detailed-comparisons]

### vs Commander.js [#vs-commanderjs]

**Commander.js** is the most popular Node.js CLI framework, known for its simplicity and maturity.

#### Advantages of Commander.js [#advantages-of-commanderjs]

* **Widespread adoption** - Used by thousands of projects
* **Large community** - Extensive documentation and examples
* **Simple API** - Easy to get started
* **Mature ecosystem** - Many plugins and extensions available

#### Advantages of Cerebro [#advantages-of-cerebro]

* **Better TypeScript support** - Superior type inference and autocomplete
* **Built-in plugin system** - Extend functionality without external dependencies
* **Command composition** - Call commands from within other commands
* **Nested commands** - Support for hierarchical command structures
* **Modern architecture** - Designed with TypeScript and async/await in mind
* **Better performance** - Optimized for fast startup times

#### When to Choose Commander.js [#when-to-choose-commanderjs]

* You need maximum ecosystem compatibility
* You're building a simple CLI without complex needs
* Your team is already familiar with Commander.js

#### When to Choose Cerebro [#when-to-choose-cerebro]

* You want excellent TypeScript support out of the box
* You need plugin extensibility
* You want command composition capabilities
* You need nested subcommands
* Performance is important for your use case

**Example Comparison:**

```typescript
// Commander.js
import { Command } from "commander";

const program = new Command();
program.name("my-app").version("1.0.0");

program
    .command("run")
    .option("-d, --debug", "output extra debugging")
    .action((options) => {
        if (options.debug) console.log("Debug mode");
    });

program.parse();
```

```typescript
// Cerebro
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app", {
    packageVersion: "1.0.0",
});

cli.addCommand({
    name: "run",
    options: [{ name: "debug", alias: "d", type: Boolean }],
    execute: ({ options, logger }) => {
        if (options.debug) logger.debug("Debug mode");
    },
});

await cli.run();
```

**Nested Commands Example:**

```typescript
// Commander.js - Nested commands
program
    .command("deploy")
    .command("staging")
    .action(() => {
        console.log("Deploying to staging...");
    });

program
    .command("deploy")
    .command("production")
    .action(() => {
        console.log("Deploying to production...");
    });
```

```typescript
// Cerebro - Nested commands
cli.addCommand({
    name: "staging",
    commandPath: ["deploy"],
    description: "Deploy to staging environment",
    execute: ({ logger }) => {
        logger.info("Deploying to staging...");
    },
});

cli.addCommand({
    name: "production",
    commandPath: ["deploy"],
    description: "Deploy to production environment",
    execute: ({ logger }) => {
        logger.info("Deploying to production...");
    },
});

// Usage: cli deploy staging
// Usage: cli deploy production
```

### vs Yargs [#vs-yargs]

**Yargs** is a powerful argument parser with extensive features and a rich ecosystem.

#### Advantages of Yargs [#advantages-of-yargs]

* **Rich feature set** - Extensive argument parsing capabilities
* **Middleware support** - Powerful middleware system
* **Positional arguments** - Excellent support for complex argument patterns
* **Validation** - Built-in validation and coercion

#### Advantages of Cerebro [#advantages-of-cerebro-1]

* **Simpler API** - More intuitive and easier to learn
* **TypeScript-first** - Better type safety and inference
* **Plugin architecture** - Built-in plugin system with lifecycle hooks
* **Performance** - Faster startup and execution
* **Command composition** - Built-in support for calling commands programmatically

#### When to Choose Yargs [#when-to-choose-yargs]

* You need complex argument parsing patterns
* You require extensive middleware capabilities
* Your CLI has very complex positional argument requirements

#### When to Choose Cerebro [#when-to-choose-cerebro-1]

* You want a cleaner, more modern API
* TypeScript support is important
* You need plugin extensibility
* You prefer better performance

**Example Comparison:**

```typescript
// Yargs
import yargs from "yargs";
import { hideBin } from "yargs/helpers";

const argv = yargs(hideBin(process.argv))
    .option("input", {
        alias: "i",
        type: "string",
        description: "Input file",
        demandOption: true,
    })
    .option("output", {
        alias: "o",
        type: "string",
        description: "Output file",
    })
    .parse();
```

```typescript
// Cerebro
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app");

cli.addCommand({
    name: "process",
    options: [
        {
            name: "input",
            alias: "i",
            type: String,
            description: "Input file",
            required: true,
        },
        {
            name: "output",
            alias: "o",
            type: String,
            description: "Output file",
        },
    ],
    execute: ({ options }) => {
        // Process files
    },
});

await cli.run();
```

### vs Oclif [#vs-oclif]

**Oclif** is Salesforce's enterprise-grade CLI framework with extensive tooling and features.

#### Advantages of Oclif [#advantages-of-oclif]

* **Enterprise features** - Designed for large-scale CLI applications
* **Built-in generators** - Scaffolding tools for commands and plugins
* **Multi-command architecture** - Excellent for complex CLIs
* **Plugin ecosystem** - Rich plugin marketplace
* **Testing utilities** - Built-in testing helpers

#### Advantages of Cerebro [#advantages-of-cerebro-2]

* **Lighter weight** - Smaller bundle size and faster startup
* **Simpler setup** - Zero configuration approach
* **Better TypeScript** - Superior type inference
* **Modern API** - Cleaner, more intuitive interface
* **No generators needed** - Write commands directly without scaffolding

#### When to Choose Oclif [#when-to-choose-oclif]

* Building enterprise-grade CLIs with many commands
* You need extensive scaffolding and generators
* You want access to a plugin marketplace
* Building CLIs that integrate with Salesforce

#### When to Choose Cerebro [#when-to-choose-cerebro-2]

* You want a lighter, faster framework
* You prefer simplicity over enterprise features
* TypeScript support is a priority
* You want zero configuration

**Example Comparison:**

```typescript
// Oclif
import { Command, Flags } from "@oclif/core";

export class Build extends Command {
    static flags = {
        production: Flags.boolean({
            char: "p",
            description: "Production build",
        }),
    };

    async run() {
        const { flags } = await this.parse(Build);
        // Build logic
    }
}
```

```typescript
// Cerebro
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app");

cli.addCommand({
    name: "build",
    options: [
        {
            name: "production",
            alias: "p",
            type: Boolean,
            description: "Production build",
        },
    ],
    execute: ({ options }) => {
        // Build logic
    },
});

await cli.run();
```

### vs Meow [#vs-meow]

**Meow** is a minimal CLI helper built by Sindre Sorhus, focused on simplicity and zero dependencies.

#### Advantages of Meow [#advantages-of-meow]

* **Ultra-lightweight** - Zero dependencies, tiny bundle size
* **Simple API** - Minimal and straightforward
* **Fast** - Extremely fast startup
* **No bloat** - Only essential features

#### Advantages of Cerebro [#advantages-of-cerebro-3]

* **More features** - Built-in plugin system, command composition
* **Better TypeScript** - Full type safety and inference
* **Help generation** - Automatic help text generation
* **Shell completions** - Built-in completion support
* **Command structure** - Better organization for multiple commands

#### When to Choose Meow [#when-to-choose-meow]

* Building extremely simple CLIs
* Bundle size is critical
* You only need basic argument parsing
* Zero dependencies is a hard requirement

#### When to Choose Cerebro [#when-to-choose-cerebro-3]

* You need more than basic argument parsing
* You want plugin extensibility
* TypeScript support is important
* You need help generation and completions

**Example Comparison:**

```typescript
// Meow
import meow from "meow";

const cli = meow(
    `
  Usage
    $ my-app <input>

  Options
    --flag, -f  Some flag

  Examples
    $ my-app unicorn
`,
    {
        flags: {
            flag: {
                type: "boolean",
                alias: "f",
            },
        },
    },
);
```

```typescript
// Cerebro
import { Cerebro } from "@visulima/cerebro";

const cli = new Cerebro("my-app");

cli.addCommand({
    name: "run",
    argument: {
        name: "input",
        type: String,
    },
    options: [
        {
            name: "flag",
            alias: "f",
            type: Boolean,
        },
    ],
    execute: ({ argument, options }) => {
        // Command logic
    },
});

await cli.run();
```

### vs CAC [#vs-cac]

**CAC** (Command And Conquer) is a super lightweight CLI framework with zero dependencies.

#### Advantages of CAC [#advantages-of-cac]

* **Zero dependencies** - Completely dependency-free
* **Very fast** - Extremely lightweight and fast
* **Simple** - Minimal API surface
* **Small bundle** - Tiny footprint

#### Advantages of Cerebro [#advantages-of-cerebro-4]

* **TypeScript support** - Full type safety
* **Plugin system** - Built-in extensibility
* **More features** - Help generation, completions, command composition
* **Better DX** - Superior developer experience
* **Error handling** - Built-in error handling system

#### When to Choose CAC [#when-to-choose-cac]

* You need zero dependencies
* Minimal bundle size is critical
* You only need basic command parsing

#### When to Choose Cerebro [#when-to-choose-cerebro-4]

* You want TypeScript support
* You need plugin capabilities
* Better developer experience matters

### vs Cleye [#vs-cleye]

**Cleye** is a modern TypeScript-first CLI library with strongly typed parameters.

#### Advantages of Cleye [#advantages-of-cleye]

* **TypeScript-first** - Excellent type safety
* **Strong typing** - Strongly typed parameters
* **Clean API** - Modern and intuitive
* **Small bundle** - Lightweight

#### Advantages of Cerebro [#advantages-of-cerebro-5]

* **Plugin system** - Built-in plugin architecture
* **Command composition** - Call commands programmatically
* **More features** - Help generation, completions, toolbox
* **Lifecycle hooks** - Plugin lifecycle management
* **Better organization** - More structured for complex CLIs

#### When to Choose Cleye [#when-to-choose-cleye]

* You want a simple TypeScript-first CLI
* You prefer minimal dependencies
* Basic command parsing is sufficient

#### When to Choose Cerebro [#when-to-choose-cerebro-5]

* You need plugin extensibility
* You want command composition
* You need more advanced features

## Performance Comparison [#performance-comparison]

Cerebro is optimized for performance, especially important for CLI tools that start fresh with every invocation:

* **Fast startup** - Minimal initialization overhead
* **Efficient parsing** - Optimized argument parsing
* **Small memory footprint** - Lightweight runtime
* **Quick command execution** - Optimized command dispatching

For detailed performance benchmarks, see the [benchmark results](https://github.com/visulima/visulima/tree/main/packages/cerebro/__bench__).

## Migration Guide [#migration-guide]

If you're considering migrating from another CLI framework, check out our [Migration Guide](https://github.com/visulima/visulima/blob/main/packages/cerebro/MIGRATION-GUIDE) for detailed examples and best practices.

## Features Comparison [#features-comparison]

### What Cerebro Has [#what-cerebro-has]

* ✅ **Command composition** - Call commands programmatically
* ✅ **Nested/Subcommands** - Support for `cli deploy staging` style commands using `commandPath`
* ✅ **Plugin system** - Extensible architecture with lifecycle hooks
* ✅ **TypeScript-first** - Excellent type safety and inference
* ✅ **Shell completions** - Built-in completion support (via plugin)
* ✅ **Help generation** - Automatic help text generation
* ✅ **Error handling** - Built-in error types and handling
* ✅ **Command grouping** - Organize commands in help output
* ✅ **Option validation** - Required options, conflicts, implied options
* ✅ **Negatable options** - `--no-` prefix support
* ✅ **Command aliases** - Multiple aliases per command
* ✅ **Global options** - Built-in help, version, verbose, quiet, debug
* ✅ **Default command** - Set a default command when none provided

### What Cerebro Doesn't Have (Yet) [#what-cerebro-doesnt-have-yet]

Cerebro focuses on simplicity and performance, which means some advanced features available in other frameworks are intentionally omitted or can be added via plugins:

* ⚠️ **Multiple Named Arguments** - Single positional argument support only (can accept multiple values as array)
* ⚠️ **Environment Variable Mapping** - No automatic `MYAPP_PORT` → `--port` mapping (can be added via plugin)
* ⚠️ **Config File Support** - No built-in JSON/YAML/TOML config file reading (can be added via plugin)
* ⚠️ **Middleware System** - No Yargs-style middleware for option preprocessing (plugins provide lifecycle hooks instead)
* ⚠️ **Custom Option Coercion** - Basic type conversion only, no custom coercion functions
* ⚠️ **Command Generators** - No scaffolding tools like Oclif (by design - prefer direct code)

<Callout type="info">
  **Note:** Many missing features can be implemented via plugins. The plugin system is designed to be the extension mechanism for additional functionality.
</Callout>

## Summary [#summary]

**Choose Cerebro if:**

* ✅ You want excellent TypeScript support
* ✅ You need plugin extensibility
* ✅ Performance matters for your CLI
* ✅ You want command composition
* ✅ You need nested subcommands
* ✅ You prefer modern, clean APIs
* ✅ You need built-in shell completions
* ✅ You want a simple, focused framework

**Consider alternatives if:**

* ❌ You need maximum ecosystem compatibility (→ Commander.js)
* ❌ You require complex argument parsing patterns (→ Yargs)
* ❌ You need environment variable/config file integration out of the box (→ Yargs)
* ❌ You need zero dependencies (→ Meow, CAC)
* ❌ You want minimal features (→ Cleye)
* ❌ You need command generators/scaffolding (→ Oclif)

<Callout type="info">
  **Note:** This comparison is based on features and typical use cases. Your specific requirements may vary. We recommend trying Cerebro and comparing it
  directly with your use case. Missing features can often be added via plugins or custom code.
</Callout>


# Options (/docs/packages/cerebro/guides/options)



# Options & Arguments [#options--arguments]

Options (flags) and arguments are how users provide input to your commands.

## Options [#options]

Options are named parameters passed with `--option` or `-o` syntax.

### Basic Options [#basic-options]

```typescript
cli.addCommand({
    name: "build",
    options: [
        {
            name: "production",
            type: Boolean,
            description: "Build for production",
        },
    ],
    execute: ({ options }) => {
        console.log(options.production); // true or false
    },
});
```

Usage:

```bash
cli build --production  # options.production = true
cli build              # options.production = false
```

### Option Types [#option-types]

#### Boolean Options [#boolean-options]

```typescript
{
  name: "verbose",
  type: Boolean,
  description: "Enable verbose output"
}
```

#### String Options [#string-options]

```typescript
{
  name: "output",
  type: String,
  description: "Output directory"
}
```

Usage: `cli build --output dist`

#### Number Options [#number-options]

```typescript
{
  name: "port",
  type: Number,
  description: "Server port"
}
```

Usage: `cli serve --port 3000`

#### Array Options [#array-options]

Options can accept multiple values:

```typescript
{
  name: "files",
  type: String, // Will be an array
  multiple: true,
  description: "Files to process"
}
```

Usage: `cli process --files file1.txt --files file2.txt`

### Aliases [#aliases]

Provide short aliases for options:

```typescript
{
  name: "output",
  alias: "o",
  type: String,
  description: "Output directory"
}
```

Usage:

```bash
cli build --output dist
cli build -o dist  # Same as above
```

### Default Values [#default-values]

Set default values for options:

```typescript
{
  name: "port",
  type: Number,
  defaultValue: 3000,
  description: "Server port"
}
```

```typescript
execute: ({ options }) => {
    console.log(options.port); // 3000 if not provided
};
```

### Required Options [#required-options]

Make options mandatory:

```typescript
{
  name: "config",
  type: String,
  required: true,
  description: "Configuration file path"
}
```

If not provided, Cerebro will throw an error with a helpful message.

### Negatable Options [#negatable-options]

Boolean options can be negated with `--no-` prefix:

```typescript
{
  name: "color",
  type: Boolean,
  defaultValue: true,
  description: "Enable colored output"
}
```

Usage:

```bash
cli build --color        # options.color = true
cli build --no-color     # options.color = false
cli build                # options.color = true (default)
```

### Conflicting Options [#conflicting-options]

Prevent certain options from being used together:

```typescript
cli.addCommand({
    name: "serve",
    options: [
        {
            name: "http",
            type: Boolean,
            conflicts: "https",
            description: "Use HTTP",
        },
        {
            name: "https",
            type: Boolean,
            conflicts: "http",
            description: "Use HTTPS",
        },
    ],
    execute: () => {},
});
```

Using both will throw an error:

```bash
cli serve --http --https  # Error: Options "http" and "https" cannot be used together
```

### Implied Options [#implied-options]

Automatically set other options when one is used:

```typescript
cli.addCommand({
    name: "build",
    options: [
        {
            name: "production",
            type: Boolean,
            implies: { minify: true, sourcemap: false },
            description: "Build for production",
        },
        {
            name: "minify",
            type: Boolean,
            description: "Minify output",
        },
        {
            name: "sourcemap",
            type: Boolean,
            description: "Generate source maps",
        },
    ],
    execute: ({ options }) => {
        // If --production is used, minify=true and sourcemap=false automatically
    },
});
```

### Boolean Options [#boolean-options-1]

Boolean options are simple flags that are either present (true) or absent (false):

```typescript
{
  name: "watch",
  type: Boolean,
  description: "Watch for changes"
}
```

Usage:

```bash
cli build --watch  # options.watch = true
cli build          # options.watch = false
```

Note: If you need an option that can accept values, use a `String` type instead:

```typescript
{
  name: "watch",
  type: String,
  description: "Watch mode (e.g., 'port' or 'file')"
}
```

### Hidden Options [#hidden-options]

Hide options from help output:

```typescript
{
  name: "debug",
  type: Boolean,
  hidden: true, // Won't appear in help
  description: "Enable debug mode"
}
```

### Type Labels [#type-labels]

Customize the type label shown in help:

```typescript
{
  name: "port",
  type: Number,
  typeLabel: "<port>", // Instead of <number>
  description: "Server port"
}
```

## Positional Arguments [#positional-arguments]

Positional arguments are provided without option names:

```typescript
cli.addCommand({
    name: "copy",
    argument: {
        name: "source",
        type: String,
        description: "Source file",
    },
    execute: ({ argument }) => {
        const source = argument[0];
        console.log(`Copying ${source}...`);
    },
});
```

Usage: `cli copy file.txt`

### Multiple Arguments [#multiple-arguments]

Arguments accept multiple values:

```typescript
cli.addCommand({
    name: "copy",
    argument: {
        name: "files",
        type: String,
        description: "Files to copy",
    },
    execute: ({ argument }) => {
        // argument is an array
        argument.forEach((file) => {
            console.log(`Copying ${file}...`);
        });
    },
});
```

Usage: `cli copy file1.txt file2.txt file3.txt`

### Argument Default Values [#argument-default-values]

```typescript
argument: {
  name: "name",
  type: String,
  defaultValue: "World",
  description: "Name to greet"
}
```

### Argument Types [#argument-types]

Arguments support the same types as options:

* `String` - Text values
* `Number` - Numeric values
* `Boolean` - Boolean values (rare for arguments)

## Accessing Options and Arguments [#accessing-options-and-arguments]

In your command's `execute` function:

```typescript
execute: ({ options, argument }) => {
    // Options
    const isProduction = options.production;
    const outputDir = options.output || "dist";

    // Arguments
    const fileName = argument[0];
    const allFiles = argument; // Array of all arguments
};
```

## Complete Example [#complete-example]

```typescript
cli.addCommand({
    name: "deploy",
    argument: {
        name: "target",
        type: String,
        defaultValue: "production",
        description: "Deployment target",
    },
    options: [
        {
            name: "env",
            alias: "e",
            type: String,
            required: true,
            description: "Environment name",
        },
        {
            name: "force",
            alias: "f",
            type: Boolean,
            defaultValue: false,
            description: "Force deployment",
        },
        {
            name: "dry-run",
            type: Boolean,
            description: "Perform a dry run",
        },
        {
            name: "services",
            type: String,
            multiple: true,
            description: "Services to deploy",
        },
    ],
    execute: ({ argument, options }) => {
        const target = argument[0];
        const env = options.env;
        const force = options.force;
        const services = options.services || [];

        console.log(`Deploying to ${target} (${env})`);
        if (force) {
            console.log("Force mode enabled");
        }
        if (services.length > 0) {
            console.log(`Services: ${services.join(", ")}`);
        }
    },
});
```

Usage examples:

```bash
# Basic usage
cli deploy staging --env production

# With multiple services
cli deploy --env production --services api --services worker

# Force deployment
cli deploy --env production --force

# Dry run
cli deploy --env production --dry-run
```

## Environment Variables [#environment-variables]

Environment variables provide a way to configure commands without passing values on the command line. They're useful for:

* Configuration that doesn't change frequently
* Sensitive values that shouldn't appear in command history
* CI/CD pipelines and automation
* Default settings that can be overridden by options

### Defining Environment Variables [#defining-environment-variables]

Add an `env` array to your command definition, similar to `options`:

```typescript
cli.addCommand({
    name: "build",
    env: [
        {
            name: "API_KEY",
            type: String,
            description: "API key for authentication",
        },
        {
            name: "TIMEOUT",
            type: Number,
            defaultValue: 5000,
            description: "Request timeout in milliseconds",
        },
        {
            name: "VERBOSE",
            type: Boolean,
            defaultValue: false,
            description: "Enable verbose logging",
        },
    ],
    execute: ({ env }) => {
        const apiKey = env.apiKey; // camelCase: API_KEY → apiKey
        const timeout = env.timeout; // 5000 if not set
        const verbose = env.verbose; // false if not set
    },
});
```

### Environment Variable Types [#environment-variable-types]

Environment variables support the same types as options:

#### String Environment Variables [#string-environment-variables]

```typescript
{
    name: "API_URL",
    type: String,
    description: "API endpoint URL"
}
```

Usage: `API_URL=https://api.example.com cli build`

#### Number Environment Variables [#number-environment-variables]

```typescript
{
    name: "PORT",
    type: Number,
    defaultValue: 3000,
    description: "Server port"
}
```

Usage: `PORT=8080 cli serve`

The value is parsed as an integer. Invalid values will use the default if provided.

#### Boolean Environment Variables [#boolean-environment-variables]

```typescript
{
    name: "ENABLE_CACHE",
    type: Boolean,
    defaultValue: false,
    description: "Enable caching"
}
```

Boolean values are case-insensitive and accept:

* `true`, `1`, `yes`, `on` → `true`
* `false`, `0`, `no`, `off`, or any other value → `false`

Usage:

```bash
ENABLE_CACHE=true cli build
ENABLE_CACHE=1 cli build
ENABLE_CACHE=yes cli build
```

### Default Values [#default-values-1]

Set default values that are used when the environment variable is not set:

```typescript
{
    name: "LOG_LEVEL",
    type: String,
    defaultValue: "info",
    description: "Logging level"
}
```

```typescript
execute: ({ env }) => {
    // env.logLevel will be "info" if LOG_LEVEL is not set
    console.log(env.logLevel);
};
```

### Hidden Environment Variables [#hidden-environment-variables]

Hide environment variables from help output:

```typescript
{
    name: "SECRET_KEY",
    type: String,
    hidden: true, // Won't appear in help
    description: "Secret key for encryption"
}
```

### CamelCase Conversion [#camelcase-conversion]

Environment variable names are automatically converted to camelCase:

* `API_KEY` → `env.apiKey`
* `LOG_LEVEL` → `env.logLevel`
* `ENABLE_SSL` → `env.enableSsl`

### Accessing Environment Variables [#accessing-environment-variables]

Access environment variables through the `env` property in your command's `execute` function:

```typescript
cli.addCommand({
    name: "deploy",
    env: [
        {
            name: "DEPLOY_ENV",
            type: String,
            defaultValue: "staging",
            description: "Deployment environment",
        },
        {
            name: "FORCE_DEPLOY",
            type: Boolean,
            defaultValue: false,
            description: "Force deployment without confirmation",
        },
    ],
    execute: ({ env, options }) => {
        const deployEnv = env.deployEnv; // "staging" if not set
        const forceDeploy = env.forceDeploy; // false if not set

        // Can combine with options
        const finalEnv = options.env || env.deployEnv;
    },
});
```

### Complete Example [#complete-example-1]

```typescript
cli.addCommand({
    name: "build",
    env: [
        {
            name: "NODE_ENV",
            type: String,
            defaultValue: "development",
            description: "Node.js environment",
        },
        {
            name: "BUILD_TIMEOUT",
            type: Number,
            defaultValue: 30000,
            description: "Build timeout in milliseconds",
        },
        {
            name: "ENABLE_SOURCEMAPS",
            type: Boolean,
            defaultValue: true,
            description: "Generate source maps",
        },
    ],
    options: [
        {
            name: "output",
            type: String,
            description: "Output directory",
        },
    ],
    execute: ({ env, options }) => {
        const nodeEnv = env.nodeEnv; // "development" or value from NODE_ENV
        const timeout = env.buildTimeout; // 30000 or value from BUILD_TIMEOUT
        const sourcemaps = env.enableSourcemaps; // true or value from ENABLE_SOURCEMAPS
        const output = options.output || "dist";

        console.log(`Building for ${nodeEnv} with timeout ${timeout}ms`);
        if (sourcemaps) {
            console.log("Source maps enabled");
        }
    },
});
```

Usage examples:

```bash
# Using defaults
cli build

# Override with environment variables
NODE_ENV=production BUILD_TIMEOUT=60000 cli build

# Combine with options
ENABLE_SOURCEMAPS=false cli build --output build

# Boolean values
ENABLE_SOURCEMAPS=1 cli build  # true
ENABLE_SOURCEMAPS=0 cli build  # false
```

### Environment Variables in Help [#environment-variables-in-help]

Environment variables are automatically displayed in the help output:

```bash
cli help build
```

Output includes an "Environment Variables" section showing:

* Variable name
* Description
* Default value (if set)

Hidden environment variables are excluded from help output.

## Global Options [#global-options]

Cerebro provides built-in global options available to all commands:

* `--help, -h` - Show help
* `--version, -V` - Show version
* `--verbose, -v` - Verbose output
* `--debug` - Debug output
* `--quiet, -q` - Quiet output
* `--no-color` - Disable colored output
* `--color` - Force colored output

These don't need to be defined in your commands.

### Custom Global Options [#custom-global-options]

You can add your own global options using `addGlobalOption()`. These are available
to every command and appear in the help output alongside the built-in ones:

```typescript
const cli = new Cerebro("my-app");

cli.addGlobalOption({
    name: "cwd",
    type: String,
    description: "Override working directory",
});

cli.addGlobalOption({
    name: "config",
    alias: "C",
    type: String,
    description: "Path to config file",
});
```

Custom global options work exactly like command options — they support `type`, `alias`,
`description`, `defaultValue`, and all other `OptionDefinition` fields. They are parsed
for every command and accessible via `toolbox.options`:

```typescript
cli.addCommand({
    name: "build",
    execute: ({ options }) => {
        const cwd = options.cwd as string | undefined;
        const config = options.config as string | undefined;
        // ...
    },
});
```

> **Note:** You cannot override built-in global options. Attempting to add an option
> with the same name or alias as a built-in will throw an error.

## Global Environment Variables [#global-environment-variables]

Cerebro also provides built-in global environment variables:

* `CEREBRO_OUTPUT_LEVEL` - Controls verbosity level (16=quiet, 32=normal, 64=verbose, 128=debug)
* `CEREBRO_MIN_NODE_VERSION` - Overrides minimum Node.js version check
* `NO_UPDATE_NOTIFIER` - Disables update notifier check
* `NODE_ENV` - Standard Node.js environment variable
* `DEBUG` - Enables debug output (same as --debug flag)

These are available to all commands and appear in the general help output.


# Plugins (/docs/packages/cerebro/guides/plugins)



# Plugins [#plugins]

Plugins extend Cerebro's functionality by hooking into the command lifecycle and extending the toolbox.

## What are Plugins? [#what-are-plugins]

Plugins allow you to:

* Add functionality to the toolbox (like file system operations, HTTP clients, etc.)
* Hook into command lifecycle (before/after execution)
* Handle errors globally
* Share code across commands

## Basic Plugin [#basic-plugin]

A plugin requires a `name` and can have lifecycle hooks:

```typescript
cli.addPlugin({
    name: "my-plugin",
    description: "My custom plugin",
    execute: (toolbox) => {
        // Extend toolbox
        toolbox.myFeature = () => {
            console.log("My feature!");
        };
    },
});
```

## Plugin Lifecycle [#plugin-lifecycle]

Plugins have access to several lifecycle hooks:

### Init Hook [#init-hook]

Called once during plugin initialization, before any commands run:

```typescript
cli.addPlugin({
    name: "database",
    init: async ({ cli, cwd, logger }) => {
        // Initialize database connection
        logger.info("Database plugin initialized");
    },
});
```

### Execute Hook [#execute-hook]

Called during command execution to extend the toolbox:

```typescript
cli.addPlugin({
    name: "filesystem",
    execute: (toolbox) => {
        // Add file system utilities to toolbox
        toolbox.fs = {
            readFile: async (path: string) => {
                // Implementation
            },
            writeFile: async (path: string, content: string) => {
                // Implementation
            },
        };
    },
});
```

Then use in commands:

```typescript
cli.addCommand({
    name: "read",
    execute: async ({ fs }) => {
        const content = await fs.readFile("file.txt");
        console.log(content);
    },
});
```

### BeforeCommand Hook [#beforecommand-hook]

Called before each command executes:

```typescript
cli.addPlugin({
    name: "analytics",
    beforeCommand: async (toolbox) => {
        console.log(`Executing command: ${toolbox.commandName}`);
        // Track command usage
    },
});
```

### AfterCommand Hook [#aftercommand-hook]

Called after successful command execution:

```typescript
cli.addPlugin({
    name: "cleanup",
    afterCommand: async (toolbox, result) => {
        // Cleanup resources
        console.log("Command completed:", result);
    },
});
```

### OnError Hook [#onerror-hook]

Called when an error occurs:

```typescript
cli.addPlugin({
    name: "error-handler",
    onError: async (error, toolbox) => {
        // Custom error handling
        console.error(`Error in ${toolbox.commandName}:`, error.message);

        // Send to error tracking service
        await sendToErrorTracking(error, toolbox);
    },
});
```

## Plugin Dependencies [#plugin-dependencies]

Plugins can depend on other plugins:

```typescript
cli.addPlugin({
    name: "advanced-fs",
    dependencies: ["filesystem"], // Requires filesystem plugin
    execute: (toolbox) => {
        // Extend filesystem plugin
        toolbox.fs.copy = async (src, dest) => {
            // Implementation
        };
    },
});
```

Dependencies are loaded in the correct order automatically.

## Complete Plugin Example [#complete-plugin-example]

```typescript
cli.addPlugin({
    name: "http-client",
    version: "1.0.0",
    description: "HTTP client utilities",
    dependencies: ["logger"],

    init: async ({ logger }) => {
        logger.info("HTTP client plugin initialized");
    },

    execute: (toolbox) => {
        toolbox.http = {
            get: async (url: string) => {
                const response = await fetch(url);
                return response.json();
            },
            post: async (url: string, data: unknown) => {
                const response = await fetch(url, {
                    method: "POST",
                    body: JSON.stringify(data),
                });
                return response.json();
            },
        };
    },

    beforeCommand: async (toolbox) => {
        toolbox.logger.debug(`Preparing HTTP client for ${toolbox.commandName}`);
    },

    afterCommand: async (toolbox, result) => {
        toolbox.logger.debug(`Command ${toolbox.commandName} completed`);
    },

    onError: async (error, toolbox) => {
        toolbox.logger.error(`HTTP error in ${toolbox.commandName}:`, error);
    },
});
```

Usage in commands:

```typescript
cli.addCommand({
    name: "fetch",
    execute: async ({ http, logger }) => {
        const data = await http.get("https://api.example.com/data");
        logger.info("Data fetched:", data);
    },
});
```

## Built-in Plugins [#built-in-plugins]

Cerebro includes a built-in logger plugin that adds logging to the toolbox:

```typescript
execute: ({ logger }) => {
    logger.info("Info message");
    logger.error("Error message");
    logger.warn("Warning message");
    logger.debug("Debug message");
};
```

## TypeScript Support [#typescript-support]

Extend the toolbox type for type safety:

```typescript
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            myFeature: () => void;
            fs: {
                readFile: (path: string) => Promise<string>;
            };
        }
    }
}
```

Now TypeScript will provide autocomplete and type checking:

```typescript
execute: ({ myFeature, fs }) => {
    myFeature(); // TypeScript knows this exists
    const content = await fs.readFile("file.txt"); // TypeScript knows the signature
};
```

## Best Practices [#best-practices]

1. **Keep plugins focused** - Each plugin should have a single responsibility
2. **Use dependencies** - If your plugin extends another, declare it as a dependency
3. **Handle errors** - Use `onError` hook for error handling, not `execute`
4. **Initialize resources in `init`** - Set up connections, load configs, etc.
5. **Extend toolbox in `execute`** - Add utilities to toolbox here
6. **Document your plugin** - Always include description and version

## Plugin vs Command [#plugin-vs-command]

* **Plugins** - Extend functionality, add to toolbox, lifecycle hooks
* **Commands** - User-facing actions, invoked via CLI

Use plugins for reusable functionality, commands for user actions.


# Using Plugins (/docs/packages/cerebro/guides/using-plugins)



# Using Plugins [#using-plugins]

Learn how to use built-in and custom plugins to extend your CLI application.

## Installing Plugins [#installing-plugins]

Built-in plugins are included with Cerebro:

```typescript
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";
```

## Error Handler Plugin [#error-handler-plugin]

Handle errors gracefully with formatted output:

```typescript
import { createCerebro } from "@visulima/cerebro";
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

const cli = createCerebro("my-cli");

cli.use(
    errorHandlerPlugin({
        exitOnError: true, // Exit process on error (default: true)
        showStackTrace: false, // Show stack traces (default: false)
        logErrors: true, // Log errors to console (default: true)
    }),
);

cli.addCommand({
    name: "test",
    execute: async () => {
        throw new Error("Something went wrong!");
        // Error will be caught and formatted by plugin
    },
});

await cli.run();
```

Without plugin:

```
Error: Something went wrong!
  at execute (file:///cli.js:10:11)
  ...full stack trace...
```

With plugin:

```
❌ Error: Something went wrong!
```

## Runtime Version Check Plugin [#runtime-version-check-plugin]

Ensure users have the correct Node.js/Deno/Bun version:

```typescript
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";

cli.use(
    runtimeVersionCheckPlugin({
        requiredVersion: ">=18.0.0",
        message: "This CLI requires Node.js 18 or higher. Please upgrade.",
    }),
);
```

If user has Node.js 16:

```
❌ This CLI requires Node.js 18 or higher. Please upgrade.
   Current version: 16.14.0
   Required version: >=18.0.0
```

## Update Notifier Plugin [#update-notifier-plugin]

Notify users when a new version is available:

```typescript
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

cli.use(
    updateNotifierPlugin({
        packageName: "my-cli",
        packageVersion: "1.0.0",
        checkInterval: 86400000, // Check once per day (24 hours)
        updateMessage: "Update available: {latest} (current: {current})\nRun: npm install -g my-cli@latest",
    }),
);

await cli.run();
```

Output when update available:

```
╭───────────────────────────────────────╮
│                                        │
│   Update available: 2.0.0 (1.0.0)    │
│   Run: npm install -g my-cli@latest   │
│                                        │
╰───────────────────────────────────────╯

... command output ...
```

## Combining Multiple Plugins [#combining-multiple-plugins]

Use multiple plugins together:

```typescript
import { createCerebro } from "@visulima/cerebro";
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

const cli = createCerebro("my-cli", {
    packageName: "my-cli",
    packageVersion: "1.0.0",
});

// Register plugins in order
cli.use(runtimeVersionCheckPlugin({ requiredVersion: ">=18.0.0" }));
cli.use(errorHandlerPlugin({ exitOnError: true }));
cli.use(
    updateNotifierPlugin({
        packageName: "my-cli",
        packageVersion: "1.0.0",
    }),
);

// Add commands...
await cli.run();
```

## Creating Custom Plugins [#creating-custom-plugins]

Create your own plugins to extend functionality:

```typescript
import type { Plugin } from "@visulima/cerebro";

// Type declaration
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            analytics: {
                track: (event: string, data?: Record<string, any>) => void;
            };
        }
    }
}

// Plugin implementation
export const analyticsPlugin = (apiKey: string): Plugin => ({
    name: "analytics",
    version: "1.0.0",
    register: async ({ toolbox, logger }) => {
        logger.log("Initializing analytics");

        toolbox.analytics = {
            track: (event: string, data?: Record<string, any>) => {
                // Send analytics event
                fetch("https://analytics.example.com/track", {
                    method: "POST",
                    headers: {
                        "X-API-Key": apiKey,
                        "Content-Type": "application/json",
                    },
                    body: JSON.stringify({ event, data, timestamp: Date.now() }),
                }).catch((error) => {
                    logger.error(`Analytics error: ${error.message}`);
                });
            },
        };
    },
});

// Use plugin
cli.use(analyticsPlugin("your-api-key"));

// Track events in commands
cli.addCommand({
    name: "deploy",
    execute: async ({ analytics, logger }) => {
        analytics.track("deploy_started");

        // Deploy logic...

        analytics.track("deploy_completed", { duration: 1234 });
        logger.log("Deployed!");
    },
});
```

## Plugin Loading Order [#plugin-loading-order]

Plugins initialize in registration order:

```typescript
cli.use(configPlugin()); // 1st: Load configuration
cli.use(databasePlugin()); // 2nd: Connect to database (needs config)
cli.use(analyticsPlugin()); // 3rd: Initialize analytics (needs config)
```

Dependencies between plugins:

```typescript
const databasePlugin = (): Plugin => ({
    name: "database",
    dependencies: ["config"], // Requires config plugin to run first
    register: async ({ toolbox }) => {
        const { config } = toolbox;
        toolbox.database = connectDatabase(config.databaseUrl);
    },
});
```

## Testing with Plugins [#testing-with-plugins]

Test commands with plugins enabled:

```typescript
import { createCerebro } from "@visulima/cerebro";
import { myPlugin } from "./plugins/my-plugin";

test("command works with plugin", async () => {
    const cli = createCerebro("test-cli");
    cli.use(myPlugin());

    cli.addCommand({
        name: "test",
        execute: ({ myFeature }) => {
            myFeature.doSomething();
        },
    });

    await cli.run(["test"]);
});
```


# Introduction (/docs/packages/cerebro)



# @visulima/cerebro [#visulimacerebro]

A lightweight, extensible CLI framework for building modern command-line applications with TypeScript support, plugins, nested commands, and cross-runtime compatibility (Node.js, Deno, Bun).

## Key Features [#key-features]

**Framework & Architecture**

* **Zero Dependencies Core** - Minimal footprint with optional peer dependencies
* **TypeScript First** - Full type safety with comprehensive type definitions
* **Cross-Runtime** - Works with Node.js, Deno, and Bun
* **Plugin System** - Extensible architecture with built-in and custom plugins

**Commands & Arguments**

* **Nested Commands** - Support for subcommands and command hierarchies
* **Argument Parsing** - Built-in parser with types (String, Boolean, Number)
* **Option Validation** - Required options, conflicting options, implied options
* **Auto-completion** - Shell completion for bash, zsh, and fish

**Developer Experience**

* **Auto Help Generation** - Automatic help text from command metadata
* **Version Command** - Built-in version display
* **README Generation** - Generate documentation from command definitions
* **Error Handling** - Comprehensive error handling with helpful messages

**Built-in Features**

* **Verbosity Levels** - Quiet, normal, verbose, and debug output modes
* **Environment Variables** - Type-safe environment variable handling
* **Exception Handling** - Graceful error handling and exit codes
* **Levenshtein Suggestions** - Command suggestions for typos

## Quick Start [#quick-start]

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("my-cli", {
    packageName: "my-cli",
    packageVersion: "1.0.0",
});

cli.addCommand({
    name: "greet",
    description: "Greet someone",
    argument: {
        name: "name",
        description: "Name to greet",
        type: String,
    },
    execute: ({ argument, logger }) => {
        logger.log(`Hello, ${argument[0]}!`);
    },
});

await cli.run();
```

## Use Cases [#use-cases]

### Build Production CLIs [#build-production-clis]

Create professional command-line tools with nested commands, options, and help text:

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("deploy-cli", {
    packageName: "@company/deploy-cli",
    packageVersion: "2.1.0",
});

cli.addCommand({
    name: "deploy",
    description: "Deploy application to environment",
    argument: {
        name: "environment",
        description: "Target environment (staging|production)",
        type: String,
    },
    options: [
        {
            name: "skip-tests",
            description: "Skip test suite",
            type: Boolean,
        },
        {
            name: "timeout",
            description: "Deployment timeout in seconds",
            type: Number,
            defaultValue: 300,
        },
    ],
    execute: async ({ argument, options, logger }) => {
        const env = argument[0];
        logger.log(`Deploying to ${env}...`);
        // Deployment logic
    },
});

await cli.run();
```

### Plugin-Based Applications [#plugin-based-applications]

Extend your CLI with plugins for error handling, version checks, and notifications:

```typescript
import { createCerebro } from "@visulima/cerebro";
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";

const cli = createCerebro("my-tool", {
    packageName: "my-tool",
    packageVersion: "1.0.0",
});

cli.use(errorHandlerPlugin());
cli.use(updateNotifierPlugin({ checkInterval: 86400000 }));

// Add commands...
await cli.run();
```

### Cross-Runtime Tools [#cross-runtime-tools]

Build CLIs that work across Node.js, Deno, and Bun:

```typescript
// Works in Node.js, Deno, and Bun
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("universal-cli");

cli.addCommand({
    name: "info",
    description: "Show runtime information",
    execute: ({ logger, env }) => {
        logger.log(`Runtime: ${env.RUNTIME ?? "unknown"}`);
        logger.log(`Platform: ${process.platform}`);
    },
});

await cli.run();
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/cerebro/installation">
    Set up Cerebro in your project
  </Card>

  <Card title="Quick Start" href="/docs/packages/cerebro/quick-start">
    Build your first CLI in 5 minutes
  </Card>

  <Card title="Concepts" href="/docs/packages/cerebro/concepts/architecture">
    Understand Cerebro's architecture
  </Card>

  <Card title="API Reference" href="/docs/packages/cerebro/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

Cerebro is designed for command-line environments and works with:

* **Node.js** - Version 18.x and above
* **Deno** - Latest stable version
* **Bun** - Latest stable version
* **Platforms** - Linux, macOS, Windows


# Installation (/docs/packages/cerebro/installation)



# Installation [#installation]

Install Cerebro using your preferred package manager:

```bash npm2yarn
npm install @visulima/cerebro
```

## Peer Dependencies [#peer-dependencies]

Cerebro has minimal dependencies by default. Install optional peer dependencies as needed:

### Required Dependencies [#required-dependencies]

```bash npm2yarn
npm install @visulima/command-line-args @visulima/error
```

### Optional Features [#optional-features]

**Boxed Output (for formatted messages)**:

```bash npm2yarn
npm install @visulima/boxen
```

**Advanced Logging (Pail integration)**:

```bash npm2yarn
npm install @visulima/pail
```

**Shell Completion**:

```bash npm2yarn
npm install @visulima/fs @visulima/path
```

**README Generation**:

```bash npm2yarn
npm install @visulima/readgen
```

## Import [#import]

### ESM (Recommended) [#esm-recommended]

```typescript
import { createCerebro } from "@visulima/cerebro";
```

### CommonJS [#commonjs]

```typescript
const { createCerebro } = require("@visulima/cerebro");
```

### Subpath Imports [#subpath-imports]

Cerebro provides subpath imports for built-in commands and plugins:

```typescript
// Built-in commands
import { HelpCommand } from "@visulima/cerebro/command/help";
import { VersionCommand } from "@visulima/cerebro/command/version";
import { CompletionCommand } from "@visulima/cerebro/command/completion";
import { ReadmeCommand } from "@visulima/cerebro/command/readme";

// Plugins
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
import { runtimeVersionCheckPlugin } from "@visulima/cerebro/plugin/runtime-version-check";
import { updateNotifierPlugin } from "@visulima/cerebro/plugin/update-notifier";
```

## Requirements [#requirements]

* **Node.js**: 18.x or higher
* **TypeScript**: 5.0 or higher (for TypeScript projects)
* **Package Manager**: npm, yarn, pnpm, or bun

## Verification [#verification]

Verify your installation by creating a simple CLI:

```typescript
import { createCerebro } from "@visulima/cerebro";

const cli = createCerebro("test-cli");

cli.addCommand({
    name: "hello",
    description: "Say hello",
    execute: ({ logger }) => {
        logger.log("Hello from Cerebro!");
    },
});

await cli.run(["hello"]);
// Output: Hello from Cerebro!
```


# Introduction (/docs/packages/cerebro/introduction)







Cerebro is a modern, TypeScript-first CLI framework that makes it easy to build powerful command-line applications. Built with performance and developer experience in mind, Cerebro provides everything you need to create awesome CLIs.

<img alt="Cerebro Output" src="__img0" />

## Why Cerebro? [#why-cerebro]

### Fast & Lightweight [#fast--lightweight]

Cerebro is optimized for performance with minimal overhead. Your CLI starts quickly and runs efficiently, even with complex command structures.

### TypeScript First [#typescript-first]

Full TypeScript support with excellent type inference. Get autocomplete, type safety, and better developer experience out of the box.

### Extensible [#extensible]

Plugin system allows you to extend functionality without modifying core code. Add features like logging, prompts, file system operations, and more.

### Feature Rich [#feature-rich]

Built-in support for:

* Commands with arguments and options
* Shell autocompletions (bash, zsh, fish, powershell)
* Help generation
* README documentation generation
* Error handling
* Plugin lifecycle hooks
* Command composition

### Zero Configuration [#zero-configuration]

Get started in minutes. Sensible defaults mean you can build a working CLI without any configuration.

## Quick Navigation [#quick-navigation]

<Cards>
  <Card title="Quick Start" href="/docs/packages/cerebro/quickstart" description="Get up and running with Cerebro in under 2 minutes" />

  <Card title="Commands" href="/docs/packages/cerebro/guides/commands" description="Learn how to create and configure commands" />

  <Card title="Options & Arguments" href="/docs/packages/cerebro/guides/options" description="Handle command-line options and positional arguments" />

  <Card title="Plugins" href="/docs/packages/cerebro/guides/plugins" description="Extend Cerebro with plugins and lifecycle hooks" />

  <Card title="Toolbox" href="/docs/packages/cerebro/toolbox/parameters" description="Access runtime, logger, and other toolbox features" />
</Cards>

## Key Features [#key-features]

### Commands [#commands]

Define commands with descriptions, options, arguments, and aliases. Commands can be grouped, hidden, or configured with examples.

```typescript
cli.addCommand({
    name: "build",
    description: "Build your project",
    options: [
        { name: "production", type: Boolean },
        { name: "output", type: String },
    ],
    execute: ({ options, logger }) => {
        logger.info(`Building ${options.production ? "production" : "development"}...`);
    },
});
```

### Options [#options]

Powerful option handling with support for:

* Type validation (String, Number, Boolean, Arrays)
* Default values
* Required options
* Aliases
* Negatable options (`--no-` prefix)
* Conflicting options
* Implied options

### Arguments [#arguments]

Positional arguments with type checking and default values.

```typescript
cli.addCommand({
    name: "greet",
    argument: {
        name: "name",
        type: String,
        description: "Name to greet",
    },
    execute: ({ argument }) => {
        console.log(`Hello, ${argument[0]}!`);
    },
});
```

### Plugins [#plugins]

Extend functionality with plugins that hook into the command lifecycle:

* `init` - Called once during plugin initialization
* `execute` - Called during command execution (extends toolbox)
* `beforeCommand` - Called before command execution
* `afterCommand` - Called after successful command execution
* `onError` - Called when errors occur

### Command Composition [#command-composition]

Call commands from within other commands using `runtime.runCommand()`:

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        logger.info("Building...");
        await runtime.runCommand("build", { argv: ["--production"] });

        logger.info("Testing...");
        await runtime.runCommand("test");

        logger.info("Deploying...");
    },
});
```

## Installation [#installation]

<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;]">
  <Tab value="pnpm">
    `bash pnpm add @visulima/cerebro `
  </Tab>

  <Tab value="npm">
    `bash npm install @visulima/cerebro `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/cerebro `
  </Tab>
</Tabs>

## Next Steps [#next-steps]

Ready to build your CLI? Head to the [Quick Start](/docs/packages/cerebro/quickstart) guide to create your first command in minutes!


# Quick Start (/docs/packages/cerebro/quick-start)



# Quick Start [#quick-start]

Build your first CLI application with Cerebro in under 5 minutes.

## Basic CLI [#basic-cli]

Create a simple CLI with a single command:

```typescript
import { createCerebro } from "@visulima/cerebro";

// Create CLI instance
const cli = createCerebro("greet-cli", {
    packageName: "greet-cli",
    packageVersion: "1.0.0",
});

// Add a command
cli.addCommand({
    name: "hello",
    description: "Greet someone",
    execute: ({ logger }) => {
        logger.log("Hello, World!");
    },
});

// Run the CLI
await cli.run();
```

Run it:

```bash
$ node cli.js hello
Hello, World!
```

## Commands with Arguments [#commands-with-arguments]

Add arguments to your commands:

```typescript
cli.addCommand({
    name: "greet",
    description: "Greet someone by name",
    argument: {
        name: "name",
        description: "Person to greet",
        type: String,
    },
    execute: ({ argument, logger }) => {
        const name = argument[0];
        logger.log(`Hello, ${name}!`);
    },
});
```

```bash
$ node cli.js greet Alice
Hello, Alice!
```

## Commands with Options [#commands-with-options]

Add options for more flexibility:

```typescript
cli.addCommand({
    name: "greet",
    description: "Greet someone",
    argument: {
        name: "name",
        description: "Person to greet",
        type: String,
    },
    options: [
        {
            name: "loud",
            alias: "l",
            description: "Make it loud",
            type: Boolean,
        },
        {
            name: "times",
            alias: "t",
            description: "Number of times to greet",
            type: Number,
            defaultValue: 1,
        },
    ],
    execute: ({ argument, options, logger }) => {
        const name = argument[0];
        const message = `Hello, ${name}!`;
        const output = options.loud ? message.toUpperCase() : message;

        for (let i = 0; i < options.times; i++) {
            logger.log(output);
        }
    },
});
```

```bash
$ node cli.js greet Alice --loud --times 3
HELLO, ALICE!
HELLO, ALICE!
HELLO, ALICE!
```

## Automatic Help [#automatic-help]

Cerebro automatically generates help text:

```bash
$ node cli.js --help
greet-cli v1.0.0

Usage: greet-cli <command> [options]

Commands:
  greet <name>  Greet someone

Options:
  --help     Show help
  --version  Show version
```

## Environment Variables [#environment-variables]

Access environment variables in your commands:

```typescript
cli.addCommand({
    name: "env",
    description: "Show environment info",
    env: {
        API_KEY: {
            description: "API key for authentication",
            required: true,
        },
    },
    execute: ({ env, logger }) => {
        logger.log(`API Key: ${env.API_KEY}`);
    },
});
```

```bash
$ API_KEY=secret123 node cli.js env
API Key: secret123
```

## Nested Commands [#nested-commands]

Create command hierarchies:

```typescript
cli.addCommand({
    name: "db",
    description: "Database commands",
    commands: [
        {
            name: "migrate",
            description: "Run migrations",
            execute: ({ logger }) => {
                logger.log("Running migrations...");
            },
        },
        {
            name: "seed",
            description: "Seed database",
            execute: ({ logger }) => {
                logger.log("Seeding database...");
            },
        },
    ],
});
```

```bash
$ node cli.js db migrate
Running migrations...

$ node cli.js db seed
Seeding database...
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Concepts" href="/docs/packages/cerebro/concepts/architecture">
    Learn how Cerebro works under the hood
  </Card>

  <Card title="Commands Guide">
    Deep dive into command creation
  </Card>

  <Card title="Plugins" href="/docs/packages/cerebro/guides/using-plugins">
    Extend your CLI with plugins
  </Card>
</Cards>


# Quick Start (/docs/packages/cerebro/quickstart)





Get started with Cerebro and build your first CLI in under 2 minutes.

<Steps>
  <Step>
    ### Install Cerebro [#install-cerebro]

    Install the package using your preferred package manager:

    <Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;]">
      <Tab value="pnpm">
        `bash pnpm add @visulima/cerebro `
      </Tab>

      <Tab value="npm">
        `bash npm install @visulima/cerebro `
      </Tab>

      <Tab value="yarn">
        `bash yarn add @visulima/cerebro `
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create Your CLI File [#create-your-cli-file]

    Create a new file `cli.js` (or `cli.ts` for TypeScript):

    ```typescript title="cli.js"
    import { Cerebro } from "@visulima/cerebro";

    const cli = new Cerebro("my-app", {
        packageName: "my-app",
        packageVersion: "1.0.0",
    });

    cli.addCommand({
        name: "hello",
        description: "Say hello to someone",
        argument: {
            name: "name",
            type: String,
            description: "Name to greet",
            defaultValue: "World",
        },
        options: [
            {
                name: "greeting",
                alias: "g",
                type: String,
                description: "Custom greeting",
                defaultValue: "Hello",
            },
        ],
        execute: ({ argument, options, logger }) => {
            const name = argument?.[0] || "World";
            logger.info(`${options.greeting}, ${name}!`);
        },
    });

    await cli.run();
    ```
  </Step>

  <Step>
    ### Make It Executable [#make-it-executable]

    Add the shebang and make it executable:

    ```bash
    chmod +x cli.js
    ```

    Or if using TypeScript with tsx:

    ```bash
    chmod +x cli.ts
    ```
  </Step>

  <Step>
    ### Run Your CLI [#run-your-cli]

    Now you can run your CLI:

    ```bash
    # Default greeting
    node cli.js hello
    # Output: Hello, World!

    # With a name
    node cli.js hello Alice
    # Output: Hello, Alice!

    # With custom greeting
    node cli.js hello Alice --greeting "Hi"
    # Output: Hi, Alice!

    # Using alias
    node cli.js hello Alice -g "Hey"
    # Output: Hey, Alice!
    ```
  </Step>

  <Step>
    ### TypeScript Support [#typescript-support]

    For TypeScript, use the same code but with `.ts` extension:

    ```typescript title="cli.ts"
    import { Cerebro } from "@visulima/cerebro";

    // ... same code ...
    ```

    Run with `tsx` or compile first:

    ```bash
    # Using tsx
    tsx cli.ts hello Alice

    # Or compile and run
    tsc cli.ts && node cli.js hello Alice
    ```

    **Congratulations!** You've created your first CLI with Cerebro. Now explore the [Commands Guide](/docs/packages/cerebro/guides/commands) to learn more about advanced features.
  </Step>
</Steps>

## What's Next? [#whats-next]

* [Commands Guide](/docs/packages/cerebro/guides/commands) - Learn about command configuration
* [Options & Arguments](/docs/packages/cerebro/guides/options) - Handle CLI options and arguments
* [Plugins](/docs/packages/cerebro/guides/plugins) - Extend functionality with plugins
* [API Reference](/docs/packages/cerebro/api/cli) - Complete API documentation


# Logger (/docs/packages/cerebro/toolbox/logger)



# Toolbox: Logger [#toolbox-logger]

The `logger` provides methods for outputting messages at different log levels.

## Basic Usage [#basic-usage]

```typescript
cli.addCommand({
    name: "example",
    execute: ({ logger }) => {
        logger.info("Information message");
        logger.error("Error message");
        logger.warn("Warning message");
        logger.debug("Debug message");
    },
});
```

## Log Levels [#log-levels]

### Info [#info]

General information messages:

```typescript
logger.info("Building project...");
logger.info("Files processed:", fileCount);
```

### Error [#error]

Error messages:

```typescript
logger.error("Failed to build");
logger.error("Error details:", error);
```

### Warn [#warn]

Warning messages:

```typescript
logger.warn("Deprecated option used");
logger.warn("This feature will be removed in v2.0");
```

### Debug [#debug]

Debug messages (only shown with `--debug` flag):

```typescript
logger.debug("Processing file:", fileName);
logger.debug("Options:", options);
```

## Logging Objects [#logging-objects]

Logger methods accept multiple arguments:

```typescript
logger.info("User:", user.name, "Age:", user.age);
logger.error("Error:", error.message, error.stack);
```

## Verbosity Control [#verbosity-control]

Log levels are controlled by verbosity flags:

```bash
cli command              # Shows info, warn, error
cli command --verbose    # Shows debug too
cli command --debug      # Shows all debug messages
cli command --quiet      # Minimal output
```

## Custom Logger [#custom-logger]

Provide a custom logger when creating the CLI:

```typescript
const customLogger = {
    info: (...args) => console.log("[INFO]", ...args),
    error: (...args) => console.error("[ERROR]", ...args),
    warn: (...args) => console.warn("[WARN]", ...args),
    debug: (...args) => {
        if (process.env.DEBUG) {
            console.debug("[DEBUG]", ...args);
        }
    },
};

const cli = new Cerebro("my-app", {
    logger: customLogger,
});
```

## Conditional Logging [#conditional-logging]

Use log levels appropriately:

```typescript
execute: ({ logger, options }) => {
    if (options.verbose) {
        logger.debug("Detailed processing information");
    }

    logger.info("Starting operation...");

    try {
        // Operation
    } catch (error) {
        logger.error("Operation failed:", error);
    }
};
```

## Best Practices [#best-practices]

1. **Use appropriate levels** - info for normal output, error for errors
2. **Don't overuse debug** - Reserve for troubleshooting
3. **Include context** - Log relevant information
4. **Format consistently** - Use consistent message formats
5. **Respect verbosity** - Don't force output in quiet mode


# Parameters (/docs/packages/cerebro/toolbox/parameters)



# Toolbox: Parameters [#toolbox-parameters]

The toolbox provides access to command parameters including arguments, options, and the original argv.

## Arguments [#arguments]

Positional arguments passed to the command:

```typescript
cli.addCommand({
    name: "copy",
    argument: {
        name: "files",
        type: String,
    },
    execute: ({ argument }) => {
        // argument is an array of strings
        argument.forEach((file) => {
            console.log(`Copying ${file}...`);
        });
    },
});
```

Usage: `cli copy file1.txt file2.txt`

* `argument[0]` - First argument
* `argument[1]` - Second argument
* `argument` - Array of all arguments

## Options [#options]

Parsed command-line options:

```typescript
cli.addCommand({
    name: "build",
    options: [
        { name: "production", type: Boolean },
        { name: "output", type: String },
    ],
    execute: ({ options }) => {
        const isProduction = options.production; // boolean
        const outputDir = options.output; // string | undefined
    },
});
```

Options are:

* Type-safe based on option definitions
* Camel-cased automatically (`--output-dir` → `options.outputDir`)
* Include default values if set
* Validated before execution

## Environment Variables [#environment-variables]

Type-safe access to environment variables defined in your command:

```typescript
cli.addCommand({
    name: "build",
    env: [
        {
            name: "API_KEY",
            type: String,
            description: "API key",
        },
        {
            name: "TIMEOUT",
            type: Number,
            defaultValue: 5000,
            description: "Timeout in ms",
        },
        {
            name: "VERBOSE",
            type: Boolean,
            defaultValue: false,
            description: "Enable verbose output",
        },
    ],
    execute: ({ env }) => {
        const apiKey = env.apiKey; // string | undefined
        const timeout = env.timeout; // number (5000 if not set)
        const verbose = env.verbose; // boolean (false if not set)
    },
});
```

Environment variables are:

* Type-safe based on their type definitions
* Automatically converted to camelCase (`API_KEY` → `apiKey`)
* Include default values if not set
* Transformed according to their type (String, Number, Boolean)

### Boolean Environment Variables [#boolean-environment-variables]

Boolean environment variables accept multiple truthy values (case-insensitive):

* `true`, `1`, `yes`, `on` → `true`
* Any other value → `false`

```bash
VERBOSE=true cli build    # env.verbose = true
VERBOSE=1 cli build      # env.verbose = true
VERBOSE=yes cli build    # env.verbose = true
VERBOSE=false cli build  # env.verbose = false
```

## Argv [#argv]

Original command-line arguments:

```typescript
execute: ({ argv }) => {
    // Raw argv as parsed by command-line-args
    console.log(argv);
};
```

Use `argv` when you need:

* Raw argument values
* Unknown options handling
* Low-level argument access

## Accessing Parameters [#accessing-parameters]

```typescript
cli.addCommand({
    name: "deploy",
    argument: {
        name: "target",
        type: String,
    },
    options: [
        { name: "env", type: String, required: true },
        { name: "force", type: Boolean },
    ],
    env: [
        {
            name: "API_KEY",
            type: String,
            description: "API key for deployment",
        },
        {
            name: "TIMEOUT",
            type: Number,
            defaultValue: 30000,
            description: "Deployment timeout",
        },
    ],
    execute: ({ argument, options, env, argv }) => {
        const target = argument[0]; // Positional argument
        const envName = options.env; // Option value
        const force = options.force || false; // Option with default
        const apiKey = env.apiKey; // Environment variable
        const timeout = env.timeout; // Environment variable with default

        // Access raw argv if needed
        console.log("Raw argv:", argv);
    },
});
```

## Type Safety [#type-safety]

With TypeScript, you get full type safety:

```typescript
interface DeployOptions {
    env: string;
    force: boolean;
    dryRun?: boolean;
}

cli.addCommand({
    name: "deploy",
    options: [
        { name: "env", type: String, required: true },
        { name: "force", type: Boolean },
        { name: "dry-run", type: Boolean },
    ],
    execute: ({ options }: { options: DeployOptions }) => {
        // TypeScript knows the structure
        const env: string = options.env; // ✅
        const force: boolean = options.force; // ✅
    },
});
```


# Print (/docs/packages/cerebro/toolbox/print)



# Toolbox: Print [#toolbox-print]

The `logger` provides print methods for formatted output (if using a logger that supports it, like Pail).

## Basic Printing [#basic-printing]

```typescript
execute: ({ logger }) => {
    logger.info("Info message");
    logger.error("Error message");
    logger.warn("Warning message");
    logger.debug("Debug message");
};
```

## Custom Print Methods [#custom-print-methods]

Some loggers (like Pail) provide additional print methods:

```typescript
execute: ({ logger }) => {
    // If using Pail logger
    if (logger.success) {
        logger.success("Operation successful!");
    }

    if (logger.table) {
        logger.table([
            { name: "Alice", age: 30 },
            { name: "Bob", age: 25 },
        ]);
    }
};
```

## Raw Output [#raw-output]

Some loggers support raw output:

```typescript
execute: ({ logger }) => {
    if (logger.raw) {
        logger.raw("Raw output without formatting");
    }
};
```

## Using Pail Logger [#using-pail-logger]

For enhanced printing capabilities, use the Pail logger:

```typescript
import { pail } from "@visulima/pail";

const cli = new Cerebro("my-app", {
    logger: pail({
        // Pail configuration
    }),
});
```

Pail provides:

* Colored output
* Tables
* Success/error formatting
* Progress bars
* And more

See [Pail documentation](https://github.com/visulima/visulima/tree/main/packages/pail) for details.


# Runtime (/docs/packages/cerebro/toolbox/runtime)



# Toolbox: Runtime [#toolbox-runtime]

The `runtime` property provides access to the CLI instance, allowing you to call other commands programmatically.

## Accessing Runtime [#accessing-runtime]

```typescript
execute: ({ runtime }) => {
    // runtime is the CLI instance
    const cliName = runtime.getCliName();
    const commands = runtime.getCommands();
};
```

## Calling Other Commands [#calling-other-commands]

Use `runtime.runCommand()` to execute other commands:

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        logger.info("Building...");
        await runtime.runCommand("build", {
            argv: ["--production"],
        });

        logger.info("Deploying...");
    },
});
```

### Passing Arguments [#passing-arguments]

```typescript
await runtime.runCommand("copy", {
    argv: ["file1.txt", "file2.txt"],
});
```

### Passing Options [#passing-options]

```typescript
await runtime.runCommand("build", {
    argv: ["--production", "--output", "dist"],
});
```

### Merging Options [#merging-options]

```typescript
await runtime.runCommand("build", {
    argv: ["--production"],
    customOption: "value",
});
```

### Getting Return Values [#getting-return-values]

```typescript
const result = await runtime.runCommand("calculate");
console.log(result); // Command return value
```

## Runtime Methods [#runtime-methods]

### getCliName() [#getcliname]

Get the CLI application name:

```typescript
const name = runtime.getCliName(); // "my-app"
```

### getCommands() [#getcommands]

Get all registered commands:

```typescript
const commands = runtime.getCommands(); // Map<string, Command>
commands.forEach((command, name) => {
    console.log(`Command: ${name}`);
});
```

### getCwd() [#getcwd]

Get the current working directory:

```typescript
const cwd = runtime.getCwd(); // "/path/to/project"
```

### getPackageName() [#getpackagename]

Get the package name if configured:

```typescript
const packageName = runtime.getPackageName(); // "my-app" | undefined
```

### getPackageVersion() [#getpackageversion]

Get the package version if configured:

```typescript
const version = runtime.getPackageVersion(); // "1.0.0" | undefined
```

### getPluginManager() [#getpluginmanager]

Get the plugin manager instance:

```typescript
const pluginManager = runtime.getPluginManager();
// Advanced plugin management
```

## Command Composition Examples [#command-composition-examples]

### Build Pipeline [#build-pipeline]

```typescript
cli.addCommand({
    name: "ci",
    execute: async ({ runtime, logger }) => {
        logger.info("Running CI pipeline...");

        await runtime.runCommand("lint");
        await runtime.runCommand("test", { argv: ["--coverage"] });
        await runtime.runCommand("build", { argv: ["--production"] });

        logger.info("CI pipeline complete!");
    },
});
```

### Conditional Execution [#conditional-execution]

```typescript
cli.addCommand({
    name: "release",
    options: [{ name: "skip-tests", type: Boolean }],
    execute: async ({ runtime, options, logger }) => {
        if (!options.skipTests) {
            logger.info("Running tests...");
            await runtime.runCommand("test");
        }

        logger.info("Building release...");
        await runtime.runCommand("build", { argv: ["--production"] });
    },
});
```

### Nested Command Calls [#nested-command-calls]

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime }) => {
        await runtime.runCommand("build");
    },
});

cli.addCommand({
    name: "build",
    execute: async ({ runtime }) => {
        await runtime.runCommand("compile");
        await runtime.runCommand("bundle");
    },
});
```

## Error Handling [#error-handling]

Errors from called commands propagate:

```typescript
cli.addCommand({
    name: "deploy",
    execute: async ({ runtime, logger }) => {
        try {
            await runtime.runCommand("build");
        } catch (error) {
            logger.error("Build failed:", error);
            throw error; // Re-throw to stop deployment
        }

        await runtime.runCommand("deploy-step");
    },
});
```

## Best Practices [#best-practices]

1. **Use for composition** - Break complex operations into smaller commands
2. **Handle errors** - Wrap `runCommand` calls in try-catch when needed
3. **Pass options explicitly** - Use `argv` array for clarity
4. **Avoid circular calls** - Don't create command call loops
5. **Document dependencies** - Make it clear which commands depend on others


# Troubleshooting (/docs/packages/cerebro/troubleshooting)



# Troubleshooting [#troubleshooting]

Common issues and solutions when working with Cerebro.

## Command Not Found [#command-not-found]

**Problem**: CLI reports "Command not found" for existing command

```bash
$ my-cli build
Error: Command "build" not found
```

**Solutions**:

1. Verify command is registered:

```typescript
cli.addCommand({
    name: "build",
    execute: ({ logger }) => {
        logger.log("Building...");
    },
});
```

2. Check for typos in command name
3. Check nested command syntax:

```bash
$ my-cli db migrate    # Correct
$ my-cli db-migrate    # Wrong
```

## Option Validation Errors [#option-validation-errors]

**Problem**: Required option errors

```bash
$ my-cli deploy
Error: Required option --environment is missing
```

**Solution**: Provide the required option:

```bash
$ my-cli deploy --environment production
```

Or make it optional with a default value:

```typescript
{
  name: "environment",
  type: String,
  defaultValue: "staging",  // No longer required
}
```

## Conflicting Options Error [#conflicting-options-error]

**Problem**: Using incompatible options together

```bash
$ my-cli test --watch --ci
Error: Options --watch and --ci conflict
```

**Solution**: Use only one of the conflicting options:

```bash
$ my-cli test --watch
# or
$ my-cli test --ci
```

## Type Errors [#type-errors]

**Problem**: TypeScript errors for toolbox extensions

```typescript
cli.addCommand({
    execute: ({ myFeature }) => {
        // Error: Property 'myFeature' does not exist
    },
});
```

**Solution**: Declare the extension type:

```typescript
declare global {
    namespace Cerebro {
        interface ExtensionOverrides {
            myFeature: {
                doSomething: () => void;
            };
        }
    }
}
```

## Plugin Initialization Issues [#plugin-initialization-issues]

**Problem**: Plugin not working in commands

```typescript
cli.use(myPlugin());

cli.addCommand({
    execute: ({ myFeature }) => {
        // myFeature is undefined
    },
});
```

**Solutions**:

1. Check plugin registration order (before commands)
2. Verify plugin adds to toolbox:

```typescript
const myPlugin = (): Plugin => ({
    name: "my-plugin",
    register: async ({ toolbox }) => {
        toolbox.myFeature = { doSomething: () => {} };
    },
});
```

3. Check for plugin dependencies

## Environment Variable Issues [#environment-variable-issues]

**Problem**: Required environment variable not found

```bash
$ my-cli deploy
Error: Required environment variable API_KEY is missing
```

**Solution**: Set the environment variable:

```bash
$ API_KEY=secret123 my-cli deploy
```

Or use a `.env` file:

```bash
# .env
API_KEY=secret123
```

```typescript
import "dotenv/config";
import { createCerebro } from "@visulima/cerebro";
// ...
```

## Help Text Not Showing [#help-text-not-showing]

**Problem**: `--help` doesn't display help text

**Solutions**:

1. Verify help command is registered (automatic by default)
2. Add command descriptions:

```typescript
cli.addCommand({
    name: "build",
    description: "Build the project", // Required for help
    execute: ({ logger }) => {},
});
```

3. Manually register help command:

```typescript
import { HelpCommand } from "@visulima/cerebro/command/help";
cli.addCommand(HelpCommand);
```

## Exit Code Issues [#exit-code-issues]

**Problem**: CLI exits with code 0 even on errors

**Solution**: Use error handler plugin:

```typescript
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";

cli.use(errorHandlerPlugin({ exitOnError: true }));
```

Or manually set exit code:

```typescript
cli.addCommand({
    name: "test",
    execute: async ({ logger }) => {
        try {
            await runTests();
        } catch (error) {
            logger.error(error.message);
            process.exit(1); // Exit with error code
        }
    },
});
```

## Performance Issues [#performance-issues]

**Problem**: CLI is slow to start

**Solutions**:

1. Lazy-load heavy dependencies:

```typescript
cli.addCommand({
    name: "heavy",
    execute: async () => {
        // Load only when command runs
        const { heavyFunction } = await import("./heavy-module");
        await heavyFunction();
    },
});
```

2. Minimize plugin initialization work
3. Use dynamic imports for optional features

## Cross-Runtime Issues [#cross-runtime-issues]

**Problem**: CLI works in Node.js but not in Deno/Bun

**Solutions**:

1. Avoid Node.js-specific APIs
2. Use Cerebro's runtime abstractions:

```typescript
import { getEnv, getCwd } from "@visulima/cerebro";

cli.addCommand({
    execute: ({ logger }) => {
        const env = getEnv(); // Works in all runtimes
        const cwd = getCwd(); // Works in all runtimes
        logger.log(`CWD: ${cwd}`);
    },
});
```

3. Test in all target runtimes

## Debugging [#debugging]

Enable debug output:

```bash
CEREBRO_OUTPUT_LEVEL=debug my-cli build
```

Add debug logging:

```typescript
cli.addCommand({
    name: "build",
    execute: ({ logger }) => {
        if (process.env.CEREBRO_OUTPUT_LEVEL === "debug") {
            logger.log("Debug: Starting build...");
        }
        // Build logic
    },
});
```


# API Reference (/docs/packages/colorize/api)



# API Reference [#api-reference]

Complete API documentation for **@visulima/colorize**.

## Imports [#imports]

### Main Package [#main-package]

```typescript
// Default import
import colorize from "@visulima/colorize";

// Named imports
import { red, green, blue, bold, hex, rgb } from "@visulima/colorize";
```

### Browser [#browser]

```typescript
import colorize from "@visulima/colorize/browser";
import { red, green, blue } from "@visulima/colorize/browser";
```

### Template [#template]

```typescript
import template from "@visulima/colorize/template";
```

### Gradient [#gradient]

```typescript
import { gradient, multilineGradient } from "@visulima/colorize/gradient";
```

### Utils [#utils]

```typescript
import { strip } from "@visulima/colorize/utils";
```

## Colors [#colors]

### Base Colors (Foreground) [#base-colors-foreground]

Standard ANSI 16 colors for text:

| Function        | Description         | Example            |
| --------------- | ------------------- | ------------------ |
| `black`         | Black text          | `black\`text\`\`   |
| `red`           | Red text            | `red\`text\`\`     |
| `green`         | Green text          | `green\`text\`\`   |
| `yellow`        | Yellow text         | `yellow\`text\`\`  |
| `blue`          | Blue text           | `blue\`text\`\`    |
| `magenta`       | Magenta text        | `magenta\`text\`\` |
| `cyan`          | Cyan text           | `cyan\`text\`\`    |
| `white`         | White text          | `white\`text\`\`   |
| `gray` / `grey` | Gray text (aliases) | `gray\`text\`\`    |

### Bright Colors (Foreground) [#bright-colors-foreground]

Brighter variants of base colors:

| Function        | Description         | Example                  |
| --------------- | ------------------- | ------------------------ |
| `blackBright`   | Bright black text   | `blackBright\`text\`\`   |
| `redBright`     | Bright red text     | `redBright\`text\`\`     |
| `greenBright`   | Bright green text   | `greenBright\`text\`\`   |
| `yellowBright`  | Bright yellow text  | `yellowBright\`text\`\`  |
| `blueBright`    | Bright blue text    | `blueBright\`text\`\`    |
| `magentaBright` | Bright magenta text | `magentaBright\`text\`\` |
| `cyanBright`    | Bright cyan text    | `cyanBright\`text\`\`    |
| `whiteBright`   | Bright white text   | `whiteBright\`text\`\`   |

### Background Colors [#background-colors]

Background colors using `bg` prefix:

| Function            | Description        | Example              |
| ------------------- | ------------------ | -------------------- |
| `bgBlack`           | Black background   | `bgBlack\`text\`\`   |
| `bgRed`             | Red background     | `bgRed\`text\`\`     |
| `bgGreen`           | Green background   | `bgGreen\`text\`\`   |
| `bgYellow`          | Yellow background  | `bgYellow\`text\`\`  |
| `bgBlue`            | Blue background    | `bgBlue\`text\`\`    |
| `bgMagenta`         | Magenta background | `bgMagenta\`text\`\` |
| `bgCyan`            | Cyan background    | `bgCyan\`text\`\`    |
| `bgWhite`           | White background   | `bgWhite\`text\`\`   |
| `bgGray` / `bgGrey` | Gray background    | `bgGray\`text\`\`    |

### Bright Background Colors [#bright-background-colors]

| Function          | Description               | Example                    |
| ----------------- | ------------------------- | -------------------------- |
| `bgBlackBright`   | Bright black background   | `bgBlackBright\`text\`\`   |
| `bgRedBright`     | Bright red background     | `bgRedBright\`text\`\`     |
| `bgGreenBright`   | Bright green background   | `bgGreenBright\`text\`\`   |
| `bgYellowBright`  | Bright yellow background  | `bgYellowBright\`text\`\`  |
| `bgBlueBright`    | Bright blue background    | `bgBlueBright\`text\`\`    |
| `bgMagentaBright` | Bright magenta background | `bgMagentaBright\`text\`\` |
| `bgCyanBright`    | Bright cyan background    | `bgCyanBright\`text\`\`    |
| `bgWhiteBright`   | Bright white background   | `bgWhiteBright\`text\`\`   |

## Styles [#styles]

### Text Modifiers [#text-modifiers]

| Function        | Description                          | Example                  |
| --------------- | ------------------------------------ | ------------------------ |
| `bold`          | Bold/bright text                     | `bold\`text\`\`          |
| `dim`           | Dimmed/faint text                    | `dim\`text\`\`           |
| `italic`        | Italic text                          | `italic\`text\`\`        |
| `underline`     | Underlined text                      | `underline\`text\`\`     |
| `strikethrough` | Strikethrough text (alias: `strike`) | `strikethrough\`text\`\` |
| `inverse`       | Inverted colors                      | `inverse\`text\`\`       |
| `hidden`        | Hidden text (invisible)              | `hidden\`text\`\`        |
| `visible`       | Always visible (no-op for always-on) | `visible\`text\`\`       |
| `reset`         | Reset all styles                     | `reset\`text\`\`         |

## Extended Colors [#extended-colors]

### ANSI 256 Colors [#ansi-256-colors]

Access the 256-color palette (0-255):

#### `ansi256(code: number)` [#ansi256code-number]

Apply a 256-color foreground. Alias: `fg()`

**Parameters:**

* `code` (number): Color code from 0 to 255

**Returns:** Chainable style function

**Example:**

```typescript
import { ansi256, fg } from "@visulima/colorize";

console.log(ansi256(196)`Bright red`); // Color code 196
console.log(fg(21)`Deep blue`); // Alias usage
console.log(ansi256(226).bold`Bold yellow`); // Chainable
```

#### `bgAnsi256(code: number)` [#bgansi256code-number]

Apply a 256-color background. Alias: `bg()`

**Parameters:**

* `code` (number): Color code from 0 to 255

**Returns:** Chainable style function

**Example:**

```typescript
import { bgAnsi256, bg, white } from "@visulima/colorize";

console.log(white.bgAnsi256(196)`White on red`);
console.log(white.bg(21)`White on blue`); // Alias usage
```

### TrueColor (16M Colors) [#truecolor-16m-colors]

#### `hex(color: string)` [#hexcolor-string]

Apply a hex color to text foreground.

**Parameters:**

* `color` (string): Hex color code (e.g., `"#FF0000"`, `"#F00"`)

**Returns:** Chainable style function

**Example:**

```typescript
import { hex } from "@visulima/colorize";

console.log(hex("#FF6B6B")`Coral red`);
console.log(hex("#F00")`Red`); // Short notation
console.log(hex("#4ECDC4").bold`Bold turquoise`);
```

#### `bgHex(color: string)` [#bghexcolor-string]

Apply a hex color to text background.

**Parameters:**

* `color` (string): Hex color code

**Returns:** Chainable style function

**Example:**

```typescript
import { bgHex, white } from "@visulima/colorize";

console.log(white.bgHex("#FF6B6B")`White on coral`);
console.log(bgHex("#4ECDC4")`Turquoise background`);
```

#### `rgb(red: number, green: number, blue: number)` [#rgbred-number-green-number-blue-number]

Apply an RGB color to text foreground.

**Parameters:**

* `red` (number): Red value (0-255)
* `green` (number): Green value (0-255)
* `blue` (number): Blue value (0-255)

**Returns:** Chainable style function

**Example:**

```typescript
import { rgb } from "@visulima/colorize";

console.log(rgb(255, 107, 107)`Coral red`);
console.log(rgb(78, 205, 196).bold`Bold turquoise`);
```

#### `bgRgb(red: number, green: number, blue: number)` [#bgrgbred-number-green-number-blue-number]

Apply an RGB color to text background.

**Parameters:**

* `red` (number): Red value (0-255)
* `green` (number): Green value (0-255)
* `blue` (number): Blue value (0-255)

**Returns:** Chainable style function

**Example:**

```typescript
import { bgRgb, white } from "@visulima/colorize";

console.log(white.bgRgb(255, 107, 107)`White on coral`);
```

## Utility Functions [#utility-functions]

### `strip(text: string): string` [#striptext-string-string]

Remove all ANSI escape codes from a string.

**Parameters:**

* `text` (string): String containing ANSI codes

**Returns:** Plain string without ANSI codes

**Example:**

```typescript
import colorize from "@visulima/colorize";
// or
import { strip } from "@visulima/colorize/utils";

const colored = colorize.red.bold`Error`;
const plain = colorize.strip(colored);

console.log(colored); // Colored output
console.log(plain); // "Error" (plain text)
```

## Template Functions [#template-functions]

### `template(strings, ...values): string` [#templatestrings-values-string]

Tagged template literal for complex string interpolation with colors.

**Usage:**

```typescript
import template from "@visulima/colorize/template";

const cpu = 65;
console.log(template`CPU: {red ${cpu}%}`);

// Chained styles
console.log(template`Status: {green.bold Success}`);

// RGB/Hex colors
console.log(template`{rgb(255,0,0) Red text}`);
console.log(template`{#FF0000 Red text}`);

// Background with shorthand
console.log(template`{#FF0000:00FF00 Red on green}`);
```

## Gradient Functions [#gradient-functions]

### `gradient(...colors: string[])` [#gradientcolors-string]

Create a color gradient for text.

**Parameters:**

* `...colors` (string\[]): Two or more color names, hex codes, or RGB strings

**Returns:** Function that applies gradient to text

**Example:**

```typescript
import { gradient } from "@visulima/colorize/gradient";

console.log(gradient("red", "blue")("Hello World"));
console.log(gradient("red", "yellow", "green")("Rainbow"));
console.log(gradient("#FF6B6B", "#4ECDC4")("Custom colors"));
console.log(gradient("rgb(255,0,0)", "rgb(0,0,255)")("RGB gradient"));
```

### `multilineGradient(colors: string[])` [#multilinegradientcolors-string]

Create a gradient that maintains vertical alignment across multiple lines.

**Parameters:**

* `colors` (string\[]): Array of color names, hex codes, or RGB strings

**Returns:** Function that applies gradient to multi-line text

**Example:**

```typescript
import { multilineGradient } from "@visulima/colorize/gradient";

const asciiArt = `
Line 1
Line 2
Line 3
`;

console.log(multilineGradient(["cyan", "magenta"])(asciiArt));
```

## Properties [#properties]

Each style function has the following properties:

### `open: string` [#open-string]

The ANSI opening code for the style.

**Example:**

```typescript
import { red } from "@visulima/colorize";

console.log(red.open); // "\x1b[31m"
```

### `close: string` [#close-string]

The ANSI closing code for the style.

**Example:**

```typescript
import { red } from "@visulima/colorize";

console.log(red.close); // "\x1b[39m"
```

### Usage with Properties [#usage-with-properties]

```typescript
import { green, red, bold } from "@visulima/colorize";

console.log(`Hello ${green.open}World${green.close}!`);

const customStyle = bold.red.bgYellow;
console.log(`${customStyle.open}Styled text${customStyle.close}`);
```

## TypeScript Types [#typescript-types]

### `ColorizeType` [#colorizetype]

The type for the default import:

```typescript
import type { ColorizeType } from "@visulima/colorize";

const colorize: ColorizeType = (await import("@visulima/colorize")).default;
```

### Style Function Type [#style-function-type]

```typescript
type StyleFunction = {
    (strings: TemplateStringsArray, ...values: any[]): string;
    (text: string): string;
    open: string;
    close: string;
} & Record<string, StyleFunction>;
```

## Chaining [#chaining]

All colors, styles, and functions are chainable in any order:

```typescript
import { red, bold, underline, hex, bgGreen } from "@visulima/colorize";

// Any order works
console.log(red.bold.underline`Text`);
console.log(bold.red.underline`Text`);
console.log(underline.bold.red`Text`);

// Mix everything
console.log(hex("#FF6B6B").bold.bgGreen.italic`Complex styling`);
```

## Browser Differences [#browser-differences]

Browser exports return arrays instead of strings:

```typescript
import { red } from "@visulima/colorize/browser";

const result = red("Error");
// Returns: ['%cError', 'color: red']

// Use spread operator
console.log(...result);
```

All methods and properties are the same, only the return format differs.


# Introduction (/docs/packages/colorize)



# @visulima/colorize [#visulimacolorize]

Terminal and console string styling done right. A high-performance, feature-rich library for colorizing terminal and browser console output with ANSI escape codes.

## Why Colorize? [#why-colorize]

**@visulima/colorize** is a modern, performant alternative to Chalk and other color libraries, offering the best of both worlds: **Chalk-compatible API** with **superior performance** (up to 3x faster).

### Key Features [#key-features]

**Compatibility & Performance**

* **Chalk-compatible API** - Drop-in replacement with the same syntax
* **Up to 3x faster** than Chalk in benchmarks
* **Named imports** - `import { red, green } from '@visulima/colorize'`
* **Zero dependencies** (except for color detection)

**Multiple Runtimes**

* **Node.js** 22.13+ support (ESM and CommonJS)
* **Browser support** - Works in Chrome, Safari, Edge, and more
* **Deno** and **Next.js** runtime compatibility

**Rich Color Support**

* **Base ANSI 16 colors** - Standard terminal colors (red, green, blue, etc.)
* **ANSI 256 colors** - Extended color palette with `ansi256()` or `fg()`/`bg()`
* **TrueColor (16M colors)** - RGB and HEX colors with `rgb()` and `hex()`
* **Automatic fallback** - TrueColor → 256 → 16 → no colors

**Developer Experience**

* **Chained syntax** - `` red.bold.underline`text` ``
* **Template literals** - `` red`Hello ${green`World`}` ``
* **Nested templates** - Deep nesting support (unique among color libraries)
* **TypeScript** - Full type definitions with IDE autocomplete

**Advanced Features**

* **Color gradients** - Single and multi-line gradient support
* **Tagged templates** - String interpolation with `@visulima/colorize/template`
* **Strip ANSI codes** - Remove colors with `strip()` method
* **Environment awareness** - Respects `NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`

## Quick Start [#quick-start]

### Installation [#installation]

```bash npm2yarn
npm install @visulima/colorize
```

### Basic Usage [#basic-usage]

```typescript
import colorize, { red, green, blue } from "@visulima/colorize";

// Default import
console.log(colorize.green("Success!"));

// Named import
console.log(red("Error!"));

// Template literals
console.log(blue`Information`);

// Chained syntax
console.log(green.bold`Success!`);

// Nested templates
console.log(red`The ${blue.underline`file.js`} not found!`);
```

## Use Cases [#use-cases]

### CLI Tool Output [#cli-tool-output]

Enhance command-line tool output with clear, colorful messages:

```typescript
import { green, red, yellow, bold } from "@visulima/colorize";

console.log(green.bold("✓ Build completed successfully!"));
console.log(yellow("⚠ Warning: Deprecated API usage detected"));
console.log(red("✗ Error: File not found"));
console.log(bold("=== Test Results ==="));
```

### Structured Logging [#structured-logging]

Create readable, color-coded logs for better debugging:

```typescript
import { gray, cyan, yellow, red, bold } from "@visulima/colorize";

const logger = {
    debug: (msg: string) => console.log(gray(`[DEBUG] ${msg}`)),
    info: (msg: string) => console.log(cyan(`[INFO] ${msg}`)),
    warn: (msg: string) => console.log(yellow(`[WARN] ${msg}`)),
    error: (msg: string) => console.log(red.bold(`[ERROR] ${msg}`)),
};

logger.info("Server started on port 3000");
logger.warn("High memory usage detected");
logger.error("Database connection failed");
```

### Terminal Dashboards [#terminal-dashboards]

Build rich terminal UI with gradients and complex styling:

```typescript
import { green, red, hex, inverse } from "@visulima/colorize";

const cpu = { totalPercent: 45 };
const ram = { used: 8, total: 16 };
const disk = { used: 120, total: 256 };

const orange = hex("#FFAB40");

console.log(inverse`
CPU:  ${red`${cpu.totalPercent}%`}
RAM:  ${green`${((ram.used / ram.total) * 100).toFixed(1)}%`}
DISK: ${orange`${((disk.used / disk.total) * 100).toFixed(1)}%`}
`);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/colorize/installation">
    Learn how to install and set up colorize in your project
  </Card>

  <Card title="Quick Start" href="/docs/packages/colorize/quick-start">
    Get started with colorize in 5 minutes
  </Card>

  <Card title="Basic Usage" href="/docs/packages/colorize/usage/basic">
    Explore common usage patterns and syntax
  </Card>

  <Card title="Advanced Features" href="/docs/packages/colorize/usage/advanced">
    Discover TrueColor, gradients, and advanced capabilities
  </Card>

  <Card title="API Reference" href="/docs/packages/colorize/api">
    Complete API documentation with all methods and options
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

### Node.js [#nodejs]

* ✅ Node.js 22.13 - 25.x
* ✅ ESM and CommonJS support

### Browsers [#browsers]

* ✅ Chrome 69+ (TrueColor)
* ✅ Safari 10+ (TrueColor)
* ✅ Edge 79+ (TrueColor)
* ✅ Opera 56+ (TrueColor)
* ⚠️ Firefox (fallback to `%c` syntax)

### Runtimes [#runtimes]

* ✅ Deno
* ✅ Next.js (edge runtime)


# Installation (/docs/packages/colorize/installation)



# Installation [#installation]

## Package Manager [#package-manager]

Install **@visulima/colorize** using your preferred package manager:

```bash npm2yarn
npm install @visulima/colorize
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0+ (optional, for TypeScript projects)

## Import Methods [#import-methods]

### Node.js (ESM) [#nodejs-esm]

```typescript
// Default import
import colorize from "@visulima/colorize";

// Named imports (recommended)
import { red, green, blue, bold, hex } from "@visulima/colorize";
```

### Node.js (CommonJS) [#nodejs-commonjs]

```javascript
// Default import
const colorize = require("@visulima/colorize");

// Named imports
const { red, green, blue, bold, hex } = require("@visulima/colorize");
```

### Browser [#browser]

For browser environments, use the dedicated browser export:

```typescript
// ESM default import
import colorize from "@visulima/colorize/browser";

// ESM named imports
import { red, green, blue } from "@visulima/colorize/browser";
```

**Important:** Browser version returns an array format for console styling. Use the spread operator:

```typescript
import { green } from "@visulima/colorize/browser";

console.log(...green("Success!")); // Note the spread operator
```

### Subpath Exports [#subpath-exports]

The package provides several specialized exports for advanced features:

```typescript
// Template literals
import template from "@visulima/colorize/template";

// Gradient support
import { gradient, multilineGradient } from "@visulima/colorize/gradient";

// Utility functions
import { strip } from "@visulima/colorize/utils";
```

## Verification [#verification]

Verify your installation by running a simple color test:

```typescript
import { green, red, blue } from "@visulima/colorize";

console.log(green("✓ Installation successful!"));
console.log(blue("ℹ Colorize is ready to use"));
console.log(red.bold("● Colors are working"));
```

If you see colored output, the installation is successful!

## TypeScript Support [#typescript-support]

TypeScript definitions are included automatically. No additional `@types` packages are needed.

```typescript
import type { ColorizeType } from "@visulima/colorize";

// Full type checking and autocomplete
const colorize: ColorizeType = (await import("@visulima/colorize")).default;
```

## Environment Variables [#environment-variables]

Colorize automatically detects and respects color support through environment variables:

* **`NO_COLOR`** - Disables all colors when set to any value
* **`FORCE_COLOR`** - Forces color output (values: `0`, `1`, `2`, `3`)
* **`COLORTERM`** - Detects TrueColor support (value: `truecolor`)

CLI flags are also supported:

* **`--no-color`** - Disables colors
* **`--color`** - Forces color output

## Next Steps [#next-steps]

<Cards>
  <Card title="Quick Start" href="/docs/packages/colorize/quick-start">
    Get up and running with colorize in 5 minutes
  </Card>

  <Card title="Basic Usage" href="/docs/packages/colorize/usage/basic">
    Learn the fundamental usage patterns
  </Card>
</Cards>


# Quick Start (/docs/packages/colorize/quick-start)



# Quick Start [#quick-start]

Learn the essentials of **@visulima/colorize** in 5 minutes.

## Installation [#installation]

```bash npm2yarn
npm install @visulima/colorize
```

## Basic Colors [#basic-colors]

Use named color imports for the simplest syntax:

```typescript
import { red, green, blue, yellow } from "@visulima/colorize";

console.log(red("Error message"));
// Output: Error message (in red)

console.log(green("Success message"));
// Output: Success message (in green)

console.log(blue("Information"));
// Output: Information (in blue)

console.log(yellow("Warning"));
// Output: Warning (in yellow)
```

## Template Literals [#template-literals]

Use template literal syntax for cleaner code:

```typescript
import { red, green, cyan } from "@visulima/colorize";

console.log(red`Error: File not found`);
console.log(green`Build completed successfully`);
console.log(cyan`Server running on port 3000`);
```

## Styles and Modifiers [#styles-and-modifiers]

Chain styles together for combined effects:

```typescript
import { red, green, bold, italic, underline } from "@visulima/colorize";

console.log(red.bold`Bold error`);
console.log(green.italic`Italic success`);
console.log(underline.cyan`Underlined info`);

// Multiple styles
console.log(bold.underline.red`Important error`);
```

## Nested Styling [#nested-styling]

Nest colors within each other for complex output:

```typescript
import { red, blue, green } from "@visulima/colorize";

console.log(red`Error in ${blue`file.js`} at line ${green`42`}`);
// Output: Error in file.js at line 42 (with different colors)
```

## Background Colors [#background-colors]

Apply background colors using `bg` prefix:

```typescript
import { bgRed, bgGreen, bgBlue, white, black } from "@visulima/colorize";

console.log(white.bgRed`Error`);
console.log(black.bgGreen`Success`);
console.log(white.bgBlue`Info`);
```

## TrueColor (RGB/HEX) [#truecolor-rgbhex]

Use custom colors with hex or RGB values:

```typescript
import { hex, rgb } from "@visulima/colorize";

// Hex colors
console.log(hex("#FF6B6B")`Custom red`);
console.log(hex("#4ECDC4")`Custom teal`);

// RGB colors
console.log(rgb(255, 107, 107)`Custom red`);
console.log(rgb(78, 205, 196)`Custom teal`);

// With background
import { bgHex, bgRgb } from "@visulima/colorize";

console.log(bgHex("#FF6B6B")`Red background`);
console.log(bgRgb(78, 205, 196)`Teal background`);
```

## Combining Everything [#combining-everything]

Mix colors, styles, and nesting for rich terminal output:

```typescript
import { bold, red, green, blue, hex } from "@visulima/colorize";

const success = green.bold`✓`;
const error = red.bold`✗`;
const info = blue`ℹ`;

console.log(`${success} Build completed`);
console.log(`${error} Tests failed`);
console.log(`${info} ${blue`Server`} started on port ${hex("#FFB800")`3000`}`);
```

## Strip ANSI Codes [#strip-ansi-codes]

Remove colors from strings when needed:

```typescript
import colorize, { red } from "@visulima/colorize";

const coloredText = red`Error message`;
const plainText = colorize.strip(coloredText);

console.log(coloredText); // Output: Error message (colored)
console.log(plainText); // Output: Error message (plain)
```

## Default Import [#default-import]

Use the default import for Chalk-compatible syntax:

```typescript
import colorize from "@visulima/colorize";

console.log(colorize.red.bold("Bold red text"));
console.log(colorize.green("Green text"));
console.log(colorize.hex("#FF6B6B")("Custom color"));
```

## Common Patterns [#common-patterns]

### Log Levels [#log-levels]

```typescript
import { gray, cyan, yellow, red, bold } from "@visulima/colorize";

const log = {
    debug: (msg: string) => console.log(gray(`[DEBUG] ${msg}`)),
    info: (msg: string) => console.log(cyan(`[INFO] ${msg}`)),
    warn: (msg: string) => console.log(yellow(`[WARN] ${msg}`)),
    error: (msg: string) => console.log(red.bold(`[ERROR] ${msg}`)),
};

log.debug("Debugging application");
log.info("Server started");
log.warn("High memory usage");
log.error("Connection failed");
```

### Status Messages [#status-messages]

```typescript
import { green, red, blue } from "@visulima/colorize";

console.log(green`✓ All tests passed`);
console.log(red`✗ 2 tests failed`);
console.log(blue`→ Running tests...`);
```

### File Operations [#file-operations]

```typescript
import { green, red, yellow } from "@visulima/colorize";

console.log(green`Created: ${yellow`src/index.ts`}`);
console.log(red`Deleted: ${yellow`dist/old.js`}`);
console.log(blue`Modified: ${yellow`package.json`}`);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Basic Usage" href="/docs/packages/colorize/usage/basic">
    Explore all base colors and styles
  </Card>

  <Card title="Advanced Features" href="/docs/packages/colorize/usage/advanced">
    Learn about gradients and 256 colors
  </Card>

  <Card title="API Reference" href="/docs/packages/colorize/api">
    Complete API documentation
  </Card>
</Cards>


# Troubleshooting (/docs/packages/colorize/troubleshooting)



# Troubleshooting [#troubleshooting]

Common issues and solutions for **@visulima/colorize**.

## Installation Issues [#installation-issues]

### Module Not Found Error [#module-not-found-error]

**Problem:** `Cannot find module '@visulima/colorize'`

**Solution:**

```bash npm2yarn
# Reinstall the package
npm install @visulima/colorize

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```

### TypeScript Errors [#typescript-errors]

**Problem:** TypeScript cannot find type definitions

**Solution:**
Type definitions are included. Ensure your `tsconfig.json` has:

```json
{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true
    }
}
```

## Color Display Issues [#color-display-issues]

### Colors Not Showing [#colors-not-showing]

**Problem:** No colors appear in terminal output

**Possible Causes & Solutions:**

1. **Environment Variable Set:**

   ```bash
   # Check if NO_COLOR is set
   echo $NO_COLOR

   # Unset it
   unset NO_COLOR
   ```

2. **Terminal Doesn't Support Colors:**

   ```bash
   # Force color output
   FORCE_COLOR=1 node script.js

   # Or use CLI flag
   node script.js --color
   ```

3. **Output is Piped:**
   When output is piped or redirected, colors are automatically disabled. Force colors:

   ```typescript
   // Set before importing
   process.env.FORCE_COLOR = "1";

   import { red } from "@visulima/colorize";
   ```

4. **CI Environment:**
   Most CI environments disable colors by default:
   ```bash
   # In CI config, set:
   FORCE_COLOR=1
   ```

### Wrong Colors Displayed [#wrong-colors-displayed]

**Problem:** Colors appear incorrect or washed out

**Solution:**

Check terminal color support:

```bash
# Check if terminal supports TrueColor
echo $COLORTERM

# Should output: truecolor
```

If your terminal doesn't support TrueColor, colorize automatically falls back to 256 or 16 colors.

### Colors Work Locally But Not in CI [#colors-work-locally-but-not-in-ci]

**Problem:** Colors show locally but not in CI/CD pipelines

**Solution:**

```yaml
# GitHub Actions
env:
    FORCE_COLOR: "1"

# GitLab CI
variables:
    FORCE_COLOR: "1"

# CircleCI
environment:
    FORCE_COLOR: "1"
```

## Browser Issues [#browser-issues]

### Spread Operator Required Error [#spread-operator-required-error]

**Problem:** Browser console shows `[Array]` instead of colored text

**Solution:**
Use the spread operator:

```typescript
import { red } from "@visulima/colorize/browser";

// ❌ Wrong
console.log(red("Error"));

// ✅ Correct
console.log(...red("Error"));
```

### Firefox Colors Not Working [#firefox-colors-not-working]

**Problem:** Colors don't appear in Firefox DevTools

**Solution:**
Firefox doesn't support ANSI codes natively. Colorize automatically falls back to `%c` syntax. Ensure you're using the spread operator:

```typescript
import { red, green } from "@visulima/colorize/browser";

console.log(...red("Error")); // Works in Firefox
console.log(...green("Success")); // Works in Firefox
```

### Source File Location Lost [#source-file-location-lost]

**Problem:** Console doesn't show file path and line numbers

**Solution:**
This happens when using the console override hack. Remove the hack to restore file paths:

```typescript
// Remove this override to see file paths again
// The trade-off is you need to use the spread operator
console.log(...colorize.red("Error")); // Shows file path
```

## Import Issues [#import-issues]

### Named Import Not Working [#named-import-not-working]

**Problem:** `import { red } from '@visulima/colorize'` fails

**Solution:**
Ensure your environment supports ESM:

**Node.js (ESM):**

```json
// package.json
{
    "type": "module"
}
```

**TypeScript:**

```json
// tsconfig.json
{
    "compilerOptions": {
        "module": "ES2020",
        "moduleResolution": "node"
    }
}
```

**CommonJS Alternative:**

```javascript
const { red } = require("@visulima/colorize");
```

### Subpath Exports Not Resolved [#subpath-exports-not-resolved]

**Problem:** `Cannot find module '@visulima/colorize/template'`

**Solution:**
Ensure you're using Node.js 22.13 or higher, which supports `exports` field in `package.json`.

Update Node.js:

```bash
nvm install 22.13
nvm use 22.13
```

Or use the full path (not recommended):

```typescript
import template from "@visulima/colorize/dist/template.mjs";
```

## Performance Issues [#performance-issues]

### Slow Rendering [#slow-rendering]

**Problem:** Terminal output is slow when using colors

**Solution:**

1. **Reduce color operations in loops:**

   ```typescript
   // ❌ Slow: Color inside loop
   for (let i = 0; i < 1000; i++) {
       console.log(red(`Item ${i}`));
   }

   // ✅ Fast: Color once, reuse
   const redText = red("Item");
   for (let i = 0; i < 1000; i++) {
       console.log(`${redText} ${i}`);
   }
   ```

2. **Use template literals efficiently:**

   ```typescript
   // ❌ Slower
   red("Text " + variable + " more text");

   // ✅ Faster
   red`Text ${variable} more text`;
   ```

### Memory Leaks [#memory-leaks]

**Problem:** Memory usage increases over time

**Solution:**
Don't store large numbers of colorize instances. Reuse colors:

```typescript
// ❌ Don't do this
const colors = [];
for (let i = 0; i < 10000; i++) {
    colors.push(red(`Item ${i}`));
}

// ✅ Do this
const red = import { red } from "@visulima/colorize";
// Use red() directly when needed
```

## TypeScript Issues [#typescript-issues]

### Type Errors with Chaining [#type-errors-with-chaining]

**Problem:** TypeScript shows errors when chaining styles

**Solution:**
This is usually a version issue. Ensure you have TypeScript 5.0+:

```bash npm2yarn
npm install -D typescript@latest
```

### Return Type Errors [#return-type-errors]

**Problem:** TypeScript complains about return types

**Solution:**
Explicitly type the function if needed:

```typescript
import type { StyleFunction } from "@visulima/colorize";
import { red } from "@visulima/colorize";

const myStyle: StyleFunction = red.bold;
```

## Windows-Specific Issues [#windows-specific-issues]

### Colors Don't Work in cmd.exe [#colors-dont-work-in-cmdexe]

**Problem:** No colors in Windows Command Prompt

**Solution:**
Use Windows Terminal instead of cmd.exe:

```bash
# Install Windows Terminal
winget install Microsoft.WindowsTerminal

# Or download from Microsoft Store
```

Alternatively, enable ANSI support in cmd.exe (Windows 10+):

```cmd
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
```

### PowerShell Colors Issue [#powershell-colors-issue]

**Problem:** Colors look wrong in PowerShell

**Solution:**
Use PowerShell 7+ for best results:

```powershell
# Install PowerShell 7
winget install Microsoft.PowerShell
```

## Gradient Issues [#gradient-issues]

### Gradient Not Smooth [#gradient-not-smooth]

**Problem:** Gradient appears blocky or with few colors

**Solution:**
Ensure your terminal supports TrueColor:

```bash
# Set COLORTERM
export COLORTERM=truecolor

# Or force color level
export FORCE_COLOR=3
```

### Multi-line Gradient Alignment Off [#multi-line-gradient-alignment-off]

**Problem:** Multi-line gradient doesn't align properly

**Solution:**
Use `multilineGradient` instead of `gradient`:

```typescript
import { multilineGradient } from "@visulima/colorize/gradient";

// ✅ Correct for multi-line
console.log(multilineGradient(["cyan", "magenta"])(text));

// ❌ Wrong for multi-line (each line gets full gradient)
console.log(gradient("cyan", "magenta")(text));
```

## Template Issues [#template-issues]

### Template Syntax Error [#template-syntax-error]

**Problem:** Tagged template doesn't work

**Solution:**
Ensure you're using the correct syntax:

```typescript
import template from "@visulima/colorize/template";

// ✅ Correct
console.log(template`{red Error message}`);

// ❌ Wrong (missing template tag)
console.log(template("{red Error message}"));
```

### Template Variables Not Interpolating [#template-variables-not-interpolating]

**Problem:** Variables show as `[object Object]`

**Solution:**
Convert objects to strings:

```typescript
import template from "@visulima/colorize/template";

const user = { name: "John" };

// ❌ Wrong
console.log(template`User: {green ${user}}`);

// ✅ Correct
console.log(template`User: {green ${user.name}}`);
console.log(template`User: {green ${JSON.stringify(user)}}`);
```

## Environment Detection [#environment-detection]

### Color Support Not Detected [#color-support-not-detected]

**Problem:** Colorize doesn't detect terminal capabilities correctly

**Solution:**
Manually set the color level:

```bash
# Force TrueColor (24-bit)
export FORCE_COLOR=3

# Force 256 colors
export FORCE_COLOR=2

# Force 16 colors
export FORCE_COLOR=1

# Disable colors
export NO_COLOR=1
```

Or programmatically:

```typescript
// Before importing colorize
process.env.FORCE_COLOR = "3";

import { red } from "@visulima/colorize";
```

## Getting Help [#getting-help]

If you're still experiencing issues:

1. **Check Node.js version:**

   ```bash
   node --version
   # Should be 22.13 or higher
   ```

2. **Check package version:**

   ```bash
   npm list @visulima/colorize
   ```

3. **Enable debug output:**

   ```typescript
   import colorize from "@visulima/colorize";

   console.log("Color support detected:", colorize.isColorSupported);
   ```

4. **Report an issue:**
   * GitHub: [github.com/visulima/visulima/issues](https://github.com/visulima/visulima/issues)
   * Include:
     * Node.js version
     * Operating system
     * Terminal emulator
     * Minimal reproduction code

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/colorize/api">
    Review the complete API documentation
  </Card>

  <Card title="Examples" href="/docs/packages/colorize/usage/examples">
    See working examples
  </Card>
</Cards>


# Advanced Features (/docs/packages/colorize/usage/advanced)



# Advanced Features [#advanced-features]

This guide covers advanced capabilities of **@visulima/colorize** including ANSI 256 colors, TrueColor support, gradients, and tagged template literals.

## ANSI 256 Colors [#ansi-256-colors]

Access the extended 256-color palette for more color options.

### Color Ranges [#color-ranges]

The 256-color palette is divided into ranges:

| Range   | Description                              |
| ------- | ---------------------------------------- |
| 0-7     | Standard colors (same as base 16)        |
| 8-15    | Bright colors (same as base 16)          |
| 16-231  | 6×6×6 RGB cube (216 colors)              |
| 232-255 | Grayscale from black to white (24 steps) |

### Foreground Colors [#foreground-colors]

Use `ansi256()` or its alias `fg()` for 256 foreground colors:

```typescript
import { ansi256, fg } from "@visulima/colorize";

// Using ansi256()
console.log(ansi256(196)`Bright red`); // Color code 196
console.log(ansi256(21)`Deep blue`); // Color code 21
console.log(ansi256(226)`Yellow`); // Color code 226

// Using fg() alias (shorter)
console.log(fg(196)`Bright red`);
console.log(fg(21)`Deep blue`);
console.log(fg(226)`Yellow`);
```

### Background Colors [#background-colors]

Use `bgAnsi256()` or its alias `bg()` for 256 background colors:

```typescript
import { bgAnsi256, bg, white } from "@visulima/colorize";

// Using bgAnsi256()
console.log(white.bgAnsi256(196)`White on red`);
console.log(white.bgAnsi256(21)`White on blue`);

// Using bg() alias (shorter)
console.log(white.bg(196)`White on red`);
console.log(white.bg(21)`White on blue`);
```

### Chaining with 256 Colors [#chaining-with-256-colors]

Combine 256 colors with styles and other colors:

```typescript
import { ansi256, bg, bold, italic } from "@visulima/colorize";

console.log(ansi256(196).bold`Bold bright red`);
console.log(bold.ansi256(21).italic`Bold italic blue`);
console.log(ansi256(226).bg(21)`Yellow text on blue background`);
```

### Grayscale Colors [#grayscale-colors]

Use grayscale range (232-255) for subtle effects:

```typescript
import { ansi256 } from "@visulima/colorize";

// Darker grays
console.log(ansi256(232)`Darkest gray`);
console.log(ansi256(237)`Dark gray`);
console.log(ansi256(242)`Medium gray`);
console.log(ansi256(248)`Light gray`);
console.log(ansi256(255)`Lightest gray (almost white)`);
```

## TrueColor (16 Million Colors) [#truecolor-16-million-colors]

Use RGB or HEX values for precise color control with 24-bit TrueColor.

### HEX Colors [#hex-colors]

Define colors using hexadecimal notation:

```typescript
import { hex, bgHex } from "@visulima/colorize";

// Foreground colors
console.log(hex("#FF6B6B")`Coral red`);
console.log(hex("#4ECDC4")`Turquoise`);
console.log(hex("#FFE66D")`Sunshine yellow`);
console.log(hex("#95E1D3")`Mint green`);

// Short hex notation
console.log(hex("#F00")`Red`);
console.log(hex("#0F0")`Green`);
console.log(hex("#00F")`Blue`);

// Background colors
console.log(bgHex("#FF6B6B")`Coral background`);
console.log(bgHex("#4ECDC4")`Turquoise background`);
```

### RGB Colors [#rgb-colors]

Define colors using RGB values (0-255):

```typescript
import { rgb, bgRgb } from "@visulima/colorize";

// Foreground colors
console.log(rgb(255, 107, 107)`Coral red`);
console.log(rgb(78, 205, 196)`Turquoise`);
console.log(rgb(255, 230, 109)`Sunshine yellow`);

// Background colors
console.log(bgRgb(255, 107, 107)`Coral background`);
console.log(bgRgb(78, 205, 196)`Turquoise background`);
```

### Chaining TrueColor [#chaining-truecolor]

Combine TrueColor with styles and other colors:

```typescript
import { hex, bgHex, bold, italic } from "@visulima/colorize";

console.log(hex("#FF6B6B").bold`Bold coral`);
console.log(bold.hex("#4ECDC4").italic`Bold italic turquoise`);
console.log(hex("#FF6B6B").bgHex("#4ECDC4")`Coral on turquoise`);
```

### Brand Colors [#brand-colors]

Define brand colors as constants:

```typescript
import { hex } from "@visulima/colorize";

const brandColors = {
    primary: hex("#007AFF"),
    success: hex("#34C759"),
    warning: hex("#FF9500"),
    danger: hex("#FF3B30"),
    info: hex("#5856D6"),
};

console.log(brandColors.primary`Primary color text`);
console.log(brandColors.success`Success message`);
console.log(brandColors.warning`Warning message`);
console.log(brandColors.danger`Error message`);
```

## Color Fallback [#color-fallback]

Colorize automatically falls back to supported color spaces:

```
TrueColor → ANSI 256 → ANSI 16 → No colors
```

If a terminal doesn't support TrueColor:

* TrueColor is converted to the nearest 256-color
* If 256 colors aren't supported, it converts to base 16 colors
* If no colors are supported, ANSI codes are stripped

No configuration needed - fallback is automatic!

## Gradients [#gradients]

Create beautiful color gradients for text.

### Single-Line Gradients [#single-line-gradients]

Apply gradients to single-line text:

```typescript
import { gradient } from "@visulima/colorize/gradient";

// Two-color gradient
console.log(gradient("red", "blue")("Hello World"));

// Three-color gradient
console.log(gradient("red", "yellow", "green")("Rainbow text"));

// Using hex colors
console.log(gradient("#FF6B6B", "#4ECDC4")("Custom gradient"));

// Using RGB colors
console.log(gradient("rgb(255,0,0)", "rgb(0,0,255)")("RGB gradient"));
```

### Multi-Line Gradients [#multi-line-gradients]

Apply gradients across multiple lines with vertical alignment:

```typescript
import { multilineGradient } from "@visulima/colorize/gradient";

const asciiArt = `
 ██████╗  ██████╗ ██╗      ██████╗ ██████╗ ██╗███████╗███████╗
██╔════╝ ██╔═══██╗██║     ██╔═══██╗██╔══██╗██║╚══███╔╝██╔════╝
██║      ██║   ██║██║     ██║   ██║██████╔╝██║  ███╔╝ █████╗
██║      ██║   ██║██║     ██║   ██║██╔══██╗██║ ███╔╝  ██╔══╝
╚██████╗ ╚██████╔╝███████╗╚██████╔╝██║  ██║██║███████╗███████╗
 ╚═════╝  ╚═════╝ ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝╚══════╝╚══════╝
`;

console.log(multilineGradient(["cyan", "magenta"])(asciiArt));
```

### Gradient Examples [#gradient-examples]

```typescript
import { gradient, multilineGradient } from "@visulima/colorize/gradient";

// Sunrise gradient
console.log(gradient("purple", "orange", "yellow")("=== Sunrise ==="));

// Ocean gradient
console.log(gradient("#001F3F", "#0074D9", "#7FDBFF")("~~~ Ocean ~~~"));

// Fire gradient
console.log(gradient("red", "orange", "yellow", "white")("🔥 FIRE 🔥"));

// Multi-line with color alignment
const duck = `
     __
   <(o )___
    ( ._> /
     \`---'
`;
console.log(multilineGradient(["orange", "yellow"])(duck));
```

## Tagged Template Literals [#tagged-template-literals]

Use tagged template literals for complex string interpolation with colors.

### Basic Template Usage [#basic-template-usage]

```typescript
import template from "@visulima/colorize/template";

const cpu = { totalPercent: 45 };
const ram = { used: 8, total: 16 };
const disk = { used: 120, total: 256 };

console.log(template`
CPU:  {red ${cpu.totalPercent}%}
RAM:  {green ${((ram.used / ram.total) * 100).toFixed(1)}%}
DISK: {blue ${((disk.used / disk.total) * 100).toFixed(1)}%}
`);
```

### Chained Styles in Templates [#chained-styles-in-templates]

Chain styles just like regular colorize:

```typescript
import template from "@visulima/colorize/template";

console.log(template`
Status: {green.bold Success}
Error: {red.bold.underline Critical}
Info: {blue.italic Note}
`);
```

### TrueColor in Templates [#truecolor-in-templates]

Use RGB and hex colors in templates:

```typescript
import template from "@visulima/colorize/template";

console.log(template`
{rgb(255,107,107) Custom red color}
{hex(#4ECDC4) Custom teal color}
`);
```

### Hex Shorthand [#hex-shorthand]

Use shorthand hex notation in templates:

```typescript
import template from "@visulima/colorize/template";

console.log(template`
{#FF0000 Red foreground}
{#:00FF00 Green background}
{#FF0000:00FF00 Red on green}
`);
```

### Complex Templates [#complex-templates]

```typescript
import template from "@visulima/colorize/template";

const miles = 18;
const calculateFeet = (miles: number) => miles * 5280;

console.log(template`
    There are {bold 5280 feet} in a mile.
    In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
`);
```

## Browser Usage [#browser-usage]

### Basic Browser Support [#basic-browser-support]

```typescript
import { red, green, blue } from "@visulima/colorize/browser";

// Note the spread operator
console.log(...red("Error message"));
console.log(...green("Success message"));
console.log(...blue("Information"));
```

### Browser Return Format [#browser-return-format]

Browser version returns arrays for console `%c` syntax:

```typescript
import { red } from "@visulima/colorize/browser";

const result = red("Error");
// Returns: ['%cError', 'color: red']

console.log(...result); // Correctly styled in browser console
```

### Browser Compatibility [#browser-compatibility]

| Browser     | Version  | Colors Supported |
| ----------- | -------- | ---------------- |
| **Chrome**  | **69+**  | TrueColor (16M)  |
| **Safari**  | **10+**  | TrueColor (16M)  |
| **Edge**    | **79+**  | TrueColor (16M)  |
| **Opera**   | **56+**  | TrueColor (16M)  |
| **Brave**   | **1.0+** | TrueColor (16M)  |
| **Vivaldi** | **2.0+** | TrueColor (16M)  |
| **Firefox** | All      | Fallback to `%c` |

### Console Hack (Optional) [#console-hack-optional]

Override console for transparent usage (removes line numbers):

```typescript
import { red, green } from "@visulima/colorize/browser";

let consoleOverwritten = false;

if (typeof window !== "undefined" && !consoleOverwritten) {
    ["error", "log", "warn", "info"].forEach((method) => {
        const original = console[method];

        console[method] = (...args: any[]) => {
            if (Array.isArray(args[0]) && args[0][0]?.includes("%c")) {
                original(...args[0]);
            } else {
                original(...args);
            }
        };
    });

    consoleOverwritten = true;
}

// Now can use without spread
console.log(red("Error")); // Works without ...
```

**Warning:** This hack removes file paths and line numbers from console output.

## Next Steps [#next-steps]

<Cards>
  <Card title="Examples">
    See real-world usage examples
  </Card>

  <Card title="API Reference" href="/docs/packages/colorize/api">
    Complete API documentation
  </Card>

  <Card title="Troubleshooting" href="/docs/packages/colorize/troubleshooting">
    Common issues and solutions
  </Card>
</Cards>


# Basic Usage (/docs/packages/colorize/usage/basic)



# Basic Usage [#basic-usage]

This guide covers the fundamental usage patterns for **@visulima/colorize**.

## Import Styles [#import-styles]

### Named Import (Recommended) [#named-import-recommended]

Import specific colors and styles for the most concise code:

```typescript
import { red, green, blue, bold, italic } from "@visulima/colorize";

console.log(red("Error"));
console.log(green.bold("Success"));
```

### Default Import [#default-import]

Use the default import for Chalk-compatible syntax:

```typescript
import colorize from "@visulima/colorize";

console.log(colorize.red("Error"));
console.log(colorize.green.bold("Success"));
```

### Combined Imports [#combined-imports]

Mix default and named imports:

```typescript
import colorize, { red, strip } from "@visulima/colorize";

const coloredText = red("Error");
const plainText = colorize.strip(coloredText);
```

## Syntax Options [#syntax-options]

Colorize supports three syntax styles for maximum flexibility:

### 1. Function Syntax [#1-function-syntax]

Pass strings as function arguments:

```typescript
import { red, green, blue } from "@visulima/colorize";

console.log(red("Error message"));
console.log(green("Success message"));
console.log(blue("Information"));
```

### 2. Template Literal Syntax [#2-template-literal-syntax]

Use template literals for cleaner code:

```typescript
import { red, green, blue } from "@visulima/colorize";

console.log(red`Error message`);
console.log(green`Success message`);
console.log(blue`Information`);
```

### 3. Template Literal with Variables [#3-template-literal-with-variables]

Interpolate variables within template literals:

```typescript
import { red, blue, green } from "@visulima/colorize";

const filename = "config.json";
const line = 42;

console.log(red`Error in ${filename} at line ${line}`);
// Output: Error in config.json at line 42 (all in red)
```

## Base ANSI 16 Colors [#base-ansi-16-colors]

### Foreground Colors [#foreground-colors]

Standard terminal colors for text:

```typescript
import {
    black,
    red,
    green,
    yellow,
    blue,
    magenta,
    cyan,
    white,
    gray, // alias: grey
} from "@visulima/colorize";

console.log(black`Black text`);
console.log(red`Red text`);
console.log(green`Green text`);
console.log(yellow`Yellow text`);
console.log(blue`Blue text`);
console.log(magenta`Magenta text`);
console.log(cyan`Cyan text`);
console.log(white`White text`);
console.log(gray`Gray text`); // or grey
```

### Bright Colors [#bright-colors]

Brighter variants of standard colors:

```typescript
import { blackBright, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright } from "@visulima/colorize";

console.log(redBright`Bright red`);
console.log(greenBright`Bright green`);
console.log(blueBright`Bright blue`);
```

### Background Colors [#background-colors]

Apply colors to text background using `bg` prefix:

```typescript
import {
    bgBlack,
    bgRed,
    bgGreen,
    bgYellow,
    bgBlue,
    bgMagenta,
    bgCyan,
    bgWhite,
    white, // for foreground
} from "@visulima/colorize";

console.log(white.bgRed`White text on red background`);
console.log(white.bgBlue`White text on blue background`);
console.log(bgGreen`Green background`);
```

### Bright Background Colors [#bright-background-colors]

```typescript
import { bgBlackBright, bgRedBright, bgGreenBright, bgYellowBright, bgBlueBright, bgMagentaBright, bgCyanBright, bgWhiteBright } from "@visulima/colorize";

console.log(bgRedBright`Bright red background`);
console.log(bgGreenBright`Bright green background`);
```

## Text Styles [#text-styles]

### Basic Styles [#basic-styles]

```typescript
import { bold, dim, italic, underline, strikethrough } from "@visulima/colorize";

console.log(bold`Bold text`);
console.log(dim`Dimmed text`);
console.log(italic`Italic text`);
console.log(underline`Underlined text`);
console.log(strikethrough`Strikethrough text`); // alias: strike
```

### Special Styles [#special-styles]

```typescript
import { inverse, hidden, visible, reset } from "@visulima/colorize";

console.log(inverse`Inverted colors`);
console.log(hidden`Hidden text`); // Text is invisible
console.log(visible`Always visible`);
console.log(reset`Reset all styles`);
```

## Chained Syntax [#chained-syntax]

Chain multiple colors and styles together:

### Color + Style [#color--style]

```typescript
import { red, green, blue, bold, italic, underline } from "@visulima/colorize";

console.log(red.bold`Bold red text`);
console.log(green.italic`Italic green text`);
console.log(blue.underline`Underlined blue text`);
```

### Multiple Styles [#multiple-styles]

```typescript
import { red, bold, italic, underline } from "@visulima/colorize";

console.log(red.bold.italic`Bold italic red`);
console.log(bold.underline.green`Bold underlined green`);
console.log(red.bold.underline.italic`All styles combined`);
```

### Foreground + Background [#foreground--background]

```typescript
import { white, red, green, bgRed, bgGreen } from "@visulima/colorize";

console.log(white.bgRed`White text on red background`);
console.log(red.bgGreen`Red text on green background`);
```

### Any Order [#any-order]

Styles can be chained in any order:

```typescript
import { bold, red, underline } from "@visulima/colorize";

console.log(bold.red.underline`Style order 1`);
console.log(red.bold.underline`Style order 2`);
console.log(underline.bold.red`Style order 3`);
// All produce the same result
```

## Nested Styling [#nested-styling]

Nest colored text within other colored text:

### Basic Nesting [#basic-nesting]

```typescript
import { red, blue } from "@visulima/colorize";

console.log(red`Error: ${blue`file.js`} not found`);
// Output: "Error: file.js not found" with different colors
```

### Deep Nesting [#deep-nesting]

```typescript
import { green, yellow, magenta, cyan, red } from "@visulima/colorize";

console.log(green`Level 1 ${yellow`Level 2 ${magenta`Level 3 ${cyan`Level 4 ${red`Level 5`}`}`}`} back to Level 1`);
```

### Nested with Styles [#nested-with-styles]

```typescript
import { red, blue, bold, italic, underline } from "@visulima/colorize";

console.log(red`Error in ${bold.blue`file.js`} at ${italic`line 42`}`);
console.log(bold`Important: ${underline.red`Critical error`} detected`);
```

## Handling Edge Cases [#handling-edge-cases]

Colorize handles edge cases gracefully:

### Empty and Null Values [#empty-and-null-values]

```typescript
import { red } from "@visulima/colorize";

console.log(red()); // Returns: ""
console.log(red("")); // Returns: ""
console.log(red(undefined)); // Returns: ""
console.log(red(null)); // Returns: ""
```

### Newlines [#newlines]

Colors properly break at newlines:

```typescript
import { bgGreen, red } from "@visulima/colorize";

console.log(bgGreen`First line
Second line
Third line`);
// Each line has green background properly applied
```

## Strip ANSI Codes [#strip-ansi-codes]

Remove all ANSI color codes from strings:

```typescript
import colorize, { red, green, bold } from "@visulima/colorize";
// or
import { strip } from "@visulima/colorize/utils";

const styledText = red.bold`Error message`;
const plainText = colorize.strip(styledText);

console.log(styledText); // Output: Error message (colored and bold)
console.log(plainText); // Output: Error message (plain text)
```

## Using ANSI Codes Directly [#using-ansi-codes-directly]

Access raw ANSI codes for custom implementations:

```typescript
import { green, red, bold } from "@visulima/colorize";

// Each style has 'open' and 'close' properties
console.log(`Hello ${green.open}World${green.close}!`);

// Define custom styles
const myStyle = bold.italic.red.bgYellow;
console.log(`Custom: ${myStyle.open}styled text${myStyle.close}`);

console.log("Open code:", green.open); // \x1b[32m
console.log("Close code:", green.close); // \x1b[39m
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Advanced Features">
    Explore 256 colors, TrueColor, and gradients
  </Card>

  <Card title="Examples">
    See real-world usage examples
  </Card>

  <Card title="API Reference" href="/docs/packages/colorize/api">
    Complete API documentation
  </Card>
</Cards>


# Real-World Examples (/docs/packages/colorize/usage/examples)



# Real-World Examples [#real-world-examples]

Practical examples demonstrating how to use **@visulima/colorize** in real-world scenarios.

## CLI Tool Output [#cli-tool-output]

### Build Status Reporter [#build-status-reporter]

```typescript
import { green, red, yellow, blue, bold, dim } from "@visulima/colorize";

class BuildReporter {
    success(message: string) {
        console.log(green.bold(`✓ ${message}`));
    }

    error(message: string, details?: string) {
        console.log(red.bold(`✗ ${message}`));
        if (details) {
            console.log(dim(`  ${details}`));
        }
    }

    warning(message: string) {
        console.log(yellow(`⚠ ${message}`));
    }

    info(message: string) {
        console.log(blue(`ℹ ${message}`));
    }

    step(current: number, total: number, message: string) {
        console.log(dim(`[${current}/${total}]`) + ` ${message}`);
    }
}

const reporter = new BuildReporter();

reporter.step(1, 3, "Compiling TypeScript...");
reporter.success("TypeScript compilation completed");

reporter.step(2, 3, "Running tests...");
reporter.error("Tests failed", "2 tests failed in user.test.ts");

reporter.step(3, 3, "Building bundle...");
reporter.warning("Bundle size exceeds 1MB");
reporter.success("Build completed");
```

### Package Manager Output [#package-manager-output]

```typescript
import { green, cyan, yellow, gray, bold } from "@visulima/colorize";

function installPackage(name: string, version: string) {
    console.log(bold(`Installing ${name}@${version}...`));
    console.log(gray(`  → Resolving dependencies`));
    console.log(gray(`  → Fetching packages`));
    console.log(gray(`  → Linking dependencies`));
    console.log(green(`  ✓ ${name}@${version} installed`));
}

function packageInfo(name: string, description: string) {
    console.log(cyan.bold(name));
    console.log(gray(description));
}

installPackage("@visulima/colorize", "2.0.0");
packageInfo("@visulima/colorize", "Terminal string styling done right");
```

## Structured Logging [#structured-logging]

### Logger with Log Levels [#logger-with-log-levels]

```typescript
import { gray, cyan, yellow, red, bold } from "@visulima/colorize";

enum LogLevel {
    DEBUG = 0,
    INFO = 1,
    WARN = 2,
    ERROR = 3,
}

class Logger {
    constructor(private level: LogLevel = LogLevel.INFO) {}

    debug(message: string, data?: any) {
        if (this.level <= LogLevel.DEBUG) {
            console.log(gray(`[DEBUG] ${message}`), data || "");
        }
    }

    info(message: string, data?: any) {
        if (this.level <= LogLevel.INFO) {
            console.log(cyan(`[INFO]  ${message}`), data || "");
        }
    }

    warn(message: string, data?: any) {
        if (this.level <= LogLevel.WARN) {
            console.log(yellow(`[WARN]  ${message}`), data || "");
        }
    }

    error(message: string, error?: Error) {
        if (this.level <= LogLevel.ERROR) {
            console.log(red.bold(`[ERROR] ${message}`));
            if (error) {
                console.log(red(error.stack || error.message));
            }
        }
    }

    success(message: string) {
        console.log(green.bold(`[OK]    ${message}`));
    }
}

// Usage
const logger = new Logger(LogLevel.DEBUG);

logger.debug("Application starting");
logger.info("Server listening on port 3000");
logger.warn("Deprecated API usage detected");
logger.error("Database connection failed", new Error("Connection timeout"));
logger.success("All migrations completed");
```

### Request Logger [#request-logger]

```typescript
import { green, yellow, red, cyan, gray, bold } from "@visulima/colorize";

interface RequestLog {
    method: string;
    path: string;
    status: number;
    duration: number;
}

function logRequest({ method, path, status, duration }: RequestLog) {
    const methodColor =
        {
            GET: cyan,
            POST: green,
            PUT: yellow,
            DELETE: red,
            PATCH: yellow,
        }[method] || gray;

    const statusColor = status >= 500 ? red : status >= 400 ? yellow : status >= 300 ? cyan : green;

    console.log(methodColor.bold(method.padEnd(6)) + gray(path.padEnd(30)) + statusColor(status.toString().padEnd(5)) + gray(`${duration}ms`));
}

// Usage
logRequest({ method: "GET", path: "/api/users", status: 200, duration: 45 });
logRequest({ method: "POST", path: "/api/users", status: 201, duration: 120 });
logRequest({ method: "GET", path: "/api/posts", status: 404, duration: 12 });
logRequest({ method: "PUT", path: "/api/users/123", status: 500, duration: 2500 });
```

## Terminal Dashboards [#terminal-dashboards]

### System Monitor [#system-monitor]

```typescript
import { green, red, yellow, hex, inverse, bold } from "@visulima/colorize";

interface SystemStats {
    cpu: number;
    memory: { used: number; total: number };
    disk: { used: number; total: number };
}

function displaySystemStats(stats: SystemStats) {
    const cpuColor = stats.cpu > 80 ? red : stats.cpu > 50 ? yellow : green;
    const memPercent = (stats.memory.used / stats.memory.total) * 100;
    const memColor = memPercent > 80 ? red : memPercent > 50 ? yellow : green;
    const diskPercent = (stats.disk.used / stats.disk.total) * 100;
    const diskColor = diskPercent > 80 ? red : diskPercent > 50 ? yellow : green;

    console.log(inverse(bold(" SYSTEM MONITOR ")));
    console.log();
    console.log(`CPU:  ${cpuColor`${stats.cpu.toFixed(1)}%`}`.padEnd(20) + createProgressBar(stats.cpu, 100));
    console.log(`RAM:  ${memColor`${memPercent.toFixed(1)}%`}`.padEnd(20) + createProgressBar(stats.memory.used, stats.memory.total));
    console.log(`DISK: ${diskColor`${diskPercent.toFixed(1)}%`}`.padEnd(20) + createProgressBar(stats.disk.used, stats.disk.total));
}

function createProgressBar(current: number, total: number, width: number = 20): string {
    const percent = current / total;
    const filled = Math.round(width * percent);
    const empty = width - filled;
    const bar = "█".repeat(filled) + "░".repeat(empty);

    return percent > 0.8 ? red(bar) : percent > 0.5 ? yellow(bar) : green(bar);
}

// Usage
displaySystemStats({
    cpu: 65.4,
    memory: { used: 8.2, total: 16 },
    disk: { used: 120, total: 256 },
});
```

### Progress Indicators [#progress-indicators]

```typescript
import { green, blue, yellow, gray } from "@visulima/colorize";

class ProgressBar {
    private current: number = 0;

    constructor(
        private total: number,
        private width: number = 40,
    ) {}

    update(current: number, message?: string) {
        this.current = current;
        this.render(message);
    }

    private render(message?: string) {
        const percent = Math.min(100, (this.current / this.total) * 100);
        const filled = Math.round((this.width * percent) / 100);
        const empty = this.width - filled;

        const bar = green("█".repeat(filled)) + gray("░".repeat(empty));
        const percentText = blue(`${percent.toFixed(1)}%`);
        const status = message ? yellow(` ${message}`) : "";

        process.stdout.write(`\r${bar} ${percentText}${status}`);

        if (this.current >= this.total) {
            console.log(); // New line when complete
        }
    }
}

// Usage
const progress = new ProgressBar(100);

let current = 0;
const interval = setInterval(() => {
    current += 5;
    progress.update(current, `Processing item ${current}...`);

    if (current >= 100) {
        clearInterval(interval);
    }
}, 100);
```

## File Operations [#file-operations]

### File Tree Display [#file-tree-display]

```typescript
import { blue, green, yellow, gray } from "@visulima/colorize";

interface FileNode {
    name: string;
    type: "file" | "directory";
    children?: FileNode[];
}

function displayTree(node: FileNode, prefix: string = "", isLast: boolean = true) {
    const connector = isLast ? "└── " : "├── ";
    const color = node.type === "directory" ? blue.bold : green;
    const icon = node.type === "directory" ? "📁" : "📄";

    console.log(gray(prefix + connector) + icon + " " + color(node.name));

    if (node.children) {
        const childPrefix = prefix + (isLast ? "    " : "│   ");
        node.children.forEach((child, index) => {
            const isLastChild = index === node.children!.length - 1;
            displayTree(child, childPrefix, isLastChild);
        });
    }
}

// Usage
const tree: FileNode = {
    name: "project",
    type: "directory",
    children: [
        {
            name: "src",
            type: "directory",
            children: [
                { name: "index.ts", type: "file" },
                { name: "utils.ts", type: "file" },
            ],
        },
        { name: "package.json", type: "file" },
        { name: "README.md", type: "file" },
    ],
};

displayTree(tree);
```

### File Diff Display [#file-diff-display]

```typescript
import { green, red, gray } from "@visulima/colorize";

interface DiffLine {
    type: "add" | "remove" | "unchanged";
    content: string;
}

function displayDiff(lines: DiffLine[]) {
    lines.forEach((line) => {
        switch (line.type) {
            case "add":
                console.log(green(`+ ${line.content}`));
                break;
            case "remove":
                console.log(red(`- ${line.content}`));
                break;
            case "unchanged":
                console.log(gray(`  ${line.content}`));
                break;
        }
    });
}

// Usage
const diff: DiffLine[] = [
    { type: "unchanged", content: "function hello() {" },
    { type: "remove", content: '  console.log("Hello");' },
    { type: "add", content: '  console.log("Hello World");' },
    { type: "unchanged", content: "}" },
];

displayDiff(diff);
```

## Test Runners [#test-runners]

### Test Results Display [#test-results-display]

```typescript
import { green, red, yellow, gray, bold } from "@visulima/colorize";

interface TestResult {
    name: string;
    status: "pass" | "fail" | "skip";
    duration: number;
    error?: string;
}

interface TestSuite {
    name: string;
    tests: TestResult[];
}

function displayTestResults(suite: TestSuite) {
    console.log(bold(`\n${suite.name}`));

    suite.tests.forEach((test) => {
        const icon = test.status === "pass" ? green("✓") : test.status === "fail" ? red("✗") : yellow("○");

        const duration = gray(`(${test.duration}ms)`);

        console.log(`  ${icon} ${test.name} ${duration}`);

        if (test.error) {
            console.log(red(`    ${test.error}`));
        }
    });

    const passed = suite.tests.filter((t) => t.status === "pass").length;
    const failed = suite.tests.filter((t) => t.status === "fail").length;
    const skipped = suite.tests.filter((t) => t.status === "skip").length;

    console.log();
    console.log(bold("Summary:"));
    console.log(`  ${green(`Passed: ${passed}`)}`);
    if (failed > 0) console.log(`  ${red(`Failed: ${failed}`)}`);
    if (skipped > 0) console.log(`  ${yellow(`Skipped: ${skipped}`)}`);
}

// Usage
displayTestResults({
    name: "User Service Tests",
    tests: [
        { name: "should create user", status: "pass", duration: 45 },
        { name: "should validate email", status: "pass", duration: 12 },
        { name: "should reject invalid email", status: "fail", duration: 8, error: "Expected false but got true" },
        { name: "should update user", status: "skip", duration: 0 },
    ],
});
```

## Interactive Prompts [#interactive-prompts]

### Question Prompt [#question-prompt]

```typescript
import { cyan, green, yellow } from "@visulima/colorize";
import * as readline from "readline";

async function ask(question: string): Promise<string> {
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
    });

    return new Promise((resolve) => {
        rl.question(cyan(`? ${question} `), (answer) => {
            rl.close();
            resolve(answer);
        });
    });
}

async function confirm(question: string): Promise<boolean> {
    const answer = await ask(`${question} ${yellow("(y/n)")}`);
    return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
}

// Usage
async function runInteractive() {
    const name = await ask("What is your name?");
    console.log(green(`Hello, ${name}!`));

    const proceed = await confirm("Do you want to continue?");
    if (proceed) {
        console.log(green("Continuing..."));
    } else {
        console.log(yellow("Cancelled"));
    }
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/colorize/api">
    Complete API documentation
  </Card>

  <Card title="Troubleshooting" href="/docs/packages/colorize/troubleshooting">
    Common issues and solutions
  </Card>
</Cards>


# API Reference (/docs/packages/command-line-args/api)



# API Reference [#api-reference]

## Functions [#functions]

### `parseArgs(definitions, options?)` [#parseargsdefinitions-options]

Parse command-line arguments.

**Parameters:**

* `definitions` (OptionDefinition\[]): Option definitions
* `options` (ParseOptions, optional): Parsing options

**Returns:** Parsed options object

### `commandLineArgs(definitions, options?)` [#commandlineargsdefinitions-options]

Alias for `parseArgs()` (backward compatibility).

## Types [#types]

### `OptionDefinition` [#optiondefinition]

```typescript
interface OptionDefinition {
    name: string; // Option name
    alias?: string; // Short alias
    type?: TypeConstructor; // String, Number, Boolean
    defaultValue?: any; // Default value
    multiple?: boolean; // Allow multiple values
    defaultOption?: boolean; // Capture positional args
}
```

### `ParseOptions` [#parseoptions]

```typescript
interface ParseOptions {
    partial?: boolean; // Preserve unknown options
    stopAtFirstUnknown?: boolean; // Stop at unknown option
    camelCase?: boolean; // Convert to camelCase
    argv?: string[]; // Custom argv array
}
```

## Examples [#examples]

**Basic:**

```typescript
parseArgs([{ name: "file", type: String }]);
```

**With alias:**

```typescript
parseArgs([{ name: "verbose", alias: "v", type: Boolean }]);
```

**Multiple values:**

```typescript
parseArgs([{ name: "include", type: String, multiple: true }]);
```

**Default value:**

```typescript
parseArgs([{ name: "port", type: Number, defaultValue: 3000 }]);
```

**Positional:**

```typescript
parseArgs([{ name: "files", type: String, multiple: true, defaultOption: true }]);
```


# Introduction (/docs/packages/command-line-args)



# @visulima/command-line-args [#visulimacommand-line-args]

A mature, feature-complete library to parse command-line options with TypeScript support, automatic type conversion, and intuitive API.

## Key Features [#key-features]

* **Type-safe parsing** - Automatic conversion to String, Number, Boolean
* **Multiple values** - Array support for repeated options
* **Aliases** - Short (-v) and long (--verbose) option names
* **Default values** - Fallback values when options not provided
* **Positional arguments** - Capture non-option arguments
* **Flexible parsing** - Partial parsing, stop-early modes
* **TypeScript native** - Full type definitions included

## Quick Start [#quick-start]

```typescript
import { parseArgs } from "@visulima/command-line-args";

const options = parseArgs([
    { name: "file", alias: "f", type: String },
    { name: "verbose", alias: "v", type: Boolean },
    { name: "count", alias: "c", type: Number },
]);

// Usage: node script.js --file input.txt -v --count 5
console.log(options);
// { file: "input.txt", verbose: true, count: 5 }
```

## Use Cases [#use-cases]

**CLI Tools:** Build professional command-line interfaces
&#x2A;*Build Scripts:** Parse configuration flags
&#x2A;*Development Tools:** Create flexible dev tooling
&#x2A;*Automation:** Script with configurable parameters

<Cards>
  <Card title="Installation" href="/docs/packages/command-line-args/installation">
    Install and set up the package
  </Card>

  <Card title="Quick Start" href="/docs/packages/command-line-args/quick-start">
    Parse your first CLI arguments
  </Card>

  <Card title="Usage Guide" href="/docs/packages/command-line-args/usage">
    Explore all parsing features
  </Card>

  <Card title="API Reference" href="/docs/packages/command-line-args/api">
    Complete API documentation
  </Card>
</Cards>


# Installation (/docs/packages/command-line-args/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/command-line-args
```

## Import [#import]

```typescript
import { parseArgs } from "@visulima/command-line-args";
// or
import { commandLineArgs } from "@visulima/command-line-args";
```

## Verification [#verification]

```typescript
import { parseArgs } from "@visulima/command-line-args";

const options = parseArgs([{ name: "test", type: Boolean }]);

console.log("✓ Installation successful");
```


# Quick Start (/docs/packages/command-line-args/quick-start)



# Quick Start [#quick-start]

## Basic Parsing [#basic-parsing]

```typescript
import { parseArgs } from "@visulima/command-line-args";

const options = parseArgs([
    { name: "file", alias: "f", type: String },
    { name: "verbose", alias: "v", type: Boolean },
]);

// node script.js --file input.txt -v
// { file: "input.txt", verbose: true }
```

## With Types [#with-types]

```typescript
const options = parseArgs([
    { name: "count", type: Number },
    { name: "name", type: String },
    { name: "flag", type: Boolean },
]);

// node script.js --count 42 --name "Test" --flag
// { count: 42, name: "Test", flag: true }
```

## Multiple Values [#multiple-values]

```typescript
const options = parseArgs([{ name: "include", type: String, multiple: true }]);

// node script.js --include src --include lib
// { include: ["src", "lib"] }
```

## Default Values [#default-values]

```typescript
const options = parseArgs([{ name: "port", type: Number, defaultValue: 3000 }]);

// node script.js
// { port: 3000 }
```


# Usage Guide (/docs/packages/command-line-args/usage)



# Usage Guide [#usage-guide]

## Option Definitions [#option-definitions]

```typescript
import { parseArgs } from "@visulima/command-line-args";

const definitions = [
    {
        name: "file", // Long option: --file
        alias: "f", // Short option: -f
        type: String, // Type conversion
        defaultValue: "in.txt", // Default value
        multiple: false, // Single value (default)
    },
];

const options = parseArgs(definitions);
```

## Type Conversion [#type-conversion]

**String:**

```typescript
{ name: "file", type: String }
// --file input.txt → { file: "input.txt" }
```

**Number:**

```typescript
{ name: "count", type: Number }
// --count 42 → { count: 42 }
```

**Boolean:**

```typescript
{ name: "verbose", type: Boolean }
// --verbose → { verbose: true }
// (no flag) → { verbose: false }
```

## Multiple Values [#multiple-values]

```typescript
const options = parseArgs([{ name: "include", type: String, multiple: true }]);

// node script.js --include src --include lib --include test
// { include: ["src", "lib", "test"] }
```

## Default Option (Positional) [#default-option-positional]

```typescript
const options = parseArgs([{ name: "files", type: String, multiple: true, defaultOption: true }]);

// node script.js file1.txt file2.txt file3.txt
// { files: ["file1.txt", "file2.txt", "file3.txt"] }
```

## Partial Parsing [#partial-parsing]

```typescript
const options = parseArgs(definitions, { partial: true });
// Unknown options are preserved in _unknown array
```

## Stop Early [#stop-early]

```typescript
const options = parseArgs(definitions, { stopAtFirstUnknown: true });
// Stops parsing at first unknown option
```

## Camel Case [#camel-case]

```typescript
const options = parseArgs(definitions, { camelCase: true });
// --my-option becomes myOption
```

## Complete Example [#complete-example]

```typescript
import { parseArgs } from "@visulima/command-line-args";

const options = parseArgs([
    { name: "input", alias: "i", type: String, defaultValue: "stdin" },
    { name: "output", alias: "o", type: String, defaultValue: "stdout" },
    { name: "verbose", alias: "v", type: Boolean },
    { name: "port", alias: "p", type: Number, defaultValue: 3000 },
    { name: "include", type: String, multiple: true },
    { name: "files", type: String, multiple: true, defaultOption: true },
]);

// node script.js -i data.json -o result.json -v -p 8080 --include lib --include src file1.js file2.js
// Result:
// {
//   input: "data.json",
//   output: "result.json",
//   verbose: true,
//   port: 8080,
//   include: ["lib", "src"],
//   files: ["file1.js", "file2.js"]
// }
```


# API Reference (/docs/packages/content-safety/api)



# API Reference [#api-reference]

Complete TypeScript API documentation for @visulima/content-safety.

## Functions [#functions]

### checkBannedWords() [#checkbannedwords]

Checks text for banned words across all configured languages.

```typescript
function checkBannedWords(text: string): BannedWordsResult;
```

#### Parameters [#parameters]

* **text** (`string`) - The text to check for banned words. Can be any length, including empty strings.

#### Returns [#returns]

`BannedWordsResult` - Object containing:

* `hasBannedWords` (`boolean`) - Whether any banned words were found
* `matches` (`BannedWordMatch[]`) - Array of all matches with position information

#### Behavior [#behavior]

* **Case-insensitive**: Matches regardless of capitalization
* **Unicode-normalized**: Converts text to NFC form before checking
* **Multi-language**: Checks all 19 language dictionaries simultaneously
* **Word boundaries**: Respects word boundaries (except CJK scripts)
* **Empty input**: Returns empty result for empty or whitespace-only strings
* **Performance**: Uses pre-compiled regex (no first-call penalty)

#### Examples [#examples]

##### Basic Usage [#basic-usage]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

const result = checkBannedWords("Hello world");
console.log(result);
// {
//   hasBannedWords: false,
//   matches: []
// }
```

##### With Banned Words [#with-banned-words]

```typescript
const result = checkBannedWords("This contains badword");
console.log(result);
// {
//   hasBannedWords: true,
//   matches: [
//     {
//       word: "badword",
//       startIndex: 14,
//       endIndex: 21,
//       language: "en"
//     }
//   ]
// }
```

##### Censoring Text [#censoring-text]

```typescript
const text = "This contains badword";
const result = checkBannedWords(text);

if (result.hasBannedWords) {
    let censored = text;
    for (const match of [...result.matches].reverse()) {
        const replacement = "*".repeat(match.word.length);
        censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
    }
    console.log(censored); // "This contains *******"
}
```

##### Multi-Language Detection [#multi-language-detection]

```typescript
const result = checkBannedWords(`
  English bad word
  German bad word
  日本語 bad word
`);

result.matches.forEach((match) => {
    console.log(`${match.word} (${match.language})`);
});
```

##### Case Insensitivity [#case-insensitivity]

```typescript
checkBannedWords("BADWORD"); // detected
checkBannedWords("badword"); // detected
checkBannedWords("BaDwOrD"); // detected
```

## Types [#types]

### BannedWordsResult [#bannedwordsresult]

The result of checking text for banned words.

```typescript
interface BannedWordsResult {
    hasBannedWords: boolean;
    matches: BannedWordMatch[];
}
```

#### Properties [#properties]

* **hasBannedWords** (`boolean`)
  * `true` if one or more banned words were found
  * `false` otherwise
  * Convenience property to avoid checking `matches.length > 0`

* **matches** (`BannedWordMatch[]`)
  * Array of all matched banned words
  * Empty array `[]` when no matches found
  * Sorted by appearance order in text

#### Example [#example]

```typescript
const result: BannedWordsResult = {
    hasBannedWords: true,
    matches: [
        {
            word: "badword",
            startIndex: 0,
            endIndex: 7,
            language: "en",
        },
    ],
};
```

***

### BannedWordMatch [#bannedwordmatch]

Represents a single banned word match found in text.

```typescript
interface BannedWordMatch {
    word: string;
    startIndex: number;
    endIndex: number;
    language: string;
}
```

#### Properties [#properties-1]

* **word** (`string`)
  * The matched word or phrase exactly as it appears in the text
  * Preserves original capitalization from input text
  * Example: `"BADWORD"`, `"badword"`, `"BaDwOrD"`

* **startIndex** (`number`)
  * Zero-based start index in the original text
  * Inclusive (points to first character of match)
  * Example: For `"hello badword world"`, startIndex = 6

* **endIndex** (`number`)
  * Zero-based end index in the original text
  * Exclusive (points to character after match)
  * Example: For `"hello badword world"`, endIndex = 13
  * Use for slicing: `text.slice(startIndex, endIndex)`

* **language** (`string`)
  * ISO 639-1 language code (2 letters)
  * Indicates which dictionary the word was matched from
  * Examples: `"en"`, `"de"`, `"ja"`
  * If a word appears in multiple languages, first one alphabetically is used

#### Example [#example-1]

```typescript
const match: BannedWordMatch = {
    word: "badword",
    startIndex: 10,
    endIndex: 17,
    language: "en",
};

// Extract matched text
const text = "This is a badword in text";
const extracted = text.slice(match.startIndex, match.endIndex);
console.log(extracted); // "badword"
```

## Constants [#constants]

### BANNED\_WORDS [#banned_words]

Comprehensive banned words dictionary organized by language code.

```typescript
const BANNED_WORDS: Record<string, readonly string[]>;
```

#### Structure [#structure]

Object where:

* **Keys**: ISO 639-1 language codes (`string`)
* **Values**: Read-only arrays of banned words (`readonly string[]`)

#### Supported Languages [#supported-languages]

* `ar` - Arabic
* `az` - Azerbaijani
* `de` - German
* `en` - English
* `es` - Spanish
* `fa` - Persian/Farsi
* `fr` - French
* `ga` - Irish
* `hi` - Hindi
* `it` - Italian
* `ja` - Japanese
* `ko` - Korean
* `nl` - Dutch
* `pl` - Polish
* `pt` - Portuguese
* `ru` - Russian
* `sv` - Swedish
* `tr` - Turkish
* `zh` - Chinese

#### Examples [#examples-1]

##### View Available Languages [#view-available-languages]

```typescript
import { BANNED_WORDS } from "@visulima/content-safety";

console.log(Object.keys(BANNED_WORDS));
// ['ar', 'az', 'de', 'en', 'es', 'fa', 'fr', 'ga', 'hi', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh']
```

##### Check Word Count [#check-word-count]

```typescript
console.log(BANNED_WORDS.en.length); // Number of English banned words
console.log(BANNED_WORDS.ja.length); // Number of Japanese banned words
```

##### Check if Word is Banned [#check-if-word-is-banned]

```typescript
const word = "badword";
const isBanned = Object.values(BANNED_WORDS)
    .flat()
    .some((w) => w.toLowerCase() === word.toLowerCase());

console.log(isBanned); // true or false
```

##### Custom Filtering [#custom-filtering]

```typescript
// Get all English words starting with 'a'
const enWordsStartingWithA = BANNED_WORDS.en.filter((w) => w.startsWith("a"));

// Count total words across all languages
const totalWords = Object.values(BANNED_WORDS).reduce((sum, words) => sum + words.length, 0);
```

#### Notes [#notes]

* **Read-only**: Arrays are marked as `readonly` to prevent modification
* **Lowercase**: Most words are stored in lowercase
* **Multi-word phrases**: Some entries contain spaces (e.g., "white trash")
* **Variants**: Includes leet-speak and common variations
* **Not customizable at runtime**: Word lists are compiled at build time

## Usage Patterns [#usage-patterns]

### Pattern: Simple Validation [#pattern-simple-validation]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

function isClean(text: string): boolean {
    return !checkBannedWords(text).hasBannedWords;
}
```

### Pattern: Detailed Validation [#pattern-detailed-validation]

```typescript
import { checkBannedWords, type BannedWordsResult } from "@visulima/content-safety";

interface ValidationResult {
    valid: boolean;
    errors: string[];
    bannedWords?: number;
}

function validateContent(text: string): ValidationResult {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return { valid: true, errors: [] };
    }

    return {
        valid: false,
        errors: ["Content contains inappropriate language"],
        bannedWords: result.matches.length,
    };
}
```

### Pattern: Text Censoring [#pattern-text-censoring]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

function censorText(text: string): string {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return text;
    }

    let censored = text;
    for (const match of [...result.matches].reverse()) {
        const replacement = "*".repeat(match.word.length);
        censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
    }

    return censored;
}
```

### Pattern: Highlighting [#pattern-highlighting]

```typescript
import { checkBannedWords, type BannedWordMatch } from "@visulima/content-safety";

interface TextSegment {
    text: string;
    banned: boolean;
    language?: string;
}

function segmentText(text: string): TextSegment[] {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return [{ text, banned: false }];
    }

    const segments: TextSegment[] = [];
    let lastIndex = 0;

    for (const match of result.matches) {
        // Clean text before match
        if (match.startIndex > lastIndex) {
            segments.push({
                text: text.slice(lastIndex, match.startIndex),
                banned: false,
            });
        }

        // Banned word
        segments.push({
            text: match.word,
            banned: true,
            language: match.language,
        });

        lastIndex = match.endIndex;
    }

    // Remaining text
    if (lastIndex < text.length) {
        segments.push({
            text: text.slice(lastIndex),
            banned: false,
        });
    }

    return segments;
}
```

### Pattern: Analytics [#pattern-analytics]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

interface ContentAnalysis {
    text: string;
    clean: boolean;
    bannedWordCount: number;
    languagesDetected: string[];
    severity: "none" | "low" | "medium" | "high";
}

function analyzeContent(text: string): ContentAnalysis {
    const result = checkBannedWords(text);

    const languages = [...new Set(result.matches.map((m) => m.language))];
    const count = result.matches.length;

    let severity: "none" | "low" | "medium" | "high" = "none";
    if (count > 0) severity = "low";
    if (count > 3) severity = "medium";
    if (count > 10) severity = "high";

    return {
        text,
        clean: !result.hasBannedWords,
        bannedWordCount: count,
        languagesDetected: languages,
        severity,
    };
}
```

## TypeScript Support [#typescript-support]

The library is fully typed with TypeScript:

```typescript
import type { BannedWordMatch, BannedWordsResult } from "@visulima/content-safety";

// Type-safe function signatures
function handleResult(result: BannedWordsResult): void {
    // TypeScript knows the exact shape
    result.hasBannedWords; // boolean
    result.matches; // BannedWordMatch[]
}

// Type-safe match handling
function handleMatch(match: BannedWordMatch): void {
    match.word; // string
    match.startIndex; // number
    match.endIndex; // number
    match.language; // string
}
```

## Browser and Runtime Support [#browser-and-runtime-support]

The library works in all modern JavaScript environments:

* Node.js 18+
* Browsers (ES2020+)
* Deno
* Bun
* Edge Functions (Vercel, Cloudflare Workers)
* React Native
* Electron

No polyfills required.

## Next Steps [#next-steps]

* [Usage Guide](/docs/packages/content-safety/usage) - Detailed usage examples
* [Supported Languages](/docs/packages/content-safety/languages) - View language coverage
* [Installation](/docs/packages/content-safety/installation) - Setup instructions
* [GitHub Repository](https://github.com/visulima/visulima) - Source code and issues


# Getting Started (/docs/packages/content-safety)



# Getting Started [#getting-started]

@visulima/content-safety is a robust TypeScript library for detecting banned words, profanity, slurs, hate speech, and inappropriate content across multiple languages. It provides accurate, Unicode-aware text analysis with position information for censoring or highlighting.

## Key Features [#key-features]

### Multi-Language Support [#multi-language-support]

Comprehensive banned word detection across **19 languages**:

* **European**: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese, Swedish, Russian, Irish
* **Middle Eastern**: Arabic, Persian/Farsi, Turkish, Azerbaijani
* **Asian**: Japanese, Korean, Chinese, Hindi

### Unicode-Aware [#unicode-aware]

Full support for international scripts and complex text:

* **CJK Scripts**: Japanese, Korean, Chinese (no word boundaries required)
* **RTL Scripts**: Arabic, Persian, Hebrew
* **Complex Scripts**: Devanagari (Hindi), Thai, and others
* **Unicode Normalization**: Consistent matching with NFC normalization

### High Performance [#high-performance]

Optimized for production use:

* **Eager Regex Compilation**: Cache built at module load (no first-call lag)
* **Single Pass Checking**: All languages checked simultaneously
* **Efficient Pattern Matching**: Longest phrases matched first

### Precise Position Tracking [#precise-position-tracking]

Detailed match information for flexible handling:

* Start and end indices for each match
* Language attribution (which dictionary matched)
* Support for highlighting, censoring, or rejection

### Advanced Features [#advanced-features]

* **Case-Insensitive**: Matches regardless of capitalization
* **Multi-Word Phrases**: Detects compound expressions (e.g., "white trash")
* **Leet-Speak Detection**: Includes common variants (e.g., "b1tch")
* **Word Boundary Aware**: Prevents false positives in compound words
* **Zero Dependencies**: Pure TypeScript, works in browser and Node.js

## Quick Start [#quick-start]

### Installation [#installation]

```bash
npm install @visulima/content-safety
```

```bash
yarn add @visulima/content-safety
```

```bash
pnpm add @visulima/content-safety
```

### Basic Usage [#basic-usage]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

// Check clean text
const result = checkBannedWords("Hello, how are you today?");
console.log(result.hasBannedWords); // false
console.log(result.matches); // []

// Check text with banned words
const result2 = checkBannedWords("This contains badword");
console.log(result2.hasBannedWords); // true
console.log(result2.matches[0]);
// {
//   word: "badword",
//   startIndex: 14,
//   endIndex: 21,
//   language: "en"
// }
```

## Use Cases [#use-cases]

### Content Moderation [#content-moderation]

Filter user-generated content in forums, comments, and chat applications:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

function moderateContent(userInput: string) {
    const result = checkBannedWords(userInput);

    if (result.hasBannedWords) {
        return {
            allowed: false,
            reason: `Content contains ${result.matches.length} inappropriate word(s)`,
        };
    }

    return { allowed: true };
}
```

### Text Censoring [#text-censoring]

Automatically censor inappropriate content:

```typescript
function censorText(text: string): string {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return text;
    }

    let censored = text;
    // Process in reverse to maintain indices
    for (const match of result.matches.reverse()) {
        const replacement = "*".repeat(match.word.length);
        censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
    }

    return censored;
}
```

### Real-Time Validation [#real-time-validation]

Provide instant feedback in forms and text editors:

```typescript
function validateInput(text: string) {
    const result = checkBannedWords(text);

    return {
        isValid: !result.hasBannedWords,
        matches: result.matches.map((m) => ({
            position: m.startIndex,
            length: m.word.length,
            language: m.language,
        })),
    };
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/content-safety/installation">
    Detailed installation and setup instructions
  </Card>

  <Card title="Usage Guide" href="/docs/packages/content-safety/usage">
    Learn how to use the library with examples
  </Card>

  <Card title="Supported Languages" href="/docs/packages/content-safety/languages">
    View all supported languages and word lists
  </Card>

  <Card title="API Reference" href="/docs/packages/content-safety/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

Works in all modern environments:

* Node.js 18+
* Browsers (Chrome, Firefox, Safari, Edge)
* Deno
* Bun
* Edge Functions (Vercel, Cloudflare Workers)
* React Native
* Electron


# Installation (/docs/packages/content-safety/installation)



# Installation [#installation]

## Package Managers [#package-managers]

Install @visulima/content-safety using your preferred package manager:

### npm [#npm]

```bash
npm install @visulima/content-safety
```

### yarn [#yarn]

```bash
yarn add @visulima/content-safety
```

### pnpm [#pnpm]

```bash
pnpm add @visulima/content-safety
```

### bun [#bun]

```bash
bun add @visulima/content-safety
```

## Requirements [#requirements]

### Runtime Support [#runtime-support]

@visulima/content-safety works in all modern JavaScript environments:

* **Node.js**: 18.x or higher
* **Browsers**: All modern browsers with ES2020+ support
  * Chrome 80+
  * Firefox 72+
  * Safari 14+
  * Edge 80+
* **Deno**: 1.x or higher
* **Bun**: 1.x or higher

### TypeScript Support [#typescript-support]

The library is written in TypeScript and includes full type definitions:

* **TypeScript**: 5.0 or higher (recommended)
* Types are included in the package (no separate @types package needed)

## Import Methods [#import-methods]

### ES Modules (Recommended) [#es-modules-recommended]

```typescript
import { checkBannedWords, BANNED_WORDS } from "@visulima/content-safety";
import type { BannedWordMatch, BannedWordsResult } from "@visulima/content-safety";
```

### CommonJS [#commonjs]

```javascript
const { checkBannedWords, BANNED_WORDS } = require("@visulima/content-safety");
```

### Named Imports [#named-imports]

Import only what you need for optimal tree-shaking:

```typescript
// Import just the checker function
import { checkBannedWords } from "@visulima/content-safety";

// Import just the word list
import { BANNED_WORDS } from "@visulima/content-safety";

// Import types
import type { BannedWordMatch, BannedWordsResult } from "@visulima/content-safety";
```

## Verification [#verification]

Verify your installation by running a simple check:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

const result = checkBannedWords("Hello world");
console.log(result);
// { hasBannedWords: false, matches: [] }
```

## Build Tools [#build-tools]

### Webpack [#webpack]

Works out of the box with Webpack 5:

```javascript
// No special configuration needed
import { checkBannedWords } from "@visulima/content-safety";
```

### Vite [#vite]

Works seamlessly with Vite:

```typescript
import { checkBannedWords } from "@visulima/content-safety";
```

### Rollup [#rollup]

Compatible with Rollup:

```javascript
import { checkBannedWords } from "@visulima/content-safety";
```

### esbuild [#esbuild]

Works with esbuild:

```typescript
import { checkBannedWords } from "@visulima/content-safety";
```

## Framework Integration [#framework-integration]

### React [#react]

```tsx
import { useState } from "react";
import { checkBannedWords } from "@visulima/content-safety";

function CommentForm() {
    const [text, setText] = useState("");
    const [error, setError] = useState("");

    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
        const value = e.target.value;
        setText(value);

        const result = checkBannedWords(value);
        if (result.hasBannedWords) {
            setError("Content contains inappropriate language");
        } else {
            setError("");
        }
    };

    return (
        <div>
            <textarea value={text} onChange={handleChange} />
            {error && <p className="error">{error}</p>}
        </div>
    );
}
```

### Vue [#vue]

```vue
<script setup lang="ts">
import { ref, computed } from "vue";
import { checkBannedWords } from "@visulima/content-safety";

const text = ref("");

const result = computed(() => checkBannedWords(text.value));
const hasError = computed(() => result.value.hasBannedWords);
</script>

<template>
    <div>
        <textarea v-model="text" />
        <p v-if="hasError" class="error">Content contains inappropriate language</p>
    </div>
</template>
```

### Next.js [#nextjs]

Works in both client and server components:

```typescript
// app/api/moderate/route.ts
import { checkBannedWords } from "@visulima/content-safety";

export async function POST(request: Request) {
    const { text } = await request.json();
    const result = checkBannedWords(text);

    return Response.json({
        allowed: !result.hasBannedWords,
        matches: result.matches,
    });
}
```

### Svelte [#svelte]

```svelte
<script lang="ts">
  import { checkBannedWords } from '@visulima/content-safety';

  let text = '';

  $: result = checkBannedWords(text);
  $: hasError = result.hasBannedWords;
</script>

<textarea bind:value={text} />
{#if hasError}
  <p class="error">Content contains inappropriate language</p>
{/if}
```

## Edge Runtime Support [#edge-runtime-support]

### Vercel Edge Functions [#vercel-edge-functions]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

export const config = {
    runtime: "edge",
};

export default async function handler(request: Request) {
    const { text } = await request.json();
    const result = checkBannedWords(text);

    return new Response(JSON.stringify(result), {
        headers: { "content-type": "application/json" },
    });
}
```

### Cloudflare Workers [#cloudflare-workers]

```typescript
import { checkBannedWords } from "@visulima/content-safety";

export default {
    async fetch(request: Request) {
        const { text } = await request.json();
        const result = checkBannedWords(text);

        return new Response(JSON.stringify(result), {
            headers: { "content-type": "application/json" },
        });
    },
};
```

## Troubleshooting [#troubleshooting]

### Module Not Found [#module-not-found]

If you encounter module resolution issues:

1. Clear your package manager cache:

   ```bash
   npm cache clean --force
   # or
   yarn cache clean
   # or
   pnpm store prune
   ```

2. Delete `node_modules` and reinstall:
   ```bash
   rm -rf node_modules
   npm install
   ```

### TypeScript Errors [#typescript-errors]

If TypeScript can't find types:

1. Ensure `moduleResolution` is set to `"bundler"` or `"node16"` in `tsconfig.json`:

   ```json
   {
       "compilerOptions": {
           "moduleResolution": "bundler"
       }
   }
   ```

2. Check that your TypeScript version is 5.0+:
   ```bash
   npx tsc --version
   ```

### Build Errors [#build-errors]

If you encounter build errors in older browsers:

1. Ensure your bundler is configured to transpile `node_modules`:
   ```javascript
   // vite.config.js
   export default {
       build: {
           target: "es2020",
       },
   };
   ```

## Next Steps [#next-steps]

* [Usage Guide](/docs/packages/content-safety/usage) - Learn how to use the library
* [API Reference](/docs/packages/content-safety/api) - Detailed API documentation
* [Supported Languages](/docs/packages/content-safety/languages) - View language support


# Supported Languages (/docs/packages/content-safety/languages)



# Supported Languages [#supported-languages]

@visulima/content-safety includes banned word lists for **19 languages**, covering major languages from around the world. All languages are checked simultaneously when analyzing text.

## Language Coverage [#language-coverage]

### European Languages [#european-languages]

#### English (en) [#english-en]

* **Script**: Latin
* **Coverage**: Comprehensive profanity, slurs, hate speech
* **Variants**: Includes leet-speak (b1tch, etc.)
* **Multi-word phrases**: Yes (e.g., "white trash")

#### German (de) [#german-de]

* **Script**: Latin (with umlauts)
* **Coverage**: German profanity and slurs
* **Regional variants**: Standard German

#### Spanish (es) [#spanish-es]

* **Script**: Latin (with diacritics)
* **Coverage**: Spanish profanity and slurs
* **Regional variants**: Multiple Spanish-speaking regions

#### French (fr) [#french-fr]

* **Script**: Latin (with diacritics)
* **Coverage**: French profanity and slurs
* **Regional variants**: European French

#### Italian (it) [#italian-it]

* **Script**: Latin
* **Coverage**: Italian profanity and slurs

#### Dutch (nl) [#dutch-nl]

* **Script**: Latin
* **Coverage**: Dutch profanity and slurs

#### Polish (pl) [#polish-pl]

* **Script**: Latin (with Polish diacritics)
* **Coverage**: Polish profanity and slurs

#### Portuguese (pt) [#portuguese-pt]

* **Script**: Latin (with diacritics)
* **Coverage**: Portuguese profanity and slurs
* **Regional variants**: Both European and Brazilian Portuguese

#### Swedish (sv) [#swedish-sv]

* **Script**: Latin (with Swedish characters)
* **Coverage**: Swedish profanity and slurs

#### Russian (ru) [#russian-ru]

* **Script**: Cyrillic
* **Coverage**: Russian profanity and slurs
* **Unicode support**: Full Cyrillic character handling

#### Irish (ga) [#irish-ga]

* **Script**: Latin
* **Coverage**: Irish profanity and slurs

### Middle Eastern Languages [#middle-eastern-languages]

#### Arabic (ar) [#arabic-ar]

* **Script**: Arabic (RTL)
* **Coverage**: Arabic profanity and slurs
* **Script features**: Right-to-left text support
* **Regional variants**: Modern Standard Arabic

#### Persian/Farsi (fa) [#persianfarsi-fa]

* **Script**: Perso-Arabic (RTL)
* **Coverage**: Persian profanity and slurs
* **Script features**: Right-to-left text support

#### Turkish (tr) [#turkish-tr]

* **Script**: Latin (with Turkish-specific letters)
* **Coverage**: Turkish profanity and slurs

#### Azerbaijani (az) [#azerbaijani-az]

* **Script**: Latin
* **Coverage**: Azerbaijani profanity and slurs

### Asian Languages [#asian-languages]

#### Japanese (ja) [#japanese-ja]

* **Script**: Mixed (Hiragana, Katakana, Kanji)
* **Coverage**: Japanese profanity and slurs
* **Word boundaries**: No word boundaries (CJK handling)

#### Korean (ko) [#korean-ko]

* **Script**: Hangul
* **Coverage**: Korean profanity and slurs
* **Word boundaries**: No word boundaries (CJK handling)

#### Chinese (zh) [#chinese-zh]

* **Script**: Simplified and Traditional Chinese
* **Coverage**: Chinese profanity and slurs
* **Word boundaries**: No word boundaries (CJK handling)

#### Hindi (hi) [#hindi-hi]

* **Script**: Devanagari
* **Coverage**: Hindi profanity and slurs
* **Script features**: Complex script support

## Language Detection [#language-detection]

### Automatic Multi-Language Checking [#automatic-multi-language-checking]

The library automatically checks all languages simultaneously:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

// Mixed language text - all languages checked
const result = checkBannedWords(`
  English bad word
  German bad word
  Japanese bad word
`);

// All languages will be detected
console.log(result.matches.map((m) => m.language));
// ['en', 'de', 'ja']
```

### Language Attribution [#language-attribution]

Each match includes the language code it was detected from:

```typescript
const result = checkBannedWords("text with badword");

result.matches.forEach((match) => {
    console.log(`Found "${match.word}" from language: ${match.language}`);
});
```

## Script Support [#script-support]

### Latin Scripts [#latin-scripts]

Standard Latin alphabet with full diacritic support:

* English, Spanish, French, Portuguese, etc.
* Accents: é, ñ, ü, ø, etc.

### Cyrillic [#cyrillic]

Full support for Cyrillic script:

* Russian (Ru): А-Я, а-я
* Unicode-aware word boundaries

### Arabic Script [#arabic-script]

Right-to-left (RTL) text support:

* Arabic (ar): ا-ي
* Persian (fa): Perso-Arabic extensions
* Proper handling of RTL text direction

### CJK (Chinese, Japanese, Korean) [#cjk-chinese-japanese-korean]

Special handling for CJK scripts:

* No word boundaries required (continuous text)
* Character-level matching
* Support for mixed Hiragana, Katakana, Kanji, Hangul

### Complex Scripts [#complex-scripts]

Support for complex scripts with combining characters:

* Devanagari (Hindi)
* Thai
* Other Indic scripts

## Unicode Normalization [#unicode-normalization]

All text is normalized to NFC (Canonical Composition) form for consistent matching:

```typescript
// Both forms will match identically
checkBannedWords("café"); // NFC form
checkBannedWords("café"); // NFD form (combining accent)
```

This ensures:

* Consistent matching across different Unicode representations
* Proper handling of accented characters
* Correct detection regardless of input normalization

## Word Boundary Handling [#word-boundary-handling]

### Western Scripts (Latin, Cyrillic, Arabic, etc.) [#western-scripts-latin-cyrillic-arabic-etc]

Uses Unicode-aware word boundaries:

* `\p{L}` - Unicode letter property
* `\p{N}` - Unicode number property
* Respects word boundaries in all scripts

```typescript
// Matches (standalone word)
checkBannedWords("badword here"); // ✓ detected

// May not match (part of compound word)
checkBannedWords("notabadwordhere"); // depends on word list
```

### CJK Scripts [#cjk-scripts]

No word boundaries applied:

* Characters can appear anywhere in continuous text
* More sensitive matching for CJK content

```typescript
// CJK example
checkBannedWords("前badword後"); // ✓ detected
```

## Data Sources [#data-sources]

The banned word lists are curated from multiple sources:

* **Manual curation**: Carefully reviewed lists
* [google-profanity-words](https://github.com/coffee-and-fun/google-profanity-words): Community-maintained lists
* [safetext](https://github.com/viddexa/safetext): Multi-language profanity database

## Adding Custom Words [#adding-custom-words]

While the library doesn't support runtime customization, you can access the word lists:

```typescript
import { BANNED_WORDS } from "@visulima/content-safety";

// View all languages
console.log(Object.keys(BANNED_WORDS));
// ['ar', 'az', 'de', 'en', 'es', 'fa', 'fr', 'ga', 'hi', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh']

// View English words (sensitive content - be careful)
console.log(BANNED_WORDS.en);
```

## Language Codes (ISO 639-1) [#language-codes-iso-639-1]

| Code | Language    | Native Name  |
| ---- | ----------- | ------------ |
| ar   | Arabic      | العربية      |
| az   | Azerbaijani | Azərbaycanca |
| de   | German      | Deutsch      |
| en   | English     | English      |
| es   | Spanish     | Español      |
| fa   | Persian     | فارسی        |
| fr   | French      | Français     |
| ga   | Irish       | Gaeilge      |
| hi   | Hindi       | हिन्दी       |
| it   | Italian     | Italiano     |
| ja   | Japanese    | 日本語          |
| ko   | Korean      | 한국어          |
| nl   | Dutch       | Nederlands   |
| pl   | Polish      | Polski       |
| pt   | Portuguese  | Português    |
| ru   | Russian     | Русский      |
| sv   | Swedish     | Svenska      |
| tr   | Turkish     | Türkçe       |
| zh   | Chinese     | 中文           |

## Contributing Languages [#contributing-languages]

To add support for additional languages:

1. Create a new file: `src/words/{language-code}.ts`
2. Export an array of banned words:
   ```typescript
   const words: readonly string[] = [
       // word list here
   ];
   export default words;
   ```
3. Add to `src/banned-words.ts`:
   ```typescript
   import newLang from "./words/new-lang";
   export const BANNED_WORDS = {
       // ...
       "new-lang": newLang,
   };
   ```
4. Submit a pull request to [visulima/visulima](https://github.com/visulima/visulima)

## Next Steps [#next-steps]

* [Usage Guide](/docs/packages/content-safety/usage) - Learn how to use the library
* [API Reference](/docs/packages/content-safety/api) - Complete API documentation
* [Installation](/docs/packages/content-safety/installation) - Setup instructions


# Usage Guide (/docs/packages/content-safety/usage)



# Usage Guide [#usage-guide]

## Basic Checking [#basic-checking]

The primary function is `checkBannedWords()`, which analyzes text and returns detailed match information:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

const result = checkBannedWords("Your text here");

console.log(result.hasBannedWords); // boolean
console.log(result.matches); // BannedWordMatch[]
```

### Clean Text [#clean-text]

When text contains no banned words:

```typescript
const result = checkBannedWords("Hello, how are you today?");

console.log(result);
// {
//   hasBannedWords: false,
//   matches: []
// }
```

### Text with Banned Words [#text-with-banned-words]

When banned words are detected:

```typescript
const result = checkBannedWords("This contains badword");

console.log(result);
// {
//   hasBannedWords: true,
//   matches: [
//     {
//       word: "badword",
//       startIndex: 14,
//       endIndex: 21,
//       language: "en"
//     }
//   ]
// }
```

## Content Moderation [#content-moderation]

### Simple Rejection [#simple-rejection]

Reject content containing banned words:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

function moderateContent(userInput: string): { allowed: boolean; reason?: string } {
    const result = checkBannedWords(userInput);

    if (result.hasBannedWords) {
        return {
            allowed: false,
            reason: "Content contains inappropriate language",
        };
    }

    return { allowed: true };
}

// Usage
const submission = moderateContent("User's message here");
if (!submission.allowed) {
    console.log(submission.reason);
}
```

### Detailed Feedback [#detailed-feedback]

Provide specific feedback about violations:

```typescript
function moderateWithDetails(text: string) {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return { allowed: true };
    }

    return {
        allowed: false,
        reason: `Found ${result.matches.length} inappropriate word(s)`,
        matches: result.matches.map((m) => ({
            position: m.startIndex,
            word: m.word,
            language: m.language,
        })),
    };
}
```

### Multi-Language Support [#multi-language-support]

The library automatically checks all languages simultaneously:

```typescript
// English
checkBannedWords("bad English word"); // detected

// German
checkBannedWords("bad German word"); // detected

// Japanese
checkBannedWords("bad Japanese word"); // detected

// Mixed languages in same text
checkBannedWords("English bad word and German bad word"); // both detected
```

## Text Censoring [#text-censoring]

### Replace with Asterisks [#replace-with-asterisks]

Replace banned words with asterisks:

```typescript
import { checkBannedWords } from "@visulima/content-safety";

function censorText(text: string): string {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return text;
    }

    let censored = text;

    // Process matches in reverse order to maintain indices
    for (const match of [...result.matches].reverse()) {
        const replacement = "*".repeat(match.word.length);
        censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
    }

    return censored;
}

// Usage
console.log(censorText("This is badword text"));
// "This is ******* text"
```

### Replace with \[CENSORED] [#replace-with-censored]

Replace banned words with a placeholder:

```typescript
function censorWithPlaceholder(text: string): string {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return text;
    }

    let censored = text;
    let offset = 0;

    for (const match of result.matches) {
        const before = censored.slice(0, match.startIndex + offset);
        const after = censored.slice(match.endIndex + offset);
        censored = before + "[CENSORED]" + after;

        // Adjust offset for length difference
        offset += "[CENSORED]".length - match.word.length;
    }

    return censored;
}

// Usage
console.log(censorWithPlaceholder("This badword is bad"));
// "This [CENSORED] is bad"
```

### Partial Censoring [#partial-censoring]

Censor only the middle characters:

```typescript
function partialCensor(text: string): string {
    const result = checkBannedWords(text);

    if (!result.hasBannedWords) {
        return text;
    }

    let censored = text;

    for (const match of [...result.matches].reverse()) {
        const word = match.word;
        if (word.length <= 2) {
            // Fully censor short words
            const replacement = "*".repeat(word.length);
            censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
        } else {
            // Keep first and last character
            const replacement = word[0] + "*".repeat(word.length - 2) + word[word.length - 1];
            censored = censored.slice(0, match.startIndex) + replacement + censored.slice(match.endIndex);
        }
    }

    return censored;
}

// Usage
console.log(partialCensor("This badword is bad"));
// "This b*****d is bad"
```

## Real-Time Validation [#real-time-validation]

### Form Validation [#form-validation]

Validate input as the user types:

```typescript
function validateInput(text: string) {
    const result = checkBannedWords(text);

    return {
        isValid: !result.hasBannedWords,
        errors: result.hasBannedWords ? ["Content contains inappropriate language"] : [],
        matches: result.matches,
    };
}

// Usage in a form handler
const validation = validateInput(formData.comment);
if (!validation.isValid) {
    showErrors(validation.errors);
}
```

### Highlighting Matches [#highlighting-matches]

Create UI highlighting for banned words:

```typescript
interface HighlightSegment {
  text: string;
  isBanned: boolean;
  language?: string;
}

function highlightBannedWords(text: string): HighlightSegment[] {
  const result = checkBannedWords(text);

  if (!result.hasBannedWords) {
    return [{ text, isBanned: false }];
  }

  const segments: HighlightSegment[] = [];
  let lastIndex = 0;

  for (const match of result.matches) {
    // Add clean text before match
    if (match.startIndex > lastIndex) {
      segments.push({
        text: text.slice(lastIndex, match.startIndex),
        isBanned: false
      });
    }

    // Add banned word
    segments.push({
      text: match.word,
      isBanned: true,
      language: match.language
    });

    lastIndex = match.endIndex;
  }

  // Add remaining clean text
  if (lastIndex < text.length) {
    segments.push({
      text: text.slice(lastIndex),
      isBanned: false
    });
  }

  return segments;
}

// Usage in React
function TextHighlighter({ text }: { text: string }) {
  const segments = highlightBannedWords(text);

  return (
    <div>
      {segments.map((segment, i) => (
        <span
          key={i}
          className={segment.isBanned ? "banned" : ""}
          title={segment.language}
        >
          {segment.text}
        </span>
      ))}
    </div>
  );
}
```

## Advanced Use Cases [#advanced-use-cases]

### Character Count for Moderation [#character-count-for-moderation]

Count banned words by language:

```typescript
function analyzeContent(text: string) {
    const result = checkBannedWords(text);

    const byLanguage = result.matches.reduce(
        (acc, match) => {
            acc[match.language] = (acc[match.language] || 0) + 1;
            return acc;
        },
        {} as Record<string, number>,
    );

    return {
        totalBanned: result.matches.length,
        byLanguage,
        severity: result.matches.length > 5 ? "high" : "low",
    };
}

// Usage
const analysis = analyzeContent(userPost);
console.log(analysis);
// {
//   totalBanned: 3,
//   byLanguage: { en: 2, de: 1 },
//   severity: "low"
// }
```

### Logging and Analytics [#logging-and-analytics]

Track banned word usage for analytics:

```typescript
function logBannedWords(userId: string, text: string) {
    const result = checkBannedWords(text);

    if (result.hasBannedWords) {
        result.matches.forEach((match) => {
            analytics.track("banned_word_detected", {
                userId,
                word: match.word, // Consider hashing for privacy
                language: match.language,
                timestamp: new Date().toISOString(),
            });
        });
    }

    return result;
}
```

### Custom Word Lists [#custom-word-lists]

Access the banned words dictionary directly:

```typescript
import { BANNED_WORDS } from "@visulima/content-safety";

// See available languages
console.log(Object.keys(BANNED_WORDS));
// ['ar', 'az', 'de', 'en', 'es', ...]

// Check English word count
console.log(BANNED_WORDS.en.length);

// Check if a specific word is banned (case-sensitive)
const word = "badword";
const isBanned = Object.values(BANNED_WORDS)
    .flat()
    .some((w) => w.toLowerCase() === word.toLowerCase());
```

## Edge Cases [#edge-cases]

### Empty or Whitespace [#empty-or-whitespace]

Empty strings and whitespace-only strings return no matches:

```typescript
checkBannedWords(""); // { hasBannedWords: false, matches: [] }
checkBannedWords("   "); // { hasBannedWords: false, matches: [] }
checkBannedWords("\n\t"); // { hasBannedWords: false, matches: [] }
```

### Case Sensitivity [#case-sensitivity]

The checker is case-insensitive:

```typescript
checkBannedWords("BADWORD"); // detected
checkBannedWords("badword"); // detected
checkBannedWords("BaDwOrD"); // detected
```

### Unicode Normalization [#unicode-normalization]

Text is normalized to NFC form for consistent matching:

```typescript
// Different Unicode representations of the same text
checkBannedWords("café"); // NFC form
checkBannedWords("café"); // NFD form (combining accent)
// Both will match identically
```

### Word Boundaries [#word-boundaries]

The checker respects word boundaries (except for CJK scripts):

```typescript
// Matches (standalone word)
checkBannedWords("badword here"); // detected

// May not match (part of larger word, depends on word list)
checkBannedWords("goodbadwordhere"); // depends on word boundaries
```

## Next Steps [#next-steps]

* [API Reference](/docs/packages/content-safety/api) - Complete API documentation
* [Supported Languages](/docs/packages/content-safety/languages) - View all language support
* [GitHub Issues](https://github.com/visulima/visulima/issues) - Report bugs or request features


# API Reference (/docs/packages/deep-clone/api)



# API Reference [#api-reference]

Complete reference for all functions and types in the `@visulima/deep-clone` package.

## Main Function [#main-function]

### deepClone [#deepclone]

Creates a deep clone of the input data with circular reference handling.

**Signature:**

```typescript
function deepClone<T>(originalData: T, options?: Options): DeepReadwrite<T>;
```

**Type Parameters:**

* `T` - The type of the original data

**Parameters:**

* `originalData` (`T`, required) - The data to clone (any type)
* `options` (`Options`, optional) - Cloning configuration options

**Returns:** `DeepReadwrite<T>` - A deep cloned copy with readonly modifiers removed

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    name: "Alice",
    age: 30,
    nested: { city: "NYC" },
};

const cloned = deepClone(original);
cloned.nested.city = "LA";

console.log(original.nested.city); // "NYC" (unchanged)
console.log(cloned.nested.city); // "LA"
```

***

## Options [#options]

### Options Interface [#options-interface]

Configuration options for the `deepClone` function.

**Type Definition:**

```typescript
type Options = {
    strict?: boolean;
    handler?: Partial<Handlers>;
};
```

**Properties:**

#### strict [#strict]

Controls whether to copy non-enumerable properties and symbols.

* **Type:** `boolean`
* **Default:** `false`
* **Description:**
  * `false` (loose mode): Only copies enumerable properties (faster)
  * `true` (strict mode): Copies all properties including non-enumerable and symbols (slower)

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";

const obj = { visible: "enumerable" };
Object.defineProperty(obj, "hidden", {
    value: "non-enumerable",
    enumerable: false,
});

// Loose mode (default)
const loose = deepClone(obj);
console.log(loose.hidden); // undefined

// Strict mode
const strict = deepClone(obj, { strict: true });
console.log(strict.hidden); // "non-enumerable"
```

#### handler [#handler]

Custom handlers for specific data types.

* **Type:** `Partial<Handlers>`
* **Default:** `undefined`
* **Description:** Override default cloning behavior for specific types. Every key is optional, so you only pass the handlers you want to override.

**Handlers Definition:**

```typescript
type InternalHandler<T> = (object: T, state: State) => T;

type Handlers = {
    Array: InternalHandler<unknown[]>;
    ArrayBuffer: InternalHandler<ArrayBuffer>;
    Blob: InternalHandler<Blob>;
    DataView: InternalHandler<DataView>;
    Date: InternalHandler<Date>;
    Error: InternalHandler<Error>;
    File: InternalHandler<File>;
    Function: InternalHandler<Function>;
    Map: InternalHandler<Map<unknown, unknown>>;
    Object: InternalHandler<Record<string, unknown>>;
    Promise: InternalHandler<Promise<unknown>>;
    RegExp: InternalHandler<RegExp>;
    Set: InternalHandler<Set<unknown>>;
    SharedArrayBuffer: InternalHandler<SharedArrayBuffer>;
    WeakMap: InternalHandler<WeakMap<any, unknown>>;
    WeakSet: InternalHandler<WeakSet<any>>;
};
```

> Note: typed arrays are cloned through the `ArrayBuffer` handler — there are no dedicated typed-array keys.

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";
import type { State } from "@visulima/deep-clone";

const cloned = deepClone(data, {
    handler: {
        Date: (date: Date, _state: State) => {
            // Clone to current time instead of original time
            return new Date();
        },
        Array: (array: unknown[], state: State) => {
            // Custom array cloning (e.g., filter nulls)
            const filtered = array.filter((item) => item !== null);
            return filtered.map((item) => state.clone(item, state));
        },
    },
});
```

***

## State Interface [#state-interface]

The state object passed to custom handlers.

**Type Definition:**

```typescript
interface State {
    cache: WeakMap<any, any>;
    clone: (value: any, state: State) => any;
}
```

**Properties:**

* `cache` (`WeakMap<any, any>`) - Circular reference tracking cache
* `clone` (`function`) - The clone function to recursively clone nested values

**Usage in Custom Handlers:**

```typescript
import { deepClone } from "@visulima/deep-clone";
import type { State } from "@visulima/deep-clone";

const cloned = deepClone(data, {
    handler: {
        Object: (obj: Record<PropertyKey, unknown>, state: State) => {
            // Create empty object
            const copy = {} as Record<PropertyKey, unknown>;

            // Clone each property using state.clone
            for (const key in obj) {
                copy[key] = state.clone(obj[key], state);
            }

            return copy;
        },
    },
});
```

***

## Utility Functions [#utility-functions]

### copyOwnProperties [#copyownproperties]

Copies all own enumerable properties from an object (shallow copy).

**Signature:**

```typescript
function copyOwnProperties<T extends object>(object: T): T;
```

**Parameters:**

* `object` (`T`, required) - The object to copy properties from

**Returns:** `T` - A new object with copied properties

**Note:** This performs a **shallow copy**. Nested objects are referenced, not cloned.

**Example:**

```typescript
import { copyOwnProperties } from "@visulima/deep-clone/utils";

const original = {
    name: "Alice",
    age: 30,
    address: { city: "NYC" },
};

const copy = copyOwnProperties(original);
copy.age = 31;
copy.address.city = "LA";

console.log(original.age); // 30 (unchanged)
console.log(original.address.city); // "LA" (changed! shallow copy)
```

***

### getCleanClone [#getcleanclone]

Creates an empty object with the same prototype as the input object.

**Signature:**

```typescript
function getCleanClone<T extends object>(object: T): T;
```

**Parameters:**

* `object` (`T`, required) - The object to get a clean clone of

**Returns:** `T` - An empty object with the same prototype

**Example:**

```typescript
import { getCleanClone } from "@visulima/deep-clone/utils";

class User {
    name: string = "";
    age: number = 0;

    greet() {
        return `Hello, ${this.name}!`;
    }
}

const user = new User();
user.name = "Alice";
user.age = 30;

const clean = getCleanClone(user);

console.log(clean.name); // "" (empty)
console.log(clean.age); // 0 (default)
console.log(clean.greet()); // "Hello, !" (method exists)
console.log(clean instanceof User); // true
```

**Use Case:** Useful when you need an empty instance of the same class/prototype without manually calling constructors.

***

## Type Definitions [#type-definitions]

### DeepReadwrite [#deepreadwrite]

Utility type that recursively removes `readonly` modifiers from all properties.

**Type Definition:**

```typescript
type DeepReadwrite<T> = T extends object | [] ? { -readonly [P in keyof T]: DeepReadwrite<T[P]> } : T;
```

**Description:** The cloned object has all readonly modifiers removed, allowing mutations.

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";

interface ReadonlyData {
    readonly id: number;
    readonly config: {
        readonly enabled: boolean;
    };
}

const data: ReadonlyData = {
    id: 1,
    config: { enabled: true },
};

// TypeScript error: Cannot assign to 'id' because it is a read-only property
// data.id = 2;

const cloned = deepClone(data);

// OK! DeepReadwrite removes readonly
cloned.id = 2;
cloned.config.enabled = false;
```

***

## Supported Types Reference [#supported-types-reference]

### Fully Supported Types [#fully-supported-types]

These types are deeply cloned with full support:

| Type                | Behavior                                   |
| ------------------- | ------------------------------------------ |
| `undefined`         | Returned as-is (immutable)                 |
| `null`              | Returned as-is (immutable)                 |
| `boolean`           | Returned as-is (immutable)                 |
| `number`            | Returned as-is (immutable)                 |
| `string`            | Returned as-is (immutable)                 |
| `Object`            | Deep cloned with all nested properties     |
| `Array`             | Deep cloned with all elements              |
| `Date`              | New Date instance with same timestamp      |
| `RegExp`            | New RegExp with same pattern and flags     |
| `Map`               | New Map with cloned entries                |
| `Set`               | New Set with cloned values                 |
| `Error`             | New Error with cloned properties and stack |
| `ArrayBuffer`       | New ArrayBuffer with copied bytes          |
| `Uint8Array`        | New Uint8Array with copied data            |
| `Int8Array`         | New Int8Array with copied data             |
| `Uint16Array`       | New Uint16Array with copied data           |
| `Int16Array`        | New Int16Array with copied data            |
| `Uint32Array`       | New Uint32Array with copied data           |
| `Int32Array`        | New Int32Array with copied data            |
| `Float32Array`      | New Float32Array with copied data          |
| `Float64Array`      | New Float64Array with copied data          |
| `Uint8ClampedArray` | New Uint8ClampedArray with copied data     |
| `DataView`          | New DataView with cloned buffer            |
| `Blob`              | New Blob with same content (browser)       |
| `Buffer`            | New Buffer with copied data (Node.js)      |
| `Function`          | **Copied by reference** (not cloned)       |
| DOM Nodes           | Cloned using `element.cloneNode(true)`     |

### Unsupported Types [#unsupported-types]

These types throw `TypeError` when cloned:

| Type                | Error Message                                |
| ------------------- | -------------------------------------------- |
| `Promise`           | "Promise objects cannot be cloned"           |
| `WeakMap`           | "WeakMap objects cannot be cloned"           |
| `WeakSet`           | "WeakSet objects cannot be cloned"           |
| `SharedArrayBuffer` | "SharedArrayBuffer objects cannot be cloned" |

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";

try {
    deepClone(new Promise((resolve) => resolve(1)));
} catch (error) {
    console.log(error.message);
    // "Promise objects cannot be cloned"
}
```

***

## Error Handling [#error-handling]

### TypeError [#typeerror]

Thrown when attempting to clone unsupported types.

**Example:**

```typescript
import { deepClone } from "@visulima/deep-clone";

try {
    const weakMap = new WeakMap();
    deepClone(weakMap);
} catch (error) {
    console.log(error instanceof TypeError); // true
    console.log(error.message); // "WeakMap objects cannot be cloned"
}
```

### Circular References [#circular-references]

Circular references are **automatically handled** and do not throw errors:

```typescript
import { deepClone } from "@visulima/deep-clone";

const obj: any = { name: "circular" };
obj.self = obj; // Circular reference

const cloned = deepClone(obj); // No error!
console.log(cloned.self === cloned); // true
```

***

## Function Summary [#function-summary]

| Function            | Category | Description                                           |
| ------------------- | -------- | ----------------------------------------------------- |
| `deepClone`         | Main     | Deep clone any value with circular reference handling |
| `copyOwnProperties` | Utility  | Shallow copy of object's own properties               |
| `getCleanClone`     | Utility  | Create empty object with same prototype               |

## Type Export Summary [#type-export-summary]

| Type               | Description                            |
| ------------------ | -------------------------------------- |
| `Options`          | Configuration options for deepClone    |
| `State`            | State object for custom handlers       |
| `DeepReadwrite<T>` | Removes readonly modifiers recursively |

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/deep-clone/usage">
    Learn how to use deepClone with detailed examples
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/deep-clone)



# @visulima/deep-clone [#visulimadeep-clone]

Fast and reliable deep cloning for JavaScript objects. Create independent copies of complex data structures including nested objects, arrays, dates, maps, sets, and more—all while handling circular references automatically.

## Key Features [#key-features]

**Performance Optimized**

* Competitive performance compared to popular libraries
* Loose mode for fast standard cloning
* Strict mode for complete property cloning
* Memory-efficient circular reference handling

**Comprehensive Type Support**

* Objects, arrays, and primitives
* Built-in types: Date, RegExp, Map, Set, Error
* TypedArrays and Buffers
* Blob, ArrayBuffer, and DataView
* Functions (copied by reference)

**Advanced Capabilities**

* Automatic circular reference detection
* Custom handlers for specific types
* Utility functions for specialized cloning
* TypeScript type preservation

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/deep-clone
```

Clone an object:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    name: "John",
    age: 30,
    address: {
        city: "New York",
        country: "USA",
    },
};

const cloned = deepClone(original);
cloned.address.city = "Los Angeles";

console.log(original.address.city); // "New York" (unchanged)
console.log(cloned.address.city); // "Los Angeles"
```

## Use Cases [#use-cases]

### Clone API Response Data [#clone-api-response-data]

Create independent copies of API responses for state management:

```typescript
import { deepClone } from "@visulima/deep-clone";

async function fetchUserData(userId: string) {
    const response = await fetch(`/api/users/${userId}`);
    const data = await response.json();

    // Clone to prevent accidental mutations
    return deepClone(data);
}

// Use the cloned data safely
const user = await fetchUserData("123");
const modifiedUser = { ...user, status: "active" };
```

### Handle Circular References [#handle-circular-references]

Clone objects with circular references safely:

```typescript
import { deepClone } from "@visulima/deep-clone";

const person = {
    name: "Alice",
    friends: [] as Array<{ name: string; friends: unknown[] }>,
};

const friend = {
    name: "Bob",
    friends: [person],
};

person.friends.push(friend);

// Handles circular references automatically
const cloned = deepClone(person);
console.log(cloned.friends[0].friends[0] === cloned); // true
```

### Clone Complex Data Structures [#clone-complex-data-structures]

Work with Maps, Sets, and other built-in types:

```typescript
import { deepClone } from "@visulima/deep-clone";

const complexData = {
    users: new Map([
        ["alice", { name: "Alice", age: 30 }],
        ["bob", { name: "Bob", age: 25 }],
    ]),
    tags: new Set(["javascript", "typescript", "node"]),
    createdAt: new Date(),
    pattern: /[a-z]+/gi,
};

const cloned = deepClone(complexData);
cloned.users.set("charlie", { name: "Charlie", age: 35 });

console.log(complexData.users.size); // 2 (unchanged)
console.log(cloned.users.size); // 3
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/deep-clone/installation">
    Learn about installation and import methods
  </Card>

  <Card title="Usage Guide" href="/docs/packages/deep-clone/usage">
    Explore cloning modes, options, and utilities
  </Card>

  <Card title="API Reference" href="/docs/packages/deep-clone/api">
    Complete API documentation with all parameters
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package works in both Node.js and browser environments:

* **Node.js:** ≥22.13 ≤25.x
* **Browsers:** Modern browsers with ES6 support
* **Deno/Bun:** Fully compatible

Requires support for WeakMap for circular reference handling.


# Installation (/docs/packages/deep-clone/installation)





# Installation [#installation]

Install the package using your preferred package manager:

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/deep-clone `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/deep-clone `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/deep-clone `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/deep-clone `
  </Tab>
</Tabs>

## Import Methods [#import-methods]

### Main Function [#main-function]

Import the primary `deepClone` function:

```typescript
import { deepClone } from "@visulima/deep-clone";

const cloned = deepClone({ a: 1, b: { c: 2 } });
```

### Default Import [#default-import]

Alternative default import:

```typescript
import deepClone from "@visulima/deep-clone";

const cloned = deepClone({ a: 1, b: { c: 2 } });
```

### Utility Functions [#utility-functions]

Import utility functions from submodules:

```typescript
import { copyOwnProperties, getCleanClone } from "@visulima/deep-clone/utils";

const copy = copyOwnProperties({ a: 1, b: 2 });
const clean = getCleanClone({ a: 1, b: 2 });
```

### Custom Handlers [#custom-handlers]

Import handlers for customization:

```typescript
import type { Options, State } from "@visulima/deep-clone";
import { copyArrayStrict, copyObjectStrict } from "@visulima/deep-clone/handler";
```

### CommonJS [#commonjs]

For CommonJS environments:

```javascript
const { deepClone } = require("@visulima/deep-clone");
const { copyOwnProperties } = require("@visulima/deep-clone/utils");
```

## Requirements [#requirements]

* **Node.js:** ≥22.13 ≤25.x
* **TypeScript:** ≥5.0 (optional, for type definitions)
* **Browser:** ES6+ support required (WeakMap for circular references)

## Verify Installation [#verify-installation]

Test the installation works correctly:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    name: "test",
    nested: { value: 42 },
};

const cloned = deepClone(original);
cloned.nested.value = 100;

console.log(original.nested.value); // 42 (unchanged)
console.log(cloned.nested.value); // 100 (modified)
```

If the original object remains unchanged, installation was successful!

## TypeScript Support [#typescript-support]

The package includes comprehensive TypeScript type definitions. The generic type parameter preserves your object's types:

```typescript
import { deepClone } from "@visulima/deep-clone";

interface User {
    id: number;
    name: string;
    settings: {
        theme: "light" | "dark";
    };
}

const user: User = {
    id: 1,
    name: "Alice",
    settings: { theme: "dark" },
};

// TypeScript knows the returned type is User
const cloned: User = deepClone(user);
```

The `DeepReadwrite` utility type removes readonly modifiers, allowing you to modify the cloned object:

```typescript
import { deepClone } from "@visulima/deep-clone";

interface ReadonlyUser {
    readonly id: number;
    readonly settings: {
        readonly theme: string;
    };
}

const user: ReadonlyUser = {
    id: 1,
    settings: { theme: "dark" },
};

// Cloned object has mutable properties
const cloned = deepClone(user);
cloned.id = 2; // OK! readonly is removed
cloned.settings.theme = "light"; // OK!
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/deep-clone/usage">
    Learn how to use deepClone with options and utilities
  </Card>

  <Card title="API Reference" href="/docs/packages/deep-clone/api">
    Explore the complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/deep-clone/usage)



# Usage Guide [#usage-guide]

Learn how to use `@visulima/deep-clone` for all your cloning needs.

## Basic Cloning [#basic-cloning]

### Clone Simple Objects [#clone-simple-objects]

Clone objects with nested properties:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    name: "John Doe",
    age: 30,
    address: {
        city: "New York",
        zipCode: "10001",
    },
};

const cloned = deepClone(original);
cloned.address.city = "Los Angeles";

console.log(original.address.city); // "New York" (unchanged)
console.log(cloned.address.city); // "Los Angeles"
```

### Clone Arrays [#clone-arrays]

Arrays and their nested contents are fully cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }, [1, 2, [3, 4]]];

const cloned = deepClone(original);
cloned[0].name = "Charlie";
cloned[2][2][0] = 999;

console.log(original[0].name); // "Alice" (unchanged)
console.log(original[2][2][0]); // 3 (unchanged)
console.log(cloned[0].name); // "Charlie"
console.log(cloned[2][2][0]); // 999
```

### Clone Primitives [#clone-primitives]

Primitives are returned as-is (they're immutable):

```typescript
import { deepClone } from "@visulima/deep-clone";

console.log(deepClone(42)); // 42
console.log(deepClone("hello")); // "hello"
console.log(deepClone(true)); // true
console.log(deepClone(null)); // null
console.log(deepClone(undefined)); // undefined
```

## Cloning Built-in Types [#cloning-built-in-types]

### Clone Dates [#clone-dates]

Date objects are properly cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    createdAt: new Date("2024-01-01"),
    updatedAt: new Date(),
};

const cloned = deepClone(original);
cloned.createdAt.setFullYear(2025);

console.log(original.createdAt.getFullYear()); // 2024 (unchanged)
console.log(cloned.createdAt.getFullYear()); // 2025
```

### Clone RegExp [#clone-regexp]

Regular expressions maintain their patterns and flags:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    emailPattern: /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/gi,
    phonePattern: /^\+?[1-9]\d{1,14}$/,
};

const cloned = deepClone(original);

console.log(cloned.emailPattern.source); // Same pattern
console.log(cloned.emailPattern.flags); // "gi" (same flags)
console.log(original.emailPattern !== cloned.emailPattern); // true (different instance)
```

### Clone Maps [#clone-maps]

Map entries and their values are cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = new Map([
    ["user:1", { name: "Alice", age: 30 }],
    ["user:2", { name: "Bob", age: 25 }],
]);

const cloned = deepClone(original);
cloned.get("user:1").age = 31;

console.log(original.get("user:1").age); // 30 (unchanged)
console.log(cloned.get("user:1").age); // 31
```

### Clone Sets [#clone-sets]

Set values are deeply cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = new Set([
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
]);

const cloned = deepClone(original);
const firstItem = Array.from(cloned)[0];
firstItem.name = "Charlie";

const originalFirst = Array.from(original)[0];
console.log(originalFirst.name); // "Alice" (unchanged)
console.log(firstItem.name); // "Charlie"
```

### Clone Errors [#clone-errors]

Error objects including stack traces are cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = new Error("Something went wrong");
original.code = "ERR_CUSTOM";

const cloned = deepClone(original);
cloned.code = "ERR_MODIFIED";

console.log(original.code); // "ERR_CUSTOM" (unchanged)
console.log(cloned.code); // "ERR_MODIFIED"
console.log(cloned.message); // "Something went wrong"
console.log(cloned.stack); // Stack trace preserved
```

Works with error subtypes:

```typescript
import { deepClone } from "@visulima/deep-clone";

const typeError = new TypeError("Invalid type");
const rangeError = new RangeError("Out of range");
const syntaxError = new SyntaxError("Syntax error");

const clonedType = deepClone(typeError);
console.log(clonedType instanceof TypeError); // true
```

### Clone TypedArrays [#clone-typedarrays]

TypedArrays are properly cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    bytes: new Uint8Array([1, 2, 3, 4]),
    floats: new Float32Array([1.1, 2.2, 3.3]),
};

const cloned = deepClone(original);
cloned.bytes[0] = 99;

console.log(original.bytes[0]); // 1 (unchanged)
console.log(cloned.bytes[0]); // 99
```

## Circular References [#circular-references]

### Handle Circular Objects [#handle-circular-objects]

Circular references are automatically detected and preserved:

```typescript
import { deepClone } from "@visulima/deep-clone";

const person = {
    name: "Alice",
    friends: [] as Array<{ name: string; bestFriend?: typeof person }>,
};

const friend = {
    name: "Bob",
    bestFriend: person,
};

person.friends.push(friend);

const cloned = deepClone(person);

// Circular reference is preserved
console.log(cloned.friends[0].bestFriend === cloned); // true
console.log(cloned.friends[0].bestFriend.name); // "Alice"
```

### Handle Complex Circular Structures [#handle-complex-circular-structures]

Multiple circular references are handled correctly:

```typescript
import { deepClone } from "@visulima/deep-clone";

const nodeA = { id: "A", connections: [] as Array<typeof nodeA | typeof nodeB> };
const nodeB = { id: "B", connections: [] as Array<typeof nodeA | typeof nodeB> };
const nodeC = { id: "C", connections: [] as Array<typeof nodeA | typeof nodeB> };

nodeA.connections.push(nodeB, nodeC);
nodeB.connections.push(nodeA, nodeC);
nodeC.connections.push(nodeA, nodeB);

const cloned = deepClone(nodeA);

// All circular references preserved
console.log(cloned.connections[0].connections[0] === cloned); // true
```

## Cloning Modes [#cloning-modes]

### Loose Mode (Default) [#loose-mode-default]

Fast cloning that copies enumerable properties:

```typescript
import { deepClone } from "@visulima/deep-clone";

const obj = {
    visible: "I'm enumerable",
    [Symbol("id")]: "I'm a symbol",
};

Object.defineProperty(obj, "hidden", {
    value: "I'm non-enumerable",
    enumerable: false,
});

const cloned = deepClone(obj);

console.log(cloned.visible); // "I'm enumerable" (copied)
console.log(cloned.hidden); // undefined (not copied)
console.log(cloned[Symbol("id")]); // undefined (not copied)
```

### Strict Mode [#strict-mode]

Clone all properties including non-enumerable and symbols:

```typescript
import { deepClone } from "@visulima/deep-clone";

const original = {
    visible: "I'm enumerable",
    [Symbol.for("id")]: "I'm a symbol",
};

Object.defineProperty(original, "hidden", {
    value: "I'm non-enumerable",
    enumerable: false,
});

const cloned = deepClone(original, { strict: true });

console.log(cloned.visible); // "I'm enumerable" (copied)
console.log(cloned.hidden); // "I'm non-enumerable" (copied!)
console.log(cloned[Symbol.for("id")]); // "I'm a symbol" (copied!)
```

Use strict mode when you need complete property cloning:

```typescript
import { deepClone } from "@visulima/deep-clone";

class User {
    public name: string;
    private _password: string;

    constructor(name: string, password: string) {
        this.name = name;
        this._password = password;

        // Make _password non-enumerable
        Object.defineProperty(this, "_password", {
            enumerable: false,
            writable: true,
        });
    }
}

const user = new User("Alice", "secret123");

// Loose mode skips _password
const looseClone = deepClone(user);
console.log(looseClone._password); // undefined

// Strict mode includes _password
const strictClone = deepClone(user, { strict: true });
console.log(strictClone._password); // "secret123"
```

## Custom Handlers [#custom-handlers]

### Override Default Behavior [#override-default-behavior]

Customize how specific types are cloned:

```typescript
import { deepClone } from "@visulima/deep-clone";
import type { State } from "@visulima/deep-clone";

const cloned = deepClone(originalData, {
    handler: {
        Date: (date: Date, _state: State) => {
            // Always clone to current time
            return new Date();
        },
        RegExp: (regexp: RegExp, _state: State) => {
            // Return original RegExp instead of cloning
            return regexp;
        },
    },
});
```

### Handle Custom Classes [#handle-custom-classes]

Define handlers for your own classes:

```typescript
import { deepClone } from "@visulima/deep-clone";
import type { State } from "@visulima/deep-clone";

class Point {
    constructor(
        public x: number,
        public y: number,
    ) {}

    distance(): number {
        return Math.sqrt(this.x ** 2 + this.y ** 2);
    }
}

const original = {
    points: [new Point(1, 2), new Point(3, 4)],
};

const cloned = deepClone(original, {
    handler: {
        Object: (obj: Record<PropertyKey, unknown>, state: State) => {
            if (obj instanceof Point) {
                // Custom Point cloning logic
                return new Point(obj.x * 2, obj.y * 2);
            }

            // Default object cloning
            const copy = {} as Record<PropertyKey, unknown>;
            for (const key in obj) {
                copy[key] = state.clone(obj[key], state);
            }
            return copy;
        },
    },
});

console.log(cloned.points[0].x); // 2 (doubled)
console.log(cloned.points[0].y); // 4 (doubled)
```

## Utility Functions [#utility-functions]

### Copy Own Properties [#copy-own-properties]

Copy only the immediate properties of an object:

```typescript
import { copyOwnProperties } from "@visulima/deep-clone/utils";

const original = {
    name: "Alice",
    age: 30,
    address: { city: "NYC" },
};

const copy = copyOwnProperties(original);
copy.address.city = "LA";

// Nested objects are still referenced
console.log(original.address.city); // "LA" (modified!)

// Use deepClone for true deep copy
import { deepClone } from "@visulima/deep-clone";
const deepCopy = deepClone(original);
deepCopy.address.city = "SF";
console.log(original.address.city); // "LA" (unchanged)
```

### Get Clean Clone [#get-clean-clone]

Get an empty object with the same prototype:

```typescript
import { getCleanClone } from "@visulima/deep-clone/utils";

class User {
    name: string = "";
    greet() {
        return `Hello, ${this.name}!`;
    }
}

const user = new User();
user.name = "Alice";

const clean = getCleanClone(user);

console.log(clean.name); // "" (empty)
console.log(clean.greet()); // "Hello, !" (method exists)
console.log(clean instanceof User); // true (prototype preserved)
```

## Type Support [#type-support]

### Supported Types [#supported-types]

These types are fully supported for cloning:

```typescript
import { deepClone } from "@visulima/deep-clone";

const data = {
    // Primitives (returned as-is)
    num: 42,
    str: "hello",
    bool: true,
    nul: null,
    undef: undefined,

    // Objects and Arrays
    obj: { nested: { deep: true } },
    arr: [1, [2, [3]]],

    // Built-in Types
    date: new Date(),
    regexp: /pattern/gi,
    map: new Map([["key", "value"]]),
    set: new Set([1, 2, 3]),
    error: new Error("message"),

    // Binary Data
    buffer: Buffer.from("hello"),
    uint8: new Uint8Array([1, 2, 3]),
    arrayBuffer: new ArrayBuffer(8),
    dataView: new DataView(new ArrayBuffer(8)),

    // Browser APIs (if available)
    blob: new Blob(["content"], { type: "text/plain" }),

    // Functions (copied by reference)
    func: () => console.log("hello"),
};

const cloned = deepClone(data);
```

### Unsupported Types [#unsupported-types]

These types throw errors or are not supported:

```typescript
import { deepClone } from "@visulima/deep-clone";

// These throw TypeError:
try {
    deepClone(new Promise((resolve) => resolve(1)));
} catch (error) {
    console.log(error.message); // "Promise objects cannot be cloned"
}

try {
    deepClone(new WeakMap());
} catch (error) {
    console.log(error.message); // "WeakMap objects cannot be cloned"
}

try {
    deepClone(new WeakSet());
} catch (error) {
    console.log(error.message); // "WeakSet objects cannot be cloned"
}

try {
    deepClone(new SharedArrayBuffer(8));
} catch (error) {
    console.log(error.message); // "SharedArrayBuffer objects cannot be cloned"
}

// DOM elements: use element.cloneNode() instead
// Symbols: use strict mode to clone them
```

## Performance Tips [#performance-tips]

### Choose the Right Mode [#choose-the-right-mode]

* **Loose mode (default):** Use for standard objects and better performance
* **Strict mode:** Only when you need non-enumerable properties or symbols

```typescript
import { deepClone } from "@visulima/deep-clone";

const simple = { a: 1, b: 2, c: { d: 3 } };

// Faster for standard objects
const cloned1 = deepClone(simple);

// Slower but more complete
const cloned2 = deepClone(simple, { strict: true });
```

### Avoid Unnecessary Cloning [#avoid-unnecessary-cloning]

Don't clone primitives or immutable data:

```typescript
import { deepClone } from "@visulima/deep-clone";

// ❌ Unnecessary cloning
const num = deepClone(42);
const str = deepClone("hello");

// ✅ Just use the values directly
const num = 42;
const str = "hello";

// ✅ Only clone when needed
const obj = { count: 42 };
const cloned = deepClone(obj); // Clone the container, not the primitive
```

### Reuse for Similar Structures [#reuse-for-similar-structures]

For repeated cloning of similar structures, consider the performance characteristics:

```typescript
import { deepClone } from "@visulima/deep-clone";

// If cloning many similar objects, loose mode is consistently faster
const users = [
    /* many user objects */
];
const clonedUsers = users.map((user) => deepClone(user));
```

## Real-World Examples [#real-world-examples]

### Clone Redux State [#clone-redux-state]

Create immutable state copies for Redux:

```typescript
import { deepClone } from "@visulima/deep-clone";

interface State {
    user: {
        id: number;
        name: string;
        preferences: Record<string, unknown>;
    };
    cart: Array<{ id: number; quantity: number }>;
}

function reducer(state: State, action: { type: string; payload: unknown }): State {
    const newState = deepClone(state);

    switch (action.type) {
        case "UPDATE_USER":
            newState.user = { ...newState.user, ...(action.payload as Partial<State["user"]>) };
            break;
        case "ADD_TO_CART":
            newState.cart.push(action.payload as State["cart"][0]);
            break;
    }

    return newState;
}
```

### Clone Form Data [#clone-form-data]

Clone form state for undo/redo functionality:

```typescript
import { deepClone } from "@visulima/deep-clone";

class FormManager {
    private history: unknown[] = [];
    private current = 0;

    saveState(formData: unknown): void {
        this.history = this.history.slice(0, this.current + 1);
        this.history.push(deepClone(formData));
        this.current = this.history.length - 1;
    }

    undo(): unknown | null {
        if (this.current > 0) {
            this.current--;
            return deepClone(this.history[this.current]);
        }
        return null;
    }

    redo(): unknown | null {
        if (this.current < this.history.length - 1) {
            this.current++;
            return deepClone(this.history[this.current]);
        }
        return null;
    }
}
```

### Clone Configuration Objects [#clone-configuration-objects]

Safely clone and modify configuration:

```typescript
import { deepClone } from "@visulima/deep-clone";

const baseConfig = {
    server: {
        host: "localhost",
        port: 3000,
        ssl: {
            enabled: false,
            cert: null,
            key: null,
        },
    },
    database: {
        host: "localhost",
        port: 5432,
        name: "myapp",
    },
};

// Create environment-specific configs
const productionConfig = deepClone(baseConfig);
productionConfig.server.host = "api.example.com";
productionConfig.server.ssl.enabled = true;
productionConfig.server.ssl.cert = "/path/to/cert";

const developmentConfig = deepClone(baseConfig);
developmentConfig.server.port = 3001;

// Original remains unchanged
console.log(baseConfig.server.ssl.enabled); // false
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/deep-clone/api">
    Complete API documentation with all parameters and types
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Accessibility (/docs/packages/dev-toolbar/built-in-apps/accessibility)





**App ID:** `dev-toolbar:a11y`

The Accessibility app integrates [axe-core](https://github.com/dequelabs/axe-core) — the industry-standard accessibility engine used by Deque, Google Lighthouse, and many browser extensions — directly into your dev workflow. Run a scan with one click, see violations highlighted on the page with colour-coded overlays, and drill into each issue with WCAG references and fix guidance.

## Features [#features]

* **WCAG 2.0 / 2.1 / 2.2 and Best Practices** standard selection
* **Colour-coded element overlays** on the live page (critical → red, serious → orange, moderate → yellow, minor → blue)
* **SessionStorage persistence** — scan results survive panel close/reopen within the same browser session
* **Severity filtering** — focus on critical issues first
* **Rule disabling** — disable noisy or inapplicable rules per-session
* **Export** — download results as JSON or CSV
* **Tooltip** — shows violation count and severity breakdown without opening the panel; includes quick Scan and Overlays toggle buttons

## Tooltip [#tooltip]

The accessibility tooltip appears when hovering the A11y app button in the toolbar. It shows:

* Total violation count (red badge when violations exist, green when clean)
* Breakdown grid: **Critical / Serious / Moderate / Minor** counts
* "Scanned X ago" timestamp for the most recent scan
* **Scan** / **Re-scan** button — runs a full axe-core audit inline
* **Overlays** button — toggles element highlights on the page

You can scan and toggle overlays without ever opening the full panel.

## Using the Panel [#using-the-panel]

### Running a Scan [#running-a-scan]

1. Open the Accessibility app from the toolbar
2. Optionally select a **WCAG Standard** from the dropdown (WCAG 2.0 A/AA/AAA, WCAG 2.1 A/AA/AAA, WCAG 2.2 A/AA/AAA, or Best Practices)
3. Optionally set a **minimum severity** filter (Critical, Serious, Moderate, Minor)
4. Click **Start Scan**

The scan runs axe-core in the page context and typically completes in under a second for most pages.

### Reading Results [#reading-results]

Each violation card shows:

* **Severity badge** (Critical / Serious / Moderate / Minor)
* **Rule name** and short description
* **Affected element count**
* **WCAG tags** (e.g. `wcag2aa`, `wcag143`)
* **Learn more** link to the axe-core rule documentation
* **Disable rule** button — suppresses this rule for the remainder of the session

Click a violation card to scroll to and highlight the first affected element on the page.

### Overlays [#overlays]

Toggle **Show Overlays** to paint colour-coded outlines directly onto all failing elements:

| Colour         | Severity |
| -------------- | -------- |
| Red outline    | Critical |
| Orange outline | Serious  |
| Yellow outline | Moderate |
| Blue outline   | Minor    |

Overlays use `el.style.setProperty('outline', ..., 'important')` so they always appear regardless of the page's own CSS.

### Exporting Results [#exporting-results]

Use the **Export JSON** or **Export CSV** buttons in the panel header to download the current scan results. Useful for filing issues, tracking regressions, or pasting into reports.

## Session Persistence [#session-persistence]

Scan results are saved to `sessionStorage` under the key `__vdt_a11y__`. The data includes:

```ts
{
    issues: AxeViolation[];
    lastScan: number;   // Unix timestamp
}
```

This means:

* Results survive closing and reopening the DevTools panel
* Results are cleared when the browser tab is closed
* Each page navigation resets the cache (different page = different session entry)

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The Accessibility app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        a11y: true,
    },
});
```

### axe-core Dependency [#axe-core-dependency]

`axe-core` is an **optional peer dependency** — you must install it separately:

```sh
pnpm add -D axe-core
# or
npm install --save-dev axe-core
# or
yarn add -D axe-core
```

axe-core is dynamically imported inside the scan function, so it does **not** add to your bundle size — it is only loaded when the user triggers a scan in development mode. If axe-core is not installed, the panel displays an error message when a scan is attempted.

<Callout type="info">
  axe-core runs entirely in the browser. No data leaves your machine. The scan reads the live DOM and reports violations locally.
</Callout>

## Supported WCAG Standards [#supported-wcag-standards]

| Standard        | Description                                              |
| --------------- | -------------------------------------------------------- |
| `wcag2a`        | WCAG 2.0 Level A — minimum compliance                    |
| `wcag2aa`       | WCAG 2.0 Level AA — standard compliance target (default) |
| `wcag2aaa`      | WCAG 2.0 Level AAA — maximum compliance                  |
| `wcag21a`       | WCAG 2.1 Level A                                         |
| `wcag21aa`      | WCAG 2.1 Level AA                                        |
| `wcag21aaa`     | WCAG 2.1 Level AAA — maximum compliance                  |
| `wcag22a`       | WCAG 2.2 Level A                                         |
| `wcag22aa`      | WCAG 2.2 Level AA                                        |
| `wcag22aaa`     | WCAG 2.2 Level AAA — maximum compliance                  |
| `best-practice` | axe-core best practices (not a formal WCAG level)        |


# Annotations (/docs/packages/dev-toolbar/built-in-apps/annotations)





**App ID:** `dev-toolbar:annotations`

The Annotations app lets you mark elements on a rendered page with visual annotations — capturing intent, severity, screenshots, component context, and accessibility data. Annotations persist to the filesystem and can be consumed by AI agents via [MCP](/docs/packages/dev-toolbar/integrations/mcp).

## Why Annotations? [#why-annotations]

Traditional bug reporting loses context. A screenshot in a ticket doesn't carry the CSS class, the React component name, or the exact source file. Annotations capture all of that automatically — and expose it to AI coding agents so they can find and fix the issue without asking you to explain where the code lives.

```mermaid
sequenceDiagram
    participant D as Developer (Browser)
    participant S as .devtoolbar/
    participant A as AI Agent (MCP)

    D->>S: Click element → Create annotation
    D->>S: Add comment, intent, severity
    Note over S: annotations.json updated
    A->>S: get_pending_annotations()
    S-->>A: Returns element, source, styles, comment
    A->>A: Reads context, fixes code
    A->>S: acknowledge_annotation()
    Note over D: Marker shows "acknowledged"
    A->>S: resolve_annotation()
    Note over D: Marker disappears
```

## Features [#features]

* **Intent tagging** — mark annotations as `fix`, `change`, `approve`, or `question`
* **Severity levels** — `blocking`, `important`, or `suggestion`
* **Status lifecycle** — `pending` → `acknowledged` → `resolved` or `dismissed`

```mermaid
stateDiagram-v2
    [*] --> pending: Created
    pending --> acknowledged: Agent starts work
    pending --> resolved: Human or agent fixes
    pending --> dismissed: Not actionable
    acknowledged --> resolved: Fix complete
    acknowledged --> dismissed: Not actionable
    resolved --> [*]
    dismissed --> [*]
```

* **Rich metadata capture** — bounding box, CSS classes, computed styles, accessibility attributes, framework component info, DOM path, nearby elements, selected text
* **Screenshot capture** — pixel-perfect screenshots via the Screen Capture API
* **Source file linking** — automatically captures `file:line:col` from `data-vdt-source` attributes
* **Multi-select** — drag to annotate multiple elements at once
* **Conversation threads** — each annotation has a thread for human/agent dialogue
* **Markdown export** — export annotations at four detail levels for pasting into issues or agent prompts
* **Filesystem persistence** — annotations stored in `.devtoolbar/annotations.json`, screenshots in `.devtoolbar/screenshots/`

## How it Works [#how-it-works]

### Inspector Toolbar [#inspector-toolbar]

When the Inspector is active, a floating toolbar appears at the bottom of the viewport with these controls:

| Button         | Shortcut | Description                                                      |
| -------------- | -------- | ---------------------------------------------------------------- |
| **Inspect**    | —        | Inspect mode — click to view source, a11y info, open in editor   |
| **Annotate**   | —        | Annotate mode — click to create an annotation at the click point |
| **Freeze**     | `P`      | Pause/resume all animations, timers, and videos                  |
| **Visibility** | `H`      | Toggle annotation markers visible/hidden                         |
| **Copy**       | `C`      | Copy all annotations as Markdown to clipboard                    |
| **Clear**      | `X`      | Delete all annotations (with confirmation)                       |
| **Close**      | `Esc`    | Close the inspector                                              |

The toolbar is draggable — grab anywhere that isn't a button to reposition it.

### Creating an Annotation [#creating-an-annotation]

1. Open the toolbar and activate the **Inspector** app (cursor icon)
2. Switch to **Annotate mode** (the message bubble icon in the floating toolbar)
3. Hover over an element — the inspector overlay highlights it with a label
4. Click the element — a **pending marker** appears at the click point and the annotation form opens nearby with:
   * Element preview with source file and framework component info
   * **Computed styles** (collapsible section)
   * **Intent** selector (fix / change / approve / question)
   * **Severity** selector (blocking / important / suggestion)
   * **Screenshot capture** button
   * **Comment** text field
5. Submit — the annotation is saved to disk and a permanent numbered marker replaces the pending marker

The overlay highlight **stays frozen** on the selected element while the form is open — hovering other elements won't change it.

### Selection Modes [#selection-modes]

**Single element click** — click any element to annotate it. In annotate mode, the marker is placed at the exact click point.

**Area selection** — drag anywhere on the page (on non-text elements) to draw a selection rectangle. If elements are found within the rectangle, a multi-select annotation is created. If no elements are found, an **area selection** annotation is created with a green dashed outline.

**Cmd+Shift+Click multi-select** — hold Cmd/Ctrl+Shift and click elements one by one to build a selection group. Elements toggle in/out of the selection. Selected elements are highlighted with outlines (green for 2+ elements). Release the modifier keys to commit the selection.

**Text selection** — selected text (`window.getSelection()`) is automatically captured when clicking to annotate. The selected text is included in the annotation.

**Deep select (Cmd+hover)** — hold Cmd (Mac) or Ctrl (Windows) while hovering to pierce through invisible overlays, animation wrappers, and empty container divs. The highlight switches to a dashed border to indicate deep select is active. Useful with frameworks like Framer Motion or Remotion that render empty divs on top of content.

### Marker Interactions [#marker-interactions]

* **Hover** — marker scales up and shows an edit pencil icon. The original element is highlighted on the page.
* **Click** — configurable: show detail popup (default), edit annotation, or delete (see Settings).
* **Right-click** — always the opposite action (edit if click=delete, detail if click=edit).
* **Hover highlight** — for area selections, the stored bounding box region is shown with a dashed border.

### Managing Annotations [#managing-annotations]

Open the **Annotations** panel from the toolbar to see all annotations for the current page. Each annotation card shows:

* Numbered marker with intent colour
* Comment text and severity badge
* Source file location (if available)
* Status indicator
* Actions: view detail, edit, resolve, delete

### Annotation Detail [#annotation-detail]

Click any annotation marker or card to open the detail popup:

| Field             | Description                                   |
| ----------------- | --------------------------------------------- |
| **Comment**       | Your annotation text                          |
| **Intent**        | fix / change / approve / question             |
| **Severity**      | blocking / important / suggestion             |
| **Status**        | pending / acknowledged / resolved / dismissed |
| **Element**       | Tag name, classes, and human-readable label   |
| **Source**        | `file:line:col` from JSX source injection     |
| **Screenshot**    | Visual capture of the annotated element       |
| **Component**     | React/Vue/Svelte component name and stack     |
| **Accessibility** | ARIA role, label, describedby, tabindex       |
| **Styles**        | Key computed CSS properties                   |
| **DOM Path**      | Full ancestry path with shadow DOM markers    |

## Markdown Export [#markdown-export]

Press **C** on the inspector toolbar or click **Copy** in an annotation detail popup to export annotations as structured markdown. Four detail levels are available — configure the default in the Annotations panel settings.

### When to use each format [#when-to-use-each-format]

| Format       | Best for                          | Includes                                                   |
| ------------ | --------------------------------- | ---------------------------------------------------------- |
| **Compact**  | Quick fix lists, Slack messages   | Element + comment (one line per annotation)                |
| **Standard** | Bug reports, PR descriptions      | + source location, selector, component info, selected text |
| **Detailed** | Thorough reviews, complex layouts | + CSS classes, DOM path, nearby text context               |
| **Forensic** | AI agents, debugging style issues | + computed styles, accessibility, nearby elements          |

### Output examples [#output-examples]

<Tabs items="[&#x22;Compact&#x22;, &#x22;Standard&#x22;, &#x22;Detailed&#x22;, &#x22;Forensic&#x22;]">
  <Tab value="Compact">
    Minimal output — one line per annotation. Good for quick issue lists or pasting into Slack.

    ```markdown
    # Annotations (3)

    - **button "Submit":** Fix the padding on mobile — text is clipped
    - **h1 "Welcome":** Change heading to "Get Started" (re: "Welcome to...")
    - **input[email]:** Add validation error state for invalid emails
    ```
  </Tab>

  <Tab value="Standard">
    Balanced detail for most use cases. Includes source file, selector, and component context so agents can find the code.

    ```markdown
    # Annotations

    > 3 annotation(s)

    ## 1. [FIX] important — button "Submit"

    **Status:** pending
    **URL:** http://localhost:5173/dashboard
    **Selector:** `button.submit-btn`
    **Source:** `src/components/SubmitButton.tsx:42:10`
    **Component:** SubmitButton (react)
    **Stack:** App > Dashboard > Form > SubmitButton
    **File:** `src/components/SubmitButton.tsx:42`

    Fix the padding on mobile — text is clipped

    ---

    ## 2. [CHANGE] suggestion — h1 "Welcome"

    **Status:** pending
    **URL:** http://localhost:5173/
    **Selector:** `h1.hero-heading`
    **Source:** `src/pages/Home.tsx:18:6`
    **Selected:** "Welcome to..."

    Change heading to "Get Started"

    ---
    ```
  </Tab>

  <Tab value="Detailed">
    Full context with classes, DOM path, and nearby text. Good for thorough reviews where the reviewer needs spatial context.

    ```markdown
    # Annotations

    > 2 annotation(s)

    ## 1. [FIX] blocking — button "Submit"

    **Status:** pending
    **URL:** http://localhost:5173/dashboard
    **Selector:** `button.submit-btn`
    **Source:** `src/components/SubmitButton.tsx:42:10`
    **Component:** SubmitButton (react)
    **Stack:** App > Dashboard > Form > SubmitButton
    **File:** `src/components/SubmitButton.tsx:42`
    **Classes:** `flex items-center gap-2 px-4 py-2 bg-primary`
    **Context:** Submit your application
    **DOM Path:** `body > main > form > div > button`

    Fix the padding on mobile — text is clipped on iPhone SE

    ---
    ```
  </Tab>

  <Tab value="Forensic">
    Maximum detail including computed styles, accessibility attributes, and nearby elements. Use when AI agents need every possible signal to locate and fix an issue.

    ```markdown
    # Annotations

    > 1 annotation(s)

    ## 1. [FIX] blocking — button "Submit"

    **Status:** pending
    **URL:** http://localhost:5173/dashboard
    **Selector:** `button.submit-btn`
    **Source:** `src/components/SubmitButton.tsx:42:10`
    **Component:** SubmitButton (react)
    **Stack:** App > Dashboard > Form > SubmitButton
    **File:** `src/components/SubmitButton.tsx:42`
    **Classes:** `flex items-center gap-2 px-4 py-2 bg-primary`
    **Context:** Submit your application
    **DOM Path:** `body > main > form > div > button`
    **Role:** button
    **Nearby:** input, label, div, span
    **Styles:** `display: flex; padding: 8px 16px; font-size: 14px; color: rgb(255, 255, 255); background-color: rgb(99, 102, 241)`

    Fix the padding on mobile — text is clipped on iPhone SE.
    The bounding box overlaps the adjacent input on viewports below 375px.

    ---
    ```
  </Tab>
</Tabs>

### Customizing output [#customizing-output]

The copied markdown is plain text. Edit it before pasting into your agent prompt:

* **Add context** — prepend with "I'm working on the dashboard page, fix these issues:"
* **Prioritize** — reorder annotations by importance
* **Remove noise** — delete annotations that aren't relevant
* **Add instructions** — append "Fix these and run `pnpm test` when done"

### Source file detection [#source-file-detection]

In development mode, the annotation system automatically detects source files via `data-vdt-source` attributes injected by the Vite plugin's Babel/SWC transform. This works with any JSX framework (React, Vue JSX, Solid, etc.) and enables agents to jump directly to the right file:line:col instead of searching.

### Framework component detection [#framework-component-detection]

Component names and stacks are included when detected. The level of detail adapts to your output format:

| Format       | React                       | Vue            | Svelte         |
| ------------ | --------------------------- | -------------- | -------------- |
| **Compact**  | omitted                     | omitted        | omitted        |
| **Standard** | Component name + stack      | Component name | Component name |
| **Detailed** | + source file               | + source file  | + source file  |
| **Forensic** | + full stack, all ancestors | + parent chain | + file path    |

## Annotation Settings [#annotation-settings]

Open the **Annotations** panel and click the **Settings** button in the toolbar to access annotation settings:

| Setting                | Options                                                               | Default     |
| ---------------------- | --------------------------------------------------------------------- | ----------- |
| **Output detail**      | `compact`, `standard`, `detailed`, `forensic`                         | `standard`  |
| **Marker colour**      | Indigo, Blue, Cyan, Green, Yellow, Orange, Red (solid filled)         | Indigo      |
| **Marker click**       | What happens when clicking a marker: Show Detail, Edit, or Delete     | Show Detail |
| **Block interactions** | Prevent clicks on buttons, links, inputs from firing while inspecting | `true`      |

Settings are saved to `localStorage` under `__vdt_annotation_settings`.

## Live Sync (SSE) [#live-sync-sse]

When the Vite dev server is running, annotations sync in real-time between the browser and MCP agents via Server-Sent Events. The dev server watches `.devtoolbar/annotations.json` for changes and pushes `annotations.changed` events to connected browsers.

This means:

* When an agent resolves or acknowledges an annotation via MCP, the browser **automatically updates** markers and removes resolved annotations — no manual refresh needed.
* When you create an annotation in the browser, the MCP agent can detect it immediately via `watch_annotations`.

## Animation Freeze Mode [#animation-freeze-mode]

When annotating, you can freeze all page animations to precisely target moving elements:

* **CSS animations** — paused via `animation-play-state: paused`
* **CSS transitions** — temporarily removed
* **JavaScript timers** — `setTimeout` and `setInterval` callbacks queued until unfreeze
* **requestAnimationFrame** — callbacks queued until unfreeze
* **Web Animations API** — running animations paused
* **Video elements** — paused

The toolbar itself is never frozen — elements with the `__vdt_` prefix are excluded.

## Framework Detection [#framework-detection]

The annotation system automatically detects framework components:

| Framework  | Detection Method                       | Captured Data                   |
| ---------- | -------------------------------------- | ------------------------------- |
| **React**  | Fiber tree (`__reactFiber$`)           | Component name, component stack |
| **Vue**    | `__vue_app__` / `__vueParentComponent` | Component name                  |
| **Svelte** | `__svelte_meta`                        | Component name                  |

## Storage [#storage]

Annotations are stored on the filesystem, not in the browser:

```
.devtoolbar/
├── annotations.json          # All annotations (JSON array)
└── screenshots/
    ├── {uuid}.png
    ├── {uuid}.jpg
    └── {uuid}.webp
```

The store includes file locking to prevent concurrent write races and path validation to prevent directory traversal.

<Callout type="info">
  Add `.devtoolbar/` to your `.gitignore` if you don't want to commit annotations. Alternatively, commit them to share annotation context with your team.
</Callout>

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

Both the Inspector and Annotations apps must be enabled:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        inspector: true, // Required — provides the annotation overlay
        annotations: true, // Shows the annotation management panel
    },
    injectSource: {
        enabled: true, // Recommended — enables source file linking
    },
    editor: "code", // Optional — editor for "open in source"
});
```

### AI Agent Integration [#ai-agent-integration]

Annotations are designed to be consumed by AI agents via the [MCP server](/docs/packages/dev-toolbar/integrations/mcp). See the MCP integration page for setup instructions.

## Annotation Schema [#annotation-schema]

Every annotation is stored as a JSON object in `.devtoolbar/annotations.json`. The schema is designed to carry enough context for an AI agent to locate, understand, and fix an issue without asking the developer for clarification.

### Core Fields [#core-fields]

These fields are always present on every annotation.

| Field        | Type                                                       | Description                                                                        |
| ------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `id`         | `string`                                                   | Unique identifier (UUID v4)                                                        |
| `comment`    | `string`                                                   | Human feedback text                                                                |
| `intent`     | `"fix" \| "change" \| "question" \| "approve"`             | What the developer wants — fix a bug, request a change, ask a question, or approve |
| `severity`   | `"blocking" \| "important" \| "suggestion"`                | Priority level — blocking issues are addressed first                               |
| `status`     | `"pending" \| "acknowledged" \| "resolved" \| "dismissed"` | Lifecycle state                                                                    |
| `elementTag` | `string`                                                   | HTML tag name (e.g. `button`, `div`, `img`)                                        |
| `url`        | `string`                                                   | Page URL where the annotation was created                                          |
| `x`          | `number`                                                   | Click position as percentage of viewport width (0-100)                             |
| `y`          | `number`                                                   | Click position as pixels from document top (or viewport top if `isFixed`)          |
| `createdAt`  | `string`                                                   | ISO 8601 creation timestamp                                                        |
| `updatedAt`  | `string`                                                   | ISO 8601 last-updated timestamp                                                    |

### Element Context [#element-context]

These optional fields provide rich context about the annotated element for AI agents and code search.

| Field            | Type          | Description                                                                                    |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `elementLabel`   | `string`      | Human-readable label (e.g. `button "Submit"`, `link "Home" to /`, `input[email]`)              |
| `elementPath`    | `string`      | Unique CSS selector for the element                                                            |
| `cssClasses`     | `string`      | Space-separated class list (CSS module hashes cleaned)                                         |
| `fullPath`       | `string`      | Full DOM ancestry path (e.g. `body > main > article > p`) with shadow DOM markers (`⟨shadow⟩`) |
| `nearbyText`     | `string`      | Visible text in/around the element (up to 120 chars)                                           |
| `nearbyElements` | `string`      | Sibling elements for spatial context                                                           |
| `selectedText`   | `string`      | Text the user had selected when annotating (up to 80 chars)                                    |
| `computedStyles` | `string`      | Key CSS properties: display, position, color, font-size, padding, etc.                         |
| `source`         | `string`      | Source file location from `data-vdt-source` (e.g. `src/App.tsx:42:10`)                         |
| `boundingBox`    | `BoundingBox` | Element position and dimensions at annotation time                                             |

### Framework Component Context [#framework-component-context]

The `frameworkContext` field captures component information from React, Vue, or Svelte — not limited to any single framework.

| Field                             | Type       | Description                                                            |
| --------------------------------- | ---------- | ---------------------------------------------------------------------- |
| `frameworkContext.framework`      | `string`   | Framework identifier: `"react"`, `"vue"`, or `"svelte"`                |
| `frameworkContext.componentName`  | `string`   | Nearest user-land component name                                       |
| `frameworkContext.componentStack` | `string[]` | Full component ancestry (e.g. `["App", "Layout", "Header", "Button"]`) |
| `frameworkContext.sourceFile`     | `string`   | Component source file path                                             |
| `frameworkContext.sourceLine`     | `number`   | Source line number                                                     |

### Accessibility [#accessibility]

The `accessibility` field captures ARIA attributes as a structured object.

| Field                           | Type      | Description                                  |
| ------------------------------- | --------- | -------------------------------------------- |
| `accessibility.role`            | `string`  | ARIA role (explicit or implicit)             |
| `accessibility.ariaLabel`       | `string`  | `aria-label` value                           |
| `accessibility.ariaDescribedBy` | `string`  | Resolved text from `aria-describedby` target |
| `accessibility.focusable`       | `boolean` | Whether the element is keyboard-focusable    |
| `accessibility.tabindex`        | `number`  | `tabindex` value                             |

### Multi-select & Position [#multi-select--position]

| Field                  | Type            | Description                                                               |
| ---------------------- | --------------- | ------------------------------------------------------------------------- |
| `isMultiSelect`        | `boolean`       | True if created via drag selection or Cmd+Shift+Click                     |
| `isFixed`              | `boolean`       | True if the element has fixed/sticky positioning (Y is viewport-relative) |
| `elementBoundingBoxes` | `BoundingBox[]` | Individual bounding boxes for each element in a multi-select annotation   |

### Resolution & Threading [#resolution--threading]

| Field                | Type              | Description                                                     |
| -------------------- | ----------------- | --------------------------------------------------------------- |
| `resolvedAt`         | `string`          | ISO 8601 timestamp when resolved or dismissed                   |
| `resolvedBy`         | `string`          | Who resolved it: `"human"`, `"agent"`, or a specific agent name |
| `screenshot`         | `string`          | Relative path to screenshot file (e.g. `screenshots/uuid.png`)  |
| `thread`             | `ThreadMessage[]` | Conversation thread between human and AI agent                  |
| `thread[].id`        | `string`          | Unique message ID (server-generated)                            |
| `thread[].role`      | `string`          | Message author: `"human"` or `"agent"`                          |
| `thread[].content`   | `string`          | Message text                                                    |
| `thread[].timestamp` | `string`          | ISO 8601 timestamp (server-generated)                           |

### TypeScript Types [#typescript-types]

```ts
interface Annotation {
    id: string;
    comment: string;
    intent: "approve" | "change" | "fix" | "question";
    severity: "blocking" | "important" | "suggestion";
    status: "acknowledged" | "dismissed" | "pending" | "resolved";
    elementTag: string;
    elementLabel?: string;
    elementPath?: string;
    boundingBox?: BoundingBox;
    elementBoundingBoxes?: BoundingBox[];
    accessibility?: AccessibilityInfo;
    frameworkContext?: FrameworkContext;
    computedStyles?: string;
    cssClasses?: string;
    fullPath?: string;
    nearbyElements?: string;
    nearbyText?: string;
    selectedText?: string;
    screenshot?: string;
    source?: string;
    isFixed?: boolean;
    isMultiSelect?: boolean;
    url: string;
    x: number;
    y: number;
    createdAt: string;
    updatedAt: string;
    resolvedAt?: string;
    resolvedBy?: string;
    thread?: ThreadMessage[];
}

interface ThreadMessage {
    id?: string;
    role: string;
    content: string;
    timestamp: string;
}

interface BoundingBox {
    x: number;
    y: number;
    width: number;
    height: number;
}

interface FrameworkContext {
    framework: string;
    componentName?: string;
    componentStack?: string[];
    sourceFile?: string;
    sourceLine?: number;
    data?: Record<string, unknown>;
}

interface AccessibilityInfo {
    role?: string;
    ariaLabel?: string;
    ariaDescribedBy?: string;
    focusable: boolean;
    tabindex?: number;
}
```

## Limitations [#limitations]

* **Screenshot capture** requires the Screen Capture API and a user gesture (browser permission prompt). Not available in all browsers or headless environments.
* **Framework detection** is best-effort — minified production builds strip component names. Works reliably in development mode.
* **Cross-origin iframes** cannot be inspected due to browser security restrictions. Same-origin iframes are fully supported.
* **Shadow DOM piercing** works for open shadow roots only. Closed shadow roots are opaque.


# Assets (/docs/packages/dev-toolbar/built-in-apps/assets)



**App ID:** `dev-toolbar:assets`

The Assets app scans Vite's `publicDir` (defaults to `public/`) via RPC and displays all static files in a searchable, filterable list. Click any asset to open a detail panel with a live preview and metadata.

## Features [#features]

* **Full asset listing** — all files from `publicDir`, sorted alphabetically
* **Type filtering** — filter by image, video, audio, font, text, or other
* **Full-text search** — filter by file path
* **Live preview** — images render inline, videos show the first frame, audio gets a playback control
* **Metadata** — file size and last-modified timestamp
* **Copy URL** — copy the public URL to the clipboard in one click
* **Open in browser** — open the asset URL in a new tab
* **Refresh** — re-fetch the asset list without reloading the page

## Using the Panel [#using-the-panel]

### Browsing [#browsing]

On open the panel fetches all files in `publicDir` and displays them as a scrollable list. Each row shows:

* **Type badge** — colour-coded by file category
* **Public path** — the URL-accessible path (e.g. `/images/logo.png`)
* **Size** — human-readable file size

### Filtering [#filtering]

Use the search box to filter by path substring. The type filter pills below the search box narrow the list to a single category. The counter shows `filtered / total`.

### Asset Detail [#asset-detail]

Click any row to open the detail panel on the right:

| Field             | Description                                      |
| ----------------- | ------------------------------------------------ |
| **Preview**       | Inline image/video/audio preview when applicable |
| **Path**          | Full public URL path                             |
| **Type**          | Asset category badge                             |
| **Size**          | File size                                        |
| **Last Modified** | File modification timestamp                      |

Two action buttons are available:

* **Copy URL** — copies the public path to the clipboard
* **Open in browser** — opens the asset in a new browser tab

### Refreshing [#refreshing]

Click **Refresh** in the header to re-scan `publicDir`. Useful after adding or deleting files without reloading the page.

## Asset Type Reference [#asset-type-reference]

| Type    | Extensions                                        | Badge colour |
| ------- | ------------------------------------------------- | ------------ |
| `image` | png, jpg, jpeg, gif, svg, webp, avif, ico, bmp, … | Blue         |
| `video` | mp4, webm, mov, avi, mkv, ogv                     | Purple       |
| `audio` | mp3, wav, ogg, aac, flac, m4a, opus               | Yellow       |
| `font`  | woff, woff2, ttf, otf, eot                        | Orange       |
| `text`  | html, css, js, json, xml, csv, md, txt            | Emerald      |
| `other` | Everything else                                   | Grey         |

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The Assets app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        assets: true,
    },
});
```

## Notes [#notes]

* Assets are read from `server.config.publicDir`. If `publicDir` is set to `false` or the directory does not exist, the panel shows an empty state.
* The asset list reflects the current state of the filesystem at the time of the RPC call. Click **Refresh** to pick up newly added or deleted files.
* Large directories with many files may take a moment to load.


# Inspector (/docs/packages/dev-toolbar/built-in-apps/inspector)





**App ID:** `dev-toolbar:inspector`

The Inspector app lets you interact with any element on the rendered page. Click an element to open its source in your editor, or create an annotation that captures rich context — CSS classes, component names, accessibility attributes, and a screenshot — for bug reports or AI agent consumption.

## How it Works [#how-it-works]

1. Open the toolbar and activate the **Inspector** app (the cursor icon).
2. A floating toolbar appears with mode buttons and tool controls.
3. In **Inspect mode** (default): hover to highlight elements, click to see source/a11y info and action buttons.
4. In **Annotate mode**: hover to highlight, click to create an annotation directly.

### Inspect Mode (default) [#inspect-mode-default]

Click an element — a popup appears with:

* **Open in editor** — jumps to the JSX source in your configured editor
* **Copy HTML** — copies the element's outer HTML to the clipboard
* **Copy path** — copies the `file:line:col` source path
* **Copy A11y** — copies accessibility attributes as text

### Annotate Mode [#annotate-mode]

Click an element — the annotation form opens directly at the click point. See the [Annotations app](/docs/packages/dev-toolbar/built-in-apps/annotations) for details.

### Keyboard Shortcuts [#keyboard-shortcuts]

| Key                            | Action                                        |
| ------------------------------ | --------------------------------------------- |
| `P`                            | Toggle animation freeze                       |
| `H`                            | Toggle marker visibility                      |
| `C`                            | Copy annotations as Markdown                  |
| `X`                            | Clear all annotations                         |
| `Esc`                          | Close inspector (or clear multi-select first) |
| `Cmd`/`Ctrl` + hover           | Deep select (pierce overlays)                 |
| `Cmd`/`Ctrl` + `Shift` + click | Multi-select toggle                           |

Shortcuts are disabled when focused on an input, textarea, or select.

Press **Escape** or click the Inspector button again to deactivate.

## Element Inspection [#element-inspection]

The Inspector captures detailed information about each hovered element:

| Data                | Source                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------- |
| **Element label**   | Human-readable name (e.g. `button "Submit"`, `link "Home" to /`, `input[email]`)            |
| **Source location** | `file:line:col` from `data-vdt-source` attributes                                           |
| **CSS classes**     | Class list with CSS module hashes cleaned (e.g. `class_abc123` → `class`)                   |
| **CSS selector**    | Unique selector generated for the element (ID → unique class → nth-of-type)                 |
| **Computed styles** | Key CSS properties: display, position, colors, fonts, spacing                               |
| **Accessibility**   | ARIA role, label, describedby, tabindex, focusable state                                    |
| **Component**       | React/Vue/Svelte component name and stack (see [Framework Detection](#framework-detection)) |
| **DOM path**        | Full ancestry including shadow DOM boundaries (e.g. `body > main > button ⟨shadow⟩`)        |

### Shadow DOM Piercing [#shadow-dom-piercing]

The Inspector recursively pierces open shadow roots and same-origin iframes to find the actual element under your cursor. This means you can inspect elements inside web components and embedded frames.

### Deep Select [#deep-select]

Hold **Cmd** (Mac) or **Ctrl** (Windows/Linux) while hovering to activate deep select. This skips through invisible overlays, animation wrappers, and empty container divs to reach the actual content element underneath. The highlight border switches to **dashed** to indicate deep select is active. Uses a two-pass algorithm: text content first, then smallest visible element.

## JSX Source Injection [#jsx-source-injection]

The Inspector relies on `data-vdt-source` attributes injected into every JSX opening element at build time by the `inject-source` Vite plugin (part of `@visulima/dev-toolbar/vite`).

Source injection is **enabled by default** in development mode and is skipped entirely in production builds.

Configure it via the [`injectSource`](/docs/packages/dev-toolbar/configuration#injectsource) plugin option:

```ts
devToolbar({
    injectSource: {
        enabled: true,
        ignore: {
            files: ["**/generated/**"],
            components: ["StrictMode"],
        },
    },
});
```

<Callout type="info">
  Source injection reads the original file from disk before transforming, so both SSR and client builds produce identical `data-vdt-source` values. This
  prevents React hydration mismatches in SSR frameworks.
</Callout>

## Configuring the Editor [#configuring-the-editor]

By default, `launch-editor` auto-detects the running editor (WebStorm, VS Code, etc.) from the OS process list.

**Per-user override (Settings app):*&#x2A; open the Settings app and choose your editor from the &#x2A;*"Preferred editor"** dropdown. The selection is saved to `localStorage` and takes priority over the plugin-level default.

**Project-level default:** set the [`editor`](/docs/packages/dev-toolbar/configuration#editor) plugin option in your Vite config — this seeds the initial value for all users who haven't made a personal selection:

```ts
devToolbar({
    editor: "webstorm",
});
```

## Animation Freeze Mode [#animation-freeze-mode]

When the Inspector is active, you can freeze all page animations to precisely target moving elements. This is particularly useful when annotating elements that are mid-animation or transition.

When frozen:

* CSS animations pause via `animation-play-state: paused`
* CSS transitions are temporarily removed
* `setTimeout` / `setInterval` callbacks are queued and replayed on unfreeze
* `requestAnimationFrame` callbacks are queued
* Web Animations API (WAAPI) animations pause
* Video elements pause

The toolbar itself is never frozen — elements with the `__vdt_` prefix are excluded. Freeze mode survives Vite HMR updates.

## Framework Detection [#framework-detection]

The Inspector automatically detects framework components when hovering elements:

| Framework  | Detection Method                       | What's Captured                 |
| ---------- | -------------------------------------- | ------------------------------- |
| **React**  | Fiber tree (`__reactFiber$`)           | Component name, component stack |
| **Vue**    | `__vue_app__` / `__vueParentComponent` | Component name                  |
| **Svelte** | `__svelte_meta`                        | Component name                  |

Component names are most accurate in development mode. Minified production builds strip component names.

## Multi-select [#multi-select]

Two ways to select multiple elements:

**Drag selection** — drag anywhere (on non-text elements) to draw a rectangle. All elements within are captured as a single annotation. If no elements are found, an "Area selection" annotation is created for the region. The selection samples points within the rectangle, queries nearby elements via CSS selectors, and crosses same-origin iframe boundaries.

**Cmd+Shift+Click** — hold Cmd/Ctrl+Shift and click elements one by one. Each click toggles the element in/out of the selection group. Selected elements show colored outlines (green for 2+ elements). Release the modifier keys to commit the selection and open the annotation form.

## Enabling the Inspector [#enabling-the-inspector]

The Inspector is disabled by default. Enable it in your Vite config:

```ts
devToolbar({
    apps: {
        inspector: true,
    },
});
```

To also enable annotations (recommended):

```ts
devToolbar({
    apps: {
        inspector: true,
        annotations: true,
    },
    injectSource: {
        enabled: true,
    },
});
```

## Limitations [#limitations]

* **Cross-origin iframes** cannot be inspected due to browser security restrictions. Same-origin iframes are fully supported.
* **Closed shadow roots** are opaque — only open shadow roots can be pierced.
* **Framework detection** is best-effort in production builds where component names are minified.
* **Screenshot capture** requires the Screen Capture API and a user gesture (permission prompt).


# Module Graph (/docs/packages/dev-toolbar/built-in-apps/module-graph)



**App ID:** `dev-toolbar:module-graph`

The Module Graph app queries Vite's server-side module graph via RPC and presents it as a filterable, searchable list. Each module entry shows its file extension, URL, and importer count. Click any module to see a detail pane with the full list of files that import it.

## Features [#features]

* **Live graph** — fetches the current state of Vite's module graph on open
* **Full-text search** — filter modules by URL or file extension
* **Extension badges** — colour-coded by file type (`.ts`, `.tsx`, `.vue`, `.css`, etc.)
* **Importer count** — see at a glance how many modules depend on each file
* **Importer list** — click a module to see all files that import it
* **Refresh** — re-fetch the graph without reloading the page

## Using the Panel [#using-the-panel]

### Browsing the Module List [#browsing-the-module-list]

On open the panel fetches all modules currently tracked by Vite and displays them as a scrollable list. Each row shows:

* **Extension badge** — colour-coded pill (`.ts` = blue, `.css` = purple, `.json` = yellow, `.vue` = green, etc.)
* **Module URL** — the Vite-resolved path, truncated with monospace font
* **Importer count** — a small badge showing `N↑` where N is the number of modules that import this one. Modules with no importers are entry points.

### Filtering [#filtering]

Type in the search box to filter modules by URL substring or extension. The counter on the right shows `filtered / total`. The filter is case-insensitive.

```
Filter modules…   [  42 / 318  ]
```

### Module Detail [#module-detail]

Click any module row to open the detail pane on the right:

| Field           | Description                                     |
| --------------- | ----------------------------------------------- |
| **URL**         | Full resolved URL                               |
| **Type**        | File extension badge                            |
| **Importers**   | Number of modules that import this one          |
| **Imported by** | List of importer URLs (monospace, one per line) |

Click the same row again (or press the `✕` button) to close the detail pane.

### Refreshing [#refreshing]

Click **Refresh** in the header to re-fetch the module graph from Vite. This is useful after HMR updates that add or remove modules.

### Error State [#error-state]

If the RPC call fails (e.g. the Vite server is temporarily unavailable), an error message is shown with a **Retry** button.

## Extension Colour Reference [#extension-colour-reference]

| Extension     | Colour  |
| ------------- | ------- |
| `.ts`, `.tsx` | Blue    |
| `.js`, `.jsx` | Green   |
| `.vue`        | Emerald |
| `.css`        | Purple  |
| `.json`       | Yellow  |
| `.svg`        | Orange  |
| Other         | Grey    |

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The Module Graph app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        moduleGraph: true,
    },
});
```

## Notes [#notes]

* The module graph data comes from Vite's server-side `ModuleGraph` via an RPC call. It reflects modules that have been loaded or imported at least once since the dev server started.
* Large projects may have hundreds of modules. Use the search filter to narrow results.
* Virtual modules (those with `\0` or `?` in their IDs) are included in the list.


# Performance (/docs/packages/dev-toolbar/built-in-apps/performance)



**App ID:** `dev-toolbar:performance`

The Performance app surfaces real-time performance data from the browser's [Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API) and the [Web Vitals](https://web.dev/vitals/) specification. No external libraries, no DevTools tab switching — key metrics are available the moment you open the panel.

## Features [#features]

* **Core Web Vitals** — LCP, FID/INP, CLS with pass/fail thresholds
* **Paint timings** — FCP, TTFB
* **Resource timing** — breakdown of assets loaded on the page, grouped by type
* **Navigation timing** — DNS, connection, request, response, DOM parse, load phases
* **Tooltip summary** — shows a traffic-light status in the toolbar button without opening the panel

## Tooltip [#tooltip]

The Performance tooltip shows a high-level health summary:

* Green indicator — all measured Web Vitals within "Good" thresholds
* Yellow indicator — at least one metric in "Needs improvement"
* Red indicator — at least one metric "Poor"

Hover the Performance button in the toolbar to see the current status without opening the full panel.

## Panel Sections [#panel-sections]

### Web Vitals [#web-vitals]

Displays the Core Web Vitals collected from `PerformanceObserver` entries since the page loaded:

| Metric                              | Good     | Needs Improvement | Poor      |
| ----------------------------------- | -------- | ----------------- | --------- |
| **LCP** — Largest Contentful Paint  | ≤ 2.5 s  | 2.5–4.0 s         | > 4.0 s   |
| **INP** — Interaction to Next Paint | ≤ 200 ms | 200–500 ms        | > 500 ms  |
| **CLS** — Cumulative Layout Shift   | ≤ 0.1    | 0.1–0.25          | > 0.25    |
| **FCP** — First Contentful Paint    | ≤ 1.8 s  | 1.8–3.0 s         | > 3.0 s   |
| **TTFB** — Time to First Byte       | ≤ 800 ms | 800–1800 ms       | > 1800 ms |

Each metric shows the current value, a colour-coded badge, and the threshold boundaries for context.

### Resource Timing [#resource-timing]

A filterable table of all resources loaded by the page (scripts, stylesheets, fonts, images, XHR/fetch):

* **URL** — truncated to the path with full URL on hover
* **Type** — inferred from the `initiatorType`
* **Duration** — total transfer time in milliseconds
* **Size** — transfer size in KB

Sort by duration to find the slowest assets.

### Navigation Timing [#navigation-timing]

A waterfall breakdown of the page's navigation lifecycle:

| Phase          | Description                              |
| -------------- | ---------------------------------------- |
| DNS Lookup     | `domainLookupEnd - domainLookupStart`    |
| TCP Connection | `connectEnd - connectStart`              |
| SSL/TLS        | `connectEnd - secureConnectionStart`     |
| Request        | `responseStart - requestStart`           |
| Response       | `responseEnd - responseStart`            |
| DOM Processing | `domContentLoadedEventEnd - responseEnd` |
| Load Event     | `loadEventEnd - loadEventStart`          |

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The Performance app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        performance: true,
    },
});
```

## Notes [#notes]

* Web Vitals are measured from the current page load. Refresh the page to reset measurements.
* LCP and CLS are finalized only after user interaction or page visibility changes; the displayed values update live.
* The Performance panel reads from `window.performance` — no data is sent to any external service.


# SEO (/docs/packages/dev-toolbar/built-in-apps/seo)



**App ID:** `dev-toolbar:seo`

The SEO app reads the current page's `<head>` in real time across four tabs: live social preview cards, a meta tag audit table, a missing-tag checklist, and a JSON-LD structured data validator.

## Features [#features]

* **Social preview cards** for 7 platforms — see exactly how your link looks when posted
* **Meta tag audit** — every relevant tag listed with presence/absence status
* **Missing tag warnings** — required tags highlighted with a warning badge
* **Structured data validation** — scans all `<script type="application/ld+json">` blocks and validates against Schema.org rules for 10+ types
* **Refresh on demand** — re-reads the page head without a full reload

## Social Preview Tab [#social-preview-tab]

The Social Previews tab renders mock link-unfurl cards for each platform using the Open Graph and Twitter Card tags found in your `<head>`. This lets you catch wrong aspect ratios, missing images, or truncated titles before deploying.

### Supported Platforms [#supported-platforms]

| Platform        | Tags used                                                               |
| --------------- | ----------------------------------------------------------------------- |
| **Facebook**    | `og:title`, `og:description`, `og:image`, `og:url`                      |
| **X / Twitter** | `twitter:title`, `twitter:description`, `twitter:image`, `twitter:card` |
| **LinkedIn**    | `og:title`, `og:description`, `og:image`, `og:url`                      |
| **Discord**     | `og:title`, `og:description`, `og:image`                                |
| **Slack**       | `og:title`, `og:description`, `og:image`                                |
| **Mastodon**    | `og:title`, `og:description`, `og:image`                                |
| **Bluesky**     | `og:title`, `og:description`, `og:image`                                |

Each card shows:

* **OG image** at the correct aspect ratio (1200×630) — or a "No image" placeholder
* **URL** in muted uppercase
* **Title** (bold, single line)
* **Description** (muted, up to two lines)
* **Missing tags warning badge** when required tags for that platform are absent

### Fallback Behaviour [#fallback-behaviour]

If a platform-specific tag is missing, the preview falls back in this order:

1. Platform-specific tag (e.g. `twitter:title`)
2. Open Graph equivalent (e.g. `og:title`)
3. Plain `<title>` or `<meta name="description">`
4. "No title" / empty

## Meta Tags Tab [#meta-tags-tab]

The Meta Tags tab shows every relevant tag as a flat list with the raw value alongside. Required tags are flagged with a "⚠ Missing" warning when absent.

### Tags Audited [#tags-audited]

| Tag                         | Required |
| --------------------------- | -------- |
| `<title>`                   | Yes      |
| `<meta name="description">` | Yes      |
| `<link rel="canonical">`    | No       |
| `og:title`                  | Yes      |
| `og:description`            | Yes      |
| `og:image`                  | Yes      |
| `og:url`                    | No       |
| `og:type`                   | No       |
| `twitter:card`              | Yes      |
| `twitter:title`             | No       |
| `twitter:description`       | No       |
| `twitter:image`             | No       |
| `twitter:site`              | No       |

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The SEO app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        seo: true,
    },
});
```

## Structured Data Tab [#structured-data-tab]

The Structured Data tab scans every `<script type="application/ld+json">` block in the page's `<head>` and validates each schema against Schema.org rules.

### What it checks [#what-it-checks]

Each schema is shown as an expandable card with an overall status badge (`Error`, `Warning`, `Info`, `OK`) and per-field messages. `@graph` arrays are expanded into individual cards, each inheriting the parent `@context`.

### Supported Schema.org types [#supported-schemaorg-types]

| Type                                      | Required fields checked                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Article` / `NewsArticle` / `BlogPosting` | `headline` (or `name`), `author.name`, `datePublished` (ISO 8601), `image`                                                                               |
| `Product`                                 | `name`; at least one of `offers`, `aggregateRating`, or `review`; `offers.price` + `offers.priceCurrency`; `aggregateRating.ratingValue` + `reviewCount` |
| `BreadcrumbList`                          | `itemListElement` array (≥ 2 items), sequential `position`, item `name`                                                                                  |
| `FAQPage`                                 | `mainEntity` array (≥ 1 item), each with `name` and `acceptedAnswer.text`                                                                                |
| `Event` / `EventSeries`                   | `name`, `startDate` (ISO 8601), `location.name`                                                                                                          |
| `LocalBusiness` / `Organization`          | `name`, `url`, `logo` (suggestion)                                                                                                                       |
| `Person`                                  | `name`, `url` (suggestion)                                                                                                                               |
| `Recipe`                                  | `name`, `image`, `recipeIngredient`, `recipeInstructions`                                                                                                |
| `WebSite` / `WebPage`                     | `name`, `url`                                                                                                                                            |
| `VideoObject`                             | `name`, `description`, `thumbnailUrl`, `uploadDate` (ISO 8601)                                                                                           |

All schemas are also checked for a valid `@context` referencing `schema.org` and a present `@type`.

### Severity levels [#severity-levels]

| Icon | Level   | Meaning                                                  |
| ---- | ------- | -------------------------------------------------------- |
| ✖    | Error   | Critical issue — schema will not produce rich results    |
| ⚠    | Warning | Missing recommended field — rich results may be degraded |
| ℹ    | Info    | Optional enhancement                                     |
| ✔    | OK      | No issues found                                          |

The tab badge shows the count of schemas with errors (red) or warnings (amber).

## Notes [#notes]

* The SEO app reads from the live DOM — it always reflects the current `<head>` state, including any tags injected by JavaScript after the initial load.
* Use the **Refresh** button in the panel header to re-read the `<head>` after client-side navigation or dynamic tag changes.
* OG image previews make a regular `<img>` request to the image URL. The image must be publicly accessible (or accessible from your dev machine) to render.


# Settings (/docs/packages/dev-toolbar/built-in-apps/settings)



**App ID:** `dev-toolbar:settings`

The Settings app provides a UI for every user-adjustable preference. Changes are applied immediately and persisted to `localStorage` under the key `__v_dt__frame_state`, so they survive page reloads. Plugin-level defaults (from `vite.config.ts`) are used as the initial values; user choices always take priority.

## Setting Groups [#setting-groups]

### Appearance [#appearance]

| Setting           | Description                                                   | Default |
| ----------------- | ------------------------------------------------------------- | ------- |
| **Theme**         | `Light`, `Dark`, or `System` (follows `prefers-color-scheme`) | System  |
| **Reduce motion** | Disable all animations and transitions in the toolbar         | Off     |

### Toolbar [#toolbar]

| Setting                               | Description                                                                                          | Default |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------- |
| **Auto-hide when inactive**           | Collapse the toolbar pill after a period of inactivity. Options: Never, Always, 2 s, 5 s, 10 s, 30 s | 5 s     |
| **Show toolbar when panel is closed** | Keep the toolbar pill visible even when no app panel is open                                         | On      |

### Panel [#panel]

| Setting                    | Description                                                | Default |
| -------------------------- | ---------------------------------------------------------- | ------- |
| **Close on outside click** | Close the DevTools panel when clicking anywhere outside it | On      |

### Editor [#editor]

| Setting              | Description                                                                                                      | Default       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------- |
| **Preferred editor** | Editor used when clicking "Open in editor" in the Inspector. Overrides the plugin-level `editor` option per-user | Auto-detected |

Select from a dropdown of all editors supported by [`launch-editor`](https://github.com/yyx990803/launch-editor) (VS Code, WebStorm, Cursor, Vim, etc.). Choose **Auto-detected** to let `launch-editor` detect the running IDE from the OS process list or `EDITOR` / `VISUAL` environment variables.

### Keyboard Shortcuts [#keyboard-shortcuts]

| Setting            | Description                               | Default           |
| ------------------ | ----------------------------------------- | ----------------- |
| **Toggle toolbar** | Open or close the DevTools panel          | `Alt`+`Shift`+`D` |
| **Close panel**    | Dismiss the active app or close the panel | `Escape`          |

Each keyboard shortcut has a **Record** button that enters capture mode — the next key combination you press (excluding lone modifier keys) is saved as the new binding. A **Reset** link appears next to a customised binding to restore the default.

## Recording a Custom Shortcut [#recording-a-custom-shortcut]

1. Click **Record** next to the shortcut you want to change
2. The button pulses and reads "Press keys…"
3. Press the desired key combination (e.g. `Ctrl`+`Shift`+`F`)
4. The new binding is saved immediately
5. A **Reset** link appears if the binding differs from the default

To cancel without saving, click the &#x2A;*✕** button.

### Supported Key Formats [#supported-key-formats]

Key names follow the browser's `KeyboardEvent.key` specification. Modifier prefixes are:

| Modifier         | Prefix    |
| ---------------- | --------- |
| Alt / Option     | `Alt`     |
| Control          | `Control` |
| Meta / Cmd / Win | `Meta`    |
| Shift            | `Shift`   |

Examples: `Alt+Shift+D`, `Control+Shift+P`, `Meta+K`, `F12`

## localStorage Schema [#localstorage-schema]

All settings are stored as a JSON object:

```ts
interface DevToolsFrameState {
    closeOnOutsideClick: boolean;
    editor: string; // preferred editor key, "" = auto-detect
    height: number; // panel height % (20–95)
    isPip: boolean; // picture-in-picture mode
    isFirstVisit: boolean; // onboarding hint shown
    keybindings: {
        toggle: string; // e.g. "Alt+Shift+D"
        close: string; // e.g. "Escape"
    };
    left: number; // pill horizontal position % (0–100)
    minimizePanelInactive: number; // ms, -1 = never
    open: boolean; // panel open state (never restored on load)
    position: "top" | "bottom" | "left" | "right";
    preferShowFloatingPanel: boolean;
    reduceMotion: boolean;
    route: string;
    top: number; // pill vertical position % (0–100)
    viewMode: "default" | "fullscreen" | "wide";
    width: number; // panel width % (0–100)
}
```

**Storage key:** `__v_dt__frame_state`

## Plugin Defaults [#plugin-defaults]

You can set project-level defaults in `vite.config.ts`. These are used as the initial values when no `localStorage` state exists:

```ts title="vite.config.ts"
devToolbar({
    closeOnOutsideClick: true,
    editor: "webstorm", // seeds the "Preferred editor" dropdown for all users
    height: 60,
    keybindings: {
        toggle: "Alt+Shift+D",
        close: "Escape",
    },
    minimizePanelInactive: 5000,
    position: "bottom",
    reduceMotion: false,
    width: 80,
});
```

User choices in the Settings app always override these defaults.

## View Modes [#view-modes]

The panel supports three view modes accessible via the panel header controls:

| Mode         | Description                                 |
| ------------ | ------------------------------------------- |
| `default`    | Panel fills the configured width percentage |
| `wide`       | Panel expands to 100% viewport width        |
| `fullscreen` | Panel covers the entire viewport            |

View mode can also be set programmatically via the [Global API](/docs/packages/dev-toolbar/custom-apps/global-api).


# Tailwind (/docs/packages/dev-toolbar/built-in-apps/tailwind)





**App ID:** `dev-toolbar:tailwind`

The Tailwind app fetches your project's fully-resolved Tailwind CSS configuration from the dev server and displays all design tokens — colors, spacing, typography, shadows, and more — in a searchable, grouped view.

## What it shows [#what-it-shows]

The panel organizes tokens into tabs:

| Tab            | Contents                                                              |
| -------------- | --------------------------------------------------------------------- |
| **Colors**     | Every color token with a visual swatch and its hex/rgb value          |
| **Spacing**    | Spacing scale values (0, 0.5, 1, 2, 3, 4, ..., 96)                    |
| **Typography** | Font families, font sizes, font weights, line heights, letter spacing |
| **Effects**    | Box shadows, opacity scale, blur values                               |
| **Config**     | Raw CSS custom properties from your `:root` / `@layer theme`          |

Each section supports search — type to filter tokens by name or value.

## How it works [#how-it-works]

1. The Tailwind app calls the built-in `getTailwindConfig()` RPC function on the Vite dev server.
2. The server resolves your CSS using `@tailwindcss/node` and `@tailwindcss/oxide`, extracting all theme tokens.
3. It also scans your document's `:root` stylesheets for CSS custom properties (e.g. `--color-primary`).
4. The resolved tokens are sent to the browser panel and rendered as interactive cards.

<Callout type="info">
  Only **Tailwind CSS v4** is supported. The app returns `null` and shows a "No Tailwind config found" message when no Tailwind v4 CSS is detected. Tailwind
  v3 projects using `tailwind.config.js` are not supported.
</Callout>

## Token resolution [#token-resolution]

Tokens are resolved from two sources:

* **Tailwind theme** — values from `@tailwindcss/node`'s resolved config, including default + user overrides
* **CSS variables** — custom properties found in `:root` rules across all loaded stylesheets

The merged result gives you a complete view of your design system's actual runtime values.

## Enabling the Tailwind app [#enabling-the-tailwind-app]

The Tailwind app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        tailwind: true,
    },
});
```

### Dependencies [#dependencies]

The Tailwind app requires these packages (they should already be in your project if you use Tailwind v4):

* `tailwindcss` (v4+)
* `@tailwindcss/node`
* `@tailwindcss/oxide`

These are listed as `devDependencies` in the dev-toolbar's `package.json` and do not add any runtime overhead — they run only on the Vite dev server.

## Limitations [#limitations]

* **Tailwind v3 not supported** — only v4's CSS-first configuration is compatible.
* **Token display is read-only** — you cannot edit tokens from the panel. Changes must be made in your CSS.
* **CSS variable scanning** is limited to `:root` rules in loaded stylesheets. Variables defined in nested selectors or shadow DOM are not captured.


# Timeline (/docs/packages/dev-toolbar/built-in-apps/timeline)



**App ID:** `dev-toolbar:timeline`

The Timeline app provides a chronological log of events emitted during your application's lifecycle. Your code and any libraries that integrate with the dev toolbar can push events to the timeline; the Timeline app displays them grouped, filterable, and with full detail inspection.

## Features [#features]

* **Real-time event stream** — events appear as they happen
* **Group filtering** — show/hide events from specific libraries or application areas
* **Severity levels** — `info`, `warning`, `error` with colour coding
* **Detail inspection** — click any event to expand its full data payload
* **Clear** — wipe the timeline to start fresh

## Event Structure [#event-structure]

Each timeline event has the following shape:

```ts
interface TimelineEvent {
    /** Unique identifier for the event */
    id: string;

    /** Short display title */
    title: string;

    /** Optional subtitle (e.g. component name, route) */
    subtitle?: string;

    /** Unix timestamp in milliseconds */
    time: number;

    /** Duration in milliseconds (for span events) */
    duration?: number;

    /** Arbitrary data payload shown in the detail pane */
    data?: Record<string, unknown>;

    /** Severity level */
    level?: "info" | "warning" | "error";
}
```

Events are organized into **groups**:

```ts
interface TimelineGroup {
    /** Unique group identifier (e.g. "my-library") */
    id: string;

    /** Display label for the group */
    label: string;

    /** Optional accent colour (CSS colour string) */
    color?: string;
}
```

## Emitting Events [#emitting-events]

### From Your Application [#from-your-application]

Use the global hook to emit events from anywhere in your application:

```ts
const hook = (window as any).__DEV_TOOLBAR_HOOK__;

if (hook) {
    hook.addTimelineEvent("my-app", {
        id: crypto.randomUUID(),
        title: "User signed in",
        subtitle: "auth",
        time: Date.now(),
        level: "info",
        data: {
            userId: "user_123",
            method: "oauth",
        },
    });
}
```

### From a Library [#from-a-library]

Libraries that integrate with the dev toolbar via the hook system get timeline access automatically. See [Library Integration](/docs/packages/dev-toolbar/integrations/library-integration) for the full integration pattern.

```ts
// In your library's dev-mode initialization
if (typeof window !== "undefined" && (window as any).__DEV_TOOLBAR_HOOK__) {
    const hook = (window as any).__DEV_TOOLBAR_HOOK__;

    // Register a group for your library's events
    hook.addTimelineGroup?.("my-library", {
        label: "My Library",
        color: "#6366f1",
    });

    // Emit events as things happen
    myEmitter.on("query:start", (query) => {
        hook.addTimelineEvent("my-library", {
            id: `query-${query.id}`,
            title: `Query: ${query.name}`,
            time: Date.now(),
            level: "info",
            data: query,
        });
    });
}
```

## Panel Walkthrough [#panel-walkthrough]

### Event List [#event-list]

The main area shows all events in reverse-chronological order (newest at the top). Each row shows:

* **Level indicator** — coloured left border (blue = info, yellow = warning, red = error)
* **Title** and optional **subtitle**
* **Group badge** — identifies which library/area emitted the event
* **Timestamp** — relative time from page load

### Group Filter [#group-filter]

A row of toggle chips at the top of the panel lets you show/hide events from each group. Active groups are highlighted; click to toggle.

### Event Detail [#event-detail]

Click any event row to open a detail pane on the right showing:

* Full title and subtitle
* Absolute timestamp
* Duration (for span events)
* Pretty-printed `data` payload as JSON

### Clearing the Timeline [#clearing-the-timeline]

Click **Clear** in the panel header to remove all events from the in-memory store. This does not prevent new events from appearing.

## Configuration [#configuration]

### Enable via Plugin [#enable-via-plugin]

The Timeline app is disabled by default. Enable it in your Vite config:

```ts title="vite.config.ts"
devToolbar({
    apps: {
        timeline: true,
    },
});
```

## Notes [#notes]

* Events are stored in memory only — they are lost on page reload.
* The timeline store is shared with the global API. Events emitted via `window.__DEV_TOOLBAR_HOOK__` before the toolbar has initialized are buffered and replayed once the toolbar mounts.


# Vite Config (/docs/packages/dev-toolbar/built-in-apps/vite-config)



**App ID:** `dev-toolbar:vite-config`

The Vite Config app fetches the resolved (post-plugin) Vite configuration from the dev server via RPC and displays it as collapsible, copyable JSON sections. The configuration shown is what Vite actually uses after all plugins and merges have been applied — the same object you would get from `resolvedConfig` in a plugin's `configResolved` hook.

## Features [#features]

* **Resolved config** — shows the final merged configuration, not your raw `vite.config.ts`
* **Collapsible sections** — Server, Build, and Resolve/Alias sections are independently expandable
* **Copy to clipboard** — each section has a one-click copy button
* **Header badges** — quick-glance `mode`, `root`, and `base` values
* **Refresh** — re-fetch without page reload

## Panel Layout [#panel-layout]

### Header Badges [#header-badges]

The top of the panel shows key configuration values at a glance:

* **Mode badge** — `development` or `production` (uppercase, primary colour)
* **Root path** — the absolute path to the project root
* **Base** — the public base URL, if set to something other than `/`

### Config Sections [#config-sections]

The resolved config is split into three collapsible sections:

| Section             | Contents                                                        |
| ------------------- | --------------------------------------------------------------- |
| **Server**          | Dev server options: host, port, proxy, HMR settings, CORS, etc. |
| **Build**           | Build options: outDir, target, minify, rollupOptions, etc.      |
| **Resolve / Alias** | Module resolution: alias map, extensions, conditions, etc.      |

Each section shows the raw JSON value for that config key. Click the section header to expand/collapse. Click **Copy** to copy the JSON to the clipboard.

### Refresh [#refresh]

Click **Refresh** in the panel header to re-fetch the config. This is useful after plugin changes that trigger a config reload.

## Configuration [#configuration]

### Disable via Plugin [#disable-via-plugin]

```ts title="vite.config.ts"
devToolbar({
    apps: {
        viteConfig: false,
    },
});
```

## What's Included [#whats-included]

The data comes from Vite's `resolvedConfig` object. The toolbar fetches a serialized subset containing:

```ts
{
    mode: string;
    root: string;
    base: string;
    server: ResolvedServerOptions;
    build: ResolvedBuildOptions;
    resolve: ResolvedConfig["resolve"];
}
```

Functions, plugins, and non-serializable values are omitted from the JSON output.

## Notes [#notes]

* The config is fetched fresh on each panel open (or manual refresh). It is not cached.
* The RPC call goes to Vite's development server, so the panel requires an active Vite dev server — it does not work in production builds.
* Sensitive values like environment variables are only shown if they are part of the Vite config object itself (i.e. defined in `vite.config.ts`). `.env` file values are not surfaced.


# Configuration (/docs/packages/dev-toolbar/configuration)





Pass options to the `devToolbar()` plugin in your `vite.config.ts`:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";

export default defineConfig({
    plugins: [
        devToolbar({
            placement: "bottom-center",
            // Opt-in to the apps you want — all are off by default
            apps: {
                inspector: true,
                seo: true,
                performance: true,
                a11y: true,
                timeline: true,
                moduleGraph: true,
                tailwind: true,
                assets: true,
            },
        }),
    ],
});
```

## Plugin Options [#plugin-options]

### `apps` [#apps]

Controls which built-in apps are registered. All optional apps are **disabled by default** — only `viteConfig` and `settings` are shown out of the box. Set an app to `true` to enable it.

```ts
apps?: {
    a11y?: boolean;           // default: false
    annotations?: boolean;    // default: false
    assets?: boolean;         // default: false
    inspector?: boolean;      // default: false
    moduleGraph?: boolean;    // default: false
    performance?: boolean;    // default: false
    seo?: boolean;            // default: false
    settings?: boolean;       // default: true  (always shown)
    tailwind?: boolean;       // default: false
    timeline?: boolean;       // default: false
    viteConfig?: boolean;     // default: true  (always shown)
}
```

**Example** — enable the SEO, Inspector, Annotations, and Performance apps:

```ts
devToolbar({
    apps: {
        annotations: true,
        inspector: true,
        seo: true,
        performance: true,
    },
});
```

***

### `appendTo` [#appendto]

**Type:** `string | RegExp` — &#x2A;*Default:** `''` (auto-detected for supported frameworks)

Append the toolbar import to a specific module ID instead of injecting a `<script>` tag via `transformIndexHtml`.
Use this whenever your project's HTML is not a static file that Vite can transform — most commonly with SSR frameworks.

```ts
devToolbar({
    appendTo: "src/main.ts",
    // or as a regex:
    appendTo: /main\.(ts|js)$/,
});
```

**Auto-detection**

The plugin automatically detects supported SSR frameworks and sets `appendTo` for you:

| Framework      | Detection                                                                    | Auto `appendTo`  |
| -------------- | ---------------------------------------------------------------------------- | ---------------- |
| TanStack Start | `tanstack-start-core:config` or `tanstack-react-start:config` plugin present | `/router\.tsx$/` |

If your framework is auto-detected, you do not need to set `appendTo` manually. An explicit `appendTo` value always takes precedence over auto-detection.

**Why SSR frameworks need this**

Frameworks like TanStack Start, Nuxt, and SvelteKit render the full HTML document on the server at request time.
Vite's `transformIndexHtml` hook is only called when Vite itself serves an HTML file; server-rendered HTML bypasses it entirely.
`appendTo` switches to module-graph injection instead: the toolbar import is prepended to the matched module during Vite's `transform` phase.
Because that hook automatically skips SSR transforms (`transformOptions.ssr === true`), the import is added only to the **client** bundle — never to the server-side render.

<Callout type="warn">
  Only set `appendTo` if you understand exactly what it does. The toolbar import is prepended to the matching module's source code at transform time. Make
  sure the target module is executed in the browser (not server-only code).
</Callout>

***

### `closeOnOutsideClick` [#closeonoutsideclick]

**Type:** `boolean` — &#x2A;*Default:** `true`

Close the DevTools panel when the user clicks outside of it. Users can override this preference in the [Settings app](/docs/packages/dev-toolbar/built-in-apps/settings).

***

### `customApps` [#customapps]

**Type:** `DevToolbarApp[]` — &#x2A;*Default:** `[]`

Register additional custom apps at plugin configuration time. These are added alongside the built-in apps. See [Creating Custom Apps](/docs/packages/dev-toolbar/custom-apps/creating-apps) for the full `DevToolbarApp` interface.

```ts
import type { DevToolbarApp } from "@visulima/dev-toolbar";

const myApp: DevToolbarApp = {
    id: "my-app",
    name: "My App",
    icon: myIconSvgString,
    component: MyAppComponent,
};

devToolbar({
    customApps: [myApp],
});
```

***

### `defaultVisible` [#defaultvisible]

**Type:** `boolean` — &#x2A;*Default:** `true`

Whether the toolbar pill is visible when the page first loads. Set to `false` to hide the toolbar until the user presses the toggle shortcut.

***

### `editor` [#editor]

**Type:** `string` — &#x2A;*Default:** auto-detected

The editor to open when clicking "Open in editor" in the Inspector app.
Accepts any value understood by [`launch-editor`](https://github.com/yyx990803/launch-editor):

* An editor alias: `"code"`, `"webstorm"`, `"vim"`, `"atom"`, `"subl"`
* A full path to the editor executable

When omitted, `launch-editor` auto-detects the editor from the `EDITOR` / `VISUAL`
environment variables, or by scanning the running IDE process list (e.g. it detects
a running WebStorm or VS Code window automatically).

```ts
devToolbar({
    editor: "webstorm",
    // or
    editor: "code",
    // or
    editor: "/usr/local/bin/hx",
});
```

***

### `height` [#height]

**Type:** `number` (20–95) — &#x2A;*Default:** `60`

Initial panel height as a percentage of the viewport height. Users can resize the panel by dragging its top edge; the value is then saved to `localStorage`.

***

### `injectSource` [#injectsource]

**Type:** `{ enabled?: boolean; ignore?: { files?: string[]; components?: string[] } }` — &#x2A;*Default:** `{ enabled: true }`

Controls the JSX source injection transform. When enabled, `data-vdt-source="<file>:<line>:<col>"` attributes are
added to every JSX opening element at build time (development mode only). The Inspector app uses these attributes
to jump directly to the source file when an element is clicked.

Only runs when `config.mode === "development"`. Set `enabled: false` to opt out entirely.

```ts
devToolbar({
    injectSource: {
        enabled: true,

        // Optional: skip specific files or component names
        ignore: {
            files: ["**/generated/**", "**/*.stories.tsx"], // glob patterns
            components: ["StrictMode", "Suspense"], // component names (exact or glob)
        },
    },
});
```

<Callout type="info">
  Source injection reads the unmodified on-disk file so that both SSR and client builds emit identical `data-vdt-source` values. This prevents React hydration
  mismatches in SSR frameworks such as TanStack Start.
</Callout>

***

### `keybindings` [#keybindings]

**Type:** `{ toggle?: string; close?: string }`

Project-level default keyboard shortcuts. These act as the defaults; users can override them in the [Settings app](/docs/packages/dev-toolbar/built-in-apps/settings), and their choices are saved to `localStorage`.

```ts
devToolbar({
    keybindings: {
        toggle: "Alt+Shift+D", // default
        close: "Escape", // default
    },
});
```

Key names follow the `KeyboardEvent.key` property. Modifiers are joined with `+`: `Control`, `Alt`, `Meta`, `Shift`.

***

### `minimizePanelInactive` [#minimizepanelinactive]

**Type:** `number` — &#x2A;*Default:** `5000`

Auto-hide the toolbar pill after this many milliseconds of inactivity (no mouse movement near the toolbar). Set to `-1` to never auto-hide. Set to `0` to always hide immediately when inactive. Users can change this in the [Settings app](/docs/packages/dev-toolbar/built-in-apps/settings).

***

### `placement` [#placement]

**Type:** `"bottom-left" | "bottom-center" | "bottom-right"` — &#x2A;*Default:** `"bottom-center"`

Initial horizontal alignment of the toolbar pill. This is a coarse shorthand that sets both the edge and horizontal position. For full control use `position` + drag to reposition. The toolbar pill is draggable to any position; its final location is saved to `localStorage`.

***

### `position` [#position]

**Type:** `"bottom" | "left" | "right" | "top"` — &#x2A;*Default:** `"bottom"`

Which edge of the viewport the toolbar pill is anchored to. Takes precedence over the edge implied by `placement`.

***

### `reduceMotion` [#reducemotion]

**Type:** `boolean` — &#x2A;*Default:** `false`

Disable animations and transitions in the toolbar. Users can also toggle this in the [Settings app](/docs/packages/dev-toolbar/built-in-apps/settings). When `true`, the toolbar respects `prefers-reduced-motion` at all times.

***

### `removeDevtoolsOnBuild` [#removedevtoolsonbuild]

**Type:** `boolean` — &#x2A;*Default:** `true`

Strip all dev-toolbar virtual modules from the bundle when building for production (i.e. when `command !== 'serve'` or `mode === 'production'`).

The plugin already has `apply: "serve"` so the toolbar is never injected during a standard build. `removeDevtoolsOnBuild` is an explicit safety net that ensures nothing leaks through in edge cases — such as the [`appendTo`](#appendto) option, where the toolbar import is added to a user module that is also present in the production build graph.

When enabled (the default), a second Vite plugin resolves all `virtual:visulima-dev-toolbar-*` imports to an empty module so they are safely tree-shaken away.

```ts
devToolbar({
    // Keep the toolbar in staging / preview builds
    removeDevtoolsOnBuild: false,
});
```

<Callout type="info">
  Leave this at `true` for all standard use cases. Only set it to `false` if you intentionally ship the toolbar in non-development builds (e.g. internal
  staging environments where Vite builds instead of serving).
</Callout>

***

### `requireUrlFlag` [#requireurlflag]

**Type:** `boolean` — &#x2A;*Default:** `false`

When `true`, the toolbar is only injected when the page URL contains the flag specified by `urlFlagName`. Useful for staging environments where you only want the toolbar active on specific URLs.

```ts
devToolbar({
    requireUrlFlag: true,
    urlFlagName: "devtools", // ?devtools or #devtools in URL
});
```

***

### `serverFunctions` [#serverfunctions]

**Type:** `Partial<ServerFunctions>`

Register additional Node.js functions that app components can call over RPC. See [RPC Functions](/docs/packages/dev-toolbar/custom-apps/rpc) for the full pattern.

```ts
import fs from "node:fs/promises";

devToolbar({
    serverFunctions: {
        async getRoutes() {
            const files = await fs.readdir("src/pages");
            return files.map((f) => `/${f.replace(/\.(tsx?|jsx?)$/, "")}`);
        },
    },
});
```

***

### `urlFlagName` [#urlflagname]

**Type:** `string` — &#x2A;*Default:** `"devtools"`

The URL flag name checked when `requireUrlFlag` is `true`. The toolbar activates when the flag appears as a query param (`?devtools`) or hash fragment (`#devtools`).

***

### `width` [#width]

**Type:** `number` — &#x2A;*Default:** `80`

Initial panel width as a percentage of the viewport width. Users can resize the panel by dragging; the value is saved to `localStorage`.

## Complete TypeScript Interface [#complete-typescript-interface]

```ts
interface DevToolbarOptions {
    /**
     * Append toolbar import to this module instead of injecting into HTML.
     * @default ''
     */
    appendTo?: string | RegExp;

    /**
     * Built-in apps to enable. All optional apps are disabled by default.
     * Only viteConfig and settings are shown out of the box.
     */
    apps?: {
        a11y?: boolean;
        annotations?: boolean;
        assets?: boolean;
        inspector?: boolean;
        moduleGraph?: boolean;
        performance?: boolean;
        seo?: boolean;
        settings?: boolean;
        tailwind?: boolean;
        timeline?: boolean;
        viteConfig?: boolean;
    };

    /**
     * Close panel when clicking outside it.
     * @default true
     */
    closeOnOutsideClick?: boolean;

    /**
     * Additional custom apps to register.
     */
    customApps?: DevToolbarApp[];

    /**
     * Show toolbar pill on initial page load.
     * @default true
     */
    defaultVisible?: boolean;

    /**
     * Force a specific editor for open-in-editor. Auto-detected if omitted.
     */
    editor?: string;

    /**
     * Initial panel height as viewport height percentage (20–95).
     * @default 60
     */
    height?: number;

    /**
     * JSX source attribute injection config.
     */
    injectSource?: { enabled?: boolean; ignore?: { files?: string[]; components?: string[] } };

    /**
     * Project-level default keyboard shortcuts.
     * Users can override via the Settings app.
     */
    keybindings?: {
        /** @default "Alt+Shift+D" */
        toggle?: string;
        /** @default "Escape" */
        close?: string;
    };

    /**
     * Auto-hide after N ms of inactivity. -1 = never.
     * @default 5000
     */
    minimizePanelInactive?: number;

    /**
     * Toolbar pill edge alignment.
     * @default "bottom-center"
     */
    placement?: "bottom-left" | "bottom-center" | "bottom-right";

    /**
     * Toolbar pill anchor edge.
     * @default "bottom"
     */
    position?: "bottom" | "left" | "right" | "top";

    /**
     * Disable animations globally.
     * @default false
     */
    reduceMotion?: boolean;

    /**
     * Strip toolbar virtual modules from production builds.
     * @default true
     */
    removeDevtoolsOnBuild?: boolean;

    /**
     * Only activate when URL contains urlFlagName.
     * @default false
     */
    requireUrlFlag?: boolean;

    /**
     * Additional server-side RPC functions.
     */
    serverFunctions?: Partial<ServerFunctions>;

    /**
     * URL flag name for requireUrlFlag.
     * @default "devtools"
     */
    urlFlagName?: string;

    /**
     * Initial panel width as viewport width percentage.
     * @default 80
     */
    width?: number;
}
```


# App API Reference (/docs/packages/dev-toolbar/custom-apps/app-api)



## `DevToolbarApp` [#devtoolbarapp]

The interface that describes a dev toolbar app. Pass instances of this to `customApps` in the plugin options, or to `registerApp()` on the global API.

```ts
interface DevToolbarApp {
    /**
     * Unique identifier for this app.
     * Recommended format: "your-package:app-name"
     * Must not conflict with built-in IDs (see table below).
     */
    id: string;

    /**
     * Display name shown in the toolbar tooltip and panel header.
     */
    name: string;

    /**
     * Raw SVG string for the toolbar button icon.
     * Use an import with ?raw to get the SVG source:
     *   import myIcon from "./icon.svg?raw";
     */
    icon: string;

    /**
     * The main Preact component rendered in the panel when the app is open.
     * Must accept AppComponentProps.
     */
    component: ComponentType<AppComponentProps>;

    /**
     * Optional compact Preact component rendered in the tooltip on button hover.
     * Receives the same AppComponentProps as the main component.
     */
    tooltip?: ComponentType<AppComponentProps>;

    /**
     * Optional rendering mode. Defaults to inline (Shadow DOM).
     * Set to { type: "iframe", src: "..." } to load a URL in a full-size iframe.
     * When view is set, component and init are ignored.
     */
    view?: AppView;
}
```

### Reserved App IDs [#reserved-app-ids]

Do not use these IDs for custom apps:

| ID                         | App           |
| -------------------------- | ------------- |
| `dev-toolbar:a11y`         | Accessibility |
| `dev-toolbar:annotations`  | Annotations   |
| `dev-toolbar:assets`       | Assets        |
| `dev-toolbar:inspector`    | Inspector     |
| `dev-toolbar:module-graph` | Module Graph  |
| `dev-toolbar:performance`  | Performance   |
| `dev-toolbar:seo`          | SEO           |
| `dev-toolbar:settings`     | Settings      |
| `dev-toolbar:tailwind`     | Tailwind      |
| `dev-toolbar:timeline`     | Timeline      |
| `dev-toolbar:vite-config`  | Vite Config   |

***

## `AppView` [#appview]

Controls how the app content is rendered inside the panel.

```ts
type AppView =
    | {
          /** Render the app inline in the Shadow DOM (default). */
          type: "inline";
      }
    | {
          /** Load a URL in a full-size iframe. */
          type: "iframe";
          /** The URL to load. */
          src: string;
      };
```

When `view` is omitted, the toolbar defaults to `{ type: "inline" }` and renders the `component` (or calls `init`) inside the panel's Shadow DOM.

When `view: { type: "iframe", src }` is set:

* `component` and `init` are ignored.
* The panel renders a borderless `<iframe>` that fills the content area.
* The toolbar chrome (resize handles, fullscreen, PiP) works as normal.

***

## `AppComponentProps` [#appcomponentprops]

Props passed to every app component (both main panel and tooltip):

```ts
interface AppComponentProps {
    /**
     * Helper object providing access to server-side RPC functions.
     *
     * Cast to your typed interface for full type safety:
     *   const rpc = helpers.rpc as unknown as MyServerFunctions;
     */
    helpers: {
        rpc: ServerFunctions & Record<string, (...args: any[]) => Promise<any>>;
    };
}
```

***

## `ServerFunctions` [#serverfunctions]

The built-in server functions available via `helpers.rpc`:

```ts
interface ServerFunctions {
    /**
     * Returns the resolved Vite configuration (serializable subset).
     */
    getViteConfig(): Promise<{
        mode: string;
        root: string;
        base: string;
        server: Record<string, unknown>;
        build: Record<string, unknown>;
        resolve: Record<string, unknown>;
    }>;

    /**
     * Returns the current Vite module graph as a flat array.
     */
    getModuleGraph(): Promise<
        Array<{
            id: string;
            url: string;
            importerCount: number;
            importerUrls: string[];
        }>
    >;

    /**
     * Returns the resolved Tailwind CSS design tokens. Returns null if no Tailwind config found.
     */
    getTailwindConfig(): Promise<Record<string, unknown> | null>;

    /**
     * Reads a file relative to the project root and returns its UTF-8 content.
     */
    readFile(path: string): Promise<string>;

    /**
     * Opens a file in the configured editor.
     * Respects the LAUNCH_EDITOR environment variable; defaults to VS Code.
     */
    openInEditor(file: string, line?: number, column?: number): Promise<void>;

    /**
     * Returns all annotations from .devtoolbar/annotations.json.
     */
    getAnnotations(): Promise<Annotation[]>;

    /**
     * Creates a new annotation. Server generates id and timestamps.
     */
    createAnnotation(data: CreateAnnotationData): Promise<Annotation>;

    /**
     * Updates an existing annotation.
     */
    updateAnnotation(id: string, data: UpdateAnnotationData): Promise<Annotation>;

    /**
     * Deletes an annotation and its screenshot.
     */
    deleteAnnotation(id: string): Promise<void>;

    /**
     * Returns a screenshot as a base64 data URL.
     */
    getScreenshot(annotationId: string): Promise<string>;

    /**
     * Saves a screenshot from a data URL. Returns the relative file path.
     */
    saveScreenshot(annotationId: string, dataUrl: string): Promise<string>;
}
```

***

## `TimelineEvent` [#timelineevent]

Events emitted to the Timeline app:

```ts
interface TimelineEvent {
    /** Unique event ID */
    id: string;

    /** Short display title */
    title: string;

    /** Optional subtitle (component name, route, etc.) */
    subtitle?: string;

    /** Unix timestamp in milliseconds */
    time: number;

    /** Optional duration for span events (milliseconds) */
    duration?: number;

    /** Arbitrary data payload, displayed as JSON in the detail pane */
    data?: Record<string, unknown>;

    /** Severity level for colour coding */
    level?: "info" | "warning" | "error";
}
```

***

## `DevToolbarHook` [#devtoolbarhook]

The global hook interface — available at `window.__DEV_TOOLBAR_HOOK__`:

```ts
interface DevToolbarHook {
    /**
     * Subscribe to a hook event. Returns an unsubscribe function.
     */
    on<T extends keyof HookEvents>(event: T, handler: HookEvents[T]): () => void;

    /**
     * Subscribe to a hook event once.
     */
    once<T extends keyof HookEvents>(event: T, handler: HookEvents[T]): void;

    /**
     * Unsubscribe from a hook event.
     */
    off<T extends keyof HookEvents>(event: T, handler?: HookEvents[T]): void;

    /**
     * Emit a hook event.
     */
    emit<T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>): void;

    /**
     * Register an app via the hook (equivalent to customApps in plugin options).
     * Safe to call before the toolbar has initialized — buffered and replayed.
     */
    registerApp(app: DevToolbarApp): void;

    /**
     * Add an event to the Timeline app.
     * Safe to call before the toolbar has initialized — buffered and replayed.
     */
    addTimelineEvent(groupId: string, event: TimelineEvent): void;
}
```

***

## `HookEvents` [#hookevents]

Events available on the hook system:

```ts
interface HookEvents {
    /** Fired once when the toolbar has mounted and is ready */
    "devtools:init": () => void;

    /** Fired when an app panel is opened */
    "devtools:open": (appId: string) => void;

    /** Fired when the panel is closed */
    "devtools:close": () => void;

    /** Fired when an app component throws an unhandled error */
    "app:error": (error: Error, appId?: string) => void;

    /** Fired when a timeline event is added */
    "timeline:event": (event: TimelineEvent) => void;

    /** Custom events — any string key is valid */
    [key: string]: (...args: any[]) => void;
}
```

***

## Global DevTools API [#global-devtools-api]

Available at `window.__VISULIMA_DEVTOOLS__`. See the [Global API](/docs/packages/dev-toolbar/custom-apps/global-api) page for full documentation.

```ts
interface VisulimaDevToolsAPI {
    // Visibility
    show(): void;
    hide(): void;
    toggle(): void;

    // App management
    openApp(id: string): Promise<void>;
    closeApp(): void;
    getActiveApp(): DevToolbarApp | null;
    registerApp(app: DevToolbarApp, isCore?: boolean): void;
    unregisterApp(id: string): void;
    getApps(): DevToolbarApp[];

    // Notifications
    notify(appId: string, type: "info" | "warning" | "error"): void;
    clearNotification(appId: string): void;

    // Settings
    getSettings(): DevToolsFrameState;
    updateSettings(patch: Partial<DevToolsFrameState>): void;

    // RPC
    rpc: ServerFunctions;

    // Hook
    hook: DevToolbarHook;
}
```


# Creating Custom Apps (/docs/packages/dev-toolbar/custom-apps/creating-apps)





Custom apps let you embed any developer tool inside the toolbar panel. Each app appears as a button in the toolbar pill; clicking it opens your component in the resizable panel. Apps can also have a **tooltip** — a compact preview that appears on hover without opening the full panel.

## Quick Example [#quick-example]

```tsx title="my-app.tsx"
/** @jsxImportSource preact */
import type { ComponentChildren } from "preact";
import type { AppComponentProps } from "@visulima/dev-toolbar";

const MyApp = ({ helpers }: AppComponentProps): ComponentChildren => {
    return (
        <div style={{ padding: "20px" }}>
            <h2>Hello from My App!</h2>
        </div>
    );
};

export default MyApp;
```

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";
import myIconSvg from "./my-icon.svg?raw";
import MyApp from "./my-app";

export default defineConfig({
    plugins: [
        devToolbar({
            customApps: [
                {
                    id: "my-package:my-app",
                    name: "My App",
                    icon: myIconSvg, // raw SVG string
                    component: MyApp,
                },
            ],
        }),
    ],
});
```

<Callout type="info">
  App components are Preact components rendered inside the Shadow DOM. The JSX pragma `/** @jsxImportSource preact */` can be added per `.tsx` file, or set
  globally in `tsconfig.json` via `"jsxImportSource": "preact"`.
</Callout>

## Step-by-Step Guide [#step-by-step-guide]

<Steps>
  <Step>
    ### Define the App Component [#define-the-app-component]

    Create a Preact component that receives `AppComponentProps`:

    ```tsx title="src/devtools/my-app.tsx"
    /** @jsxImportSource preact */
    import type { ComponentChildren } from "preact";
    import { useState } from "preact/hooks";
    import type { AppComponentProps } from "@visulima/dev-toolbar";

    const MyApp = ({ helpers }: AppComponentProps): ComponentChildren => {
        const [data, setData] = useState<string | null>(null);

        const load = async (): Promise<void> => {
            // Call a server-side RPC function
            const result = await (helpers.rpc as any).myCustomFunction();
            setData(JSON.stringify(result, null, 2));
        };

        return (
            <div class="p-4 space-y-4">
                <button class="px-3 py-1.5 border border-border text-sm cursor-pointer bg-transparent text-foreground" onClick={load} type="button">
                    Load Data
                </button>
                {data && <pre class="text-xs font-mono text-foreground/80 bg-foreground/5 p-4 overflow-auto">{data}</pre>}
            </div>
        );
    };

    export default MyApp;
    ```
  </Step>

  <Step>
    ### (Optional) Add a Tooltip [#optional-add-a-tooltip]

    A tooltip shows a compact summary when the user hovers the app button — without opening the full panel:

    ```tsx title="src/devtools/my-tooltip.tsx"
    /** @jsxImportSource preact */
    import type { ComponentChildren } from "preact";
    import type { AppComponentProps } from "@visulima/dev-toolbar";

    const MyTooltip = (_props: AppComponentProps): ComponentChildren => {
        return (
            <div class="p-3 text-sm text-foreground">
                <p>Quick summary goes here</p>
            </div>
        );
    };

    export default MyTooltip;
    ```
  </Step>

  <Step>
    ### Register in `vite.config.ts` [#register-in-viteconfigts]

    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import { devToolbar } from "@visulima/dev-toolbar/vite";
    import myIconSvg from "./src/devtools/my-icon.svg?raw";
    import MyApp from "./src/devtools/my-app";
    import MyTooltip from "./src/devtools/my-tooltip";

    export default defineConfig({
        plugins: [
            devToolbar({
                customApps: [
                    {
                        id: "my-package:my-app", // must be unique
                        name: "My App", // shown in tooltip and panel header
                        icon: myIconSvg, // raw SVG string
                        component: MyApp,
                        tooltip: MyTooltip, // optional
                    },
                ],
            }),
        ],
    });
    ```
  </Step>

  <Step>
    ### (Optional) Add Server RPC Functions [#optional-add-server-rpc-functions]

    If your app needs to talk to Node.js (read files, call APIs, inspect the build), add server RPC functions. See the [RPC documentation](/docs/packages/dev-toolbar/custom-apps/rpc) for details.
  </Step>
</Steps>

## App Component Props [#app-component-props]

```ts
interface AppComponentProps {
    /**
     * RPC helper — provides access to server-side functions.
     * Cast to your typed interface for full type safety.
     */
    helpers: {
        rpc: ServerFunctions & Record<string, (...args: any[]) => Promise<any>>;
    };
}
```

## App Definition [#app-definition]

```ts
interface DevToolbarApp {
    /** Unique identifier. Use a namespaced format: "my-lib:my-app" */
    id: string;

    /** Display name shown in the toolbar and panel header */
    name: string;

    /** Raw SVG string for the toolbar button icon */
    icon: string;

    /** Main panel component */
    component: ComponentType<AppComponentProps>;

    /** Optional compact tooltip component shown on hover */
    tooltip?: ComponentType<AppComponentProps>;
}
```

## Styling [#styling]

App components are rendered inside Shadow DOM with Tailwind CSS v4 available. Use Tailwind utility classes directly. The design system uses CSS custom properties for theming:

| Token                   | Usage                         |
| ----------------------- | ----------------------------- |
| `text-foreground`       | Primary text                  |
| `text-muted-foreground` | Secondary/disabled text       |
| `bg-background`         | Panel background              |
| `bg-card`               | Card/section background       |
| `bg-primary`            | Brand accent (lime `#caff00`) |
| `text-primary`          | Brand accent text             |
| `border-border`         | Standard border colour        |

For example:

```tsx
<div class="p-5 space-y-4">
    <h2 class="text-xs font-bold uppercase tracking-widest text-muted-foreground">// My Section</h2>
    <div class="border border-border bg-card p-4">
        <p class="text-sm text-foreground">Content goes here</p>
    </div>
</div>
```

## Iframe Apps [#iframe-apps]

Instead of a Preact component, you can load any URL inside the panel using `view: { type: "iframe", src: "..." }`. The URL is rendered in a full-size `<iframe>` that fills the panel area — useful for embedding existing web pages, Storybook, Swagger UI, or any standalone dev tool.

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";
import myIconSvg from "./my-icon.svg?raw";

export default defineConfig({
    plugins: [
        devToolbar({
            customApps: [
                {
                    id: "my-package:storybook",
                    name: "Storybook",
                    icon: myIconSvg,
                    view: {
                        type: "iframe",
                        src: "http://localhost:6006",
                    },
                },
            ],
        }),
    ],
});
```

Iframe apps:

* Do **not** use a `component` or `init` — set only `view`.
* Cannot access `helpers.rpc` from inside the iframe (different origin).
* The toolbar header, resize handles, and fullscreen/PiP controls all work normally.

## Dynamic Registration [#dynamic-registration]

Apps can also be registered at runtime via the [Global API](/docs/packages/dev-toolbar/custom-apps/global-api):

```ts
const api = (window as any).__VISULIMA_DEVTOOLS__;

if (api) {
    api.registerApp({
        id: "my-package:dynamic-app",
        name: "Dynamic App",
        icon: svgString,
        component: MyDynamicApp,
    });
}
```

## App ID Conventions [#app-id-conventions]

Use a namespaced format to avoid collisions with built-in apps and other libraries:

```
your-package:app-name
```

Built-in app IDs use the `dev-toolbar:` prefix — do not use this prefix for custom apps.

| Reserved                   | Reason   |
| -------------------------- | -------- |
| `dev-toolbar:a11y`         | Built-in |
| `dev-toolbar:annotations`  | Built-in |
| `dev-toolbar:assets`       | Built-in |
| `dev-toolbar:inspector`    | Built-in |
| `dev-toolbar:module-graph` | Built-in |
| `dev-toolbar:performance`  | Built-in |
| `dev-toolbar:seo`          | Built-in |
| `dev-toolbar:settings`     | Built-in |
| `dev-toolbar:tailwind`     | Built-in |
| `dev-toolbar:timeline`     | Built-in |
| `dev-toolbar:vite-config`  | Built-in |


# Global API (/docs/packages/dev-toolbar/custom-apps/global-api)





The global API is available at `window.__VISULIMA_DEVTOOLS__` during development. It provides programmatic control over every aspect of the toolbar — useful for integration testing, browser console debugging, and runtime app registration.

<Callout type="warn">
  The global API is only available in development mode. Always guard calls with an existence check.
</Callout>

```ts
const api = (window as any).__VISULIMA_DEVTOOLS__;

if (api) {
    // safe to use
}
```

***

## Visibility [#visibility]

### `show()` [#show]

Show the toolbar pill (if hidden via `hide()` or auto-hide).

```ts
api.show();
```

### `hide()` [#hide]

Hide the toolbar pill.

```ts
api.hide();
```

### `toggle()` [#toggle]

Toggle the toolbar pill visibility.

```ts
api.toggle();
```

***

## App Management [#app-management]

### `openApp(id: string): Promise<void>` [#openappid-string-promisevoid]

Open an app panel by its ID. The panel slides into view and the app component mounts.

```ts
await api.openApp("dev-toolbar:a11y");
await api.openApp("my-package:my-app");
```

### `closeApp(): void` [#closeapp-void]

Close the currently open app panel.

```ts
api.closeApp();
```

### `getActiveApp(): DevToolbarApp | null` [#getactiveapp-devtoolbarapp--null]

Returns the currently open app, or `null` if the panel is closed.

```ts
const app = api.getActiveApp();
console.log(app?.id); // "dev-toolbar:a11y"
```

### `registerApp(app: DevToolbarApp, isCore?: boolean): void` [#registerappapp-devtoolbarapp-iscore-boolean-void]

Register a new app at runtime. The app button appears in the toolbar immediately.

```ts
api.registerApp({
    id: "my-package:inspector",
    name: "Inspector",
    icon: svgString,
    component: InspectorApp,
});
```

Set `isCore = true` to place the app in the main toolbar row (alongside built-in apps). Without this flag, the app appears in the "More" overflow panel.

### `unregisterApp(id: string): void` [#unregisterappid-string-void]

Remove an app from the toolbar. The app button disappears immediately.

```ts
api.unregisterApp("my-package:inspector");
```

### `getApps(): DevToolbarApp[]` [#getapps-devtoolbarapp]

Returns the full list of registered apps (built-in + custom).

```ts
const apps = api.getApps();
apps.forEach((app) => console.log(app.id, app.name));
```

***

## Notifications [#notifications]

Show a notification badge on an app button to draw the user's attention.

### `notify(appId: string, type: "info" | "warning" | "error"): void` [#notifyappid-string-type-info--warning--error-void]

```ts
api.notify("my-package:monitor", "warning");
```

The notification badge appears on the app's toolbar button. Clicking the button clears the notification and opens the app.

### `clearNotification(appId: string): void` [#clearnotificationappid-string-void]

Remove a notification badge without opening the app.

```ts
api.clearNotification("my-package:monitor");
```

***

## Settings [#settings]

### `getSettings(): DevToolsFrameState` [#getsettings-devtoolsframestate]

Returns the current toolbar state (position, size, theme preferences, keybindings, etc.).

```ts
const settings = api.getSettings();
console.log(settings.position); // "bottom"
console.log(settings.width); // 80
console.log(settings.keybindings); // { toggle: "Alt+Shift+D", close: "Escape" }
```

### `updateSettings(patch: Partial<DevToolsFrameState>): void` [#updatesettingspatch-partialdevtoolsframestate-void]

Merge a partial update into the current state. Changes are persisted to `localStorage` immediately.

```ts
// Move panel to a different edge
api.updateSettings({ position: "right" });

// Change panel to fullscreen mode
api.updateSettings({ viewMode: "fullscreen" });

// Update keyboard shortcuts
api.updateSettings({
    keybindings: {
        toggle: "Control+Shift+D",
        close: "Escape",
    },
});
```

***

## RPC [#rpc]

### `rpc` [#rpc-1]

Direct access to the server-side RPC functions — the same object available as `helpers.rpc` inside app components.

```ts
// Read the resolved Vite config from the console
const config = await api.rpc.getViteConfig();
console.log(config.server.port);

// Open a file in the editor
await api.rpc.openInEditor("/src/components/Button.tsx", 42);

// Browse the module graph
const modules = await api.rpc.getModuleGraph();
const heaviest = [...modules].sort((a, b) => b.importerCount - a.importerCount).slice(0, 5);
```

***

## Hook [#hook]

### `hook` [#hook-1]

Access to the same hook system available via `window.__DEV_TOOLBAR_HOOK__`. Useful for emitting events and subscribing from non-component code.

```ts
// Subscribe to panel open events
api.hook.on("devtools:open", (appId) => {
    console.log("App opened:", appId);
});

// Add a timeline event
api.hook.addTimelineEvent("my-app", {
    id: crypto.randomUUID(),
    title: "Data fetched",
    time: Date.now(),
    level: "info",
    data: { url: "/api/users", count: 42 },
});
```

***

## Console Debugging [#console-debugging]

The global API is useful for debugging directly in the browser console:

```js
// Quickly open the Accessibility app
__VISULIMA_DEVTOOLS__.openApp("dev-toolbar:a11y");

// Check current panel size
__VISULIMA_DEVTOOLS__.getSettings().width;

// List all registered apps
__VISULIMA_DEVTOOLS__.getApps().map((a) => a.id);

// Trigger a fullscreen view
__VISULIMA_DEVTOOLS__.updateSettings({ viewMode: "fullscreen" });
```

***

## Full Type Reference [#full-type-reference]

```ts
interface VisulimaDevToolsAPI {
    // Visibility
    show(): void;
    hide(): void;
    toggle(): void;

    // App management
    openApp(id: string): Promise<void>;
    closeApp(): void;
    getActiveApp(): DevToolbarApp | null;
    registerApp(app: DevToolbarApp, isCore?: boolean): void;
    unregisterApp(id: string): void;
    getApps(): DevToolbarApp[];

    // Notifications
    notify(appId: string, type: "info" | "warning" | "error"): void;
    clearNotification(appId: string): void;

    // Settings
    getSettings(): DevToolsFrameState;
    updateSettings(patch: Partial<DevToolsFrameState>): void;

    // RPC access
    rpc: ServerFunctions;

    // Hook system access
    hook: DevToolbarHook;
}
```


# RPC Functions (/docs/packages/dev-toolbar/custom-apps/rpc)





The RPC (Remote Procedure Call) layer provides type-safe communication between the browser (client) and Vite's Node.js dev server (server). Built-in RPC functions cover common tasks like reading the Vite config, walking the module graph, and opening files in an editor. You can also add your own server functions.

## Built-in Server Functions [#built-in-server-functions]

These functions are available on `helpers.rpc` in every app component:

### `getViteConfig()` [#getviteconfig]

Returns the resolved Vite configuration as a plain serializable object.

```ts
const config = await (helpers.rpc as any).getViteConfig();
// { mode: "development", root: "/path/to/project", server: { ... }, ... }
```

### `getModuleGraph()` [#getmodulegraph]

Returns the current Vite module graph as an array of module entries.

```ts
const modules = await (helpers.rpc as any).getModuleGraph();
// [{ id: "/src/main.ts", url: "/src/main.ts", importerCount: 0, importerUrls: [] }, ...]
```

Each module entry:

```ts
interface ModuleEntry {
    id: string;
    url: string;
    importerCount: number;
    importerUrls: string[];
}
```

### `getTailwindConfig()` [#gettailwindconfig]

Returns the resolved Tailwind CSS design tokens from the project's CSS. Returns `null` when no Tailwind config is found.

```ts
const tokens = await (helpers.rpc as any).getTailwindConfig();
// { colors: { primary: "#...", ... }, spacing: { ... }, ... } | null
```

### `readFile(path)` [#readfilepath]

Reads a file relative to the project root (or absolute) and returns its UTF-8 content.

```ts
const content = await (helpers.rpc as any).readFile("package.json");
```

### `openInEditor(file, line?, column?)` [#openineditorfile-line-column]

Opens a file in the configured editor using [`launch-editor`](https://github.com/yyx990803/launch-editor), which knows the right CLI flags for each editor (`--goto` for VS Code, `-l` for vim, etc.).

The editor is auto-detected from the `EDITOR` / `VISUAL` environment variables or by scanning running IDE processes. Override it project-wide with the [`editor`](/docs/packages/dev-toolbar/configuration#editor) plugin option.

```ts
await (helpers.rpc as any).openInEditor("/absolute/path/to/file.ts", 10, 5);
// Opens file.ts at line 10, column 5
```

### `getAnnotations()` [#getannotations]

Returns all annotations stored in `.devtoolbar/annotations.json`.

```ts
const annotations = await (helpers.rpc as any).getAnnotations();
// [{ id: "abc", comment: "Fix alignment", intent: "fix", status: "pending", ... }]
```

### `createAnnotation(data)` [#createannotationdata]

Creates a new annotation. The server generates the `id`, `createdAt`, and `updatedAt` fields.

```ts
await (helpers.rpc as any).createAnnotation({
    comment: "Fix this button alignment",
    intent: "fix",
    severity: "important",
    elementTag: "button",
    url: window.location.href,
    x: 50,
    y: 200,
});
```

### `updateAnnotation(id, data)` [#updateannotationid-data]

Updates an existing annotation's comment, intent, severity, status, or adds a thread message.

```ts
await (helpers.rpc as any).updateAnnotation("abc123", {
    status: "resolved",
    resolvedBy: "human",
});
```

### `deleteAnnotation(id)` [#deleteannotationid]

Deletes an annotation and its associated screenshot file.

```ts
await (helpers.rpc as any).deleteAnnotation("abc123");
```

### `getScreenshot(annotationId)` [#getscreenshotannotationid]

Returns the screenshot for an annotation as a base64 data URL.

```ts
const dataUrl = await (helpers.rpc as any).getScreenshot("abc123");
// "data:image/png;base64,iVBOR..."
```

### `saveScreenshot(annotationId, dataUrl)` [#savescreenshotannotationid-dataurl]

Saves a screenshot from a data URL. Returns the relative file path.

```ts
const path = await (helpers.rpc as any).saveScreenshot("abc123", dataUrl);
// "screenshots/abc123.png"
```

## Custom Server Functions [#custom-server-functions]

Add your own Node.js functions by passing them to the plugin's `serverFunctions` option:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";
import fs from "node:fs/promises";

export default defineConfig({
    plugins: [
        devToolbar({
            serverFunctions: {
                async getPackageJson() {
                    const raw = await fs.readFile("package.json", "utf8");
                    return JSON.parse(raw);
                },

                async listRoutes() {
                    // Return application routes, read from the filesystem, etc.
                    const files = await fs.readdir("src/pages");
                    return files.map((f) => `/${f.replace(/\.(tsx?|jsx?)$/, "")}`);
                },
            },
        }),
    ],
});
```

Then call them from your app component:

```tsx title="my-app.tsx"
/** @jsxImportSource preact */
import { useEffect, useState } from "preact/hooks";
import type { AppComponentProps } from "@visulima/dev-toolbar";

const MyApp = ({ helpers }: AppComponentProps) => {
    const [routes, setRoutes] = useState<string[]>([]);

    useEffect(() => {
        (helpers.rpc as any).listRoutes().then(setRoutes);
    }, []);

    return (
        <ul class="p-4 space-y-1">
            {routes.map((route) => (
                <li key={route} class="text-sm font-mono text-foreground/80">
                    {route}
                </li>
            ))}
        </ul>
    );
};
```

## Type-Safe RPC [#type-safe-rpc]

For full TypeScript type safety, define an interface for your server functions and use it on both sides:

```ts title="src/devtools/rpc-types.ts"
export interface MyServerFunctions {
    getPackageJson(): Promise<Record<string, unknown>>;
    listRoutes(): Promise<string[]>;
    readEnvVars(): Promise<Record<string, string>>;
}
```

```ts title="vite.config.ts"
import type { MyServerFunctions } from "./src/devtools/rpc-types";

devToolbar({
    serverFunctions: {
        async getPackageJson() { ... },
        async listRoutes() { ... },
        async readEnvVars() { ... },
    } satisfies MyServerFunctions,
})
```

```tsx title="my-app.tsx"
/** @jsxImportSource preact */
import { useEffect, useState } from "preact/hooks";
import type { AppComponentProps } from "@visulima/dev-toolbar";
import type { MyServerFunctions } from "./rpc-types";

const MyApp = ({ helpers }: AppComponentProps) => {
    const [routes, setRoutes] = useState<string[]>([]);
    const rpc = helpers.rpc as unknown as MyServerFunctions;

    useEffect(() => {
        rpc.listRoutes().then(setRoutes); // fully typed!
    }, []);

    return (
        <ul class="p-4 space-y-1">
            {routes.map((route) => (
                <li key={route} class="text-sm font-mono text-foreground/80">
                    {route}
                </li>
            ))}
        </ul>
    );
};
```

## How RPC Works [#how-rpc-works]

Under the hood, the RPC layer uses Vite's HMR WebSocket channel:

1. The client calls `helpers.rpc.functionName(args)` — this sends a message over the Vite HMR WebSocket
2. The Vite plugin receives the message, calls the matching server function, and serializes the result
3. The result is sent back over the WebSocket and resolves the promise on the client

<Callout type="info">
  RPC calls only work during development with an active Vite dev server. In production builds, the toolbar and its RPC layer are not present.
</Callout>

## Error Handling [#error-handling]

RPC calls return promises. If the server function throws, the promise rejects with the error message:

```ts
try {
    const config = await (helpers.rpc as any).getViteConfig();
} catch (err) {
    console.error("RPC failed:", err instanceof Error ? err.message : String(err));
}
```

For UI error states, display a retry button:

```tsx
const [error, setError] = useState<string | null>(null);

const load = async (): Promise<void> => {
    try {
        const data = await (helpers.rpc as any).myFunction();
        setData(data);
    } catch (err) {
        setError(err instanceof Error ? err.message : "Failed to load");
    }
};

if (error) {
    return (
        <div class="p-8 text-center">
            <p class="text-sm text-destructive">{error}</p>
            <button onClick={load} type="button">
                Retry
            </button>
        </div>
    );
}
```

## Limitations [#limitations]

* RPC function arguments and return values must be JSON-serializable (no `Function`, `Symbol`, `undefined` values, circular references, etc.)
* Server functions run in Vite's Node.js context — they have access to the filesystem and Node.js APIs, but not to the browser DOM
* Each RPC call is a round-trip over the WebSocket; avoid calling RPC inside tight loops


# Getting Started (/docs/packages/dev-toolbar/getting-started)





**Prerequisites:** Vite 6, 7, or 8 · Node.js 22.21+

<Steps>
  <Step>
    ## Install [#install]

    <Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
      <Tab value="npm">
        `bash npm install -D @visulima/dev-toolbar `
      </Tab>

      <Tab value="pnpm">
        `bash pnpm add -D @visulima/dev-toolbar `
      </Tab>

      <Tab value="yarn">
        `bash yarn add -D @visulima/dev-toolbar `
      </Tab>

      <Tab value="bun">
        `bash bun add -d @visulima/dev-toolbar `
      </Tab>
    </Tabs>

    <Callout type="info">
      The package is a development-only tool. It is automatically excluded from production builds — the Vite plugin no-ops when `command !== 'serve'`.
    </Callout>
  </Step>

  <Step>
    ## Add the Vite Plugin [#add-the-vite-plugin]

    Open your `vite.config.ts` and add the `devToolbar` plugin:

    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import { devToolbar } from "@visulima/dev-toolbar/vite";

    export default defineConfig({
        plugins: [devToolbar()],
    });
    ```

    That's it. Start your dev server and press &#x2A;*`Alt`+`Shift`+`D`** to open the toolbar.
  </Step>

  <Step>
    ## Open the Toolbar [#open-the-toolbar]

    A small pill appears at the bottom-center of your page. Click any app icon to open its panel, or use the keyboard shortcut:

    | Action                    | Shortcut          |
    | ------------------------- | ----------------- |
    | Toggle toolbar open/close | `Alt`+`Shift`+`D` |
    | Close active app / panel  | `Escape`          |
  </Step>
</Steps>

## Minimal Configuration [#minimal-configuration]

By default only the **Vite Config** and **Settings** apps are shown. Enable whichever optional apps you need:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";

export default defineConfig({
    plugins: [
        devToolbar({
            // Toolbar placement
            placement: "bottom-right",

            // Opt-in to the apps you want
            apps: {
                inspector: true,
                performance: true,
                seo: true,
            },

            // Change the default keyboard shortcuts
            keybindings: {
                toggle: "Alt+Shift+D",
                close: "Escape",
            },
        }),
    ],
});
```

## Using with SSR Frameworks [#using-with-ssr-frameworks]

SSR frameworks such as **TanStack Start**, **Nuxt**, and **SvelteKit** render the full HTML document server-side.
Vite's `transformIndexHtml` hook — which the toolbar normally uses to inject its `<script>` — is never called on those server-rendered responses.

### TanStack Start (auto-detected) [#tanstack-start-auto-detected]

The plugin automatically detects TanStack Start and injects the toolbar via the module graph (targeting `router.tsx`) — no extra configuration needed:

```ts title="vite.config.ts"
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { devToolbar } from "@visulima/dev-toolbar/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [tanstackStart(), viteReact(), devToolbar()],
});
```

<Callout type="info">
  Because TanStack Start renders on the server, any `window.__DEV_TOOLBAR_HOOK__` calls must be placed inside a `useEffect` to ensure they only run in the browser:

  ```tsx
  React.useEffect(() => {
      if (typeof window !== "undefined" && window.__DEV_TOOLBAR_HOOK__) {
          window.__DEV_TOOLBAR_HOOK__.addTimelineEvent("custom", { /* ... */ });
      }
  }, []);
  ```
</Callout>

### Other SSR / Non-HTML Setups [#other-ssr--non-html-setups]

For any project without a static `index.html` entry point that is not auto-detected, use the `appendTo` option to inject the toolbar via the JavaScript module graph instead of the HTML pipeline.
The `transform` hook that powers `appendTo` automatically skips SSR builds (`transformOptions.ssr === true`), so the import is only added to the client bundle.

Point `appendTo` at a module that is guaranteed to run client-side only:

```ts title="vite.config.ts"
devToolbar({
    appendTo: "src/main.ts",
});
```

## Framework Examples [#framework-examples]

<Tabs items="[&#x22;React&#x22;, &#x22;Vue&#x22;, &#x22;Svelte&#x22;, &#x22;Vanilla&#x22;, &#x22;TanStack Start&#x22;]">
  <Tab value="React">
    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react";
    import { devToolbar } from "@visulima/dev-toolbar/vite";

    export default defineConfig({
        plugins: [
            react(),
            devToolbar(),
        ],
    });
    ```
  </Tab>

  <Tab value="Vue">
    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import vue from "@vitejs/plugin-vue";
    import { devToolbar } from "@visulima/dev-toolbar/vite";

    export default defineConfig({
        plugins: [
            vue(),
            devToolbar(),
        ],
    });
    ```
  </Tab>

  <Tab value="Svelte">
    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import { svelte } from "@sveltejs/vite-plugin-svelte";
    import { devToolbar } from "@visulima/dev-toolbar/vite";

    export default defineConfig({
        plugins: [
            svelte(),
            devToolbar(),
        ],
    });
    ```
  </Tab>

  <Tab value="Vanilla">
    ```ts title="vite.config.ts"
    import { defineConfig } from "vite";
    import { devToolbar } from "@visulima/dev-toolbar/vite";

    export default defineConfig({
        plugins: [
            devToolbar(),
        ],
    });
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```ts title="vite.config.ts"
    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import { devToolbar } from "@visulima/dev-toolbar/vite";
    import viteReact from "@vitejs/plugin-react";
    import { defineConfig } from "vite";

    export default defineConfig({
        resolve: {
            tsconfigPaths: true,
        },
        plugins: [
            tanstackStart(),
            viteReact(),
            // TanStack Start is auto-detected — no appendTo needed.
            devToolbar(),
        ],
    });
    ```
  </Tab>
</Tabs>

## Next Steps [#next-steps]

* [Full configuration reference](/docs/packages/dev-toolbar/configuration) — every plugin option explained
* [Built-in apps](/docs/packages/dev-toolbar/built-in-apps/accessibility) — learn what each app does
* [Inspector](/docs/packages/dev-toolbar/built-in-apps/inspector) — click any element to jump to source
* [Annotations](/docs/packages/dev-toolbar/built-in-apps/annotations) — visually annotate elements with rich context
* [MCP integration](/docs/packages/dev-toolbar/integrations/mcp) — connect AI agents to your annotations
* [Creating custom apps](/docs/packages/dev-toolbar/custom-apps/creating-apps) — build your own devtools panel
* [Library integration](/docs/packages/dev-toolbar/integrations/library-integration) — add devtools support to your library


# Visulima Dev Toolbar (/docs/packages/dev-toolbar)





`@visulima/dev-toolbar` is a powerful, extensible development toolbar for any Vite-based project — React, Vue, Svelte, SolidJS, or plain HTML. Inspired by Astro DevToolbar, Vue DevTools, and Nuxt DevTools, it brings a consistent developer experience regardless of your framework.

The toolbar renders inside a Shadow DOM custom element for complete CSS isolation, communicates with the Vite dev server over type-safe RPC, and ships eleven built-in apps covering the most common development workflows.

**Requirements:** Vite 6, 7, or 8 · Node.js 22.21+

## Features [#features]

<Cards>
  <Card title="Framework Agnostic" description="Works with any Vite project. React, Vue, Svelte, SolidJS — zero framework assumptions." />

  <Card title="11 Built-in Apps" description="Accessibility auditing, Annotations, Assets browser, Inspector, Module Graph, Performance metrics, SEO inspection, Settings, Tailwind tokens, Timeline events, and Vite Config viewer — out of the box." />

  <Card title="Visual Annotations" description="Click elements to annotate them with intent, severity, and context. Annotations persist to disk and are readable by AI agents via MCP." />

  <Card title="AI Agent Integration" description="MCP server exposes annotations to coding agents like Claude Code. Agents read context, fix issues, and resolve annotations — no copy-paste needed." />

  <Card title="Click-to-Source Inspector" description="Click any element to jump to its JSX source in your editor. Supports React, Vue, and Svelte component detection with Shadow DOM piercing." />

  <Card title="Extensible App System" description="Register custom apps with Preact components, full RPC access, and tooltip support. Build your own devtools panel in minutes." />

  <Card title="Type-safe RPC" description="Bidirectional communication between the browser and Vite's Node.js process. Inspect files, open editors, read configs — all typed end-to-end." />

  <Card title="Persistent State" description="Panel size, position, theme, and keyboard shortcuts are saved to localStorage and restored across page reloads automatically." />

  <Card title="Library Integration" description="Third-party libraries can hook in via __DEV_TOOLBAR_HOOK__ without any direct dependency, enabling zero-config devtools for your users." />
</Cards>

## Built-in Apps at a Glance [#built-in-apps-at-a-glance]

| App                                                                     | ID                         | What it does                                             |
| ----------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------- |
| [Accessibility](/docs/packages/dev-toolbar/built-in-apps/accessibility) | `dev-toolbar:a11y`         | axe-core WCAG audit with live element overlays           |
| [Annotations](/docs/packages/dev-toolbar/built-in-apps/annotations)     | `dev-toolbar:annotations`  | Visual annotations with AI agent integration via MCP     |
| [Assets](/docs/packages/dev-toolbar/built-in-apps/assets)               | `dev-toolbar:assets`       | Browse, preview, and inspect static files in `publicDir` |
| [Inspector](/docs/packages/dev-toolbar/built-in-apps/inspector)         | `dev-toolbar:inspector`    | Click any element to jump to its source in your editor   |
| [Module Graph](/docs/packages/dev-toolbar/built-in-apps/module-graph)   | `dev-toolbar:module-graph` | Browse and filter Vite's live module graph               |
| [Performance](/docs/packages/dev-toolbar/built-in-apps/performance)     | `dev-toolbar:performance`  | Web Vitals, resource timing, navigation metrics          |
| [SEO](/docs/packages/dev-toolbar/built-in-apps/seo)                     | `dev-toolbar:seo`          | Social preview cards + meta tag audit                    |
| [Settings](/docs/packages/dev-toolbar/built-in-apps/settings)           | `dev-toolbar:settings`     | Theme, toolbar behaviour, keyboard shortcuts             |
| [Tailwind](/docs/packages/dev-toolbar/built-in-apps/tailwind)           | `dev-toolbar:tailwind`     | Browse resolved Tailwind CSS v4 design tokens            |
| [Timeline](/docs/packages/dev-toolbar/built-in-apps/timeline)           | `dev-toolbar:timeline`     | Chronological event log from your app and libraries      |
| [Vite Config](/docs/packages/dev-toolbar/built-in-apps/vite-config)     | `dev-toolbar:vite-config`  | Inspect the resolved Vite configuration                  |

## How it Works [#how-it-works]

The toolbar is injected into the page by a Vite plugin as a `<dev-toolbar>` custom element. It renders a Preact UI inside Shadow DOM — so no styles leak in or out. Each "app" is a Preact component that receives RPC helpers and renders inside a resizable, draggable panel.

```
Browser                          Vite Dev Server           AI Agent
──────────────────────────────   ────────────────────────  ──────────────
<dev-toolbar> (Shadow DOM)  ←──  HTML injection             MCP Server
  ├── Toolbar pill                ├── RPC handler      ←──→ ├── get_pending_annotations
  ├── Panel canvas       ←──────→ ├── getViteConfig()       ├── get_screenshot
  │   ├── App: A11y               ├── getModuleGraph()      ├── resolve_annotation
  │   ├── App: Inspector          ├── openInEditor()        └── watch_annotations
  │   ├── App: Annotations        ├── getAnnotations()
  │   ├── App: Performance        └── saveScreenshot()
  │   └── App: SEO
  ├── Settings (localStorage)
  └── Annotations (.devtoolbar/)
```

## Keyboard Shortcuts [#keyboard-shortcuts]

| Action                    | Default           |
| ------------------------- | ----------------- |
| Toggle toolbar open/close | `Alt`+`Shift`+`D` |
| Close active app / panel  | `Escape`          |

Both shortcuts are fully configurable in the [Settings app](/docs/packages/dev-toolbar/built-in-apps/settings) or via the [plugin options](/docs/packages/dev-toolbar/configuration).


# Library Integration (/docs/packages/dev-toolbar/integrations/library-integration)





If you are building a library (a state manager, data fetcher, router, etc.), you can integrate with the Visulima Dev Toolbar without taking a hard dependency on `@visulima/dev-toolbar`. Your library checks for the global hook at runtime — when the toolbar is present, devtools appear; when it is absent, nothing happens.

This is the same pattern used by React Query DevTools, Pinia DevTools, and Vue Router DevTools.

## The Global Hook [#the-global-hook]

The toolbar exposes `window.__DEV_TOOLBAR_HOOK__` as soon as it initializes. Libraries can interact with it to:

* Register a custom app panel
* Add events to the Timeline
* Subscribe to toolbar lifecycle events

The hook is **buffered** — calls made before the toolbar has mounted are queued and replayed once it initializes. This means you can safely call `__DEV_TOOLBAR_HOOK__` as soon as your library starts, without worrying about load order.

***

## Quick Integration [#quick-integration]

The minimum integration registers an app and emits timeline events:

```ts title="my-library/src/devtools.ts"
function initDevTools(myLibraryInstance: MyLibrary): void {
    if (typeof window === "undefined") return;

    const hook = (window as any).__DEV_TOOLBAR_HOOK__;

    if (!hook) return;

    // Register a devtools panel for your library
    hook.registerApp({
        id: "my-library:devtools",
        name: "My Library",
        icon: myLibraryIconSvg, // raw SVG string
        component: MyLibraryPanel, // Preact component
        tooltip: MyLibraryTooltip, // optional
    });

    // Emit timeline events as things happen
    myLibraryInstance.on("query:start", (query) => {
        hook.addTimelineEvent("my-library", {
            id: crypto.randomUUID(),
            title: `Query: ${query.name}`,
            time: Date.now(),
            level: "info",
            data: query,
        });
    });
}
```

Call this function from your library's dev-mode initialization:

```ts title="my-library/src/index.ts"
export function createMyLibrary(options: Options): MyLibrary {
    const instance = new MyLibrary(options);

    // Only initialize devtools in development
    if (process.env.NODE_ENV !== "production") {
        initDevTools(instance);
    }

    return instance;
}
```

***

## Full Step-by-Step Guide [#full-step-by-step-guide]

<Steps>
  <Step>
    ### Create the Devtools Panel Component [#create-the-devtools-panel-component]

    Build a Preact component for your library's devtools panel. The component receives `helpers.rpc` for any server-side needs, but library devtools often only need in-memory state:

    ```tsx title="my-library/src/devtools/panel.tsx"
    /** @jsxImportSource preact */
    import type { ComponentChildren } from "preact";
    import { useEffect, useState } from "preact/hooks";
    import type { AppComponentProps } from "@visulima/dev-toolbar";
    import { myLibraryStore } from "../store";

    const MyLibraryPanel = (_props: AppComponentProps): ComponentChildren => {
        const [state, setState] = useState(myLibraryStore.getSnapshot());

        useEffect(() => {
            return myLibraryStore.subscribe(() => {
                setState(myLibraryStore.getSnapshot());
            });
        }, []);

        return (
            <div class="p-5 space-y-4">
                <h2 class="text-xs font-bold uppercase tracking-widest text-muted-foreground">// My Library State</h2>
                <pre class="text-xs font-mono text-foreground/80 bg-foreground/5 border border-border p-4 overflow-auto">{JSON.stringify(state, null, 2)}</pre>
            </div>
        );
    };

    export default MyLibraryPanel;
    ```
  </Step>

  <Step>
    ### (Optional) Create a Tooltip [#optional-create-a-tooltip]

    A tooltip shows a compact summary on hover without opening the full panel:

    ```tsx title="my-library/src/devtools/tooltip.tsx"
    /** @jsxImportSource preact */
    import type { ComponentChildren } from "preact";
    import { useEffect, useState } from "preact/hooks";
    import type { AppComponentProps } from "@visulima/dev-toolbar";
    import { myLibraryStore } from "../store";

    const MyLibraryTooltip = (_props: AppComponentProps): ComponentChildren => {
        const [count, setCount] = useState(myLibraryStore.getCount());

        useEffect(() => {
            return myLibraryStore.subscribe(() => {
                setCount(myLibraryStore.getCount());
            });
        }, []);

        return (
            <div class="p-3 space-y-1 min-w-32">
                <div class="text-xs font-bold text-muted-foreground uppercase tracking-widest">My Library</div>
                <div class="text-sm font-mono text-foreground">{count} items tracked</div>
            </div>
        );
    };

    export default MyLibraryTooltip;
    ```
  </Step>

  <Step>
    ### Register with the Hook [#register-with-the-hook]

    ```ts title="my-library/src/devtools/index.ts"
    import myIcon from "./icon.svg?raw";
    import MyLibraryPanel from "./panel";
    import MyLibraryTooltip from "./tooltip";
    import type { MyLibrary } from "../types";

    export function installDevtools(instance: MyLibrary): void {
        if (typeof window === "undefined") return;

        const hook = (window as any).__DEV_TOOLBAR_HOOK__;

        if (!hook) return;

        // Register the app panel
        hook.registerApp({
            id: "my-library:devtools",
            name: "My Library",
            icon: myIcon,
            component: MyLibraryPanel,
            tooltip: MyLibraryTooltip,
        });

        // Emit timeline events
        instance.on("action", (action) => {
            hook.addTimelineEvent("my-library", {
                id: crypto.randomUUID(),
                title: action.type,
                subtitle: action.payload ? JSON.stringify(action.payload).slice(0, 40) : undefined,
                time: Date.now(),
                level: "info",
                data: action,
            });
        });

        // Subscribe to toolbar events
        hook.on("devtools:init", () => {
            console.log("[my-library] DevTools initialized");
        });
    }
    ```
  </Step>

  <Step>
    ### Call from Your Library Entry Point [#call-from-your-library-entry-point]

    ```ts title="my-library/src/index.ts"
    import { installDevtools } from "./devtools";

    export function createMyLibrary(options: Options): MyLibrary {
        const instance = new MyLibrary(options);

        if (process.env.NODE_ENV !== "production") {
            installDevtools(instance);
        }

        return instance;
    }
    ```
  </Step>
</Steps>

***

## Hook API Reference [#hook-api-reference]

```ts
interface DevToolbarHook {
    on(event: string, handler: (...args: any[]) => void): () => void;
    once(event: string, handler: (...args: any[]) => void): void;
    off(event: string, handler?: (...args: any[]) => void): void;
    emit(event: string, ...args: any[]): void;
    registerApp(app: DevToolbarApp): void;
    addTimelineEvent(groupId: string, event: TimelineEvent): void;
}
```

### Hook Events [#hook-events]

| Event            | Payload                          | Description                      |
| ---------------- | -------------------------------- | -------------------------------- |
| `devtools:init`  | —                                | Toolbar has mounted and is ready |
| `devtools:open`  | `appId: string`                  | An app panel was opened          |
| `devtools:close` | —                                | The panel was closed             |
| `app:error`      | `(error: Error, appId?: string)` | An app component threw an error  |
| `timeline:event` | `(groupId, event)`               | A timeline event was added       |

***

## Timeline Events [#timeline-events]

Use timeline events to give users a chronological view of your library's activity:

```ts
hook.addTimelineEvent("my-library", {
    id: crypto.randomUUID(),
    title: "Cache invalidated",
    subtitle: "/api/users",
    time: Date.now(),
    level: "warning",
    data: {
        reason: "stale-while-revalidate",
        age: 31000,
    },
});
```

Timeline groups are automatically created from the `groupId` string. Users can filter events by group in the [Timeline app](/docs/packages/dev-toolbar/built-in-apps/timeline).

***

## No Dependency Required [#no-dependency-required]

Your library does not need to add `@visulima/dev-toolbar` as a dependency. The integration is entirely runtime-based:

```ts
// ✅ No import from @visulima/dev-toolbar
const hook = (window as any).__DEV_TOOLBAR_HOOK__;
if (hook) {
    /* ... */
}
```

If your library ships TypeScript types and you want to type the hook, use a `declare global`:

```ts title="my-library/src/devtools/types.ts"
declare global {
    interface Window {
        __DEV_TOOLBAR_HOOK__?: {
            registerApp(app: { id: string; name: string; icon: string; component: unknown; tooltip?: unknown }): void;
            addTimelineEvent(
                groupId: string,
                event: {
                    id: string;
                    title: string;
                    time: number;
                    level?: "info" | "warning" | "error";
                    data?: Record<string, unknown>;
                },
            ): void;
            on(event: string, handler: (...args: any[]) => void): () => void;
        };
    }
}
```

<Callout type="info">
  The hook is initialized before user code runs. The toolbar script is injected into `<head>` with `prepend` priority. Even so, calls before `devtools:init` are safely buffered and replayed.
</Callout>

***

## Real-World Pattern [#real-world-pattern]

Here is a complete minimal integration modeled on how popular libraries wire up devtools:

```ts title="my-library/src/devtools.ts"
let installed = false;

export function tryInstallDevTools(instance: MyLibrary): void {
    // Avoid double-installing (e.g. if createMyLibrary is called twice)
    if (installed) return;
    if (typeof window === "undefined") return;
    if (process.env.NODE_ENV === "production") return;

    const hook = (window as any).__DEV_TOOLBAR_HOOK__;
    if (!hook) return;

    installed = true;

    hook.registerApp({
        id: "my-library:panel",
        name: "My Library",
        icon: ICON_SVG,
        component: Panel,
        tooltip: Tooltip,
    });

    // Timeline integration
    instance.subscribe((event) => {
        hook.addTimelineEvent("my-library", {
            id: crypto.randomUUID(),
            title: event.type,
            time: Date.now(),
            level: event.error ? "error" : "info",
            data: event,
        });
    });

    // Badge notification when errors occur
    instance.on("error", () => {
        const api = (window as any).__VISULIMA_DEVTOOLS__;
        api?.notify("my-library:panel", "error");
    });
}
```


# MCP Server (/docs/packages/dev-toolbar/integrations/mcp)





The MCP (Model Context Protocol) server bridges the dev toolbar and AI coding agents. It exposes annotation data — comments, element context, source locations, screenshots — as structured tool calls that agents like Claude Code can consume directly.

## Why MCP? [#why-mcp]

Annotations capture *what* needs to change and *where* in the codebase. The MCP server makes that context available to AI agents so they can:

1. Read pending annotations with full element context
2. View screenshots of annotated elements
3. Acknowledge work-in-progress
4. Add messages to annotation threads
5. Mark annotations as resolved when the fix is complete

```mermaid
flowchart LR
    B[Browser\nDev Toolbar] -->|save| S[".devtoolbar/\nannotations.json\nscreenshots/"]
    A[AI Agent] -->|MCP tools| S
    S -->|SSE events| B

    style B fill:#6366f1,color:#fff
    style A fill:#22c55e,color:#fff
    style S fill:#18181b,color:#fafafa,stroke:#a1a1aa
```

The browser writes annotations to disk. The MCP server reads them. SSE events notify the browser when the agent makes changes.

***

## Setup [#setup]

<Steps>
  <Step>
    ### Install the package [#install-the-package]

    The MCP server is included in `@visulima/dev-toolbar` — no extra package needed.
  </Step>

  <Step>
    ### Configure your MCP client [#configure-your-mcp-client]

    Add the dev-toolbar MCP server to your agent's configuration.

    <Tabs items="[&#x22;Claude Code&#x22;, &#x22;Generic MCP Client&#x22;]">
      <Tab value="Claude Code">
        Add to your project's `.mcp.json`:

        ```json title=".mcp.json"
        {
            "mcpServers": {
                "dev-toolbar": {
                    "command": "npx",
                    "args": ["visulima-dev-toolbar-mcp"],
                    "cwd": "/absolute/path/to/your/project"
                }
            }
        }
        ```
      </Tab>

      <Tab value="Generic MCP Client">
        Run the server directly:

        ```bash
        npx visulima-dev-toolbar-mcp
        ```

        The server communicates over stdio using the MCP protocol. Point your MCP client at this command.
      </Tab>
    </Tabs>

    <Callout type="info">
      The `cwd` must point to the project root where `.devtoolbar/annotations.json` is stored. The server reads and writes to this directory.
    </Callout>
  </Step>

  <Step>
    ### Create annotations in the browser [#create-annotations-in-the-browser]

    Open your app in the browser, activate the Inspector, and annotate elements. The MCP server reads directly from the `.devtoolbar/` directory — no additional sync needed.
  </Step>

  <Step>
    ### Let your agent work [#let-your-agent-work]

    Ask your agent to check for pending annotations. It will use the MCP tools to read context, fix issues, and resolve annotations.
  </Step>
</Steps>

***

## MCP Tools [#mcp-tools]

The server exposes six tools:

### `get_pending_annotations` [#get_pending_annotations]

Retrieve all annotations with `status: "pending"`.

Returns an array of annotation objects with full metadata (element tag, source location, CSS classes, accessibility info, component context, etc.). Screenshot fields return `true`/`false` instead of binary data — use `get_screenshot` to fetch the actual image.

```json
// Example response
[
    {
        "id": "a1b2c3",
        "comment": "Fix alignment on mobile",
        "intent": "fix",
        "severity": "important",
        "status": "pending",
        "elementTag": "div",
        "source": "src/components/Hero.tsx:42:8",
        "screenshot": true,
        "cssClasses": "flex items-center gap-4",
        "url": "http://localhost:5173/"
    }
]
```

### `get_screenshot` [#get_screenshot]

Fetch a specific annotation's screenshot as a base64-encoded data URL.

**Parameters:**

* `annotationId` (string) — the annotation ID

Returns the screenshot as `data:image/png;base64,...` (or JPEG/WebP depending on capture format).

### `acknowledge_annotation` [#acknowledge_annotation]

Mark an annotation as `acknowledged` — signals that work has started.

**Parameters:**

* `annotationId` (string) — the annotation ID

### `add_thread_message` [#add_thread_message]

Add a message to an annotation's conversation thread.

**Parameters:**

* `annotationId` (string) — the annotation ID
* `content` (string) — the message text

The message is added with `role: "agent"`, a unique `id`, and a server-generated timestamp. Thread messages are visible in the browser's annotation detail popup and sync in real-time via SSE.

### `resolve_annotation` [#resolve_annotation]

Mark an annotation as `resolved`. The associated screenshot is automatically deleted.

**Parameters:**

* `annotationId` (string) — the annotation ID

### `watch_annotations` [#watch_annotations]

Block until new pending annotations appear. Useful for hands-free workflows where the agent polls for work.

**Parameters:**

* `timeout` (number, optional) — maximum wait time in milliseconds
* `batchWindow` (number, optional) — wait this many milliseconds after the first new annotation before returning, to batch multiple annotations

***

## Workflow Patterns [#workflow-patterns]

### Manual Review [#manual-review]

The simplest pattern — you annotate, then ask your agent to check:

```
You:   "Check for pending annotations and fix them"
Agent: get_pending_annotations → reads context → fixes code → resolve_annotation
```

```mermaid
sequenceDiagram
    participant You
    participant Agent

    You->>Agent: "Fix pending annotations"
    Agent->>Agent: get_pending_annotations()
    Agent->>Agent: Read element, source, styles
    Agent->>Agent: Fix code
    Agent->>Agent: resolve_annotation()
    Agent-->>You: "Fixed 3 annotations"
```

### Hands-free Mode [#hands-free-mode]

The agent watches for new annotations and acts on them automatically:

```
You:   "Watch for annotations and fix them as they come in"
Agent: watch_annotations in a loop → acknowledge → fix → resolve
```

```mermaid
sequenceDiagram
    participant You as Developer
    participant Agent

    You->>Agent: "Watch and fix annotations"
    loop Every batch
        Agent->>Agent: watch_annotations()
        Note over Agent: Blocks until new annotations arrive
        Agent->>Agent: acknowledge_annotation()
        Agent->>Agent: Fix code
        Agent->>Agent: resolve_annotation()
    end
```

### Critique Mode [#critique-mode]

Use annotations to review AI-generated code:

```
Agent: Writes code
You:   Annotate issues in the browser ("this button is misaligned", "wrong colour")
Agent: Reads annotations → applies fixes → resolves
```

***

## Security [#security]

The MCP server enforces several safety measures:

* **Directory traversal protection** — all file paths are validated to stay within the project root
* **Screenshot path validation** — screenshot paths must start with `screenshots/`
* **ID sanitization** — annotation IDs are stripped of unsafe characters before use as filenames
* **Async file locking** — prevents race conditions on concurrent reads/writes

***

## Limitations [#limitations]

* The MCP server reads from the filesystem. The Vite dev server provides real-time SSE notifications when annotations change, but the MCP server itself uses file polling in `watch_annotations`.
* Screenshots are captured via the browser's Screen Capture API. If you skip the screenshot step, `get_screenshot` returns nothing.
* The server runs with the permissions of the process that spawned it. Ensure `cwd` points to a trusted project directory.


# vite-overlay (/docs/packages/dev-toolbar/integrations/vite-overlay)





`@visulima/vite-overlay` is a drop-in replacement for Vite's built-in error overlay. It adds syntax highlighting, source-map aware stack traces, cause-chain navigation, and AI-powered solution hints.

When both packages are installed together the Dev Toolbar automatically detects vite-overlay and shows a red **error badge button** in the toolbar bar. Clicking the badge opens or closes the overlay panel, so you get a single, integrated debugging experience without any extra wiring.

***

## How it works [#how-it-works]

The toolbar polls two globals that vite-overlay writes to the browser window:

| Global                       | Set by       | What it contains                      |
| ---------------------------- | ------------ | ------------------------------------- |
| `window.__v_o_error_history` | vite-overlay | Array of all captured errors          |
| `window.__v_o__current`      | vite-overlay | The currently mounted overlay element |

When `__v_o_error_history` has at least one entry a red triangular badge button appears on the right side of the toolbar bar. The badge shows the error count (capped at `9+`). Clicking it toggles the overlay panel open or closed.

Because the detection is automatic there is nothing to configure — just install both plugins.

***

## Installation [#installation]

<Steps>
  <Step>
    ### Install both packages [#install-both-packages]

    ```sh
    pnpm add -D @visulima/dev-toolbar @visulima/vite-overlay
    ```
  </Step>

  <Step>
    ### Configure your Vite config [#configure-your-vite-config]

    Add both plugins to `plugins`. Set `showBallonButton: false` on vite-overlay so the toolbar renders the error button instead of the standalone floating balloon:

    ```ts title="vite.config.ts"
    import { devToolbar } from "@visulima/dev-toolbar/vite";
    import viteOverlay from "@visulima/vite-overlay";
    import { defineConfig } from "vite";

    export default defineConfig({
        plugins: [
            // Disable the built-in balloon — the dev-toolbar renders its own error button
            viteOverlay({ showBallonButton: false }),
            devToolbar({
                apps: {
                    settings: true,
                },
            }),
        ],
    });
    ```

    <Callout type="info">
      Plugin order does not matter. The toolbar detects vite-overlay at runtime via the shared globals, not at build time.
    </Callout>
  </Step>
</Steps>

***

## Error badge behaviour [#error-badge-behaviour]

Once an error is captured by vite-overlay:

* A red **alert-triangle** icon appears on the right side of the toolbar bar.
* The badge shows the total number of errors in the current history (`1`–`9+`).
* Clicking the badge **shows** the overlay if it is hidden, or **hides** it if it is visible.
* The badge disappears automatically when the error history is cleared (e.g. after a hot-reload that resolves the error).

The toolbar checks the error count every 300 ms so the badge appears within a fraction of a second of an error being captured.

***

## Keeping the standalone balloon [#keeping-the-standalone-balloon]

If you prefer the standalone floating balloon from vite-overlay and do not want the toolbar button, simply omit `showBallonButton: false`:

```ts title="vite.config.ts"
export default defineConfig({
    plugins: [
        viteOverlay(), // default: showBallonButton: true
        devToolbar({ apps: { settings: true } }),
    ],
});
```

Both the balloon and the toolbar button will work independently. The toolbar button will still appear because both are driven by the same `__v_o_error_history` global.

***

## Framework-specific notes [#framework-specific-notes]

### SSR frameworks (TanStack Start, Nuxt, SvelteKit, …) [#ssr-frameworks-tanstack-start-nuxt-sveltekit-]

SSR frameworks render the HTML server-side, which means `transformIndexHtml` is not called by Vite and the toolbar script is never injected automatically.

**TanStack Start** is auto-detected — no extra configuration needed. For other SSR frameworks, use the `appendTo` option to target a module file that is part of every route instead:

```ts title="vite.config.ts"
devToolbar({
    // Inject via the router module instead of index.html
    appendTo: /router\.tsx$/,
    apps: { settings: true },
});
```

See the [Getting Started](/docs/packages/dev-toolbar/getting-started) guide for more details on `appendTo`.

### React [#react]

The vite-overlay plugin auto-detects `@vitejs/plugin-react`. No extra configuration is needed. To use a custom React plugin pass its name:

```ts
viteOverlay({ reactPluginName: "my-custom-react-plugin" });
```

### Vue [#vue]

Pass a custom Vue plugin name if you use something other than `@vitejs/plugin-vue`:

```ts
viteOverlay({ vuePluginName: "my-custom-vue-plugin" });
```

***

## Full vite-overlay options reference [#full-vite-overlay-options-reference]

The full option set for `@visulima/vite-overlay` is documented in its own package. The options most relevant when used together with the Dev Toolbar are:

| Option                    | Default     | Notes                                                                        |
| ------------------------- | ----------- | ---------------------------------------------------------------------------- |
| `showBallonButton`        | `true`      | Set to `false` when using the Dev Toolbar so only the toolbar badge is shown |
| `forwardConsole`          | `true`      | Captures `console.error` calls and shows them in the overlay                 |
| `forwardedConsoleMethods` | `["error"]` | Add `"warn"` etc. to capture more console output                             |
| `solutionFinders`         | `[]`        | Custom solution-finder functions for AI-powered hints                        |
| `overlay.customCSS`       | —           | Inject CSS to restyle the overlay panel or balloon                           |


# API (/docs/packages/disposable-email-domains/api)



# API Reference [#api-reference]

## `isDisposableEmail(email: string): boolean` [#isdisposableemailemail-string-boolean]

Check if email is from a disposable domain.

**Parameters:**

* `email` (string): Email address to check

**Returns:** `true` if disposable, `false` otherwise

**Example:**

```typescript
isDisposableEmail("user@tempmail.com"); // true
isDisposableEmail("user@gmail.com"); // false
```

## `disposableDomains: string[]` [#disposabledomains-string]

Array of all known disposable email domains.

**Example:**

```typescript
console.log(disposableDomains.length);
// 12000+
```


# Introduction (/docs/packages/disposable-email-domains)



# @visulima/disposable-email-domains [#visulimadisposable-email-domains]

Validate and block disposable/temporary email addresses using a comprehensive, regularly-updated list of disposable email domains.

## Quick Start [#quick-start]

```typescript
import { isDisposableEmail } from "@visulima/disposable-email-domains";

isDisposableEmail("user@mailinator.com");
// true (disposable)

isDisposableEmail("user@gmail.com");
// false (legitimate)
```

## Use Cases [#use-cases]

* **User Registration** - Block temporary emails
* **Email Validation** - Ensure real email addresses
* **Spam Prevention** - Reduce fake accounts
* **Data Quality** - Maintain clean user database

<Cards>
  <Card title="Installation" href="/docs/packages/disposable-email-domains/installation">
    Install the package
  </Card>

  <Card title="Usage" href="/docs/packages/disposable-email-domains/usage">
    Learn how to validate emails
  </Card>

  <Card title="API" href="/docs/packages/disposable-email-domains/api">
    API documentation
  </Card>
</Cards>


# Installation (/docs/packages/disposable-email-domains/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/disposable-email-domains
```

## Import [#import]

```typescript
import { isDisposableEmail, disposableDomains } from "@visulima/disposable-email-domains";
```


# Usage (/docs/packages/disposable-email-domains/usage)



# Usage [#usage]

## Check Disposable Email [#check-disposable-email]

```typescript
import { isDisposableEmail } from "@visulima/disposable-email-domains";

const email = "user@tempmail.com";

if (isDisposableEmail(email)) {
    console.log("Disposable email detected");
} else {
    console.log("Valid email");
}
```

## Get Domain List [#get-domain-list]

```typescript
import { disposableDomains } from "@visulima/disposable-email-domains";

console.log(disposableDomains);
// ["mailinator.com", "tempmail.com", ...]
```

## Form Validation [#form-validation]

```typescript
function validateEmail(email: string): boolean {
    // Check format
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
        return false;
    }

    // Check if disposable
    if (isDisposableEmail(email)) {
        return false;
    }

    return true;
}
```


# Signing and Encryption (/docs/packages/email/crypto/signing-and-encryption)



# Signing and Encryption [#signing-and-encryption]

The email package supports signing and encrypting email messages to increase their integrity and security. Both options can be combined to encrypt a signed message and/or to sign an encrypted message.

## Prerequisites [#prerequisites]

Before signing/encrypting messages, make sure to have:

* **For DKIM**: A valid DKIM private key (PEM format)
* **For S/MIME**: Valid S/MIME security certificates and private keys
* **For S/MIME**: The `pkijs` and `asn1js` packages installed (required for S/MIME operations)

```bash
npm install pkijs asn1js
```

When using OpenSSL to generate certificates, make sure to add the `-addtrust emailProtection` command option for S/MIME certificates.

## Signing Messages [#signing-messages]

When signing a message, a cryptographic hash is generated for the entire content of the message (including attachments). This hash is added as an attachment or header so the recipient can validate the integrity of the received message. However, the contents of the original message are still readable for mailing agents not supporting signed messages, so you must also encrypt the message if you want to hide its contents.

You can sign messages using either **S/MIME** or **DKIM**. In both cases, the certificate and private key must be PEM encoded, and can be either created using OpenSSL or obtained at an official Certificate Authority (CA). The email recipient must have the CA certificate in the list of trusted issuers in order to verify the signature.

**Note**: If you use message signature, sending to Bcc will be removed from the message. If you need to send a message to multiple recipients, you need to compute a new signature for each recipient.

### DKIM Signer [#dkim-signer]

DKIM is an email authentication method that affixes a digital signature, linked to a domain name, to each outgoing email message. It requires a private key but not a certificate.

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createDkimSigner } from "@visulima/email/crypto";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Create DKIM signer
const dkimSigner = createDkimSigner({
    domainName: "example.com",
    keySelector: "default",
    privateKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    // Optional: passphrase if the key is encrypted
    // passphrase: "your-passphrase",
});

// Sign and send email
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").sign(dkimSigner);

const result = await mail.send(message);
```

#### DKIM Options [#dkim-options]

The DKIM signer supports various configuration options:

```typescript
const dkimSigner = createDkimSigner({
    domainName: "example.com",
    keySelector: "default",
    // Private key can be:
    // - Direct key content: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
    // - File path (Node.js, Bun, Deno): "file:///path/to/private-key.pem"
    privateKey: "file:///path/to/private-key.pem",
    passphrase: "optional-passphrase",

    // Canonicalization algorithms
    headerCanon: "relaxed", // 'simple' (default) or 'relaxed'
    bodyCanon: "relaxed", // 'simple' (default) or 'relaxed'

    // Headers to ignore when signing
    headersToIgnore: ["Message-ID", "X-Custom-Header"],
});
```

**Platform Support**:

* **Node.js**: Full support including file-based keys (`file://` paths)
* **Bun**: Full support including file-based keys (`file://` paths)
* **Deno**: Full support including file-based keys (`file://` paths)
* **Cloudflare Workers/workerd**: Full support - requires `nodejs_compat` flag and key content as strings (no file paths). Uses `unenv` polyfills for `node:crypto` compatibility ([unenv](https://github.com/unjs/unenv)).
* **Other environments**: Provide key content directly (no file support)

### ARC Signer [#arc-signer]

ARC ([Authenticated Received Chain, RFC 8617](https://www.rfc-editor.org/rfc/rfc8617)) lets a forwarding service preserve the authentication results (SPF/DKIM/DMARC) it observed, so downstream receivers can still trust them after the message is relayed. `signArc` seals a message for an **originating sealer** (instance `i=1`), adding three headers: `ARC-Authentication-Results`, `ARC-Message-Signature`, and `ARC-Seal`.

```typescript
import { signArc } from "@visulima/email/crypto";

const { email: sealed, headers } = await signArc(message, {
    domainName: "forwarder.example.com",
    keySelector: "arc1",
    privateKey: process.env.ARC_PRIVATE_KEY, // PEM string, or a "file://" path
    authenticationResults: "forwarder.example.com; spf=pass smtp.mailfrom=sender.example; dkim=pass header.d=sender.example",
});

// `sealed` is the EmailOptions with the three ARC-* headers added; `headers` is the raw header set.
```

#### ARC Options [#arc-options]

| Option                  | Type                         | Default    | Description                                        |
| ----------------------- | ---------------------------- | ---------- | -------------------------------------------------- |
| `domainName`            | `string`                     | required   | Signing domain (`d=`)                              |
| `keySelector`           | `string`                     | required   | DNS key selector (`s=`)                            |
| `privateKey`            | `string`                     | required   | RSA private key (PEM, or `file://` path)           |
| `authenticationResults` | `string`                     | required   | The `Authentication-Results` value to chain        |
| `cv`                    | `"none" \| "pass" \| "fail"` | `"none"`   | Chain validation status (always `none` for `i=1`)  |
| `headersToSign`         | `string[]`                   | common set | Lower-cased header names covered by the AMS (`h=`) |
| `instance`              | `number`                     | `1`        | ARC instance (`i=`); only `1` is supported         |
| `timestamp`             | `number`                     | now        | Signature time (`t=`) in unix seconds              |
| `passphrase`            | `string`                     | -          | Passphrase for an encrypted private key            |

The signature-base builders `arcMessageSignatureBase(email, options)` and `arcSealBase(aarValue, amsValue, options)` are also exported so an ARC verifier can re-derive the exact bytes that were signed.

> **Note:** like the DKIM signer, the body hash (`bh=`) is computed over `text` + `"\n\n"` + `html` with relaxed canonicalization. For a third-party ARC verifier to accept the seal, the body transmitted on the wire must canonicalize to the same value — apply ARC where the final MIME body is known. Only RSA keys are supported today (Ed25519 is not yet implemented).

### S/MIME Signer [#smime-signer]

S/MIME is a standard for public key encryption and signing of MIME data. It requires using both a certificate and a private key.

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createSmimeSigner } from "@visulima/email/crypto";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Create S/MIME signer
const smimeSigner = createSmimeSigner({
    certificate: "/path/to/certificate.crt",
    privateKey: "/path/to/private-key.key",
    // Optional: passphrase if the key is encrypted (supported in Node.js)
    // passphrase: "your-passphrase",
    // Optional: intermediate certificates
    // intermediateCerts: ["/path/to/intermediate.crt"],
});

// Sign and send email
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").sign(smimeSigner);

const result = await mail.send(message);
```

**Platform Support**:

* **Node.js 20+**: Full support including encrypted private keys (PBES2/PBKDF2). Uses Node.js crypto APIs.
* **Bun**: Full support via Node.js compatibility layer. Encrypted keys require Node.js crypto.
* **Deno**: Full support via Node.js compatibility layer. Encrypted keys require Node.js crypto.
* **Cloudflare Workers/workerd**: Not supported - requires `node:fs/promises` for file reading and `node:crypto` for key handling. Code would need modification to accept strings instead of file paths.

## Encrypting Messages [#encrypting-messages]

When encrypting a message, the entire message (including attachments) is encrypted using a certificate. Therefore, only the recipients that have the corresponding private key can read the original message contents.

### S/MIME Encrypter [#smime-encrypter]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createSmimeEncrypter } from "@visulima/email/crypto";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Single certificate for all recipients
const encrypter = createSmimeEncrypter({
    certificates: "/path/to/recipient-certificate.crt",
});

// Or, use different certificates per recipient
const perRecipientEncrypter = createSmimeEncrypter({
    certificates: {
        "jane@example.com": "/path/to/jane-certificate.crt",
        "john@example.com": "/path/to/john-certificate.crt",
    },
    // Optional: encryption algorithm
    // Supported: 'aes-256-cbc', 'aes-192-cbc', 'aes-128-cbc'
    // Default: 'aes-256-cbc'
    // algorithm: "aes-256-cbc",
});

// Encrypt and send email
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").encrypt(encrypter);

const result = await mail.send(message);
```

**Platform Support**:

* **Node.js 20+**: Full support. Uses Node.js crypto APIs and Web Crypto API.
* **Bun**: Full support via Node.js compatibility layer and Web Crypto API.
* **Deno**: Full support via Node.js compatibility layer and Web Crypto API.
* **Cloudflare Workers/workerd**: Not supported - requires `node:fs/promises` for file reading. Code would need modification to accept strings instead of file paths.

**Encryption Algorithms**:

* `aes-256-cbc` (default) - AES-256 in CBC mode
* `aes-192-cbc` - AES-192 in CBC mode
* `aes-128-cbc` - AES-128 in CBC mode

## Combining Signing and Encryption [#combining-signing-and-encryption]

You can combine signing and encryption. The message will be signed first, then encrypted:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createDkimSigner, createSmimeEncrypter } from "@visulima/email/crypto";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const dkimSigner = createDkimSigner({
    domainName: "example.com",
    keySelector: "default",
    privateKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
});

const encrypter = createSmimeEncrypter({
    certificates: "/path/to/recipient-certificate.crt",
});

// Sign then encrypt
const message = new MailMessage()
    .to("user@example.com")
    .from("sender@example.com")
    .subject("Hello")
    .html("<h1>Hello World</h1>")
    .sign(dkimSigner)
    .encrypt(encrypter);

const result = await mail.send(message);
```

## Important Notes [#important-notes]

1. **Message Rendering**: Signing and encrypting messages require their contents to be fully rendered. For example, the content of templated emails is rendered by template engines. So, if you want to sign and/or encrypt such a message, make sure the template is rendered before signing/encrypting.

2. **BCC Handling**: When using message signature, BCC recipients will be removed from the message. If you need to send a message to multiple recipients, you need to compute a new signature for each recipient.

3. **Certificate Management**: Ensure that certificates used for signing and encryption are valid and trusted by the recipients.

4. **Private Key Security**: Always handle private keys securely. Avoid hardcoding them in your codebase; use environment variables or secure vaults instead.

5. **Encrypted Private Keys**:
   * **Node.js**: Full support for encrypted private keys (PBES2/PBKDF2). Simply provide the `passphrase` option. Node.js crypto automatically handles encrypted PKCS#8 and PKCS#1 keys.
   * **Bun/Deno**: Encrypted keys work via Node.js compatibility layer. If compatibility is not available, decrypt the key externally or use Node.js for automatic decryption.
   * **Cloudflare Workers/workerd**: Full support for encrypted keys via `unenv` polyfills. Provide the `passphrase` option just like in Node.js ([unenv](https://github.com/unjs/unenv)).

## Platform Compatibility [#platform-compatibility]

| Feature           | Node.js | Bun   | Deno  | Cloudflare Workers |
| ----------------- | ------- | ----- | ----- | ------------------ |
| DKIM Signing      | ✅       | ✅     | ✅     | ✅\*                |
| S/MIME Signing    | ✅\*\*   | ✅\*\* | ✅\*\* | ❌\*\*\*            |
| S/MIME Encryption | ✅\*\*   | ✅\*\* | ✅\*\* | ❌\*\*\*            |

\* DKIM in Cloudflare Workers: Full support - requires `nodejs_compat` flag and key content as strings (no file paths). Uses `unenv` polyfills for `node:crypto` compatibility ([unenv](https://github.com/unjs/unenv)). All required functions (`createHash`, `createSign`, `createPrivateKey`) are available.

\*\* S/MIME requires Web Crypto API (Node.js 20+, Bun, Deno) and pkijs/asn1js packages. All runtimes use Node.js APIs via compatibility layers where available.

\*\*\* S/MIME in Cloudflare Workers: Not supported - requires `node:fs/promises` for file reading. Current implementation expects file paths, not strings. Code would need modification to accept strings instead of file paths.

## Examples [#examples]

### Example: DKIM Signing with File-based Key [#example-dkim-signing-with-file-based-key]

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { smtpProvider } from "@visulima/email/providers/smtp";
import { createDkimSigner } from "@visulima/email/crypto";

const mail = createMail(
    smtpProvider({
        host: "smtp.example.com",
        port: 587,
        auth: {
            user: "user@example.com",
            pass: "password",
        },
    }),
);

// Option 1: Use file:// path (works in Node.js, Bun, Deno)
const dkimSigner = createDkimSigner({
    domainName: "example.com",
    keySelector: "default",
    privateKey: "file:///path/to/dkim-private-key.pem",
    headerCanon: "relaxed",
    bodyCanon: "relaxed",
});

// Option 2: Read file manually (Node.js example)
// import { readFileSync } from "node:fs";
// const privateKey = readFileSync("/path/to/dkim-private-key.pem", "utf-8");
// const dkimSigner = createDkimSigner({
//   domainName: "example.com",
//   keySelector: "default",
//   privateKey,
// });

const message = new MailMessage()
    .to("recipient@example.com")
    .from("sender@example.com")
    .subject("Signed Email")
    .html("<h1>This email is signed with DKIM</h1>")
    .sign(dkimSigner);

await mail.send(message);
```

### Example: S/MIME Signing and Encryption [#example-smime-signing-and-encryption]

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createSmimeSigner, createSmimeEncrypter } from "@visulima/email/crypto";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const signer = createSmimeSigner({
    certificate: "/path/to/sender-certificate.crt",
    privateKey: "/path/to/sender-private-key.key",
    passphrase: "optional-passphrase",
});

const encrypter = createSmimeEncrypter({
    certificates: {
        "recipient1@example.com": "/path/to/recipient1-certificate.crt",
        "recipient2@example.com": "/path/to/recipient2-certificate.crt",
    },
});

const message = new MailMessage()
    .to(["recipient1@example.com", "recipient2@example.com"])
    .from("sender@example.com")
    .subject("Secure Email")
    .html("<h1>This email is signed and encrypted</h1>")
    .sign(signer)
    .encrypt(encrypter);

await mail.send(message);
```

### Cloudflare Workers Support [#cloudflare-workers-support]

**Current Status**:

* **DKIM Signing**: ✅ **Full support** - works with `nodejs_compat` flag using `unenv` polyfills
* **S/MIME Signing/Encryption**: ❌ **Not supported** - requires `node:fs/promises` for file reading

**DKIM in Cloudflare Workers**:

* ✅ All required `node:crypto` functions are available via `unenv` polyfills ([unenv](https://github.com/unjs/unenv))
* ✅ `createHash`, `createSign`, and `createPrivateKey` are all supported
* ✅ Works with key content as strings (no file paths needed)
* ✅ Encrypted keys are supported (via `createPrivateKey` from unenv)

**Configuration**: Enable `nodejs_compat` in your `wrangler.toml`:

```toml
[env.production]
compatibility_flags = ["nodejs_compat"]
```

**Example for Cloudflare Workers**:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createDkimSigner } from "@visulima/email/crypto";

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const mail = createMail(resendProvider({ apiKey: env.RESEND_API_KEY }));

        const dkimSigner = createDkimSigner({
            domainName: "example.com",
            keySelector: "default",
            privateKey: env.DKIM_PRIVATE_KEY, // Must be string, not file:// path
            // Optional: passphrase for encrypted keys (supported via unenv)
            // passphrase: env.DKIM_PASSPHRASE,
        });

        const message = new MailMessage()
            .to("recipient@example.com")
            .from("sender@example.com")
            .subject("Signed Email")
            .html("<h1>This email is signed with DKIM</h1>")
            .sign(dkimSigner);

        await mail.send(message);

        return new Response("Email sent");
    },
};
```

**S/MIME in Cloudflare Workers**:

* ❌ Not supported - requires `node:fs/promises` for file reading
* Code would need modification to accept strings instead of file paths

**Workarounds**: For S/MIME in Cloudflare Workers, consider:

* Using email providers that handle signing/encryption server-side
* Running signing/encryption in a separate Node.js service
* Modifying the code to accept certificate/key content as strings


# Deliverability (/docs/packages/email/deliverability/introduction)



# Deliverability [#deliverability]

The `@visulima/email/deliverability` entry point bundles the tooling you need to meet modern bulk-sender requirements: one-click `List-Unsubscribe` headers, a pluggable suppression list, and pure parsers for the DNS records and feedback reports that drive your sending reputation.

```typescript
import {
    buildListUnsubscribe,
    parseListUnsubscribe,
    MemorySuppressionStore,
    createSuppressionStore,
    filterSuppressed,
    parseDmarcRecord,
    parseMtaStsPolicy,
    parseTlsRptRecord,
    parseTlsReport,
    parseArfReport,
} from "@visulima/email/deliverability";
```

## List-Unsubscribe [#list-unsubscribe]

`buildListUnsubscribe()` produces the `List-Unsubscribe` (and, when requested, `List-Unsubscribe-Post`) headers. Gmail and Yahoo's 2024 bulk-sender rules expect bulk senders to expose a [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058) one-click unsubscribe.

```typescript
type ListUnsubscribeOptions = {
    url?: string; // an https: URL the recipient (or their client) can use to unsubscribe
    mailto?: string; // a bare address or full mailto: URI
    oneClick?: boolean; // emit the RFC 8058 List-Unsubscribe-Post header
    mailtoSubject?: string; // default subject for a bare mailto address (default: "unsubscribe")
};

type ListUnsubscribeHeaders = {
    "List-Unsubscribe": string;
    "List-Unsubscribe-Post"?: string;
};
```

At least one of `url` or `mailto` must be provided, otherwise `buildListUnsubscribe()` throws a `TypeError`.

```typescript
import { buildListUnsubscribe } from "@visulima/email/deliverability";

const headers = buildListUnsubscribe({
    url: "https://example.com/unsub?id=abc",
    mailto: "unsubscribe@example.com",
    oneClick: true,
});
// {
//   "List-Unsubscribe": "<https://example.com/unsub?id=abc>, <mailto:unsubscribe@example.com?subject=unsubscribe>",
//   "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
// }
```

### One-Click Requires an HTTPS URL [#one-click-requires-an-https-url]

RFC 8058 one-click unsubscribe is only meaningful over HTTPS. Passing `oneClick: true` without an `https:` `url` throws a `TypeError`:

```typescript
// Throws: One-click unsubscribe (RFC 8058) requires an https `url`
buildListUnsubscribe({ mailto: "unsubscribe@example.com", oneClick: true });
```

### Merging Into an Email [#merging-into-an-email]

Merge the returned headers into a message with `setHeaders()`:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { buildListUnsubscribe } from "@visulima/email/deliverability";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const message = new MailMessage()
    .to("user@example.com")
    .from("newsletter@example.com")
    .subject("This week at Acme")
    .html("<h1>Hello</h1>")
    .setHeaders(
        buildListUnsubscribe({
            url: "https://example.com/unsub?id=abc",
            mailto: "unsubscribe@example.com",
            oneClick: true,
        }),
    );

await mail.send(message);
```

### Parsing a List-Unsubscribe Header [#parsing-a-list-unsubscribe-header]

`parseListUnsubscribe()` unwraps the angle-bracketed targets from a raw header value into a `string[]`:

```typescript
import { parseListUnsubscribe } from "@visulima/email/deliverability";

const targets = parseListUnsubscribe("<https://example.com/unsub?id=abc>, <mailto:unsubscribe@example.com?subject=unsubscribe>");
// ["https://example.com/unsub?id=abc", "mailto:unsubscribe@example.com?subject=unsubscribe"]
```

## Suppression Lists [#suppression-lists]

A suppression list is the addresses you must never send to again — bounces, spam complaints, and unsubscribes. `MemorySuppressionStore` is an in-memory implementation suitable for tests, single-process apps, or as a write-through cache in front of a durable store. Matching is case-insensitive (addresses are normalized to lower case on write).

```typescript
type SuppressionReason = "bounce" | "complaint" | "manual" | "unsubscribe";

type SuppressionEntry = {
    address: string; // the normalized (lower-cased) address
    createdAt: Date;
    reason: SuppressionReason;
    metadata?: Record<string, unknown>;
};
```

```typescript
import { MemorySuppressionStore } from "@visulima/email/deliverability";

const store = new MemorySuppressionStore();

store.add("User@Example.com", "bounce", { type: "hard" });

store.has("user@example.com"); // true (case-insensitive)
store.get("user@example.com"); // { address: "user@example.com", reason: "bounce", createdAt: Date, metadata: { type: "hard" } }
store.size; // 1

for (const entry of store.list()) {
    console.log(entry.address, entry.reason);
}

store.remove("user@example.com"); // true
```

The `createSuppressionStore()` factory is a convenience for an in-memory store, optionally seeded with existing entries:

```typescript
import { createSuppressionStore } from "@visulima/email/deliverability";

const store = createSuppressionStore([
    { address: "bounced@example.com", reason: "bounce" },
    { address: "complained@example.com", reason: "complaint", metadata: { source: "fbl" } },
]);
```

### Pre-Send Filtering [#pre-send-filtering]

`filterSuppressed()` partitions a recipient list into `allowed` and `suppressed`. It accepts `EmailAddress` objects (`{ email, name? }`) and is asynchronous, so it works with both in-memory and durable stores:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createSuppressionStore, filterSuppressed } from "@visulima/email/deliverability";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
const store = createSuppressionStore([{ address: "bounced@example.com", reason: "bounce" }]);

const recipients = [{ email: "ok@example.com" }, { email: "bounced@example.com" }];

const { allowed, suppressed } = await filterSuppressed(recipients, store);

if (suppressed.length > 0) {
    console.warn(
        "Skipping suppressed recipients:",
        suppressed.map((r) => r.email),
    );
}

if (allowed.length > 0) {
    const message = new MailMessage().to(allowed).from("newsletter@example.com").subject("Hello").html("<h1>Hello</h1>");
    await mail.send(message);
}
```

### Backing the Store With Redis or a Database [#backing-the-store-with-redis-or-a-database]

For production, implement the `SuppressionStore` interface to back the list with Redis, Postgres, or a provider's native suppression API. Implementations are expected to normalize addresses to lower case on write, and methods may be sync or async.

```typescript
type SuppressionStore = {
    add: (address: string, reason: SuppressionReason, metadata?: Record<string, unknown>) => Promise<void> | void;
    has: (address: string) => boolean | Promise<boolean>;
    get: (address: string) => (SuppressionEntry | undefined) | Promise<SuppressionEntry | undefined>;
    remove: (address: string) => boolean | Promise<boolean>;
    list?: () => Iterable<SuppressionEntry> | Promise<Iterable<SuppressionEntry>>;
};
```

```typescript
import type { Redis } from "ioredis";
import type { SuppressionEntry, SuppressionReason, SuppressionStore } from "@visulima/email/deliverability";

const createRedisSuppressionStore = (redis: Redis): SuppressionStore => {
    const key = (address: string) => `suppression:${address.trim().toLowerCase()}`;

    return {
        async add(address, reason, metadata) {
            const entry: SuppressionEntry = { address: address.trim().toLowerCase(), createdAt: new Date(), reason, metadata };

            await redis.set(key(address), JSON.stringify(entry));
        },
        async has(address) {
            return (await redis.exists(key(address))) === 1;
        },
        async get(address) {
            const raw = await redis.get(key(address));

            return raw ? (JSON.parse(raw) as SuppressionEntry) : undefined;
        },
        async remove(address) {
            return (await redis.del(key(address))) === 1;
        },
    };
};
```

## Report & Record Parsers [#report--record-parsers]

All parsers are pure functions — no I/O, no DNS. Fetch the records or reports yourself (DNS lookup, HTTPS request, inbound webhook) and pass the raw text in.

### DMARC [#dmarc]

`parseDmarcRecord()` parses the `_dmarc.<domain>` TXT policy record. Unknown policy values (anything other than `none` / `quarantine` / `reject`) become `undefined`. The original tag/value pairs are preserved under `tags`.

```typescript
import { parseDmarcRecord } from "@visulima/email/deliverability";

const record = parseDmarcRecord(
    "v=DMARC1; p=reject; sp=quarantine; pct=100; adkim=s; aspf=r; rua=mailto:agg@example.com; ruf=mailto:forensic@example.com; fo=1",
);
// {
//   valid: true,
//   policy: "reject",
//   subdomainPolicy: "quarantine",
//   percent: 100,
//   adkim: "s",
//   aspf: "r",
//   rua: ["mailto:agg@example.com"],
//   ruf: ["mailto:forensic@example.com"],
//   fo: "1",
//   tags: { v: "DMARC1", p: "reject", sp: "quarantine", pct: "100", adkim: "s", aspf: "r", rua: "...", ruf: "...", fo: "1" },
// }
```

### MTA-STS [#mta-sts]

`parseMtaStsPolicy()` parses the policy file served at `https://mta-sts.<domain>/.well-known/mta-sts.txt`:

```typescript
import { parseMtaStsPolicy } from "@visulima/email/deliverability";

const policy = parseMtaStsPolicy(["version: STSv1", "mode: enforce", "mx: mail.example.com", "mx: *.example.net", "max_age: 604800"].join("\n"));
// {
//   valid: true,
//   version: "STSv1",
//   mode: "enforce",
//   mx: ["mail.example.com", "*.example.net"],
//   maxAge: 604800,
// }
```

### TLS-RPT [#tls-rpt]

`parseTlsRptRecord()` parses the `_smtp._tls.<domain>` TXT record, and `parseTlsReport()` normalizes a TLS-RPT JSON report (passed as a JSON string or an already-parsed object) into a session-count summary.

```typescript
import { parseTlsRptRecord, parseTlsReport } from "@visulima/email/deliverability";

const record = parseTlsRptRecord("v=TLSRPTv1; rua=mailto:tlsrpt@example.com");
// { valid: true, version: "TLSRPTv1", rua: ["mailto:tlsrpt@example.com"] }

const report = parseTlsReport(rawTlsRptJson);
// {
//   organizationName: "google.com",
//   reportId: "2024-01-01T00:00:00Z_example.com",
//   startDate: "2024-01-01T00:00:00Z",
//   endDate: "2024-01-02T00:00:00Z",
//   totalSuccessful: 1234,
//   totalFailure: 5,
//   policies: [ /* raw policy objects */ ],
// }
```

### ARF (Feedback-Loop Complaints) [#arf-feedback-loop-complaints]

`parseArfReport()` parses an [ARF](https://www.rfc-editor.org/rfc/rfc5965) feedback-loop complaint — the report mailbox providers send when a recipient marks your message as spam. Pass the full raw ARF email or just its `message/feedback-report` part. Use `originalRcptTo` to drive suppression of the complaining recipient.

```typescript
import { parseArfReport } from "@visulima/email/deliverability";

const report = parseArfReport(rawArfEmail);
// {
//   feedbackType: "abuse",
//   originalRcptTo: "complainer@example.com",
//   originalMailFrom: "newsletter@example.com",
//   reportedDomain: "example.com",
//   sourceIp: "192.0.2.1",
//   arrivalDate: "Mon, 01 Jan 2024 00:00:00 +0000",
//   fields: { /* every lower-cased field from the report part */ },
// }
```

## The 2024 Gmail / Yahoo Bulk-Sender Pattern [#the-2024-gmail--yahoo-bulk-sender-pattern]

Putting the pieces together: emit a one-click `List-Unsubscribe`, filter every send against your suppression list, and feed inbound ARF complaints back into that same list. This closes the loop the bulk-sender rules require — recipients can always unsubscribe in one click, and a spam complaint permanently suppresses the complainer.

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { buildListUnsubscribe, createSuppressionStore, filterSuppressed, parseArfReport } from "@visulima/email/deliverability";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
const suppression = createSuppressionStore();

// 1. Pre-send: drop anyone on the suppression list, attach a one-click unsubscribe.
const sendBulk = async (recipients: { email: string }[]) => {
    const { allowed } = await filterSuppressed(recipients, suppression);

    if (allowed.length === 0) {
        return;
    }

    const message = new MailMessage()
        .to(allowed)
        .from("newsletter@example.com")
        .subject("This week at Acme")
        .html("<h1>Hello</h1>")
        .setHeaders(
            buildListUnsubscribe({
                url: "https://example.com/unsub?id=abc",
                mailto: "unsubscribe@example.com",
                oneClick: true,
            }),
        );

    await mail.send(message);
};

// 2. Inbound ARF webhook: a spam complaint suppresses the complainer.
const handleComplaint = async (rawArfEmail: string) => {
    const report = parseArfReport(rawArfEmail);

    if (report.originalRcptTo) {
        await suppression.add(report.originalRcptTo, "complaint", { source: "fbl", reportedDomain: report.reportedDomain });
    }
};
```


# Events (/docs/packages/email/events/introduction)



# Events [#events]

`@visulima/email/events` gives you a single, provider-agnostic way to observe what happens to your mail. Both internal send-lifecycle signals (queued, attempt, sent, failed) and normalized provider webhook events (delivered, opened, clicked, bounced, complained, deferred, unsubscribed) converge onto one `EmailEvent` shape, so you can wire a single subscriber and reconstruct a complete per-message timeline from one stream.

```typescript
import { ALL_EVENTS, EventBus, MemoryEventStore } from "@visulima/email/events";
import type { EmailEvent, EmailEventType, EventStore } from "@visulima/email/events";
```

## The EmailEvent Shape [#the-emailevent-shape]

Every event — whether emitted by the send pipeline or derived from a webhook — uses the same interface:

```typescript
interface EmailEvent {
    /** A unique id for this event. */
    id: string;

    /** The kind of event. */
    type: EmailEventType;

    /** When the event occurred. */
    timestamp: Date;

    /** The message this event concerns. */
    messageId?: string;

    /** The recipient address this event concerns, when applicable. */
    recipient?: string;

    /** The provider that produced (or will produce) the message. */
    provider?: string;

    /** Arbitrary structured payload (provider response, bounce sub-type, click URL, …). */
    data?: Record<string, unknown>;
}
```

### Event Types [#event-types]

`type` is an `EmailEventType`, one of:

| Type           | Origin           | Description                                        |
| -------------- | ---------------- | -------------------------------------------------- |
| `queued`       | Send pipeline    | The message was accepted into a queue.             |
| `attempt`      | Send pipeline    | A delivery attempt is starting.                    |
| `sent`         | Send pipeline    | The provider accepted the message for delivery.    |
| `delivered`    | Provider webhook | The receiving mail server accepted the message.    |
| `opened`       | Provider webhook | The recipient opened the message.                  |
| `clicked`      | Provider webhook | The recipient clicked a tracked link.              |
| `bounced`      | Provider webhook | The message bounced (hard or soft).                |
| `complained`   | Provider webhook | The recipient marked the message as spam.          |
| `deferred`     | Provider webhook | Delivery was temporarily deferred by the receiver. |
| `failed`       | Send pipeline    | A delivery attempt failed.                         |
| `unsubscribed` | Provider webhook | The recipient unsubscribed.                        |

The first group (`queued` → `failed`) is emitted by the send pipeline; the rest typically originate from provider webhooks (delivery and engagement signals).

## EventBus [#eventbus]

`EventBus` is a tiny synchronous pub/sub bus for `EmailEvent`s. Subscribe to a specific `EmailEventType` or to `ALL_EVENTS` (`"*"`) to receive everything.

```typescript
import { ALL_EVENTS, EventBus } from "@visulima/email/events";

const bus = new EventBus();

// Subscribe to a single type.
const unsubscribe = bus.on("sent", (event) => {
    console.log(`Sent ${event.messageId} via ${event.provider}`);
});

// Subscribe to every event.
bus.on(ALL_EVENTS, (event) => {
    console.log(`[${event.type}]`, event.messageId);
});

// Stop listening.
unsubscribe();
```

### Methods [#methods]

| Method                 | Description                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| `on(type, listener)`   | Subscribes a listener. Returns an unsubscribe function.                      |
| `once(type, listener)` | Subscribes a listener that is removed after its first invocation.            |
| `off(type, listener)`  | Removes a previously-added listener.                                         |
| `emit(event)`          | Dispatches an event to type-specific listeners, then to `ALL_EVENTS` ones.   |
| `clear(type?)`         | Removes all listeners, or only those for a single type when `type` is given. |

### Logging Lifecycle Events [#logging-lifecycle-events]

Wire an `EventBus` once and let every part of your app emit onto it:

```typescript
import { ALL_EVENTS, EventBus } from "@visulima/email/events";
import type { EmailEvent } from "@visulima/email/events";

const bus = new EventBus();

bus.on(ALL_EVENTS, (event: EmailEvent) => {
    console.log(`[${event.timestamp.toISOString()}] ${event.type}`, {
        messageId: event.messageId,
        recipient: event.recipient,
        provider: event.provider,
    });
});

// Emit from your send pipeline.
bus.emit({
    id: "evt_1",
    type: "queued",
    timestamp: new Date(),
    messageId: "msg_42",
    recipient: "user@example.com",
});

bus.emit({
    id: "evt_2",
    type: "sent",
    timestamp: new Date(),
    messageId: "msg_42",
    recipient: "user@example.com",
    provider: "resend",
});

// Emit from a normalized webhook handler.
bus.emit({
    id: "evt_3",
    type: "delivered",
    timestamp: new Date(),
    messageId: "msg_42",
    recipient: "user@example.com",
    provider: "resend",
});
```

### One-Time Listeners [#one-time-listeners]

Use `once()` to react to the next event of a type and then auto-remove the listener:

```typescript
bus.once("bounced", (event) => {
    console.warn(`First bounce for ${event.recipient}`, event.data);
});
```

## MemoryEventStore [#memoryeventstore]

`MemoryEventStore` is an in-memory `EventStore` that groups events by `messageId`, so you can reconstruct a complete, time-ordered timeline for any single message. Events without a `messageId` are kept under a shared bucket so nothing is silently dropped.

```typescript
import { MemoryEventStore } from "@visulima/email/events";

const store = new MemoryEventStore();
```

### Methods [#methods-1]

| Method                | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `append(event)`       | Appends an event to its message's bucket.                       |
| `timeline(messageId)` | Returns the time-ordered events for one message (oldest first). |
| `all()`               | Returns every stored event, ordered by timestamp.               |
| `clear()`             | Removes all stored events.                                      |

### Reconstructing a Per-Message Timeline [#reconstructing-a-per-message-timeline]

Append events to the store as they arrive, then read back the full timeline for a message:

```typescript
import { EventBus, MemoryEventStore } from "@visulima/email/events";

const bus = new EventBus();
const store = new MemoryEventStore();

// Persist every event the bus sees.
bus.on("*", (event) => {
    store.append(event);
});

// … events are emitted over the message's lifecycle …
bus.emit({ id: "evt_1", type: "queued", timestamp: new Date("2026-06-01T10:00:00Z"), messageId: "msg_42" });
bus.emit({ id: "evt_2", type: "sent", timestamp: new Date("2026-06-01T10:00:01Z"), messageId: "msg_42" });
bus.emit({ id: "evt_3", type: "delivered", timestamp: new Date("2026-06-01T10:00:05Z"), messageId: "msg_42" });
bus.emit({ id: "evt_4", type: "opened", timestamp: new Date("2026-06-01T10:02:00Z"), messageId: "msg_42" });

// Reconstruct the full, ordered history for one message.
for (const event of store.timeline("msg_42")) {
    console.log(event.type, "at", event.timestamp.toISOString());
}
// queued    at 2026-06-01T10:00:00.000Z
// sent      at 2026-06-01T10:00:01.000Z
// delivered at 2026-06-01T10:00:05.000Z
// opened    at 2026-06-01T10:02:00.000Z
```

## The EventStore Interface [#the-eventstore-interface]

`MemoryEventStore` is the built-in implementation. To persist events durably (database, log pipeline, analytics warehouse), implement the `EventStore` interface yourself:

```typescript
import type { EmailEvent, EventStore } from "@visulima/email/events";

class DatabaseEventStore implements EventStore {
    public async append(event: EmailEvent): Promise<void> {
        await db.emailEvents.insert(event);
    }

    public async timeline(messageId: string): Promise<EmailEvent[]> {
        return db.emailEvents.where({ messageId }).orderBy("timestamp", "asc");
    }
}
```

Both `append` and `timeline` may be synchronous or asynchronous, so the same interface fits an in-memory store and a remote database alike.


# Capability Guard (/docs/packages/email/getting-started/capability-guard)



# Capability Guard [#capability-guard]

Every provider declares which capabilities it supports through its `features` flags — `attachments`, `tagging`, `scheduling`, `html`, `customHeaders`, `replyTo`, `templates`, and more. Before a message is handed to the provider, `Mail` runs a **fail-fast** check: if the message uses a capability the provider has *explicitly* declared unsupported (`features[x] === false`), the send is rejected locally — no wasted network round-trip and no silent data loss.

## How it works [#how-it-works]

```typescript
import { createMail } from "@visulima/email";
import { awsSesProvider } from "@visulima/email/providers/aws-ses";

// AWS SES declares `tagging: false`
const mail = createMail(awsSesProvider({ accessKeyId, secretAccessKey, region }));

const result = await mail.send({
    from: { email: "noreply@example.com" },
    subject: "Hi",
    tags: ["promo"], // not representable by AWS SES
    text: "Body",
    to: { email: "user@example.com" },
});

result.success; // false
(result.error as { code?: string }).code; // "UNSUPPORTED_FEATURES"
```

The error message lists exactly which fields were rejected, and the `hint` contains a human-readable explanation per field.

> Capabilities left `undefined` are treated as "unknown" and are **never** rejected, so providers that publish a partial (or no) `features` map are never falsely blocked. Aggregate providers such as [`failover`](/docs/packages/email/providers/failover) and [`roundrobin`](/docs/packages/email/providers/roundrobin) deliberately leave routed-dependent capabilities undefined and delegate the decision to whichever mailer ultimately handles the message.

## Configuring the guard [#configuring-the-guard]

The behaviour is configurable per `Mail` instance via the second argument to `createMail`:

```typescript
createMail(provider, { featureCheck: "error" }); // default — reject unsupported fields
createMail(provider, { featureCheck: "warn" }); // log a warning and send anyway
createMail(provider, { featureCheck: "off" }); // skip the check entirely
```

| Mode      | Behaviour                                                                          |
| --------- | ---------------------------------------------------------------------------------- |
| `"error"` | (default) `send()` returns a failed `Result` with an `UNSUPPORTED_FEATURES` error. |
| `"warn"`  | Logs a warning (when a logger is attached) and sends the message anyway.           |
| `"off"`   | Skips the check entirely.                                                          |

`sendMany()` inherits the configured mode automatically — a rejected message yields an unsuccessful `Receipt` rather than throwing.

## Running the check standalone [#running-the-check-standalone]

You can run the same check yourself — for example inside a custom provider built with `defineProvider`:

```typescript
import { checkFeatureSupport } from "@visulima/email";
// or the focused entry point:
// import checkFeatureSupport from "@visulima/email/validation/check-feature-support";

const { supported, violations } = checkFeatureSupport(message, provider.features);

if (!supported) {
    for (const violation of violations) {
        console.warn(violation.message);
    }
}
```

`checkFeatureSupport(options, features?)` returns `{ supported: boolean, violations: FeatureViolation[] }`. When `features` is omitted the check is a no-op (`supported: true`).


# Configuration (/docs/packages/email/getting-started/configuration)



# Configuration [#configuration]

This guide covers how to configure email providers in your application.

## Provider Configuration [#provider-configuration]

Each provider has its own configuration options. Here are examples for common providers:

### Resend [#resend]

```typescript
import { resendProvider } from "@visulima/email/providers/resend";

const resend = resendProvider({
    apiKey: process.env.RESEND_API_KEY!,
    timeout: 30000, // Optional: request timeout in milliseconds
    retries: 3, // Optional: number of retry attempts
});
```

### AWS SES [#aws-ses]

```typescript
import { awsSesProvider } from "@visulima/email/providers/aws-ses";

const awsSes = awsSesProvider({
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: "us-east-1", // Optional, defaults to us-east-1
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### SMTP [#smtp]

```typescript
import { smtpProvider } from "@visulima/email/providers/smtp";

const smtp = smtpProvider({
    host: "smtp.example.com",
    port: 587,
    secure: false, // true for 465, false for other ports
    user: process.env.SMTP_USER!,
    password: process.env.SMTP_PASSWORD!,
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Zeptomail [#zeptomail]

```typescript
import { zeptomailProvider } from "@visulima/email/providers/zeptomail";

const zeptomail = zeptomailProvider({
    token: process.env.ZEPTOMAIL_TOKEN!, // Format: "Zoho-enczapikey <your_api_key>"
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Brevo [#brevo]

```typescript
import { brevoProvider } from "@visulima/email/providers/brevo";

const brevo = brevoProvider({
    apiKey: process.env.BREVO_API_KEY!,
    endpoint: "https://api.brevo.com/v3", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mailjet [#mailjet]

```typescript
import { mailjetProvider } from "@visulima/email/providers/mailjet";

const mailjet = mailjetProvider({
    apiKey: process.env.MAILJET_API_KEY!,
    apiSecret: process.env.MAILJET_API_SECRET!,
    endpoint: "https://api.mailjet.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### MailerSend [#mailersend]

```typescript
import { mailerSendProvider } from "@visulima/email/providers/mailersend";

const mailerSend = mailerSendProvider({
    apiToken: process.env.MAILERSEND_API_TOKEN!,
    endpoint: "https://api.mailersend.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mandrill [#mandrill]

```typescript
import { mandrillProvider } from "@visulima/email/providers/mandrill";

const mandrill = mandrillProvider({
    apiKey: process.env.MANDRILL_API_KEY!,
    endpoint: "https://mandrillapp.com/api/1.0", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### MailPace [#mailpace]

```typescript
import { mailPaceProvider } from "@visulima/email/providers/mailpace";

const mailPace = mailPaceProvider({
    apiToken: process.env.MAILPACE_API_TOKEN!,
    endpoint: "https://app.mailpace.com/api/v1", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mailtrap [#mailtrap]

```typescript
import { mailtrapProvider } from "@visulima/email/providers/mailtrap";

const mailtrap = mailtrapProvider({
    apiToken: process.env.MAILTRAP_API_TOKEN!,
    endpoint: "https://send.api.mailtrap.io", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Postal [#postal]

```typescript
import { postalProvider } from "@visulima/email/providers/postal";

const postal = postalProvider({
    host: process.env.POSTAL_HOST!,
    apiKey: process.env.POSTAL_API_KEY!,
    endpoint: `https://${process.env.POSTAL_HOST}/api/v1`, // Optional, auto-generated from host
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Azure Communication Services [#azure-communication-services]

```typescript
import { azureProvider } from "@visulima/email/providers/azure";

// Using access token
const azure = azureProvider({
    accessToken: process.env.AZURE_ACCESS_TOKEN!,
    region: process.env.AZURE_REGION!, // e.g., "eastus", "westus"
    endpoint: `https://${process.env.AZURE_REGION}.communication.azure.com`, // Optional, auto-generated
    timeout: 30000, // Optional
    retries: 3, // Optional
});

// Or using connection string
const azureWithConnectionString = azureProvider({
    connectionString: process.env.AZURE_CONNECTION_STRING!,
    region: process.env.AZURE_REGION!,
});
```

### Infobip [#infobip]

```typescript
import { infobipProvider } from "@visulima/email/providers/infobip";

const infobip = infobipProvider({
    apiKey: process.env.INFOBIP_API_KEY!,
    baseUrl: "https://api.infobip.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Scaleway [#scaleway]

```typescript
import { scalewayProvider } from "@visulima/email/providers/scaleway";

const scaleway = scalewayProvider({
    apiKey: process.env.SCALEWAY_API_KEY!,
    region: process.env.SCALEWAY_REGION!, // e.g., "fr-par", "nl-ams"
    endpoint: "https://api.scaleway.com/transactional-email/v1alpha1", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### AhaSend [#ahasend]

```typescript
import { ahaSendProvider } from "@visulima/email/providers/ahasend";

const ahaSend = ahaSendProvider({
    apiKey: process.env.AHASEND_API_KEY!,
    endpoint: "https://api.ahasend.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mailomat [#mailomat]

```typescript
import { mailomatProvider } from "@visulima/email/providers/mailomat";

const mailomat = mailomatProvider({
    apiKey: process.env.MAILOMAT_API_KEY!,
    endpoint: "https://api.mailomat.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Sweego [#sweego]

```typescript
import { sweegoProvider } from "@visulima/email/providers/sweego";

const sweego = sweegoProvider({
    apiKey: process.env.SWEEGO_API_KEY!,
    endpoint: "https://api.sweego.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mailgun [#mailgun]

```typescript
import { mailgunProvider } from "@visulima/email/providers/mailgun";

const mailgun = mailgunProvider({
    apiKey: process.env.MAILGUN_API_KEY!,
    domain: process.env.MAILGUN_DOMAIN!, // Required: Your Mailgun domain
    endpoint: "https://api.mailgun.net", // Optional: Use https://api.eu.mailgun.net for EU accounts
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Postmark [#postmark]

```typescript
import { postmarkProvider } from "@visulima/email/providers/postmark";

const postmark = postmarkProvider({
    serverToken: process.env.POSTMARK_SERVER_TOKEN!,
    endpoint: "https://api.postmarkapp.com", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### SendGrid [#sendgrid]

```typescript
import { sendGridProvider } from "@visulima/email/providers/sendgrid";

const sendgrid = sendGridProvider({
    apiKey: process.env.SENDGRID_API_KEY!,
    endpoint: "https://api.sendgrid.com/v3", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Plunk [#plunk]

```typescript
import { plunkProvider } from "@visulima/email/providers/plunk";

const plunk = plunkProvider({
    apiKey: process.env.PLUNK_API_KEY!,
    endpoint: "https://api.useplunk.com/v1", // Optional, defaults to this
    timeout: 30000, // Optional
    retries: 3, // Optional
});
```

### Mock (for Testing) [#mock-for-testing]

```typescript
import { mockProvider } from "@visulima/email/providers/mock";

const mock = mockProvider({
    debug: true, // Optional: enable debug logging
    delay: 100, // Optional: simulate delay in milliseconds
    failureRate: 0.1, // Optional: failure rate (0.0 to 1.0)
    simulateFailure: false, // Optional: always fail if true
    timeout: 0, // Optional: not used by mock provider
    retries: 0, // Optional: not used by mock provider
});
```

## Mail Options [#mail-options]

`createMail` accepts an optional second argument to configure the `Mail` instance itself (as opposed to the provider):

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }), {
    featureCheck: "error", // "error" (default) | "warn" | "off"
});
```

`featureCheck` controls the fail-fast [capability guard](/docs/packages/email/getting-started/capability-guard), which rejects messages that use fields the provider has explicitly declared unsupported before they reach the network. See the dedicated guide for details.

## Environment Variables [#environment-variables]

It's recommended to store sensitive configuration in environment variables:

```bash
# .env
RESEND_API_KEY=re_xxx
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
SMTP_USER=user@example.com
SMTP_PASSWORD=password
ZEPTOMAIL_TOKEN=Zoho-enczapikey YOUR_API_KEY_HERE
BREVO_API_KEY=your-brevo-api-key
MAILJET_API_KEY=your-mailjet-api-key
MAILJET_API_SECRET=your-mailjet-api-secret
MAILERSEND_API_TOKEN=your-mailersend-api-token
MANDRILL_API_KEY=your-mandrill-api-key
MAILPACE_API_TOKEN=your-mailpace-api-token
MAILTRAP_API_TOKEN=your-mailtrap-api-token
POSTAL_HOST=your-postal-server.com
POSTAL_API_KEY=your-postal-api-key
AZURE_ACCESS_TOKEN=your-azure-access-token
AZURE_REGION=eastus
AZURE_CONNECTION_STRING=endpoint=https://...;accesskey=...
INFOBIP_API_KEY=your-infobip-api-key
SCALEWAY_API_KEY=your-scaleway-api-key
SCALEWAY_REGION=fr-par
AHASEND_API_KEY=your-ahasend-api-key
MAILOMAT_API_KEY=your-mailomat-api-key
SWEEGO_API_KEY=your-sweego-api-key
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=your-domain.com
POSTMARK_SERVER_TOKEN=your-postmark-server-token
SENDGRID_API_KEY=SG.your-sendgrid-api-key
PLUNK_API_KEY=your-plunk-api-key
```

Then use them in your code:

```typescript
const resend = resendProvider({
    apiKey: process.env.RESEND_API_KEY!,
});
```

## Typing Configuration [#typing-configuration]

If you want to type your configuration objects, you can import the config types from each provider:

```typescript
import { resendProvider, type ResendConfig } from "@visulima/email/providers/resend";
import { smtpProvider, type SmtpConfig } from "@visulima/email/providers/smtp";

// Type your configuration
const resendConfig: ResendConfig = {
    apiKey: process.env.RESEND_API_KEY!,
    timeout: 30000,
    retries: 3,
};

const smtpConfig: SmtpConfig = {
    host: "smtp.example.com",
    port: 587,
    secure: false,
    user: process.env.SMTP_USER!,
    password: process.env.SMTP_PASSWORD!,
};

// Use typed configs
const resend = resendProvider(resendConfig);
const smtp = smtpProvider(smtpConfig);
```

Each provider exports its own config type from its provider path. For example:

* `ResendConfig` from `@visulima/email/providers/resend`
* `SmtpConfig` from `@visulima/email/providers/smtp`
* `AwsSesConfig` from `@visulima/email/providers/aws-ses`
* `BrevoConfig` from `@visulima/email/providers/brevo`
* `MailgunConfig` from `@visulima/email/providers/mailgun`
* `MailjetConfig` from `@visulima/email/providers/mailjet`
* `MailerSendConfig` from `@visulima/email/providers/mailersend`
* `MandrillConfig` from `@visulima/email/providers/mandrill`
* `MailPaceConfig` from `@visulima/email/providers/mailpace`
* `MailtrapConfig` from `@visulima/email/providers/mailtrap`
* `PostalConfig` from `@visulima/email/providers/postal`
* `PostmarkConfig` from `@visulima/email/providers/postmark`
* `AzureConfig` from `@visulima/email/providers/azure`
* `InfobipConfig` from `@visulima/email/providers/infobip`
* `ScalewayConfig` from `@visulima/email/providers/scaleway`
* `AhaSendConfig` from `@visulima/email/providers/ahasend`
* `MailomatConfig` from `@visulima/email/providers/mailomat`
* `SweegoConfig` from `@visulima/email/providers/sweego`
* `SendGridConfig` from `@visulima/email/providers/sendgrid`
* `PlunkConfig` from `@visulima/email/providers/plunk`
* `MockConfig` from `@visulima/email/providers/mock`
* `OpenTelemetryConfig` from `@visulima/email/providers/opentelemetry`
* And so on for other providers

## Provider Factory Pattern [#provider-factory-pattern]

All providers follow a factory pattern. They return a `ProviderFactory` function that creates a provider instance:

```typescript
import { resendProvider } from "@visulima/email/providers/resend";

// resendProvider is a factory function
const providerFactory = resendProvider;

// Call it with configuration to get a provider
const provider = providerFactory({ apiKey: "re_xxx" });
```

## Multiple Providers [#multiple-providers]

You can configure multiple providers and switch between them:

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { smtpProvider } from "@visulima/email/providers/smtp";

const resend = resendProvider({ apiKey: "re_xxx" });
const smtp = smtpProvider({
    host: "smtp.example.com",
    port: 587,
    user: "user@example.com",
    password: "password",
});

// Use Resend for production
const productionMail = createMail(resend);

// Use SMTP for development
const developmentMail = createMail(smtp);
```

## Failover Configuration [#failover-configuration]

Configure failover to automatically switch providers on failure:

```typescript
import { failoverProvider } from "@visulima/email/providers/failover";
import { resendProvider } from "@visulima/email/providers/resend";
import { smtpProvider } from "@visulima/email/providers/smtp";

const failover = failoverProvider({
    mailers: [
        resendProvider({ apiKey: "re_xxx" }),
        smtpProvider({
            host: "smtp.example.com",
            port: 587,
            user: "user@example.com",
            password: "password",
        }),
    ],
    retryAfter: 60, // Wait 60 seconds before trying next provider
    timeout: 30000,
    retries: 3,
});
```

## Round Robin Configuration [#round-robin-configuration]

Configure round robin for load balancing:

```typescript
import { roundRobinProvider } from "@visulima/email/providers/roundrobin";
import { resendProvider } from "@visulima/email/providers/resend";
import { smtpProvider } from "@visulima/email/providers/smtp";

const roundRobin = roundRobinProvider({
    mailers: [
        resendProvider({ apiKey: "re_xxx" }),
        smtpProvider({
            host: "smtp.example.com",
            port: 587,
            user: "user@example.com",
            password: "password",
        }),
    ],
    retryAfter: 60,
    timeout: 30000,
    retries: 3,
});
```

## Default Email Configuration [#default-email-configuration]

You can configure default values for all emails sent through a Mail instance. This is useful when you want to set a default `from` address, `replyTo` address, or headers that apply to all emails.

### Setting Default From Address [#setting-default-from-address]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Set default from address
mail.setFrom({ email: "noreply@example.com", name: "My App" });

// Now all emails will use this from address if not specified
const message = new MailMessage().to("user@example.com").subject("Hello").html("<h1>Hello World</h1>");
// No need to set .from() - it will use the default

await mail.send(message);
```

### Setting Default Reply-To Address [#setting-default-reply-to-address]

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Set default reply-to address
mail.setReplyTo({ email: "support@example.com" });

// All emails will include this reply-to if not specified in the message
```

### Setting Default Headers [#setting-default-headers]

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Set default headers
mail.setHeaders({
    "X-App-Name": "MyApp",
    "X-Version": "1.0.0",
    "X-Environment": "production",
});

// These headers will be added to all emails
// Message-specific headers will take precedence if they conflict
```

### Chaining Configuration Methods [#chaining-configuration-methods]

You can chain the configuration methods together:

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }))
    .setFrom({ email: "noreply@example.com", name: "My App" })
    .setReplyTo({ email: "support@example.com" })
    .setHeaders({ "X-App-Name": "MyApp" });
```

### Overriding Defaults [#overriding-defaults]

Default values are only applied if the corresponding field is not set in the message:

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
mail.setFrom({ email: "noreply@example.com" });

// This message will use the default from address
const message1 = new MailMessage().to("user@example.com").subject("Hello").html("<h1>Hello</h1>");
await mail.send(message1); // Uses noreply@example.com

// This message overrides the default
const message2 = new MailMessage()
    .to("user@example.com")
    .from({ email: "custom@example.com" }) // Overrides default
    .subject("Hello")
    .html("<h1>Hello</h1>");
await mail.send(message2); // Uses custom@example.com
```

### Header Merging [#header-merging]

When setting default headers, they are merged with message-specific headers. Message headers take precedence:

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
mail.setHeaders({
    "X-App-Name": "MyApp",
    "X-Version": "1.0.0",
});

const message = new MailMessage()
    .to("user@example.com")
    .from("sender@example.com")
    .subject("Hello")
    .html("<h1>Hello</h1>")
    .header("X-Version", "2.0.0") // Overrides default
    .header("X-Custom", "value"); // Additional header

// Final headers will be:
// X-App-Name: MyApp (from default)
// X-Version: 2.0.0 (from message, overrides default)
// X-Custom: value (from message)
```

## Next Steps [#next-steps]

* [Sending Mail](/docs/packages/email/getting-started/sending-mail) - Learn how to send emails
* [Providers](/docs/packages/email/providers/introduction) - Explore all available providers


# Introduction (/docs/packages/email/getting-started/introduction)



# Introduction [#introduction]

This guide will help you get started with @visulima/email. We'll cover the core concepts and show you how to send your first email.

## Core Concepts [#core-concepts]

@visulima/email is built around a few key concepts:

### Mail Instance [#mail-instance]

The `Mail` class is the main entry point for sending emails. You create a `Mail` instance with a provider:

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
```

### Providers [#providers]

Providers are responsible for actually sending emails. Each provider implements a common interface, allowing you to switch providers without changing your code.

```typescript
import { resendProvider } from "@visulima/email/providers/resend";
import { smtpProvider } from "@visulima/email/providers/smtp";

// Use Resend
const resend = resendProvider({ apiKey: "re_xxx" });

// Or use SMTP
const smtp = smtpProvider({
    host: "smtp.example.com",
    port: 587,
    user: "user@example.com",
    password: "password",
});
```

### Mail Messages [#mail-messages]

Mail messages are built using the fluent `MailMessage` API:

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Basic Example [#basic-example]

Here's a complete example of sending an email:

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

// 1. Create a provider
const resend = resendProvider({
    apiKey: process.env.RESEND_API_KEY!,
});

// 2. Create a Mail instance
const mail = createMail(resend);

// Optional: Set default configuration for all emails
mail.setFrom({ email: "noreply@example.com", name: "My App" });

// 3. Build and send a message
import { MailMessage } from "@visulima/email";

const message = new MailMessage()
    .to("user@example.com")
    // .from() is optional if set via mail.setFrom()
    .subject("Welcome!")
    .html("<h1>Welcome to our service!</h1>")
    .text("Welcome to our service!");

const result = await mail.send(message);

// 4. Handle the result
if (result.success) {
    console.log("Email sent successfully:", result.data?.messageId);
} else {
    console.error("Failed to send email:", result.error);
}
```

## Creating Drafts [#creating-drafts]

You can create draft emails in EML (RFC 822) format without sending them:

```typescript
import { writeFile } from "fs/promises";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

// Create a draft in EML format (doesn't send)
const eml = await mail.draft(message);

// Save to file - can be opened by email clients
await writeFile("draft.eml", eml);
```

## Next Steps [#next-steps]

* [Configuration](/docs/packages/email/getting-started/configuration) - Configure providers
* [Sending Mail](/docs/packages/email/getting-started/sending-mail) - Learn different ways to send emails
* [Building Messages](/docs/packages/email/mail-messages/building-messages) - Explore the message builder API


# Sending Mail (/docs/packages/email/getting-started/sending-mail)



# Sending Mail [#sending-mail]

This guide covers the different ways to send emails with @visulima/email.

## Using the Message Builder [#using-the-message-builder]

The most common way to send emails is using the fluent message builder API:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").text("Hello World");

const result = await mail.send(message);
```

### Chaining Methods [#chaining-methods]

The message builder supports method chaining for a fluent API:

```typescript
const message = new MailMessage()
    .to("user@example.com")
    .cc("cc@example.com")
    .bcc("bcc@example.com")
    .from("sender@example.com")
    .replyTo("reply@example.com")
    .subject("Hello")
    .html("<h1>Hello World</h1>")
    .text("Hello World");

const result = await mail.send(message);
```

### Multiple Recipients [#multiple-recipients]

You can send to multiple recipients:

```typescript
const message = new MailMessage().to(["user1@example.com", "user2@example.com"]).from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

Or use the `EmailAddress` format:

```typescript
const message = new MailMessage()
    .to([
        { email: "user1@example.com", name: "User 1" },
        { email: "user2@example.com", name: "User 2" },
    ])
    .from({ email: "sender@example.com", name: "Sender" })
    .subject("Hello")
    .html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Direct Email Sending [#direct-email-sending]

You can also send emails directly using `EmailOptions`:

```typescript
import type { EmailOptions } from "@visulima/email";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const emailOptions: EmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello World</h1>",
    text: "Hello World",
};

const result = await mail.send(emailOptions);
```

## Creating Draft Emails [#creating-draft-emails]

You can create draft emails in EML (RFC 822) format without sending them. This is useful for previewing, saving for later, or testing email content. The `draft()` method returns the email as an EML string with an `X-Unsent: 1` header automatically added.

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { writeFile } from "fs/promises";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// Create a draft from MailMessage
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

const eml = await mail.draft(message);

// Save draft to file
await writeFile("draft.eml", eml);

// Or preview the draft
console.log("Draft EML:", eml);
```

### Using Drafts with EmailOptions [#using-drafts-with-emailoptions]

You can also create drafts from `EmailOptions`:

```typescript
const eml = await mail.draft({
    to: "user@example.com",
    from: "sender@example.com",
    subject: "Hello",
    html: "<h1>Hello World</h1>",
});

// Save draft to database or file system
await saveDraftToFile("draft.eml", eml);
```

### Drafts with Global Configuration [#drafts-with-global-configuration]

Drafts automatically apply global configuration (default from, reply-to, headers):

```typescript
const mail = createMail(resendProvider({ apiKey: "re_xxx" }))
    .setFrom({ email: "noreply@example.com" })
    .setHeaders({ "X-App-Name": "MyApp" });

const message = new MailMessage().to("user@example.com").subject("Hello").html("<h1>Hello</h1>");

// Draft will include the global from address and headers
const eml = await mail.draft(message);
// The EML will include "X-App-Name": "MyApp" and "X-Unsent": "1" headers
```

### Serving Drafts as Downloads [#serving-drafts-as-downloads]

You can serve drafts as downloadable EML files (similar to Symfony):

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

// In your HTTP handler (e.g., Express, Fastify, etc.)
app.get("/draft/:id", async (req, res) => {
    const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

    const eml = await mail.draft(message);

    res.setHeader("Content-Type", "message/rfc822");
    res.setHeader("Content-Disposition", 'attachment; filename="draft.eml"');
    res.send(eml);
});
```

### Important Notes [#important-notes]

* Drafts are created in EML (RFC 822) format with the `X-Unsent: 1` header automatically added
* The `draft()` method returns a string (EML format) that can be saved to a file or database
* EML files can be opened by most email clients (Outlook, Thunderbird, Apple Mail, etc.)
* The EML format is useful for archiving, previewing, or sharing draft emails

## Handling Results [#handling-results]

All sending methods return a `Result<EmailResult>` object:

```typescript
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello</h1>");
const result = await mail.send(message);

if (result.success) {
    console.log("Email sent:", result.data?.messageId);
    console.log("Provider:", result.data?.provider);
    console.log("Timestamp:", result.data?.timestamp);
} else {
    console.error("Failed to send email:", result.error);
}
```

## Error Handling [#error-handling]

Always check the result and handle errors appropriately:

```typescript
try {
    const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello</h1>");
    const result = await mail.send(message);

    if (!result.success) {
        // Handle provider-specific errors
        if (result.error instanceof Error) {
            console.error("Error:", result.error.message);
        }
        // Retry logic, fallback provider, etc.
    }
} catch (error) {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
}
```

## Validating Email Addresses [#validating-email-addresses]

Before sending emails, you can validate email addresses to ensure they're valid and not from disposable email services.

### Basic Email Validation [#basic-email-validation]

```typescript
import { validateEmail } from "@visulima/email/validation/validate-email";

const email = "user@example.com";

if (!validateEmail(email)) {
    throw new Error("Invalid email address");
}

// Proceed with sending
const message = new MailMessage().to(email).from("sender@example.com").subject("Hello").html("<h1>Hello</h1>");
await mail.send(message);
```

### Disposable Email Detection [#disposable-email-detection]

To prevent sending emails to disposable/temporary email addresses, use the disposable email detection utility:

**Use it before sending:**

```typescript
import { isDisposableEmail } from "@visulima/email/validation/disposable-email-domains";
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const recipientEmail = "user@mailinator.com";

// Check if email is disposable
if (isDisposableEmail(recipientEmail)) {
    throw new Error("Disposable email addresses are not allowed");
}

// Send email if validation passes
const message = new MailMessage().to(recipientEmail).from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
const result = await mail.send(message);
```

### Validating Multiple Recipients [#validating-multiple-recipients]

When sending to multiple recipients, validate all addresses:

```typescript
import { isDisposableEmail } from "@visulima/email/validation/disposable-email-domains";
import { validateEmail } from "@visulima/email/validation/validate-email";
import { MailMessage } from "@visulima/email";

const recipients = ["user1@example.com", "user2@mailinator.com", "user3@example.com"];

// Filter out invalid and disposable emails
const validRecipients = recipients.filter((email) => {
    return validateEmail(email) && !isDisposableEmail(email);
});

if (validRecipients.length === 0) {
    throw new Error("No valid recipients");
}

// Send to valid recipients only
const message = new MailMessage().to(validRecipients).from("sender@example.com").subject("Hello").html("<h1>Hello</h1>");
await mail.send(message);
```

### Custom Disposable Domains [#custom-disposable-domains]

You can also add custom disposable domains to check:

```typescript
import { isDisposableEmail } from "@visulima/email/validation/disposable-email-domains";

const customDisposableDomains = new Set(["my-disposable.com", "test-temp.com"]);

if (isDisposableEmail("user@my-disposable.com", customDisposableDomains)) {
    throw new Error("Disposable email addresses are not allowed");
}
```

### Role Account Detection [#role-account-detection]

Detect if an email address is a role account (non-personal email addresses like `noreply@`, `support@`, `admin@`, etc.):

```typescript
import { isRoleAccount } from "@visulima/email/validation/role-accounts";

if (isRoleAccount("noreply@example.com")) {
    console.log("This is a role account (non-personal)");
}

// With custom role prefixes
const customPrefixes = new Set(["custom-role", "my-role"]);
if (isRoleAccount("custom-role@example.com", customPrefixes)) {
    console.log("Custom role account detected");
}
```

### MX Record Checking [#mx-record-checking]

Verify that a domain has valid MX (Mail Exchange) records before sending:

```typescript
import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
import { InMemoryCache } from "@visulima/email/utils/cache";

const domain = "example.com";

// Without cache
const mxResult = await checkMxRecords(domain);

// With cache (recommended for better performance)
const cache = new InMemoryCache();
const mxResultCached = await checkMxRecords(domain, {
    cache,
    ttl: 5 * 60 * 1000, // Cache for 5 minutes
});

if (!mxResultCached.valid) {
    throw new Error(`Domain ${domain} has no valid MX records`);
}

console.log("MX records found:", mxResultCached.records);
```

### SMTP Verification [#smtp-verification]

Verify if an email address exists by connecting to the mail server:

```typescript
import { verifySmtp } from "@visulima/email/validation/verify-smtp";
import { InMemoryCache } from "@visulima/email/utils/cache";
import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";

// Create separate caches for MX records and SMTP results
const mxCache = new InMemoryCache<MxCheckResult>();
const smtpCache = new InMemoryCache<SmtpVerificationResult>();

const result = await verifySmtp("user@example.com", {
    timeout: 5000,
    fromEmail: "test@example.com",
    port: 25,
    cache: mxCache, // Optional: cache MX records
    smtpCache, // Optional: cache SMTP verification results
    ttl: 5 * 60 * 1000, // Cache for 5 minutes
});

if (result.valid) {
    console.log("Email address exists");
} else {
    console.error("Verification failed:", result.error);
}
```

**Note:** Many mail servers block SMTP verification to prevent email harvesting. This method may not work for all domains and should be used with caution.

### Comprehensive Email Verification [#comprehensive-email-verification]

Use the comprehensive verification function to check multiple aspects of an email address:

```typescript
import { verifyEmail } from "@visulima/email/validation/verify-email";
import { InMemoryCache } from "@visulima/email/utils/cache";
import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";

// Create separate caches for MX records and SMTP results
const mxCache = new InMemoryCache<MxCheckResult>();
const smtpCache = new InMemoryCache<SmtpVerificationResult>();

const result = await verifyEmail("user@example.com", {
    checkDisposable: true,
    checkRoleAccount: true,
    checkMx: true,
    checkSmtp: false, // Optional: many servers block SMTP verification
    cache: mxCache, // Optional: cache MX records
    smtpCache, // Optional: cache SMTP verification results
});

if (result.valid) {
    console.log("Email passed all checks");
} else {
    console.error("Validation errors:", result.errors);
    console.warn("Warnings:", result.warnings);
}

// Access individual check results
if (result.disposable) {
    console.warn("Email is from a disposable service");
}

if (result.roleAccount) {
    console.warn("Email appears to be a role account");
}

if (result.mxValid === false) {
    console.error("Domain has no valid MX records");
}
```

### Complete Validation Example [#complete-validation-example]

Here's a complete example combining all validation checks:

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { InMemoryCache } from "@visulima/email/utils/cache";
import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";
import { verifyEmail } from "@visulima/email/validation/verify-email";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
// Reuse cache instances across requests
const mxCache = new InMemoryCache<MxCheckResult>();
const smtpCache = new InMemoryCache<SmtpVerificationResult>();

const validateAndSend = async (recipientEmail: string) => {
    // Comprehensive verification with caching
    const verification = await verifyEmail(recipientEmail, {
        checkDisposable: true,
        checkRoleAccount: true,
        checkMx: true,
        checkSmtp: false,
        cache: mxCache, // Cache MX records
        smtpCache, // Cache SMTP verification results
    });

    if (!verification.valid) {
        const errors = verification.errors.join(", ");
        throw new Error(`Email validation failed: ${errors}`);
    }

    if (verification.warnings.length > 0) {
        console.warn("Email warnings:", verification.warnings);
    }

    // Send email
    const message = new MailMessage().to(recipientEmail).from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
    const result = await mail.send(message);

    if (!result.success) {
        throw result.error;
    }

    return result.data;
};

// Use the validation function
try {
    const emailResult = await validateAndSend("user@example.com");
    console.log("Email sent:", emailResult?.messageId);
} catch (error) {
    console.error("Failed to send email:", error);
}
```

### Normalizing Email Aliases [#normalizing-email-aliases]

Some email providers support aliases that point to the same mailbox. Normalize emails to their canonical form to prevent duplicate accounts:

```typescript
import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";

// Gmail: removes dots and plus aliases
const normalized = normalizeEmailAliases("example+test@gmail.com");
// Returns: "example@gmail.com"

// Use before storing in database or checking for duplicates
const userEmail = normalizeEmailAliases("user.name+tag@gmail.com");
// Store "username@gmail.com" instead of "user.name+tag@gmail.com"
```

**Supported Providers:**

* **Gmail**: Removes dots (`.`) and plus aliases (`+`)
* **Yahoo, Outlook, Hotmail, Live, MSN, iCloud, ProtonMail, Zoho, FastMail, Mail.com, GMX**: Removes plus aliases (`+`) only, dots are preserved

## Batch Sending with Personalization [#batch-sending-with-personalization]

`mail.sendBatch(base, personalizations, options?)` sends one message per personalization, built from a shared base message. Each personalization overrides the recipients (and optionally `subject`, `cc`, `bcc`, `replyTo`, and `headers`) on top of the base. Results stream back as receipts, exactly like `sendMany`.

```typescript
import { createMail } from "@visulima/email";

const mail = createMail(provider);

for await (const receipt of mail.sendBatch({ from: { email: "news@example.com" }, subject: "Hello", html: "<p>Hi</p>" }, [
    { to: { email: "a@example.com" } },
    { subject: "Custom subject", to: { email: "b@example.com" } },
])) {
    if (receipt.successful) {
        console.log("Sent:", receipt.messageId);
    }
}
```

Pass a `render` function to treat the base `subject`/`html`/`text` as templates and render them per recipient with that recipient's `data`:

```typescript
import { renderHandlebars } from "@visulima/email/template/handlebars";

await Array.fromAsync(
    mail.sendBatch(
        { from: { email: "news@example.com" }, subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>" },
        [
            { to: { email: "bob@example.com" }, data: { name: "Bob" } },
            { to: { email: "ada@example.com" }, data: { name: "Ada" } },
        ],
        { render: (template, data) => renderHandlebars(template, data) },
    ),
);
```

Pass `{ signal }` (an `AbortSignal`) to cancel the batch mid-flight.

## Result Helpers [#result-helpers]

Every `send` returns a `Result<EmailResult>` (`{ success, data?, error? }`). The helpers exported from the package root (and from `@visulima/email/utils/result`) make branching ergonomic:

```typescript
import { isOk, isErr, unwrap, unwrapOr, mapOk, tryAsync } from "@visulima/email";

const result = await mail.send(message);

if (isOk(result)) {
    console.log(result.data.messageId); // `data` is narrowed to be present
}

const messageId = unwrapOr(
    mapOk(result, (data) => data.messageId),
    "unknown",
);

// `tryAsync` captures any throwing async call as a Result instead of throwing:
const wrapped = await tryAsync(() => mail.send(message).then(unwrap));
```

## Next Steps [#next-steps]

* [Building Messages](/docs/packages/email/mail-messages/building-messages) - Learn more about the message builder
* [Attachments](/docs/packages/email/mail-messages/attachments) - Add attachments to your emails
* [Middleware](/docs/packages/email/middleware/introduction) - Retry, rate-limit, circuit breaker, dedupe
* [Queue](/docs/packages/email/queue/introduction) - Durable background sending
* [Testing](/docs/packages/email/testing/introduction) - The mock provider and Vitest matchers


# Inbound (/docs/packages/email/inbound/introduction)



# Inbound [#inbound]

Every provider that receives mail on your behalf — Postmark, SendGrid Inbound Parse, Mailgun Routes, Cloudflare Email Workers, AWS SES — posts you a different webhook payload. The `@visulima/email/inbound` subpath normalizes all of them onto one shape, `InboundEmail`, so the rest of your application is provider-agnostic. It also bundles helpers for the things you actually do with inbound mail: extracting the new reply text out of a quoted history, stitching messages into conversation threads, and parsing addresses.

## The normalized shape: `InboundEmail` [#the-normalized-shape-inboundemail]

Every `parse*Inbound` adapter maps its provider's payload onto this shape:

```typescript
interface InboundAddress {
    email: string;
    name?: string;
}

interface InboundAttachment {
    filename: string;
    contentType?: string;
    content?: string; // base64, when the provider inlines it
    size?: number;
    cid?: string; // Content-ID, for inline attachments
}

interface InboundEmail {
    from?: InboundAddress;
    to: InboundAddress[];
    cc: InboundAddress[];
    bcc: InboundAddress[];
    replyTo?: InboundAddress;
    subject?: string;
    text?: string;
    html?: string;
    headers: Record<string, string>; // keys are lower-cased
    messageId?: string;
    inReplyTo?: string;
    references: string[]; // oldest first
    attachments: InboundAttachment[];
    provider: string; // the provider this was parsed from
    raw?: unknown; // the original payload, for provider-specific fields
}
```

Headers are keyed by their **lower-cased** name. `references` is an array of bare Message-IDs (oldest first). `raw` always holds the original payload so you can reach for provider-specific fields the normalized shape doesn't carry.

## Provider parsers [#provider-parsers]

Each parser takes that provider's webhook payload and returns an `InboundEmail`.

### Postmark (`parsePostmarkInbound`) [#postmark-parsepostmarkinbound]

```typescript
import { parsePostmarkInbound } from "@visulima/email/inbound";

const email = parsePostmarkInbound(await request.json());
```

### SendGrid (`parseSendGridInbound`) [#sendgrid-parsesendgridinbound]

SendGrid's [Inbound Parse](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/setting-up-the-inbound-parse-webhook) posts `multipart/form-data` fields. Its `headers` field is a single raw string, which the parser splits for you.

```typescript
import { parseSendGridInbound } from "@visulima/email/inbound";

// Collect the parsed multipart fields into a plain object first.
const email = parseSendGridInbound(formFields);
```

### Mailgun (`parseMailgunInbound`) [#mailgun-parsemailguninbound]

Mailgun's `message-headers` field is either a JSON array of `[name, value]` pairs or a string; the parser accepts both.

```typescript
import { parseMailgunInbound } from "@visulima/email/inbound";

const email = parseMailgunInbound(formFields);
```

### Cloudflare Email Workers (`parseCloudflareInbound`) [#cloudflare-email-workers-parsecloudflareinbound]

Cloudflare delivers a `ForwardableEmailMessage` whose body is only available as a **stream**. Decode the body yourself and pass the result via `text`/`html` alongside the message.

```typescript
import { parseCloudflareInbound } from "@visulima/email/inbound";

export default {
    async email(message, env, ctx) {
        const text = await new Response(message.raw).text();

        const email = parseCloudflareInbound({
            from: message.from,
            to: message.to,
            headers: message.headers, // a Headers instance
            text,
        });

        // ...handle email
    },
};
```

### AWS SES (`parseSesInbound`) [#aws-ses-parsesesinbound]

Pass the SES `mail` object (typically delivered via SNS/Lambda). SES does not include the decoded body in the notification — fetch it from S3 (or pass it directly) and supply it via `text`/`html`.

```typescript
import { parseSesInbound } from "@visulima/email/inbound";

const email = parseSesInbound({
    mail: snsRecord.mail,
    text: bodyFromS3, // decoded body you fetched yourself
});
```

## Extracting the reply: `extractReply` [#extracting-the-reply-extractreply]

When someone replies, the provider hands you the entire quoted history. `extractReply` strips it back down to just the new text the sender wrote.

```typescript
import { extractReply } from "@visulima/email/inbound";

const reply = extractReply(email.text ?? "");
```

It handles:

* `>`-prefixed quote blocks
* Localized "On … wrote:" attribution lines — including German ("Am … schrieb:"), French, Spanish, and Turkish variants
* Outlook's `-----Original Message-----` separator and `From:` / `Von:` header blocks
* The `-- ` signature delimiter

By default the trailing signature is stripped. Pass `stripSignature: false` to keep it:

```typescript
const reply = extractReply(email.text ?? "", { stripSignature: false });
```

| Option            | Type      | Default | Description                                              |
| ----------------- | --------- | ------- | -------------------------------------------------------- |
| `stripSignature?` | `boolean` | `true`  | Remove the trailing signature after the `-- ` delimiter. |

## Threading: `stitchThreads` [#threading-stitchthreads]

Group a flat list of `InboundEmail`s into conversations. Threading is driven by `In-Reply-To` / `References`, with a normalized-subject fallback for clients that don't set those headers.

```typescript
import { stitchThreads } from "@visulima/email/inbound";

const threads = stitchThreads(messages);

for (const thread of threads) {
    console.log(thread.id, thread.messages.length);
}
```

Each `EmailThread` is `{ id: string; messages: InboundEmail[] }`. The `id` is the thread's root Message-ID (or a synthetic key when a message has none); `messages` preserve input order.

The two normalizers backing the fallback are exported on their own:

```typescript
import { normalizeMessageId, normalizeSubject } from "@visulima/email/inbound";

normalizeMessageId("<abc123@mail.example.com>"); // "abc123@mail.example.com"
normalizeSubject("Re: Fwd: Quarterly report"); // "quarterly report"
```

## Address helpers [#address-helpers]

The same parsers the adapters use internally are exported for working with raw header values:

```typescript
import { parseAddress, parseAddressList, parseReferences } from "@visulima/email/inbound";

parseAddress("Jane Doe <jane@example.com>");
// { email: "jane@example.com", name: "Jane Doe" }

parseAddressList("a@example.com, Bob <b@example.com>");
// [{ email: "a@example.com" }, { email: "b@example.com", name: "Bob" }]

parseReferences("<msg-1@example.com> <msg-2@example.com>");
// ["msg-1@example.com", "msg-2@example.com"]
```

## End-to-end example [#end-to-end-example]

Receiving a Postmark inbound webhook, normalizing it, pulling out the new reply, and acting on it:

```typescript
import { extractReply, parsePostmarkInbound } from "@visulima/email/inbound";

app.post("/inbound/postmark", async (request, response) => {
    // 1. Normalize the provider payload.
    const email = parsePostmarkInbound(await request.json());

    // 2. Strip the quoted history and signature down to the new reply.
    const reply = extractReply(email.text ?? "");

    // 3. Use the normalized fields — provider-agnostic from here on.
    await tickets.appendComment({
        from: email.from?.email,
        subject: email.subject,
        body: reply,
        inReplyTo: email.inReplyTo,
        attachments: email.attachments,
    });

    response.status(200).end();
});
```


# Introduction (/docs/packages/email)



# Email [#email]

**Powerful email sending package with multiple provider support**

@visulima/email is a flexible, provider-agnostic email sending library that works across multiple JavaScript runtimes. It provides a clean, fluent API for building and sending emails with support for multiple email service providers, template engines, and advanced features like failover and load balancing.

## Why @visulima/email? [#why-visulimaemail]

* **Multiple Providers** - Support for 30+ providers including AWS SES, Resend, Brevo, Mailgun, Mailjet, SendGrid, Postmark, SMTP, and more
* **Provider Agnostic** - Switch between providers without changing your code
* **Cross-Runtime Support** - Works in Node.js, Deno, Bun, and Cloudflare Workers (provider-dependent)
* **Fluent API** - Clean, chainable API inspired by Laravel's Mail system
* **Template Engines** - Support for Handlebars, MJML, React Email, Vue Email, and HTML-to-text conversion
* **Failover & Load Balancing** - Built-in failover and round-robin providers for high availability
* **TypeScript Support** - Full type safety out of the box
* **Tree-shakeable** - Import only what you need for optimal bundle size
* **Optional Dependencies** - Template engines and providers are optional peer dependencies
* **Attachment Support** - Rich attachment handling with inline images and files
* **Reusable Templates** - Create reusable email templates using factory functions
* **Email Verification** - Comprehensive email validation including format validation, disposable email detection, MX record checking, role account detection, and SMTP verification

## Runtime Support [#runtime-support]

@visulima/email supports multiple JavaScript runtimes. Some providers work universally (Node.js, Deno, Bun, Cloudflare Workers), while others require Node.js:

**Universal Providers** (all runtimes): Resend, HTTP, Zeptomail, Brevo, Mailgun, Mailjet, MailerSend, Mandrill, MailPace, Mailtrap, Postal, Postmark, Azure, Infobip, Scaleway, AhaSend, Mailomat, Sweego, SendGrid, Plunk, Mock, and more\
**Node.js Only**: AWS SES, SMTP, MailCrab, Nodemailer

See [Runtime Support](/docs/packages/email/installation#runtime-support) for complete details.

## Quick Start [#quick-start]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

// Create a provider
const resend = resendProvider({
    apiKey: "re_xxx",
});

// Create a Mail instance
const mail = createMail(resend);

// Send an email using the message builder
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

const result = await mail.send(message);

if (result.success) {
    console.log("Email sent:", result.data?.messageId);
}
```

## Installation [#installation]

```bash
npm install @visulima/email
```

```bash
yarn add @visulima/email
```

```bash
pnpm add @visulima/email
```

## Requirements [#requirements]

* **Node.js**: 20.19 or higher, up to 25.x (for Node.js-specific providers)
* **TypeScript**: Optional but recommended for full type safety

**Note**: Universal providers work in Node.js, Deno, Bun, and Cloudflare Workers without Node.js version requirements. See [Runtime Support](/docs/packages/email/installation#runtime-support) for complete details.

## Supported Providers [#supported-providers]

### Universal Providers (All Runtimes) [#universal-providers-all-runtimes]

* **Resend** - Modern email API for developers
* **Brevo** - Email marketing and transactional email platform (formerly Sendinblue)
* **Mailgun** - Developer-friendly email API service
* **Mailjet** - Email marketing and transactional email platform
* **MailerSend** - Modern email API for developers
* **Mandrill** - Mailchimp Transactional Email
* **MailPace** - Simple transactional email service
* **Mailtrap** - Email testing and development tool
* **Postal** - Self-hosted email server
* **Postmark** - Transactional email service focused on deliverability
* **Azure** - Microsoft Azure Communication Services
* **Infobip** - Global communication platform
* **Scaleway** - European cloud provider email service
* **AhaSend** - Email delivery service
* **Mailomat** - Email service provider
* **Sweego** - Email delivery service
* **SendGrid** - Cloud-based email service for transactional and marketing emails
* **Zeptomail** - Zeptomail email service
* **Plunk** - Modern email platform built on AWS SES
* **HTTP** - Generic HTTP API provider
* **Mock** - In-memory provider for testing

### Node.js Only Providers [#nodejs-only-providers]

* **AWS SES** - Amazon Simple Email Service
* **SMTP** - Standard SMTP protocol
* **Nodemailer** - Popular Node.js email library wrapper
* **MailCrab** - Local development email testing

### Composite Providers [#composite-providers]

* **Failover** - Automatic failover between multiple providers
* **Round Robin** - Load balancing across multiple providers
* **OpenTelemetry** - OpenTelemetry instrumentation wrapper for observability

## Template Engines [#template-engines]

* **Handlebars** - Logic-less templating
* **MJML** - Email framework that makes responsive email easy
* **React Email** - Build beautiful emails with React
* **Vue Email** - Build beautiful emails with Vue
* **HTML-to-Text** - Convert HTML emails to plain text automatically

## What's Next? [#whats-next]

* [Installation Guide](/docs/packages/email/installation) - Learn how to install and set up @visulima/email
* [Getting Started](/docs/packages/email/getting-started/introduction) - Start sending emails with simple examples
* [Building Messages](/docs/packages/email/mail-messages/building-messages) - Learn how to build email messages
* [Providers](/docs/packages/email/providers/introduction) - Explore available email providers
* [Template Engines](/docs/packages/email/templates/introduction) - Use template engines for dynamic emails


# Installation (/docs/packages/email/installation)



# Installation [#installation]

@visulima/email is available as an npm package and can be installed using your preferred package manager.

## Package Managers [#package-managers]

### npm [#npm]

```bash
npm install @visulima/email
```

### yarn [#yarn]

```bash
yarn add @visulima/email
```

### pnpm [#pnpm]

```bash
pnpm add @visulima/email
```

## Requirements [#requirements]

* **Node.js**: 20.19 or higher, up to 25.x (for Node.js-specific providers)
* **TypeScript**: Optional but recommended for full type safety

## Runtime Support [#runtime-support]

@visulima/email supports multiple JavaScript runtimes, but provider availability varies by runtime:

### Universal Runtimes [#universal-runtimes]

The following providers work in **Node.js**, **Deno**, **Bun**, and **Cloudflare Workers**:

* **Resend** - Uses Fetch API
* **Brevo** - Uses Fetch API
* **Mailgun** - Uses Fetch API
* **Mailjet** - Uses Fetch API
* **MailerSend** - Uses Fetch API
* **Mandrill** - Uses Fetch API
* **MailPace** - Uses Fetch API
* **Mailtrap** - Uses Fetch API
* **Postal** - Uses Fetch API
* **Postmark** - Uses Fetch API
* **Azure** - Uses Fetch API (requires OAuth2 token or connection string)
* **Infobip** - Uses Fetch API
* **Scaleway** - Uses Fetch API
* **AhaSend** - Uses Fetch API
* **Mailomat** - Uses Fetch API
* **Sweego** - Uses Fetch API
* **SendGrid** - Uses Fetch API
* **Zeptomail** - Uses Fetch API
* **Plunk** - Uses Fetch API
* **HTTP** - Uses Fetch API
* **Mock** - In-memory provider
* **Failover** - Works if all wrapped providers support the runtime
* **Round Robin** - Works if all wrapped providers support the runtime
* **OpenTelemetry** - Works if wrapped provider supports the runtime

### Node.js Only [#nodejs-only]

The following providers require Node.js built-in modules (`node:crypto`, `node:net`, `node:tls`) and only work in **Node.js**:

* **AWS SES** - Requires `node:crypto` for AWS Signature V4 signing
* **SMTP** - Requires `node:net` and `node:tls` for SMTP connections
* **MailCrab** - Wraps SMTP provider (requires Node.js)
* **Nodemailer** - Requires the `nodemailer` package (Node.js only)

### Runtime Compatibility Table [#runtime-compatibility-table]

| Provider      | Node.js | Deno | Bun | Cloudflare Workers |
| ------------- | ------- | ---- | --- | ------------------ |
| Resend        | ✅       | ✅    | ✅   | ✅                  |
| Brevo         | ✅       | ✅    | ✅   | ✅                  |
| Mailgun       | ✅       | ✅    | ✅   | ✅                  |
| Mailjet       | ✅       | ✅    | ✅   | ✅                  |
| MailerSend    | ✅       | ✅    | ✅   | ✅                  |
| Mandrill      | ✅       | ✅    | ✅   | ✅                  |
| MailPace      | ✅       | ✅    | ✅   | ✅                  |
| Mailtrap      | ✅       | ✅    | ✅   | ✅                  |
| Postal        | ✅       | ✅    | ✅   | ✅                  |
| Postmark      | ✅       | ✅    | ✅   | ✅                  |
| Azure         | ✅       | ✅    | ✅   | ✅                  |
| Infobip       | ✅       | ✅    | ✅   | ✅                  |
| Scaleway      | ✅       | ✅    | ✅   | ✅                  |
| AhaSend       | ✅       | ✅    | ✅   | ✅                  |
| Mailomat      | ✅       | ✅    | ✅   | ✅                  |
| Sweego        | ✅       | ✅    | ✅   | ✅                  |
| SendGrid      | ✅       | ✅    | ✅   | ✅                  |
| Zeptomail     | ✅       | ✅    | ✅   | ✅                  |
| Plunk         | ✅       | ✅    | ✅   | ✅                  |
| HTTP          | ✅       | ✅    | ✅   | ✅                  |
| Mock          | ✅       | ✅    | ✅   | ✅                  |
| AWS SES       | ✅       | ❌    | ❌   | ❌                  |
| SMTP          | ✅       | ❌    | ❌   | ❌                  |
| MailCrab      | ✅       | ❌    | ❌   | ❌                  |
| Nodemailer    | ✅       | ❌    | ❌   | ❌                  |
| Failover      | ✅\*     | ✅\*  | ✅\* | ✅\*                |
| Round Robin   | ✅\*     | ✅\*  | ✅\* | ✅\*                |
| OpenTelemetry | ✅\*     | ✅\*  | ✅\* | ✅\*                |

\* Runtime support depends on the wrapped providers. Works if all wrapped providers support the runtime.

## Provider Dependencies [#provider-dependencies]

@visulima/email uses peer dependencies for providers. You only need to install the providers you plan to use. Most providers work out of the box with no additional dependencies - they use the native Fetch API.

### Universal Providers (No Additional Dependencies) [#universal-providers-no-additional-dependencies]

The following providers work without any additional dependencies:

* **Resend** - Just configure with your API key
* **Brevo** - Just configure with your API key
* **Mailgun** - Just configure with your API key and domain
* **Mailjet** - Just configure with your API key and secret
* **MailerSend** - Just configure with your API key
* **Mandrill** - Just configure with your API key
* **MailPace** - Just configure with your API key
* **Mailtrap** - Just configure with your API key
* **Postal** - Just configure with your API key and server URL
* **Postmark** - Just configure with your API key
* **Azure** - Configure with OAuth2 token or connection string
* **Infobip** - Just configure with your API key
* **Scaleway** - Just configure with your API key
* **AhaSend** - Just configure with your API key
* **Mailomat** - Just configure with your API key
* **Sweego** - Just configure with your API key
* **SendGrid** - Just configure with your API key
* **Zeptomail** - Just configure with your API key
* **Plunk** - Just configure with your API key
* **HTTP** - Configure with your custom HTTP endpoint
* **Mock** - No configuration needed (for testing)

### Node.js Only Providers [#nodejs-only-providers]

* **AWS SES** - No additional dependencies needed, uses native fetch API and `node:crypto` for AWS Signature V4 signing
* **SMTP** - No additional dependencies needed, uses native Node.js SMTP support (`node:net` and `node:tls`)
* **Nodemailer** - Nodemailer is included as a dependency, no additional installation needed
* **MailCrab** - No additional dependencies needed, wraps SMTP provider

### Composite Providers [#composite-providers]

* **Failover** - No additional dependencies, works with any providers
* **Round Robin** - No additional dependencies, works with any providers
* **OpenTelemetry** - Requires `@opentelemetry/api` package for observability features

## Template Engine Dependencies [#template-engine-dependencies]

Template engines are optional peer dependencies. Install only the ones you need:

### Handlebars [#handlebars]

```bash
npm install handlebars
# or
yarn add handlebars
# or
pnpm add handlebars
```

### MJML [#mjml]

```bash
npm install mjml
# or
yarn add mjml
# or
pnpm add mjml
```

### React Email [#react-email]

```bash
npm install @react-email/render
# or
yarn add @react-email/render
# or
pnpm add @react-email/render
```

### Vue Email [#vue-email]

```bash
npm install @vue-email/render
# or
yarn add @vue-email/render
# or
pnpm add @vue-email/render
```

### HTML-to-Text [#html-to-text]

```bash
npm install html-to-text
# or
yarn add html-to-text
# or
pnpm add html-to-text
```

### Disposable Email Detection [#disposable-email-detection]

The disposable email detection utility is included by default using `@visulima/disposable-email-domains`. The `isDisposableEmail` utility function is available to detect temporary/disposable email addresses. See [Validating Email Addresses](/docs/packages/email/getting-started/sending-mail#validating-email-addresses) for usage examples.

## TypeScript Support [#typescript-support]

@visulima/email is written in TypeScript and provides full type definitions. No additional type packages are required.

```typescript
import type { Mail, MailMessage, Provider } from "@visulima/email";
```

## Verify Installation [#verify-installation]

After installation, verify that @visulima/email is working correctly:

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "test" }));
console.log("@visulima/email is installed and ready!");
```

## Next Steps [#next-steps]

* [Getting Started](/docs/packages/email/getting-started/introduction) - Learn how to use @visulima/email
* [Configuration](/docs/packages/email/getting-started/configuration) - Configure providers for your needs
* [Sending Mail](/docs/packages/email/getting-started/sending-mail) - Send your first email


# Attachments (/docs/packages/email/mail-messages/attachments)



# Attachments [#attachments]

@visulima/email provides a rich attachment API inspired by Laravel's Mail system. You can attach files from the filesystem, raw data, URLs, and embed inline images for use in HTML emails.

## Attachment Types [#attachment-types]

### The Attachment Interface [#the-attachment-interface]

All attachments conform to the `Attachment` interface:

```typescript
interface Attachment {
    filename: string;
    content?: string | Buffer | Promise<Uint8Array>;
    contentType?: string;
    contentDisposition?: "attachment" | "inline";
    encoding?: string;
    cid?: string;
    path?: string;
    href?: string;
    httpHeaders?: Record<string, string>;
    raw?: string | Buffer;
    headers?: Record<string, string>;
}
```

## Attaching Files from Path [#attaching-files-from-path]

Use `attachFromPath()` to attach a file from the filesystem. The file is read and its MIME type is automatically detected.

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Invoice Attached").html("<h1>Your invoice is attached.</h1>");

await message.attachFromPath("/path/to/invoice.pdf");
```

### With Options [#with-options]

```typescript
await message.attachFromPath("/path/to/document.pdf", {
    filename: "my-invoice.pdf", // Custom filename
    contentType: "application/pdf", // Override MIME type
    contentDisposition: "attachment", // 'attachment' (default) or 'inline'
    encoding: "base64", // Content transfer encoding
    headers: { "X-Custom": "value" }, // Custom attachment headers
});
```

The `AttachmentOptions` interface:

| Option               | Type                       | Description                                    |
| -------------------- | -------------------------- | ---------------------------------------------- |
| `filename`           | `string`                   | Custom filename (defaults to file basename)    |
| `contentType`        | `string`                   | MIME type (auto-detected if not provided)      |
| `contentDisposition` | `"attachment" \| "inline"` | Disposition type (default: `"attachment"`)     |
| `encoding`           | `string`                   | Transfer encoding (e.g., `"base64"`, `"7bit"`) |
| `cid`                | `string`                   | Content-ID for inline attachments              |
| `headers`            | `Record<string, string>`   | Custom headers for this attachment             |

## Attaching Raw Data [#attaching-raw-data]

Use `attachData()` to attach raw string or Buffer content:

```typescript
const csvContent = "Name,Email\nJohn,john@example.com";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Report").html("<h1>Report attached</h1>");

message.attachData(csvContent, {
    filename: "report.csv",
    contentType: "text/csv",
});
```

### Buffer Attachments [#buffer-attachments]

```typescript
import { readFileSync } from "fs";

const pdfBuffer = readFileSync("/path/to/file.pdf");

message.attachData(pdfBuffer, {
    filename: "document.pdf",
    contentType: "application/pdf",
});
```

The `AttachmentDataOptions` interface extends `AttachmentOptions` with a required `filename`:

| Option     | Type     | Required | Description                 |
| ---------- | -------- | -------- | --------------------------- |
| `filename` | `string` | Yes      | Filename for the attachment |

## Inline Attachments (Embedded Images) [#inline-attachments-embedded-images]

### Embed from Path [#embed-from-path]

Use `embedFromPath()` to embed an image from the filesystem as an inline attachment. It returns a Content-ID that you can use in HTML with `cid:`:

```typescript
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Newsletter");

const logoCid = await message.embedFromPath("/path/to/logo.png");

message.html(`
    <h1>Welcome!</h1>
    <img src="cid:${logoCid}" alt="Logo" />
`);
```

### Embed from Data [#embed-from-data]

Use `embedData()` to embed raw data as an inline attachment:

```typescript
const imageBuffer = Buffer.from("...");
const imageCid = message.embedData(imageBuffer, "logo.png", {
    contentType: "image/png",
});

message.html(`
    <h1>Welcome!</h1>
    <img src="cid:${imageCid}" alt="Logo" />
`);
```

## Helper Functions [#helper-functions]

### Detect MIME Type [#detect-mime-type]

```typescript
import { detectMimeType } from "@visulima/email";

const mimeType = detectMimeType("document.pdf");
// Returns: "application/pdf"
```

### Generate Content-ID [#generate-content-id]

```typescript
import { generateContentId } from "@visulima/email";

const cid = generateContentId("logo.png");
// Returns something like: "logo-png-a1b2c3d@email"
```

### Read File as Buffer [#read-file-as-buffer]

```typescript
import { readFileAsBuffer } from "@visulima/email";

const buffer = await readFileAsBuffer("/path/to/file.pdf");
```

## Calendar Events [#calendar-events]

You can attach calendar events (ICS/iCal format) to emails:

### From String [#from-string]

```typescript
const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Meeting Invite").html("<h1>You're invited!</h1>");

message.icalEvent("BEGIN:VCALENDAR\nVERSION:2.0\n...", {
    method: "REQUEST",
});
```

### Using ical-generator [#using-ical-generator]

```typescript
message.icalEvent(
    (calendar) => {
        calendar.createEvent({
            start: new Date("2025-01-15T10:00:00Z"),
            end: new Date("2025-01-15T11:00:00Z"),
            summary: "Team Meeting",
            location: "Conference Room A",
        });
    },
    { method: "REQUEST" },
);
```

### From File [#from-file]

```typescript
message.icalEventFromFile("/path/to/event.ics", {
    method: "REQUEST",
});
```

### From URL [#from-url]

```typescript
message.icalEventFromUrl("https://example.com/event.ics", {
    method: "REQUEST",
});
```

The `CalendarEventOptions` interface:

| Option            | Type     | Description                                                |
| ----------------- | -------- | ---------------------------------------------------------- |
| `method`          | `string` | Calendar method (e.g., `"REQUEST"`, `"CANCEL"`, `"REPLY"`) |
| `alternativeText` | `string` | Alternative text for the calendar event                    |

## Provider Support [#provider-support]

Not all providers support attachments. Check the provider documentation for attachment support:

| Provider | Attachments | Inline Images |
| -------- | ----------- | ------------- |
| Resend   | Yes         | Yes           |
| Brevo    | Yes         | Yes           |
| Mailgun  | Yes         | Yes           |
| SendGrid | Yes         | Yes           |
| Postmark | Yes         | Yes           |
| SMTP     | Yes         | Yes           |
| AWS SES  | No          | No            |
| Mock     | Yes         | Yes           |


# Building Messages (/docs/packages/email/mail-messages/building-messages)



# Building Messages [#building-messages]

The `MailMessage` class provides a fluent, chainable API for building email messages. This guide covers all available methods.

## Basic Message [#basic-message]

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Setting Recipients [#setting-recipients]

### To Addresses [#to-addresses]

```typescript
// Single recipient (string)
new MailMessage().to("user@example.com");

// Single recipient (object)
new MailMessage().to({ email: "user@example.com", name: "John Doe" });

// Multiple recipients (array)
new MailMessage().to(["user1@example.com", "user2@example.com"]);

// Multiple recipients (array of objects)
new MailMessage().to([
    { email: "user1@example.com", name: "User 1" },
    { email: "user2@example.com", name: "User 2" },
]);
```

### CC and BCC [#cc-and-bcc]

```typescript
new MailMessage().to("user@example.com").cc("cc@example.com").bcc("bcc@example.com");
```

### Reply-To [#reply-to]

```typescript
new MailMessage().to("user@example.com").from("sender@example.com").replyTo("reply@example.com");
```

## Setting Content [#setting-content]

### Subject [#subject]

```typescript
new MailMessage().subject("Welcome to our service!");
```

### HTML Content [#html-content]

```typescript
new MailMessage().html("<h1>Hello</h1><p>This is HTML content.</p>");
```

### Plain Text Content [#plain-text-content]

```typescript
new MailMessage().text("Hello\n\nThis is plain text content.");
```

### Both HTML and Text [#both-html-and-text]

```typescript
new MailMessage().html("<h1>Hello</h1><p>This is HTML.</p>").text("Hello\n\nThis is plain text.");
```

## Custom Headers [#custom-headers]

```typescript
new MailMessage().header("X-Custom-Header", "value").header("X-Priority", "1");
```

Or set multiple headers at once:

```typescript
new MailMessage().setHeaders({
    "X-Custom-Header": "value",
    "X-Priority": "1",
    "X-Mailer": "MyApp",
});
```

## Attachments [#attachments]

### Attach File from Path [#attach-file-from-path]

```typescript
await message.attachFromPath("/path/to/file.pdf");
```

With options:

```typescript
await message.attachFromPath("/path/to/file.pdf", {
    filename: "custom-name.pdf",
    contentType: "application/pdf",
});
```

### Attach Data [#attach-data]

```typescript
message.attachData(Buffer.from("file content"), {
    filename: "document.txt",
    contentType: "text/plain",
});
```

## Inline Attachments [#inline-attachments]

### Embed Image from Path [#embed-image-from-path]

```typescript
const cid = await message.embedFromPath("/path/to/image.png");
// Use cid in HTML: <img src="cid:${cid}" />
```

### Embed Image Data [#embed-image-data]

```typescript
const cid = message.embedData(Buffer.from("image data"), "logo.png", {
    contentType: "image/png",
});
// Use cid in HTML: <img src="cid:${cid}" />
```

## Using Templates [#using-templates]

### Handlebars Template [#handlebars-template]

```typescript
import { renderHandlebars } from "@visulima/email/template/handlebars";

await message.view(renderHandlebars, "<h1>Hello {{name}}!</h1>", { name: "John" });
```

### MJML Template [#mjml-template]

```typescript
import mjml from "@visulima/email/template/mjml";

const mjmlTemplate = `
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello World</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>
`;

await message.view(mjml, mjmlTemplate);
```

### React Email [#react-email]

```typescript
import reactEmail from "@visulima/email/template/react-email";
import { WelcomeEmail } from "./emails/WelcomeEmail";

await message.view(reactEmail, <WelcomeEmail name="John" />);
```

### Vue Email [#vue-email]

```typescript
import vueEmail from "@visulima/email/template/vue-email";
import { MyTemplate } from "./emails/MyTemplate";

// Render HTML
await message.view(
    vueEmail,
    MyTemplate,
    {
        title: "some title",
    },
    {
        pretty: true,
    },
);

// Render plain text
await message.view(
    vueEmail,
    MyTemplate,
    {
        title: "some title",
    },
    {
        plainText: true,
    },
);
```

## Auto-Generate Text from HTML [#auto-generate-text-from-html]

When using templates, text can be automatically generated from HTML:

```typescript
import { renderHandlebars } from "@visulima/email/template/handlebars";

await message.view(
    renderHandlebars,
    "<h1>Hello {{name}}!</h1><p>Welcome to our service.</p>",
    { name: "John" },
    { autoText: true }, // Default: true
);
```

## Building Without Sending [#building-without-sending]

You can build the email options without sending:

```typescript
const emailOptions = await message.build();
// Use emailOptions with another provider or for testing
```

## Complete Example [#complete-example]

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { renderHandlebars } from "@visulima/email/template/handlebars";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const message = new MailMessage()
    .to({ email: "user@example.com", name: "John Doe" })
    .cc("cc@example.com")
    .from({ email: "sender@example.com", name: "My App" })
    .replyTo("support@example.com")
    .subject("Welcome!")
    .header("X-Priority", "1");

await message.view(renderHandlebars, "<h1>Hello {{name}}!</h1>", { name: "John" });
await message.attachFromPath("/path/to/welcome.pdf");

const result = await mail.send(message);
```

## Next Steps [#next-steps]

* [Attachments](/docs/packages/email/mail-messages/attachments) - Learn more about attachments
* [Template Engines](/docs/packages/email/templates/introduction) - Use template engines


# Reusable Email Templates (/docs/packages/email/mail-messages/mailable-classes)



# Reusable Email Templates [#reusable-email-templates]

You can create reusable email templates using factory functions that return configured `MailMessage` instances. This provides a clean way to organize and reuse email logic.

## Basic Template Function [#basic-template-function]

```typescript
import { MailMessage } from "@visulima/email";

const createWelcomeEmail = (user: { name: string; email: string }) => {
    return new MailMessage()
        .to({ email: user.email, name: user.name })
        .from({ email: "noreply@example.com" })
        .subject(`Welcome, ${user.name}!`)
        .html(`<h1>Welcome ${user.name}!</h1><p>Thanks for joining us.</p>`)
        .text(`Welcome ${user.name}! Thanks for joining us.`);
};
```

## Using Template Functions [#using-template-functions]

```typescript
import { createMail, MailMessage } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const message = createWelcomeEmail({ name: "John", email: "john@example.com" });
const result = await mail.send(message);
```

## Using Templates in Factory Functions [#using-templates-in-factory-functions]

```typescript
import { MailMessage } from "@visulima/email";
import { renderHandlebars } from "@visulima/email/template/handlebars";

const createWelcomeEmail = async (user: { name: string; email: string }) => {
    const html = await renderHandlebars(
        `
      <h1>Welcome {{name}}!</h1>
      <p>Thanks for joining us on {{date}}.</p>
      `,
        {
            name: user.name,
            date: new Date().toLocaleDateString(),
        },
    );

    return new MailMessage().to({ email: user.email, name: user.name }).from({ email: "noreply@example.com" }).subject(`Welcome, ${user.name}!`).html(html);
};
```

## Complex Template Example [#complex-template-example]

```typescript
import { MailMessage } from "@visulima/email";
import { renderHandlebars } from "@visulima/email/template/handlebars";
import { readFile } from "node:fs/promises";

const createOrderConfirmationEmail = async (order: {
    id: string;
    customer: { name: string; email: string };
    items: Array<{ name: string; price: number }>;
    total: number;
}) => {
    const html = await renderHandlebars(await readFile("./templates/order-confirmation.hbs", "utf-8"), { order });

    const message = new MailMessage()
        .to({ email: order.customer.email, name: order.customer.name })
        .from({ email: "orders@example.com", name: "Order Confirmation" })
        .subject(`Order Confirmation #${order.id}`)
        .html(html);

    await message.attachFromPath(`./invoices/${order.id}.pdf`, {
        filename: `invoice-${order.id}.pdf`,
    });

    return message;
};
```

## Using Classes (Optional) [#using-classes-optional]

If you prefer a class-based approach, you can extend `MailMessage`:

```typescript
import { MailMessage } from "@visulima/email";

class WelcomeEmail extends MailMessage {
    constructor(user: { name: string; email: string }) {
        super();
        this.to({ email: user.email, name: user.name })
            .from({ email: "noreply@example.com" })
            .subject(`Welcome, ${user.name}!`)
            .html(`<h1>Welcome ${user.name}!</h1><p>Thanks for joining us.</p>`)
            .text(`Welcome ${user.name}! Thanks for joining us.`);
    }
}

// Usage
const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
const message = new WelcomeEmail({ name: "John", email: "john@example.com" });
await mail.send(message);
```

## Next Steps [#next-steps]

* [Building Messages](/docs/packages/email/mail-messages/building-messages) - Learn the message builder API
* [Attachments](/docs/packages/email/mail-messages/attachments) - Add attachments to your emails


# Middleware (/docs/packages/email/middleware/introduction)



# Middleware [#middleware]

The `@visulima/email/middleware` entry point ships composable middlewares that wrap the provider's `sendEmail` call — adding retries, rate limiting, circuit breaking, deduplication, logging, and OAuth2 credential injection without coupling any of that logic to your provider adapter.

```typescript
import {
    retryMiddleware,
    rateLimitMiddleware,
    RATE_LIMIT_PRESETS,
    circuitBreakerMiddleware,
    dedupeMiddleware,
    loggingMiddleware,
    oauth2Middleware,
    composeMiddleware,
} from "@visulima/email/middleware";
```

## Attaching Middleware [#attaching-middleware]

Register middleware on a `Mail` instance with `mail.use()`. It is chainable, and middlewares run in registration order — the **first** registered is the **outermost** wrapper around the provider call.

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { rateLimitMiddleware, retryMiddleware } from "@visulima/email/middleware";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }))
    .use(rateLimitMiddleware({ rate: 10 }))
    .use(retryMiddleware({ retries: 3 }));
```

In the chain above, every send first passes through the rate limiter (outermost), then the retry middleware, then the provider. Because rate limiting wraps retries, retried attempts are also paced by the limiter.

## retryMiddleware [#retrymiddleware]

Retries failed sends with full-jitter exponential backoff (`random(0, baseDelay * 2 ** attempt)`), which avoids the thundering-herd problem a fixed retry schedule causes. After all attempts are exhausted, an optional `onDeadLetter` hook fires so you can persist or alert on the final failure.

```typescript
type RetryMiddlewareOptions = {
    retries?: number; // max attempts including the first (default: 3)
    baseDelay?: number; // base backoff in ms (default: 200)
    shouldRetry?: (result: Result<EmailResult>) => boolean; // default: retry every failure
    onDeadLetter?: (options: EmailOptions, result: Result<EmailResult>) => Promise<void> | void;
    sleep?: (ms: number) => Promise<void>; // injectable for tests
};
```

```typescript
import { retryMiddleware } from "@visulima/email/middleware";

mail.use(
    retryMiddleware({
        retries: 5,
        baseDelay: 250,
        shouldRetry: (result) => !result.success && result.error?.message.includes("rate"),
        onDeadLetter: async (options, result) => {
            await deadLetterQueue.push({ to: options.to, error: result.error });
        },
    }),
);
```

## rateLimitMiddleware [#ratelimitmiddleware]

Throttles sends with a token-bucket limiter. When capacity is exhausted it **awaits** capacity rather than failing, smoothing bursts to your sustained `rate`.

```typescript
type RateLimitMiddlewareOptions = {
    rate: number; // sustained sends per second
    burst?: number; // max burst capacity in tokens (default: rate)
    now?: () => number; // time source in ms (default: Date.now)
    sleep?: (ms: number) => Promise<void>; // injectable for tests
};
```

`RATE_LIMIT_PRESETS` provides per-second presets tuned to common providers' default plans — override them for your own quota:

| Provider   | Sends / second |
| ---------- | -------------- |
| `resend`   | 10             |
| `sendgrid` | 100            |
| `mailgun`  | 100            |
| `postmark` | 100            |
| `aws-ses`  | 14             |

```typescript
import { rateLimitMiddleware, RATE_LIMIT_PRESETS } from "@visulima/email/middleware";

mail.use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.resend }));

// Or allow short bursts above the sustained rate:
mail.use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.sendgrid, burst: 200 }));
```

## circuitBreakerMiddleware [#circuitbreakermiddleware]

Trips a circuit after repeated provider failures: while **open** it fails fast (returning a `CIRCUIT_OPEN` error) instead of hammering a struggling provider. After `resetTimeout`, it moves to **half-open** and lets a single probe request through; success closes the circuit, failure re-opens it.

```typescript
type CircuitBreakerMiddlewareOptions = {
    failureThreshold?: number; // consecutive failures before opening (default: 5)
    resetTimeout?: number; // ms to stay open before a half-open probe (default: 30000)
    onStateChange?: (state: "closed" | "half-open" | "open") => void;
    now?: () => number; // time source in ms (default: Date.now)
};
```

```typescript
import { circuitBreakerMiddleware } from "@visulima/email/middleware";

mail.use(
    circuitBreakerMiddleware({
        failureThreshold: 5,
        resetTimeout: 30_000,
        onStateChange: (state) => console.warn(`[email] circuit ${state}`),
    }),
);
```

## dedupeMiddleware [#dedupemiddleware]

Suppresses duplicate sends of the same message within a TTL window — useful behind at-least-once delivery sources (queues, webhooks) that may replay a message. Repeats return the original cached result instead of re-sending. The default key is a SHA-256 content hash of recipients, subject, and body.

```typescript
type DedupeMiddlewareOptions = {
    ttl?: number; // how long a key is remembered, in ms (default: 60000)
    keyFn?: (options: EmailOptions) => string; // default: content hash
    now?: () => number; // time source in ms (default: Date.now)
};
```

```typescript
import { dedupeMiddleware } from "@visulima/email/middleware";

// Default content-hash dedupe within 5 minutes.
mail.use(dedupeMiddleware({ ttl: 5 * 60_000 }));

// Or dedupe on your own idempotency key from the message headers.
mail.use(
    dedupeMiddleware({
        keyFn: (options) => String(options.headers?.["X-Idempotency-Key"] ?? options.subject),
    }),
);
```

## loggingMiddleware [#loggingmiddleware]

Logs each send attempt and its outcome. Recipient addresses are **redacted by default** (e.g. `j•••@example.com`) to keep PII out of your logs. Pass `redact: false` in trusted environments, or a custom logger to route logs anywhere.

```typescript
type LoggingMiddlewareOptions = {
    logger?: Pick<Console, "error" | "info">; // default: console
    redact?: boolean; // redact recipient addresses (default: true)
};
```

```typescript
import { loggingMiddleware } from "@visulima/email/middleware";

mail.use(loggingMiddleware());

// With a custom logger and no redaction (e.g. a local dev environment):
mail.use(loggingMiddleware({ logger: myLogger, redact: false }));
```

## oauth2Middleware [#oauth2middleware]

Injects an OAuth2 bearer credential into each outgoing message, caching it until just before expiry and refreshing on demand. Use it for Gmail / Microsoft 365, where access tokens are short-lived. The token can be injected as a request header (default) or handed to the `onToken` callback for SMTP XOAUTH2 clients.

```typescript
type OAuth2Token = {
    accessToken: string;
    expiresAt?: number; // absolute epoch ms; omit for non-expiring tokens
};

type OAuth2MiddlewareOptions = {
    fetchToken: () => Promise<OAuth2Token> | OAuth2Token; // your refresh flow
    headerName?: string; // header to inject into (default: "Authorization")
    scheme?: string; // auth scheme prefix (default: "Bearer")
    skewMs?: number; // refresh this many ms before expiry (default: 60000)
    onToken?: (token: OAuth2Token) => void; // e.g. feed SMTP XOAUTH2
    now?: () => number; // time source in ms (default: Date.now)
};
```

```typescript
import { oauth2Middleware } from "@visulima/email/middleware";

mail.use(
    oauth2Middleware({
        fetchToken: async () => {
            const { access_token, expires_in } = await refreshGoogleToken();

            return { accessToken: access_token, expiresAt: Date.now() + expires_in * 1000 };
        },
    }),
);
```

`fetchToken` is only called when the cached token is missing or within `skewMs` of expiry, so token refreshes are minimized across sends.

## composeMiddleware [#composemiddleware]

When you need to compose a middleware stack **without** a `Mail` instance — for testing, or to wrap a bare send function — use `composeMiddleware()`. It folds the middlewares (in registration order) around a terminal `SendFunction`.

```typescript
import { composeMiddleware, retryMiddleware, dedupeMiddleware } from "@visulima/email/middleware";
import type { SendFunction } from "@visulima/email/middleware";

const terminal: SendFunction = async (options) => provider.sendEmail(options);

const send = composeMiddleware([dedupeMiddleware(), retryMiddleware({ retries: 3 })], terminal);

const result = await send(emailOptions);
```

## A Realistic Stack [#a-realistic-stack]

A production stack typically rate-limits to the provider's quota, fails fast when the provider is down, and retries transient failures. Order matters: register from outermost to innermost.

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { circuitBreakerMiddleware, RATE_LIMIT_PRESETS, rateLimitMiddleware, retryMiddleware } from "@visulima/email/middleware";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }))
    .use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.resend }))
    .use(circuitBreakerMiddleware())
    .use(retryMiddleware({ retries: 3 }));
```

Every send is first paced by the rate limiter, then short-circuited by the circuit breaker if Resend is unhealthy, and finally retried with backoff on transient failures before reaching the provider.


# AhaSend (/docs/packages/email/providers/ahasend)



# AhaSend Provider [#ahasend-provider]

The AhaSend provider allows you to send emails through the [AhaSend API](https://api.ahasend.com/docs), an email delivery service.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { ahaSendProvider } from "@visulima/email/providers/ahasend";

const mail = createMail(
    ahaSendProvider({
        apiKey: process.env.AHASEND_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `AhaSendConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                   | Description                     |
| ---------- | --------- | -------- | ------------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                         | Your AhaSend API key            |
| `endpoint` | `string`  | No       | `https://api.ahasend.com` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                   | Enable debug logging            |
| `logger`   | `Console` | No       | -                         | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                       | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                   | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from AhaSend").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The AhaSend provider supports additional options through `AhaSendEmailOptions`:

| Option              | Type                      | Description         |
| ------------------- | ------------------------- | ------------------- |
| `templateId`        | `string`                  | AhaSend template ID |
| `templateVariables` | `Record<string, unknown>` | Template variables  |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# AWS SES (/docs/packages/email/providers/aws-ses)



# AWS SES Provider [#aws-ses-provider]

The AWS SES provider allows you to send emails through [Amazon Simple Email Service](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html) using native Node.js APIs with AWS Signature V4 signing. No AWS SDK dependency is required.

**Runtime Support:** Node.js only (requires `node:crypto` for AWS Signature V4 signing)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { awsSesProvider } from "@visulima/email/providers/aws-ses";

const mail = createMail(
    awsSesProvider({
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: "us-east-1",
    }),
);
```

## Configuration [#configuration]

The `AwsSesConfig` interface extends `BaseConfig` with the following options:

| Option            | Type      | Required | Default       | Description                                                  |
| ----------------- | --------- | -------- | ------------- | ------------------------------------------------------------ |
| `accessKeyId`     | `string`  | Yes      | -             | AWS access key ID                                            |
| `secretAccessKey` | `string`  | Yes      | -             | AWS secret access key                                        |
| `region`          | `string`  | Yes      | `us-east-1`   | AWS region                                                   |
| `sessionToken`    | `string`  | No       | -             | AWS session token (for temporary credentials)                |
| `apiVersion`      | `string`  | No       | `2010-12-01`  | AWS SES API version                                          |
| `endpoint`        | `string`  | No       | Auto-resolved | Custom endpoint (defaults to `email.{region}.amazonaws.com`) |
| `maxAttempts`     | `number`  | No       | `3`           | Maximum request attempts                                     |
| `debug`           | `boolean` | No       | `false`       | Enable debug logging                                         |
| `logger`          | `Console` | No       | -             | Custom logger instance                                       |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from AWS SES").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The AWS SES provider supports additional options through `AwsSesEmailOptions`:

```typescript
import type { AwsSesEmailOptions } from "@visulima/email/providers/aws-ses";

const options: AwsSesEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    configurationSetName: "my-config-set",
    messageTags: {
        Environment: "production",
        Application: "my-app",
    },
    sourceArn: "arn:aws:ses:us-east-1:123456789:identity/example.com",
    returnPath: "bounce@example.com",
    returnPathArn: "arn:aws:ses:us-east-1:123456789:identity/example.com",
};
```

| Option                 | Type                     | Description                          |
| ---------------------- | ------------------------ | ------------------------------------ |
| `configurationSetName` | `string`                 | Configuration set name               |
| `messageTags`          | `Record<string, string>` | Message tags as key-value pairs      |
| `sourceArn`            | `string`                 | Source ARN for sending authorization |
| `returnPath`           | `string`                 | Return path email address            |
| `returnPathArn`        | `string`                 | Return path ARN                      |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | No        |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | No        |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | No        |
| Tracking       | No        |

## Important Notes [#important-notes]

* This provider uses the `SendRawEmail` API action, which generates a full MIME message internally.
* Unsupported fields (attachments, priority, tags, replyTo) will cause an error if provided, rather than being silently ignored.
* The provider uses native `node:crypto` for AWS Signature V4 signing and does not require the AWS SDK.


# Azure (/docs/packages/email/providers/azure)



# Azure Provider [#azure-provider]

The Azure provider allows you to send emails through [Microsoft Azure Communication Services](https://learn.microsoft.com/en-us/azure/communication-services/concepts/email/email-overview).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers) - requires OAuth2 token or connection string

## Setup [#setup]

### Using Connection String [#using-connection-string]

```typescript
import { createMail } from "@visulima/email";
import { azureProvider } from "@visulima/email/providers/azure";

const mail = createMail(
    azureProvider({
        connectionString: process.env.AZURE_CONNECTION_STRING!,
        region: "eastus",
    }),
);
```

### Using OAuth2 Access Token [#using-oauth2-access-token]

```typescript
const mail = createMail(
    azureProvider({
        accessToken: process.env.AZURE_ACCESS_TOKEN!,
        region: "eastus",
    }),
);
```

## Configuration [#configuration]

The `AzureConfig` interface extends `BaseConfig` with the following options:

| Option             | Type      | Required | Default | Description                                                              |
| ------------------ | --------- | -------- | ------- | ------------------------------------------------------------------------ |
| `region`           | `string`  | Yes      | -       | Azure region (e.g., `eastus`, `westus`)                                  |
| `connectionString` | `string`  | No\*     | -       | Azure Communication Services connection string                           |
| `accessToken`      | `string`  | No\*     | -       | Azure AD access token for OAuth2 authentication                          |
| `endpoint`         | `string`  | No       | Auto    | Custom endpoint (defaults to `https://{region}.communication.azure.com`) |
| `debug`            | `boolean` | No       | `false` | Enable debug logging                                                     |
| `logger`           | `Console` | No       | -       | Custom logger instance                                                   |
| `retries`          | `number`  | No       | `3`     | Number of retry attempts                                                 |
| `timeout`          | `number`  | No       | `30000` | Request timeout in milliseconds                                          |

\*Either `connectionString` or `accessToken` must be provided.

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Azure").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Azure provider supports additional options through `AzureEmailOptions`:

| Option              | Type                      | Description            |
| ------------------- | ------------------------- | ---------------------- |
| `importance`        | `"normal" \| "high"`      | Email importance level |
| `templateId`        | `string`                  | Azure template ID      |
| `templateVariables` | `Record<string, unknown>` | Template variables     |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | Yes       |
| Tracking       | No        |


# Brevo (/docs/packages/email/providers/brevo)



# Brevo Provider [#brevo-provider]

The Brevo provider allows you to send emails through the [Brevo API](https://developers.brevo.com/reference/sendtransacemail), formerly known as Sendinblue.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { brevoProvider } from "@visulima/email/providers/brevo";

const mail = createMail(
    brevoProvider({
        apiKey: process.env.BREVO_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `BrevoConfig` interface extends `BaseConfig` with the following options:

| Option           | Type      | Required | Default                    | Description                                                                |
| ---------------- | --------- | -------- | -------------------------- | -------------------------------------------------------------------------- |
| `apiKey`         | `string`  | Yes      | -                          | Your Brevo API key                                                         |
| `endpoint`       | `string`  | No       | `https://api.brevo.com/v3` | Custom API endpoint                                                        |
| `hardValidation` | `boolean` | No       | `false`                    | If true, replyTo arrays are rejected. If false, the first address is used. |
| `debug`          | `boolean` | No       | `false`                    | Enable debug logging                                                       |
| `logger`         | `Console` | No       | -                          | Custom logger instance                                                     |
| `retries`        | `number`  | No       | `3`                        | Number of retry attempts on failure                                        |
| `timeout`        | `number`  | No       | `30000`                    | Request timeout in milliseconds                                            |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Brevo").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Brevo provider supports additional options through `BrevoEmailOptions`:

### Scheduled Sending [#scheduled-sending]

The `scheduledAt` option accepts an ISO 8601 string or a Unix timestamp in seconds (not milliseconds).

```typescript
import type { BrevoEmailOptions } from "@visulima/email/providers/brevo";

const options: BrevoEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Scheduled email",
    html: "<h1>Hello</h1>",
    scheduledAt: "2025-01-15T10:00:00Z",
};
```

### Template-Based Emails [#template-based-emails]

```typescript
const options: BrevoEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Template email",
    html: "",
    templateId: 123,
    templateParams: {
        name: "John",
        company: "Acme",
    },
};
```

### Batch Sending [#batch-sending]

```typescript
const options: BrevoEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Batch email",
    html: "<h1>Hello</h1>",
    batchId: "batch-123",
};
```

| Option           | Type                             | Description                                      |
| ---------------- | -------------------------------- | ------------------------------------------------ |
| `tags`           | `string[]`                       | Tags for categorization                          |
| `templateId`     | `number`                         | Brevo template ID                                |
| `templateParams` | `Record<string, unknown>`        | Template parameters                              |
| `scheduledAt`    | `string \| number`               | ISO 8601 date string or Unix timestamp (seconds) |
| `batchId`        | `string`                         | Batch ID for batch sending                       |
| `replyTo`        | `EmailAddress \| EmailAddress[]` | Reply-to address (only one allowed by Brevo)     |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |

## Additional Methods [#additional-methods]

### Retrieve Email [#retrieve-email]

```typescript
const provider = brevoProvider({ apiKey: "xxx" });
const result = await provider.getEmail("email-id");
```

## Important Notes [#important-notes]

* Brevo only supports a single reply-to address. If an array is provided and `hardValidation` is `false` (default), the first address is used. If `hardValidation` is `true`, an error is returned.


# Failover (/docs/packages/email/providers/failover)



# Failover Provider [#failover-provider]

The Failover provider automatically falls back to the next provider when the current one fails. This ensures high availability for email sending.

**Runtime Support:** Depends on the wrapped providers

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { failoverProvider } from "@visulima/email/providers/failover";
import { resendProvider } from "@visulima/email/providers/resend";
import { sendGridProvider } from "@visulima/email/providers/sendgrid";
import { smtpProvider } from "@visulima/email/providers/smtp";

const mail = createMail(
    failoverProvider({
        mailers: [
            resendProvider({ apiKey: process.env.RESEND_API_KEY! }),
            sendGridProvider({ apiKey: process.env.SENDGRID_API_KEY! }),
            smtpProvider({ host: "smtp.example.com", port: 587 }),
        ],
    }),
);
```

## Configuration [#configuration]

The `FailoverConfig` interface extends `BaseConfig` with the following options:

| Option       | Type        | Required | Default | Description                                                  |
| ------------ | ----------- | -------- | ------- | ------------------------------------------------------------ |
| `mailers`    | `unknown[]` | Yes      | -       | Array of provider instances or provider factory functions    |
| `retryAfter` | `number`    | No       | `60`    | Time in milliseconds to wait before trying the next provider |
| `debug`      | `boolean`   | No       | `false` | Enable debug logging                                         |
| `logger`     | `Console`   | No       | -       | Custom logger instance                                       |

## How It Works [#how-it-works]

1. The failover provider tries to send the email using the first provider in the `mailers` array.
2. If the first provider fails, it tries the second provider, and so on.
3. If all providers fail, the error from the last provider is returned.
4. The `retryAfter` option controls the delay between retries.

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello with Failover").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Mixing Runtimes [#mixing-runtimes]

When using failover in non-Node.js environments, ensure all providers support your runtime:

```typescript
// Safe for Cloudflare Workers
const mail = createMail(
    failoverProvider({
        mailers: [
            resendProvider({ apiKey: "re_xxx" }),
            sendGridProvider({ apiKey: "SG.xxx" }),
            // Do NOT include smtpProvider here - it requires Node.js
        ],
    }),
);
```

## Supported Features [#supported-features]

The failover provider supports whatever features the underlying providers support. Feature availability depends on which provider ultimately sends the email.


# HTTP (/docs/packages/email/providers/http)



# HTTP Provider [#http-provider]

The HTTP provider allows you to send emails through any generic HTTP API endpoint. This is useful for custom email services or internal APIs that accept email payloads.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { httpProvider } from "@visulima/email/providers/http";

const mail = createMail(
    httpProvider({
        endpoint: "https://my-email-api.example.com/send",
        apiKey: process.env.API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `HttpEmailConfig` interface has the following options:

| Option     | Type                       | Required | Default  | Description                          |
| ---------- | -------------------------- | -------- | -------- | ------------------------------------ |
| `endpoint` | `string`                   | Yes      | -        | The HTTP endpoint URL to send to     |
| `apiKey`   | `string`                   | No       | -        | API key for authentication           |
| `headers`  | `Record<string, string>`   | No       | -        | Custom HTTP headers for all requests |
| `method`   | `"GET" \| "POST" \| "PUT"` | No       | `"POST"` | HTTP method to use                   |

**Note:** The HTTP provider does not extend `BaseConfig` and does not support `debug`, `logger`, `retries`, or `timeout` options from the base configuration.

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello via HTTP").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The HTTP provider supports additional options through `HttpEmailOptions`:

```typescript
import type { HttpEmailOptions } from "@visulima/email/providers/http";

const options: HttpEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    endpointOverride: "https://other-api.example.com/send",
    methodOverride: "PUT",
    customParams: {
        priority: "high",
        trackingId: "abc-123",
    },
};
```

| Option             | Type                       | Description                                   |
| ------------------ | -------------------------- | --------------------------------------------- |
| `customParams`     | `Record<string, unknown>`  | Custom parameters in the request payload      |
| `endpointOverride` | `string`                   | Override the endpoint for this specific email |
| `methodOverride`   | `"GET" \| "POST" \| "PUT"` | Override the HTTP method for this email       |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | No        |
| Tracking       | No        |


# Infobip (/docs/packages/email/providers/infobip)



# Infobip Provider [#infobip-provider]

The Infobip provider allows you to send emails through the [Infobip Email API](https://www.infobip.com/docs/api/channels/email/send-email), a global communication platform.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { infobipProvider } from "@visulima/email/providers/infobip";

const mail = createMail(
    infobipProvider({
        apiKey: process.env.INFOBIP_API_KEY!,
        baseUrl: "https://api.infobip.com",
    }),
);
```

## Configuration [#configuration]

The `InfobipConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                   | Description                     |
| ---------- | --------- | -------- | ------------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                         | Your Infobip API key            |
| `baseUrl`  | `string`  | No       | `https://api.infobip.com` | Infobip base URL                |
| `endpoint` | `string`  | No       | `{baseUrl}/email/3/send`  | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                   | Enable debug logging            |
| `logger`   | `Console` | No       | -                         | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                       | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                   | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Infobip").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Infobip provider supports additional options through `InfobipEmailOptions`:

| Option               | Type                      | Description                              |
| -------------------- | ------------------------- | ---------------------------------------- |
| `templateId`         | `number`                  | Infobip template ID                      |
| `templateVariables`  | `Record<string, unknown>` | Template variables                       |
| `sendAt`             | `number`                  | Send at (Unix timestamp in milliseconds) |
| `intermediateReport` | `boolean`                 | Request delivery status updates          |
| `notifyUrl`          | `string`                  | URL for delivery notifications           |
| `trackingUrl`        | `string`                  | URL for click tracking                   |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Providers Introduction (/docs/packages/email/providers/introduction)



# Providers [#providers]

Providers are responsible for actually sending emails. @visulima/email supports multiple providers, allowing you to choose the best one for your needs or switch providers without changing your code.

## Available Providers [#available-providers]

* **[AWS SES](/docs/packages/email/providers/aws-ses)** - Amazon Simple Email Service ([API Docs](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html))
* **[Resend](/docs/packages/email/providers/resend)** - Modern email API for developers ([API Docs](https://resend.com/docs/api-reference/emails/send-email))
* **[Brevo](/docs/packages/email/providers/brevo)** - Email marketing and transactional email platform (formerly Sendinblue) ([API Docs](https://developers.brevo.com/reference/sendtransacemail))
* **[Mailgun](/docs/packages/email/providers/mailgun)** - Developer-friendly email API service ([API Docs](https://documentation.mailgun.com/en/latest/api_reference.html))
* **[Mailjet](/docs/packages/email/providers/mailjet)** - Email marketing and transactional email platform ([API Docs](https://dev.mailjet.com/email/guides/send-api-v31/))
* **[MailerSend](/docs/packages/email/providers/mailersend)** - Modern email API for developers ([API Docs](https://developers.mailersend.com/api/v1/email.html))
* **[Mandrill](/docs/packages/email/providers/mandrill)** - Mailchimp Transactional Email ([API Docs](https://mailchimp.com/developer/transactional/api/messages/send-new-message/))
* **[MailPace](/docs/packages/email/providers/mailpace)** - Simple transactional email service ([API Docs](https://docs.mailpace.com/api))
* **[Mailtrap](/docs/packages/email/providers/mailtrap)** - Email testing and development tool ([API Docs](https://mailtrap.io/api-docs))
* **[Postal](/docs/packages/email/providers/postal)** - Self-hosted email server ([API Docs](https://postal.atech.media/docs/developer/sending))
* **[Postmark](/docs/packages/email/providers/postmark)** - Transactional email service focused on deliverability ([API Docs](https://postmarkapp.com/developer/api/email-api))
* **[Azure](/docs/packages/email/providers/azure)** - Microsoft Azure Communication Services ([API Docs](https://learn.microsoft.com/en-us/azure/communication-services/concepts/email/email-overview))
* **[Infobip](/docs/packages/email/providers/infobip)** - Global communication platform ([API Docs](https://www.infobip.com/docs/api/channels/email/send-email))
* **[Scaleway](/docs/packages/email/providers/scaleway)** - European cloud provider email service ([API Docs](https://www.scaleway.com/en/docs/messaging-and-queuing/transactional-email/api-reference/))
* **[AhaSend](/docs/packages/email/providers/ahasend)** - Email delivery service ([API Docs](https://api.ahasend.com/docs))
* **[Mailomat](/docs/packages/email/providers/mailomat)** - Email service provider ([API Docs](https://api.mailomat.com/docs))
* **[Sweego](/docs/packages/email/providers/sweego)** - Email delivery service ([API Docs](https://api.sweego.com/docs))
* **[SendGrid](/docs/packages/email/providers/sendgrid)** - Cloud-based email service for transactional and marketing emails ([API Docs](https://docs.sendgrid.com/api-reference/mail-send/mail-send))
* **[SMTP](/docs/packages/email/providers/smtp)** - Standard SMTP protocol ([RFC 5321](https://tools.ietf.org/html/rfc5321))
* **[Zeptomail](/docs/packages/email/providers/zeptomail)** - Zeptomail email service ([API Docs](https://www.zeptomail.com/docs/api/))
* **[Plunk](/docs/packages/email/providers/plunk)** - Modern email platform built on AWS SES ([API Docs](https://docs.useplunk.com/api-reference))
* **[HTTP](/docs/packages/email/providers/http)** - Generic HTTP API provider
* **[Nodemailer](/docs/packages/email/providers/nodemailer)** - Popular Node.js email library wrapper ([API Docs](https://nodemailer.com/about/))
* **[Mock](/docs/packages/email/providers/mock)** - In-memory provider for testing
* **[Failover](/docs/packages/email/providers/failover)** - Automatic failover between multiple providers
* **[Round Robin](/docs/packages/email/providers/roundrobin)** - Load balancing across multiple providers
* **[MailCrab](/docs/packages/email/providers/mailcrab)** - Local development email testing ([Docs](https://mailcrab.app/))
* **[OpenTelemetry](/docs/packages/email/providers/opentelemetry)** - OpenTelemetry instrumentation wrapper for observability ([API Docs](https://opentelemetry.io/docs/))

## Runtime Support [#runtime-support]

Different providers support different JavaScript runtimes. Choose providers based on your deployment target:

### Universal Providers (All Runtimes) [#universal-providers-all-runtimes]

These providers work in **Node.js**, **Deno**, **Bun**, and **Cloudflare Workers**:

* ✅ **Resend** - Uses Fetch API, works everywhere
* ✅ **HTTP** - Uses Fetch API, works everywhere
* ✅ **Zeptomail** - Uses Fetch API, works everywhere
* ✅ **Brevo** - Uses Fetch API, works everywhere
* ✅ **Mailgun** - Uses Fetch API, works everywhere
* ✅ **Mailjet** - Uses Fetch API, works everywhere
* ✅ **MailerSend** - Uses Fetch API, works everywhere
* ✅ **Mandrill** - Uses Fetch API, works everywhere
* ✅ **MailPace** - Uses Fetch API, works everywhere
* ✅ **Mailtrap** - Uses Fetch API, works everywhere
* ✅ **Postal** - Uses Fetch API, works everywhere
* ✅ **Postmark** - Uses Fetch API, works everywhere
* ✅ **Azure** - Uses Fetch API, works everywhere (requires OAuth2 token or connection string)
* ✅ **Infobip** - Uses Fetch API, works everywhere
* ✅ **Scaleway** - Uses Fetch API, works everywhere
* ✅ **AhaSend** - Uses Fetch API, works everywhere
* ✅ **Mailomat** - Uses Fetch API, works everywhere
* ✅ **Sweego** - Uses Fetch API, works everywhere
* ✅ **SendGrid** - Uses Fetch API, works everywhere
* ✅ **Plunk** - Uses Fetch API, works everywhere
* ✅ **Mock** - In-memory provider, works everywhere
* ✅ **Failover** - Works if all wrapped providers support your runtime
* ✅ **Round Robin** - Works if all wrapped providers support your runtime
* ✅ **OpenTelemetry** - Works if wrapped provider supports your runtime

### Node.js Only Providers [#nodejs-only-providers]

These providers require Node.js built-in modules and only work in **Node.js**:

* ⚠️ **AWS SES** - Requires `node:crypto` for AWS Signature V4 signing
* ⚠️ **SMTP** - Requires `node:net` and `node:tls` for SMTP connections
* ⚠️ **MailCrab** - Wraps SMTP provider (requires Node.js)
* ⚠️ **Nodemailer** - Requires the `nodemailer` package (Node.js only)

### Runtime Compatibility [#runtime-compatibility]

| Provider      | Node.js | Deno | Bun | Cloudflare Workers |
| ------------- | ------- | ---- | --- | ------------------ |
| Resend        | ✅       | ✅    | ✅   | ✅                  |
| HTTP          | ✅       | ✅    | ✅   | ✅                  |
| Zeptomail     | ✅       | ✅    | ✅   | ✅                  |
| Brevo         | ✅       | ✅    | ✅   | ✅                  |
| Mailgun       | ✅       | ✅    | ✅   | ✅                  |
| Mailjet       | ✅       | ✅    | ✅   | ✅                  |
| MailerSend    | ✅       | ✅    | ✅   | ✅                  |
| Mandrill      | ✅       | ✅    | ✅   | ✅                  |
| MailPace      | ✅       | ✅    | ✅   | ✅                  |
| Mailtrap      | ✅       | ✅    | ✅   | ✅                  |
| Postal        | ✅       | ✅    | ✅   | ✅                  |
| Postmark      | ✅       | ✅    | ✅   | ✅                  |
| Azure         | ✅       | ✅    | ✅   | ✅                  |
| Infobip       | ✅       | ✅    | ✅   | ✅                  |
| Scaleway      | ✅       | ✅    | ✅   | ✅                  |
| AhaSend       | ✅       | ✅    | ✅   | ✅                  |
| Mailomat      | ✅       | ✅    | ✅   | ✅                  |
| Sweego        | ✅       | ✅    | ✅   | ✅                  |
| SendGrid      | ✅       | ✅    | ✅   | ✅                  |
| Plunk         | ✅       | ✅    | ✅   | ✅                  |
| Mock          | ✅       | ✅    | ✅   | ✅                  |
| AWS SES       | ✅       | ❌    | ❌   | ❌                  |
| SMTP          | ✅       | ❌    | ❌   | ❌                  |
| MailCrab      | ✅       | ❌    | ❌   | ❌                  |
| Nodemailer    | ✅       | ❌    | ❌   | ❌                  |
| Failover      | ✅\*     | ✅\*  | ✅\* | ✅\*                |
| Round Robin   | ✅\*     | ✅\*  | ✅\* | ✅\*                |
| OpenTelemetry | ✅\*     | ✅\*  | ✅\* | ✅\*                |

\* Runtime support depends on the wrapped providers. Works if all wrapped providers support the runtime.

### Choosing a Provider [#choosing-a-provider]

* **For Cloudflare Workers, Deno, or Bun**: Use Resend, HTTP, Zeptomail, Brevo, Mailgun, Mailjet, MailerSend, Mandrill, MailPace, Mailtrap, Postal, Postmark, SendGrid, Plunk, Azure, Infobip, Scaleway, AhaSend, Mailomat, Sweego, or Mock
* **For Node.js**: You can use any provider
* **For testing**: Use Mock or Mailtrap provider to test email logic without sending real emails
* **For observability**: Use OpenTelemetry provider to wrap any provider and add distributed tracing and metrics
* **For cross-runtime compatibility**: Use Resend, HTTP, Zeptomail, Brevo, Mailgun, Mailjet, MailerSend, Mandrill, MailPace, Mailtrap, Postal, Postmark, SendGrid, Plunk, Azure, Infobip, Scaleway, AhaSend, Mailomat, Sweego, or Mock, or wrap Node.js-only providers in Failover/Round Robin with universal providers as fallbacks

## Provider Interface [#provider-interface]

All providers implement a common interface:

```typescript
interface Provider {
    initialize(opts?: Record<string, unknown>): Promise<void>;
    isAvailable(): Promise<boolean>;
    sendEmail(options: EmailOptions): Promise<Result<EmailResult>>;
    validateCredentials?(): Promise<boolean>;
    getEmail?(id: string): Promise<Result<unknown>>;
    shutdown?(): Promise<void>;
}
```

## Using Providers [#using-providers]

### Import from Separate Exports [#import-from-separate-exports]

Each provider is exported from its own path for better tree-shaking:

```typescript
import { resendProvider } from "@visulima/email/providers/resend";
import { smtpProvider } from "@visulima/email/providers/smtp";
```

### Create Provider Instance [#create-provider-instance]

```typescript
const resend = resendProvider({
    apiKey: "re_xxx",
});
```

### Use with Mail [#use-with-mail]

```typescript
import { createMail } from "@visulima/email";

const mail = createMail(resend);
```

## Switching Providers [#switching-providers]

Since all providers implement the same interface, you can switch providers without changing your email code:

```typescript
import { createMail, MailMessage } from "@visulima/email";

// Use Resend in production
const productionMail = createMail(resendProvider({ apiKey: process.env.RESEND_API_KEY! }));

// Use SMTP in development
const developmentMail = createMail(
    smtpProvider({
        host: "localhost",
        port: 1025,
        secure: false,
    }),
);

// Same code works with both
const sendEmail = async (mail: Mail) => {
    const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello</h1>");
    await mail.send(message);
};
```

## Provider-Specific Options [#provider-specific-options]

Some providers support additional options in `EmailOptions`:

### Resend [#resend]

```typescript
import type { ResendEmailOptions } from "@visulima/email/providers/resend";

const options: ResendEmailOptions = {
    from: { email: "sender@example.com" },
    to: "user@example.com",
    subject: "Hello",
    html: "<h1>Hello</h1>",
    tags: [{ name: "category", value: "welcome" }], // Resend-specific
};
```

## Next Steps [#next-steps]

* Explore individual provider documentation
* [Configuration](/docs/packages/email/getting-started/configuration) - Learn how to configure providers


# MailCrab (/docs/packages/email/providers/mailcrab)



# MailCrab Provider [#mailcrab-provider]

The MailCrab provider wraps the SMTP provider to send emails to a [MailCrab](https://mailcrab.app/) instance, a local development email testing tool. MailCrab captures all emails sent to it and provides a web interface for viewing them.

**Runtime Support:** Node.js only (wraps the SMTP provider which requires `node:net` and `node:tls`)

## Setup [#setup]

First, start MailCrab locally (e.g., via Docker):

```bash
docker run -p 1080:1080 -p 1025:1025 marlonb/mailcrab
```

Then configure the provider:

```typescript
import { createMail } from "@visulima/email";
import { mailCrabProvider } from "@visulima/email/providers/mailcrab";

const mail = createMail(
    mailCrabProvider({
        host: "localhost",
        port: 1025,
    }),
);
```

## Configuration [#configuration]

The `MailCrabConfig` interface extends `BaseConfig` with the following options:

| Option   | Type      | Required | Default     | Description            |
| -------- | --------- | -------- | ----------- | ---------------------- |
| `host`   | `string`  | No       | `localhost` | MailCrab SMTP host     |
| `port`   | `number`  | No       | `1025`      | MailCrab SMTP port     |
| `secure` | `boolean` | No       | `false`     | Use secure connection  |
| `debug`  | `boolean` | No       | `false`     | Enable debug logging   |
| `logger` | `Console` | No       | -           | Custom logger instance |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Test email via MailCrab").html("<h1>Hello World</h1>");

const result = await mail.send(message);
// View the email at http://localhost:1080
```

## Supported Features [#supported-features]

Since MailCrab wraps the SMTP provider, it supports the same features as SMTP:

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | No        |
| Tracking       | No        |


# MailerSend (/docs/packages/email/providers/mailersend)



# MailerSend Provider [#mailersend-provider]

The MailerSend provider allows you to send emails through the [MailerSend API](https://developers.mailersend.com/api/v1/email.html).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailerSendProvider } from "@visulima/email/providers/mailersend";

const mail = createMail(
    mailerSendProvider({
        apiToken: process.env.MAILERSEND_API_TOKEN!,
    }),
);
```

## Configuration [#configuration]

The `MailerSendConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                      | Description                     |
| ---------- | --------- | -------- | ---------------------------- | ------------------------------- |
| `apiToken` | `string`  | Yes      | -                            | Your MailerSend API token       |
| `endpoint` | `string`  | No       | `https://api.mailersend.com` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                      | Enable debug logging            |
| `logger`   | `Console` | No       | -                            | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                          | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                      | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from MailerSend").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The MailerSend provider supports additional options through `MailerSendEmailOptions`:

```typescript
import type { MailerSendEmailOptions } from "@visulima/email/providers/mailersend";

const options: MailerSendEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    templateId: "tmpl_xxx",
    templateVariables: { name: "John" },
    personalization: [
        {
            email: "user@example.com",
            data: { name: "John" },
        },
    ],
    scheduledAt: 1705312800,
};
```

| Option              | Type                                                 | Description                           |
| ------------------- | ---------------------------------------------------- | ------------------------------------- |
| `templateId`        | `string`                                             | MailerSend template ID                |
| `templateVariables` | `Record<string, unknown>`                            | Template variables                    |
| `personalization`   | `{ email: string; data: Record<string, unknown> }[]` | Per-recipient variables               |
| `scheduledAt`       | `number`                                             | Scheduled delivery (Unix timestamp)   |
| `domainId`          | `string`                                             | Domain ID for domain-specific sending |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Mailgun (/docs/packages/email/providers/mailgun)



# Mailgun Provider [#mailgun-provider]

The Mailgun provider allows you to send emails through the [Mailgun API](https://documentation.mailgun.com/en/latest/api_reference.html), a developer-friendly email API service.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailgunProvider } from "@visulima/email/providers/mailgun";

const mail = createMail(
    mailgunProvider({
        apiKey: process.env.MAILGUN_API_KEY!,
        domain: "mg.example.com",
    }),
);
```

## Configuration [#configuration]

The `MailgunConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                   | Description                                                     |
| ---------- | --------- | -------- | ------------------------- | --------------------------------------------------------------- |
| `apiKey`   | `string`  | Yes      | -                         | Your Mailgun API key                                            |
| `domain`   | `string`  | Yes      | -                         | Your Mailgun sending domain                                     |
| `endpoint` | `string`  | No       | `https://api.mailgun.net` | API endpoint (use `https://api.eu.mailgun.net` for EU accounts) |
| `debug`    | `boolean` | No       | `false`                   | Enable debug logging                                            |
| `logger`   | `Console` | No       | -                         | Custom logger instance                                          |
| `retries`  | `number`  | No       | `3`                       | Number of retry attempts on failure                             |
| `timeout`  | `number`  | No       | `30000`                   | Request timeout in milliseconds                                 |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@mg.example.com").subject("Hello from Mailgun").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Mailgun provider supports additional options through `MailgunEmailOptions`:

```typescript
import type { MailgunEmailOptions } from "@visulima/email/providers/mailgun";

const options: MailgunEmailOptions = {
    from: { email: "sender@mg.example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    tags: ["welcome", "onboarding"],
    clickTracking: true,
    openTracking: true,
    testMode: false,
    template: "welcome-template",
    templateVariables: { name: "John" },
};
```

| Option                | Type                      | Description                                     |
| --------------------- | ------------------------- | ----------------------------------------------- |
| `tags`                | `string[]`                | Tags for categorization                         |
| `template`            | `string`                  | Mailgun template name                           |
| `templateVariables`   | `Record<string, unknown>` | Template variables                              |
| `campaignId`          | `string`                  | Campaign ID for tracking                        |
| `deliveryTime`        | `string \| number`        | Delivery time (RFC 2822 date or Unix timestamp) |
| `clickTracking`       | `boolean`                 | Enable/disable click tracking                   |
| `openTracking`        | `boolean`                 | Enable/disable open tracking                    |
| `unsubscribeTracking` | `boolean`                 | Enable/disable unsubscribe tracking             |
| `testMode`            | `boolean`                 | Test mode - emails will not actually be sent    |
| `requireTls`          | `boolean`                 | Require TLS for delivery                        |
| `skipVerification`    | `boolean`                 | Skip TLS certificate verification               |

## EU Region [#eu-region]

For EU-based Mailgun accounts, use the EU endpoint:

```typescript
const mail = createMail(
    mailgunProvider({
        apiKey: process.env.MAILGUN_API_KEY!,
        domain: "mg.example.com",
        endpoint: "https://api.eu.mailgun.net",
    }),
);
```

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |

## Additional Methods [#additional-methods]

### Retrieve Email [#retrieve-email]

Retrieve email event details by message ID:

```typescript
const provider = mailgunProvider({ apiKey: "xxx", domain: "mg.example.com" });
const result = await provider.getEmail("message-id");
```


# Mailjet (/docs/packages/email/providers/mailjet)



# Mailjet Provider [#mailjet-provider]

The Mailjet provider allows you to send emails through the [Mailjet Send API v3.1](https://dev.mailjet.com/email/guides/send-api-v31/).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailjetProvider } from "@visulima/email/providers/mailjet";

const mail = createMail(
    mailjetProvider({
        apiKey: process.env.MAILJET_API_KEY!,
        apiSecret: process.env.MAILJET_API_SECRET!,
    }),
);
```

## Configuration [#configuration]

The `MailjetConfig` interface extends `BaseConfig` with the following options:

| Option      | Type      | Required | Default                   | Description                     |
| ----------- | --------- | -------- | ------------------------- | ------------------------------- |
| `apiKey`    | `string`  | Yes      | -                         | Your Mailjet API key            |
| `apiSecret` | `string`  | Yes      | -                         | Your Mailjet API secret         |
| `endpoint`  | `string`  | No       | `https://api.mailjet.com` | Custom API endpoint             |
| `debug`     | `boolean` | No       | `false`                   | Enable debug logging            |
| `logger`    | `Console` | No       | -                         | Custom logger instance          |
| `retries`   | `number`  | No       | `3`                       | Number of retry attempts        |
| `timeout`   | `number`  | No       | `30000`                   | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Mailjet").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Mailjet provider supports additional options through `MailjetEmailOptions`:

```typescript
import type { MailjetEmailOptions } from "@visulima/email/providers/mailjet";

const options: MailjetEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    templateId: 12345,
    templateLanguage: true,
    templateVariables: { name: "John" },
    customId: "campaign-123",
    priority: 2,
};
```

| Option                | Type                      | Description                          |
| --------------------- | ------------------------- | ------------------------------------ |
| `templateId`          | `number`                  | Mailjet template ID                  |
| `templateLanguage`    | `boolean`                 | Enable template language processing  |
| `templateVariables`   | `Record<string, unknown>` | Template variables                   |
| `customId`            | `string`                  | Custom ID for tracking               |
| `campaign`            | `string`                  | Custom campaign name                 |
| `deduplicateCampaign` | `boolean`                 | Prevent duplicate emails in campaign |
| `priority`            | `number`                  | Priority (1-5, where 1 is highest)   |
| `deliveryTime`        | `number`                  | Delivery time (Unix timestamp)       |
| `eventPayload`        | `string`                  | Event payload for webhooks           |
| `urlTags`             | `Record<string, string>`  | URL tags for tracking                |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Mailomat (/docs/packages/email/providers/mailomat)



# Mailomat Provider [#mailomat-provider]

The Mailomat provider allows you to send emails through the [Mailomat API](https://api.mailomat.com/docs).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailomatProvider } from "@visulima/email/providers/mailomat";

const mail = createMail(
    mailomatProvider({
        apiKey: process.env.MAILOMAT_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `MailomatConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                    | Description                     |
| ---------- | --------- | -------- | -------------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                          | Your Mailomat API key           |
| `endpoint` | `string`  | No       | `https://api.mailomat.com` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                    | Enable debug logging            |
| `logger`   | `Console` | No       | -                          | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                        | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                    | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Mailomat").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Mailomat provider supports additional options through `MailomatEmailOptions`:

| Option              | Type                      | Description             |
| ------------------- | ------------------------- | ----------------------- |
| `tags`              | `string[]`                | Tags for categorization |
| `templateId`        | `string`                  | Mailomat template ID    |
| `templateVariables` | `Record<string, unknown>` | Template variables      |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# MailPace (/docs/packages/email/providers/mailpace)



# MailPace Provider [#mailpace-provider]

The MailPace provider allows you to send emails through the [MailPace API](https://docs.mailpace.com/api), a simple transactional email service.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailPaceProvider } from "@visulima/email/providers/mailpace";

const mail = createMail(
    mailPaceProvider({
        apiToken: process.env.MAILPACE_API_TOKEN!,
    }),
);
```

## Configuration [#configuration]

The `MailPaceConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                           | Description                     |
| ---------- | --------- | -------- | --------------------------------- | ------------------------------- |
| `apiToken` | `string`  | Yes      | -                                 | Your MailPace API token         |
| `endpoint` | `string`  | No       | `https://app.mailpace.com/api/v1` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                           | Enable debug logging            |
| `logger`   | `Console` | No       | -                                 | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                               | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                           | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from MailPace").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The MailPace provider supports additional options through `MailPaceEmailOptions`:

```typescript
import type { MailPaceEmailOptions } from "@visulima/email/providers/mailpace";

const options: MailPaceEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    tags: ["welcome"],
    listUnsubscribe: "https://example.com/unsubscribe",
};
```

| Option              | Type                      | Description                   |
| ------------------- | ------------------------- | ----------------------------- |
| `tags`              | `string[]`                | Tags for categorization       |
| `templateId`        | `number`                  | MailPace template ID          |
| `templateVariables` | `Record<string, unknown>` | Template variables            |
| `listUnsubscribe`   | `string`                  | List-Unsubscribe header value |

### Attachments [#attachments]

MailPace uses a specific attachment format:

```typescript
const options: MailPaceEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "With attachment",
    html: "<h1>Hello</h1>",
    attachments: [
        {
            name: "document.pdf",
            content: "base64-encoded-content",
            content_type: "application/pdf",
        },
    ],
};
```

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# Mailtrap (/docs/packages/email/providers/mailtrap)



# Mailtrap Provider [#mailtrap-provider]

The Mailtrap provider allows you to send emails through the [Mailtrap API](https://mailtrap.io/api-docs), an email testing and development tool that also supports transactional email sending.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mailtrapProvider } from "@visulima/email/providers/mailtrap";

const mail = createMail(
    mailtrapProvider({
        apiToken: process.env.MAILTRAP_API_TOKEN!,
    }),
);
```

## Configuration [#configuration]

The `MailtrapConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                        | Description                     |
| ---------- | --------- | -------- | ------------------------------ | ------------------------------- |
| `apiToken` | `string`  | Yes      | -                              | Your Mailtrap API token         |
| `endpoint` | `string`  | No       | `https://send.api.mailtrap.io` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                        | Enable debug logging            |
| `logger`   | `Console` | No       | -                              | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                            | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                        | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Mailtrap").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Mailtrap provider supports additional options through `MailtrapEmailOptions`:

```typescript
import type { MailtrapEmailOptions } from "@visulima/email/providers/mailtrap";

const options: MailtrapEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    category: "welcome",
    templateUuid: "tmpl-uuid-xxx",
    templateVariables: { name: "John" },
    customVariables: { userId: "123" },
};
```

| Option              | Type                      | Description                  |
| ------------------- | ------------------------- | ---------------------------- |
| `category`          | `string`                  | Category for categorization  |
| `templateUuid`      | `string`                  | Mailtrap template UUID       |
| `templateVariables` | `Record<string, unknown>` | Template variables           |
| `customVariables`   | `Record<string, unknown>` | Custom variables (key-value) |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Mandrill (/docs/packages/email/providers/mandrill)



# Mandrill Provider [#mandrill-provider]

The Mandrill provider allows you to send emails through [Mailchimp Transactional Email (Mandrill)](https://mailchimp.com/developer/transactional/api/messages/send-new-message/).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mandrillProvider } from "@visulima/email/providers/mandrill";

const mail = createMail(
    mandrillProvider({
        apiKey: process.env.MANDRILL_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `MandrillConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                           | Description                     |
| ---------- | --------- | -------- | --------------------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                                 | Your Mandrill API key           |
| `endpoint` | `string`  | No       | `https://mandrillapp.com/api/1.0` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                           | Enable debug logging            |
| `logger`   | `Console` | No       | -                                 | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                               | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                           | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Mandrill").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Mandrill provider supports additional options through `MandrillEmailOptions`:

```typescript
import type { MandrillEmailOptions } from "@visulima/email/providers/mandrill";

const options: MandrillEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello {{name}}</h1>",
    tags: ["welcome", "onboarding"],
    globalMergeVars: [{ name: "company", content: "Acme Corp" }],
    mergeVars: [
        {
            rcpt: "user@example.com",
            vars: [{ name: "name", content: "John" }],
        },
    ],
    metadata: { campaign: "onboarding-2025" },
    subaccount: "client-123",
};
```

| Option                    | Type                                                             | Description                     |
| ------------------------- | ---------------------------------------------------------------- | ------------------------------- |
| `tags`                    | `string[]`                                                       | Tags for categorization         |
| `templateName`            | `string`                                                         | Mandrill template name          |
| `templateContent`         | `{ name: string; content: string }[]`                            | Template content blocks         |
| `templateVariables`       | `{ name: string; content: unknown }[]`                           | Template variables (merge vars) |
| `globalMergeVars`         | `{ name: string; content: unknown }[]`                           | Global merge variables          |
| `mergeVars`               | `{ rcpt: string; vars: { name: string; content: unknown }[] }[]` | Per-recipient merge variables   |
| `metadata`                | `Record<string, string>`                                         | Metadata key-value pairs        |
| `sendAt`                  | `string`                                                         | Send at timestamp (ISO 8601)    |
| `subaccount`              | `string`                                                         | Subaccount ID                   |
| `googleAnalyticsCampaign` | `string`                                                         | Google Analytics campaign name  |
| `googleAnalyticsDomains`  | `string[]`                                                       | Google Analytics domains        |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Mock (/docs/packages/email/providers/mock)



# Mock Provider [#mock-provider]

The Mock provider is an in-memory email provider designed for testing. It stores sent emails in memory and allows you to inspect them, simulate failures, and add artificial delays.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { mockProvider } from "@visulima/email/providers/mock";

const mock = mockProvider();
const mail = createMail(mock);
```

## Configuration [#configuration]

The `MockConfig` interface extends `BaseConfig` with the following options:

| Option             | Type                           | Required | Default | Description                                    |
| ------------------ | ------------------------------ | -------- | ------- | ---------------------------------------------- |
| `simulateFailure`  | `boolean`                      | No       | `false` | When true, `sendEmail` always returns an error |
| `failureRate`      | `number`                       | No       | `0`     | Failure rate (0-1) for random failures         |
| `delay`            | `number`                       | No       | `0`     | Delay in milliseconds before resolving         |
| `randomDelayRange` | `{ min: number; max: number }` | No       | -       | Random delay range in milliseconds             |
| `defaultResponse`  | `Receipt`                      | No       | -       | Default response to return for send operations |
| `debug`            | `boolean`                      | No       | `false` | Enable debug logging                           |
| `logger`           | `Console`                      | No       | -       | Custom logger instance                         |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Test email").html("<h1>Hello World</h1>");

const result = await mail.send(message);

if (result.success) {
    console.log("Mock email sent:", result.data?.messageId);
}
```

## Testing Scenarios [#testing-scenarios]

### Simulate Failures [#simulate-failures]

```typescript
const mock = mockProvider({
    simulateFailure: true,
});

const mail = createMail(mock);
const result = await mail.send(message);
// result.success will be false
```

### Random Failure Rate [#random-failure-rate]

```typescript
const mock = mockProvider({
    failureRate: 0.3, // 30% of sends will fail
});
```

### Artificial Delays [#artificial-delays]

```typescript
// Fixed delay
const mock = mockProvider({
    delay: 500, // 500ms delay
});

// Random delay range
const mock = mockProvider({
    randomDelayRange: {
        min: 100,
        max: 1000,
    },
});
```

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | No        |
| Tracking       | No        |


# Netcore (/docs/packages/email/providers/netcore)



# Netcore Provider [#netcore-provider]

The Netcore provider sends emails through the [Netcore Email API v5.1](https://emailapi.netcorecloud.net/) (formerly Pepipost).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers) — uses the Fetch API.

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { netcoreProvider } from "@visulima/email/providers/netcore";

const mail = createMail(
    netcoreProvider({
        apiKey: process.env.NETCORE_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `NetcoreConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                                  | Description                                           |
| ---------- | --------- | -------- | ---------------------------------------- | ----------------------------------------------------- |
| `apiKey`   | `string`  | Yes      | -                                        | Your Netcore Email API key (sent as `api_key` header) |
| `endpoint` | `string`  | No       | `https://emailapi.netcorecloud.net/v5.1` | Custom API endpoint                                   |
| `debug`    | `boolean` | No       | `false`                                  | Enable debug logging                                  |
| `logger`   | `Console` | No       | -                                        | Custom logger instance                                |
| `retries`  | `number`  | No       | `3`                                      | Number of retry attempts                              |
| `timeout`  | `number`  | No       | `30000`                                  | Request timeout in milliseconds                       |

## Basic Usage [#basic-usage]

```typescript
const result = await mail.send({
    from: { email: "noreply@example.com", name: "My App" },
    to: { email: "user@example.com" },
    subject: "Hello from Netcore",
    html: "<h1>Welcome!</h1>",
    text: "Welcome!",
});
```

## Provider-Specific Email Options [#provider-specific-email-options]

The `NetcoreEmailOptions` interface extends `EmailOptions` with:

| Option         | Type                      | Description                                          |
| -------------- | ------------------------- | ---------------------------------------------------- |
| `templateId`   | `string`                  | Stored template id to send instead of inline content |
| `templateData` | `Record<string, unknown>` | Variables substituted into the Netcore template      |

```typescript
await mail.send({
    from: { email: "noreply@example.com" },
    to: { email: "user@example.com" },
    subject: "Templated email",
    templateId: "12345",
    templateData: { name: "Ada" },
});
```

## Supported Features [#supported-features]

* ✅ Attachments
* ✅ Batch sending
* ✅ Custom headers
* ✅ HTML & text bodies
* ✅ Reply-To
* ✅ Tagging
* ✅ Templates
* ✅ Tracking


# Nodemailer (/docs/packages/email/providers/nodemailer)



# Nodemailer Provider [#nodemailer-provider]

The Nodemailer provider wraps the popular [Nodemailer](https://nodemailer.com/about/) Node.js email library, allowing you to use any Nodemailer transport (SMTP, Sendmail, SES, etc.) with the @visulima/email API.

**Runtime Support:** Node.js only (requires the `nodemailer` package)

## Prerequisites [#prerequisites]

Install `nodemailer` as a peer dependency:

```bash
npm install nodemailer
```

## Setup [#setup]

### SMTP Transport [#smtp-transport]

```typescript
import { createMail } from "@visulima/email";
import { nodemailerProvider } from "@visulima/email/providers/nodemailer";

const mail = createMail(
    nodemailerProvider({
        transport: {
            host: "smtp.example.com",
            port: 587,
            secure: false,
            auth: {
                user: process.env.SMTP_USER!,
                pass: process.env.SMTP_PASSWORD!,
            },
        },
    }),
);
```

### Sendmail Transport [#sendmail-transport]

```typescript
const mail = createMail(
    nodemailerProvider({
        transport: {
            sendmail: true,
            path: "/usr/sbin/sendmail",
        },
    }),
);
```

## Configuration [#configuration]

The `NodemailerConfig` interface extends `BaseConfig` with the following options:

| Option        | Type                                | Required | Default | Description                        |
| ------------- | ----------------------------------- | -------- | ------- | ---------------------------------- |
| `transport`   | `Record<string, unknown> \| string` | Yes      | -       | Nodemailer transport configuration |
| `defaultFrom` | `EmailAddress`                      | No       | -       | Default from address               |
| `debug`       | `boolean`                           | No       | `false` | Enable debug logging               |
| `logger`      | `Console`                           | No       | -       | Custom logger instance             |
| `retries`     | `number`                            | No       | `3`     | Number of retry attempts           |
| `timeout`     | `number`                            | No       | `30000` | Request timeout in milliseconds    |

The `transport` option accepts any valid Nodemailer transport configuration. See [Nodemailer transports documentation](https://nodemailer.com/transports/) for all available options.

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello via Nodemailer").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Nodemailer provider supports additional options through `NodemailerEmailOptions`:

| Option              | Type                                | Description                                |
| ------------------- | ----------------------------------- | ------------------------------------------ |
| `transportOverride` | `Record<string, unknown> \| string` | Override transport for this specific email |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | No        |
| Tracking       | No        |


# OpenTelemetry (/docs/packages/email/providers/opentelemetry)



# OpenTelemetry Provider [#opentelemetry-provider]

The OpenTelemetry provider wraps any other provider with [OpenTelemetry](https://opentelemetry.io/docs/) instrumentation, adding distributed tracing and metrics to your email sending operations.

**Runtime Support:** Depends on the wrapped provider

## Prerequisites [#prerequisites]

Install OpenTelemetry packages:

```bash
npm install @opentelemetry/api @opentelemetry/sdk-trace-base
```

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { opentelemetryProvider } from "@visulima/email/providers/opentelemetry";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(
    opentelemetryProvider({
        provider: resendProvider({ apiKey: process.env.RESEND_API_KEY! }),
        serviceName: "my-email-service",
        recordContent: false,
    }),
);
```

## Configuration [#configuration]

The `OpenTelemetryConfig` interface extends `BaseConfig` with the following options:

| Option          | Type                          | Required | Default   | Description                               |
| --------------- | ----------------------------- | -------- | --------- | ----------------------------------------- |
| `provider`      | `Provider \| ProviderFactory` | Yes      | -         | The provider to wrap with instrumentation |
| `serviceName`   | `string`                      | No       | `"email"` | Service name for OpenTelemetry spans      |
| `recordContent` | `boolean`                     | No       | `false`   | Whether to record email content in spans  |
| `tracer`        | `Tracer`                      | No       | Global    | Custom OpenTelemetry tracer instance      |
| `debug`         | `boolean`                     | No       | `false`   | Enable debug logging                      |
| `logger`        | `Console`                     | No       | -         | Custom logger instance                    |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello with Tracing").html("<h1>Hello World</h1>");

const result = await mail.send(message);
// Spans will be created automatically for the send operation
```

## Custom Tracer [#custom-tracer]

You can provide a custom tracer instance:

```typescript
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("my-app", "1.0.0");

const mail = createMail(
    opentelemetryProvider({
        provider: resendProvider({ apiKey: "re_xxx" }),
        tracer,
        serviceName: "email-service",
    }),
);
```

## Recording Content [#recording-content]

By default, email content is not recorded in spans for privacy reasons. Enable it for debugging:

```typescript
const mail = createMail(
    opentelemetryProvider({
        provider: resendProvider({ apiKey: "re_xxx" }),
        recordContent: true, // Records email content in spans
    }),
);
```

## Supported Features [#supported-features]

The OpenTelemetry provider supports whatever features the underlying provider supports. It transparently proxies all operations while adding instrumentation.


# Outlook365 (/docs/packages/email/providers/outlook365)



# Outlook365 Provider [#outlook365-provider]

The Outlook365 provider sends emails through the [Microsoft Graph `sendMail` endpoint](https://learn.microsoft.com/en-us/graph/api/user-sendmail).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers) — uses the Fetch API.

Authentication is delegated: you supply a static `accessToken` or an async `getAccessToken` (e.g. backed by
`@azure/msal-node`). The provider never bundles an auth SDK, so it stays dependency-light and runtime-agnostic.

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { outlook365Provider } from "@visulima/email/providers/outlook365";

const mail = createMail(
    outlook365Provider({
        // Bring your own OAuth2 token with the `Mail.Send` scope.
        getAccessToken: async () => getGraphAccessToken(),
        userId: "sender@contoso.com", // or "me" (default) to use the token's own mailbox
    }),
);
```

## Configuration [#configuration]

The `Outlook365Config` interface extends `BaseConfig`. One of `accessToken` / `getAccessToken` is required.

| Option            | Type                         | Required | Default                            | Description                                                  |
| ----------------- | ---------------------------- | -------- | ---------------------------------- | ------------------------------------------------------------ |
| `accessToken`     | `string`                     | Cond.    | -                                  | Static OAuth2 token with the `Mail.Send` scope               |
| `getAccessToken`  | `() => MaybePromise<string>` | Cond.    | -                                  | Returns a fresh OAuth2 token (preferred for expiring tokens) |
| `userId`          | `string`                     | No       | `me`                               | Mailbox to send as (user id / UPN)                           |
| `saveToSentItems` | `boolean`                    | No       | `true`                             | Keep a copy in the Sent Items folder                         |
| `endpoint`        | `string`                     | No       | `https://graph.microsoft.com/v1.0` | Custom Graph endpoint                                        |
| `debug`           | `boolean`                    | No       | `false`                            | Enable debug logging                                         |
| `logger`          | `Console`                    | No       | -                                  | Custom logger instance                                       |
| `retries`         | `number`                     | No       | `3`                                | Number of retry attempts                                     |
| `timeout`         | `number`                     | No       | `30000`                            | Request timeout in milliseconds                              |

## Basic Usage [#basic-usage]

```typescript
const result = await mail.send({
    from: { email: "sender@contoso.com" },
    to: { email: "user@example.com" },
    subject: "Hello from Outlook365",
    html: "<h1>Welcome!</h1>",
});
```

> **Note:** Microsoft Graph always sends as the authenticated user / `userId`, so the `from` address is effectively
> the mailbox the token is scoped to. Graph's `sendMail` returns `202 Accepted` with an empty body, so a message id is
> synthesised in the result.

## Provider-Specific Email Options [#provider-specific-email-options]

The `Outlook365EmailOptions` interface extends `EmailOptions` with:

| Option       | Type                          | Description        |
| ------------ | ----------------------------- | ------------------ |
| `importance` | `"high" \| "low" \| "normal"` | Message importance |

## Supported Features [#supported-features]

* ✅ Attachments
* ✅ Custom headers
* ✅ HTML & text bodies
* ✅ Reply-To
* ❌ Batch sending
* ❌ Tagging / templates / tracking (use Graph directly for those)


# Plunk (/docs/packages/email/providers/plunk)



# Plunk Provider [#plunk-provider]

The Plunk provider allows you to send emails through the [Plunk API](https://docs.useplunk.com/api-reference), a modern email platform built on AWS SES.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { plunkProvider } from "@visulima/email/providers/plunk";

const mail = createMail(
    plunkProvider({
        apiKey: process.env.PLUNK_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `PlunkConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default | Description                     |
| ---------- | --------- | -------- | ------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -       | Your Plunk API key              |
| `endpoint` | `string`  | No       | Auto    | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false` | Enable debug logging            |
| `logger`   | `Console` | No       | -       | Custom logger instance          |
| `retries`  | `number`  | No       | `3`     | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000` | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Plunk").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Plunk provider supports additional options through `PlunkEmailOptions`:

| Option         | Type                      | Description                                                    |
| -------------- | ------------------------- | -------------------------------------------------------------- |
| `templateId`   | `string`                  | Template ID for template-based emails                          |
| `data`         | `Record<string, unknown>` | Data to pass to the email template                             |
| `subscriber`   | `string`                  | Subscriber email for tracking (defaults to first `to` address) |
| `subscriberId` | `string`                  | Optional subscriber identifier                                 |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# Postal (/docs/packages/email/providers/postal)



# Postal Provider [#postal-provider]

The Postal provider allows you to send emails through a self-hosted [Postal](https://postal.atech.media/docs/developer/sending) email server.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { postalProvider } from "@visulima/email/providers/postal";

const mail = createMail(
    postalProvider({
        apiKey: process.env.POSTAL_API_KEY!,
        host: "postal.example.com",
    }),
);
```

## Configuration [#configuration]

The `PostalConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                 | Description                     |
| ---------- | --------- | -------- | ----------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                       | Your Postal server API key      |
| `host`     | `string`  | Yes      | -                       | Your Postal server host         |
| `endpoint` | `string`  | No       | `https://{host}/api/v1` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                 | Enable debug logging            |
| `logger`   | `Console` | No       | -                       | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                     | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                 | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Postal").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Postal provider supports additional options through `PostalEmailOptions`:

| Option              | Type                      | Description                    |
| ------------------- | ------------------------- | ------------------------------ |
| `tags`              | `string[]`                | Tags for categorization        |
| `templateId`        | `number`                  | Postal template ID             |
| `templateVariables` | `Record<string, unknown>` | Template variables             |
| `postalMessageId`   | `string`                  | Postal message ID for tracking |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# Postmark (/docs/packages/email/providers/postmark)



# Postmark Provider [#postmark-provider]

The Postmark provider allows you to send emails through the [Postmark API](https://postmarkapp.com/developer/api/email-api), a transactional email service focused on deliverability.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { postmarkProvider } from "@visulima/email/providers/postmark";

const mail = createMail(
    postmarkProvider({
        serverToken: process.env.POSTMARK_SERVER_TOKEN!,
    }),
);
```

## Configuration [#configuration]

The `PostmarkConfig` interface extends `BaseConfig` with the following options:

| Option        | Type      | Required | Default                       | Description                     |
| ------------- | --------- | -------- | ----------------------------- | ------------------------------- |
| `serverToken` | `string`  | Yes      | -                             | Your Postmark Server API Token  |
| `endpoint`    | `string`  | No       | `https://api.postmarkapp.com` | Custom API endpoint             |
| `debug`       | `boolean` | No       | `false`                       | Enable debug logging            |
| `logger`      | `Console` | No       | -                             | Custom logger instance          |
| `retries`     | `number`  | No       | `3`                           | Number of retry attempts        |
| `timeout`     | `number`  | No       | `30000`                       | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Postmark").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Postmark provider supports additional options through `PostmarkEmailOptions`:

```typescript
import type { PostmarkEmailOptions } from "@visulima/email/providers/postmark";

const options: PostmarkEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    messageStream: "outbound",
    trackOpens: true,
    trackLinks: "HtmlAndText",
    metadata: { userId: "123" },
    inlineCss: true,
};
```

| Option          | Type                                                  | Description                                 |
| --------------- | ----------------------------------------------------- | ------------------------------------------- |
| `templateId`    | `number`                                              | Postmark template ID                        |
| `templateAlias` | `string`                                              | Postmark template alias (alternative to ID) |
| `templateModel` | `Record<string, unknown>`                             | Template model/variables                    |
| `messageStream` | `string`                                              | Message stream ID                           |
| `trackOpens`    | `boolean`                                             | Enable open tracking                        |
| `trackLinks`    | `"HtmlAndText" \| "HtmlOnly" \| "TextOnly" \| "None"` | Link tracking mode                          |
| `metadata`      | `Record<string, string>`                              | Metadata key-value pairs                    |
| `inlineCss`     | `boolean`                                             | Inline CSS for HTML emails                  |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# Resend (/docs/packages/email/providers/resend)



# Resend Provider [#resend-provider]

The Resend provider allows you to send emails through the [Resend API](https://resend.com/docs/api-reference/emails/send-email), a modern email API for developers.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";

const mail = createMail(
    resendProvider({
        apiKey: process.env.RESEND_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `ResendConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                  | Description                             |
| ---------- | --------- | -------- | ------------------------ | --------------------------------------- |
| `apiKey`   | `string`  | Yes      | -                        | Your Resend API key (starts with `re_`) |
| `endpoint` | `string`  | No       | `https://api.resend.com` | Custom API endpoint                     |
| `debug`    | `boolean` | No       | `false`                  | Enable debug logging                    |
| `logger`   | `Console` | No       | -                        | Custom logger instance                  |
| `retries`  | `number`  | No       | `3`                      | Number of retry attempts on failure     |
| `timeout`  | `number`  | No       | `30000`                  | Request timeout in milliseconds         |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Resend").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Resend provider supports additional options through `ResendEmailOptions`:

### Tags [#tags]

Tags can be used for categorizing emails. Tag names and values must only contain ASCII letters, numbers, underscores, or dashes. Tag names have a max length of 256 characters.

```typescript
import type { ResendEmailOptions } from "@visulima/email/providers/resend";

const options: ResendEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Tagged email",
    html: "<h1>Hello</h1>",
    tags: [
        { name: "category", value: "welcome" },
        { name: "environment", value: "production" },
    ],
};
```

### Scheduled Sending [#scheduled-sending]

```typescript
const options: ResendEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Scheduled email",
    html: "<h1>Hello</h1>",
    scheduledAt: new Date("2025-01-15T10:00:00Z"),
};
```

### Template-Based Emails [#template-based-emails]

```typescript
const options: ResendEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Template email",
    html: "",
    templateId: "tmpl_xxx",
    templateData: {
        name: "John",
        company: "Acme",
    },
};
```

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |

## Additional Methods [#additional-methods]

### Retrieve Email [#retrieve-email]

You can retrieve email details by ID:

```typescript
const provider = resendProvider({ apiKey: "re_xxx" });
const result = await provider.getEmail("email-id");
```

### Validate Credentials [#validate-credentials]

```typescript
const isValid = await provider.validateCredentials();
```


# Round Robin (/docs/packages/email/providers/roundrobin)



# Round Robin Provider [#round-robin-provider]

The Round Robin provider distributes email sending across multiple providers in a round-robin fashion, providing load balancing for high-volume email sending.

**Runtime Support:** Depends on the wrapped providers

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { roundRobinProvider } from "@visulima/email/providers/roundrobin";
import { resendProvider } from "@visulima/email/providers/resend";
import { sendGridProvider } from "@visulima/email/providers/sendgrid";

const mail = createMail(
    roundRobinProvider({
        mailers: [resendProvider({ apiKey: process.env.RESEND_API_KEY! }), sendGridProvider({ apiKey: process.env.SENDGRID_API_KEY! })],
    }),
);
```

## Configuration [#configuration]

The `RoundRobinConfig` interface extends `BaseConfig` with the following options:

| Option       | Type        | Required | Default | Description                                                                 |
| ------------ | ----------- | -------- | ------- | --------------------------------------------------------------------------- |
| `mailers`    | `unknown[]` | Yes      | -       | Array of provider instances or provider factory functions                   |
| `retryAfter` | `number`    | No       | `60`    | Time in milliseconds to wait before retrying with next unavailable provider |
| `debug`      | `boolean`   | No       | `false` | Enable debug logging                                                        |
| `logger`     | `Console`   | No       | -       | Custom logger instance                                                      |

## How It Works [#how-it-works]

1. Each email is sent using the next provider in the rotation.
2. If a provider is unavailable, the round robin moves to the next available provider.
3. The rotation continues cyclically through all providers.
4. If all providers are unavailable, an error is returned.

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

// First email goes to provider 1
await mail.send(new MailMessage().to("a@example.com").from("sender@example.com").subject("Email 1").html("<h1>1</h1>"));

// Second email goes to provider 2
await mail.send(new MailMessage().to("b@example.com").from("sender@example.com").subject("Email 2").html("<h1>2</h1>"));

// Third email goes back to provider 1
await mail.send(new MailMessage().to("c@example.com").from("sender@example.com").subject("Email 3").html("<h1>3</h1>"));
```

## Supported Features [#supported-features]

The round robin provider supports whatever features the underlying providers support. Feature availability depends on which provider is selected for a given email.


# Scaleway (/docs/packages/email/providers/scaleway)



# Scaleway Provider [#scaleway-provider]

The Scaleway provider allows you to send emails through the [Scaleway Transactional Email API](https://www.scaleway.com/en/docs/messaging-and-queuing/transactional-email/api-reference/), a European cloud provider email service.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { scalewayProvider } from "@visulima/email/providers/scaleway";

const mail = createMail(
    scalewayProvider({
        apiKey: process.env.SCALEWAY_API_KEY!,
        region: "fr-par",
    }),
);
```

## Configuration [#configuration]

The `ScalewayConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                                                 | Description                                |
| ---------- | --------- | -------- | ------------------------------------------------------- | ------------------------------------------ |
| `apiKey`   | `string`  | Yes      | -                                                       | Your Scaleway API key                      |
| `region`   | `string`  | Yes      | -                                                       | Scaleway region (e.g., `fr-par`, `nl-ams`) |
| `endpoint` | `string`  | No       | `https://api.scaleway.com/transactional-email/v1alpha1` | Custom API endpoint                        |
| `debug`    | `boolean` | No       | `false`                                                 | Enable debug logging                       |
| `logger`   | `Console` | No       | -                                                       | Custom logger instance                     |
| `retries`  | `number`  | No       | `3`                                                     | Number of retry attempts                   |
| `timeout`  | `number`  | No       | `30000`                                                 | Request timeout in milliseconds            |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Scaleway").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Scaleway provider supports additional options through `ScalewayEmailOptions`:

| Option              | Type                      | Description          |
| ------------------- | ------------------------- | -------------------- |
| `templateId`        | `string`                  | Scaleway template ID |
| `templateVariables` | `Record<string, unknown>` | Template variables   |
| `projectId`         | `string`                  | Scaleway project ID  |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# SendGrid (/docs/packages/email/providers/sendgrid)



# SendGrid Provider [#sendgrid-provider]

The SendGrid provider allows you to send emails through the [SendGrid Mail Send API](https://docs.sendgrid.com/api-reference/mail-send/mail-send), a cloud-based email service for transactional and marketing emails.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { sendGridProvider } from "@visulima/email/providers/sendgrid";

const mail = createMail(
    sendGridProvider({
        apiKey: process.env.SENDGRID_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `SendGridConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                    | Description                     |
| ---------- | --------- | -------- | -------------------------- | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                          | Your SendGrid API key           |
| `endpoint` | `string`  | No       | `https://api.sendgrid.com` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                    | Enable debug logging            |
| `logger`   | `Console` | No       | -                          | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                        | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                    | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from SendGrid").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The SendGrid provider supports extensive additional options through `SendGridEmailOptions`:

### Dynamic Templates [#dynamic-templates]

```typescript
import type { SendGridEmailOptions } from "@visulima/email/providers/sendgrid";

const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "",
    templateId: "d-xxx",
    templateData: { name: "John", company: "Acme" },
};
```

### Tracking Settings [#tracking-settings]

```typescript
const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    trackingSettings: {
        clickTracking: { enable: true, enableText: false },
        openTracking: { enable: true, substitutionTag: "%open%" },
        subscriptionTracking: {
            enable: true,
            text: "Unsubscribe here: <% %>",
            html: "<a href='<% %>'>Unsubscribe</a>",
            substitutionTag: "<% %>",
        },
        ganalytics: {
            enable: true,
            utmSource: "email",
            utmMedium: "transactional",
            utmCampaign: "welcome",
        },
    },
};
```

### Mail Settings [#mail-settings]

```typescript
const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    mailSettings: {
        sandboxMode: true,
        bypassListManagement: false,
        footer: {
            enable: true,
            text: "Footer text",
            html: "<p>Footer HTML</p>",
        },
    },
};
```

| Option             | Type                      | Description                                  |
| ------------------ | ------------------------- | -------------------------------------------- |
| `templateId`       | `string`                  | SendGrid dynamic template ID                 |
| `templateData`     | `Record<string, unknown>` | Dynamic template data                        |
| `sendAt`           | `number`                  | Send at (Unix timestamp)                     |
| `batchId`          | `string`                  | Batch ID for batch sending                   |
| `asmGroupId`       | `number`                  | Advanced Suppression Management group ID     |
| `ipPoolName`       | `string`                  | IP pool name                                 |
| `mailSettings`     | `object`                  | Mail settings (sandbox, footer, etc.)        |
| `trackingSettings` | `object`                  | Tracking settings (clicks, opens, analytics) |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | Yes       |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | Yes       |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | Yes       |


# SMTP (/docs/packages/email/providers/smtp)



# SMTP Provider [#smtp-provider]

The SMTP provider allows you to send emails using the standard [SMTP protocol (RFC 5321)](https://tools.ietf.org/html/rfc5321) with a built-in SMTP client. No external library is required.

**Runtime Support:** Node.js only (requires `node:net` and `node:tls`)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { smtpProvider } from "@visulima/email/providers/smtp";

const mail = createMail(
    smtpProvider({
        host: "smtp.example.com",
        port: 587,
        secure: false,
        user: process.env.SMTP_USER!,
        password: process.env.SMTP_PASSWORD!,
    }),
);
```

## Configuration [#configuration]

The `SmtpConfig` interface extends `BaseConfig` with the following options:

| Option               | Type                                           | Required | Default | Description                           |
| -------------------- | ---------------------------------------------- | -------- | ------- | ------------------------------------- |
| `host`               | `string`                                       | Yes      | -       | SMTP server hostname                  |
| `port`               | `number`                                       | Yes      | -       | SMTP server port (25, 465, 587, etc.) |
| `secure`             | `boolean`                                      | No       | `false` | Use TLS (true for port 465)           |
| `user`               | `string`                                       | No       | -       | SMTP username                         |
| `password`           | `string`                                       | No       | -       | SMTP password                         |
| `authMethod`         | `"LOGIN" \| "PLAIN" \| "CRAM-MD5" \| "OAUTH2"` | No       | -       | Authentication method                 |
| `pool`               | `boolean`                                      | No       | `false` | Enable connection pooling             |
| `maxConnections`     | `number`                                       | No       | -       | Maximum pool connections              |
| `rejectUnauthorized` | `boolean`                                      | No       | -       | Reject unauthorized TLS certificates  |
| `dkim`               | `object`                                       | No       | -       | DKIM signing configuration            |
| `oauth2`             | `object`                                       | No       | -       | OAuth2 authentication configuration   |
| `debug`              | `boolean`                                      | No       | `false` | Enable debug logging                  |
| `logger`             | `Console`                                      | No       | -       | Custom logger instance                |
| `retries`            | `number`                                       | No       | `3`     | Number of retry attempts              |
| `timeout`            | `number`                                       | No       | `30000` | Request timeout in milliseconds       |

### DKIM Configuration [#dkim-configuration]

```typescript
const mail = createMail(
    smtpProvider({
        host: "smtp.example.com",
        port: 587,
        user: "user",
        password: "pass",
        dkim: {
            domainName: "example.com",
            keySelector: "default",
            privateKey: "-----BEGIN PRIVATE KEY-----\n...",
        },
    }),
);
```

### OAuth2 Authentication [#oauth2-authentication]

```typescript
const mail = createMail(
    smtpProvider({
        host: "smtp.gmail.com",
        port: 465,
        secure: true,
        authMethod: "OAUTH2",
        oauth2: {
            user: "user@gmail.com",
            clientId: "client-id",
            clientSecret: "client-secret",
            refreshToken: "refresh-token",
            accessToken: "access-token",
        },
    }),
);
```

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello via SMTP").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The SMTP provider supports additional options through `SmtpEmailOptions`:

```typescript
import type { SmtpEmailOptions } from "@visulima/email/providers/smtp";

const options: SmtpEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    priority: "high",
    inReplyTo: "<original-message-id@example.com>",
    references: ["<message-1@example.com>", "<message-2@example.com>"],
    listUnsubscribe: "https://example.com/unsubscribe",
    useDkim: true,
    dsn: {
        success: true,
        failure: true,
        delay: false,
    },
    googleMailHeaders: {
        category: "primary",
        feedbackId: "feedback-123",
        promotionalContent: false,
    },
};
```

| Option              | Type                          | Description                                    |
| ------------------- | ----------------------------- | ---------------------------------------------- |
| `priority`          | `"high" \| "normal" \| "low"` | Message priority                               |
| `inReplyTo`         | `string`                      | Reference to a previous message ID (threading) |
| `references`        | `string \| string[]`          | References to related message IDs              |
| `listUnsubscribe`   | `string \| string[]`          | List-Unsubscribe header                        |
| `useDkim`           | `boolean`                     | Sign the email with DKIM                       |
| `dsn`               | `object`                      | Delivery Status Notification options           |
| `googleMailHeaders` | `object`                      | Google Mail-specific headers                   |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | No        |
| Templates      | No        |
| Tracking       | No        |


# SparkPost (/docs/packages/email/providers/sparkpost)



# SparkPost Provider [#sparkpost-provider]

The SparkPost provider sends emails through the [SparkPost Transmissions API](https://developers.sparkpost.com/api/transmissions/).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers) — uses the Fetch API.

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { sparkpostProvider } from "@visulima/email/providers/sparkpost";

const mail = createMail(
    sparkpostProvider({
        apiKey: process.env.SPARKPOST_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `SparkPostConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                            | Description                                                          |
| ---------- | --------- | -------- | ---------------------------------- | -------------------------------------------------------------------- |
| `apiKey`   | `string`  | Yes      | -                                  | Your SparkPost API key (sent as the `Authorization` header)          |
| `endpoint` | `string`  | No       | `https://api.sparkpost.com/api/v1` | Custom API endpoint. Use `https://api.eu.sparkpost.com/api/v1` (EU). |
| `debug`    | `boolean` | No       | `false`                            | Enable debug logging                                                 |
| `logger`   | `Console` | No       | -                                  | Custom logger instance                                               |
| `retries`  | `number`  | No       | `3`                                | Number of retry attempts                                             |
| `timeout`  | `number`  | No       | `30000`                            | Request timeout in milliseconds                                      |

## Basic Usage [#basic-usage]

```typescript
const result = await mail.send({
    from: { email: "noreply@example.com", name: "My App" },
    to: { email: "user@example.com" },
    subject: "Hello from SparkPost",
    html: "<h1>Welcome!</h1>",
    text: "Welcome!",
});
```

## Provider-Specific Email Options [#provider-specific-email-options]

The `SparkPostEmailOptions` interface extends `EmailOptions` with:

| Option        | Type      | Description                                          |
| ------------- | --------- | ---------------------------------------------------- |
| `campaignId`  | `string`  | Campaign id applied to the transmission              |
| `templateId`  | `string`  | Stored template id to send instead of inline content |
| `trackOpens`  | `boolean` | Whether open tracking is enabled                     |
| `trackClicks` | `boolean` | Whether click tracking is enabled                    |

```typescript
await mail.send({
    from: { email: "noreply@example.com" },
    to: { email: "user@example.com" },
    subject: "Campaign email",
    html: "<p>Hello</p>",
    campaignId: "summer-2026",
    trackOpens: true,
    trackClicks: true,
});
```

## Supported Features [#supported-features]

* ✅ Attachments
* ✅ Batch sending
* ✅ Custom headers
* ✅ HTML & text bodies
* ✅ Reply-To
* ✅ Tagging
* ✅ Templates
* ✅ Open/click tracking


# Sweego (/docs/packages/email/providers/sweego)



# Sweego Provider [#sweego-provider]

The Sweego provider allows you to send emails through the [Sweego API](https://api.sweego.com/docs), an email delivery service.

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { sweegoProvider } from "@visulima/email/providers/sweego";

const mail = createMail(
    sweegoProvider({
        apiKey: process.env.SWEEGO_API_KEY!,
    }),
);
```

## Configuration [#configuration]

The `SweegoConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default                  | Description                     |
| ---------- | --------- | -------- | ------------------------ | ------------------------------- |
| `apiKey`   | `string`  | Yes      | -                        | Your Sweego API key             |
| `endpoint` | `string`  | No       | `https://api.sweego.com` | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false`                  | Enable debug logging            |
| `logger`   | `Console` | No       | -                        | Custom logger instance          |
| `retries`  | `number`  | No       | `3`                      | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000`                  | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Sweego").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Sweego provider supports additional options through `SweegoEmailOptions`:

| Option              | Type                      | Description             |
| ------------------- | ------------------------- | ----------------------- |
| `tags`              | `string[]`                | Tags for categorization |
| `templateId`        | `string`                  | Sweego template ID      |
| `templateVariables` | `Record<string, unknown>` | Template variables      |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | Yes       |
| Tracking       | No        |


# Zeptomail (/docs/packages/email/providers/zeptomail)



# Zeptomail Provider [#zeptomail-provider]

The Zeptomail provider allows you to send emails through the [Zeptomail API](https://www.zeptomail.com/docs/api/).

**Runtime Support:** Universal (Node.js, Deno, Bun, Cloudflare Workers)

## Setup [#setup]

```typescript
import { createMail } from "@visulima/email";
import { zeptomailProvider } from "@visulima/email/providers/zeptomail";

const mail = createMail(
    zeptomailProvider({
        token: process.env.ZEPTOMAIL_TOKEN!,
    }),
);
```

## Configuration [#configuration]

The `ZeptomailConfig` interface extends `BaseConfig` with the following options:

| Option     | Type      | Required | Default | Description                     |
| ---------- | --------- | -------- | ------- | ------------------------------- |
| `token`    | `string`  | Yes      | -       | Your Zeptomail send mail token  |
| `endpoint` | `string`  | No       | Auto    | Custom API endpoint             |
| `debug`    | `boolean` | No       | `false` | Enable debug logging            |
| `logger`   | `Console` | No       | -       | Custom logger instance          |
| `retries`  | `number`  | No       | `3`     | Number of retry attempts        |
| `timeout`  | `number`  | No       | `30000` | Request timeout in milliseconds |

## Basic Usage [#basic-usage]

```typescript
import { MailMessage } from "@visulima/email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello from Zeptomail").html("<h1>Hello World</h1>");

const result = await mail.send(message);
```

## Provider-Specific Email Options [#provider-specific-email-options]

The Zeptomail provider supports additional options through `ZeptomailEmailOptions`:

| Option            | Type                     | Description                                  |
| ----------------- | ------------------------ | -------------------------------------------- |
| `clientReference` | `string`                 | Identifier to track a particular transaction |
| `mimeHeaders`     | `Record<string, string>` | Additional MIME headers                      |
| `trackClicks`     | `boolean`                | Enable tracking for click events             |
| `trackOpens`      | `boolean`                | Enable tracking for open events              |

## Supported Features [#supported-features]

| Feature        | Supported |
| -------------- | --------- |
| Attachments    | Yes       |
| Batch Sending  | No        |
| Custom Headers | Yes       |
| HTML           | Yes       |
| Reply-To       | Yes       |
| Scheduling     | No        |
| Tagging        | Yes       |
| Templates      | No        |
| Tracking       | Yes       |


# Queue (/docs/packages/email/queue/introduction)



# Queue [#queue]

`@visulima/email/queue` lets you decouple accepting an email from delivering it. You `enqueue()` a message, and a worker reserves jobs, sends them with bounded concurrency, retries failures with backoff, and dead-letters jobs that exhaust their attempts. An in-memory queue ships for tests and single-process apps; a durable [unstorage](https://unstorage.unjs.io/)-backed queue (importable from `@visulima/email/queue/unstorage`) persists jobs across restarts and across many backends.

```typescript
import { createWorker, MemoryQueue } from "@visulima/email/queue";
import type { EmailQueue, QueueJob } from "@visulima/email/queue";
```

## How It Works [#how-it-works]

Delivery follows a reserve → ack/retry cycle:

1. `enqueue(message)` adds a job to the queue.
2. `reserve()` hands a job to a worker and hides it for a visibility window so other workers don't pick it up.
3. On success the worker `ack`s the job (removing it); on failure it `retry`s the job (returning it to the queue, optionally after a delay).

If a worker crashes mid-process, the reserved job becomes deliverable again once its visibility timeout elapses.

## MemoryQueue [#memoryqueue]

`MemoryQueue` is an in-memory `EmailQueue` with `scheduledAt` support and a reservation visibility timeout. It is ideal for tests, single-process apps, and as a reference for adapter authors. Jobs do not survive a process restart — use a durable adapter in production.

```typescript
import { MemoryQueue } from "@visulima/email/queue";

const queue = new MemoryQueue({
    visibilityTimeout: 30_000, // ms a reserved job stays hidden (default 30000)
    now: () => Date.now(), // injectable time source, mainly for tests
});
```

### EmailQueue Methods [#emailqueue-methods]

| Method                              | Description                                                                         |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `enqueue(message, { scheduledAt })` | Adds a message. Returns the new job id. `scheduledAt` accepts a `Date` or epoch ms. |
| `reserve()`                         | Reserves the next ready job, hiding it for the visibility window.                   |
| `ack(id)`                           | Marks a reserved job as processed and removes it.                                   |
| `retry(id, delayMs?)`               | Returns a job to the queue after an optional delay, incrementing its attempt count. |
| `size()`                            | Returns the number of jobs not yet acked (ready plus reserved).                     |

### Scheduling [#scheduling]

`scheduledAt` delays when a job first becomes deliverable. It accepts either a `Date` or epoch milliseconds:

```typescript
// Deliver in one hour.
await queue.enqueue(message, { scheduledAt: new Date(Date.now() + 60 * 60 * 1000) });

// Same, using epoch milliseconds.
await queue.enqueue(message, { scheduledAt: Date.now() + 60 * 60 * 1000 });
```

## createWorker [#createworker]

`createWorker(options)` returns a worker that processes queued jobs with bounded concurrency, retry/backoff, and dead-lettering. The `send` function is typically `mail.send.bind(mail)`.

```typescript
const worker = createWorker({
    queue,
    send: mail.send.bind(mail),
    concurrency: 5,
    maxAttempts: 3,
    backoff: (attempts) => 1000 * 2 ** (attempts - 1),
    pollInterval: 1000,
    onError: (job, result) => console.warn("attempt failed", job.id, result.error),
    onDeadLetter: (job, result) => console.error("dead-lettered", job.id, result.error),
});
```

### Worker Options [#worker-options]

| Option         | Type                                        | Default                                  | Description                                                |
| -------------- | ------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
| `queue`        | `EmailQueue`                                | —                                        | The queue to consume.                                      |
| `send`         | `(message) => Promise<Result<EmailResult>>` | —                                        | The send function, typically `mail.send.bind(mail)`.       |
| `concurrency`  | `number`                                    | `1`                                      | How many jobs to process concurrently.                     |
| `maxAttempts`  | `number`                                    | `3`                                      | Maximum delivery attempts before a job is dead-lettered.   |
| `backoff`      | `(attempts) => number`                      | `attempts => 1000 * 2 ** (attempts - 1)` | Delay (ms) before re-attempting after `attempts` failures. |
| `pollInterval` | `number`                                    | `1000`                                   | Idle poll interval (ms) when no job is ready.              |
| `onError`      | `(job, result) => void`                     | —                                        | Called on every failed attempt, before any retry.          |
| `onDeadLetter` | `(job, result) => void`                     | —                                        | Called when a job exhausts its attempts and is dropped.    |

### Worker Handle [#worker-handle]

`createWorker()` returns `{ start, stop, drain }`:

| Method    | Description                                                                                 |
| --------- | ------------------------------------------------------------------------------------------- |
| `start()` | Begins polling and processing jobs in the background.                                       |
| `stop()`  | Stops polling. In-flight jobs are allowed to finish.                                        |
| `drain()` | Processes all currently-ready jobs, then resolves. Does not wait for future-scheduled jobs. |

`drain()` is handy in tests and one-shot runs where you want to flush the queue and await completion rather than poll in the background.

### Enqueue and Run a Worker [#enqueue-and-run-a-worker]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createWorker, MemoryQueue } from "@visulima/email/queue";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
const queue = new MemoryQueue();

// Enqueue messages instead of sending them inline.
await queue.enqueue({
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Welcome",
    html: "<h1>Welcome!</h1>",
});

// Process in the background.
const worker = createWorker({
    queue,
    send: mail.send.bind(mail),
    concurrency: 5,
});

worker.start();

// … later, on shutdown:
worker.stop();
```

In a test or one-shot script, drain instead of starting a long-running loop:

```typescript
const worker = createWorker({ queue, send: mail.send.bind(mail) });

await queue.enqueue(message);
await worker.drain(); // processes everything ready, then resolves
```

## UnstorageQueue [#unstoragequeue]

`UnstorageQueue` (and the `createUnstorageQueue` factory) from `@visulima/email/queue/unstorage` is a **durable** `EmailQueue` backed by any [unstorage](https://unstorage.unjs.io/) `Storage`. Because unstorage abstracts many backends — memory, filesystem, Redis, Cloudflare KV, Postgres, and more — a single adapter persists the queue across all of them.

`unstorage` is an optional peer dependency. Install it (and any driver you need) alongside `@visulima/email`:

**Install:** `npm install unstorage`

```typescript
import { createUnstorageQueue, UnstorageQueue } from "@visulima/email/queue/unstorage";
```

### Options [#options]

`createUnstorageQueue(storage, options)` accepts:

| Option              | Type           | Default         | Description                                                 |
| ------------------- | -------------- | --------------- | ----------------------------------------------------------- |
| `prefix`            | `string`       | `"email:queue"` | Key prefix under which jobs are stored.                     |
| `visibilityTimeout` | `number`       | `30000`         | Ms a reserved job stays hidden before becoming deliverable. |
| `now`               | `() => number` | `Date.now`      | Injectable time source, mainly for tests.                   |

### Caveats [#caveats]

* The stored `message` must be **JSON-serializable**. Avoid `Buffer` attachments — pass `path` / `href` / base64 `content` instead.
* unstorage has no transactions, so `reserve()` is best-effort (non-transactional) under concurrent workers. The visibility timeout bounds duplicate delivery on a crash.

### Durable Queue with Redis [#durable-queue-with-redis]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { createWorker } from "@visulima/email/queue";
import { createUnstorageQueue } from "@visulima/email/queue/unstorage";
import { createStorage } from "unstorage";
import redisDriver from "unstorage/drivers/redis";

const mail = createMail(resendProvider({ apiKey: "re_xxx" }));

const storage = createStorage({
    driver: redisDriver({
        base: "email",
        url: "redis://localhost:6379",
    }),
});

const queue = createUnstorageQueue(storage, {
    prefix: "email:queue",
    visibilityTimeout: 30_000,
});

// Enqueue a JSON-serializable message.
await queue.enqueue({
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Welcome",
    html: "<h1>Welcome!</h1>",
});

// The worker API is identical regardless of the queue backend.
const worker = createWorker({
    queue,
    send: mail.send.bind(mail),
    concurrency: 5,
});

worker.start();
```

Because both `MemoryQueue` and `UnstorageQueue` implement the same `EmailQueue` interface, you can develop and test against `MemoryQueue` and switch to a durable backend in production without changing your worker code.


# Template Engines (/docs/packages/email/templates/introduction)



# Template Engines [#template-engines]

@visulima/email supports multiple template engines for rendering dynamic email content. All template engines implement the `TemplateRenderer` interface and can be used with the `MailMessage.view()` method.

```typescript
type TemplateRenderer = (template: unknown, data?: Record<string, unknown>, options?: Record<string, unknown>) => string | Promise<string>;
```

## Available Template Engines [#available-template-engines]

### Handlebars [#handlebars]

[Handlebars](https://handlebarsjs.com/) provides logic-less templating with support for helpers and partials.

**Install:** `npm install handlebars`

```typescript
import { MailMessage } from "@visulima/email";
import { renderHandlebars } from "@visulima/email/template/handlebars";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome");

await message.view(renderHandlebars, "<h1>Hello {{name}}!</h1><p>Welcome to {{company}}.</p>", {
    name: "John",
    company: "Acme Corp",
});
```

#### Registering Helpers [#registering-helpers]

```typescript
import { registerHandlebarsHelper } from "@visulima/email/template/handlebars";

registerHandlebarsHelper("uppercase", (str: string) => str.toUpperCase());

await message.view(renderHandlebars, "<h1>Hello {{uppercase name}}!</h1>", {
    name: "John",
});
```

#### Registering Partials [#registering-partials]

```typescript
import { registerHandlebarsPartial } from "@visulima/email/template/handlebars";

registerHandlebarsPartial("header", "<header><h1>{{title}}</h1></header>");

await message.view(renderHandlebars, "{{> header}}<p>Content here</p>", {
    title: "Welcome",
});
```

### MJML [#mjml]

[MJML](https://mjml.io/) is a framework that makes it easy to create responsive emails. It compiles MJML markup to HTML.

**Install:** `npm install mjml`

```typescript
import { MailMessage } from "@visulima/email";
import mjml from "@visulima/email/template/mjml";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome");

const mjmlTemplate = `
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>
`;

await message.view(mjml, mjmlTemplate);
```

#### MJML Options [#mjml-options]

| Option            | Type                           | Default  | Description                 |
| ----------------- | ------------------------------ | -------- | --------------------------- |
| `beautify`        | `boolean`                      | `false`  | Beautify the output HTML    |
| `minify`          | `boolean`                      | `false`  | Minify the output HTML      |
| `keepComments`    | `boolean`                      | `true`   | Keep comments in the output |
| `validationLevel` | `"strict" \| "soft" \| "skip"` | `"soft"` | Validation strictness level |
| `fonts`           | `Record<string, string>`       | -        | Custom fonts map            |

```typescript
await message.view(
    mjml,
    mjmlTemplate,
    {},
    {
        minify: true,
        validationLevel: "strict",
    },
);
```

### React Email [#react-email]

[React Email](https://react.email/) lets you build beautiful emails using React components.

**Install:** `npm install @react-email/render @react-email/components`

```typescript
import { MailMessage } from "@visulima/email";
import reactEmail from "@visulima/email/template/react-email";
import { Html, Head, Body, Text } from "@react-email/components";

const WelcomeEmail = ({ name }: { name: string }) => (
    <Html>
        <Head />
        <Body>
            <Text>Hello {name}!</Text>
        </Body>
    </Html>
);

const message = new MailMessage()
    .to("user@example.com")
    .from("sender@example.com")
    .subject("Welcome");

await message.view(reactEmail, <WelcomeEmail name="John" />);
```

#### React Email Options [#react-email-options]

| Option      | Type      | Default | Description                          |
| ----------- | --------- | ------- | ------------------------------------ |
| `plainText` | `boolean` | `false` | Render as plain text instead of HTML |
| `pretty`    | `boolean` | `false` | Pretty print the output HTML         |

### Vue Email [#vue-email]

[Vue Email](https://vuemail.net/) lets you build emails with Vue components.

**Install:** `npm install @vue-email/render @vue-email/components`

```typescript
import { MailMessage } from "@visulima/email";
import vueEmail from "@visulima/email/template/vue-email";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome");

await message.view(vueEmail, VueEmailComponent, {
    name: "John",
    company: "Acme",
});
```

#### Vue Email Options [#vue-email-options]

| Option              | Type                      | Default | Description                          |
| ------------------- | ------------------------- | ------- | ------------------------------------ |
| `plainText`         | `boolean`                 | `false` | Render as plain text instead of HTML |
| `pretty`            | `boolean`                 | `false` | Pretty print the output HTML         |
| `htmlToTextOptions` | `Record<string, unknown>` | -       | Options for HTML-to-text conversion  |

### HTML-to-Text [#html-to-text]

The HTML-to-text converter transforms HTML content into readable plain text. It is used automatically by `MailMessage` when only HTML content is provided (auto-text generation).

**Install:** `npm install html-to-text`

```typescript
import htmlToText from "@visulima/email/template/html-to-text";

const text = htmlToText("<h1>Hello World</h1><p>Welcome to our platform.</p>");
// Output: "HELLO WORLD\n\nWelcome to our platform."
```

#### HTML-to-Text Options [#html-to-text-options]

| Option             | Type              | Default | Description                              |
| ------------------ | ----------------- | ------- | ---------------------------------------- |
| `wordwrap`         | `number \| false` | `80`    | Word wrap limit (false to disable)       |
| `preserveNewlines` | `boolean`         | `false` | Preserve newlines in output              |
| `longWordSplit`    | `object`          | -       | Options for handling long words          |
| `selectors`        | `object[]`        | -       | Custom selectors for formatting elements |

### Liquid [#liquid]

[LiquidJS](https://liquidjs.com/) is the Shopify templating language, with tags, filters, and control flow.

**Install:** `npm install liquidjs`

```typescript
import { MailMessage } from "@visulima/email";
import liquid from "@visulima/email/template/liquid";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome");

await message.view(liquid, "{% if vip %}VIP {% endif %}Hello {{ name | upcase }}!", {
    name: "ada",
    vip: true,
});
```

The render function accepts an options object that is forwarded to the LiquidJS `Liquid` constructor as the third argument.

### JSX Email [#jsx-email]

[jsx-email](https://jsx.email/) renders email components with a Preact-compatible runtime.

**Install:** `npm install jsx-email`

```typescript
import jsxEmail from "@visulima/email/template/jsx-email";
import { Text } from "jsx-email";

const html = await jsxEmail(<Text>Hello jsx-email</Text>);

// Pass `{ plainText: true }` as the third argument to render plain text instead.
const text = await jsxEmail(<Text>Plain body</Text>, undefined, { plainText: true });
```

### i18n (Localized Rendering) [#i18n-localized-rendering]

The i18n helper wraps **any** template engine with locale resolution: it picks the template for the requested locale, falling back to the language subtag (`en-US` → `en`) and then to a default locale.

```typescript
import { renderHandlebars } from "@visulima/email/template/handlebars";
import { createI18nRenderer, renderI18n } from "@visulima/email/template/i18n";

const templates = {
    en: "Hello {{name}}",
    de: "Hallo {{name}}",
};

// One-off render:
await renderI18n(templates, "de", renderHandlebars, { name: "Ada" }); // "Hallo Ada"

// Reusable renderer bound to an engine + default locale:
const render = createI18nRenderer(renderHandlebars, "en");

await render(templates, "fr", { name: "Cleo" }); // falls back to "en" → "Hello Cleo"
```

`resolveLocale(templates, locale, defaultLocale?)` is also exported if you only need the resolution logic. `renderI18n` throws an `EmailError` when neither the locale, its language subtag, nor the default locale has a template.

## Auto-Generated Text Content [#auto-generated-text-content]

When you use `message.view()` or set HTML content with `message.html()`, @visulima/email automatically generates a plain text version using the HTML-to-text converter. This ensures email clients that don't support HTML still display readable content.

To disable auto-text generation:

```typescript
await message.view(renderHandlebars, template, data, {
    autoText: false,
});
```

## Text-Only Templates [#text-only-templates]

Use `viewText()` for text-only template rendering:

```typescript
import { renderHandlebars } from "@visulima/email/template/handlebars";

const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome");

await message.viewText(renderHandlebars, "Hello {{name}}! Welcome to {{company}}.", {
    name: "John",
    company: "Acme Corp",
});
```

## Custom Template Engines [#custom-template-engines]

You can create custom template engines by implementing the `TemplateRenderer` type:

```typescript
import type { TemplateRenderer } from "@visulima/email";

const myRenderer: TemplateRenderer = (template, data, options) => {
    let result = template as string;

    for (const [key, value] of Object.entries(data || {})) {
        result = result.replaceAll(`\${${key}}`, String(value));
    }

    return result;
};

await message.view(myRenderer, "<h1>Hello ${name}!</h1>", {
    name: "John",
});
```


# Testing (/docs/packages/email/testing/introduction)



# Testing [#testing]

`@visulima/email/test` makes it easy to assert on email behavior without sending anything over the network. `createTestEmail()` gives you a ready `Mail` instance wired to an in-memory mock provider, plus helpers to inspect, wait on, and reset the captured outbox. A set of Vitest matchers (`toHaveSentTo`, `toHaveSentWithSubject`, and more) lets you write expressive assertions over what was sent.

```typescript
import { createTestEmail, registerEmailMatchers } from "@visulima/email/test";
```

## createTestEmail [#createtestemail]

`createTestEmail()` returns a test harness backed by the in-memory mock provider. Nothing leaves the process — every message is captured for assertion.

```typescript
const email = createTestEmail();
// email.mail   -> a ready Mail instance, used exactly like a real one
// email.sent() -> captured entries, oldest first
// email.reset()-> clears the captured outbox
// email.waitFor(predicate, options) -> resolves with the first matching entry
```

### Returned Harness [#returned-harness]

| Member                         | Description                                                                             |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `mail`                         | A `Mail` instance wired to the mock provider. Use it exactly like a real one.           |
| `sent()`                       | Returns the captured messages, oldest first.                                            |
| `reset()`                      | Removes all captured messages.                                                          |
| `waitFor(predicate, options?)` | Resolves with the first captured message matching `predicate`, polling until `timeout`. |

`waitFor` accepts an options object with `timeout` (ms, default `1000`) and `interval` (ms, default `10`). It is useful when the send happens asynchronously — for example, after a queue worker processes a job:

```typescript
const email = createTestEmail();

void someBackgroundJob(email.mail);

const message = await email.waitFor((entry) => entry.options.subject === "Welcome", {
    timeout: 2000,
    interval: 20,
});
```

## Vitest Matchers [#vitest-matchers]

`registerEmailMatchers(expect)` extends Vitest's `expect` with email-specific matchers. The raw matcher map is also exported as `emailMatchers` for manual use.

| Matcher                                         | Description                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| `toHaveSentTo(address)`                         | Asserts a message was sent to `address` (To, Cc, or Bcc; case-insensitive).           |
| `toHaveSentWithSubject(stringOrRegExp)`         | Asserts a message's subject equals a string or matches a `RegExp`.                    |
| `toHaveSentWithAttachment(filename?)`           | Asserts a message carried an attachment, optionally with an exact filename.           |
| `toHaveSentMatching(predicateOrPartialOptions)` | Asserts a message matches a predicate over the options, or shallow-matches a partial. |

The matchers assert against a `TestEmail` harness or a raw array of captured entries.

## Recommended Setup [#recommended-setup]

Register the matchers once in your test (or a shared setup file) and add a `declare module "vitest"` augmentation so the new matchers are fully typed:

```typescript
import { beforeAll, expect } from "vitest";
import { createTestEmail, registerEmailMatchers } from "@visulima/email/test";

declare module "vitest" {
    interface Assertion<T = any> {
        toHaveSentTo(address: string): T;
        toHaveSentWithSubject(expected: string | RegExp): T;
        toHaveSentWithAttachment(filename?: string): T;
        toHaveSentMatching(matcher: Record<string, unknown> | ((options: any) => boolean)): T;
    }
    interface AsymmetricMatchersContaining {
        toHaveSentTo(address: string): void;
        toHaveSentWithSubject(expected: string | RegExp): void;
        toHaveSentWithAttachment(filename?: string): void;
        toHaveSentMatching(matcher: Record<string, unknown> | ((options: any) => boolean)): void;
    }
}

beforeAll(() => {
    registerEmailMatchers(expect);
});
```

## Writing a Test [#writing-a-test]

With the matchers registered, assert directly on the harness:

```typescript
import { beforeAll, expect, it } from "vitest";
import { createTestEmail, registerEmailMatchers } from "@visulima/email/test";

beforeAll(() => {
    registerEmailMatchers(expect);
});

it("sends a welcome email", async () => {
    const email = createTestEmail();

    await email.mail.send({
        from: { email: "sender@example.com" },
        to: { email: "user@example.com" },
        subject: "Welcome",
        html: "<h1>Welcome!</h1>",
    });

    expect(email).toHaveSentTo("user@example.com");
    expect(email).toHaveSentWithSubject("Welcome");
    expect(email).toHaveSentWithSubject(/welcome/i);
});
```

### Matching on Arbitrary Options [#matching-on-arbitrary-options]

Use `toHaveSentMatching` with a partial options object or a predicate for assertions the dedicated matchers don't cover:

```typescript
// Shallow-match a partial of the sent options.
expect(email).toHaveSentMatching({ subject: "Welcome" });

// Or pass a predicate.
expect(email).toHaveSentMatching((options) => options.to?.email === "user@example.com");
```

### Inspecting and Resetting [#inspecting-and-resetting]

`sent()` returns the raw captured entries for manual assertions, and `reset()` clears the outbox between tests:

```typescript
import { afterEach } from "vitest";

const email = createTestEmail();

afterEach(() => {
    email.reset();
});

it("captures the outbox", async () => {
    await email.mail.send({ from: { email: "a@x.com" }, to: { email: "b@x.com" }, subject: "Hi", text: "yo" });

    const captured = email.sent();
    expect(captured).toHaveLength(1);
    expect(captured[0]?.options.subject).toBe("Hi");
});
```

## Using the Matchers Manually [#using-the-matchers-manually]

If you prefer not to register the matchers globally, pass the raw `emailMatchers` map to `expect.extend(...)` yourself:

```typescript
import { expect } from "vitest";
import { emailMatchers } from "@visulima/email/test";

expect.extend(emailMatchers);
```


# Webhooks (/docs/packages/email/webhooks/introduction)



# Webhooks [#webhooks]

@visulima/email ships signature verifiers for the inbound webhooks every major provider sends — delivery, bounce, complaint, and open/click events. Each verifier lives under the `@visulima/email/webhooks` subpath and returns the same simple result shape, so you can branch on it the same way regardless of provider.

```typescript
type WebhookVerificationResult = {
    valid: boolean;
    reason?: string;
};
```

All verifiers are **synchronous** except `verifySnsMessage`, which is **async** (it may fetch a certificate over the network).

> **Always pass the RAW, unparsed request body.** Most schemes sign the exact bytes you received. Parsing JSON and re-serializing it changes whitespace and key order, which breaks verification. Read the raw body string first, then hand both the body and the request headers to the verifier.

## Standard Webhooks / Svix (`verifyStandardWebhook`) [#standard-webhooks--svix-verifystandardwebhook]

The [Standard Webhooks](https://www.standardwebhooks.com/) scheme is used by Svix and any provider built on it. The signed content is `${id}.${timestamp}.${payload}`, HMAC-SHA256'd with the (base64-decoded) secret. The `webhook-signature` header may carry several space-separated `v1,<sig>` entries; a match against any one of them passes.

```typescript
import { verifyStandardWebhook } from "@visulima/email/webhooks";

const result = verifyStandardWebhook({
    // The raw request body string, exactly as received.
    payload: rawBody,
    // A Headers instance or a plain record. Lookups are case-insensitive and accept
    // both webhook-* and svix-* names.
    headers: request.headers,
    // The signing secret — supports the whsec_-prefixed base64 form, or a raw string.
    secret: "whsec_YOUR_WEBHOOK_SECRET",
});

if (!result.valid) {
    console.warn("rejected webhook:", result.reason);
}
```

| Field        | Type                           | Description                                                                                                                     |
| ------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `payload`    | `string`                       | The raw, unparsed request body exactly as received.                                                                             |
| `headers`    | `Headers \| Record<string, …>` | Request headers. Recognizes `webhook-id`/`svix-id`, `webhook-timestamp`/`svix-timestamp`, `webhook-signature`/`svix-signature`. |
| `secret`     | `string`                       | The signing secret. Supports the `whsec_` base64 form.                                                                          |
| `tolerance?` | `number`                       | Replay window in seconds. `0` disables it. Default: `300`.                                                                      |
| `now?`       | `number`                       | Override the current time (milliseconds) — primarily for testing.                                                               |

## Resend (`verifyResendWebhook`) [#resend-verifyresendwebhook]

Resend signs webhooks with Svix, so `verifyResendWebhook` is an alias of `verifyStandardWebhook`. It accepts the `svix-*` headers Resend sends.

```typescript
import { verifyResendWebhook } from "@visulima/email/webhooks";

const result = verifyResendWebhook({
    payload: rawBody,
    headers: request.headers, // svix-id, svix-timestamp, svix-signature
    secret: process.env.RESEND_WEBHOOK_SECRET!, // whsec_...
});
```

## Mailgun (`verifyMailgunWebhook`) [#mailgun-verifymailgunwebhook]

Mailgun nests `timestamp`, `token`, and `signature` under a `signature` object in the webhook JSON body. The signature is `HMAC-SHA256(key = signingKey, message = timestamp + token)`, sent as a hex digest.

```typescript
import { verifyMailgunWebhook } from "@visulima/email/webhooks";

const body = await request.json();

const result = verifyMailgunWebhook({
    // Your Mailgun HTTP webhook signing key (Settings → Webhooks).
    signingKey: process.env.MAILGUN_WEBHOOK_SIGNING_KEY!,
    timestamp: body.signature.timestamp,
    token: body.signature.token,
    signature: body.signature.signature,
});

if (result.valid) {
    // handle the event payload at body["event-data"]
}
```

| Field        | Type               | Description                                                |
| ------------ | ------------------ | ---------------------------------------------------------- |
| `signingKey` | `string`           | Your Mailgun HTTP webhook signing key.                     |
| `timestamp`  | `number \| string` | From `signature.timestamp` (unix seconds).                 |
| `token`      | `string`           | From `signature.token`.                                    |
| `signature`  | `string`           | The hex HMAC from `signature.signature`.                   |
| `tolerance?` | `number`           | Replay window in seconds. `0` disables it. Default: `300`. |
| `now?`       | `number`           | Override the current time (milliseconds), for testing.     |

## SendGrid (`verifySendGridWebhook`) [#sendgrid-verifysendgridwebhook]

SendGrid's Event Webhook uses an **ECDSA** (prime256v1) signature over `timestamp + payload`, and rejects stale requests to prevent replay. The signature and timestamp arrive in the `X-Twilio-Email-Event-Webhook-Signature` and `X-Twilio-Email-Event-Webhook-Timestamp` headers.

```typescript
import { verifySendGridWebhook } from "@visulima/email/webhooks";

const result = verifySendGridWebhook({
    payload: rawBody,
    // The verification key from SendGrid's Event Webhook settings.
    // Either the base64 DER (SPKI) string SendGrid shows, or a full PEM block.
    publicKey: process.env.SENDGRID_WEBHOOK_PUBLIC_KEY!,
    signature: request.headers["x-twilio-email-event-webhook-signature"],
    timestamp: request.headers["x-twilio-email-event-webhook-timestamp"],
});
```

| Field        | Type     | Description                                                    |
| ------------ | -------- | -------------------------------------------------------------- |
| `payload`    | `string` | The raw, unparsed request body.                                |
| `publicKey`  | `string` | The SendGrid verification key — base64 DER (SPKI) or PEM.      |
| `signature`  | `string` | `X-Twilio-Email-Event-Webhook-Signature` (base64 DER ECDSA).   |
| `timestamp`  | `string` | `X-Twilio-Email-Event-Webhook-Timestamp` (unix epoch seconds). |
| `tolerance?` | `number` | Replay window in seconds. `0` disables it. Default: `300`.     |
| `now?`       | `number` | Override the current time (milliseconds), for testing.         |

This verifier throws an `EmailError` when the supplied public key cannot be parsed.

## Postmark (`verifyPostmarkWebhook`) [#postmark-verifypostmarkwebhook]

Postmark does **not** sign webhook payloads. Instead it supports HTTP Basic Auth credentials embedded in the webhook URL (plus IP allow-listing). This verifier validates the incoming `Authorization` header against the username/password you configured.

```typescript
import { verifyPostmarkWebhook } from "@visulima/email/webhooks";

const result = verifyPostmarkWebhook({
    authorization: request.headers.authorization, // e.g. "Basic dXNlcjpwYXNz"
    username: process.env.POSTMARK_WEBHOOK_USER!,
    password: process.env.POSTMARK_WEBHOOK_PASS!,
});
```

| Field           | Type                  | Description                                          |
| --------------- | --------------------- | ---------------------------------------------------- |
| `authorization` | `string \| undefined` | The incoming `Authorization` header value.           |
| `username`      | `string`              | The username configured on the Postmark webhook URL. |
| `password`      | `string`              | The password configured on the Postmark webhook URL. |

## AWS SES / SNS (`verifySnsMessage`) [#aws-ses--sns-verifysnsmessage]

AWS SES delivers events (deliveries, bounces, complaints) wrapped in **SNS notifications**, which are signed with RSA. `verifySnsMessage` is **async**: it fetches the signing certificate referenced by the message's `SigningCertURL`, then verifies the signature.

The default certificate fetcher only accepts `https://sns.<region>.amazonaws.com` URLs (and the `.cn` China partition). In tests, inject a `certificateResolver` to avoid network access.

```typescript
import { verifySnsMessage } from "@visulima/email/webhooks";

const message = await request.json(); // the SNS envelope

const result = await verifySnsMessage(message);

if (result.valid) {
    // For SES notifications, the SES event lives in JSON.parse(message.Message)
}
```

Injecting a resolver (e.g. for tests or caching):

```typescript
const result = await verifySnsMessage(message, {
    certificateResolver: (url) => certificateCache.get(url) ?? fetchPem(url),
});
```

### `isValidSigningCertUrl` [#isvalidsigningcerturl]

The host allowlist used by the default fetcher is exposed directly, so you can pre-validate a `SigningCertURL` before doing any work:

```typescript
import { isValidSigningCertUrl } from "@visulima/email/webhooks";

isValidSigningCertUrl("https://sns.us-east-1.amazonaws.com/cert.pem"); // true
isValidSigningCertUrl("https://evil.example.com/cert.pem"); // false
```

## Putting it together: a request handler [#putting-it-together-a-request-handler]

A typical Express / Hono style handler reads the **raw** body and the headers, verifies, then branches on `result.valid`:

```typescript
import { verifyResendWebhook } from "@visulima/email/webhooks";

// Express — make sure the raw body is available (e.g. express.raw({ type: "*/*" })).
app.post("/webhooks/resend", (request, response) => {
    const rawBody = request.body.toString("utf8");

    const result = verifyResendWebhook({
        payload: rawBody,
        headers: request.headers,
        secret: process.env.RESEND_WEBHOOK_SECRET!,
    });

    if (!result.valid) {
        response.status(400).json({ error: result.reason ?? "invalid signature" });

        return;
    }

    // Safe to parse and handle now that the signature is verified.
    const event = JSON.parse(rawBody);

    // ...dispatch on event.type

    response.status(204).end();
});
```

```typescript
import { Hono } from "hono";
import { verifyResendWebhook } from "@visulima/email/webhooks";

const app = new Hono();

app.post("/webhooks/resend", async (c) => {
    const rawBody = await c.req.text(); // raw, unparsed body

    const result = verifyResendWebhook({
        payload: rawBody,
        headers: c.req.raw.headers, // a Headers instance
        secret: c.env.RESEND_WEBHOOK_SECRET,
    });

    if (!result.valid) {
        return c.json({ error: result.reason ?? "invalid signature" }, 400);
    }

    const event = JSON.parse(rawBody);

    // ...dispatch on event.type

    return c.body(null, 204);
});
```


# API (/docs/packages/email-provider-mx/api)



# API Reference [#api-reference]

## `classifyMx(mxHost: string): MxProviderInfo | undefined` [#classifymxmxhost-string-mxproviderinfo--undefined]

Classifies a single MX hostname.

**Parameters:**

* `mxHost` (string): The MX hostname (e.g. the `exchange` field of a DNS MX record)

**Returns:** `MxProviderInfo` (`{ provider, type, display }`), or `undefined` if the host is not recognized.

```typescript
classifyMx("aspmx.l.google.com");
// → { provider: "google", type: "mailbox", display: "Google Workspace" }
```

## `classifyMxRecords(records): MxProviderInfo | undefined` [#classifymxrecordsrecords-mxproviderinfo--undefined]

Classifies a set of MX records, returning the provider of the primary
(lowest-priority) recognized record.

**Parameters:**

* `records` (`{ exchange: string; priority: number }[]`): The MX records to classify

**Returns:** `MxProviderInfo | undefined`

## `isSecureEmailGateway(mxHost: string): boolean` [#issecureemailgatewaymxhost-string-boolean]

Reports whether an MX hostname belongs to a known Secure Email Gateway.

```typescript
isSecureEmailGateway("eu-smtp-inbound-1.mimecast.com"); // → true
isSecureEmailGateway("aspmx.l.google.com"); // → false
```

## Types [#types]

```typescript
type MxProviderType = "free" | "mailbox" | "seg";

interface MxProviderInfo {
    provider: string; // stable identifier, e.g. "google"
    type: MxProviderType; // "mailbox" | "free" | "seg"
    display: string; // human-friendly label, e.g. "Google Workspace"
}
```

## `MX_PROVIDERS` [#mx_providers]

The raw curated dataset is also exported as `MX_PROVIDERS` (with the `patterns`
each provider matches) for advanced use.

```typescript
import { MX_PROVIDERS } from "@visulima/email-provider-mx";
```


# Introduction (/docs/packages/email-provider-mx)



# @visulima/email-provider-mx [#visulimaemail-provider-mx]

A tiny, static, hand-curated lookup that turns an MX hostname into the mail
provider behind it. It distinguishes **mailbox hosts** (Google Workspace,
Microsoft 365, Zoho, Fastmail, Proton, Yandex), **free consumer webmail**
(Yahoo, iCloud, GMX, Mail.ru, Mail.com, Web.de), and **Secure Email Gateways /
SEGs** (Proofpoint, Mimecast, Barracuda, Cisco, Trend Micro, Sophos, Forcepoint,
Symantec/MessageLabs, Cloudflare Area 1).

There are **no network calls** — it is pure data plus suffix matching. Pair it
with your own DNS resolver (`dns.resolveMx`, a DoH client, etc.) to feed it MX
records.

## Quick Start [#quick-start]

```typescript
import { classifyMx } from "@visulima/email-provider-mx";

classifyMx("aspmx.l.google.com");
// → { provider: "google", type: "mailbox", display: "Google Workspace" }

classifyMx("mx0a-00000000.pphosted.com");
// → { provider: "proofpoint", type: "seg", display: "Proofpoint" }

classifyMx("mail.example.com");
// → undefined (unknown host)
```

## Use Cases [#use-cases]

* **Deliverability Diagnostics** - Identify the mailbox host or gateway fronting a domain
* **SEG Detection** - Flag domains protected by a Secure Email Gateway
* **Provider Analytics** - Segment recipients by mail provider
* **Enrichment** - Feed `@visulima/email-verifier` provider/SEG classification

<Cards>
  <Card title="Installation" href="/docs/packages/email-provider-mx/installation">
    Install the package
  </Card>

  <Card title="Usage" href="/docs/packages/email-provider-mx/usage">
    Learn how to classify MX records
  </Card>

  <Card title="API" href="/docs/packages/email-provider-mx/api">
    API documentation
  </Card>
</Cards>


# Installation (/docs/packages/email-provider-mx/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/email-provider-mx
```

## Import [#import]

```typescript
import { classifyMx, classifyMxRecords, isSecureEmailGateway } from "@visulima/email-provider-mx";
```

The package is ESM-only, zero-dependency, and performs no network access — pair
it with your own DNS resolver to obtain MX records.


# Usage (/docs/packages/email-provider-mx/usage)



# Usage [#usage]

## Classify a single MX host [#classify-a-single-mx-host]

```typescript
import { classifyMx } from "@visulima/email-provider-mx";

classifyMx("aspmx.l.google.com");
// → { provider: "google", type: "mailbox", display: "Google Workspace" }

classifyMx("mx0a-00000000.pphosted.com");
// → { provider: "proofpoint", type: "seg", display: "Proofpoint" }

classifyMx("mail.example.com");
// → undefined (unknown host)
```

Matching is case-insensitive, ignores a trailing dot, and only matches on a dot
boundary, so `notgoogle.com` does **not** match `google.com`. The most specific
(longest) known suffix wins, so `tenant.mail.protection.outlook.com` resolves to
Microsoft 365.

## Classify a set of MX records [#classify-a-set-of-mx-records]

Feed it the records from a DNS lookup. They are sorted by ascending priority and
the first recognized record wins — which is usually the primary MX. Secure Email
Gateways are typically published as the lowest-priority (primary) MX, so this
surfaces the gateway fronting the mailbox host.

```typescript
import { resolveMx } from "node:dns/promises";

import { classifyMxRecords } from "@visulima/email-provider-mx";

const records = await resolveMx("example.com");
// e.g. [{ exchange: "mx0a-00000000.pphosted.com", priority: 10 }, …]

classifyMxRecords(records);
// → { provider: "proofpoint", type: "seg", display: "Proofpoint" }
```

## Detect a Secure Email Gateway [#detect-a-secure-email-gateway]

```typescript
import { isSecureEmailGateway } from "@visulima/email-provider-mx";

isSecureEmailGateway("eu-smtp-inbound-1.mimecast.com"); // → true
isSecureEmailGateway("aspmx.l.google.com"); // → false
```

## A note on classification [#a-note-on-classification]

Classification is by MX host, which cannot always separate a free consumer tier
from a paid business tier on the same infrastructure. For example, consumer
Gmail (`gmail-smtp-in.l.google.com`) and Google Workspace (`aspmx.l.google.com`)
both resolve under `google.com`, so both classify as Google `mailbox`.


# API (/docs/packages/email-verifier/api)



# API Reference [#api-reference]

## `verifyEmail(email, options?): Promise<EmailVerificationReport>` [#verifyemailemail-options-promiseemailverificationreport]

The top-level orchestrator. Runs the offline checks immediately, then — unless
`offline` is set — the network checks, and aggregates everything (including the
score) into one report.

**Parameters:**

* `email` (string): The address to verify
* `options?` (`VerifyEmailOptions`): see below

**`VerifyEmailOptions`:**

| Option               | Type                      | Default | Description                                                                   |
| -------------------- | ------------------------- | ------- | ----------------------------------------------------------------------------- |
| `offline`            | `boolean`                 | `false` | Skip all network checks (overrides `checkSmtp`)                               |
| `checkSmtp`          | `boolean`                 | `true`  | Run live SMTP verification                                                    |
| `cache`              | `Cache<MxCheckResult>`    | —       | Shared cache for MX/SMTP lookups across a list                                |
| `smtp`               | `SmtpVerificationOptions` | —       | SMTP probe options (timeout, `catchAllProbes`, …)                             |
| `disposable`         | `DisposableEmailOptions`  | —       | Disposable-list overrides                                                     |
| `free`               | `FreeEmailOptions`        | —       | Free-list overrides                                                           |
| `roleCustomPrefixes` | `Iterable<string>`        | —       | Additional role-account prefixes                                              |
| `typo`               | `TypoOptions`             | —       | Typo-suggestion overrides                                                     |
| `weights`            | `Partial<ScoreWeights>`   | —       | Score weight overrides (see [Scoring](/docs/packages/email-verifier/scoring)) |

## `EmailVerificationReport` [#emailverificationreport]

```typescript
type VerificationState = "deliverable" | "risky" | "undeliverable" | "unknown";

interface EmailVerificationReport {
    email: string;
    state: VerificationState; // overall verdict
    reason: string; // human-readable explanation
    score: number; // composite 0–100

    syntaxValid: boolean;
    disposable: boolean;
    free: boolean;
    role: boolean;
    noReply: boolean;
    acceptAll: boolean; // catch-all domain
    mailboxFull: boolean;
    deferred: boolean; // greylisted / inconclusive
    secureEmailGateway: boolean;

    domain: DomainReport; // MX resolution
    smtp?: SmtpVerificationResult;
    name: NameResult; // parsed first/last/full + confidence
    character: CharacterResult;
    symbol: SymbolResult;
    tag: TagResult; // +sub-address detection
    provider?: MxProviderInfo; // classified mailbox/SEG
    didYouMean?: string; // typo suggestion
}
```

## Standalone checks [#standalone-checks]

Each is exported from the root and from its own subpath.

| Function                        | Subpath                                      | Purpose                              |
| ------------------------------- | -------------------------------------------- | ------------------------------------ |
| `validateSyntax(email)`         | `@visulima/email-verifier/checks/syntax`     | RFC-ish syntax validity              |
| `checkMxRecords(domain, opts?)` | `@visulima/email-verifier/checks/mx`         | MX (with A/AAAA fallback)            |
| `verifySmtp(email, opts?)`      | `@visulima/email-verifier/checks/smtp`       | SMTP RCPT / catch-all / mailbox-full |
| `isDisposableEmail(email)`      | `@visulima/email-verifier/checks/disposable` | Disposable domain                    |
| `isFreeEmail(email)`            | `@visulima/email-verifier/checks/free`       | Free mailbox provider                |
| `isRoleAccount` / `isNoReply`   | `@visulima/email-verifier/checks/role`       | Role / no-reply mailbox              |
| `detectTag(email)`              | `@visulima/email-verifier/checks/tag`        | `+tag` sub-addressing                |
| `analyzeCharacters(email)`      | `@visulima/email-verifier/checks/character`  | Local-part character irregularities  |
| `analyzeSymbols(email)`         | `@visulima/email-verifier/checks/symbol`     | Unicode / mixed-script analysis      |

## Enrichment [#enrichment]

| Function                                                    | Subpath                                    | Purpose                               |
| ----------------------------------------------------------- | ------------------------------------------ | ------------------------------------- |
| `enrichProvider(records)`                                   | `@visulima/email-verifier/enrich/provider` | Provider / SEG from MX                |
| `classifyMx` / `classifyMxRecords` / `isSecureEmailGateway` | `@visulima/email-verifier/enrich/provider` | Re-exported MX classification         |
| `suggestEmailTypo(email)`                                   | `@visulima/email-verifier/enrich/typo`     | Misspelled-domain suggestion          |
| `suggestDomain` / `sift3Distance`                           | `@visulima/email-verifier/enrich/typo`     | Lower-level typo helpers              |
| `parseName(email)`                                          | `@visulima/email-verifier/enrich/name`     | First / last / full name + confidence |

## Scoring [#scoring]

| Export                         | Purpose                            |
| ------------------------------ | ---------------------------------- |
| `scoreReport(input, weights?)` | Compute `{ score, state, reason }` |
| `DEFAULT_WEIGHTS`              | The default scoring weights        |

See [Scoring](/docs/packages/email-verifier/scoring) for the weight table and override examples.

## Caching [#caching]

`InMemoryCache` (implements the `Cache` interface) can be shared across calls so
repeated domains reuse MX/SMTP work:

```typescript
import { InMemoryCache, verifyEmail } from "@visulima/email-verifier";

const cache = new InMemoryCache();

await verifyEmail("a@example.com", { cache });
await verifyEmail("b@example.com", { cache }); // reuses example.com MX/SMTP
```


# Introduction (/docs/packages/email-verifier)



# @visulima/email-verifier [#visulimaemail-verifier]

`@visulima/email-verifier` validates and enriches an email address without
pulling in a mail-sending stack. It mirrors the surface of commercial APIs like
[emailable](https://emailable.com): syntax + domain + SMTP verification,
catch-all / mailbox-full / greylist handling, disposable / free / role / no-reply
detection, sub-address (tag) parsing, character & Unicode-symbol analysis,
provider & Secure-Email-Gateway classification, misspelled-domain suggestions,
name parsing, and a transparent 0–100 quality score — all aggregated into one
`EmailVerificationReport`.

> It is **mailer-free**: it does not depend on `@visulima/email`, so a
> validation-only consumer never installs the 25 provider adapters.

## Quick Start [#quick-start]

```typescript
import { verifyEmail } from "@visulima/email-verifier";

const report = await verifyEmail("john.doe@gmail.com");

report.state; // "deliverable" | "risky" | "undeliverable" | "unknown"
report.reason; // e.g. "accepted_email"
report.score; // 0–100
report.free; // true
report.provider?.display; // "Google Workspace"
report.name; // { firstName: "John", lastName: "Doe", fullName: "John Doe", confidence: "high" }
```

## Use Cases [#use-cases]

* **Signup Validation** - Block undeliverable, disposable, or role addresses at registration
* **List Hygiene** - Score and segment an existing list before a send
* **Lead Scoring** - Combine free/role/provider signals into a quality score
* **Fraud Signals** - Surface catch-all, mixed-script, and typo-domain risks

<Cards>
  <Card title="Installation" href="/docs/packages/email-verifier/installation">
    Install the package
  </Card>

  <Card title="Usage" href="/docs/packages/email-verifier/usage">
    Verify an address end-to-end or à la carte
  </Card>

  <Card title="Scoring" href="/docs/packages/email-verifier/scoring">
    Understand and override the quality score
  </Card>

  <Card title="API" href="/docs/packages/email-verifier/api">
    API documentation
  </Card>
</Cards>


# Installation (/docs/packages/email-verifier/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/email-verifier
```

## Import [#import]

The top-level orchestrator runs every check and aggregates one report:

```typescript
import { verifyEmail } from "@visulima/email-verifier";
```

Every individual check and enrichment is also exported on its own subpath, so a
bundle only includes what it imports:

```typescript
import { validateSyntax } from "@visulima/email-verifier/checks/syntax";
import { checkMxRecords } from "@visulima/email-verifier/checks/mx";
import { verifySmtp } from "@visulima/email-verifier/checks/smtp";
import { isRoleAccount, isNoReply } from "@visulima/email-verifier/checks/role";
import { enrichProvider } from "@visulima/email-verifier/enrich/provider";
import { suggestEmailTypo } from "@visulima/email-verifier/enrich/typo";
import { parseName } from "@visulima/email-verifier/enrich/name";
import { scoreReport } from "@visulima/email-verifier/score";
```

## Network caveat [#network-caveat]

SMTP verification connects to the recipient's mail server on port 25. Many
networks block outbound 25 and many servers tarpit or refuse verification
probes, so treat a `deferred` / `unknown` result as inconclusive rather than
undeliverable. Pass `{ offline: true }` to skip all network checks and produce a
syntax + heuristic-only report.


# Scoring (/docs/packages/email-verifier/scoring)



# Quality Score [#quality-score]

Every report carries a composite `score` from 0–100 produced by a **transparent
additive model**: it starts from a 100-point baseline, subtracts a penalty for
each negative signal, and adds a small bonus for a known-good provider. The
result is clamped to the 0–100 range, then mapped to the `state` / `reason`.

## Default weights [#default-weights]

```typescript
import { DEFAULT_WEIGHTS } from "@visulima/email-verifier/score";
```

| Signal           | Weight | Effect                                            |
| ---------------- | ------ | ------------------------------------------------- |
| `disposable`     | 60     | Throwaway / disposable domain                     |
| `mailboxFull`    | 40     | Mailbox over quota (452 / 552)                    |
| `mixedScripts`   | 30     | Local-part mixes Unicode scripts (homoglyph risk) |
| `acceptAll`      | 25     | Catch-all domain — existence unverifiable         |
| `noReply`        | 25     | `no-reply`-style address                          |
| `role`           | 25     | Role / shared mailbox (`info@`, `sales@`)         |
| `didYouMean`     | 20     | A likely typo domain was detected                 |
| `character`      | 15     | Irregular local-part characters                   |
| `deferred`       | 15     | Greylisted / inconclusive SMTP                    |
| `smtpUnverified` | 10     | SMTP could not confirm the mailbox                |
| `symbol`         | 10     | Unusual Unicode symbols                           |
| `free`           | 5      | Free mailbox provider                             |
| `knownProvider`  | 5      | Bonus for a recognized mailbox provider           |

## Overriding weights [#overriding-weights]

Pass `weights` (a partial override merged over the defaults) to `verifyEmail` to
tune the model to your risk appetite — e.g. treat free providers as neutral and
penalise role accounts harder:

```typescript
import { verifyEmail } from "@visulima/email-verifier";

const report = await verifyEmail("info@example.com", {
    weights: { free: 0, role: 40 },
});
```

## Scoring a report directly [#scoring-a-report-directly]

`scoreReport` is exported standalone so you can re-score an existing report (or a
hand-built `ScoreInput`) without re-running the checks:

```typescript
import { scoreReport } from "@visulima/email-verifier/score";

const { score, state, reason } = scoreReport(input, { disposable: 80 });
```


# Usage (/docs/packages/email-verifier/usage)



# Usage [#usage]

## Full verification [#full-verification]

`verifyEmail` runs the offline checks (syntax, disposable, free, role, tag,
character, symbol, name, typo) immediately, then — unless `offline` is set —
resolves the network checks (MX, SMTP, provider) and aggregates everything into
one `EmailVerificationReport`.

```typescript
import { verifyEmail } from "@visulima/email-verifier";

const report = await verifyEmail("john.doe@gmail.com");

if (report.state === "deliverable") {
    console.log(`OK (${report.score}/100), provider: ${report.provider?.display}`);
} else {
    console.log(`${report.state}: ${report.reason}`);
}
```

The report exposes every signal as a discrete flag — `disposable`, `free`,
`role`, `noReply`, `acceptAll`, `mailboxFull`, `deferred`, `secureEmailGateway`,
`syntaxValid` — plus structured `domain`, `smtp`, `name`, `character`, `symbol`,
`tag`, and `provider` sub-objects, an optional `didYouMean` typo suggestion, and
the composite `score`.

## Offline mode [#offline-mode]

Skip every network round-trip (no MX, SMTP, or provider lookup) for a fast,
deterministic, heuristic-only report — useful in tests or at form-submit time:

```typescript
const report = await verifyEmail("info@example.com", { offline: true });

report.syntaxValid; // true
report.role; // true
report.state; // "unknown" — deliverability was not probed
```

## Catch-all and SMTP options [#catch-all-and-smtp-options]

```typescript
const report = await verifyEmail("user@example.com", {
    smtp: {
        catchAllProbes: 2, // extra random RCPTs to detect accept-all
        timeout: 10_000,
    },
});

report.acceptAll; // true when the server accepts random local-parts
report.mailboxFull; // true on a 452/552 over-quota response
report.deferred; // true when greylisted (4xx) — inconclusive
```

## À la carte checks [#à-la-carte-checks]

Each check is a pure function you can call on its own:

```typescript
import { validateSyntax } from "@visulima/email-verifier/checks/syntax";
import { isRoleAccount } from "@visulima/email-verifier/checks/role";
import { suggestEmailTypo } from "@visulima/email-verifier/enrich/typo";

validateSyntax("john@gmail.com"); // true
isRoleAccount("info@acme.com"); // true
suggestEmailTypo("john@gmial.com")?.full; // "john@gmail.com"
```

## Batch verification [#batch-verification]

Pass a shared `cache` so repeated domains reuse the same MX/SMTP work across a
list:

```typescript
import { InMemoryCache, verifyEmail } from "@visulima/email-verifier";

const cache = new InMemoryCache();

const reports = await Promise.all(emails.map((email) => verifyEmail(email, { cache })));
```


# Code Frame API (/docs/packages/error/api/code-frame)



# Code Frame API [#code-frame-api]

## `codeFrame(source, location, options?)` [#codeframesource-location-options]

Generate code frame showing error location.

**Parameters:**

* `source` (string): Source code
* `location` (object): Error location
  * `start.line` (number): Start line
  * `start.column` (number): Start column
  * `end` (object, optional): End location
* `options` (object, optional):
  * `linesAbove` (number): Lines above error
  * `linesBelow` (number): Lines below error
  * `message` (string): Error message

**Returns:** Formatted code frame string

**Example:**

```typescript
const frame = codeFrame(
    source,
    {
        start: { line: 2, column: 10 },
        end: { line: 2, column: 15 },
    },
    {
        linesAbove: 2,
        linesBelow: 2,
        message: "Unexpected token",
    },
);
```


# VisulimaError API (/docs/packages/error/api/visulima-error)



# VisulimaError API [#visulimaerror-api]

## Constructor [#constructor]

```typescript
new VisulimaError(options);
```

**Options:**

* `name` (string): Error name
* `message` (string): Error message
* `cause` (Error, optional): Original error

## Properties [#properties]

### `hint: string` [#hint-string]

User-friendly hint for fixing the error.

### `cause: Error` [#cause-error]

Original error that caused this error.

## Methods [#methods]

### `getErrorCauses(error: Error): Error[]` [#geterrorcauseserror-error-error]

Get all causes in error chain.

**Example:**

```typescript
const causes = getErrorCauses(error);
```


# Code Frames (/docs/packages/error/guides/code-frames)



# Code Frames [#code-frames]

## Basic Usage [#basic-usage]

```typescript
import { codeFrame } from "@visulima/error/code-frame";

const source = `
function add(a, b) {
    return a + b;
}

const result = add(1, "2");
`.trim();

const frame = codeFrame(source, {
    start: { line: 5, column: 20 },
});

console.log(frame);
```

## With Range [#with-range]

```typescript
const frame = codeFrame(source, {
    start: { line: 5, column: 16 },
    end: { line: 5, column: 19 },
});
```

## Custom Options [#custom-options]

```typescript
const frame = codeFrame(
    source,
    {
        start: { line: 5, column: 16 },
    },
    {
        linesAbove: 3,
        linesBelow: 2,
        message: "Type mismatch",
    },
);
```


# Custom Errors (/docs/packages/error/guides/custom-errors)



# Creating Custom Errors [#creating-custom-errors]

## Basic Custom Error [#basic-custom-error]

```typescript
import { VisulimaError } from "@visulima/error";

class ValidationError extends VisulimaError {
    constructor(message: string, field?: string) {
        super({
            name: "ValidationError",
            message,
        });

        if (field) {
            this.hint = `Field '${field}' is invalid`;
        }
    }
}
```

## With Metadata [#with-metadata]

```typescript
class APIError extends VisulimaError {
    public statusCode: number;
    public endpoint: string;

    constructor(message: string, statusCode: number, endpoint: string) {
        super({
            name: "APIError",
            message,
        });

        this.statusCode = statusCode;
        this.endpoint = endpoint;
    }
}

const error = new APIError("Request failed", 500, "/api/users");
```

## Error Chains [#error-chains]

```typescript
const dbError = new Error("Connection refused");
const appError = new VisulimaError({
    name: "ApplicationError",
    message: "Failed to fetch user",
    cause: dbError,
});

throw appError;
```


# Introduction (/docs/packages/error)



# @visulima/error [#visulimaerror]

Comprehensive error handling library with enhanced error objects, stacktrace parsing, code frame generation, and AI-powered solution suggestions.

## Key Features [#key-features]

**Enhanced Errors**

* Custom error classes with hints and causes
* Nested error support with full cause chains
* Additional context and metadata

**Code Frames**

* Beautiful code frame generation
* Syntax highlighting for error locations
* Configurable line ranges

**Stacktrace Parsing**

* Parse and analyze stack traces
* Extract file locations and line numbers
* Cross-platform support

**AI Solutions** (Optional)

* AI-powered error solutions
* Context-aware suggestions
* Integrates with AI providers

## Quick Start [#quick-start]

```typescript
import { VisulimaError } from "@visulima/error";

class ValidationError extends VisulimaError {
    constructor(message: string) {
        super({
            name: "ValidationError",
            message,
        });
    }
}

const error = new ValidationError("Invalid email format");
error.hint = "Expected format: user@example.com";

throw error;
```

## Use Cases [#use-cases]

**Application Error Handling:** Enhanced errors for better debugging
&#x2A;*API Development:** Structured error responses
&#x2A;*CLI Tools:** User-friendly error messages with code frames
&#x2A;*Development Tools:** Error analysis and reporting

<Cards>
  <Card title="Installation" href="/docs/packages/error/installation">
    Install and set up the package
  </Card>

  <Card title="Quick Start" href="/docs/packages/error/quick-start">
    Create your first enhanced error
  </Card>

  <Card title="Guides" href="/docs/packages/error/guides/custom-errors">
    Learn about all features
  </Card>

  <Card title="API Reference">
    Complete API documentation
  </Card>
</Cards>


# Installation (/docs/packages/error/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/error
```

## Optional: AI Integration [#optional-ai-integration]

For AI-powered solution suggestions:

```bash npm2yarn
npm install ai
```

## Import [#import]

```typescript
// Main exports
import { VisulimaError, getErrorCauses } from "@visulima/error";

// Code frames
import { codeFrame } from "@visulima/error/code-frame";

// Stacktrace parsing
import { parseStacktrace } from "@visulima/error/stacktrace";

// Solutions
import { addSolution } from "@visulima/error/solution";

// AI solutions (requires 'ai' package)
import { generateAISolution } from "@visulima/error/solution/ai";
```


# Quick Start (/docs/packages/error/quick-start)



# Quick Start [#quick-start]

## Create Custom Error [#create-custom-error]

```typescript
import { VisulimaError } from "@visulima/error";

class DatabaseError extends VisulimaError {
    constructor(message: string) {
        super({
            name: "DatabaseError",
            message,
        });
    }
}

throw new DatabaseError("Connection failed");
```

## Add Hints [#add-hints]

```typescript
const error = new DatabaseError("Connection timeout");
error.hint = "Check database connection string";

throw error;
```

## Code Frame [#code-frame]

```typescript
import { codeFrame } from "@visulima/error/code-frame";

const source = "const x = 10;\nconst error = x.y;\n";
const frame = codeFrame(source, {
    start: { line: 2, column: 16 },
});

console.log(frame);
//   1 | const x = 10;
// > 2 | const error = x.y;
//     |                ^
```

## Error Causes [#error-causes]

```typescript
import { getErrorCauses } from "@visulima/error";

const rootError = new Error("Root cause");
const wrappedError = new Error("Wrapped", { cause: rootError });

const causes = getErrorCauses(wrappedError);
// Returns array of all errors in chain
```


# API (/docs/packages/error-handler/api)



# API Reference [#api-reference]

## `createErrorHandler(options?)` [#createerrorhandleroptions]

Create error handling middleware.

**Options:**

* `debug` (boolean): Show stack traces
* `log` (boolean): Enable logging
* `logger` (object): Custom logger
* `formatError` (function): Custom formatter

**Returns:** Express/Connect middleware function


# Introduction (/docs/packages/error-handler)



# @visulima/error-handler [#visulimaerror-handler]

Production-ready error handling middleware for Node.js applications with customizable error formatting, logging, and HTTP response generation.

## Key Features [#key-features]

* HTTP error responses
* Error logging integration
* Custom error formatters
* Stack trace filtering
* Production/development modes

## Quick Start [#quick-start]

```typescript
import { createErrorHandler } from "@visulima/error-handler";

const errorHandler = createErrorHandler({
    debug: process.env.NODE_ENV !== "production",
});

app.use(errorHandler);
```

<Cards>
  <Card title="Installation" href="/docs/packages/error-handler/installation">
    Install
  </Card>

  <Card title="Quick Start" href="/docs/packages/error-handler/quick-start">
    Get started
  </Card>

  <Card title="Usage" href="/docs/packages/error-handler/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/error-handler/api">
    API docs
  </Card>
</Cards>


# Installation (/docs/packages/error-handler/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/error-handler
```

## Import [#import]

```typescript
import { createErrorHandler } from "@visulima/error-handler";
```


# Quick Start (/docs/packages/error-handler/quick-start)



# Quick Start [#quick-start]

## Express/Connect [#expressconnect]

```typescript
import express from "express";
import { createErrorHandler } from "@visulima/error-handler";

const app = express();

// Your routes...

// Error handler (must be last)
app.use(
    createErrorHandler({
        debug: true,
    }),
);
```

## Custom Format [#custom-format]

```typescript
app.use(
    createErrorHandler({
        debug: true,
        formatError: (error) => ({
            error: error.message,
            code: error.statusCode || 500,
        }),
    }),
);
```


# Usage (/docs/packages/error-handler/usage)



# Usage [#usage]

## Basic Setup [#basic-setup]

```typescript
import { createErrorHandler } from "@visulima/error-handler";

const handler = createErrorHandler({
    debug: process.env.NODE_ENV !== "production",
    log: true,
});
```

## With Logger [#with-logger]

```typescript
const handler = createErrorHandler({
    debug: false,
    logger: console,
});
```

## Custom Formatter [#custom-formatter]

```typescript
const handler = createErrorHandler({
    formatError: (error, req) => ({
        message: error.message,
        path: req.url,
        timestamp: new Date().toISOString(),
    }),
});
```


# API Reference (/docs/packages/find-ai-runner/api)



# API Reference [#api-reference]

## Functions [#functions]

### `detectAllProviders(options?)` [#detectallprovidersoptions]

Returns info for all 11 supported providers, whether installed or not. Pass `{ version: false }` to skip the (slow) version probe.

```typescript
function detectAllProviders(options?: AiDetectOptions): AiProviderInfo[];
```

### `detectAllProvidersAsync(options?)` [#detectallprovidersasyncoptions]

Async/parallel variant of `detectAllProviders`.

```typescript
function detectAllProvidersAsync(options?: AiDetectOptions): Promise<AiProviderInfo[]>;
```

### `detectAvailableProviders(options?)` [#detectavailableprovidersoptions]

Returns only providers that are installed on the system.

```typescript
function detectAvailableProviders(options?: AiDetectOptions): AiProviderInfo[];
```

### `detectProvider(name, options?)` [#detectprovidername-options]

Detect a specific provider by name. Returns provider info including availability, path, version, and detection method.

```typescript
function detectProvider(name: AiProviderName, options?: AiDetectOptions): AiProviderInfo;
```

### `findRunner(preference?, options?)` [#findrunnerpreference-options]

Return the first available provider in preference order, stopping at the first hit. Version probing is opt-in via `{ version: true }`.

```typescript
function findRunner(preference?: AiProviderName[], options?: AiDetectOptions): AiProviderInfo | undefined;
```

### `buildCliArgs(name, prompt, options?)` [#buildcliargsname-prompt-options]

Build the CLI arguments array for a provider without executing. Useful for previewing or logging what command would be run. Permission-bypass flags are only added when `options.dangerous` is `true`.

```typescript
function buildCliArgs(name: AiProviderName, prompt: string, options?: AiRunOptions): string[];
```

### `runProvider(provider, prompt, options?)` [#runproviderprovider-prompt-options]

Execute a prompt against a detected provider. Uses `spawn` with stdin closed immediately for non-interactive execution. The process environment is sanitized with `NO_COLOR=1` and `FORCE_COLOR=0` for clean output. By default the provider runs with its normal safety prompts; pass `{ dangerous: true }` for permission-bypass mode.

```typescript
function runProvider(provider: AiProviderInfo, prompt: string, options?: AiRunOptions): Promise<AiRunResult>;
```

**Throws** an [`AiRunError`](#airunerror) (carrying partial output + exit metadata) if:

* the provider is not available
* the process times out (`timedOut`)
* the run is aborted via `options.signal` (`aborted`)
* the process exits with a non-zero code
* spawning the process fails

## Constants [#constants]

### `PROVIDERS` [#providers]

The full provider configuration map.

```typescript
const PROVIDERS: Record<AiProviderName, AiProviderConfig>;
```

### `PROVIDER_NAMES` [#provider_names]

All supported provider names in alphabetical order.

```typescript
const PROVIDER_NAMES: AiProviderName[];
// ["amp", "claude", "codex", "copilot", "crush", "cursor", "droid", "gemini", "kimi", "opencode", "qwen"]
```

## Types [#types]

### `AiProviderName` [#aiprovidername]

Union of all supported provider name strings.

```typescript
type AiProviderName = "amp" | "claude" | "codex" | "copilot" | "crush" | "cursor" | "droid" | "gemini" | "kimi" | "opencode" | "qwen";
```

### `AiProviderInfo` [#aiproviderinfo]

Information about a detected AI CLI provider.

```typescript
interface AiProviderInfo {
    /** Provider name. */
    name: AiProviderName;
    /** Whether the provider was found on the system. */
    available: boolean;
    /** How the provider was detected. */
    detectionMethod?: "envvar" | "which" | "known-path";
    /** Absolute path to the CLI binary. */
    path?: string;
    /** Detected version string (e.g., "1.2.3"). */
    version?: string;
}
```

### `AiProviderConfig` [#aiproviderconfig]

Configuration for an AI CLI provider.

```typescript
interface AiProviderConfig {
    /** Primary CLI command name. */
    command: string;
    /** Alternate CLI command names to try. */
    alternateCommands: string[];
    /** Environment variable that can override the CLI path. */
    envVariable: string;
    /** Default model to use if none specified. Empty string means provider-default. */
    defaultModel: string;
    /** Whether the provider accepts a max-tokens flag. */
    supportsMaxTokens: boolean;
    /** Whether the provider accepts a model-selection flag. */
    supportsModel: boolean;
    /** Builds the CLI arguments array for a given prompt and options. */
    buildArgs: (prompt: string, options: AiBuildArgsOptions) => string[];
}
```

### `AiBuildArgsOptions` [#aibuildargsoptions]

Options passed to a provider's `buildArgs` function.

```typescript
interface AiBuildArgsOptions {
    /** When true, append the provider's permission-bypass flag. */
    dangerous?: boolean;
    /** Maximum tokens in the response. */
    maxTokens: number;
    /** Resolved model id ("" means provider-default). */
    model: string;
}
```

### `AiDetectOptions` [#aidetectoptions]

Options controlling provider detection.

```typescript
interface AiDetectOptions {
    /**
     * Whether to probe each found CLI for its version banner.
     * Detection helpers default this to `true`; `findRunner` defaults it to `false`.
     */
    version?: boolean;
}
```

### `AiRunOptions` [#airunoptions]

Options for running a prompt against an AI provider.

```typescript
interface AiRunOptions {
    /** Working directory for the spawned process. */
    cwd?: string;
    /** When true, enable permission-bypass mode (adds the provider's bypass flag). */
    dangerous?: boolean;
    /** Extra environment variables, merged over `process.env`. */
    env?: Record<string, string | undefined>;
    /** Maximum tokens in the response. Defaults to 4096. */
    maxTokens?: number;
    /** Model override (e.g., "claude-opus-4-20250514"). */
    model?: string;
    /** Callback invoked with each stderr chunk as it streams in. */
    onStderr?: (chunk: string) => void;
    /** Callback invoked with each stdout chunk as it streams in. */
    onStdout?: (chunk: string) => void;
    /** AbortSignal to cancel the run; `controller.abort()` kills the child. */
    signal?: AbortSignal;
    /** Timeout in milliseconds. Defaults to 300000 (5 minutes). */
    timeoutMs?: number;
}
```

### `AiRunResult` [#airunresult]

Result from running a prompt against an AI provider.

```typescript
interface AiRunResult {
    /** Wall-clock duration of the run in milliseconds. */
    durationMs: number;
    /** Exit code of the process (null if killed by a signal). */
    exitCode: number | null;
    /** Which provider was used. */
    provider: AiProviderName;
    /** Standard error output from the CLI. */
    stderr: string;
    /** Standard output from the CLI (the AI response). */
    stdout: string;
}
```

### `AiRunError` [#airunerror]

Error thrown by `runProvider`. Carries partial output and exit metadata so callers can debug failed, timed-out, or aborted runs.

```typescript
class AiRunError extends Error {
    /** Whether the run was aborted via `options.signal`. */
    readonly aborted: boolean;
    /** Wall-clock duration before failure, in milliseconds. */
    readonly durationMs: number;
    /** Exit code (null if killed by a signal or never spawned). */
    readonly exitCode: number | null;
    /** Provider that was being run. */
    readonly provider: AiProviderName;
    /** Partial stderr captured before failure. */
    readonly stderr: string;
    /** Partial stdout captured before failure. */
    readonly stdout: string;
    /** Whether the run exceeded `timeoutMs`. */
    readonly timedOut: boolean;
}
```


# Introduction (/docs/packages/find-ai-runner)



# Find AI Runner [#find-ai-runner]

**Detect and invoke AI CLI tools installed on the system.**

`@visulima/find-ai-runner` provides a unified interface for discovering and running 11 popular AI CLI tools. It handles detection across multiple strategies, builds the correct CLI arguments for each provider, and executes prompts with configurable timeouts and models.

## Key Features [#key-features]

* **11 providers supported** — Amp, Claude, Codex, Copilot, Crush, Cursor, Droid, Gemini, Kimi, OpenCode, Qwen
* **Three detection strategies** — Environment variables, system PATH lookup, and known installation paths
* **Unified execution API** — Single `runProvider()` function works with any detected provider
* **Cross-platform** — Works on Linux, macOS, and Windows
* **Zero dependencies** — No runtime dependencies
* **TypeScript first** — Full type safety with exported types

## Quick Start [#quick-start]

```typescript
import { detectAvailableProviders, runProvider } from "@visulima/find-ai-runner";

// Find all installed AI CLI tools
const available = detectAvailableProviders();
console.log(`Found ${available.length} AI providers`);

// Run a prompt against the first available provider
const [provider] = available;

if (provider) {
    const result = await runProvider(provider, "Explain this error: Cannot read property 'foo' of undefined");
    console.log(result.stdout);
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/find-ai-runner/installation">
    Set up find-ai-runner in your project
  </Card>

  <Card title="Usage" href="/docs/packages/find-ai-runner/usage">
    Detection, execution, and configuration examples
  </Card>

  <Card title="Providers" href="/docs/packages/find-ai-runner/providers">
    Supported AI CLI tools and their configuration
  </Card>

  <Card title="API Reference" href="/docs/packages/find-ai-runner/api">
    Complete API documentation
  </Card>
</Cards>


# Installation (/docs/packages/find-ai-runner/installation)



# Installation [#installation]

## Quick Start (no install) [#quick-start-no-install]

Use directly via `npx`:

```bash
npx @visulima/find-ai-runner list
```

## Package Install [#package-install]

Install using your preferred package manager:

```bash npm2yarn
npm install @visulima/find-ai-runner
```

## Requirements [#requirements]

* **Node.js**: 20.19 or higher

## Import [#import]

```typescript
import { detectAllProviders, detectAvailableProviders, detectProvider, buildCliArgs, runProvider, PROVIDERS, PROVIDER_NAMES } from "@visulima/find-ai-runner";
```

### Type Imports [#type-imports]

```typescript
import type { AiProviderConfig, AiProviderInfo, AiProviderName, AiRunOptions, AiRunResult } from "@visulima/find-ai-runner";
```


# Providers (/docs/packages/find-ai-runner/providers)



# Supported Providers [#supported-providers]

find-ai-runner supports 11 AI CLI providers. Each provider has a primary command, optional alternate commands, and provider-specific flags for prompt execution.

## Provider Reference [#provider-reference]

| Provider | Command    | Alternates     | Env Variable    | Default Model    |
| -------- | ---------- | -------------- | --------------- | ---------------- |
| Amp      | `amp`      |                | `AMP_PATH`      | provider-default |
| Claude   | `claude`   |                | `CLAUDE_PATH`   | provider-default |
| Codex    | `codex`    | `openai-codex` | `CODEX_PATH`    | provider-default |
| Copilot  | `copilot`  |                | `COPILOT_PATH`  | provider-default |
| Crush    | `crush`    |                | `CRUSH_PATH`    | provider-default |
| Cursor   | `agent`    | `cursor`       | `CURSOR_PATH`   | provider-default |
| Droid    | `droid`    |                | `DROID_PATH`    | provider-default |
| Gemini   | `gemini`   | `gemini-cli`   | `GEMINI_PATH`   | `gemini-2.5-pro` |
| Kimi     | `kimi`     |                | `KIMI_PATH`     | provider-default |
| OpenCode | `opencode` |                | `OPENCODE_PATH` | provider-default |
| Qwen     | `qwen`     | `qwen-code`    | `QWEN_PATH`     | provider-default |

## CLI Flags Per Provider [#cli-flags-per-provider]

Each provider uses different flags to accept prompts and configure behavior.
The permission-bypass / auto-approval flag in the last column is **only added
when you opt in** with `{ dangerous: true }` (or `--dangerous` on the CLI).

| Provider | Prompt Flags (safe default)                                   | Bypass flag (opt-in via `dangerous`)         |
| -------- | ------------------------------------------------------------- | -------------------------------------------- |
| Amp      | `-x` + prompt                                                 | `--dangerously-allow-all`                    |
| Claude   | `[--model <model>] --output-format text -p`                   | `--dangerously-skip-permissions`             |
| Codex    | `exec [--model <model>]` + prompt                             | `--dangerously-bypass-approvals-and-sandbox` |
| Copilot  | `-p` + prompt `[--model <model>]`                             | `--allow-all-tools`                          |
| Crush    | `run [-m <model>]` + prompt                                   | `--yolo`                                     |
| Cursor   | `-p --output-format text [--model <m>]` + prompt              | `--force`                                    |
| Droid    | prompt + `-o text [-m <model>]`                               | `--skip-permissions-unsafe`                  |
| Gemini   | `--sandbox [--model <m>] --max-output-tokens <n> -p` + prompt | drops `--sandbox`                            |
| Kimi     | `--quiet -p` + prompt `[-m <model>]`                          | —                                            |
| OpenCode | `run` + prompt `[-m <model>]`                                 | —                                            |
| Qwen     | `-p` + prompt + `-o text [-m <model>]`                        | `--yolo`                                     |

## Provider Details [#provider-details]

> **Warning:** Permission-bypass mode is opt-in. By default every provider runs with its normal safety prompts; pass `{ dangerous: true }` (or `--dangerous` on the CLI) to add the provider's bypass flag, which grants unattended tool/file/shell access. Only use it for fully trusted prompts.

### Amp [#amp]

[Amp](https://amp.dev) CLI tool. Uses `-x` for execute mode. Bypass: `--dangerously-allow-all`.

### Claude [#claude]

[Claude Code](https://claude.com/claude-code) by Anthropic. Supports model selection and outputs plain text. Defaults to the provider-default model. Bypass: `--dangerously-skip-permissions`.

### Codex [#codex]

[OpenAI Codex CLI](https://github.com/openai/codex). Also detected as `openai-codex`. Targets the modern Rust CLI surface (`codex exec "<prompt>"`); the retired `--approval-mode`/`--max-tokens` flags are no longer emitted. Bypass: `--dangerously-bypass-approvals-and-sandbox`.

### Copilot [#copilot]

[GitHub Copilot CLI](https://github.com/github/copilot-cli). Uses `-p` for prompt mode. Bypass: `--allow-all-tools`.

### Crush [#crush]

[Crush](https://crush.dev) CLI. Uses the `run` subcommand. Bypass: `--yolo`.

### Cursor [#cursor]

[Cursor](https://cursor.com) agent mode. Primary command is `agent`, also detected as `cursor`. Bypass: `--force`.

### Droid [#droid]

[Droid](https://github.com/nicepkg/droid) CLI. Accepts positional prompts with text output. Bypass: `--skip-permissions-unsafe`.

### Gemini [#gemini]

[Google Gemini CLI](https://github.com/google-gemini/gemini-cli). Also detected as `gemini-cli`. Runs in sandbox mode (its safety boundary) with configurable max output tokens. Default model: `gemini-2.5-pro`. With `dangerous`, the `--sandbox` flag is dropped.

### Kimi [#kimi]

[Kimi](https://kimi.ai) CLI. Uses `--quiet` for clean output and `-p` for prompt mode.

### OpenCode [#opencode]

[OpenCode](https://opencode.ai) CLI. Uses the `run` subcommand. Defaults to the provider-default model.

### Qwen [#qwen]

[Qwen](https://qwen.ai) CLI. Also detected as `qwen-code`. Uses `-p` for prompt and `-o text` for text output. Bypass: `--yolo`.


# Usage (/docs/packages/find-ai-runner/usage)



# Usage [#usage]

## CLI [#cli]

Run directly with `npx` — no installation required:

```bash
# List all providers and their availability
npx @visulima/find-ai-runner list

# Output as JSON
npx @visulima/find-ai-runner list --json

# Detect a specific provider
npx @visulima/find-ai-runner detect claude

# Run a prompt against a provider
npx @visulima/find-ai-runner run claude "Explain this error"

# Run with a custom model and timeout
npx @visulima/find-ai-runner run claude "Analyze this code" --model claude-opus-4-20250514 --timeout 60000

# Preview CLI arguments without executing
npx @visulima/find-ai-runner args claude "Explain this code"
npx @visulima/find-ai-runner args claude "Explain this code" --json
```

### CLI Options [#cli-options]

| Option             | Short | Description                                       |
| ------------------ | ----- | ------------------------------------------------- |
| `--help`           | `-h`  | Show help message                                 |
| `--version`        | `-v`  | Show version                                      |
| `--json`           | `-j`  | Output as JSON                                    |
| `--model <model>`  | `-m`  | Model override (for run command)                  |
| `--max-tokens <n>` |       | Max tokens (default: 4096)                        |
| `--timeout <ms>`   | `-t`  | Timeout in ms (default: 300000)                   |
| `--dangerous`      |       | Enable permission-bypass mode (UNSAFE, see below) |

> **Warning:** `--dangerous` (or `{ dangerous: true }` in the API) adds the provider's permission-bypass / auto-approval flag, granting the agent unattended tool/file/shell access. Untrusted content in the prompt that prompt-injects the agent then runs with all safety rails off. Only use it for fully trusted prompts. Unknown flags are reported as warnings on stderr.

## Programmatic API [#programmatic-api]

## Detecting Providers [#detecting-providers]

### Detect all providers [#detect-all-providers]

Returns info for all 11 providers, whether installed or not:

```typescript
import { detectAllProviders } from "@visulima/find-ai-runner";

const all = detectAllProviders();

for (const provider of all) {
    console.log(`${provider.name}: ${provider.available ? "installed" : "not found"}`);
}
```

### Detect available providers only [#detect-available-providers-only]

Returns only providers that are installed on the system:

```typescript
import { detectAvailableProviders } from "@visulima/find-ai-runner";

const available = detectAvailableProviders();
console.log(available);
// [{ name: "claude", available: true, path: "/usr/local/bin/claude", version: "1.2.3" }, ...]
```

### Detect a specific provider [#detect-a-specific-provider]

```typescript
import { detectProvider } from "@visulima/find-ai-runner";

const claude = detectProvider("claude");

if (claude.available) {
    console.log(`Claude found at ${claude.path}, version ${claude.version}`);
    console.log(`Detection method: ${claude.detectionMethod}`); // "envvar", "which", or "known-path"
}
```

### Faster detection (parallel, skip version probe) [#faster-detection-parallel-skip-version-probe]

`detectAllProviders`/`detectProvider` cold-start each found CLI for its
`--version` banner, which can cost \~0.5-2 s per Node-based CLI. Skip it with
`{ version: false }`, and use `detectAllProvidersAsync` to probe in parallel:

```typescript
import { detectAllProvidersAsync } from "@visulima/find-ai-runner";

const providers = await detectAllProvidersAsync({ version: false });
```

### Find the first available runner [#find-the-first-available-runner]

```typescript
import { findRunner } from "@visulima/find-ai-runner";

// Prefer claude, then codex, then gemini; stops at the first installed one.
const runner = findRunner(["claude", "codex", "gemini"]);

if (runner) {
    console.log(`Using ${runner.name} at ${runner.path}`);
}
```

## Running Prompts [#running-prompts]

### Basic execution [#basic-execution]

```typescript
import { detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");

if (provider.available) {
    const result = await runProvider(provider, "Explain this error: TypeError: Cannot read property 'foo' of undefined");
    console.log(result.stdout);
    console.log(`exit ${result.exitCode} in ${result.durationMs}ms`);
}
```

### Working directory, env, cancellation, streaming, and errors [#working-directory-env-cancellation-streaming-and-errors]

```typescript
import { AiRunError, detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");
const controller = new AbortController();

if (provider.available) {
    try {
        const result = await runProvider(provider, "Review the staged changes", {
            cwd: "/path/to/repo", // point the agent at a target repo
            env: { ANTHROPIC_API_KEY: process.env.MY_KEY }, // per-run env, merged over process.env
            signal: controller.signal, // controller.abort() cancels the run
            onStdout: (chunk) => process.stdout.write(chunk), // stream progress
        });

        console.log(result.stdout);
    } catch (error) {
        if (error instanceof AiRunError) {
            // Partial output + exit metadata are preserved for debugging.
            console.error(`timedOut=${error.timedOut} aborted=${error.aborted} exit=${error.exitCode}`);
            console.error(error.stdout);
        }
    }
}
```

### Custom model and timeout [#custom-model-and-timeout]

```typescript
import { detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");

if (provider.available) {
    const result = await runProvider(provider, "Analyze this dependency update", {
        model: "claude-opus-4-20250514",
        maxTokens: 8192,
        timeoutMs: 60_000,
    });

    console.log(result.stdout);
    console.log(`Provider used: ${result.provider}`);
}
```

### Preview CLI arguments [#preview-cli-arguments]

Build the CLI arguments without executing, useful for logging or debugging:

```typescript
import { buildCliArgs } from "@visulima/find-ai-runner";

const args = buildCliArgs("claude", "Explain this code", {
    model: "claude-opus-4-20250514",
});

console.log(args);
// ["--model", "claude-opus-4-20250514", "--output-format", "text", "-p", "Explain this code"]

// With dangerous: true, the permission-bypass flag is prepended:
const unsafe = buildCliArgs("claude", "Explain this code", { dangerous: true });
// ["--dangerously-skip-permissions", "--output-format", "text", "-p", "Explain this code"]
```

## Detection Strategies [#detection-strategies]

Providers are detected using three strategies, tried in order:

1. **Environment variable** — Each provider has a dedicated env var (e.g., `CLAUDE_PATH`, `GEMINI_PATH`) that can point to the CLI binary
2. **`which`/`where` command** — Looks up the command on the system PATH
3. **Known paths** — Checks common installation directories:
   * `/opt/homebrew/bin/` (macOS Homebrew)
   * `/usr/local/bin/` (system-wide)
   * `~/.npm-global/bin/` (npm global)
   * `~/.local/bin/` (user-local)
   * `~/.cargo/bin/` (Rust/Cargo)
   * Windows: `%APPDATA%\npm\`, `%LOCALAPPDATA%\Programs\`, `%ProgramFiles%\`

## Environment Variable Overrides [#environment-variable-overrides]

Override the detected path for any provider by setting its environment variable:

```bash
export CLAUDE_PATH=/custom/path/to/claude
export GEMINI_PATH=/opt/custom/gemini
```

This is useful for:

* Using a specific version of a provider
* Testing with a mock/wrapper script
* Corporate environments with non-standard installation paths


# API Reference (/docs/packages/find-cache-dir/api)



# API Reference [#api-reference]

Complete reference for all functions in the `@visulima/find-cache-dir` package.

## Functions [#functions]

### findCacheDir [#findcachedir]

Find the cache directory asynchronously.

**Signature:**

```typescript
function findCacheDir(name: string, options?: Options): Promise<string | undefined>;
```

**Parameters:**

* `name` (`string`, required) - Application name (should match your package name)
* `options` (`Options`, optional) - Configuration options

**Returns:** `Promise<string | undefined>` - Path to cache directory, or `undefined` if not found

**Example:**

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
console.log(cacheDir);
// macOS: /Users/username/Library/Caches/my-app
// Linux: /home/username/.cache/my-app
// Windows: C:\Users\username\AppData\Local\my-app
```

***

### findCacheDirSync [#findcachedirsync]

Find the cache directory synchronously.

**Signature:**

```typescript
function findCacheDirSync(name: string, options?: Options): string | undefined;
```

**Parameters:**

* `name` (`string`, required) - Application name (should match your package name)
* `options` (`Options`, optional) - Configuration options

**Returns:** `string | undefined` - Path to cache directory, or `undefined` if not found

**Example:**

```typescript
import { findCacheDirSync } from "@visulima/find-cache-dir";

const cacheDir = findCacheDirSync("my-app");
console.log(cacheDir);
```

***

## Options [#options]

### Options Interface [#options-interface]

Configuration options for cache directory lookup.

**Type Definition:**

```typescript
interface Options {
    cwd?: string;
    create?: boolean;
    throwError?: boolean;
}
```

**Properties:**

#### cwd [#cwd]

Starting directory for searching.

* **Type:** `string`
* **Default:** `process.cwd()`
* **Description:** Directory to start searching for `package.json`

**Example:**

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", {
    cwd: "/path/to/project",
});
```

***

#### create [#create]

Create the directory if it doesn't exist.

* **Type:** `boolean`
* **Default:** `false`
* **Description:** Automatically create the cache directory

**Example:**

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", {
    create: true,
});
// Directory is guaranteed to exist
```

***

#### throwError [#throwerror]

Throw an error if cache directory not found.

* **Type:** `boolean`
* **Default:** `false`
* **Description:** Throw error instead of returning `undefined`

**Example:**

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

try {
    const cacheDir = await findCacheDir("my-app", {
        throwError: true,
    });
    console.log("Found:", cacheDir);
} catch (error) {
    console.error("Cache directory not found");
}
```

***

## Cache Directory Locations [#cache-directory-locations]

### Platform-Specific Paths [#platform-specific-paths]

The package finds platform-specific cache directories:

**macOS:**

```
~/Library/Caches/<name>
/Users/username/Library/Caches/my-app
```

**Linux:**

```
~/.cache/<name>
/home/username/.cache/my-app

# Or if XDG_CACHE_HOME is set:
$XDG_CACHE_HOME/<name>
```

**Windows:**

```
%LOCALAPPDATA%\<name>
C:\Users\username\AppData\Local\my-app

# Fallback:
%USERPROFILE%\AppData\Local\<name>
```

### Project-Local Cache [#project-local-cache]

If in a Node.js project with `node_modules`, uses:

```
<project>/node_modules/.cache/<name>
```

***

## Environment Variables [#environment-variables]

### CACHE\_DIR [#cache_dir]

Override the cache directory location:

```bash
CACHE_DIR=/tmp/custom-cache node script.js
```

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

// Will use /tmp/custom-cache/<name> if CACHE_DIR is set
const cacheDir = await findCacheDir("my-app");
```

**Use Cases:**

* Testing environments
* CI/CD pipelines
* Docker containers
* Custom deployment scenarios

***

## Return Values [#return-values]

### Success [#success]

Returns absolute path to cache directory:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
// "/Users/username/Library/Caches/my-app"
```

### Not Found (default) [#not-found-default]

Returns `undefined` if no cache directory found:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
if (cacheDir === undefined) {
    console.log("No cache directory available");
}
```

### Not Found (with throwError) [#not-found-with-throwerror]

Throws error if cache directory not found:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

try {
    const cacheDir = await findCacheDir("my-app", { throwError: true });
} catch (error) {
    console.error(error.message);
    // "Could not find cache directory"
}
```

***

## TypeScript Types [#typescript-types]

### Type Exports [#type-exports]

```typescript
import type { Options } from "@visulima/find-cache-dir";

const options: Options = {
    cwd: process.cwd(),
    create: true,
    throwError: false,
};
```

### Type Definitions [#type-definitions]

```typescript
// Function signatures
type FindCacheDir = (name: string, options?: Options) => Promise<string | undefined>;

type FindCacheDirSync = (name: string, options?: Options) => string | undefined;

// Options
interface Options {
    cwd?: string;
    create?: boolean;
    throwError?: boolean;
}
```

***

## Error Handling [#error-handling]

### Common Error Scenarios [#common-error-scenarios]

**No package.json found:**

```typescript
const cacheDir = await findCacheDir("my-app", { throwError: true });
// Error: Could not find package.json
```

**No cache directory available:**

```typescript
const cacheDir = await findCacheDir("my-app", { throwError: true });
// Error: Could not determine cache directory
```

**Permission denied:**

```typescript
const cacheDir = await findCacheDir("my-app", { create: true });
// Error: EACCES: permission denied
```

### Best Practices [#best-practices]

Handle errors gracefully:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { tmpdir } from "os";
import { join } from "path";

async function getCacheDir(name: string): Promise<string> {
    try {
        const cacheDir = await findCacheDir(name, { create: true });
        if (cacheDir) return cacheDir;
    } catch (error) {
        console.warn("Failed to find cache directory:", error);
    }

    // Fallback to temp directory
    return join(tmpdir(), name);
}
```

***

## Function Comparison [#function-comparison]

### Async vs Sync [#async-vs-sync]

| Feature            | `findCacheDir`        | `findCacheDirSync` |
| ------------------ | --------------------- | ------------------ |
| **Execution**      | Async (Promise)       | Sync (blocking)    |
| **Use Case**       | Modern async code     | Legacy sync code   |
| **Performance**    | Non-blocking          | Blocking           |
| **Error Handling** | try/catch or .catch() | try/catch          |

**When to use async:**

```typescript
// In async functions
async function build() {
    const cache = await findCacheDir("builder");
    // ...
}

// In Promise chains
findCacheDir("app").then((cache) => {
    // Use cache
});
```

**When to use sync:**

```typescript
// In synchronous initialization
const cache = findCacheDirSync("app");

// In scripts without async context
function setupCache() {
    return findCacheDirSync("tool", { create: true });
}
```

***

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/find-cache-dir/usage">
    Learn how to use the package with examples
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/find-cache-dir)



# @visulima/find-cache-dir [#visulimafind-cache-dir]

Find the standard cache directory for your application across different operating systems. Automatically locates platform-specific cache locations and creates namespaced directories for your project.

## Key Features [#key-features]

**Platform-Aware**

* macOS: `~/Library/Caches/`
* Windows: `%LOCALAPPDATA%` or `%USERPROFILE%\AppData\Local\`
* Linux: `~/.cache/` or `$XDG_CACHE_HOME`

**Flexible Options**

* Async and sync versions
* Automatic directory creation
* Custom starting directory
* Error handling controls

**Project-Scoped**

* Creates `node_modules/.cache/your-app` structure
* Follows Node.js caching conventions
* Isolated per-project caching

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/find-cache-dir
```

Find your cache directory:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
console.log(cacheDir);
// macOS: /Users/username/Library/Caches/my-app
// Linux: /home/username/.cache/my-app
// Windows: C:\Users\username\AppData\Local\my-app
```

## Use Cases [#use-cases]

### Cache Build Artifacts [#cache-build-artifacts]

Store compiled output for faster rebuilds:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { writeFileSync } from "fs";
import { join } from "path";

const cacheDir = await findCacheDir("my-compiler", { create: true });
const outputPath = join(cacheDir, "compiled.js");

writeFileSync(outputPath, compiledCode);
console.log(`Cached to: ${outputPath}`);
```

### Store Temporary Downloads [#store-temporary-downloads]

Cache downloaded files between runs:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { createWriteStream, existsSync } from "fs";
import { join } from "path";

async function downloadWithCache(url: string, filename: string) {
    const cacheDir = await findCacheDir("my-downloader", { create: true });
    const cachePath = join(cacheDir, filename);

    if (existsSync(cachePath)) {
        console.log("Using cached file");
        return cachePath;
    }

    // Download and cache
    const response = await fetch(url);
    const fileStream = createWriteStream(cachePath);
    // ... pipe response to file ...

    return cachePath;
}
```

### Share Cache Across Tools [#share-cache-across-tools]

Multiple tools can share a cache namespace:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

// Tool 1: Build system
const buildCache = await findCacheDir("project-tools");

// Tool 2: Test runner (shares same cache)
const testCache = await findCacheDir("project-tools");

console.log(buildCache === testCache); // true
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/find-cache-dir/installation">
    Learn how to install and import the package
  </Card>

  <Card title="Usage Guide" href="/docs/packages/find-cache-dir/usage">
    Explore async/sync usage and options
  </Card>

  <Card title="API Reference" href="/docs/packages/find-cache-dir/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package is designed for Node.js environments:

* **Node.js:** ≥22.13 ≤25.x
* **Browsers:** Not applicable (filesystem operations)
* **Deno/Bun:** Compatible with filesystem APIs


# Installation (/docs/packages/find-cache-dir/installation)





# Installation [#installation]

Install the package using your preferred package manager:

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/find-cache-dir `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/find-cache-dir `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/find-cache-dir `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/find-cache-dir `
  </Tab>
</Tabs>

## Import Methods [#import-methods]

### ESM (Recommended) [#esm-recommended]

Import async and sync versions:

```typescript
import { findCacheDir, findCacheDirSync } from "@visulima/find-cache-dir";

// Async
const cacheDir = await findCacheDir("my-app");

// Sync
const cacheDirSync = findCacheDirSync("my-app");
```

### CommonJS [#commonjs]

For CommonJS environments:

```javascript
const { findCacheDir, findCacheDirSync } = require("@visulima/find-cache-dir");

const cacheDir = findCacheDir("my-app");
```

## Requirements [#requirements]

* **Node.js:** ≥22.13 ≤25.x
* **Filesystem access:** Read/write permissions for cache directories
* **TypeScript:** ≥5.0 (optional, for type definitions)

## Verify Installation [#verify-installation]

Test the installation:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("test-app");
console.log(`Cache directory: ${cacheDir}`);
```

You should see a path to your system's cache directory!

## TypeScript Support [#typescript-support]

The package includes full TypeScript type definitions:

```typescript
import { findCacheDir, findCacheDirSync } from "@visulima/find-cache-dir";
import type { Options } from "@visulima/find-cache-dir";

const options: Options = {
    cwd: process.cwd(),
    create: true,
    throwError: false,
};

const cacheDir: string = await findCacheDir("my-app", options);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/find-cache-dir/usage">
    Learn how to use async/sync versions and options
  </Card>

  <Card title="API Reference" href="/docs/packages/find-cache-dir/api">
    Explore the complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/find-cache-dir/usage)



# Usage Guide [#usage-guide]

Learn how to find and use cache directories in your applications.

## Basic Usage [#basic-usage]

### Async Version [#async-version]

Use the async version in modern async/await code:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
console.log(cacheDir);
// macOS: /Users/username/Library/Caches/my-app
// Linux: /home/username/.cache/my-app
// Windows: C:\Users\username\AppData\Local\my-app
```

### Sync Version [#sync-version]

Use the sync version when you need immediate results:

```typescript
import { findCacheDirSync } from "@visulima/find-cache-dir";

const cacheDir = findCacheDirSync("my-app");
console.log(cacheDir);
```

## Options [#options]

### Create Directory Automatically [#create-directory-automatically]

Create the cache directory if it doesn't exist:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", { create: true });
// Directory is created if it doesn't exist
```

### Custom Starting Directory [#custom-starting-directory]

Specify where to start searching for `package.json`:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", {
    cwd: "/path/to/project",
});
```

### Error Handling [#error-handling]

Control error throwing behavior:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

try {
    const cacheDir = await findCacheDir("my-app", {
        throwError: true,
    });
} catch (error) {
    console.error("Cache directory not found:", error);
}
```

Without `throwError`, returns `undefined` if not found:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
if (cacheDir) {
    console.log("Found:", cacheDir);
} else {
    console.log("No cache directory found");
}
```

## Real-World Examples [#real-world-examples]

### Cache Compiled Code [#cache-compiled-code]

Store compilation results for faster rebuilds:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { writeFileSync, readFileSync, existsSync } from "fs";
import { join } from "path";
import { createHash } from "crypto";

async function compileWithCache(sourceFile: string): Promise<string> {
    const cacheDir = await findCacheDir("my-compiler", { create: true });
    const source = readFileSync(sourceFile, "utf-8");
    const hash = createHash("md5").update(source).digest("hex");
    const cachePath = join(cacheDir, `${hash}.js`);

    if (existsSync(cachePath)) {
        console.log("Using cached compilation");
        return readFileSync(cachePath, "utf-8");
    }

    console.log("Compiling...");
    const compiled = await compile(source);

    writeFileSync(cachePath, compiled);
    return compiled;
}
```

### Package Manager Cache [#package-manager-cache]

Implement a package cache system:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { join } from "path";
import { createWriteStream, createReadStream } from "fs";
import { pipeline } from "stream/promises";

class PackageCache {
    private cacheDir: string | undefined;

    async init() {
        this.cacheDir = await findCacheDir("my-package-manager", {
            create: true,
        });
    }

    async cachePackage(name: string, version: string, stream: NodeJS.ReadableStream) {
        if (!this.cacheDir) throw new Error("Cache not initialized");

        const cachePath = join(this.cacheDir, `${name}@${version}.tgz`);
        await pipeline(stream, createWriteStream(cachePath));
    }

    getCachedPackage(name: string, version: string): NodeJS.ReadableStream | null {
        if (!this.cacheDir) return null;

        const cachePath = join(this.cacheDir, `${name}@${version}.tgz`);
        try {
            return createReadStream(cachePath);
        } catch {
            return null;
        }
    }
}
```

### Development Server Cache [#development-server-cache]

Cache development server state:

```typescript
import { findCacheDirSync } from "@visulima/find-cache-dir";
import { writeFileSync, readFileSync, existsSync } from "fs";
import { join } from "path";

class DevServerState {
    private stateFile: string;

    constructor(projectName: string) {
        const cacheDir = findCacheDirSync(projectName, { create: true });
        if (!cacheDir) throw new Error("Could not create cache directory");
        this.stateFile = join(cacheDir, "dev-server-state.json");
    }

    save(state: Record<string, unknown>) {
        writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
    }

    load(): Record<string, unknown> | null {
        if (!existsSync(this.stateFile)) return null;
        return JSON.parse(readFileSync(this.stateFile, "utf-8"));
    }
}

// Usage
const state = new DevServerState("my-dev-server");
state.save({ port: 3000, lastUsed: Date.now() });

const loaded = state.load();
console.log("Previous state:", loaded);
```

## Environment Variables [#environment-variables]

### Override Cache Directory [#override-cache-directory]

For testing, override with `CACHE_DIR` environment variable:

```bash
CACHE_DIR=/tmp/test-cache node my-script.js
```

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

// Will use /tmp/test-cache if CACHE_DIR is set
const cacheDir = await findCacheDir("my-app");
```

## Platform-Specific Behavior [#platform-specific-behavior]

### macOS [#macos]

Cache stored in `~/Library/Caches/`:

```
/Users/username/Library/Caches/my-app/
```

### Linux [#linux]

Cache stored in `~/.cache/` or `$XDG_CACHE_HOME`:

```
/home/username/.cache/my-app/
```

### Windows [#windows]

Cache stored in `%LOCALAPPDATA%`:

```
C:\Users\username\AppData\Local\my-app\
```

## Best Practices [#best-practices]

### Name Consistency [#name-consistency]

Use your package name from `package.json`:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { readFileSync } from "fs";

const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
const cacheDir = await findCacheDir(pkg.name, { create: true });
```

### Error Handling [#error-handling-1]

Always handle potential undefined results:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");

if (!cacheDir) {
    console.warn("No cache directory available, using temp directory");
    // Fallback logic
}
```

### Cleanup Old Cache [#cleanup-old-cache]

Implement cache cleanup strategies:

```typescript
import { findCacheDir } from "@visulima/find-cache-dir";
import { readdirSync, statSync, unlinkSync } from "fs";
import { join } from "path";

async function cleanOldCache(maxAgeDays: number = 30) {
    const cacheDir = await findCacheDir("my-app");
    if (!cacheDir) return;

    const now = Date.now();
    const maxAge = maxAgeDays * 24 * 60 * 60 * 1000;

    for (const file of readdirSync(cacheDir)) {
        const filePath = join(cacheDir, file);
        const stats = statSync(filePath);

        if (now - stats.mtimeMs > maxAge) {
            unlinkSync(filePath);
            console.log(`Removed old cache file: ${file}`);
        }
    }
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/find-cache-dir/api">
    Complete API documentation
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# API Reference (/docs/packages/fmt/api)



# API Reference [#api-reference]

Complete reference for all functions and types in the `@visulima/fmt` package.

## Main Functions [#main-functions]

### format [#format]

Format a string using printf-style placeholders.

**Signature:**

```typescript
function format(fmt: string, parameters: unknown[], options?: FormatOptions): string;
```

**Parameters:**

* `fmt` (`string`, required) - Format string with placeholders (e.g., "Hello %s")
* `parameters` (`unknown[]`, required) - Array of values to substitute
* `options` (`FormatOptions`, optional) - Formatting options

**Returns:** `string` - Formatted string

**Example:**

```typescript
import { format } from "@visulima/fmt";

const result = format("Hello %s, you have %d messages", ["Alice", 5]);
console.log(result); // "Hello Alice, you have 5 messages"
```

***

### build [#build]

Build a custom format function with additional formatters.

**Signature:**

```typescript
function build(options: BuildOptions): FormatFunction;
```

**Parameters:**

* `options` (`BuildOptions`, required) - Configuration options
  * `formatters` (`Formatters`, optional) - Custom format specifiers

**Returns:** `FormatFunction` - A custom format function

**Example:**

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        t: (time) => new Date(time).toLocaleString(),
        h: (num) => `0x${num.toString(16)}`,
    },
});

const result = format("Time: %t, Hex: %h", [Date.now(), 255]);
// Time: 2/16/2026, 12:30:00 PM, Hex: 0xff
```

***

## Types [#types]

### FormatOptions [#formatoptions]

Options for the `format` function.

**Type Definition:**

```typescript
interface FormatOptions {
    stringify?: (value: unknown) => string;
}
```

**Properties:**

* `stringify` (`function`, optional) - Custom serializer for the `%j`, `%o` and `%O` placeholders (they all share one JSON code path). Defaults to a `JSON.stringify` wrapper that emits `"[Circular]"` on throw.

**Example:**

```typescript
import { format } from "@visulima/fmt";

const options = {
    stringify: (obj: unknown) => JSON.stringify(obj, null, 2),
};

const result = format("Config: %j", [{ port: 8080 }], options);
```

***

### BuildOptions [#buildoptions]

Options for the `build` function.

**Type Definition:**

```typescript
interface BuildOptions {
    formatters?: Formatters;
}
```

**Properties:**

* `formatters` (`Formatters`, optional) - Custom format specifiers

***

### Formatters [#formatters]

Custom formatter functions.

**Type Definition:**

```typescript
type Formatters = Record<string, (value: any) => string>;
```

**Description:** An object mapping single-character keys to formatter functions.

**Example:**

```typescript
const formatters: Formatters = {
    u: (url) => new URL(url).hostname,
    p: (percent) => `${(percent * 100).toFixed(2)}%`,
};
```

***

### FormatFunction [#formatfunction]

The function signature returned by `build`.

**Type Definition:**

```typescript
type FormatFunction = (fmt: string, parameters: unknown[], options?: FormatOptions) => string;
```

**Description:** Same signature as `format` but with custom formatters baked in.

***

## Format Specifiers [#format-specifiers]

### Standard Specifiers [#standard-specifiers]

| Specifier | Description          | Example                                 |
| --------- | -------------------- | --------------------------------------- |
| `%s`      | String               | `format("%s", ["hello"])` → `"hello"`   |
| `%d`      | Decimal number       | `format("%d", [42])` → `"42"`           |
| `%i`      | Integer              | `format("%i", [42.7])` → `"42"`         |
| `%f`      | Float                | `format("%f", [3.14])` → `"3.14"`       |
| `%j`      | JSON                 | `format("%j", [{a:1}])` → `'{"a":1}'`   |
| `%o`      | JSON (alias of `%j`) | `format("%o", [{a:1}])` → `'{"a":1}'`   |
| `%O`      | JSON (alias of `%j`) | `format("%O", [{a:1}])` → `'{"a":1}'`   |
| `%c`      | CSS styling          | `format("%cText%c", ["color:red", ""])` |
| `%%`      | Literal %            | `format("%%", [])` → `"%"`              |

### %s - String [#s---string]

Converts values to strings.

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("%s", [42])); // "42"
console.log(format("%s", [true])); // "true"
console.log(format("%s", [[1, 2]])); // "1,2"
console.log(format("%s", [null])); // "null"
console.log(format("%s", [undefined])); // "undefined"
console.log(format("%s", [Symbol("id")])); // "Symbol(id)"
```

**Special Cases:**

* `BigInt` is not converted to string
* `-0` remains as `-0`
* Objects are converted via `toString()`

***

### %d - Decimal Number [#d---decimal-number]

Converts values to numbers.

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("%d", [42])); // "42"
console.log(format("%d", ["123"])); // "123"
console.log(format("%d", [true])); // "1"
console.log(format("%d", [false])); // "0"
console.log(format("%d", ["abc"])); // "NaN"
console.log(format("%d", [null])); // "0"
```

**Not Supported:**

* `BigInt` values
* `Symbol` values

***

### %i - Integer [#i---integer]

Converts values to integers (truncates decimals).

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("%i", [42.7])); // "42"
console.log(format("%i", [42])); // "42"
console.log(format("%i", [-42.7])); // "-42"
console.log(format("%i", ["123.9"])); // "123"
```

***

### %f - Float [#f---float]

Converts values to floating-point numbers.

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("%f", [3.14159])); // "3.14159"
console.log(format("%f", [42])); // "42"
console.log(format("%f", ["2.5"])); // "2.5"
```

**Not Supported:**

* `Symbol` values

***

### %j - JSON [#j---json]

Serializes values as JSON.

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("%j", [{ a: 1 }])); // '{"a":1}'
console.log(format("%j", [[1, 2, 3]])); // '[1,2,3]'
console.log(format("%j", [null])); // 'null'
console.log(format("%j", [undefined])); // %j left verbatim (undefined is not consumed)
console.log(format("%j", [() => {}])); // '[Function: <anonymous>]'
console.log(format("%j", ["text"])); // "'text'" (strings are single-quoted)
```

**Circular References:**

```typescript
import { format } from "@visulima/fmt";

const obj: any = { name: "test" };
obj.self = obj;

console.log(format("%j", [obj]));
// '{"name":"test","self":"[Circular]"}'
```

***

### %o and %O - Object [#o-and-o---object]

Both `%o` and `%O` are plain aliases of `%j`: the value is serialized with
`JSON.stringify` (via `options.stringify`), exactly like `%j`. They are **not**
`util.inspect`-style. There is no inspect-style formatting, and `%O` does **not**
include non-enumerable properties — `%j`, `%o` and `%O` all share a single JSON
code path.

```typescript
import { format } from "@visulima/fmt";

const obj = { a: 1, b: 2 };
console.log(format("%o", [obj])); // '{"a":1,"b":2}'
console.log(format("%O", [obj])); // '{"a":1,"b":2}'
```

Non-enumerable properties are dropped by `JSON.stringify`, so `%O` behaves the
same as `%o` and `%j`:

```typescript
import { format } from "@visulima/fmt";

const obj = { visible: "yes" };
Object.defineProperty(obj, "hidden", {
    value: "secret",
    enumerable: false,
});

console.log(format("%o", [obj])); // '{"visible":"yes"}'
console.log(format("%O", [obj])); // '{"visible":"yes"}' (hidden is NOT included)
```

Like `%j`, primitive special cases apply: strings are single-quoted (`'text'`),
functions become `[Function: name]`, and an `undefined` argument leaves the
specifier verbatim without consuming the argument.

***

### %c - CSS Styling [#c---css-styling]

Apply CSS-like styles to terminal output.

**Supported Properties:**

* `color` - Text color
* `background-color` - Background color
* `font-weight` - `bold` or `normal`
* `font-style` - `italic` or `normal`
* `text-decoration` - `underline`, `line-through`, or `none`
* `text-decoration-color` - Color for underline/line-through
* `text-decoration-line` - Decoration type

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

// Red text
format("%cError%c", ["color: red", ""]);

// Bold green text
format("%cSuccess%c", ["color: green; font-weight: bold", ""]);

// Italic with underline
format("%cNote%c", ["font-style: italic; text-decoration: underline", ""]);

// Yellow background
format("%cWarning%c", ["background-color: yellow", ""]);
```

**Reset Styles:**

```typescript
import { format } from "@visulima/fmt";

// Empty string resets all styles
format("%cStyled%c Normal", ["color: red", ""]);
```

**Note:** Whether `%c` emits ANSI is a simple environment gate, **not** real
terminal color detection. By default styling is emitted only when
`globalThis.window === undefined` (i.e. outside a browser-like global); it does
**not** probe for `TTY`/`NO_COLOR`/ANSI support. Override with `options.colors`
(`true` forces on, `false` forces off). When emitted, `%c` always produces 24-bit
truecolor sequences with no downsampling to 256/16 colors.

***

### %% - Literal Percent [#---literal-percent]

Output a literal % character.

**Behavior:**

```typescript
import { format } from "@visulima/fmt";

console.log(format("Progress: 50%%", [])); // "Progress: 50%"
console.log(format("%%off", [])); // "%off"
```

***

## Custom Formatters [#custom-formatters]

### Creating Custom Formatters [#creating-custom-formatters]

Add your own format specifiers:

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        // Single character key
        t: (value) => new Date(value).toLocaleString(),
        u: (value) => new URL(value).hostname,
        h: (value) => `0x${value.toString(16)}`,
        p: (value) => `${(value * 100).toFixed(2)}%`,
        b: (value) => (value ? "Yes" : "No"),
    },
});

// Use them
console.log(format("Time: %t", [Date.now()]));
console.log(format("Host: %u", ["https://example.com"]));
console.log(format("Hex: %h", [255]));
console.log(format("Percent: %p", [0.75]));
console.log(format("Boolean: %b", [true]));
```

### Formatter Function Signature [#formatter-function-signature]

```typescript
type FormatterFunction = (value: any) => string;
```

**Requirements:**

* Must return a string
* Single parameter (the value to format)
* Should handle invalid input gracefully

**Example:**

```typescript
const safeFormatter = (value: unknown): string => {
    try {
        return String(value);
    } catch {
        return "[Error formatting value]";
    }
};
```

***

## Custom Stringify [#custom-stringify]

Replace the default JSON serializer:

```typescript
import { format } from "@visulima/fmt";
import safeStringify from "fast-safe-stringify";

const options = {
    stringify: safeStringify,
};

const data = {
    /* complex object */
};
const result = format("Data: %j", [data], options);
```

***

## Performance Tips [#performance-tips]

1. **Reuse built formatters:** Call `build()` once and reuse the returned function
2. **`%o`/`%O` are aliases of `%j`:** all three use the same `JSON.stringify` path, so there is no performance difference between them
3. **Use typed parameters:** TypeScript helps catch formatting errors at compile time

***

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/fmt/usage">
    Learn how to use all features with examples
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/fmt)



# @visulima/fmt [#visulimafmt]

Fast, flexible string formatting utility inspired by Node.js's `util.format`. Format strings with printf-style placeholders, add custom formatters, and even apply CSS-like styling to terminal output—all with better performance than the standard library.

## Key Features [#key-features]

**printf-Style Formatting**

* Familiar %s, %d, %i, %f placeholders
* JSON serialization with %j
* %o and %O as JSON aliases of %j (not util.inspect-style)
* Automatic type conversion

**CSS Styling Support**

* Apply terminal colors with CSS syntax
* %c placeholder for inline styles
* Supports color, background, text decoration

**Customizable**

* Build custom format functions
* Add your own format specifiers
* Custom stringify functions
* Fast and optimized

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/fmt
```

Format a string:

```typescript
import { format } from "@visulima/fmt";

const result = format("Hello %s, you have %d new messages", ["Alice", 5]);
console.log(result); // "Hello Alice, you have 5 new messages"
```

## Use Cases [#use-cases]

### Format Log Messages [#format-log-messages]

Create structured log messages with dynamic values:

```typescript
import { format } from "@visulima/fmt";

function log(level: string, message: string, ...args: unknown[]) {
    const formatted = format(message, args);
    console.log(`[${level}] ${formatted}`);
}

log("INFO", "User %s logged in from %s", "alice", "192.168.1.1");
// [INFO] User alice logged in from 192.168.1.1

log("ERROR", "Failed to connect to database: %j", { host: "localhost", port: 5432 });
// [ERROR] Failed to connect to database: {"host":"localhost","port":5432}
```

### Styled Terminal Output [#styled-terminal-output]

Add colors and styles using CSS syntax:

```typescript
import { format } from "@visulima/fmt";

const styled = format("%cSuccess!%c Operation completed in %dms", ["color: green; font-weight: bold", "", 127]);

console.log(styled);
// Outputs "Success!" in bold green, then normal text
```

### Custom Date Formatter [#custom-date-formatter]

Build a formatter with custom placeholders:

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        t: (time) => new Date(time).toLocaleString(),
        T: (time) => new Date(time).toISOString(),
    },
});

const message = format("Event occurred at %t (ISO: %T)", [Date.now(), Date.now()]);
console.log(message);
// Event occurred at 2/16/2026, 12:30:00 PM (ISO: 2026-02-16T11:30:00.000Z)
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/fmt/installation">
    Learn how to install and import the package
  </Card>

  <Card title="Usage Guide" href="/docs/packages/fmt/usage">
    Explore all format specifiers and options
  </Card>

  <Card title="API Reference" href="/docs/packages/fmt/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package works in both Node.js and browser environments:

* **Node.js:** ≥22.13 ≤25.x (full support)
* **Browsers:** Compatible with ES6+ browsers
* **Deno/Bun:** Fully compatible

Note: by default CSS styling (%c) is emitted only when `globalThis.window` is
`undefined` (i.e. outside a browser-like global). This is a plain environment
gate, not real terminal color detection; use `options.colors` to force it on or
off.


# Installation (/docs/packages/fmt/installation)





# Installation [#installation]

Install the package using your preferred package manager:

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/fmt `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/fmt `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/fmt `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/fmt `
  </Tab>
</Tabs>

## Import Methods [#import-methods]

### ESM (Recommended) [#esm-recommended]

Import the functions you need:

```typescript
import { format, build } from "@visulima/fmt";

const result = format("Hello %s", ["World"]);
```

### CommonJS [#commonjs]

For CommonJS environments:

```javascript
const { format, build } = require("@visulima/fmt");

const result = format("Hello %s", ["World"]);
```

## Requirements [#requirements]

* **Node.js:** ≥22.13 ≤25.x
* **TypeScript:** ≥5.0 (optional, for type definitions)

## Verify Installation [#verify-installation]

Test the installation with a simple format:

```typescript
import { format } from "@visulima/fmt";

const result = format("Testing %d + %d = %d", [2, 2, 4]);
console.log(result); // "Testing 2 + 2 = 4"
```

If you see the expected output, installation was successful!

## TypeScript Support [#typescript-support]

The package includes full TypeScript type definitions:

```typescript
import { format, build } from "@visulima/fmt";
import type { FormatOptions, Formatters } from "@visulima/fmt";

const options: FormatOptions = {
    stringify: JSON.stringify,
};

const result: string = format("Value: %j", [{ key: "value" }], options);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/fmt/usage">
    Learn how to use all format specifiers
  </Card>

  <Card title="API Reference" href="/docs/packages/fmt/api">
    Explore the complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/fmt/usage)



# Usage Guide [#usage-guide]

Learn how to format strings with @visulima/fmt.

## Basic Formatting [#basic-formatting]

### String Formatting [#string-formatting]

Format strings with the %s specifier:

```typescript
import { format } from "@visulima/fmt";

const result = format("Hello %s", ["World"]);
console.log(result); // "Hello World"

// Multiple values
const greeting = format("%s %s, welcome!", ["Hello", "Alice"]);
console.log(greeting); // "Hello Alice, welcome!"
```

The %s specifier converts most values to strings:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Number: %s", [42])); // "Number: 42"
console.log(format("Boolean: %s", [true])); // "Boolean: true"
console.log(format("Array: %s", [[1, 2, 3]])); // "Array: 1,2,3"
console.log(format("Null: %s", [null])); // "Null: null"
console.log(format("Undefined: %s", [undefined])); // "Undefined: undefined"
```

### Number Formatting [#number-formatting]

Use %d for decimal numbers:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Count: %d", [42])); // "Count: 42"
console.log(format("Count: %d", ["123"])); // "Count: 123" (converted)
console.log(format("Count: %d", [true])); // "Count: 1"
console.log(format("Count: %d", [false])); // "Count: 0"
console.log(format("Count: %d", ["abc"])); // "Count: NaN"
```

Use %i for integers:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Integer: %i", [42.7])); // "Integer: 42" (truncated)
console.log(format("Integer: %i", [42])); // "Integer: 42"
```

Use %f for floating-point numbers:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Float: %f", [3.14159])); // "Float: 3.14159"
console.log(format("Float: %f", [42])); // "Float: 42"
```

### JSON Formatting [#json-formatting]

Use %j to serialize objects as JSON:

```typescript
import { format } from "@visulima/fmt";

const user = { name: "Alice", age: 30 };
console.log(format("User: %j", [user]));
// User: {"name":"Alice","age":30}

const config = { host: "localhost", port: 8080 };
console.log(format("Config: %j", [config]));
// Config: {"host":"localhost","port":8080}
```

Handles circular references:

```typescript
import { format } from "@visulima/fmt";

const obj: any = { name: "circular" };
obj.self = obj;

console.log(format("Object: %j", [obj]));
// Object: {"name":"circular","self":"[Circular]"}
```

### Object Serialization [#object-serialization]

`%o` and `%O` are plain aliases of `%j` — they serialize with `JSON.stringify`,
**not** `util.inspect`. There is no inspect-style output:

```typescript
import { format } from "@visulima/fmt";

const user = { name: "Alice", age: 30 };
console.log(format("User: %o", [user]));
// User: {"name":"Alice","age":30}
```

`%O` does **not** include non-enumerable properties — `JSON.stringify` drops
them, so `%O` behaves identically to `%o` and `%j`:

```typescript
import { format } from "@visulima/fmt";

const obj = { visible: "yes" };
Object.defineProperty(obj, "hidden", {
    value: "secret",
    enumerable: false,
});

console.log(format("Basic: %o", [obj]));
// Basic: {"visible":"yes"}

console.log(format("Detailed: %O", [obj]));
// Detailed: {"visible":"yes"} (hidden is NOT included)
```

## CSS Styling [#css-styling]

### Add Colors and Styles [#add-colors-and-styles]

Use %c to apply CSS-like styles to terminal output:

```typescript
import { format } from "@visulima/fmt";

const styled = format("%cError:%c Something went wrong", [
    "color: red; font-weight: bold",
    "", // Reset styles
]);

console.log(styled);
// "Error:" in bold red, then normal text
```

Multiple styled segments:

```typescript
import { format } from "@visulima/fmt";

const message = format("%cSuccess%c The operation %ccompleted%c in %d ms", ["color: green; font-weight: bold", "", "font-style: italic", "", 127]);

console.log(message);
```

### Supported CSS Properties [#supported-css-properties]

The %c formatter supports these CSS properties:

* `color` - Text color (e.g., "red", "#ff0000", "rgb(255,0,0)")
* `background-color` - Background color
* `font-weight` - bold text
* `font-style` - italic text
* `text-decoration` - underline, line-through
* `text-decoration-color` - Color for decoration
* `text-decoration-line` - Type of decoration

```typescript
import { format } from "@visulima/fmt";

const examples = [
    format("%cRed text%c", ["color: red", ""]),
    format("%cBold text%c", ["font-weight: bold", ""]),
    format("%cItalic text%c", ["font-style: italic", ""]),
    format("%cUnderline%c", ["text-decoration: underline", ""]),
    format("%cBackground%c", ["background-color: yellow", ""]),
];

examples.forEach((ex) => console.log(ex));
```

## Custom Formatters [#custom-formatters]

### Build Custom Format Function [#build-custom-format-function]

Create a format function with your own placeholders:

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        t: (time) => new Date(time).toLocaleString(),
        h: (hex) => `0x${hex.toString(16)}`,
        p: (percent) => `${(percent * 100).toFixed(2)}%`,
    },
});

console.log(format("Event at %t", [Date.now()]));
// Event at 2/16/2026, 12:30:00 PM

console.log(format("Value: %h", [255]));
// Value: 0xff

console.log(format("Complete: %p", [0.75]));
// Complete: 75.00%
```

### Combine Standard and Custom Formatters [#combine-standard-and-custom-formatters]

Custom formatters work alongside standard ones:

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        u: (url) => new URL(url).hostname,
    },
});

const message = format("Connecting to %u on port %d", ["https://example.com:8080/path", 8080]);

console.log(message);
// Connecting to example.com on port 8080
```

## Custom Stringify [#custom-stringify]

### Use Custom Serializer [#use-custom-serializer]

Replace the default JSON serializer:

```typescript
import { format } from "@visulima/fmt";

const options = {
    stringify: (obj: unknown) => {
        if (typeof obj === "object" && obj !== null) {
            return `<Object with ${Object.keys(obj).length} keys>`;
        }
        return String(obj);
    },
};

const data = { name: "Alice", age: 30, email: "alice@example.com" };
console.log(format("User: %j", [data], options));
// User: <Object with 3 keys>
```

### Use fast-safe-stringify [#use-fast-safe-stringify]

For better performance and circular reference handling:

```typescript
import { format } from "@visulima/fmt";
import stringify from "fast-safe-stringify";

const options = { stringify };

const circular: any = { name: "circular" };
circular.self = circular;

console.log(format("Data: %j", [circular], options));
// Uses fast-safe-stringify for better performance
```

## Special Cases [#special-cases]

### Literal Percent Sign [#literal-percent-sign]

Use %% to output a literal %:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Progress: %d%%", [75]));
// Progress: 75%

console.log(format("Discount: %%off", []));
// Discount: %off
```

### Missing Arguments [#missing-arguments]

Extra placeholders remain unchanged:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Hello %s %s", ["World"]));
// Hello World %s

console.log(format("%d + %d = %d", [2, 2]));
// 2 + 2 = %d
```

### Extra Arguments [#extra-arguments]

Extra arguments are appended:

```typescript
import { format } from "@visulima/fmt";

console.log(format("Hello %s", ["World", "Extra", "Args"]));
// Hello World Extra Args
```

## Real-World Examples [#real-world-examples]

### Structured Logging [#structured-logging]

Create a logger with formatted output:

```typescript
import { format } from "@visulima/fmt";

class Logger {
    log(level: string, message: string, ...args: unknown[]) {
        const timestamp = new Date().toISOString();
        const formatted = format(message, args);
        console.log(`[${timestamp}] [${level}] ${formatted}`);
    }

    info(message: string, ...args: unknown[]) {
        this.log("INFO", message, ...args);
    }

    error(message: string, ...args: unknown[]) {
        this.log("ERROR", message, ...args);
    }
}

const logger = new Logger();
logger.info("User %s logged in", "alice");
logger.error("Connection failed: %j", { code: "ETIMEDOUT" });
```

### Debug Messages [#debug-messages]

Format debug output with context:

```typescript
import { format } from "@visulima/fmt";

function debug(component: string, message: string, ...args: unknown[]) {
    if (process.env.DEBUG) {
        const formatted = format(message, args);
        console.debug(`[${component}] ${formatted}`);
    }
}

debug("Database", "Executing query: %s with params %j", "SELECT * FROM users", { limit: 10 });
debug("API", "Request to %s took %dms", "/api/users", 127);
```

### Error Messages [#error-messages]

Create detailed error messages:

```typescript
import { format } from "@visulima/fmt";

class ValidationError extends Error {
    constructor(field: string, value: unknown, constraint: string) {
        const message = format("Validation failed for field '%s': value %j does not satisfy constraint '%s'", [field, value, constraint]);
        super(message);
        this.name = "ValidationError";
    }
}

throw new ValidationError("email", "invalid-email", "must be valid email address");
```

### Template System [#template-system]

Build a simple template system:

```typescript
import { build } from "@visulima/fmt";

const format = build({
    formatters: {
        user: (u: { name: string; email: string }) => `${u.name} <${u.email}>`,
        date: (d: number) => new Date(d).toLocaleDateString(),
        money: (amount: number) => `$${amount.toFixed(2)}`,
    },
});

const template = "Invoice for %user\nDate: %date\nAmount: %money";
const invoice = format(template, [{ name: "Alice", email: "alice@example.com" }, Date.now(), 99.95]);

console.log(invoice);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/fmt/api">
    Complete API documentation with all parameters
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# API (/docs/packages/free-email-domains/api)



# API Reference [#api-reference]

## `isFreeEmail(email: string, options?): boolean` [#isfreeemailemail-string-options-boolean]

Check if an email address is from a free email provider.

**Parameters:**

* `email` (string): Email address to check
* `options?` (`Set<string>` | `FreeEmailOptions`): Additional free domains, or an options object with `allowDomains`/`customDomains`

**Returns:** `true` if free, `false` otherwise

**Example:**

```typescript
isFreeEmail("user@gmail.com"); // true
isFreeEmail("ceo@my-company.com"); // false
```

## `isFreeDomain(domain: string, options?): boolean` [#isfreedomaindomain-string-options-boolean]

Like `isFreeEmail` but accepts a bare domain rather than a full email address.

```typescript
isFreeDomain("gmail.com"); // true
```

## `areFreeEmails(emails: string[], options?): Map<string, boolean>` [#arefreeemailsemails-string-options-mapstring-boolean]

Check multiple email addresses at once. Returns a `Map` of email to boolean.

## `extractDomain(email: string): string | undefined` [#extractdomainemail-string-string--undefined]

Returns the normalized (lowercased, trimmed) domain of an email address, or `undefined` if invalid.

## `setDomains(domains: ReadonlyArray<string>): void` [#setdomainsdomains-readonlyarraystring-void]

Inject the free-domain list explicitly, bypassing the Node filesystem loader (edge/browser/bundled runtimes).

## `preload(): Promise<void>` [#preload-promisevoid]

Eagerly load the built-in list so the first check does not stall the event loop.

## `isListLoaded(): boolean` [#islistloaded-boolean]

Returns `true` once the built-in list is loaded; `false` if it has not been accessed yet or failed to load.

## `./domains` subpath [#domains-subpath]

Array of all known free email provider domains.

```typescript
import domains from "@visulima/free-email-domains/domains" with { type: "json" };

console.log(domains.length);
// 8000+
```


# Introduction (/docs/packages/free-email-domains)



# @visulima/free-email-domains [#visulimafree-email-domains]

Detect addresses from free email service providers using a comprehensive, regularly-updated list of free email domains.

## Quick Start [#quick-start]

```typescript
import { isFreeEmail } from "@visulima/free-email-domains";

isFreeEmail("user@gmail.com");
// true (free provider)

isFreeEmail("ceo@my-company.com");
// false (custom/corporate)
```

## Use Cases [#use-cases]

* **Lead Scoring** - Flag free-provider signups for sales qualification
* **Fraud Signals** - Combine with other heuristics for risk scoring
* **B2B Gating** - Require a corporate email for business features
* **Data Quality** - Segment users by email provider type

<Cards>
  <Card title="Installation" href="/docs/packages/free-email-domains/installation">
    Install the package
  </Card>

  <Card title="Usage" href="/docs/packages/free-email-domains/usage">
    Learn how to detect free providers
  </Card>

  <Card title="API" href="/docs/packages/free-email-domains/api">
    API documentation
  </Card>
</Cards>


# Installation (/docs/packages/free-email-domains/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/free-email-domains
```

## Import [#import]

```typescript
import { isFreeEmail, isFreeDomain, areFreeEmails } from "@visulima/free-email-domains";
```

The raw, sorted domain array is available from the `./domains` subpath:

```typescript
import domains from "@visulima/free-email-domains/domains" with { type: "json" };
```


# Usage (/docs/packages/free-email-domains/usage)



# Usage [#usage]

## Check Free Email [#check-free-email]

```typescript
import { isFreeEmail } from "@visulima/free-email-domains";

const email = "user@gmail.com";

if (isFreeEmail(email)) {
    console.log("Free email provider detected");
} else {
    console.log("Custom/corporate email");
}
```

## Get Domain List [#get-domain-list]

```typescript
import domains from "@visulima/free-email-domains/domains" with { type: "json" };

console.log(domains);
// ["gmail.com", "outlook.com", "yahoo.com", ...]
```

## Business-Email Gating [#business-email-gating]

```typescript
import { isFreeEmail } from "@visulima/free-email-domains";

function requireBusinessEmail(email: string): boolean {
    // Check format
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
        return false;
    }

    // Reject free providers — require a corporate domain
    if (isFreeEmail(email)) {
        return false;
    }

    return true;
}
```


# API Reference (/docs/packages/fs/api)



# API Reference [#api-reference]

Complete API documentation for **@visulima/fs**.

## Imports [#imports]

```typescript
// Main module
import {
    readJson,
    readJsonSync,
    writeJson,
    writeJsonSync,
    walk,
    walkSync,
    findUp,
    findUpSync,
    ensureDir,
    ensureDirSync,
    ensureFile,
    ensureFileSync,
    ensureLink,
    ensureLinkSync,
    ensureSymlink,
    ensureSymlinkSync,
    emptyDir,
    emptyDirSync,
    glob,
    globSync,
    isGlob,
    globParent,
    match,
    matcher,
} from "@visulima/fs";

// YAML (requires 'yaml' peer dependency)
import { readYaml, readYamlSync, writeYaml, writeYamlSync } from "@visulima/fs/yaml";

// Size utilities
import { getFileSize, getFileSizeSync, getCompressedSize, getCompressedSizeSync } from "@visulima/fs/size";

// EOL utilities
import { detectEOL, detectEOLSync, normalizeEOL, normalizeEOLSync } from "@visulima/fs/eol";

// Glob helpers (each is also available as a dedicated subpath for tree-shaking)
import { glob, globSync } from "@visulima/fs/glob";
import isGlob from "@visulima/fs/is-glob";
import globParent from "@visulima/fs/glob-parent";
import { match, matcher } from "@visulima/fs/match";
```

## JSON Functions [#json-functions]

### `readJson(path: string): Promise<any>` [#readjsonpath-string-promiseany]

Read and parse a JSON file.

**Parameters:**

* `path` (string): Path to JSON file

**Returns:** Promise resolving to parsed JSON data

**Example:**

```typescript
const config = await readJson("config.json");
```

***

### `readJsonSync(path: string): any` [#readjsonsyncpath-string-any]

Synchronously read and parse a JSON file.

**Parameters:**

* `path` (string): Path to JSON file

**Returns:** Parsed JSON data

**Example:**

```typescript
const packageJson = readJsonSync("package.json");
```

***

### `writeJson(path: string, data: any, options?: WriteJsonOptions): Promise<void>` [#writejsonpath-string-data-any-options-writejsonoptions-promisevoid]

Write data to a JSON file with formatting.

**Parameters:**

* `path` (string): Output file path
* `data` (any): Data to write
* `options` (WriteJsonOptions, optional): Formatting options
  * `spaces` (number): Indentation spaces (default: 2)

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await writeJson("output.json", { key: "value" }, { spaces: 2 });
```

***

### `writeJsonSync(path: string, data: any, options?: WriteJsonOptions): void` [#writejsonsyncpath-string-data-any-options-writejsonoptions-void]

Synchronously write data to a JSON file.

**Parameters:**

* `path` (string): Output file path
* `data` (any): Data to write
* `options` (WriteJsonOptions, optional): Formatting options

**Example:**

```typescript
writeJsonSync("data.json", { items: [1, 2, 3] });
```

***

## YAML Functions [#yaml-functions]

### `readYaml(path: string): Promise<any>` [#readyamlpath-string-promiseany]

Read and parse a YAML file.

**Requires:** `yaml` peer dependency

**Parameters:**

* `path` (string): Path to YAML file

**Returns:** Promise resolving to parsed YAML data

**Example:**

```typescript
const config = await readYaml("config.yml");
```

***

### `readYamlSync(path: string): any` [#readyamlsyncpath-string-any]

Synchronously read and parse a YAML file.

**Parameters:**

* `path` (string): Path to YAML file

**Returns:** Parsed YAML data

**Example:**

```typescript
const data = readYamlSync("data.yaml");
```

***

### `writeYaml(path: string, data: any): Promise<void>` [#writeyamlpath-string-data-any-promisevoid]

Write data to a YAML file.

**Parameters:**

* `path` (string): Output file path
* `data` (any): Data to write

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await writeYaml("output.yml", { name: "project" });
```

***

### `writeYamlSync(path: string, data: any): void` [#writeyamlsyncpath-string-data-any-void]

Synchronously write data to a YAML file.

**Parameters:**

* `path` (string): Output file path
* `data` (any): Data to write

**Example:**

```typescript
writeYamlSync("config.yaml", configuration);
```

***

## Directory Walking [#directory-walking]

### `walk(path: string, options?: WalkOptions): AsyncIterableIterator<WalkEntry>` [#walkpath-string-options-walkoptions-asynciterableiteratorwalkentry]

Recursively walk a directory tree.

**Parameters:**

* `path` (string): Directory to walk
* `options` (WalkOptions, optional):
  * `maxDepth` (number): Maximum depth (default: Infinity)
  * `includeFiles` (boolean): Include files (default: true)
  * `includeDirs` (boolean): Include directories (default: true)
  * `includeSymlinks` (boolean): Include symlinks (default: true)
  * `followSymlinks` (boolean): Follow symlinks (default: false)
  * `extensions` (string\[]): Filter by extensions
  * `match` (string\[] | RegExp\[]): Include patterns
  * `skip` (string\[] | RegExp\[]): Exclude patterns

**Returns:** Async iterable of WalkEntry objects

**WalkEntry Type:**

```typescript
interface WalkEntry {
    path: string;
    isFile: boolean;
    isDirectory: boolean;
    isSymlink: boolean;
}
```

**Example:**

```typescript
for await (const entry of walk("src", {
    extensions: [".ts", ".tsx"],
    skip: ["**/*.test.ts"],
})) {
    console.log(entry.path);
}
```

***

### `walkSync(path: string, options?: WalkOptions): IterableIterator<WalkEntry>` [#walksyncpath-string-options-walkoptions-iterableiteratorwalkentry]

Synchronously walk a directory tree.

**Parameters:**

* Same as `walk()`

**Returns:** Iterable of WalkEntry objects

**Example:**

```typescript
for (const entry of walkSync("src")) {
    console.log(entry.path);
}
```

***

## Finding Files [#finding-files]

### `findUp(matcher: string | string[] | FindUpMatcher, options?: FindUpOptions): Promise<string | undefined>` [#findupmatcher-string--string--findupmatcher-options-findupoptions-promisestring--undefined]

Find a file or directory by walking up parent directories.

**Parameters:**

* `matcher` (string | string\[] | Function):
  * String: Filename to find
  * Array: Multiple possible filenames
  * Function: Custom matcher `(dir: string, file: string) => boolean | Promise<boolean>`
* `options` (FindUpOptions, optional):
  * `cwd` (string): Starting directory (default: process.cwd())
  * `stopAt` (string): Stop searching at this directory
  * `type` (string): 'file' or 'directory'

**Returns:** Promise resolving to found path or undefined

**Example:**

```typescript
// Find by name
const pkg = await findUp("package.json");

// Multiple names
const config = await findUp([".config.json", "config.json"]);

// Custom matcher
const found = await findUp((dir, file) => {
    return file === "package.json";
});
```

***

### `findUpSync(matcher: string | string[] | FindUpMatcher, options?: FindUpOptions): string | undefined` [#findupsyncmatcher-string--string--findupmatcher-options-findupoptions-string--undefined]

Synchronously find a file or directory.

**Parameters:**

* Same as `findUp()`

**Returns:** Found path or undefined

**Example:**

```typescript
const gitRoot = findUpSync(".git", { type: "directory" });
```

***

## Ensuring Files and Directories [#ensuring-files-and-directories]

### `ensureDir(path: string): Promise<string>` [#ensuredirpath-string-promisestring]

Ensure directory exists, create if necessary.

**Parameters:**

* `path` (string): Directory path

**Returns:** Promise resolving to directory path

**Example:**

```typescript
await ensureDir("src/components/ui");
```

***

### `ensureDirSync(path: string): string` [#ensuredirsyncpath-string-string]

Synchronously ensure directory exists.

**Parameters:**

* `path` (string): Directory path

**Returns:** Directory path

**Example:**

```typescript
ensureDirSync("dist/assets");
```

***

### `ensureFile(path: string): Promise<void>` [#ensurefilepath-string-promisevoid]

Ensure file exists, create if necessary.

**Parameters:**

* `path` (string): File path

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await ensureFile("logs/app.log");
```

***

### `ensureFileSync(path: string): void` [#ensurefilesyncpath-string-void]

Synchronously ensure file exists.

**Parameters:**

* `path` (string): File path

**Example:**

```typescript
ensureFileSync("cache/data.txt");
```

***

### `ensureLink(srcPath: string, destPath: string): Promise<void>` [#ensurelinksrcpath-string-destpath-string-promisevoid]

Ensure hard link exists.

**Parameters:**

* `srcPath` (string): Source file path
* `destPath` (string): Destination link path

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await ensureLink("source.txt", "link.txt");
```

***

### `ensureLinkSync(srcPath: string, destPath: string): void` [#ensurelinksyncsrcpath-string-destpath-string-void]

Synchronously ensure hard link exists.

**Parameters:**

* `srcPath` (string): Source file path
* `destPath` (string): Destination link path

**Example:**

```typescript
ensureLinkSync("original.dat", "link.dat");
```

***

### `ensureSymlink(target: string, path: string, type?: "file" | "dir"): Promise<void>` [#ensuresymlinktarget-string-path-string-type-file--dir-promisevoid]

Ensure symbolic link exists.

**Parameters:**

* `target` (string): Target path
* `path` (string): Symlink path
* `type` (string, optional): 'file' or 'dir'

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await ensureSymlink("target/file.txt", "link.txt", "file");
await ensureSymlink("target/directory", "link-dir", "dir");
```

***

### `ensureSymlinkSync(target: string, path: string, type?: "file" | "dir"): void` [#ensuresymlinksynctarget-string-path-string-type-file--dir-void]

Synchronously ensure symbolic link exists.

**Parameters:**

* Same as `ensureSymlink()`

**Example:**

```typescript
ensureSymlinkSync("source.txt", "link.txt", "file");
```

***

## Directory Utilities [#directory-utilities]

### `emptyDir(path: string): Promise<boolean>` [#emptydirpath-string-promiseboolean]

Check if directory is empty.

**Parameters:**

* `path` (string): Directory path

**Returns:** Promise resolving to true if empty or doesn't exist

**Example:**

```typescript
const isEmpty = await emptyDir("temp");
```

***

### `emptyDirSync(path: string): boolean` [#emptydirsyncpath-string-boolean]

Synchronously check if directory is empty.

**Parameters:**

* `path` (string): Directory path

**Returns:** True if empty or doesn't exist

**Example:**

```typescript
if (emptyDirSync("cache")) {
    console.log("Cache is empty");
}
```

***

## Size Functions [#size-functions]

### `getFileSize(path: string): Promise<number>` [#getfilesizepath-string-promisenumber]

Get file size in bytes.

**Parameters:**

* `path` (string): File path

**Returns:** Promise resolving to size in bytes

**Example:**

```typescript
const bytes = await getFileSize("large-file.json");
console.log(`${bytes} bytes`);
```

***

### `getFileSizeSync(path: string): number` [#getfilesizesyncpath-string-number]

Synchronously get file size.

**Parameters:**

* `path` (string): File path

**Returns:** Size in bytes

**Example:**

```typescript
const size = getFileSizeSync("image.png");
```

***

### `getCompressedSize(path: string, compression: "gzip" | "brotli"): Promise<number>` [#getcompressedsizepath-string-compression-gzip--brotli-promisenumber]

Get compressed file size.

**Parameters:**

* `path` (string): File path
* `compression` (string): Compression type ('gzip' or 'brotli')

**Returns:** Promise resolving to compressed size in bytes

**Example:**

```typescript
const gzipSize = await getCompressedSize("bundle.js", "gzip");
const brotliSize = await getCompressedSize("bundle.js", "brotli");
```

***

### `getCompressedSizeSync(path: string, compression: "gzip" | "brotli"): number` [#getcompressedsizesyncpath-string-compression-gzip--brotli-number]

Synchronously get compressed file size.

**Parameters:**

* Same as `getCompressedSize()`

**Returns:** Compressed size in bytes

**Example:**

```typescript
const size = getCompressedSizeSync("file.txt", "gzip");
```

***

## EOL Functions [#eol-functions]

### `detectEOL(path: string): Promise<string>` [#detecteolpath-string-promisestring]

Detect line ending style in a file.

**Parameters:**

* `path` (string): File path

**Returns:** Promise resolving to EOL character(s): '\n', '\r\n', or '\r'

**Example:**

```typescript
const eol = await detectEOL("source.txt");
if (eol === "\r\n") {
    console.log("Windows line endings");
}
```

***

### `detectEOLSync(path: string): string` [#detecteolsyncpath-string-string]

Synchronously detect line ending style.

**Parameters:**

* `path` (string): File path

**Returns:** EOL character(s)

**Example:**

```typescript
const lineEnding = detectEOLSync("file.txt");
```

***

### `normalizeEOL(path: string, eol: string): Promise<void>` [#normalizeeolpath-string-eol-string-promisevoid]

Normalize line endings in a file.

**Parameters:**

* `path` (string): File path
* `eol` (string): Target EOL ('\n' or '\r\n')

**Returns:** Promise that resolves when complete

**Example:**

```typescript
await normalizeEOL("source.txt", "\n"); // Convert to Unix
await normalizeEOL("source.txt", "\r\n"); // Convert to Windows
```

***

### `normalizeEOLSync(path: string, eol: string): void` [#normalizeeolsyncpath-string-eol-string-void]

Synchronously normalize line endings.

**Parameters:**

* `path` (string): File path
* `eol` (string): Target EOL

**Example:**

```typescript
normalizeEOLSync("file.txt", "\n");
```

***

## Glob Matching [#glob-matching]

File matching helpers built on [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby), [`is-glob`](https://github.com/micromatch/is-glob), [`glob-parent`](https://github.com/gulpjs/glob-parent) and [`picomatch`](https://github.com/micromatch/picomatch). All four libraries are bundled into the built output, so `@visulima/fs` has no extra runtime dependencies for glob support. `tinyglobby` and `picomatch` ship with a small local patch that enables negated ignore patterns (see [`glob`](#globpatterns-string--readonly-string-options-globoptions-promisestring)).

> Attribution: portions of this section (in particular the `glob`/`globSync` signatures and the options table) are adapted from the [tinyglobby documentation](https://superchupu.dev/tinyglobby/documentation#api), © 2024 Madeline Gurriarán, distributed under the MIT License. `is-glob` © 2014–present Jon Schlinkert, `glob-parent` © 2015–present Gulp Team & contributors, `picomatch` © 2017–present Jon Schlinkert — all MIT.

### `glob(patterns: string | readonly string[], options?: GlobOptions): Promise<string[]>` [#globpatterns-string--readonly-string-options-globoptions-promisestring]

Asynchronously match files following one or more glob patterns.

**Pattern forms:**

* **Plain glob** — `src/**/*.ts`
* **Negated pattern** — `!src/**/*.spec.ts` inside `patterns` adds to the internal ignore list (same as passing it via `ignore`).
* **Negated ignore** — a leading `!` inside the `ignore` option *un-ignores* entries an earlier ignore pattern would drop, e.g. `ignore: ["dist/**", "!dist/index.d.ts"]`.

**Parameters:**

* `patterns` (string | readonly string\[]): One or more glob patterns.
* `options` (GlobOptions, optional): See [Glob Options](#glob-options).

**Returns:** Promise resolving to the list of matched paths (relative to `cwd` unless `absolute` is `true`).

**Example:**

```typescript
import { glob } from "@visulima/fs";

const scripts = await glob("src/**/*.{ts,js}", {
    cwd: process.cwd(),
    ignore: ["**/node_modules/**"],
});

// Negated ignore: drop the whole `dist/` tree except the type entry point.
const distPublic = await glob("**/*", {
    ignore: ["dist/**", "!dist/index.d.ts"],
});
```

***

### `globSync(patterns: string | readonly string[], options?: GlobOptions): string[]` [#globsyncpatterns-string--readonly-string-options-globoptions-string]

Synchronous counterpart of `glob`. Supports the same pattern forms — including negated ignores.

**Example:**

```typescript
import { globSync } from "@visulima/fs";

const tests = globSync(["**/*.test.ts", "!dist/**"]);

const keep = globSync("**/*.ts", {
    ignore: ["ignored/**", "!ignored/keep.ts"],
});
```

***

### Glob Options [#glob-options]

| Option                | Type                          | Default         | Description                                                                                                                                                                       |
| --------------------- | ----------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `absolute`            | `boolean`                     | `false`         | Return absolute paths instead of paths relative to `cwd`.                                                                                                                         |
| `braceExpansion`      | `boolean`                     | `true`          | Enable brace expansion syntax like `{a,b}` or `{1..9}`.                                                                                                                           |
| `caseSensitiveMatch`  | `boolean`                     | `true`          | Match in case-sensitive mode.                                                                                                                                                     |
| `cwd`                 | `string \| URL`               | `process.cwd()` | Working directory for the search.                                                                                                                                                 |
| `debug`               | `boolean`                     | `false`         | Log debug information (intended for development only; log format is not stable).                                                                                                  |
| `deep`                | `number`                      | `Infinity`      | Maximum directory depth to crawl.                                                                                                                                                 |
| `dot`                 | `boolean`                     | `false`         | Return dot-prefixed entries (e.g. `.gitignore`).                                                                                                                                  |
| `expandDirectories`   | `boolean`                     | `true`          | Auto-expand directory patterns. Disable when migrating from `fast-glob`.                                                                                                          |
| `extglob`             | `boolean`                     | `true`          | Enable extglobs like `+(pattern)`.                                                                                                                                                |
| `followSymbolicLinks` | `boolean`                     | `true`          | Traverse and include symbolic links. Can slightly affect performance.                                                                                                             |
| `fs`                  | `Partial<FSLike>`             | `node:fs`       | Override `node:fs` functions (useful for virtual file systems).                                                                                                                   |
| `globstar`            | `boolean`                     | `true`          | Enable `**` to match nested directories. When `false`, `**` behaves like `*`.                                                                                                     |
| `ignore`              | `string \| readonly string[]` | `[]`            | Additional patterns to exclude from the results. Entries starting with `!` *un-ignore* a path that an earlier pattern would drop, e.g. `ignore: ["dist/**", "!dist/index.d.ts"]`. |
| `onlyDirectories`     | `boolean`                     | `false`         | Return only directories. When `true`, `onlyFiles` is implicitly disabled.                                                                                                         |
| `onlyFiles`           | `boolean`                     | `true`          | Return only files.                                                                                                                                                                |
| `signal`              | `AbortSignal`                 | `undefined`     | `AbortSignal` to stop crawling the file system.                                                                                                                                   |

***

### `isGlob(value: unknown, options?: IsGlobOptions): boolean` [#isglobvalue-unknown-options-isgloboptions-boolean]

Returns `true` if the given value looks like a glob pattern (including extglobs like `@(foo|bar)`). Escaped meta characters such as `\*` are not considered globs. Non-string values always return `false`.

**Parameters:**

* `value` (unknown): The value to inspect.
* `options` (IsGlobOptions, optional):
  * `strict` (boolean): When `false`, matches more permissively — any string containing unescaped glob meta characters (`*`, `?`, `{}`, `()`, `[]`) is treated as a glob. Default: `true`.

**Example:**

```typescript
import { isGlob } from "@visulima/fs";

isGlob("src/**/*.ts"); // true
isGlob("src/index.ts"); // false
isGlob("src/\\*.ts"); // false — escaped
isGlob("!foo.js"); // true — negation
isGlob("(abc)", { strict: false }); // true
```

***

### `globParent(pattern: string, options?: GlobParentOptions): string` [#globparentpattern-string-options-globparentoptions-string]

Extracts the non-glob parent directory from a glob pattern. Useful when you need to know which directory to watch or walk for a given pattern.

**Parameters:**

* `pattern` (string): The glob pattern to inspect.
* `options` (GlobParentOptions, optional):
  * `flipBackslashes` (boolean): On Windows, flip backslashes to forward slashes before analysing. Default: `true`.

**Example:**

```typescript
import { globParent } from "@visulima/fs";

globParent("src/**/*.ts"); // "src"
globParent("foo/{a,b}/*.js"); // "foo"
globParent("foo/bar.js"); // "foo"
globParent("index.ts"); // "."
```

***

### `match(value: string | string[], pattern: string | string[], options?: MatchOptions): boolean` [#matchvalue-string--string-pattern-string--string-options-matchoptions-boolean]

Test whether a path (or any of a list of paths) matches one or more glob patterns. For repeated matches against the same pattern, prefer `matcher` to compile the pattern once.

**Example:**

```typescript
import { match } from "@visulima/fs";

match("src/index.ts", "src/**/*.ts"); // true
match("src/index.ts", ["**/*.js", "**/*.ts"]); // true
match(["a.ts", "b.js"], "**/*.ts"); // true (any value matches)
```

***

### `matcher(pattern: string | string[], options?: MatchOptions): (value: string) => boolean` [#matcherpattern-string--string-options-matchoptions-value-string--boolean]

Compile a glob pattern into a reusable single-argument predicate. The returned function accepts exactly one argument, so it is safe to pass to `Array.prototype.filter` without triggering `picomatch`'s `returnObject` parameter.

**Example:**

```typescript
import { matcher } from "@visulima/fs";

const isTs = matcher("**/*.ts");
["a.ts", "b.js", "c.ts"].filter(isTs); // ["a.ts", "c.ts"]

const isScript = matcher(["**/*.ts", "**/*.js"]);
isScript("a.css"); // false
```

`MatchOptions` is re-exported unchanged from `picomatch.PicomatchOptions` — see the [picomatch options reference](https://github.com/micromatch/picomatch#options) for the full list.

***

## TypeScript Types [#typescript-types]

```typescript
// Walk entry
interface WalkEntry {
    path: string;
    isFile: boolean;
    isDirectory: boolean;
    isSymlink: boolean;
}

// Walk options
interface WalkOptions {
    maxDepth?: number;
    includeFiles?: boolean;
    includeDirs?: boolean;
    includeSymlinks?: boolean;
    followSymlinks?: boolean;
    extensions?: string[];
    match?: (string | RegExp)[];
    skip?: (string | RegExp)[];
}

// Find up options
interface FindUpOptions {
    cwd?: string;
    stopAt?: string;
    type?: "file" | "directory";
}

// Find up matcher
type FindUpMatcher = (directory: string, file: string) => boolean | Promise<boolean>;

// Write JSON options
interface WriteJsonOptions {
    spaces?: number;
}

// Glob options (adapted from tinyglobby)
interface GlobOptions {
    absolute?: boolean;
    braceExpansion?: boolean;
    caseSensitiveMatch?: boolean;
    cwd?: string | URL;
    debug?: boolean;
    deep?: number;
    dot?: boolean;
    expandDirectories?: boolean;
    extglob?: boolean;
    followSymbolicLinks?: boolean;
    fs?: Partial<import("fdir").FSLike>;
    globstar?: boolean;
    ignore?: string | readonly string[];
    onlyDirectories?: boolean;
    onlyFiles?: boolean;
    signal?: AbortSignal;
}

interface IsGlobOptions {
    strict?: boolean;
}

interface GlobParentOptions {
    flipBackslashes?: boolean;
}

// MatchOptions === picomatch.PicomatchOptions (re-exported as-is)
```


# Introduction (/docs/packages/fs)



# @visulima/fs [#visulimafs]

Human-friendly file system utilities for Node.js. A comprehensive collection of async and sync file system operations that make working with files and directories safer and more convenient.

## Why @visulima/fs? [#why-visulimafs]

Node.js's built-in `fs&#x60; module is powerful but low-level. **@visulima/fs** provides high-level utilities that handle common patterns:

* **Safe operations** - Automatically create parent directories when needed
* **Dual APIs** - Both async and sync versions of every function
* **Type-safe** - Full TypeScript support with proper types
* **Format support** - Built-in JSON and YAML parsing/writing
* **Directory traversal** - Powerful walk and findUp utilities
* **Cross-platform** - Consistent behavior on Windows, macOS, and Linux

## Key Features [#key-features]

**Directory Walking**

* **Recursive traversal** - Walk directory trees with filtering
* **Configurable depth** - Control how deep to traverse
* **Pattern matching** - Include/exclude files by glob patterns
* **Symlink handling** - Follow or ignore symbolic links

**File Finding**

* **Find upward** - Search parent directories for files
* **Stop conditions** - Flexible search control
* **Multiple matchers** - Search by name, extension, or pattern

**Safe File Operations**

* **Ensure files** - Create files with parent directories
* **Ensure directories** - Safely create directory trees
* **Ensure links** - Create symbolic and hard links safely
* **Atomic writes** - Write files safely without corruption risk

**Format Support**

* **JSON handling** - Read and write JSON with formatting
* **YAML support** - Parse and write YAML files (optional peer dependency)
* **Automatic formatting** - Preserve indentation and style

**Utilities**

* **Empty directory check** - Determine if directory is empty
* **File size calculation** - Get size with compression support
* **EOL detection** - Detect line ending styles
* **Path utilities** - Additional path manipulation helpers

## Quick Start [#quick-start]

### Installation [#installation]

```bash npm2yarn
npm install @visulima/fs
```

### Basic Usage [#basic-usage]

```typescript
import { readJson, writeJson, emptyDir, walk, findUp } from "@visulima/fs";

// Read JSON file
const config = await readJson("config.json");

// Write JSON file (creates parent dirs automatically)
await writeJson("data/output.json", { result: "success" });

// Check if directory is empty
const isEmpty = await emptyDir("temp");

// Walk directory tree
for await (const entry of walk("src")) {
    console.log(entry.path);
}

// Find file in parent directories
const packageJson = await findUp("package.json");
```

## Use Cases [#use-cases]

### Build Tools & Scripts [#build-tools--scripts]

Safely manage build artifacts and configuration files:

```typescript
import { ensureDir, emptyDir, writeJson } from "@visulima/fs";

// Prepare build directory
await ensureDir("dist");
await emptyDir("dist");

// Write build manifest
await writeJson("dist/manifest.json", {
    version: "1.0.0",
    files: ["index.js", "styles.css"],
});
```

### Configuration Management [#configuration-management]

Read and write configuration files in multiple formats:

```typescript
import { readJson, writeJson } from "@visulima/fs";
import { readYaml, writeYaml } from "@visulima/fs/yaml";

// Read config from JSON or YAML
const config = await readJson(".config.json");
// or
const config = await readYaml(".config.yml");

// Update and save
config.updated = new Date();
await writeJson(".config.json", config);
```

### Project File Discovery [#project-file-discovery]

Find project files by walking up the directory tree:

```typescript
import { findUp } from "@visulima/fs";

// Find nearest package.json
const packagePath = await findUp("package.json");

// Find config file with multiple possible names
const configPath = await findUp([".config.json", ".config.yml", "config.json"]);

// Find with custom matcher
const gitRoot = await findUp((dir) => {
    return dir.endsWith(".git");
});
```

### Source Code Analysis [#source-code-analysis]

Process all files in a project with filtering:

```typescript
import { walk } from "@visulima/fs";

// Find all TypeScript files
const tsFiles: string[] = [];

for await (const entry of walk("src", {
    extensions: [".ts", ".tsx"],
    skip: ["**/*.test.ts", "**/node_modules/**"],
})) {
    if (entry.isFile) {
        tsFiles.push(entry.path);
    }
}
```

## Comparison with Alternatives [#comparison-with-alternatives]

### vs. Node.js `fs` [#vs-nodejs-fs]

| Feature               | @visulima/fs | Node.js fs |
| --------------------- | ------------ | ---------- |
| Ensure directories    | ✅            | ❌          |
| Safe atomic writes    | ✅            | ❌          |
| JSON read/write       | ✅            | ❌          |
| YAML support          | ✅            | ❌          |
| Directory walking     | ✅            | ❌          |
| Find up directories   | ✅            | ❌          |
| Empty directory check | ✅            | ❌          |

### vs. fs-extra [#vs-fs-extra]

| Feature           | @visulima/fs | fs-extra |
| ----------------- | ------------ | -------- |
| Modern ESM        | ✅            | ⚠️       |
| TypeScript native | ✅            | ⚠️       |
| YAML support      | ✅            | ❌        |
| Walk utilities    | ✅            | ❌        |
| Find up           | ✅            | ❌        |
| Size calculation  | ✅            | ❌        |
| EOL detection     | ✅            | ❌        |

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/fs/installation">
    Learn how to install and set up the package
  </Card>

  <Card title="Quick Start" href="/docs/packages/fs/quick-start">
    Get started with common operations in 5 minutes
  </Card>

  <Card title="Usage Guide" href="/docs/packages/fs/usage">
    Explore all file system utilities
  </Card>

  <Card title="API Reference" href="/docs/packages/fs/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

### Node.js [#nodejs]

* ✅ Node.js 22.13 - 25.x
* ✅ ESM and CommonJS support

### Operating Systems [#operating-systems]

* ✅ Windows
* ✅ macOS
* ✅ Linux
* ✅ Any POSIX-compliant OS


# Installation (/docs/packages/fs/installation)



# Installation [#installation]

## Package Manager [#package-manager]

Install **@visulima/fs** using your preferred package manager:

```bash npm2yarn
npm install @visulima/fs
```

## Optional Dependencies [#optional-dependencies]

### YAML Support [#yaml-support]

If you need to read or write YAML files, install the `yaml` peer dependency:

```bash npm2yarn
npm install yaml
```

After installing `yaml`, you can use YAML functions:

```typescript
import { readYaml, writeYaml } from "@visulima/fs/yaml";

const data = await readYaml("config.yml");
await writeYaml("output.yml", data);
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0+ (optional, for TypeScript projects)

## Import Methods [#import-methods]

### Node.js (ESM) [#nodejs-esm]

```typescript
// Main module - common file operations
import { readJson, writeJson, emptyDir, ensureDir, walk, findUp } from "@visulima/fs";

// YAML support
import { readYaml, writeYaml } from "@visulima/fs/yaml";

// Size utilities
import { getFileSize, getCompressedSize } from "@visulima/fs/size";

// EOL utilities
import { detectEOL, normalizeEOL } from "@visulima/fs/eol";

// Error types
import { FileSystemError } from "@visulima/fs/error";

// Additional utilities
import {} from /* ... */ "@visulima/fs/utils";
```

### Node.js (CommonJS) [#nodejs-commonjs]

```javascript
// Main module
const { readJson, writeJson, emptyDir, ensureDir } = require("@visulima/fs");

// YAML support
const { readYaml, writeYaml } = require("@visulima/fs/yaml");

// Size utilities
const { getFileSize } = require("@visulima/fs/size");

// EOL utilities
const { detectEOL } = require("@visulima/fs/eol");
```

### TypeScript [#typescript]

TypeScript definitions are included automatically:

```typescript
import type { WalkEntry, WalkOptions, FindUpOptions } from "@visulima/fs";

// Fully typed APIs
const entries: WalkEntry[] = [];
for await (const entry of walk("src")) {
    entries.push(entry);
}
```

## Subpath Exports [#subpath-exports]

The package provides several subpath exports for different functionality:

| Export               | Purpose                     |
| -------------------- | --------------------------- |
| `@visulima/fs`       | Core file system operations |
| `@visulima/fs/yaml`  | YAML parsing and writing    |
| `@visulima/fs/size`  | File size calculations      |
| `@visulima/fs/eol`   | End-of-line detection       |
| `@visulima/fs/error` | Error types                 |
| `@visulima/fs/utils` | Additional utilities        |

## Verification [#verification]

Verify your installation works correctly:

```typescript
import { readJson, writeJson, emptyDir } from "@visulima/fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

// Test write
const testPath = join(tmpdir(), "visulima-test.json");
await writeJson(testPath, { test: true });

// Test read
const data = await readJson(testPath);
console.log("✓ Installation successful:", data);
```

## Common Setup Patterns [#common-setup-patterns]

### In a Build Script [#in-a-build-script]

```typescript
// build.ts
import { ensureDir, emptyDir, writeJson } from "@visulima/fs";
import { readYaml } from "@visulima/fs/yaml";

// Load config
const config = await readYaml("build.config.yml");

// Prepare output directory
await ensureDir("dist");
await emptyDir("dist");

// Write manifest
await writeJson("dist/manifest.json", {
    version: config.version,
    buildTime: new Date().toISOString(),
});
```

### In a CLI Tool [#in-a-cli-tool]

```typescript
#!/usr/bin/env node
import { findUp, readJson } from "@visulima/fs";

// Find project root
const packageJsonPath = await findUp("package.json");
if (!packageJsonPath) {
    console.error("Not in a Node.js project");
    process.exit(1);
}

const packageJson = await readJson(packageJsonPath);
console.log(`Project: ${packageJson.name}@${packageJson.version}`);
```

### In a Configuration Manager [#in-a-configuration-manager]

```typescript
// config.ts
import { readJson, writeJson } from "@visulima/fs";
import { readYaml, writeYaml } from "@visulima/fs/yaml";
import { findUp } from "@visulima/fs";

export async function loadConfig() {
    // Try multiple config formats
    const jsonPath = await findUp([".config.json", "config.json"]);
    if (jsonPath) {
        return readJson(jsonPath);
    }

    const yamlPath = await findUp([".config.yml", "config.yaml"]);
    if (yamlPath) {
        return readYaml(yamlPath);
    }

    throw new Error("No configuration file found");
}
```

### In a Project Analyzer [#in-a-project-analyzer]

```typescript
// analyzer.ts
import { walk } from "@visulima/fs";
import { extname } from "node:path";

export async function analyzeProject(dir: string) {
    const stats = {
        total: 0,
        byExtension: new Map<string, number>(),
    };

    for await (const entry of walk(dir, {
        extensions: [".js", ".ts", ".jsx", ".tsx"],
        skip: ["**/node_modules/**", "**/dist/**"],
    })) {
        if (entry.isFile) {
            stats.total++;
            const ext = extname(entry.path);
            stats.byExtension.set(ext, (stats.byExtension.get(ext) || 0) + 1);
        }
    }

    return stats;
}
```

## Troubleshooting [#troubleshooting]

### Module Not Found [#module-not-found]

If you see `Cannot find module '@visulima/fs'`:

```bash npm2yarn
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

### YAML Functions Not Available [#yaml-functions-not-available]

If YAML functions throw errors:

```bash npm2yarn
# Install the yaml peer dependency
npm install yaml
```

### TypeScript Errors [#typescript-errors]

Ensure your `tsconfig.json` includes:

```json
{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true,
        "module": "ES2020",
        "target": "ES2020"
    }
}
```

### Permission Errors [#permission-errors]

If you encounter EACCES errors:

```typescript
import { ensureDir } from "@visulima/fs";

try {
    await ensureDir("/protected/path");
} catch (error) {
    if (error.code === "EACCES") {
        console.error("Permission denied");
    }
    throw error;
}
```

### Subpath Not Resolved [#subpath-not-resolved]

If subpaths like `@visulima/fs/yaml` don't work:

```bash
# Verify Node.js version (requires 22.13+)
node --version

# Update Node.js if needed
nvm install 22.13
nvm use 22.13
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Quick Start" href="/docs/packages/fs/quick-start">
    Get started with common operations
  </Card>

  <Card title="Usage Guide" href="/docs/packages/fs/usage">
    Learn about all available utilities
  </Card>

  <Card title="API Reference" href="/docs/packages/fs/api">
    Complete API documentation
  </Card>
</Cards>


# Quick Start (/docs/packages/fs/quick-start)



# Quick Start [#quick-start]

Learn the essentials of **@visulima/fs** in 5 minutes.

## Installation [#installation]

```bash npm2yarn
npm install @visulima/fs
```

## Read and Write JSON [#read-and-write-json]

The most common operations - reading and writing JSON files:

```typescript
import { readJson, readJsonSync, writeJson, writeJsonSync } from "@visulima/fs";

// Async - Read JSON
const config = await readJson("config.json");
console.log(config);

// Async - Write JSON (creates parent directories automatically)
await writeJson("data/output.json", { result: "success" }, { spaces: 2 });

// Sync versions
const data = readJsonSync("package.json");
writeJsonSync("output.json", data);
```

## Ensure Directories [#ensure-directories]

Create directories safely, including parent directories:

```typescript
import { ensureDir, ensureDirSync } from "@visulima/fs";

// Async - Creates parent directories if they don't exist
await ensureDir("src/components/ui");

// Sync version
ensureDirSync("dist/assets/images");
```

## Check Empty Directory [#check-empty-directory]

Determine if a directory is empty:

```typescript
import { emptyDir, emptyDirSync } from "@visulima/fs";

// Async
const isEmpty = await emptyDir("temp");
if (isEmpty) {
    console.log("Directory is empty");
}

// Sync version
const isEmptySync = emptyDirSync("cache");
```

## Walk Directory Trees [#walk-directory-trees]

Recursively traverse directories:

```typescript
import { walk, walkSync } from "@visulima/fs";

// Async - Walk all files
for await (const entry of walk("src")) {
    console.log(entry.path);
    // entry.isFile, entry.isDirectory, entry.isSymlink available
}

// Sync version
for (const entry of walkSync("src")) {
    if (entry.isFile) {
        console.log("File:", entry.path);
    }
}
```

### Walk with Filters [#walk-with-filters]

Filter files by extension or pattern:

```typescript
import { walk } from "@visulima/fs";

// Only TypeScript files
for await (const entry of walk("src", {
    extensions: [".ts", ".tsx"],
})) {
    console.log(entry.path);
}

// Exclude test files
for await (const entry of walk("src", {
    skip: ["**/*.test.ts", "**/node_modules/**"],
})) {
    console.log(entry.path);
}

// Include specific patterns
for await (const entry of walk("src", {
    match: ["**/components/**/*.tsx"],
})) {
    console.log(entry.path);
}
```

## Find Files Upward [#find-files-upward]

Search for files by walking up parent directories:

```typescript
import { findUp, findUpSync } from "@visulima/fs";

// Async - Find nearest package.json
const packagePath = await findUp("package.json");
console.log(packagePath); // '/project/package.json'

// Find with multiple possible names
const configPath = await findUp([".config.json", ".config.yml", "config.json"]);

// Sync version
const gitRoot = findUpSync(".git");
```

### Find with Custom Matcher [#find-with-custom-matcher]

Use a function to find directories or files:

```typescript
import { findUp } from "@visulima/fs";
import { basename } from "node:path";

// Find directory ending with specific name
const nodeModules = await findUp((dir) => {
    return basename(dir) === "node_modules";
});

// Find file with specific content
const readme = await findUp(async (dir, file) => {
    if (file === "README.md") {
        const content = await readFile(join(dir, file), "utf-8");
        return content.includes("visulima");
    }
    return false;
});
```

## Ensure Files [#ensure-files]

Create files with their parent directories:

```typescript
import { ensureFile, ensureFileSync } from "@visulima/fs";

// Async - Creates all parent directories
await ensureFile("logs/app/2024/error.log");

// Sync version
ensureFileSync("cache/temp/data.txt");
```

## Create Symbolic Links [#create-symbolic-links]

Safely create symbolic and hard links:

```typescript
import { ensureLink, ensureSymlink } from "@visulima/fs";

// Hard link
await ensureLink("source.txt", "hardlink.txt");

// Symbolic link
await ensureSymlink("target/directory", "link-to-directory", "dir");
await ensureSymlink("target/file.txt", "link-to-file.txt", "file");
```

## Read and Write YAML [#read-and-write-yaml]

Install the optional `yaml` dependency first:

```bash npm2yarn
npm install yaml
```

Then use YAML functions:

```typescript
import { readYaml, readYamlSync, writeYaml, writeYamlSync } from "@visulima/fs/yaml";

// Async - Read YAML
const config = await readYaml("config.yml");
console.log(config);

// Async - Write YAML
await writeYaml("output.yml", { name: "project", version: "1.0.0" });

// Sync versions
const data = readYamlSync("data.yaml");
writeYamlSync("output.yaml", data);
```

## File Size Utilities [#file-size-utilities]

Calculate file sizes with compression support:

```typescript
import { getFileSize, getCompressedSize } from "@visulima/fs/size";

// Get file size in bytes
const size = await getFileSize("large-file.json");
console.log(`${size} bytes`);

// Get compressed size (gzip)
const compressed = await getCompressedSize("large-file.json", "gzip");
console.log(`${compressed} bytes (gzipped)`);

// Brotli compression
const brotli = await getCompressedSize("bundle.js", "brotli");
```

## EOL Detection [#eol-detection]

Detect and normalize line endings:

```typescript
import { detectEOL, normalizeEOL } from "@visulima/fs/eol";

// Detect line ending style
const eol = await detectEOL("source.txt");
console.log(eol); // '\n' or '\r\n' or '\r'

// Normalize to Unix line endings
const content = await normalizeEOL("windows-file.txt", "\n");
```

## Common Patterns [#common-patterns]

### Build Script [#build-script]

```typescript
import { ensureDir, emptyDir, writeJson } from "@visulima/fs";

async function build() {
    // Prepare output directory
    await ensureDir("dist");
    await emptyDir("dist");

    // ... build process ...

    // Write build manifest
    await writeJson("dist/manifest.json", {
        version: "1.0.0",
        buildTime: new Date().toISOString(),
    });
}
```

### Find Project Root [#find-project-root]

```typescript
import { findUp, readJson } from "@visulima/fs";
import { dirname } from "node:path";

async function getProjectRoot() {
    const packagePath = await findUp("package.json");
    if (!packagePath) {
        throw new Error("Not in a Node.js project");
    }
    return dirname(packagePath);
}

const projectRoot = await getProjectRoot();
const packageJson = await readJson(`${projectRoot}/package.json`);
```

### Process All Source Files [#process-all-source-files]

```typescript
import { walk } from "@visulima/fs";

async function processSourceFiles() {
    const files: string[] = [];

    for await (const entry of walk("src", {
        extensions: [".ts", ".tsx"],
        skip: ["**/*.test.ts", "**/__tests__/**"],
    })) {
        if (entry.isFile) {
            files.push(entry.path);
            // Process file...
        }
    }

    return files;
}
```

### Configuration Manager [#configuration-manager]

```typescript
import { readJson, writeJson, findUp } from "@visulima/fs";
import { readYaml, writeYaml } from "@visulima/fs/yaml";

async function loadConfig() {
    // Try JSON first
    const jsonPath = await findUp("config.json");
    if (jsonPath) {
        return { path: jsonPath, data: await readJson(jsonPath) };
    }

    // Fall back to YAML
    const yamlPath = await findUp("config.yml");
    if (yamlPath) {
        return { path: yamlPath, data: await readYaml(yamlPath) };
    }

    throw new Error("No config file found");
}
```

## Sync vs. Async [#sync-vs-async]

Every function has both async and sync versions:

```typescript
// Async (recommended for I/O operations)
const data = await readJson("data.json");
await writeJson("output.json", data);

// Sync (useful in scripts or when needed)
const dataSynce = readJsonSync("data.json");
writeJsonSync("output.json", dataSync);
```

**Recommendation:** Use async versions in applications and servers. Use sync versions in build scripts and CLI tools where simplicity is preferred.

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/fs/usage">
    Explore all file system utilities in detail
  </Card>

  <Card title="API Reference" href="/docs/packages/fs/api">
    Complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/fs/usage)



# Usage Guide [#usage-guide]

Complete guide to using **@visulima/fs** file system utilities.

## JSON Operations [#json-operations]

### Read JSON Files [#read-json-files]

```typescript
import { readJson, readJsonSync } from "@visulima/fs";

// Async
const config = await readJson("config.json");

// Sync
const packageJson = readJsonSync("package.json");

// With error handling
try {
    const data = await readJson("data.json");
} catch (error) {
    if (error.code === "ENOENT") {
        console.error("File not found");
    }
}
```

### Write JSON Files [#write-json-files]

```typescript
import { writeJson, writeJsonSync } from "@visulima/fs";

// Async with formatting
await writeJson(
    "output.json",
    { key: "value" },
    {
        spaces: 2, // 2-space indentation
    },
);

// Sync
writeJsonSync("data.json", { items: [1, 2, 3] });

// Compact (no spaces)
await writeJson("compact.json", data, { spaces: 0 });

// Creates parent directories automatically
await writeJson("deeply/nested/path/file.json", data);
```

## YAML Operations [#yaml-operations]

Requires `yaml` peer dependency:

```bash npm2yarn
npm install yaml
```

### Read YAML Files [#read-yaml-files]

```typescript
import { readYaml, readYamlSync } from "@visulima/fs/yaml";

// Async
const config = await readYaml("config.yml");

// Sync
const data = readYamlSync("data.yaml");
```

### Write YAML Files [#write-yaml-files]

```typescript
import { writeYaml, writeYamlSync } from "@visulima/fs/yaml";

// Async
await writeYaml("output.yml", {
    name: "project",
    version: "1.0.0",
    dependencies: ["package1", "package2"],
});

// Sync
writeYamlSync("config.yaml", configuration);
```

## Directory Walking [#directory-walking]

### Basic Walking [#basic-walking]

```typescript
import { walk, walkSync } from "@visulima/fs";

// Async - All entries
for await (const entry of walk("src")) {
    console.log(entry.path);
    console.log("Is file:", entry.isFile);
    console.log("Is directory:", entry.isDirectory);
    console.log("Is symlink:", entry.isSymlink);
}

// Sync
for (const entry of walkSync("src")) {
    console.log(entry.path);
}
```

### Filter by Extension [#filter-by-extension]

```typescript
import { walk } from "@visulima/fs";

// Only TypeScript files
for await (const entry of walk("src", {
    extensions: [".ts", ".tsx"],
})) {
    console.log(entry.path);
}

// Multiple extensions
for await (const entry of walk("src", {
    extensions: [".js", ".jsx", ".ts", ".tsx"],
})) {
    console.log(entry.path);
}
```

### Pattern Matching [#pattern-matching]

```typescript
import { walk } from "@visulima/fs";

// Include patterns (glob or regex)
for await (const entry of walk("src", {
    match: ["**/components/**/*.tsx", "**/pages/**/*.tsx"],
})) {
    console.log("Component or page:", entry.path);
}

// Exclude patterns
for await (const entry of walk("src", {
    skip: ["**/*.test.ts", "**/*.spec.ts", "**/node_modules/**", "**/dist/**"],
})) {
    console.log(entry.path);
}

// Combine include and exclude
for await (const entry of walk(".", {
    match: ["**/*.ts"],
    skip: ["**/node_modules/**", "**/dist/**"],
})) {
    console.log(entry.path);
}
```

### Control Depth [#control-depth]

```typescript
import { walk } from "@visulima/fs";

// Limit depth (1 = only immediate children)
for await (const entry of walk("src", {
    maxDepth: 1,
})) {
    console.log(entry.path);
}

// Only 2 levels deep
for await (const entry of walk("src", {
    maxDepth: 2,
})) {
    console.log(entry.path);
}
```

### Filter Entry Types [#filter-entry-types]

```typescript
import { walk } from "@visulima/fs";

// Only files
for await (const entry of walk("src", {
    includeFiles: true,
    includeDirs: false,
    includeSymlinks: false,
})) {
    console.log("File:", entry.path);
}

// Only directories
for await (const entry of walk("src", {
    includeFiles: false,
    includeDirs: true,
})) {
    console.log("Directory:", entry.path);
}
```

### Follow Symlinks [#follow-symlinks]

```typescript
import { walk } from "@visulima/fs";

// Follow symbolic links
for await (const entry of walk("src", {
    followSymlinks: true,
})) {
    console.log(entry.path);
}

// Don't follow symlinks (default)
for await (const entry of walk("src", {
    followSymlinks: false,
    includeSymlinks: true, // But include them in results
})) {
    if (entry.isSymlink) {
        console.log("Symlink:", entry.path);
    }
}
```

## Finding Files Upward [#finding-files-upward]

### Find Single File [#find-single-file]

```typescript
import { findUp, findUpSync } from "@visulima/fs";

// Async - Find nearest package.json
const packagePath = await findUp("package.json");
if (packagePath) {
    console.log("Found at:", packagePath);
}

// Sync
const gitPath = findUpSync(".git");
```

### Find Multiple Possible Files [#find-multiple-possible-files]

```typescript
import { findUp } from "@visulima/fs";

// Try multiple filenames in order
const configPath = await findUp([".config.json", ".config.yml", "config.json", "config.yml"]);
```

### Find with Custom Matcher [#find-with-custom-matcher]

```typescript
import { findUp } from "@visulima/fs";
import { basename, join } from "node:path";
import { readFile } from "node:fs/promises";

// Find by directory name
const nodeModules = await findUp((dir) => {
    return basename(dir) === "node_modules";
});

// Find by file content
const packageWithName = await findUp(async (dir, file) => {
    if (file === "package.json") {
        const content = await readFile(join(dir, file), "utf-8");
        const pkg = JSON.parse(content);
        return pkg.name === "my-package";
    }
    return false;
});
```

### Custom Search Options [#custom-search-options]

```typescript
import { findUp } from "@visulima/fs";

// Start from specific directory
const found = await findUp("config.json", {
    cwd: "/specific/start/directory",
});

// Stop at specific directory
const foundWithStop = await findUp("file.txt", {
    stopAt: "/home/user", // Don't search above this
});

// Search up to root
const foundAtRoot = await findUp(".git", {
    type: "directory",
});
```

## Ensuring Files and Directories [#ensuring-files-and-directories]

### Ensure Directory [#ensure-directory]

Creates directory and all parent directories:

```typescript
import { ensureDir, ensureDirSync } from "@visulima/fs";

// Async
await ensureDir("src/components/ui/buttons");

// Sync
ensureDirSync("dist/assets/images/thumbnails");

// Returns existing directory path if it already exists
const dirPath = await ensureDir("existing/directory");
```

### Ensure File [#ensure-file]

Creates file and all parent directories:

```typescript
import { ensureFile, ensureFileSync } from "@visulima/fs";

// Async
await ensureFile("logs/app/2024/01/error.log");

// Sync
ensureFileSync("cache/temp/data.txt");

// Creates empty file if it doesn't exist
// Does nothing if file already exists
await ensureFile("path/to/new/file.txt");
```

### Ensure Link (Hard Link) [#ensure-link-hard-link]

```typescript
import { ensureLink, ensureLinkSync } from "@visulima/fs";

// Async - Create hard link
await ensureLink("source.txt", "hardlink.txt");

// Sync
ensureLinkSync("original.dat", "link.dat");
```

### Ensure Symlink [#ensure-symlink]

```typescript
import { ensureSymlink, ensureSymlinkSync } from "@visulima/fs";

// File symlink
await ensureSymlink("target/file.txt", "link-to-file.txt", "file");

// Directory symlink
await ensureSymlink("target/directory", "link-to-dir", "dir");

// Sync versions
ensureSymlinkSync("source.txt", "link.txt", "file");
```

## Directory Utilities [#directory-utilities]

### Check Empty Directory [#check-empty-directory]

```typescript
import { emptyDir, emptyDirSync } from "@visulima/fs";

// Async
const isEmpty = await emptyDir("temp");
if (isEmpty) {
    console.log("Directory is empty or doesn't exist");
}

// Sync
if (emptyDirSync("cache")) {
    console.log("Cache is empty");
}
```

## File Size Utilities [#file-size-utilities]

### Get File Size [#get-file-size]

```typescript
import { getFileSize, getFileSizeSync } from "@visulima/fs/size";

// Async
const bytes = await getFileSize("large-file.json");
console.log(`File size: ${bytes} bytes`);

// Sync
const size = getFileSizeSync("image.png");
console.log(`Size: ${(size / 1024).toFixed(2)} KB`);
```

### Get Compressed Size [#get-compressed-size]

Calculate file size after compression:

```typescript
import { getCompressedSize, getCompressedSizeSync } from "@visulima/fs/size";

// Gzip compression
const gzipSize = await getCompressedSize("bundle.js", "gzip");
console.log(`Gzipped: ${gzipSize} bytes`);

// Brotli compression
const brotliSize = await getCompressedSize("bundle.js", "brotli");
console.log(`Brotli: ${brotliSize} bytes`);

// Sync versions
const sizeGzip = getCompressedSizeSync("file.txt", "gzip");
const sizeBrotli = getCompressedSizeSync("file.txt", "brotli");

// Compare sizes
const original = await getFileSize("bundle.js");
const gzip = await getCompressedSize("bundle.js", "gzip");
const brotli = await getCompressedSize("bundle.js", "brotli");

console.log(`Original: ${original} bytes`);
console.log(`Gzip: ${gzip} bytes (${((gzip / original) * 100).toFixed(1)}%)`);
console.log(`Brotli: ${brotli} bytes (${((brotli / original) * 100).toFixed(1)}%)`);
```

## EOL (End of Line) Utilities [#eol-end-of-line-utilities]

### Detect Line Endings [#detect-line-endings]

```typescript
import { detectEOL, detectEOLSync } from "@visulima/fs/eol";

// Async
const eol = await detectEOL("source.txt");
console.log(eol); // '\n' (Unix), '\r\n' (Windows), or '\r' (old Mac)

// Sync
const lineEnding = detectEOLSync("file.txt");
if (lineEnding === "\r\n") {
    console.log("Windows line endings");
} else if (lineEnding === "\n") {
    console.log("Unix line endings");
}
```

### Normalize Line Endings [#normalize-line-endings]

```typescript
import { normalizeEOL, normalizeEOLSync } from "@visulima/fs/eol";

// Async - Convert to Unix line endings
await normalizeEOL("source.txt", "\n");

// Convert to Windows line endings
await normalizeEOL("source.txt", "\r\n");

// Sync version
normalizeEOLSync("file.txt", "\n");
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/fs/api">
    Complete API documentation with all parameters
  </Card>
</Cards>


# API Reference (/docs/packages/health-check/api)



# API Reference [#api-reference]

## createHealthCheck() [#createhealthcheck]

Create health check instance.

```typescript
function createHealthCheck(options?: Options): HealthCheck;
```

## HealthCheck.handler() [#healthcheckhandler]

Get request handler for health endpoint.

## HealthCheck.liveness() [#healthcheckliveness]

Kubernetes liveness probe handler.

## HealthCheck.readiness() [#healthcheckreadiness]

Kubernetes readiness probe handler.

## Check Function [#check-function]

```typescript
type Check = () => Promise<{ status: "ok" | "error"; message?: string }>;
```


# Introduction (/docs/packages/health-check)



# @visulima/health-check [#visulimahealth-check]

Create health check endpoints to monitor application status, dependencies, and readiness for production deployments.

## Key Features [#key-features]

* **Health Endpoints** - /health and /ready endpoints
* **Custom Checks** - Add database, cache, API checks
* **Kubernetes Ready** - Compatible with K8s liveness/readiness probes
* **Graceful Degradation** - Report partial failures
* **TypeScript** - Full type definitions

## Quick Start [#quick-start]

```typescript
import { createHealthCheck } from "@visulima/health-check";

const health = createHealthCheck({
    checks: {
        database: async () => await db.ping(),
        redis: async () => await redis.ping(),
    },
});

app.get("/health", health.handler());
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/health-check/installation">
    Install and setup
  </Card>

  <Card title="Usage" href="/docs/packages/health-check/usage">
    Create health checks
  </Card>

  <Card title="API" href="/docs/packages/health-check/api">
    API reference
  </Card>
</Cards>


# Installation (/docs/packages/health-check/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/health-check
```

## Import [#import]

```typescript
import { createHealthCheck, HealthCheck } from "@visulima/health-check";
```


# Usage (/docs/packages/health-check/usage)



# Usage Guide [#usage-guide]

## Basic Health Check [#basic-health-check]

```typescript
import { createHealthCheck } from "@visulima/health-check";

const health = createHealthCheck();
app.get("/health", health.handler());
```

## Custom Checks [#custom-checks]

```typescript
const health = createHealthCheck({
    checks: {
        database: async () => {
            await db.ping();
            return { status: "ok" };
        },
        api: async () => {
            const res = await fetch("https://api.example.com/ping");
            return { status: res.ok ? "ok" : "error" };
        },
    },
});
```

## Kubernetes Probes [#kubernetes-probes]

```typescript
app.get("/health", health.liveness());
app.get("/ready", health.readiness());
```


# API Reference (/docs/packages/html/api)



# API Reference [#api-reference]

Complete API documentation for all functions in @visulima/html.

## escapeHtml() [#escapehtml]

Fast HTML escaping for content and attributes.

### Signature [#signature]

```typescript
function escapeHtml(value: string | null | undefined, isAttributeValue?: boolean): string;
```

### Parameters [#parameters]

* **value** (`string | null | undefined`) - The string to escape
* **isAttributeValue** (`boolean`, optional) - If true, escapes for HTML attributes (including quotes)

### Returns [#returns]

* `string` - Escaped HTML string. Returns empty string for null/undefined.

### Examples [#examples]

```typescript
import { escapeHtml } from "@visulima/html";

// Content escaping (default)
escapeHtml("<script>alert('xss')</script>");
// => '&lt;script>alert('xss')&lt;/script>'

// Attribute escaping
escapeHtml('value="test"', true);
// => 'value=&quot;test&quot;'

// Handles null/undefined
escapeHtml(null);
// => ''
```

***

## html() [#html]

Template tag for XSS-safe HTML with automatic escaping of interpolated values.

### Signature (Template Tag) [#signature-template-tag]

```typescript
function html(strings: TemplateStringsArray, ...values: unknown[]): string;
```

### Signature (Function) [#signature-function]

```typescript
function html(value: string, escape?: boolean): string;
```

### Parameters (Template Tag) [#parameters-template-tag]

* **strings** (`TemplateStringsArray`) - Template string literals
* **values** (`unknown[]`) - Interpolated values (automatically escaped)

### Parameters (Function) [#parameters-function]

* **value** (`string`) - HTML string
* **escape** (`boolean`, optional) - If true, escapes the HTML. Default: false

### Returns [#returns-1]

* `string` - HTML string with escaped interpolations (template tag) or processed HTML (function)

### Examples [#examples-1]

```typescript
import { html } from "@visulima/html";

// Template tag
const name = "Alice";
const comment = "<script>bad</script>";
html`<div>${name}: ${comment}</div>`;
// => '<div>Alice: &lt;script&gt;bad&lt;/script&gt;</div>'

// Function mode
html("<div>Safe HTML</div>", false);
// => '<div>Safe HTML</div>'
```

***

## escapeCss() [#escapecss]

Escape strings for safe CSS interpolation.

### Signature [#signature-1]

```typescript
function escapeCss(value: string): string;
```

### Parameters [#parameters-1]

* **value** (`string`) - The CSS string to escape

### Returns [#returns-2]

* `string` - Escaped CSS string safe for interpolation

### Examples [#examples-2]

```typescript
import { escapeCss } from "@visulima/html";

const userColor = "red; } body { display: none; ";
escapeCss(userColor);
// => Escaped CSS preventing injection
```

***

## css() [#css]

Template tag and function for CSS strings with object support.

### Signature (Template Tag) [#signature-template-tag-1]

```typescript
function css(strings: TemplateStringsArray, ...values: unknown[]): string;
```

### Signature (Function - String) [#signature-function---string]

```typescript
function css(value: string, escape?: boolean): string;
```

### Signature (Function - Object) [#signature-function---object]

```typescript
function css(styles: Properties, escape?: boolean): string;
```

### Parameters [#parameters-2]

* **strings/value/styles** - CSS template, string, or object
* **escape** (`boolean`, optional) - If true, escapes the CSS. Default: false

### Returns [#returns-3]

* `string` - CSS string

### Examples [#examples-3]

```typescript
import { css } from "@visulima/html";

// Template tag
const color = "red";
css`
    .theme {
        color: ${color};
    }
`;

// CSS object with TypeScript autocomplete
css({ padding: "10px", marginTop: "20px" });
// => 'padding: 10px; margin-top: 20px;'

// Function mode
css(":where(.test) { color: red; }", false);
```

***

## escapeJs() [#escapejs]

Escape JavaScript for safe script tag interpolation.

### Signature [#signature-2]

```typescript
function escapeJs(value: string): string;
```

### Parameters [#parameters-3]

* **value** (`string`) - JavaScript string to escape

### Returns [#returns-4]

* `string` - Escaped JavaScript safe for `<script>` tags

### Examples [#examples-4]

```typescript
import { escapeJs } from "@visulima/html";

const userData = { name: "</script><script>alert(1)" };
const safe = escapeJs(JSON.stringify(userData));
const html = `<script>window.user = ${safe};</script>`;
```

***

## isValidCustomElementName() [#isvalidcustomelementname]

Validate custom element names per HTML specification.

### Signature [#signature-3]

```typescript
function isValidCustomElementName(name: string): boolean;
```

### Parameters [#parameters-4]

* **name** (`string`) - Element name to validate

### Returns [#returns-5]

* `boolean` - True if valid custom element name, false otherwise

### Rules [#rules]

* Must contain a hyphen (`-`)
* Must start with ASCII lowercase letter
* Cannot be a standard HTML tag
* Cannot start with reserved prefixes

### Examples [#examples-5]

```typescript
import { isValidCustomElementName } from "@visulima/html";

isValidCustomElementName("my-element");
// => true

isValidCustomElementName("myElement");
// => false (no hyphen)
```

***

## encode() [#encode]

Encode HTML entities with multiple modes and standards.

### Signature [#signature-4]

```typescript
function encode(text: string, options?: EncodeOptions): string;
```

### Options [#options]

```typescript
interface EncodeOptions {
    level?: "html5" | "html4" | "xml" | "all";
    mode?: "specialChars" | "nonAscii" | "nonAsciiPrintable" | "nonAsciiPrintableOnly" | "extensive";
    numeric?: "decimal" | "hexadecimal";
}
```

### Parameters [#parameters-5]

* **text** (`string`) - Text to encode
* **options** (`EncodeOptions`, optional) - Encoding configuration

### Returns [#returns-6]

* `string` - Encoded HTML string

### Examples [#examples-6]

```typescript
import { encode } from "@visulima/html";

// Default (special chars only)
encode("< > \" ' & ©");
// => '&lt; &gt; &quot; &apos; &amp; ©'

// Encode non-ASCII
encode("< ©", { mode: "nonAscii" });
// => '&lt; &copy;'

// XML with hex
encode("©", { level: "xml", mode: "nonAscii", numeric: "hexadecimal" });
// => '&#xa9;'
```

***

## decode() [#decode]

Decode HTML entities with scope control.

### Signature [#signature-5]

```typescript
function decode(html: string, options?: DecodeOptions): string;
```

### Options [#options-1]

```typescript
interface DecodeOptions {
    level?: "html5" | "html4" | "xml" | "all";
    scope?: "body" | "attribute" | "strict";
}
```

### Parameters [#parameters-6]

* **html** (`string`) - HTML to decode
* **options** (`DecodeOptions`, optional) - Decoding configuration

### Returns [#returns-7]

* `string` - Decoded string

### Examples [#examples-7]

```typescript
import { decode } from "@visulima/html";

// Default (HTML5, body scope)
decode("&lt; &gt; &copy;");
// => '< > ©'

// Strict scope (requires semicolon)
decode("&lt &gt", { scope: "strict" });
// => '&lt &gt'
```

***

## decodeEntity() [#decodeentity]

Decode a single HTML entity.

### Signature [#signature-6]

```typescript
function decodeEntity(entity: string, options?: DecodeEntityOptions): string;
```

### Options [#options-2]

```typescript
interface DecodeEntityOptions {
    level?: "html5" | "html4" | "xml" | "all";
}
```

### Parameters [#parameters-7]

* **entity** (`string`) - Single entity to decode
* **options** (`DecodeEntityOptions`, optional) - Decoding level

### Returns [#returns-8]

* `string` - Decoded character

### Examples [#examples-8]

```typescript
import { decodeEntity } from "@visulima/html";

decodeEntity("&lt;");
// => '<'

decodeEntity("&copy;");
// => '©'
```

***

## sanitizeHtml() [#sanitizehtml]

Clean user-submitted HTML.

### Signature [#signature-7]

```typescript
function sanitizeHtml(dirty: string, options?: SanitizeOptions): string;
```

### Key Options [#key-options]

```typescript
interface SanitizeOptions {
    allowedTags?: string[];
    allowedAttributes?: Record<string, string[]>;
    allowedSchemes?: string[];
    allowedIframeHostnames?: string[];
    selfClosing?: string[];
    transformTags?: Record<string, TransformFunction>;
    textFilter?: (text: string) => string;
    // ... more options
}
```

### Parameters [#parameters-8]

* **dirty** (`string`) - Unsanitized HTML
* **options** (`SanitizeOptions`, optional) - Sanitization configuration

### Returns [#returns-9]

* `string` - Sanitized HTML

### Examples [#examples-9]

```typescript
import { sanitizeHtml } from "@visulima/html";

// Basic
sanitizeHtml("<p>Hello <script>bad</script></p>");
// => '<p>Hello </p>'

// Custom config
sanitizeHtml(html, {
    allowedTags: ["p", "a", "b"],
    allowedAttributes: {
        a: ["href"],
    },
});
```

### Default Configuration [#default-configuration]

Access defaults via `sanitizeHtml.defaults`:

```typescript
const defaults = sanitizeHtml.defaults;
// {
//   allowedTags: ['h3', 'h4', 'h5', ...],
//   allowedAttributes: { a: ['href', 'name', 'target'], ... },
//   allowedSchemes: ['http', 'https', 'ftp', 'mailto'],
//   ...
// }
```

***

## stripHtml() [#striphtml]

Remove HTML tags and extract plain text.

### Signature [#signature-8]

```typescript
function stripHtml(html: string, options?: StripOptions): StripResult;
```

### Options [#options-3]

```typescript
interface StripOptions {
    stripTogetherWithTheirContents?: string[];
    // ... additional options from string-strip-html
}
```

### Result [#result]

```typescript
interface StripResult {
    result: string;
    // ... additional metadata
}
```

### Parameters [#parameters-9]

* **html** (`string`) - HTML to strip
* **options** (`StripOptions`, optional) - Stripping configuration

### Returns [#returns-10]

* `StripResult` - Object containing `result` (plain text) and metadata

### Examples [#examples-10]

```typescript
import { stripHtml } from "@visulima/html";

// Basic stripping
stripHtml("<div>Hello <b>World</b></div>").result;
// => 'Hello World'

// Strip with content
stripHtml("Text <script>bad</script> more", {
    stripTogetherWithTheirContents: ["script", "style"],
}).result;
// => 'Text more'
```

***

## htmlTags [#htmltags]

Array of all standard HTML tags.

### Type [#type]

```typescript
const htmlTags: readonly string[];
```

### Usage [#usage]

```typescript
import { htmlTags } from "@visulima/html";

console.log(htmlTags);
// => ['a', 'abbr', 'address', ...]

htmlTags.includes("div");
// => true
```

***

## voidHtmlTags [#voidhtmltags]

Array of void/self-closing HTML tags.

### Type [#type-1]

```typescript
const voidHtmlTags: readonly string[];
```

### Usage [#usage-1]

```typescript
import { voidHtmlTags } from "@visulima/html";

console.log(voidHtmlTags);
// => ['area', 'base', 'br', 'col', ...]

voidHtmlTags.includes("br");
// => true
```

***

## Type Definitions [#type-definitions]

### Properties (CSS) [#properties-css]

CSS properties type from `csstype` for TypeScript autocomplete in `css()` function:

```typescript
import type { Properties } from "@visulima/html";

const styles: Properties = {
    padding: "10px",
    marginTop: "20px",
    backgroundColor: "blue",
    // Full autocomplete for all CSS properties!
};
```

### EncodeOptions [#encodeoptions]

```typescript
interface EncodeOptions {
    /**
     * Encoding standard
     * @default "html5"
     */
    level?: "html5" | "html4" | "xml" | "all";

    /**
     * Which characters to encode
     * @default "specialChars"
     */
    mode?: "specialChars" | "nonAscii" | "nonAsciiPrintable" | "nonAsciiPrintableOnly" | "extensive";

    /**
     * Numeric entity format
     * @default "decimal"
     */
    numeric?: "decimal" | "hexadecimal";
}
```

### DecodeOptions [#decodeoptions]

```typescript
interface DecodeOptions {
    /**
     * Decoding standard
     * @default "html5"
     */
    level?: "html5" | "html4" | "xml" | "all";

    /**
     * How to handle entities without semicolon
     * @default "body"
     */
    scope?: "body" | "attribute" | "strict";
}
```

### SanitizeOptions [#sanitizeoptions]

See [sanitize-html documentation](https://github.com/apostrophecms/sanitize-html#what-are-the-default-options) for complete options.

### StripOptions [#stripoptions]

See [string-strip-html documentation](https://codsen.com/os/string-strip-html/) for complete options.

***

## Constants [#constants]

### Default Encode Options [#default-encode-options]

```typescript
{
    level: "html5",
    mode: "specialChars",
    numeric: "decimal"
}
```

### Default Decode Options [#default-decode-options]

```typescript
{
    level: "html5",
    scope: "body"
}
```

### Default Sanitize Tags [#default-sanitize-tags]

```typescript
[
    "h3",
    "h4",
    "h5",
    "h6",
    "blockquote",
    "p",
    "a",
    "ul",
    "ol",
    "nl",
    "li",
    "b",
    "i",
    "strong",
    "em",
    "strike",
    "code",
    "hr",
    "br",
    "div",
    "table",
    "thead",
    "caption",
    "tbody",
    "tr",
    "th",
    "td",
    "pre",
];
```


# Introduction (/docs/packages/html)



# @visulima/html [#visulimahtml]

Security-focused HTML utilities providing fast escaping, sanitization, entity encoding/decoding, and safe template rendering. Protect against XSS attacks, CSS injection, and JavaScript injection with comprehensive HTML processing tools.

## Key Features [#key-features]

### Security & XSS Protection [#security--xss-protection]

* **Fast HTML escaping** - Optimized escaping from Svelte for content and attributes
* **HTML template tags** - Automatic XSS protection for template literals
* **CSS/JS escaping** - Prevent injection attacks in styles and scripts
* **Sanitization** - Clean user-submitted HTML while preserving safe elements
* **Multiple protection layers** - Escaping, sanitization, and validation working together

### HTML Processing [#html-processing]

* **Entity encoding/decoding** - Fastest HTML entity library with multiple standards
* **Tag stripping** - Extract plain text while preserving legitimate brackets
* **Custom element validation** - Validate HTML custom element names
* **Tag lists** - Standard and void HTML tags for validation

### Developer Experience [#developer-experience]

* **TypeScript support** - Full type definitions with CSS property autocomplete
* **Template literal tags** - `html` and `css` template functions
* **Multiple encoding modes** - specialChars, nonAscii, extensive, and more
* **Flexible APIs** - Both function and template tag interfaces

## Quick Start [#quick-start]

```typescript
import { escapeHtml, sanitizeHtml, encode, stripHtml } from "@visulima/html";

// Escape user input
const safe = escapeHtml('<script>alert("xss")</script>');
// => '&lt;script>alert("xss")&lt;/script>'

// Sanitize HTML content
const clean = sanitizeHtml("<p>Hello <script>bad()</script>World</p>");
// => '<p>Hello World</p>'

// Encode entities
const encoded = encode("< > \" ' & ©");
// => '&lt; &gt; &quot; &apos; &amp; ©'

// Strip HTML tags
const text = stripHtml("<div>Hello <b>World</b></div>").result;
// => 'Hello World'
```

## Use Cases [#use-cases]

### Prevent XSS in User Content [#prevent-xss-in-user-content]

```typescript
import { escapeHtml, html } from "@visulima/html";

function renderComment(username: string, comment: string) {
    // Escape user input to prevent XSS
    return html`
        <div class="comment">
            <strong>${escapeHtml(username)}</strong>
            <p>${escapeHtml(comment)}</p>
        </div>
    `;
}

renderComment("Alice", '<script>alert("xss")</script>');
// Safe output with escaped script tags
```

### Sanitize Rich Text Content [#sanitize-rich-text-content]

```typescript
import { sanitizeHtml } from "@visulima/html";

function saveUserPost(htmlContent: string) {
    // Allow safe HTML formatting while removing dangerous elements
    const clean = sanitizeHtml(htmlContent, {
        allowedTags: ["p", "b", "i", "em", "strong", "a", "ul", "ol", "li"],
        allowedAttributes: {
            a: ["href", "title"],
        },
    });

    return database.posts.create({ content: clean });
}
```

### Extract Plain Text from HTML [#extract-plain-text-from-html]

```typescript
import { stripHtml } from "@visulima/html";

function generateEmailPreview(htmlEmail: string): string {
    // Remove all HTML for plain text email clients
    const plainText = stripHtml(htmlEmail, {
        stripTogetherWithTheirContents: ["script", "style"],
    }).result;

    return plainText.substring(0, 200) + "...";
}
```

### Safe CSS and JavaScript Injection [#safe-css-and-javascript-injection]

```typescript
import { escapeCss, escapeJs, css } from "@visulima/html";

function renderDynamicStyles(userColor: string) {
    // Prevent CSS injection
    return css`
        .user-theme {
            background-color: ${escapeCss(userColor)};
        }
    `;
}

function renderConfig(userData: unknown) {
    // Prevent JavaScript injection
    return `<script>window.config = ${escapeJs(JSON.stringify(userData))};</script>`;
}
```

## Security Best Practices [#security-best-practices]

### Escaping vs Sanitization [#escaping-vs-sanitization]

**Use escaping when:**

* Inserting plain text into HTML
* The content should be displayed as-is
* Maximum performance is needed
* Building HTML strings manually

**Use sanitization when:**

* Users submit HTML content
* Rich text formatting should be preserved
* Fine-grained control over allowed elements is needed

**Never:**

* Render user input without escaping or sanitization
* Use sanitization on already-escaped content
* Trust client-side validation alone

### Defense in Depth [#defense-in-depth]

```typescript
import { escapeHtml, sanitizeHtml } from "@visulima/html";

// Layer 1: Sanitize on input
const sanitized = sanitizeHtml(userInput);

// Layer 2: Escape on output
const safe = escapeHtml(sanitized, true); // attribute mode

// Layer 3: Use Content Security Policy headers
// Content-Security-Policy: default-src 'self'
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/html/installation">
    Install and import HTML utilities
  </Card>

  <Card title="Quick Start" href="/docs/packages/html/quick-start">
    Get started with escaping and sanitization
  </Card>

  <Card title="Usage Guide" href="/docs/packages/html/usage">
    Learn all HTML processing features
  </Card>

  <Card title="API Reference" href="/docs/packages/html/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

* **Node.js:** 22.13 or higher
* **Browser:** Modern browsers with standard HTML APIs
* **Dependencies:** sanitize-html, csstype
* **TypeScript:** Full type definitions included


# Installation (/docs/packages/html/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/html
```

## Import [#import]

### Main Functions [#main-functions]

```typescript
import { escapeHtml, escapeCss, escapeJs, html, css, isValidCustomElementName } from "@visulima/html";
```

### Entity Encoding [#entity-encoding]

```typescript
import { encode, decode, decodeEntity } from "@visulima/html";
```

### HTML Processing [#html-processing]

```typescript
import { sanitizeHtml, stripHtml } from "@visulima/html";
```

### HTML Tag Lists [#html-tag-lists]

```typescript
import { htmlTags, voidHtmlTags } from "@visulima/html";
```

### TypeScript Types [#typescript-types]

```typescript
import type { Properties } from "@visulima/html"; // CSS properties type
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0 or higher (if using TypeScript)
* **ECMAScript:** ES2020 or higher

## Dependencies [#dependencies]

The package includes:

* **sanitize-html** - HTML sanitization
* **csstype** - CSS property types for TypeScript autocomplete

## Verification [#verification]

Verify installation by running a simple example:

```typescript
import { escapeHtml, sanitizeHtml } from "@visulima/html";

// Test escaping
console.log(escapeHtml("<script>test</script>"));
// => '&lt;script>test&lt;/script>'

// Test sanitization
console.log(sanitizeHtml("<p>Hello <script>bad</script>World</p>"));
// => '<p>Hello World</p>'
```

## Browser Usage [#browser-usage]

For browser environments, import from the ESM bundle:

```html
<script type="module">
    import { escapeHtml } from "@visulima/html";

    const safe = escapeHtml(userInput);
</script>
```

## Bundler Configuration [#bundler-configuration]

### Vite [#vite]

No special configuration needed:

```typescript
// vite.config.ts
export default {
    // @visulima/html works out of the box
};
```

### Webpack [#webpack]

Ensure proper ESM handling:

```javascript
// webpack.config.js
module.exports = {
    resolve: {
        fullySpecified: false,
    },
};
```


# Quick Start (/docs/packages/html/quick-start)



# Quick Start [#quick-start]

Get started with @visulima/html in under 5 minutes. Learn the essential operations for HTML escaping, sanitization, and processing.

## Escape HTML [#escape-html]

Prevent XSS attacks by escaping user input:

```typescript
import { escapeHtml } from "@visulima/html";

// Escape HTML content
const userInput = '<script>alert("xss")</script>';
const safe = escapeHtml(userInput);
console.log(safe);
// => '&lt;script>alert("xss")&lt;/script>'

// Escape for HTML attributes
const attrValue = 'value="test"';
const safeAttr = escapeHtml(attrValue, true);
console.log(safeAttr);
// => 'value=&quot;test&quot;'
```

## HTML Template Tags [#html-template-tags]

Create XSS-safe HTML with automatic escaping:

```typescript
import { html } from "@visulima/html";

const username = "Alice";
const comment = '<script>alert("xss")</script>';

// Template literals automatically escape interpolated values
const markup = html`
    <div class="comment">
        <strong>${username}</strong>
        <p>${comment}</p>
    </div>
`;

console.log(markup);
// Interpolated values are escaped:
// <div class="comment">
//     <strong>Alice</strong>
//     <p>&lt;script&gt;alert("xss")&lt;/script&gt;</p>
// </div>
```

## Sanitize HTML [#sanitize-html]

Clean user-submitted HTML while preserving safe elements:

```typescript
import { sanitizeHtml } from "@visulima/html";

const userHtml = `
    <p>Hello <b>World</b></p>
    <script>alert("xss")</script>
    <a href="javascript:void(0)">Bad Link</a>
`;

const clean = sanitizeHtml(userHtml);
console.log(clean);
// => '<p>Hello <b>World</b></p>\n<a>Bad Link</a>'
// Script removed, javascript: URL removed
```

## Encode HTML Entities [#encode-html-entities]

Convert characters to HTML entities:

```typescript
import { encode, decode } from "@visulima/html";

// Encode special characters
const text = "< > \" ' & ©";
const encoded = encode(text);
console.log(encoded);
// => '&lt; &gt; &quot; &apos; &amp; ©'

// Decode entities
const html = "&lt; &gt; &copy;";
const decoded = decode(html);
console.log(decoded);
// => '< > ©'
```

## Strip HTML Tags [#strip-html-tags]

Extract plain text from HTML:

```typescript
import { stripHtml } from "@visulima/html";

const html = "<div>Hello <b>World</b></div>";
const plainText = stripHtml(html).result;
console.log(plainText);
// => 'Hello World'

// Strip specific tags with their content
const withScripts = "Text <script>alert('bad')</script> more text";
const stripped = stripHtml(withScripts, {
    stripTogetherWithTheirContents: ["script", "style"],
}).result;
console.log(stripped);
// => 'Text more text'
```

## CSS and JavaScript Escaping [#css-and-javascript-escaping]

Prevent injection in styles and scripts:

```typescript
import { escapeCss, escapeJs, css } from "@visulima/html";

// CSS escaping
const userColor = "red; } body { display: none; ";
const safeCss = css`
    .user-theme {
        color: ${escapeCss(userColor)};
    }
`;

// JavaScript escaping
const userData = { name: "</script><script>alert(1)</script>" };
const safeJs = escapeJs(JSON.stringify(userData));
const script = `<script>window.config = ${safeJs};</script>`;
```

## Validate Custom Elements [#validate-custom-elements]

Check if a string is a valid custom element name:

```typescript
import { isValidCustomElementName } from "@visulima/html";

console.log(isValidCustomElementName("my-element"));
// => true

console.log(isValidCustomElementName("myElement"));
// => false (no hyphen)
```

## Common Patterns [#common-patterns]

### Render User Comments [#render-user-comments]

```typescript
import { escapeHtml, html } from "@visulima/html";

interface Comment {
    author: string;
    text: string;
    timestamp: Date;
}

function renderComment(comment: Comment): string {
    return html`
        <div class="comment">
            <div class="comment-header">
                <strong>${escapeHtml(comment.author)}</strong>
                <time>${comment.timestamp.toISOString()}</time>
            </div>
            <p>${escapeHtml(comment.text)}</p>
        </div>
    `;
}
```

### Rich Text Editor Output [#rich-text-editor-output]

```typescript
import { sanitizeHtml } from "@visulima/html";

function saveEditorContent(htmlContent: string): string {
    return sanitizeHtml(htmlContent, {
        allowedTags: ["p", "br", "strong", "em", "a", "ul", "ol", "li"],
        allowedAttributes: {
            a: ["href", "title"],
        },
        allowedSchemes: ["http", "https", "mailto"],
    });
}
```

### Email Preview [#email-preview]

```typescript
import { stripHtml } from "@visulima/html";

function generatePreview(htmlEmail: string, maxLength: number = 100): string {
    const plainText = stripHtml(htmlEmail).result;
    return plainText.substring(0, maxLength).trim() + "...";
}
```

### Dynamic Styles [#dynamic-styles]

```typescript
import { css } from "@visulima/html";

function generateThemeStyles(primaryColor: string, fontSize: string): string {
    return css({
        color: primaryColor,
        fontSize: fontSize,
        fontWeight: "bold",
        padding: "10px",
    });
    // => 'color: red; font-size: 16px; font-weight: bold; padding: 10px;'
}
```

## Security Checklist [#security-checklist]

* ✅ **Always escape user input** before inserting into HTML
* ✅ **Use sanitization** for user-submitted HTML content
* ✅ **Validate custom element names** before registration
* ✅ **Escape CSS and JS** when interpolating user data
* ✅ **Strip HTML** when plain text is needed
* ✅ **Use template tags** for automatic XSS protection
* ❌ **Never trust client-side validation** alone
* ❌ **Never render raw user input** without processing

## Next Steps [#next-steps]

* Learn about [all HTML utilities](/docs/packages/html/usage) in the usage guide
* Explore [advanced sanitization options](/docs/packages/html/usage#html-sanitization)
* Check [entity encoding modes](/docs/packages/html/usage#html-entity-encoding)
* Review [API reference](/docs/packages/html/api) for complete documentation


# Usage (/docs/packages/html/usage)



# Usage Guide [#usage-guide]

Comprehensive guide to all HTML processing features in @visulima/html.

## HTML Escaping [#html-escaping]

### Basic Content Escaping [#basic-content-escaping]

Escape HTML special characters for safe insertion into HTML content:

```typescript
import { escapeHtml } from "@visulima/html";

// Escape dangerous characters
escapeHtml("<script>alert('xss')</script>");
// => '&lt;script>alert('xss')&lt;/script>'

// Escape ampersands
escapeHtml("Hello & World");
// => 'Hello &amp; World'

// Handle null/undefined
escapeHtml(null);
// => ''

escapeHtml(undefined);
// => ''
```

### Attribute Escaping [#attribute-escaping]

Escape for use in HTML attribute values:

```typescript
import { escapeHtml } from "@visulima/html";

// Attribute mode escapes quotes
const value = 'data-value="test"';
escapeHtml(value, true);
// => 'data-value=&quot;test&quot;'

// Use in attributes
const userInput = 'value"onclick="alert(1)"';
const html = `<input value="${escapeHtml(userInput, true)}">`;
// Safe: <input value="value&quot;onclick=&quot;alert(1)&quot;">
```

### Performance Characteristics [#performance-characteristics]

```typescript
import { escapeHtml } from "@visulima/html";

// Fast path for strings without special characters
escapeHtml("Hello World");
// No allocations needed

// Optimized for repeated escaping
for (const item of items) {
    const safe = escapeHtml(item.content);
}
```

## HTML Template Tags [#html-template-tags]

### Template Literal Usage [#template-literal-usage]

```typescript
import { html } from "@visulima/html";

// Static HTML (trusted)
const markup = html`<div class="container">Hello</div>`;
// => '<div class="container">Hello</div>'

// With interpolated values (auto-escaped)
const name = "Alice";
const comment = "<script>bad</script>";
const result = html`
    <div>
        <strong>${name}</strong>
        <p>${comment}</p>
    </div>
`;
// Interpolations are escaped:
// <div>
//     <strong>Alice</strong>
//     <p>&lt;script&gt;bad&lt;/script&gt;</p>
// </div>
```

### Conditional Content [#conditional-content]

```typescript
import { html } from "@visulima/html";

function renderUserBadge(user: { name: string; isAdmin: boolean }) {
    return html` <div class="user">${user.name} ${user.isAdmin ? html`<span class="badge">Admin</span>` : ""}</div> `;
}
```

### Lists and Iteration [#lists-and-iteration]

```typescript
import { html } from "@visulima/html";

function renderList(items: string[]) {
    return html`
        <ul>
            ${items.map((item) => html`<li>${item}</li>`).join("")}
        </ul>
    `;
}

renderList(["Apple", "Banana", "Cherry"]);
```

### Function Mode [#function-mode]

```typescript
import { html } from "@visulima/html";

// Return as-is (trusted HTML)
html("<div>Safe HTML</div>", false);
// => '<div>Safe HTML</div>'

// Escape HTML
html("<script>alert(1)</script>", true);
// => '&lt;script&gt;alert(1)&lt;/script&gt;'
```

## CSS Escaping [#css-escaping]

### Basic CSS Escaping [#basic-css-escaping]

```typescript
import { escapeCss } from "@visulima/html";

// Prevent CSS injection
const userInput = "red; } body { display: none; ";
const safe = escapeCss(userInput);

// Use in styles
const css = `.user-color { color: ${safe}; }`;
```

### CSS Selector Escaping [#css-selector-escaping]

```typescript
import { escapeCss } from "@visulima/html";

// Escape user-provided class names
const className = escapeCss(userClassName);
const styles = `.${className} { color: red; }`;

// Escape ID selectors
const id = escapeCss(userId);
const selector = `#${id}`;
```

### Style Element Injection [#style-element-injection]

```typescript
import { escapeCss } from "@visulima/html";

function injectStyles(userStyles: string) {
    return `<style>${escapeCss(userStyles)}</style>`;
}
```

## CSS Template Tags [#css-template-tags]

### Template Literal CSS [#template-literal-css]

```typescript
import { css } from "@visulima/html";

// Static CSS
const styles = css`
    .container {
        padding: 10px;
        margin: 20px;
    }
`;

// With interpolations
const color = "red";
const size = "16px";
const result = css`
    .theme {
        color: ${color};
        font-size: ${size};
    }
`;
```

### CSS Object to String [#css-object-to-string]

```typescript
import { css } from "@visulima/html";

// Convert CSS object (with TypeScript autocomplete!)
const styles = css({
    padding: "10px",
    margin: "20px",
    backgroundColor: "blue",
    fontSize: "16px",
});
// => 'padding: 10px; margin: 20px; background-color: blue; font-size: 16px;'

// CamelCase automatically converts to kebab-case
const result = css({
    paddingTop: "5px",
    marginBottom: "10px",
});
// => 'padding-top: 5px; margin-bottom: 10px;'
```

### Dynamic Styling [#dynamic-styling]

```typescript
import { css } from "@visulima/html";

interface ThemeConfig {
    primaryColor: string;
    fontSize: string;
    spacing: string;
}

function generateTheme(config: ThemeConfig): string {
    return css({
        color: config.primaryColor,
        fontSize: config.fontSize,
        padding: config.spacing,
        margin: config.spacing,
    });
}
```

## JavaScript Escaping [#javascript-escaping]

### Script Tag Injection [#script-tag-injection]

```typescript
import { escapeJs } from "@visulima/html";

// Escape for <script> tags
const userData = { name: "Alice", role: "admin" };
const safe = escapeJs(JSON.stringify(userData));

const html = `<script>window.user = ${safe};</script>`;
```

### Prevent Script Breaking [#prevent-script-breaking]

```typescript
import { escapeJs } from "@visulima/html";

// User input that tries to break out of script context
const malicious = "</script><script>alert('xss')</script>";
const safe = escapeJs(malicious);

// Safe even with malicious input
const script = `<script>const data = "${safe}";</script>`;
```

### JSON Data Injection [#json-data-injection]

```typescript
import { escapeJs } from "@visulima/html";

function inlineConfig(config: Record<string, unknown>): string {
    const safeConfig = escapeJs(JSON.stringify(config));
    return `<script>window.CONFIG = ${safeConfig};</script>`;
}
```

## Custom Element Validation [#custom-element-validation]

### Basic Validation [#basic-validation]

```typescript
import { isValidCustomElementName } from "@visulima/html";

// Valid names (contain hyphen)
isValidCustomElementName("my-element");
// => true

isValidCustomElementName("app-header");
// => true

// Invalid names (no hyphen)
isValidCustomElementName("myElement");
// => false

isValidCustomElementName("div");
// => false
```

### Registration Guard [#registration-guard]

```typescript
import { isValidCustomElementName } from "@visulima/html";

function safeRegister(name: string, constructor: CustomElementConstructor) {
    if (!isValidCustomElementName(name)) {
        throw new Error(`Invalid custom element name: "${name}". ` + "Custom element names must contain a hyphen.");
    }

    customElements.define(name, constructor);
}
```

### Validation in Frameworks [#validation-in-frameworks]

```typescript
import { isValidCustomElementName } from "@visulima/html";

class ComponentRegistry {
    register(name: string, component: unknown) {
        if (!isValidCustomElementName(name)) {
            console.error(`Invalid component name: ${name}`);
            return false;
        }

        this.components.set(name, component);
        return true;
    }
}
```

## HTML Entity Encoding [#html-entity-encoding]

### Basic Encoding [#basic-encoding]

```typescript
import { encode } from "@visulima/html";

// Encode special characters (default mode)
encode("< > \" ' & ©");
// => '&lt; &gt; &quot; &apos; &amp; ©'

// Non-ASCII characters passed through
encode("Hello © World");
// => 'Hello © World'
```

### Encoding Modes [#encoding-modes]

```typescript
import { encode } from "@visulima/html";

const text = "< > © ∆";

// specialChars: Only HTML special characters (default)
encode(text, { mode: "specialChars" });
// => '&lt; &gt; © ∆'

// nonAscii: Special chars + everything outside ASCII
encode(text, { mode: "nonAscii" });
// => '&lt; &gt; &copy; &#8710;'

// nonAsciiPrintable: Special chars + non-ASCII printable
encode(text, { mode: "nonAsciiPrintable" });
// => '&lt; &gt; &copy; &#8710;'

// extensive: All non-printable, non-ASCII, and named references
encode(text, { mode: "extensive" });
// => '&lt; &gt; &copy; &Delta;'
```

### Encoding Standards [#encoding-standards]

```typescript
import { encode } from "@visulima/html";

const text = "< ©";

// HTML5 (default)
encode(text, { level: "html5" });
// => '&lt; ©'

// HTML4
encode(text, { level: "html4" });
// => '&lt; ©'

// XML (uses numeric entities for non-standard chars)
encode(text, { level: "xml", mode: "nonAscii" });
// => '&lt; &#169;'
```

### Numeric Encoding [#numeric-encoding]

```typescript
import { encode } from "@visulima/html";

const text = "©";

// Decimal (default)
encode(text, { mode: "nonAscii", numeric: "decimal" });
// => '&#169;'

// Hexadecimal
encode(text, { mode: "nonAscii", numeric: "hexadecimal" });
// => '&#xa9;'
```

## HTML Entity Decoding [#html-entity-decoding]

### Basic Decoding [#basic-decoding]

```typescript
import { decode } from "@visulima/html";

// Decode named entities
decode("&lt; &gt; &copy;");
// => '< > ©'

// Decode numeric entities
decode("&#169; &#xa9;");
// => '© ©'

// Mixed entities
decode("&lt; &#62; &copy;");
// => '< > ©'
```

### Decoding Scopes [#decoding-scopes]

```typescript
import { decode } from "@visulima/html";

const html = "&lt &gt";

// body: Emulates browser tag body parsing (default)
decode(html, { scope: "body" });
// => '< >' (entities without semicolon replaced)

// attribute: Emulates browser attribute parsing
decode(html, { scope: "attribute" });
// => '< >' (replaced when not followed by =)

// strict: Only entities with semicolon
decode(html, { scope: "strict" });
// => '&lt &gt' (ignored without semicolon)
```

### Decode Single Entity [#decode-single-entity]

```typescript
import { decodeEntity } from "@visulima/html";

// Decode individual entities
decodeEntity("&lt;");
// => '<'

decodeEntity("&copy;");
// => '©'

decodeEntity("&#169;");
// => '©'
```

## HTML Sanitization [#html-sanitization]

### Basic Sanitization [#basic-sanitization]

```typescript
import { sanitizeHtml } from "@visulima/html";

// Remove dangerous HTML
const dirty = '<p>Hello <script>alert("xss")</script>World</p>';
const clean = sanitizeHtml(dirty);
// => '<p>Hello World</p>'

// Remove dangerous attributes
const input = '<a href="javascript:alert(1)">Click</a>';
const safe = sanitizeHtml(input);
// => '<a>Click</a>'
```

### Custom Allowed Tags [#custom-allowed-tags]

```typescript
import { sanitizeHtml } from "@visulima/html";

// Allow specific tags
const html = "<p>Text <b>bold</b> <script>bad</script></p>";
const clean = sanitizeHtml(html, {
    allowedTags: ["p", "b", "i", "strong"],
});
// => '<p>Text <b>bold</b> </p>'
```

### Per-Tag Attributes [#per-tag-attributes]

```typescript
import { sanitizeHtml } from "@visulima/html";

const html = '<a href="http://example.com" onclick="bad()">Link</a>';
const clean = sanitizeHtml(html, {
    allowedTags: ["a"],
    allowedAttributes: {
        a: ["href", "title"],
    },
});
// => '<a href="http://example.com">Link</a>'
```

### URL Scheme Filtering [#url-scheme-filtering]

```typescript
import { sanitizeHtml } from "@visulima/html";

const html = '<a href="javascript:alert(1)">Bad</a><a href="http://safe.com">Good</a>';
const clean = sanitizeHtml(html, {
    allowedTags: ["a"],
    allowedAttributes: { a: ["href"] },
    allowedSchemes: ["http", "https", "mailto"],
});
// => '<a>Bad</a><a href="http://safe.com">Good</a>'
```

### Iframe Whitelisting [#iframe-whitelisting]

```typescript
import { sanitizeHtml } from "@visulima/html";

const html = `
    <iframe src="https://www.youtube.com/embed/VIDEO"></iframe>
    <iframe src="https://evil.com/bad"></iframe>
`;

const clean = sanitizeHtml(html, {
    allowedTags: ["iframe"],
    allowedAttributes: { iframe: ["src"] },
    allowedIframeHostnames: ["www.youtube.com", "player.vimeo.com"],
});
// Only YouTube iframe preserved
```

### Transform Tags [#transform-tags]

```typescript
import { sanitizeHtml } from "@visulima/html";

const html = '<a href="http://example.com">Link</a>';
const clean = sanitizeHtml(html, {
    allowedTags: ["a"],
    allowedAttributes: { a: ["href"] },
    transformTags: {
        a: (tagName, attribs) => ({
            tagName: "a",
            attribs: {
                ...attribs,
                rel: "nofollow noopener",
                target: "_blank",
            },
        }),
    },
});
// => '<a href="http://example.com" rel="nofollow noopener" target="_blank">Link</a>'
```

### Rich Text Editor Config [#rich-text-editor-config]

```typescript
import { sanitizeHtml } from "@visulima/html";

function sanitizeRichText(html: string): string {
    return sanitizeHtml(html, {
        allowedTags: ["p", "br", "strong", "em", "u", "a", "ul", "ol", "li", "blockquote", "h1", "h2", "h3"],
        allowedAttributes: {
            a: ["href", "title"],
        },
        allowedSchemes: ["http", "https", "mailto"],
        transformTags: {
            a: (tagName, attribs) => ({
                tagName: "a",
                attribs: {
                    ...attribs,
                    rel: "nofollow noopener noreferrer",
                },
            }),
        },
    });
}
```

## HTML Tag Stripping [#html-tag-stripping]

### Basic Stripping [#basic-stripping]

```typescript
import { stripHtml } from "@visulima/html";

// Extract plain text
const html = "<div>Hello <b>World</b></div>";
const text = stripHtml(html).result;
// => 'Hello World'

// Preserves spaces between tags
const html2 = "aaa<div>bbb</div>ccc";
const text2 = stripHtml(html2).result;
// => 'aaa bbb ccc'
```

### Strip With Content [#strip-with-content]

```typescript
import { stripHtml } from "@visulima/html";

// Remove tags and their content
const html = 'Text <script>alert("bad")</script> more <style>css</style> text';
const text = stripHtml(html, {
    stripTogetherWithTheirContents: ["script", "style"],
}).result;
// => 'Text more text'

// Remove code blocks
const html2 = "Text <pre><code>code block</code></pre> more text";
const text2 = stripHtml(html2, {
    stripTogetherWithTheirContents: ["pre", "code"],
}).result;
// => 'Text more text'
```

### Preserve Legitimate Brackets [#preserve-legitimate-brackets]

```typescript
import { stripHtml } from "@visulima/html";

// Detects comparison operators
const text = "5 < 10 and 20 > 15";
const result = stripHtml(text).result;
// => '5 < 10 and 20 > 15'

// Mixed HTML and operators
const html = "Value <b>5</b> < 10";
const result2 = stripHtml(html).result;
// => 'Value 5 < 10'
```

### Email Text Extraction [#email-text-extraction]

```typescript
import { stripHtml } from "@visulima/html";

function extractEmailText(htmlEmail: string): string {
    return stripHtml(htmlEmail, {
        stripTogetherWithTheirContents: ["script", "style", "head", "title", "meta"],
    }).result;
}
```

## HTML Tag Lists [#html-tag-lists]

### Standard Tags [#standard-tags]

```typescript
import { htmlTags } from "@visulima/html";

// All standard HTML tags
console.log(htmlTags);
// => ['a', 'abbr', 'address', 'area', 'article', ...]

// Validate tag
const isStandardTag = htmlTags.includes("div");
// => true

// Filter allowed tags
const safeTags = htmlTags.filter((tag) => ["p", "a", "div", "span"].includes(tag));
```

### Void Tags [#void-tags]

```typescript
import { voidHtmlTags } from "@visulima/html";

// Self-closing tags
console.log(voidHtmlTags);
// => ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', ...]

// Check if self-closing
const isSelfClosing = voidHtmlTags.includes("br");
// => true

const needsClosing = !voidHtmlTags.includes("div");
// => true
```

### Sanitization Integration [#sanitization-integration]

```typescript
import { sanitizeHtml, htmlTags, voidHtmlTags } from "@visulima/html";

// Use tag lists for configuration
const clean = sanitizeHtml(dirtyHtml, {
    allowedTags: htmlTags.filter((tag) => ["p", "a", "b", "i", "div"].includes(tag)),
    selfClosing: voidHtmlTags,
});
```

## Practical Examples [#practical-examples]

### Comment System [#comment-system]

```typescript
import { escapeHtml, sanitizeHtml, html } from "@visulima/html";

interface Comment {
    id: string;
    author: string;
    content: string;
    isRichText: boolean;
}

function renderComment(comment: Comment): string {
    const safeAuthor = escapeHtml(comment.author);
    const safeContent = comment.isRichText
        ? sanitizeHtml(comment.content, {
              allowedTags: ["p", "b", "i", "a"],
              allowedAttributes: { a: ["href"] },
          })
        : escapeHtml(comment.content);

    return html`
        <div class="comment" data-id="${comment.id}">
            <strong>${safeAuthor}</strong>
            <div class="content">${safeContent}</div>
        </div>
    `;
}
```

### Form Input Display [#form-input-display]

```typescript
import { escapeHtml } from "@visulima/html";

function renderFormValue(fieldName: string, value: string): string {
    return `<input type="text" name="${escapeHtml(fieldName, true)}" value="${escapeHtml(value, true)}">`;
}
```

### Search Result Snippets [#search-result-snippets]

```typescript
import { stripHtml } from "@visulima/html";

function createSnippet(htmlContent: string, maxLength: number = 200): string {
    const plainText = stripHtml(htmlContent).result;
    const trimmed = plainText.substring(0, maxLength);
    return trimmed.length < plainText.length ? trimmed + "..." : trimmed;
}
```

### User Profile Bio [#user-profile-bio]

```typescript
import { sanitizeHtml } from "@visulima/html";

function saveBio(htmlBio: string): string {
    return sanitizeHtml(htmlBio, {
        allowedTags: ["p", "br", "b", "i", "a"],
        allowedAttributes: {
            a: ["href"],
        },
        allowedSchemes: ["http", "https"],
        transformTags: {
            a: (tagName, attribs) => ({
                tagName: "a",
                attribs: {
                    ...attribs,
                    rel: "nofollow",
                    target: "_blank",
                },
            }),
        },
    });
}
```


# Bytes API (/docs/packages/humanizer/api/bytes)



# Bytes API [#bytes-api]

Complete API reference for bytes formatting and parsing functions.

## formatBytes() [#formatbytes]

Formats numeric bytes into a human-readable string.

### Signature [#signature]

```typescript
function formatBytes(bytes: number, options?: FormateByteOptions): string;
```

### Parameters [#parameters]

#### bytes [#bytes]

* **Type:** `number`
* **Required:** Yes
* **Description:** The byte value to format

Must be a finite number. Non-finite values (Infinity, NaN) will throw a TypeError.

#### options [#options]

* **Type:** `FormateByteOptions`
* **Required:** No
* **Description:** Configuration options for formatting

### Options [#options-1]

#### decimals [#decimals]

* **Type:** `number`
* **Default:** `0`
* **Description:** Number of decimal places to show

```typescript
formatBytes(1234567, { decimals: 2 });
// => "1.18 MB"
```

#### locale [#locale]

* **Type:** `string`
* **Default:** `"en-US"`
* **Description:** Locale for number formatting (uses Intl.NumberFormat)

```typescript
formatBytes(1234567, { decimals: 2, locale: "de-DE" });
// => "1,18 MB"
```

#### long [#long]

* **Type:** `boolean`
* **Default:** `false`
* **Description:** Use long unit names instead of abbreviations

```typescript
formatBytes(1024, { long: true });
// => "1 Kilobytes"
```

#### units [#units]

* **Type:** `"metric" | "iec" | "metric_octet" | "iec_octet"`

* **Default:** `"metric"`

* **Description:** Unit system to use

* **`"metric"`**: KB, MB, GB (base 10: 1000)

* **`"iec"`**: KiB, MiB, GiB (base 2: 1024)

* **`"metric_octet"`**: ko, Mo, Go (French, base 10)

* **`"iec_octet"`**: Kio, Mio, Gio (French, base 2)

```typescript
formatBytes(1024, { units: "iec" });
// => "1 KiB"
```

#### base [#base]

* **Type:** `2 | 10`

* **Default:** `2`

* **Description:** Mathematical base for unit conversion

* **`2`**: Binary (1 KB = 1024 bytes)

* **`10`**: Decimal (1 KB = 1000 bytes)

```typescript
formatBytes(1000, { base: 10 });
// => "1 KB"
```

#### unit [#unit]

* **Type:** `string` (e.g., `"KB"`, `"MB"`, `"GB"`)
* **Default:** `undefined` (auto-detect)
* **Description:** Force output to a specific unit

```typescript
formatBytes(1234567, { unit: "KB", decimals: 2 });
// => "1,205.63 KB"
```

#### space [#space]

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Include space between value and unit

```typescript
formatBytes(1024, { space: false });
// => "1KB"
```

#### Additional Intl.NumberFormat Options [#additional-intlnumberformat-options]

All standard [Intl.NumberFormat options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) are supported:

* `notation`: `"standard" | "scientific" | "engineering" | "compact"`
* `useGrouping`: `boolean`
* `minimumFractionDigits`: `number`
* `maximumFractionDigits`: `number`
* And more...

```typescript
formatBytes(1234567890, {
    unit: "KB",
    notation: "scientific",
});
// => "1.234567890E6 KB"
```

### Returns [#returns]

* **Type:** `string`
* **Description:** Formatted byte string

### Throws [#throws]

* **TypeError:** If `bytes` is not a number
* **TypeError:** If `bytes` is not finite (NaN, Infinity)

### Examples [#examples]

```typescript
import { formatBytes } from "@visulima/humanizer";

// Basic usage
formatBytes(1024);
// => "1 KB"

// With decimals
formatBytes(1234567, { decimals: 2 });
// => "1.18 MB"

// German locale
formatBytes(1234567, { decimals: 2, locale: "de-DE" });
// => "1,18 MB"

// Long format
formatBytes(1024, { long: true });
// => "1 Kilobytes"

// IEC units
formatBytes(1024, { units: "iec" });
// => "1 KiB"

// Force specific unit
formatBytes(1234567, { unit: "KB", decimals: 2 });
// => "1,205.63 KB"

// Base 10
formatBytes(1000, { base: 10 });
// => "1 KB"
```

***

## parseBytes() [#parsebytes]

Parses a human-readable byte string into a numeric value.

### Signature [#signature-1]

```typescript
function parseBytes(value: string, options?: ParseByteOptions): number;
```

### Parameters [#parameters-1]

#### value [#value]

* **Type:** `string`
* **Required:** Yes
* **Description:** The byte string to parse

Examples: `"1 KB"`, `"1.5 MB"`, `"2GB"`, `"1 Megabytes"`

#### options [#options-2]

* **Type:** `ParseByteOptions`
* **Required:** No
* **Description:** Configuration options for parsing

### Options [#options-3]

#### locale [#locale-1]

* **Type:** `string`
* **Default:** `"en-US"`
* **Description:** Locale for parsing localized number formats

```typescript
parseBytes("117,70 MB", { locale: "de-DE" });
// => 123417395.2
```

#### units [#units-1]

* **Type:** `"metric" | "iec" | "metric_octet" | "iec_octet"`
* **Default:** `"metric"`
* **Description:** Unit system for parsing

```typescript
parseBytes("1 KiB", { units: "iec" });
// => 1024
```

#### base [#base-1]

* **Type:** `2 | 10`
* **Default:** `2`
* **Description:** Mathematical base for unit conversion

```typescript
parseBytes("1 KB", { base: 10 });
// => 1000
```

### Returns [#returns-1]

* **Type:** `number`
* **Description:** Byte value in numeric form
* **Special Values:** Returns `NaN` for invalid input

### Throws [#throws-1]

* **TypeError:** If `value` is not a string or is empty
* **TypeError:** If `value` exceeds 100 characters

### Examples [#examples-1]

```typescript
import { parseBytes } from "@visulima/humanizer";

// Basic usage
parseBytes("1 KB");
// => 1024

parseBytes("1.5 MB");
// => 1572864

// Case insensitive
parseBytes("1 kb");
// => 1024

// Without space
parseBytes("1MB");
// => 1048576

// Localized (German)
parseBytes("117,70 MB", { locale: "de-DE" });
// => 123417395.2

// IEC units
parseBytes("1 KiB", { units: "iec" });
// => 1024

// Base 10
parseBytes("1 KB", { base: 10 });
// => 1000

// Invalid input
parseBytes("invalid");
// => NaN
```

***

## Type Definitions [#type-definitions]

### FormateByteOptions [#formatebyteoptions]

```typescript
interface FormateByteOptions<T = string> {
    /**
     * Number of decimal places to display
     * @default 0
     */
    decimals?: number;

    /**
     * Locale for number formatting
     * @default "en-US"
     */
    locale?: string;

    /**
     * Use long unit names (e.g., "Megabytes" instead of "MB")
     * @default false
     */
    long?: boolean;

    /**
     * Unit system to use
     * @default "metric"
     */
    units?: "metric" | "iec" | "metric_octet" | "iec_octet";

    /**
     * Mathematical base for conversion (2 = binary, 10 = decimal)
     * @default 2
     */
    base?: 2 | 10;

    /**
     * Force a specific unit (e.g., "KB", "MB")
     */
    unit?: T;

    /**
     * Include space between value and unit
     * @default true
     */
    space?: boolean;

    /**
     * Additional Intl.NumberFormat options
     */
    notation?: "standard" | "scientific" | "engineering" | "compact";
    useGrouping?: boolean;
    minimumFractionDigits?: number;
    maximumFractionDigits?: number;
    // ... other Intl.NumberFormat options
}
```

### ParseByteOptions [#parsebyteoptions]

```typescript
interface ParseByteOptions {
    /**
     * Locale for parsing localized numbers
     * @default "en-US"
     */
    locale?: string;

    /**
     * Unit system for parsing
     * @default "metric"
     */
    units?: "metric" | "iec" | "metric_octet" | "iec_octet";

    /**
     * Mathematical base for conversion
     * @default 2
     */
    base?: 2 | 10;
}
```

### IntlLocale [#intllocale]

All CLDR locales are supported. Common examples:

```typescript
type IntlLocale = "en-US" | "en-GB" | "de-DE" | "fr-FR" | "es-ES" | "ja-JP" | "zh-CN";
// ... 700+ more locales
```

***

## Unit Reference [#unit-reference]

### Metric Units (Base 10) [#metric-units-base-10]

| Unit      | Short | Long      | Value                 |
| --------- | ----- | --------- | --------------------- |
| Bytes     | B     | Bytes     | 1                     |
| Kilobytes | KB    | Kilobytes | 1,000                 |
| Megabytes | MB    | Megabytes | 1,000,000             |
| Gigabytes | GB    | Gigabytes | 1,000,000,000         |
| Terabytes | TB    | Terabytes | 1,000,000,000,000     |
| Petabytes | PB    | Petabytes | 1,000,000,000,000,000 |

### IEC Units (Base 2) [#iec-units-base-2]

| Unit      | Short | Long      | Value                 |
| --------- | ----- | --------- | --------------------- |
| Bytes     | B     | Bytes     | 1                     |
| Kibibytes | KiB   | Kibibytes | 1,024                 |
| Mebibytes | MiB   | Mebibytes | 1,048,576             |
| Gibibytes | GiB   | Gibibytes | 1,073,741,824         |
| Tebibytes | TiB   | Tebibytes | 1,099,511,627,776     |
| Pebibytes | PiB   | Pebibytes | 1,125,899,906,842,624 |


# Duration API (/docs/packages/humanizer/api/duration)



# Duration API [#duration-api]

Complete API reference for duration formatting and parsing functions.

## duration() [#duration]

Formats milliseconds into a human-readable duration string.

### Signature [#signature]

```typescript
function duration(milliseconds: number, options?: DurationOptions): string;
```

### Parameters [#parameters]

#### milliseconds [#milliseconds]

* **Type:** `number`
* **Required:** Yes
* **Description:** The duration in milliseconds to format

Must be a valid number. NaN will throw a TypeError.

#### options [#options]

* **Type:** `DurationOptions`
* **Required:** No
* **Description:** Configuration options for formatting

### Options [#options-1]

#### units [#units]

* **Type:** `DurationUnitName[]`
* **Default:** `["w", "d", "h", "m", "s"]`
* **Description:** Array of units to use in output, in descending order

Valid units: `"y"`, `"mo"`, `"w"`, `"d"`, `"h"`, `"m"`, `"s"`, `"ms"`

```typescript
duration(97320000, { units: ["h", "m"] });
// => "27 hours, 2 minutes"
```

#### largest [#largest]

* **Type:** `number`
* **Default:** `Infinity`
* **Description:** Maximum number of units to display

```typescript
duration(1000000000000, { largest: 2 });
// => "31 years, 8 months"
```

#### round [#round]

* **Type:** `boolean`
* **Default:** `false`
* **Description:** Round the smallest unit to the nearest integer

```typescript
duration(1600, { round: true });
// => "2 seconds"
```

#### delimiter [#delimiter]

* **Type:** `string`
* **Default:** `", "` (or language-specific)
* **Description:** String to display between units

```typescript
duration(22140000, { delimiter: " and " });
// => "6 hours and 9 minutes"
```

#### spacer [#spacer]

* **Type:** `string`
* **Default:** `" "`
* **Description:** String to display between count and unit name

```typescript
duration(260040000, { spacer: " whole " });
// => "3 whole days, 14 whole minutes"
```

#### decimal [#decimal]

* **Type:** `string`
* **Default:** `"."` (or language-specific)
* **Description:** Decimal separator for fractional units

```typescript
duration(1200, { decimal: "," });
// => "1,2 seconds"
```

#### conjunction [#conjunction]

* **Type:** `string`
* **Default:** `""`
* **Description:** String to include before the final unit

```typescript
duration(22141000, { conjunction: " and " });
// => "6 hours, 9 minutes, and 1 second"
```

#### serialComma [#serialcomma]

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Include comma before conjunction

```typescript
duration(22141000, { conjunction: " and ", serialComma: false });
// => "6 hours, 9 minutes and 1 second"
```

#### maxDecimalPoints [#maxdecimalpoints]

* **Type:** `number`
* **Default:** `undefined` (no limit)
* **Description:** Maximum decimal points to show

```typescript
duration(8123.456789, { maxDecimalPoints: 2 });
// => "8.12 seconds"
```

#### digitReplacements [#digitreplacements]

* **Type:** `string[]` (array of 10 strings for digits 0-9)
* **Default:** `undefined` (or language-specific)
* **Description:** Custom digit characters

```typescript
duration(1234, {
    digitReplacements: ["Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine"],
});
// => "One.TwoThreeFour seconds"
```

#### language [#language]

* **Type:** `DurationLanguage`
* **Default:** English language object
* **Description:** Language object for localization

```typescript
import { durationLanguage as de } from "@visulima/humanizer/language/de";

duration(3000, { language: de });
// => "3 Sekunden"
```

#### unitMeasures [#unitmeasures]

* **Type:** `DurationUnitMeasures`
* **Default:** See table below
* **Description:** Custom unit lengths in milliseconds

```typescript
duration(2629800000, {
    unitMeasures: {
        y: 31557600000,
        mo: 30 * 86400000, // 30 days exactly
        w: 604800000,
        d: 86400000,
        h: 3600000,
        m: 60000,
        s: 1000,
        ms: 1,
    },
});
// => "1 month, 10 hours, 30 minutes"
```

**Default Unit Measures:**

| Unit | Milliseconds   | Description                               |
| ---- | -------------- | ----------------------------------------- |
| `y`  | 31,556,952,000 | 365.2425 days (accounting for leap years) |
| `mo` | 2,629,746,000  | 30.436875 days (365.2425 / 12)            |
| `w`  | 604,800,000    | 7 days                                    |
| `d`  | 86,400,000     | 24 hours                                  |
| `h`  | 3,600,000      | 60 minutes                                |
| `m`  | 60,000         | 60 seconds                                |
| `s`  | 1,000          | 1000 milliseconds                         |
| `ms` | 1              | Base unit                                 |

### Returns [#returns]

* **Type:** `string`
* **Description:** Formatted duration string

### Throws [#throws]

* **TypeError:** If `milliseconds` is NaN
* **TypeError:** If `milliseconds` is not a number

### Examples [#examples]

```typescript
import { duration } from "@visulima/humanizer";

// Basic usage
duration(3000);
// => "3 seconds"

duration(97320000);
// => "1 day, 3 hours, 2 minutes"

// Specific units
duration(97320000, { units: ["h", "m"] });
// => "27 hours, 2 minutes"

// Limit output
duration(1000000000000, { largest: 2 });
// => "31 years, 8 months"

// Rounding
duration(1600, { round: true });
// => "2 seconds"

// Custom delimiter
duration(22140000, { delimiter: " and " });
// => "6 hours and 9 minutes"

// Conjunction
duration(22141000, { conjunction: " and " });
// => "6 hours, 9 minutes, and 1 second"

// German language
import { durationLanguage as de } from "@visulima/humanizer/language/de";
duration(3000, { language: de });
// => "3 Sekunden"
```

***

## parseDuration() [#parseduration]

Parses a human-readable duration string into milliseconds.

### Signature [#signature-1]

```typescript
function parseDuration(value: string, options?: ParseDurationOptions): number | undefined;
```

### Parameters [#parameters-1]

#### value [#value]

* **Type:** `string`
* **Required:** Yes
* **Description:** The duration string to parse

Supported formats:

* **Natural language:** `"1 day, 3 hours, 2 minutes"`
* **Abbreviated:** `"2h 30m"`
* **Colon format:** `"1:25:05"` (H:MM:SS or MM:SS)
* **ISO 8601:** `"PT2H30M5S"`
* **Numeric:** `"1500"` (uses defaultUnit)

#### options [#options-2]

* **Type:** `ParseDurationOptions`
* **Required:** No
* **Description:** Configuration options for parsing

### Options [#options-3]

#### defaultUnit [#defaultunit]

* **Type:** `DurationUnit` (`"y" | "mo" | "w" | "d" | "h" | "m" | "s" | "ms"`)
* **Default:** `"ms"`
* **Description:** Unit to assume for numeric-only input

```typescript
parseDuration("1500");
// => 1500 (defaults to ms)

parseDuration("1500", { defaultUnit: "s" });
// => 1500000
```

#### language [#language-1]

* **Type:** `DurationLanguage`
* **Default:** English language object
* **Description:** Language object with unitMap for localized parsing

```typescript
import { durationLanguage as de } from "@visulima/humanizer/language/de";

parseDuration("3 Stunden", { language: de });
// => 10800000
```

### Returns [#returns-1]

* **Type:** `number | undefined`
* **Description:** Duration in milliseconds, or `undefined` if parsing fails

### Examples [#examples-1]

```typescript
import { parseDuration } from "@visulima/humanizer";

// Natural language
parseDuration("1 day, 3 hours, 2 minutes");
// => 97320000

// Abbreviated
parseDuration("2h 30m");
// => 9000000

// Colon format
parseDuration("1:25:05");
// => 5105000

parseDuration("15:30");
// => 930000

// ISO 8601
parseDuration("PT2H30M5S");
// => 9005000

// Negative duration
parseDuration("-3 weeks");
// => -1814400000

// Numeric with default unit
parseDuration("1500");
// => 1500

parseDuration("1500", { defaultUnit: "s" });
// => 1500000

// Localized (German)
import { durationLanguage as de } from "@visulima/humanizer/language/de";
parseDuration("3 Stunden", { language: de });
// => 10800000

// Invalid input
parseDuration("invalid");
// => undefined
```

***

## Type Definitions [#type-definitions]

### DurationOptions [#durationoptions]

```typescript
interface DurationOptions {
    /**
     * Units to use in output (must be in descending order)
     * @default ["w", "d", "h", "m", "s"]
     */
    units?: DurationUnitName[];

    /**
     * Maximum number of units to display
     * @default Infinity
     */
    largest?: number;

    /**
     * Round the smallest unit
     * @default false
     */
    round?: boolean;

    /**
     * Delimiter between units
     * @default ", "
     */
    delimiter?: string;

    /**
     * Spacer between count and unit
     * @default " "
     */
    spacer?: string;

    /**
     * Decimal separator
     * @default "."
     */
    decimal?: string;

    /**
     * Conjunction before final unit
     * @default ""
     */
    conjunction?: string;

    /**
     * Include comma before conjunction
     * @default true
     */
    serialComma?: boolean;

    /**
     * Maximum decimal points
     */
    maxDecimalPoints?: number;

    /**
     * Custom digit replacements (0-9)
     */
    digitReplacements?: DurationDigitReplacements;

    /**
     * Language object for localization
     */
    language?: DurationLanguage;

    /**
     * Custom unit measures in milliseconds
     */
    unitMeasures?: DurationUnitMeasures;
}
```

### ParseDurationOptions [#parsedurationoptions]

```typescript
interface ParseDurationOptions {
    /**
     * Default unit for numeric-only input
     * @default "ms"
     */
    defaultUnit?: DurationUnit;

    /**
     * Language object with unitMap for localized parsing
     */
    language?: DurationLanguage;
}
```

### DurationUnitName [#durationunitname]

```typescript
type DurationUnitName = "y" | "mo" | "w" | "d" | "h" | "m" | "s" | "ms";
```

### DurationUnit [#durationunit]

```typescript
type DurationUnit = DurationUnitName;
```

### DurationUnitMeasures [#durationunitmeasures]

```typescript
interface DurationUnitMeasures {
    y: number; // Years in milliseconds
    mo: number; // Months in milliseconds
    w: number; // Weeks in milliseconds
    d: number; // Days in milliseconds
    h: number; // Hours in milliseconds
    m: number; // Minutes in milliseconds
    s: number; // Seconds in milliseconds
    ms: number; // Milliseconds
}
```

### DurationLanguage [#durationlanguage]

```typescript
interface DurationLanguage {
    y: ((count: number) => string) | string;
    mo: ((count: number) => string) | string;
    w: ((count: number) => string) | string;
    d: ((count: number) => string) | string;
    h: ((count: number) => string) | string;
    m: ((count: number) => string) | string;
    s: ((count: number) => string) | string;
    ms: ((count: number) => string) | string;

    decimal?: string;
    delimiter?: string;
    unitMap?: Record<string, DurationUnitName>;
    // ... additional language-specific properties
}
```

### DurationDigitReplacements [#durationdigitreplacements]

```typescript
type DurationDigitReplacements = [
    string, // 0
    string, // 1
    string, // 2
    string, // 3
    string, // 4
    string, // 5
    string, // 6
    string, // 7
    string, // 8
    string, // 9
];
```

### DurationPiece [#durationpiece]

```typescript
interface DurationPiece {
    unitCount: number;
    unitName: DurationUnitName;
}
```

***

## Supported Languages [#supported-languages]

The following languages are available as language packs:

| Language             | Code    | Import                               |
| -------------------- | ------- | ------------------------------------ |
| English              | `en`    | `@visulima/humanizer/language/en`    |
| German               | `de`    | `@visulima/humanizer/language/de`    |
| Spanish              | `es`    | `@visulima/humanizer/language/es`    |
| French               | `fr`    | `@visulima/humanizer/language/fr`    |
| Japanese             | `ja`    | `@visulima/humanizer/language/ja`    |
| Chinese (Simplified) | `zh_CN` | `@visulima/humanizer/language/zh_CN` |
| Russian              | `ru`    | `@visulima/humanizer/language/ru`    |
| Arabic               | `ar`    | `@visulima/humanizer/language/ar`    |
| Portuguese           | `pt`    | `@visulima/humanizer/language/pt`    |
| Italian              | `it`    | `@visulima/humanizer/language/it`    |

See the [README](https://github.com/visulima/visulima/tree/main/packages/data-manipulation/humanizer#supported-languages) for the complete list of 50+ supported languages.

### Example Usage [#example-usage]

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as es } from "@visulima/humanizer/language/es";

duration(3000, { language: de });
// => "3 Sekunden"

duration(3000, { language: es });
// => "3 segundos"
```


# TypeScript Types (/docs/packages/humanizer/api/types)



# TypeScript Types [#typescript-types]

Complete TypeScript type definitions for @visulima/humanizer.

## Bytes Types [#bytes-types]

### FormateByteOptions [#formatebyteoptions]

Options for formatting bytes to strings.

```typescript
interface FormateByteOptions<T = string> {
    /**
     * Number of decimal places to display
     * @default 0
     */
    decimals?: number;

    /**
     * Locale for number formatting (uses Intl.NumberFormat)
     * @default "en-US"
     */
    locale?: string;

    /**
     * Use long unit names (e.g., "Megabytes" instead of "MB")
     * @default false
     */
    long?: boolean;

    /**
     * Unit system to use
     * - "metric": KB, MB, GB (base 10)
     * - "iec": KiB, MiB, GiB (base 2)
     * - "metric_octet": ko, Mo, Go (French, base 10)
     * - "iec_octet": Kio, Mio, Gio (French, base 2)
     * @default "metric"
     */
    units?: "metric" | "iec" | "metric_octet" | "iec_octet";

    /**
     * Mathematical base for conversion
     * - 2: Binary (1 KB = 1024 bytes)
     * - 10: Decimal (1 KB = 1000 bytes)
     * @default 2
     */
    base?: 2 | 10;

    /**
     * Force output to a specific unit (e.g., "KB", "MB")
     */
    unit?: T;

    /**
     * Include space between value and unit
     * @default true
     */
    space?: boolean;

    // Additional Intl.NumberFormat options
    notation?: "standard" | "scientific" | "engineering" | "compact";
    useGrouping?: boolean;
    minimumFractionDigits?: number;
    maximumFractionDigits?: number;
    minimumIntegerDigits?: number;
    minimumSignificantDigits?: number;
    maximumSignificantDigits?: number;
}
```

### ParseByteOptions [#parsebyteoptions]

Options for parsing byte strings to numbers.

```typescript
interface ParseByteOptions {
    /**
     * Locale for parsing localized numbers
     * @default "en-US"
     */
    locale?: string;

    /**
     * Unit system for parsing
     * @default "metric"
     */
    units?: "metric" | "iec" | "metric_octet" | "iec_octet";

    /**
     * Mathematical base for conversion
     * @default 2
     */
    base?: 2 | 10;
}
```

### IntlLocale [#intllocale]

Type representing all supported CLDR locales.

```typescript
type IntlLocale =
    | "af"
    | "af-NA"
    | "ar"
    | "ar-AE"
    | "ar-SA"
    | "de"
    | "de-DE"
    | "de-AT"
    | "de-CH"
    | "en"
    | "en-US"
    | "en-GB"
    | "en-AU"
    | "en-CA"
    | "es"
    | "es-ES"
    | "es-MX"
    | "fr"
    | "fr-FR"
    | "fr-CA"
    | "ja"
    | "ja-JP"
    | "zh"
    | "zh-CN"
    | "zh-TW";
// ... 700+ more locales
```

## Duration Types [#duration-types]

### DurationOptions [#durationoptions]

Options for formatting durations to strings.

```typescript
interface DurationOptions {
    /**
     * Units to use in output (must be in descending order)
     * @default ["w", "d", "h", "m", "s"]
     */
    units?: DurationUnitName[];

    /**
     * Maximum number of units to display
     * @default Infinity
     */
    largest?: number;

    /**
     * Round the smallest unit to nearest integer
     * @default false
     */
    round?: boolean;

    /**
     * Delimiter between units
     * @default ", " (or language-specific)
     */
    delimiter?: string;

    /**
     * Spacer between count and unit name
     * @default " "
     */
    spacer?: string;

    /**
     * Decimal separator
     * @default "." (or language-specific)
     */
    decimal?: string;

    /**
     * Conjunction before final unit
     * @default ""
     */
    conjunction?: string;

    /**
     * Include comma before conjunction
     * @default true
     */
    serialComma?: boolean;

    /**
     * Maximum decimal points to show
     */
    maxDecimalPoints?: number;

    /**
     * Custom digit replacements (0-9)
     */
    digitReplacements?: DurationDigitReplacements;

    /**
     * Language object for localization
     * @default English
     */
    language?: DurationLanguage;

    /**
     * Custom unit measures in milliseconds
     */
    unitMeasures?: DurationUnitMeasures;
}
```

### ParseDurationOptions [#parsedurationoptions]

Options for parsing duration strings to milliseconds.

```typescript
interface ParseDurationOptions {
    /**
     * Default unit for numeric-only input
     * @default "ms"
     */
    defaultUnit?: DurationUnit;

    /**
     * Language object with unitMap for localized parsing
     */
    language?: DurationLanguage;
}
```

### DurationUnitName [#durationunitname]

Valid duration unit names.

```typescript
type DurationUnitName = "y" | "mo" | "w" | "d" | "h" | "m" | "s" | "ms";
```

**Description:**

* `y`: Years
* `mo`: Months
* `w`: Weeks
* `d`: Days
* `h`: Hours
* `m`: Minutes
* `s`: Seconds
* `ms`: Milliseconds

### DurationUnit [#durationunit]

Alias for DurationUnitName.

```typescript
type DurationUnit = DurationUnitName;
```

### DurationUnitMeasures [#durationunitmeasures]

Unit lengths in milliseconds.

```typescript
interface DurationUnitMeasures {
    /**
     * Years in milliseconds
     * @default 31556952000 (365.2425 days)
     */
    y: number;

    /**
     * Months in milliseconds
     * @default 2629746000 (30.436875 days)
     */
    mo: number;

    /**
     * Weeks in milliseconds
     * @default 604800000 (7 days)
     */
    w: number;

    /**
     * Days in milliseconds
     * @default 86400000 (24 hours)
     */
    d: number;

    /**
     * Hours in milliseconds
     * @default 3600000 (60 minutes)
     */
    h: number;

    /**
     * Minutes in milliseconds
     * @default 60000 (60 seconds)
     */
    m: number;

    /**
     * Seconds in milliseconds
     * @default 1000
     */
    s: number;

    /**
     * Milliseconds
     * @default 1
     */
    ms: number;
}
```

### DurationLanguage [#durationlanguage]

Language object for duration localization.

```typescript
interface DurationLanguage {
    /**
     * Year unit name(s)
     * Can be a string or function that returns appropriate form based on count
     */
    y: ((count: number) => string) | string;

    /**
     * Month unit name(s)
     */
    mo: ((count: number) => string) | string;

    /**
     * Week unit name(s)
     */
    w: ((count: number) => string) | string;

    /**
     * Day unit name(s)
     */
    d: ((count: number) => string) | string;

    /**
     * Hour unit name(s)
     */
    h: ((count: number) => string) | string;

    /**
     * Minute unit name(s)
     */
    m: ((count: number) => string) | string;

    /**
     * Second unit name(s)
     */
    s: ((count: number) => string) | string;

    /**
     * Millisecond unit name(s)
     */
    ms: ((count: number) => string) | string;

    /**
     * Decimal separator
     * @default "."
     */
    decimal?: string;

    /**
     * Delimiter between units
     * @default ", "
     */
    delimiter?: string;

    /**
     * Unit map for parsing localized strings
     * Maps localized unit names to unit codes
     */
    unitMap?: Record<string, DurationUnitName>;

    /**
     * Custom digit replacements (0-9)
     */
    _digitReplacements?: DurationDigitReplacements;

    /**
     * Hide count when value is 2
     * Used in some languages (e.g., Welsh)
     * @internal
     */
    _hideCountIf2?: boolean;

    /**
     * Display number before unit (e.g., "seconds 3" instead of "3 seconds")
     * @internal
     */
    _numberFirst?: boolean;

    /**
     * Past tense template (e.g., "%s ago")
     */
    past?: string;

    /**
     * Future tense template (e.g., "in %s")
     */
    future?: string;
}
```

### DurationDigitReplacements [#durationdigitreplacements]

Array of 10 strings representing digits 0-9.

```typescript
type DurationDigitReplacements = [
    string, // 0
    string, // 1
    string, // 2
    string, // 3
    string, // 4
    string, // 5
    string, // 6
    string, // 7
    string, // 8
    string, // 9
];
```

**Example:**

```typescript
const arabicDigits: DurationDigitReplacements = ["۰", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"];
```

### DurationPiece [#durationpiece]

Internal representation of a duration component.

```typescript
interface DurationPiece {
    /**
     * The numeric count for this unit
     */
    unitCount: number;

    /**
     * The unit name
     */
    unitName: DurationUnitName;
}
```

## Usage Examples [#usage-examples]

### Type-Safe Formatting [#type-safe-formatting]

```typescript
import type { FormateByteOptions, DurationOptions } from "@visulima/humanizer";

const byteOptions: FormateByteOptions = {
    decimals: 2,
    locale: "de-DE",
    units: "metric",
    base: 2,
};

const durationOptions: DurationOptions = {
    units: ["h", "m", "s"],
    largest: 2,
    round: true,
};
```

### Custom Language Type [#custom-language-type]

```typescript
import type { DurationLanguage } from "@visulima/humanizer";

const customLanguage: DurationLanguage = {
    y: (count) => (count === 1 ? "year" : "years"),
    mo: (count) => (count === 1 ? "month" : "months"),
    w: (count) => (count === 1 ? "week" : "weeks"),
    d: (count) => (count === 1 ? "day" : "days"),
    h: (count) => (count === 1 ? "hour" : "hours"),
    m: (count) => (count === 1 ? "minute" : "minutes"),
    s: (count) => (count === 1 ? "second" : "seconds"),
    ms: (count) => (count === 1 ? "millisecond" : "milliseconds"),
    decimal: ".",
    delimiter: ", ",
};
```

### Unit Measures Type [#unit-measures-type]

```typescript
import type { DurationUnitMeasures } from "@visulima/humanizer";

const customUnits: DurationUnitMeasures = {
    y: 31557600000,
    mo: 30 * 86400000, // Exactly 30 days
    w: 604800000,
    d: 86400000,
    h: 3600000,
    m: 60000,
    s: 1000,
    ms: 1,
};
```

### Type Guards [#type-guards]

```typescript
import type { DurationUnit, IntlLocale } from "@visulima/humanizer";

function isValidDurationUnit(unit: string): unit is DurationUnit {
    return ["y", "mo", "w", "d", "h", "m", "s", "ms"].includes(unit);
}

function isValidLocale(locale: string): locale is IntlLocale {
    try {
        new Intl.NumberFormat(locale);
        return true;
    } catch {
        return false;
    }
}
```

## Type Imports [#type-imports]

Import types as needed:

```typescript
// Individual types
import type { FormateByteOptions } from "@visulima/humanizer";
import type { DurationOptions } from "@visulima/humanizer";

// Multiple types
import type { FormateByteOptions, ParseByteOptions, DurationOptions, DurationLanguage } from "@visulima/humanizer";

// All types
import type * as Humanizer from "@visulima/humanizer";
```


# Localization (/docs/packages/humanizer/concepts/localization)



# Localization [#localization]

@visulima/humanizer provides comprehensive localization support for both bytes and duration formatting, handling number formatting, unit names, and cultural conventions across hundreds of locales and languages.

## Bytes Localization [#bytes-localization]

### Locale-Based Number Formatting [#locale-based-number-formatting]

Bytes formatting uses `Intl.NumberFormat` to format numbers according to locale conventions:

```typescript
import { formatBytes } from "@visulima/humanizer";

// English (period as decimal separator)
formatBytes(123412341, { decimals: 2, locale: "en-US" });
// => "117.70 MB"

// German (comma as decimal separator)
formatBytes(123412341, { decimals: 2, locale: "de-DE" });
// => "117,70 MB"

// French (space as thousand separator)
formatBytes(123412341, { decimals: 2, locale: "fr-FR" });
// => "117,70 Mo"
```

### Parsing Localized Input [#parsing-localized-input]

The `parseBytes` function automatically handles locale-specific number formats:

```typescript
import { parseBytes } from "@visulima/humanizer";

// Parse German format (comma decimal)
parseBytes("117,70 MB", { locale: "de-DE" });
// => 123417395.2

// Parse French format (space thousand separator)
parseBytes("1 234,56 MB", { locale: "fr-FR" });
// => 1294409441.28
```

### Supported Locales for Bytes [#supported-locales-for-bytes]

formatBytes and parseBytes support **700+ locales** including:

* **Major variants:** en-US, en-GB, de-DE, fr-FR, es-ES, pt-BR, zh-CN, ja-JP, ko-KR
* **Regional variants:** en-AU, en-CA, en-IN, es-MX, pt-PT, fr-CA, zh-TW
* **All CLDR locales:** Complete support for all Unicode CLDR locales

## Duration Localization [#duration-localization]

### Language Objects [#language-objects]

Duration formatting uses language objects for translating unit names and formatting rules:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as es } from "@visulima/humanizer/language/es";
import { durationLanguage as ja } from "@visulima/humanizer/language/ja";

// German
duration(3600000, { language: de });
// => "1 Stunde"

// Spanish
duration(3600000, { language: es });
// => "1 hora"

// Japanese
duration(3600000, { language: ja });
// => "1 時間"
```

### Supported Languages for Duration [#supported-languages-for-duration]

Duration formatting supports **50+ languages**:

| Language             | Code    | Example Output |
| -------------------- | ------- | -------------- |
| English              | `en`    | "3 seconds"    |
| German               | `de`    | "3 Sekunden"   |
| Spanish              | `es`    | "3 segundos"   |
| French               | `fr`    | "3 secondes"   |
| Japanese             | `ja`    | "3 秒"          |
| Chinese (Simplified) | `zh_CN` | "3 秒"          |
| Russian              | `ru`    | "3 секунды"    |
| Arabic               | `ar`    | "٣ ثواني"      |

See [installation guide](/docs/packages/humanizer/installation#language-packs-duration) for the complete list.

### Custom Language Objects [#custom-language-objects]

Create custom language objects for unsupported languages or specialized formatting:

```typescript
import { duration } from "@visulima/humanizer";
import type { DurationLanguage } from "@visulima/humanizer";

const customLanguage: DurationLanguage = {
    y: (count) => (count === 1 ? "year" : "years"),
    mo: (count) => (count === 1 ? "month" : "months"),
    w: (count) => (count === 1 ? "week" : "weeks"),
    d: (count) => (count === 1 ? "day" : "days"),
    h: (count) => (count === 1 ? "hour" : "hours"),
    m: (count) => (count === 1 ? "minute" : "minutes"),
    s: (count) => (count === 1 ? "second" : "seconds"),
    ms: (count) => (count === 1 ? "millisecond" : "milliseconds"),
    decimal: ".",
};

duration(1000, { language: customLanguage });
// => "1 second"

duration(5000, { language: customLanguage });
// => "5 seconds"
```

### Parsing Localized Duration Strings [#parsing-localized-duration-strings]

Use language objects with unitMap for parsing localized duration strings:

```typescript
import { parseDuration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as ru } from "@visulima/humanizer/language/ru";

// Parse German duration
parseDuration("3 Stunden", { language: de });
// => 10800000

// Parse Russian duration
parseDuration("5 часов, 10 минут", { language: ru });
// => 18600000
```

## Cultural Formatting Conventions [#cultural-formatting-conventions]

### Delimiters and Conjunctions [#delimiters-and-conjunctions]

Different languages use different delimiters and conjunctions:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as ar } from "@visulima/humanizer/language/ar";

// Arabic uses different delimiter
duration(22140000, { language: ar });
// => "6 ساعات ﻭ 9 دقائق"
// (Uses " ﻭ " as delimiter instead of ", ")
```

### Digit Replacements [#digit-replacements]

Some languages use different numeral systems:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as ar } from "@visulima/humanizer/language/ar";

// Arabic numerals
duration(1234, { language: ar });
// => "١.٢٣٤ ثانية"
// (Uses Arabic-Indic digits ١٢٣٤ instead of 1234)
```

### Decimal Separators [#decimal-separators]

Decimal separators vary by language:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as en } from "@visulima/humanizer/language/en";

// German uses comma
duration(1500, { language: de });
// => "1,5 Sekunden"

// English uses period
duration(1500, { language: en });
// => "1.5 seconds"
```

## Best Practices [#best-practices]

### Match User Locale [#match-user-locale]

Always use the user's locale for the best experience:

```typescript
import { formatBytes, duration } from "@visulima/humanizer";

function formatForUser(bytes: number, ms: number, userLocale: string) {
    // Get language code from locale (e.g., "de" from "de-DE")
    const langCode = userLocale.split("-")[0];

    // Dynamically import language
    import(`@visulima/humanizer/language/${langCode}`).then(({ durationLanguage }) => {
        const formattedBytes = formatBytes(bytes, { locale: userLocale });
        const formattedDuration = duration(ms, { language: durationLanguage });

        console.log(`Size: ${formattedBytes}, Time: ${formattedDuration}`);
    });
}
```

### Fallback to English [#fallback-to-english]

Provide a fallback to English for unsupported locales:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as en } from "@visulima/humanizer/language/en";

async function getDurationLanguage(locale: string) {
    const langCode = locale.split("-")[0];

    try {
        const module = await import(`@visulima/humanizer/language/${langCode}`);
        return module.durationLanguage;
    } catch {
        // Fallback to English
        return en;
    }
}

const language = await getDurationLanguage("pt-BR");
duration(5000, { language });
```

### Test with Multiple Locales [#test-with-multiple-locales]

Always test your application with various locales to ensure proper formatting:

```typescript
import { formatBytes } from "@visulima/humanizer";

const testLocales = ["en-US", "de-DE", "fr-FR", "ja-JP", "ar-SA"];

for (const locale of testLocales) {
    console.log(`${locale}: ${formatBytes(1234567, { locale, decimals: 2 })}`);
}
// en-US: 1.18 MB
// de-DE: 1,18 MB
// fr-FR: 1,18 Mo
// ja-JP: 1.18 MB
// ar-SA: ١٫١٨ م.ب
```


# Unit Systems (/docs/packages/humanizer/concepts/unit-systems)



# Unit Systems [#unit-systems]

Understanding the different unit systems and measurement bases used for bytes and duration formatting.

## Byte Unit Systems [#byte-unit-systems]

@visulima/humanizer supports four different unit systems for byte formatting, each with different naming conventions and use cases.

### Metric (Base 10) [#metric-base-10]

The metric system uses powers of 1000 (base 10) and standard SI prefixes:

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1000, { units: "metric", base: 10 });
// => "1 KB"

formatBytes(1000000, { units: "metric", base: 10 });
// => "1 MB"

formatBytes(1000000000, { units: "metric", base: 10 });
// => "1 GB"
```

**Units:** B → KB → MB → GB → TB → PB → EB → ZB → YB

**Use case:** Hard drive manufacturers, networking (bandwidth)

### IEC (Base 2) [#iec-base-2]

The IEC system uses powers of 1024 (base 2) with binary prefixes:

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1024, { units: "iec", base: 2 });
// => "1 KiB"

formatBytes(1048576, { units: "iec", base: 2 });
// => "1 MiB"

formatBytes(1073741824, { units: "iec", base: 2 });
// => "1 GiB"
```

**Units:** B → KiB → MiB → GiB → TiB → PiB → EiB → ZiB → YiB

**Use case:** Operating systems, memory, file sizes

### Metric Octet (Base 10, French) [#metric-octet-base-10-french]

French variant using "octets" instead of "bytes":

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1000, { units: "metric_octet", base: 10, locale: "fr-FR" });
// => "1 ko"

formatBytes(1000000, { units: "metric_octet", base: 10, locale: "fr-FR" });
// => "1 Mo"
```

**Units:** o → ko → Mo → Go → To → Po → Eo → Zo → Yo

**Use case:** French-language applications and documentation

### IEC Octet (Base 2, French) [#iec-octet-base-2-french]

French variant with binary prefixes:

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1024, { units: "iec_octet", base: 2, locale: "fr-FR" });
// => "1 Kio"

formatBytes(1048576, { units: "iec_octet", base: 2, locale: "fr-FR" });
// => "1 Mio"
```

**Units:** o → Kio → Mio → Gio → Tio → Pio → Eio → Zio → Yio

**Use case:** French-language system tools and applications

## Base Conversion [#base-conversion]

The choice of base (2 or 10) significantly affects the output:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1073741824; // 1 GiB in binary

// Base 2 (binary, 1024)
formatBytes(bytes, { base: 2, units: "iec" });
// => "1 GiB"

// Base 10 (decimal, 1000)
formatBytes(bytes, { base: 10, units: "metric" });
// => "1.07 GB"
```

### When to Use Each Base [#when-to-use-each-base]

**Base 2 (1024):**

* File sizes in operating systems
* Memory (RAM, cache)
* Internal storage calculations

**Base 10 (1000):**

* Hard drive capacity (manufacturer specifications)
* Network bandwidth
* Marketing and sales materials

## Duration Units [#duration-units]

Duration formatting supports various time units with customizable measures.

### Available Units [#available-units]

```typescript
import { duration } from "@visulima/humanizer";

// Milliseconds
duration(500, { units: ["ms"] });
// => "500 milliseconds"

// Seconds
duration(5000, { units: ["s"] });
// => "5 seconds"

// Minutes
duration(300000, { units: ["m"] });
// => "5 minutes"

// Hours
duration(7200000, { units: ["h"] });
// => "2 hours"

// Days
duration(172800000, { units: ["d"] });
// => "2 days"

// Weeks
duration(1209600000, { units: ["w"] });
// => "2 weeks"

// Months
duration(5259600000, { units: ["mo"] });
// => "2 months"

// Years
duration(63113904000, { units: ["y"] });
// => "2 years"
```

### Unit Order and Hierarchy [#unit-order-and-hierarchy]

Units must be specified in descending order of size:

```typescript
import { duration } from "@visulima/humanizer";

// ✅ Correct: Descending order
duration(90061000, { units: ["d", "h", "m", "s"] });
// => "1 day, 1 hour, 1 minute, 1 second"

// ❌ Incorrect: Ascending order (will not work as expected)
duration(90061000, { units: ["s", "m", "h", "d"] });
// Output may be incorrect
```

### Custom Unit Measures [#custom-unit-measures]

Override default unit lengths for specialized use cases:

```typescript
import { duration } from "@visulima/humanizer";

// Default: Month = 30.436875 days
duration(2629800000);
// => "1 month"

// Custom: Month = 30 days exactly
duration(2629800000, {
    unitMeasures: {
        y: 31557600000,
        mo: 30 * 86400000, // 30 days
        w: 604800000,
        d: 86400000,
        h: 3600000,
        m: 60000,
        s: 1000,
        ms: 1,
    },
});
// => "1 month, 10 hours, 30 minutes"
```

### Default Unit Measures [#default-unit-measures]

The default unit measures use astronomically accurate values:

| Unit             | Value             | Calculation                             |
| ---------------- | ----------------- | --------------------------------------- |
| Year (y)         | 31,556,952,000 ms | 365.2425 days (accounts for leap years) |
| Month (mo)       | 2,629,746,000 ms  | 30.436875 days (365.2425/12)            |
| Week (w)         | 604,800,000 ms    | 7 days                                  |
| Day (d)          | 86,400,000 ms     | 24 hours                                |
| Hour (h)         | 3,600,000 ms      | 60 minutes                              |
| Minute (m)       | 60,000 ms         | 60 seconds                              |
| Second (s)       | 1,000 ms          | 1000 milliseconds                       |
| Millisecond (ms) | 1 ms              | Base unit                               |

## Choosing the Right System [#choosing-the-right-system]

### For Bytes [#for-bytes]

```typescript
import { formatBytes } from "@visulima/humanizer";

function formatFileSize(bytes: number, context: "os" | "web" | "network") {
    switch (context) {
        case "os":
            // Operating system file sizes
            return formatBytes(bytes, { units: "iec", base: 2 });

        case "web":
            // Web applications, general use
            return formatBytes(bytes, { units: "metric", base: 10 });

        case "network":
            // Network bandwidth
            return formatBytes(bytes, { units: "metric", base: 10 });

        default:
            return formatBytes(bytes);
    }
}
```

### For Duration [#for-duration]

```typescript
import { duration } from "@visulima/humanizer";

function formatDuration(ms: number, precision: "coarse" | "medium" | "fine") {
    switch (precision) {
        case "coarse":
            // Years, months, days
            return duration(ms, { units: ["y", "mo", "d"], largest: 2 });

        case "medium":
            // Hours, minutes, seconds
            return duration(ms, { units: ["h", "m", "s"], largest: 2 });

        case "fine":
            // Seconds, milliseconds
            return duration(ms, { units: ["s", "ms"], largest: 2 });

        default:
            return duration(ms);
    }
}
```

## Best Practices [#best-practices]

### Be Consistent [#be-consistent]

Use the same unit system throughout your application:

```typescript
import { formatBytes } from "@visulima/humanizer";

// ✅ Good: Consistent base and units
const config = { base: 2, units: "iec" } as const;

formatBytes(1024, config);
formatBytes(2048, config);
formatBytes(4096, config);
```

### Document Your Choice [#document-your-choice]

Make it clear which unit system you're using:

```typescript
/**
 * Formats file size using IEC binary prefixes (KiB, MiB, GiB).
 * 1 KiB = 1024 bytes (not 1000).
 */
function formatFileSize(bytes: number): string {
    return formatBytes(bytes, { base: 2, units: "iec", decimals: 2 });
}
```

### Match Platform Conventions [#match-platform-conventions]

Use the unit system appropriate for your platform:

```typescript
import { formatBytes } from "@visulima/humanizer";

const isWindows = process.platform === "win32";
const isMacOS = process.platform === "darwin";

function formatSystemFileSize(bytes: number): string {
    // macOS uses decimal (1 MB = 1,000,000 bytes)
    if (isMacOS) {
        return formatBytes(bytes, { base: 10, units: "metric" });
    }

    // Windows uses binary (1 MB = 1,048,576 bytes)
    return formatBytes(bytes, { base: 2, units: "iec" });
}
```


# Configuration (/docs/packages/humanizer/configuration)



# Configuration [#configuration]

Comprehensive configuration guide for customizing bytes and duration formatting.

## Bytes Configuration [#bytes-configuration]

### Number Formatting [#number-formatting]

Control how numbers are displayed using standard Intl.NumberFormat options.

#### Decimal Precision [#decimal-precision]

```typescript
import { formatBytes } from "@visulima/humanizer";

// No decimals (default)
formatBytes(1234567);
// => "1 MB"

// 2 decimal places
formatBytes(1234567, { decimals: 2 });
// => "1.18 MB"

// Fixed decimal places with Intl options
formatBytes(1234567, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
});
// => "1.18 MB"
```

#### Grouping Separators [#grouping-separators]

```typescript
import { formatBytes } from "@visulima/humanizer";

// With grouping (default)
formatBytes(1234567890, { unit: "KB", useGrouping: true });
// => "1,205,632 KB"

// Without grouping
formatBytes(1234567890, { unit: "KB", useGrouping: false });
// => "1205632 KB"
```

#### Scientific Notation [#scientific-notation]

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1234567890, {
    unit: "B",
    notation: "scientific",
});
// => "1.234567890E9 B"

formatBytes(1234567890, {
    unit: "B",
    notation: "engineering",
});
// => "1.234567890E9 B"

formatBytes(1234567890, {
    notation: "compact",
});
// => "1.2B B"
```

### Unit System Selection [#unit-system-selection]

Choose the appropriate unit system for your use case.

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1073741824;

// Metric (decimal, 1000-based)
formatBytes(bytes, { units: "metric", base: 10 });
// => "1.07 GB"

// IEC (binary, 1024-based)
formatBytes(bytes, { units: "iec", base: 2 });
// => "1 GiB"

// French octet variants
formatBytes(bytes, { units: "metric_octet", locale: "fr-FR" });
// => "1,07 Go"

formatBytes(bytes, { units: "iec_octet", locale: "fr-FR" });
// => "1 Gio"
```

### Locale Settings [#locale-settings]

```typescript
import { formatBytes, parseBytes } from "@visulima/humanizer";

// Application-wide locale configuration
const userLocale = navigator.language || "en-US";

function formatFileSize(bytes: number): string {
    return formatBytes(bytes, {
        decimals: 2,
        locale: userLocale,
    });
}

function parseFileSize(input: string): number {
    return parseBytes(input, { locale: userLocale });
}
```

### Custom Configuration Objects [#custom-configuration-objects]

Create reusable configuration objects:

```typescript
import type { FormateByteOptions } from "@visulima/humanizer";

// Configuration for file sizes in UI
const uiByteConfig: FormateByteOptions = {
    decimals: 1,
    units: "iec",
    base: 2,
    long: false,
};

// Configuration for technical documentation
const docsByteConfig: FormateByteOptions = {
    decimals: 2,
    units: "metric",
    base: 10,
    long: true,
};

// Configuration for French locale
const frenchByteConfig: FormateByteOptions = {
    decimals: 2,
    locale: "fr-FR",
    units: "metric_octet",
    base: 10,
};
```

## Duration Configuration [#duration-configuration]

### Unit Selection [#unit-selection]

Control which units appear in the output.

```typescript
import { duration } from "@visulima/humanizer";

const ms = 97320000;

// Default units (weeks, days, hours, minutes, seconds)
duration(ms);
// => "1 day, 3 hours, 2 minutes"

// Hours and minutes only
duration(ms, { units: ["h", "m"] });
// => "27 hours, 2 minutes"

// Full precision
duration(ms, { units: ["d", "h", "m", "s", "ms"] });
// => "1 day, 3 hours, 2 minutes"

// Coarse granularity (years, months, weeks)
duration(ms, { units: ["y", "mo", "w", "d"] });
// => "1 day"
```

### Output Limiting [#output-limiting]

```typescript
import { duration } from "@visulima/humanizer";

const ms = 1000000000000;

// Show all units (very long)
duration(ms);
// => "31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds"

// Show only top 2 units
duration(ms, { largest: 2 });
// => "31 years, 8 months"

// Show only top 3 units
duration(ms, { largest: 3 });
// => "31 years, 8 months, 1 week"
```

### Rounding Strategy [#rounding-strategy]

```typescript
import { duration } from "@visulima/humanizer";

const ms = 1234.56;

// No rounding (show decimals)
duration(ms);
// => "1.23456 seconds"

// Round to nearest integer
duration(ms, { round: true });
// => "1 second"

// Control decimals without rounding
duration(ms, { maxDecimalPoints: 2 });
// => "1.23 seconds"

// Combine rounding with largest
duration(97380000, { largest: 2, round: true });
// => "1 day, 3 hours"
```

### Text Formatting [#text-formatting]

Customize delimiters, conjunctions, and spacing.

```typescript
import { duration } from "@visulima/humanizer";

const ms = 22141000;

// Default formatting
duration(ms);
// => "6 hours, 9 minutes, 1 second"

// Custom delimiter
duration(ms, { delimiter: " and " });
// => "6 hours and 9 minutes and 1 second"

// Conjunction before last unit
duration(ms, { conjunction: " and " });
// => "6 hours, 9 minutes, and 1 second"

// No serial comma
duration(ms, { conjunction: " and ", serialComma: false });
// => "6 hours, 9 minutes and 1 second"

// Custom spacer
duration(260040000, { spacer: " whole " });
// => "3 whole days, 14 whole minutes"
```

### Language Configuration [#language-configuration]

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as es } from "@visulima/humanizer/language/es";

// Application-wide language setting
const userLanguage = getUserPreferredLanguage();

async function getDurationLanguage(langCode: string) {
    try {
        const module = await import(`@visulima/humanizer/language/${langCode}`);
        return module.durationLanguage;
    } catch {
        const { durationLanguage: en } = await import("@visulima/humanizer/language/en");
        return en;
    }
}

const language = await getDurationLanguage(userLanguage);

duration(3000, { language });
```

### Custom Unit Measures [#custom-unit-measures]

Override default unit lengths for specialized applications.

```typescript
import type { DurationUnitMeasures } from "@visulima/humanizer";

// Standard measures
const standard: DurationUnitMeasures = {
    y: 31556952000, // 365.2425 days
    mo: 2629746000, // 30.436875 days
    w: 604800000, // 7 days
    d: 86400000, // 24 hours
    h: 3600000, // 60 minutes
    m: 60000, // 60 seconds
    s: 1000, // 1000 ms
    ms: 1,
};

// Simplified (30-day months, 365-day years)
const simplified: DurationUnitMeasures = {
    y: 365 * 86400000, // 365 days
    mo: 30 * 86400000, // 30 days
    w: 7 * 86400000, // 7 days
    d: 86400000,
    h: 3600000,
    m: 60000,
    s: 1000,
    ms: 1,
};

// Business time (8-hour days, 5-day weeks)
const businessTime: DurationUnitMeasures = {
    y: 260 * 8 * 3600000, // 260 business days
    mo: 22 * 8 * 3600000, // 22 business days
    w: 5 * 8 * 3600000, // 5 business days
    d: 8 * 3600000, // 8 hours
    h: 3600000,
    m: 60000,
    s: 1000,
    ms: 1,
};

duration(2629800000, { unitMeasures: simplified });
// => "1 month, 10 hours, 30 minutes"
```

### Custom Digit Replacements [#custom-digit-replacements]

```typescript
import { duration } from "@visulima/humanizer";

// Custom digit system
const romanNumerals = ["", "I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX"];

duration(1234, {
    digitReplacements: ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
});

// Arabic-Indic digits (built into Arabic language)
import { durationLanguage as ar } from "@visulima/humanizer/language/ar";
duration(1234, { language: ar });
// => "١٫٢٣٤ ثانية"
```

## Configuration Presets [#configuration-presets]

Create and reuse configuration presets for common scenarios.

### UI Display Preset [#ui-display-preset]

```typescript
import type { DurationOptions } from "@visulima/humanizer";

export const uiDurationConfig: DurationOptions = {
    units: ["d", "h", "m"],
    largest: 2,
    round: true,
};

// Usage
duration(timestamp, uiDurationConfig);
```

### Technical Documentation Preset [#technical-documentation-preset]

```typescript
import type { DurationOptions } from "@visulima/humanizer";

export const technicalDurationConfig: DurationOptions = {
    units: ["h", "m", "s", "ms"],
    largest: 3,
    maxDecimalPoints: 3,
};
```

### Localized Preset Factory [#localized-preset-factory]

```typescript
import type { DurationOptions } from "@visulima/humanizer";

async function createLocalizedDurationConfig(locale: string): Promise<DurationOptions> {
    const langCode = locale.split("-")[0];
    const languageModule = await import(`@visulima/humanizer/language/${langCode}`);

    return {
        language: languageModule.durationLanguage,
        units: ["d", "h", "m"],
        largest: 2,
        round: true,
    };
}
```

## Environment-Based Configuration [#environment-based-configuration]

```typescript
// config/humanizer.ts
import type { FormateByteOptions, DurationOptions } from "@visulima/humanizer";

interface HumanizerConfig {
    bytes: FormateByteOptions;
    duration: DurationOptions;
}

export const config: HumanizerConfig = {
    bytes: {
        decimals: process.env.NODE_ENV === "production" ? 1 : 2,
        units: process.env.BYTE_UNIT_SYSTEM === "iec" ? "iec" : "metric",
        locale: process.env.LOCALE || "en-US",
    },
    duration: {
        units: ["d", "h", "m", "s"],
        largest: Number.parseInt(process.env.DURATION_MAX_UNITS || "3", 10),
        round: process.env.NODE_ENV === "production",
    },
};
```

## Validation Helpers [#validation-helpers]

```typescript
import type { DurationUnitName } from "@visulima/humanizer";

export function validateUnits(units: string[]): units is DurationUnitName[] {
    const validUnits = ["y", "mo", "w", "d", "h", "m", "s", "ms"];
    return units.every((unit) => validUnits.includes(unit));
}

export function ensureDescendingOrder(units: DurationUnitName[]): boolean {
    const order = ["y", "mo", "w", "d", "h", "m", "s", "ms"];
    let lastIndex = -1;

    for (const unit of units) {
        const index = order.indexOf(unit);
        if (index <= lastIndex) return false;
        lastIndex = index;
    }

    return true;
}
```

## Best Practices [#best-practices]

### Consistency [#consistency]

Use the same configuration throughout your application:

```typescript
// utils/humanizer.ts
import { formatBytes, duration } from "@visulima/humanizer";
import type { FormateByteOptions, DurationOptions } from "@visulima/humanizer";

const byteConfig: FormateByteOptions = {
    decimals: 2,
    units: "iec",
    base: 2,
};

const durationConfig: DurationOptions = {
    units: ["d", "h", "m"],
    largest: 2,
    round: true,
};

export const formatFileSize = (bytes: number) => formatBytes(bytes, byteConfig);
export const formatDuration = (ms: number) => duration(ms, durationConfig);
```

### User Preferences [#user-preferences]

Respect user locale and preferences:

```typescript
import { formatBytes, duration } from "@visulima/humanizer";

class HumanizerService {
    constructor(private userLocale: string) {}

    formatBytes(bytes: number) {
        return formatBytes(bytes, {
            decimals: 2,
            locale: this.userLocale,
        });
    }

    async formatDuration(ms: number) {
        const langCode = this.userLocale.split("-")[0];
        const { durationLanguage } = await import(`@visulima/humanizer/language/${langCode}`);

        return duration(ms, {
            language: durationLanguage,
            largest: 2,
        });
    }
}
```

### Type Safety [#type-safety]

Use TypeScript for configuration validation:

```typescript
import type { FormateByteOptions } from "@visulima/humanizer";

const config: FormateByteOptions = {
    decimals: 2,
    units: "iec", // Type-checked
    base: 2, // Type-checked
    // @ts-expect-error - Invalid unit system
    units: "invalid",
};
```


# Introduction (/docs/packages/humanizer)



# @visulima/humanizer [#visulimahumanizer]

Transform data into human-readable formats with extensive localization support. Convert bytes to readable sizes (1024 → 1KB), format durations ("3 seconds", "1 day, 3 hours"), and parse human-written values back to numbers - all with support for 700+ locales and 50+ languages.

## Key Features [#key-features]

### Bytes Conversion [#bytes-conversion]

* **Bidirectional conversion** - Format bytes to strings and parse strings to bytes
* **700+ locale support** - Localized number formatting (117,70 MB in German)
* **Multiple unit systems** - Metric, IEC, and octet variants
* **Flexible units** - KB, KiB, MB, MiB, GB, GiB, and beyond

### Duration Formatting [#duration-formatting]

* **Time humanization** - 97320000ms → "1 day, 3 hours, 2 minutes"
* **50+ languages** - Full localization for unit names and formatting
* **Bidirectional parsing** - Parse "2h 30min", "1:25:05", or "PT2H30M5S"
* **Customizable output** - Control units, rounding, delimiters, and more

### Localization & Internationalization [#localization--internationalization]

* **CLDR-based formatting** - Uses Intl.NumberFormat for accurate localization
* **Custom language objects** - Create your own translations and unit maps
* **RTL support** - Handles right-to-left languages correctly
* **Decimal/separator handling** - Respects locale-specific number formats

## Quick Start [#quick-start]

```typescript
import { formatBytes, parseBytes, duration, parseDuration } from "@visulima/humanizer";

// Bytes formatting
formatBytes(123412341, { decimals: 2 });
// => "117.70 MB"

// Duration formatting
duration(97320000);
// => "1 day, 3 hours, 2 minutes"

// Parsing back to numbers
parseBytes("117.70 MB");
// => 123417395.2

parseDuration("1 day, 3 hours, 2 minutes");
// => 97320000
```

## Use Cases [#use-cases]

### Log File Size Display [#log-file-size-display]

```typescript
import { formatBytes } from "@visulima/humanizer";

function displayLogStats(logFiles: { name: string; size: number }[]) {
    for (const file of logFiles) {
        console.log(`${file.name}: ${formatBytes(file.size, { decimals: 1 })}`);
    }
}

displayLogStats([
    { name: "error.log", size: 2458624 },
    { name: "access.log", size: 15728640 },
]);
// Output:
// error.log: 2.3 MB
// access.log: 15.0 MB
```

### API Rate Limit Messages [#api-rate-limit-messages]

```typescript
import { duration } from "@visulima/humanizer";

function getRateLimitMessage(resetTime: number, locale: string) {
    const timeUntilReset = resetTime - Date.now();
    const waitTime = duration(timeUntilReset, {
        units: ["h", "m", "s"],
        largest: 2,
    });

    return `Rate limit exceeded. Try again in ${waitTime}.`;
}

console.log(getRateLimitMessage(Date.now() + 3723000, "en"));
// => "Rate limit exceeded. Try again in 1 hour, 2 minutes."
```

### User Input Processing [#user-input-processing]

```typescript
import { parseBytes, parseDuration } from "@visulima/humanizer";

function processUploadLimit(userInput: string): number | null {
    const bytes = parseBytes(userInput);
    return Number.isNaN(bytes) ? null : bytes;
}

processUploadLimit("50 MB"); // => 52428800
processUploadLimit("2 GB"); // => 2147483648
processUploadLimit("invalid"); // => null

function parseTimeoutValue(userInput: string): number | null {
    const ms = parseDuration(userInput);
    return ms === undefined ? null : ms;
}

parseTimeoutValue("30 seconds"); // => 30000
parseTimeoutValue("2h 30m"); // => 9000000
parseTimeoutValue("1:30:00"); // => 5400000
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/humanizer/installation">
    Install and import the humanizer package
  </Card>

  <Card title="Quick Start" href="/docs/packages/humanizer/quick-start">
    Get started with bytes and duration in 5 minutes
  </Card>

  <Card title="Concepts" href="/docs/packages/humanizer/concepts/localization">
    Understand localization and unit systems
  </Card>

  <Card title="API Reference">
    Complete API documentation for all functions
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

* **Node.js:** 22.13 or higher
* **Browser:** Modern browsers with Intl.NumberFormat support
* **Edge cases:** Handles locale-specific decimal separators, thousand separators, and number formatting


# Installation (/docs/packages/humanizer/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/humanizer
```

## Import [#import]

### Main Functions [#main-functions]

```typescript
import { formatBytes, parseBytes, duration, parseDuration } from "@visulima/humanizer";
```

### Language Packs (Duration) [#language-packs-duration]

Import specific languages for duration formatting:

```typescript
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as es } from "@visulima/humanizer/language/es";
import { durationLanguage as fr } from "@visulima/humanizer/language/fr";

duration(3000, { language: de });
// => "3 Sekunden"
```

### TypeScript Types [#typescript-types]

```typescript
import type { FormateByteOptions, ParseByteOptions, DurationOptions, DurationLanguage, DurationUnit } from "@visulima/humanizer";
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0 or higher (if using TypeScript)
* **ECMAScript:** ES2020 or higher

## Verification [#verification]

Verify installation by running a simple example:

```typescript
import { formatBytes, duration } from "@visulima/humanizer";

console.log(formatBytes(1024));
// => "1 KB"

console.log(duration(3000));
// => "3 seconds"
```


# Quick Start (/docs/packages/humanizer/quick-start)



# Quick Start [#quick-start]

Get started with @visulima/humanizer in under 5 minutes. Learn the essential operations for bytes and duration formatting.

## Format Bytes to Strings [#format-bytes-to-strings]

Convert numeric byte values to human-readable strings:

```typescript
import { formatBytes } from "@visulima/humanizer";

// Basic formatting
formatBytes(1024);
// => "1 KB"

formatBytes(1234567);
// => "1 MB"

// With decimal precision
formatBytes(1234567, { decimals: 2 });
// => "1.18 MB"

// Long format
formatBytes(1234567, { decimals: 2, long: true });
// => "1.18 Megabytes"
```

## Parse Strings to Bytes [#parse-strings-to-bytes]

Convert human-readable strings back to numeric byte values:

```typescript
import { parseBytes } from "@visulima/humanizer";

parseBytes("1 KB");
// => 1024

parseBytes("1.5 MB");
// => 1572864

parseBytes("2.5GB");
// => 2684354560
```

## Format Duration [#format-duration]

Convert milliseconds to human-readable time strings:

```typescript
import { duration } from "@visulima/humanizer";

// Basic duration
duration(3000);
// => "3 seconds"

duration(97320000);
// => "1 day, 3 hours, 2 minutes"

// Limit to specific units
duration(97320000, { units: ["h", "m"] });
// => "27 hours, 2 minutes"

// Limit number of units shown
duration(97320000, { largest: 2 });
// => "1 day, 3 hours"
```

## Parse Duration [#parse-duration]

Convert human-readable duration strings to milliseconds:

```typescript
import { parseDuration } from "@visulima/humanizer";

// Natural language
parseDuration("1 day, 3 hours, 2 minutes");
// => 97320000

// Abbreviated format
parseDuration("2h 30m");
// => 9000000

// Colon format (H:MM:SS)
parseDuration("1:25:05");
// => 5105000

// ISO 8601 format
parseDuration("PT2H30M5S");
// => 9005000
```

## Localization [#localization]

Use locale-specific formatting:

```typescript
import { formatBytes, duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";

// Bytes with German locale
formatBytes(123412341, { decimals: 2, locale: "de" });
// => "117,70 MB"

// Duration with German language
duration(3000, { language: de });
// => "3 Sekunden"
```

## Common Patterns [#common-patterns]

### File Upload Limits [#file-upload-limits]

```typescript
import { formatBytes } from "@visulima/humanizer";

const maxSize = 10 * 1024 * 1024; // 10MB

console.log(`Maximum upload size: ${formatBytes(maxSize)}`);
// => "Maximum upload size: 10 MB"
```

### API Timeout Messages [#api-timeout-messages]

```typescript
import { duration } from "@visulima/humanizer";

const timeout = 30000; // 30 seconds

console.log(`Request timeout: ${duration(timeout, { units: ["s"] })}`);
// => "Request timeout: 30 seconds"
```

### Progress Display [#progress-display]

```typescript
import { formatBytes, duration } from "@visulima/humanizer";

function showProgress(downloaded: number, total: number, elapsed: number) {
    const percent = ((downloaded / total) * 100).toFixed(1);
    const downloadedStr = formatBytes(downloaded, { decimals: 1 });
    const totalStr = formatBytes(total, { decimals: 1 });
    const elapsedStr = duration(elapsed, { units: ["m", "s"], largest: 2 });

    console.log(`${percent}% (${downloadedStr} / ${totalStr}) - ${elapsedStr}`);
}

showProgress(5242880, 10485760, 15000);
// => "50.0% (5.0 MB / 10.0 MB) - 15 seconds"
```

## Next Steps [#next-steps]

* Explore [Bytes Usage](/docs/packages/humanizer/usage/bytes) for advanced formatting options
* Learn about [Duration Usage](/docs/packages/humanizer/usage/duration) for complex time formatting
* Read [Localization Concepts](/docs/packages/humanizer/concepts/localization) for internationalization
* Check API Reference for complete function documentation


# Bytes (/docs/packages/humanizer/usage/bytes)



# Bytes Usage [#bytes-usage]

Learn how to format bytes to human-readable strings and parse strings back to bytes with extensive customization options.

## Format Bytes [#format-bytes]

Convert numeric byte values to human-readable strings.

### Basic Formatting [#basic-formatting]

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(0);
// => "0 B"

formatBytes(1024);
// => "1 KB"

formatBytes(1048576);
// => "1 MB"

formatBytes(1073741824);
// => "1 GB"
```

### Decimal Precision [#decimal-precision]

Control the number of decimal places:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1234567;

formatBytes(bytes);
// => "1 MB"

formatBytes(bytes, { decimals: 1 });
// => "1.2 MB"

formatBytes(bytes, { decimals: 2 });
// => "1.18 MB"

formatBytes(bytes, { decimals: 3 });
// => "1.177 MB"
```

### Long Format [#long-format]

Display full unit names instead of abbreviations:

```typescript
import { formatBytes } from "@visulima/humanizer";

formatBytes(1024, { long: true });
// => "1 Kilobytes"

formatBytes(1048576, { long: true });
// => "1 Megabytes"

formatBytes(1073741824, { long: true });
// => "1 Gigabytes"

// IEC units with long format
formatBytes(1024, { long: true, units: "iec" });
// => "1 Kibibytes"
```

### Unit System Selection [#unit-system-selection]

Choose between metric, IEC, and octet variants:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1073741824;

// Metric (default)
formatBytes(bytes, { units: "metric" });
// => "1 GB"

// IEC binary prefixes
formatBytes(bytes, { units: "iec" });
// => "1 GiB"

// Metric octet (French)
formatBytes(bytes, { units: "metric_octet" });
// => "1 Go"

// IEC octet (French)
formatBytes(bytes, { units: "iec_octet" });
// => "1 Gio"
```

### Base Conversion [#base-conversion]

Switch between base 2 (1024) and base 10 (1000):

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1073741824;

// Base 2 (binary, default)
formatBytes(bytes, { base: 2, decimals: 2 });
// => "1.00 GB"

// Base 10 (decimal)
formatBytes(bytes, { base: 10, decimals: 2 });
// => "1.07 GB"

// Practical example: Show both values
console.log(`Binary: ${formatBytes(bytes, { base: 2, units: "iec" })}`);
console.log(`Decimal: ${formatBytes(bytes, { base: 10, units: "metric" })}`);
// Binary: 1 GiB
// Decimal: 1.07 GB
```

### Specific Unit [#specific-unit]

Force output to a specific unit:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 123412341;

// Force KB
formatBytes(bytes, { unit: "KB", decimals: 2 });
// => "120,519.86 KB"

// Force GB
formatBytes(bytes, { unit: "GB", decimals: 3 });
// => "0.115 GB"

// Force MB with long format
formatBytes(bytes, { unit: "MB", decimals: 2, long: true });
// => "117.70 Megabytes"
```

### Localized Formatting [#localized-formatting]

Use locale-specific number formatting:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 123412341;

// English (US)
formatBytes(bytes, { decimals: 2, locale: "en-US" });
// => "117.70 MB"

// German (comma decimal)
formatBytes(bytes, { decimals: 2, locale: "de-DE" });
// => "117,70 MB"

// French (space thousand separator)
formatBytes(bytes, { decimals: 2, locale: "fr-FR" });
// => "117,70 Mo"

// Japanese
formatBytes(bytes, { decimals: 2, locale: "ja-JP" });
// => "117.70 MB"
```

### Remove Spacing [#remove-spacing]

Control spacing between value and unit:

```typescript
import { formatBytes } from "@visulima/humanizer";

// With space (default)
formatBytes(1024);
// => "1 KB"

// Without space
formatBytes(1024, { space: false });
// => "1KB"
```

### Advanced Number Formatting [#advanced-number-formatting]

Pass additional Intl.NumberFormat options:

```typescript
import { formatBytes } from "@visulima/humanizer";

const bytes = 1234567890;

// Use grouping (thousand separators)
formatBytes(bytes, {
    unit: "KB",
    decimals: 2,
    useGrouping: true,
});
// => "1,205,632.71 KB"

// Scientific notation
formatBytes(bytes, {
    unit: "B",
    notation: "scientific",
});
// => "1.234567890E9 B"
```

## Parse Bytes [#parse-bytes]

Convert human-readable strings back to numeric byte values.

### Basic Parsing [#basic-parsing]

```typescript
import { parseBytes } from "@visulima/humanizer";

parseBytes("1 KB");
// => 1024

parseBytes("1 MB");
// => 1048576

parseBytes("1 GB");
// => 1073741824

parseBytes("1 TB");
// => 1099511627776
```

### Decimal Values [#decimal-values]

Parse strings with decimal values:

```typescript
import { parseBytes } from "@visulima/humanizer";

parseBytes("1.5 MB");
// => 1572864

parseBytes("2.25 GB");
// => 2415919104

parseBytes("0.5 TB");
// => 549755813888
```

### Case Insensitive [#case-insensitive]

Parsing is case insensitive:

```typescript
import { parseBytes } from "@visulima/humanizer";

parseBytes("1 kb");
// => 1024

parseBytes("1 KB");
// => 1024

parseBytes("1 Kb");
// => 1024

parseBytes("1 kB");
// => 1024
```

### Flexible Formatting [#flexible-formatting]

Parse various input formats:

```typescript
import { parseBytes } from "@visulima/humanizer";

// With space
parseBytes("1 MB");
// => 1048576

// Without space
parseBytes("1MB");
// => 1048576

// With period
parseBytes("1.5MB");
// => 1572864

// Spelled out
parseBytes("1 Megabytes");
// => 1048576
```

### Localized Parsing [#localized-parsing]

Parse locale-specific number formats:

```typescript
import { parseBytes } from "@visulima/humanizer";

// German format (comma decimal)
parseBytes("117,70 MB", { locale: "de-DE" });
// => 123417395.2

// French format (space thousand separator)
parseBytes("1 234,56 MB", { locale: "fr-FR" });
// => 1294409441.28

// English format (period decimal)
parseBytes("117.70 MB", { locale: "en-US" });
// => 123417395.2
```

### Unit System for Parsing [#unit-system-for-parsing]

Specify the unit system for parsing:

```typescript
import { parseBytes } from "@visulima/humanizer";

// Metric (default)
parseBytes("1 KB", { units: "metric" });
// => 1024

// IEC
parseBytes("1 KiB", { units: "iec" });
// => 1024

// Metric octet
parseBytes("1 ko", { units: "metric_octet" });
// => 1024
```

### Base Selection [#base-selection]

Choose the base for parsing:

```typescript
import { parseBytes } from "@visulima/humanizer";

// Base 2 (1024, default)
parseBytes("1 KB", { base: 2 });
// => 1024

// Base 10 (1000)
parseBytes("1 KB", { base: 10 });
// => 1000
```

### Error Handling [#error-handling]

Handle invalid input:

```typescript
import { parseBytes } from "@visulima/humanizer";

try {
    parseBytes("");
    // Throws: "Value is not a string or is empty."
} catch (error) {
    console.error(error.message);
}

// Invalid format returns NaN
const result = parseBytes("invalid");
console.log(Number.isNaN(result)); // true

// Check for valid result
function safeParse(input: string): number | null {
    const bytes = parseBytes(input);
    return Number.isNaN(bytes) ? null : bytes;
}

safeParse("1 MB"); // => 1048576
safeParse("invalid"); // => null
```

## Practical Examples [#practical-examples]

### File Size Display [#file-size-display]

```typescript
import { formatBytes } from "@visulima/humanizer";

interface FileInfo {
    name: string;
    size: number;
}

function displayFiles(files: FileInfo[]) {
    for (const file of files) {
        const sizeStr = formatBytes(file.size, { decimals: 2 });
        console.log(`${file.name.padEnd(30)} ${sizeStr.padStart(12)}`);
    }
}

displayFiles([
    { name: "document.pdf", size: 2458624 },
    { name: "photo.jpg", size: 5242880 },
    { name: "video.mp4", size: 157286400 },
]);
// document.pdf                       2.34 MB
// photo.jpg                          5.00 MB
// video.mp4                        150.00 MB
```

### User Input Validation [#user-input-validation]

```typescript
import { parseBytes } from "@visulima/humanizer";

function validateUploadSize(userInput: string, maxBytes: number): boolean {
    const bytes = parseBytes(userInput);

    if (Number.isNaN(bytes)) {
        throw new Error(`Invalid size format: ${userInput}`);
    }

    if (bytes > maxBytes) {
        throw new Error(`Size ${formatBytes(bytes)} exceeds maximum ${formatBytes(maxBytes)}`);
    }

    return true;
}

const maxSize = 50 * 1024 * 1024; // 50 MB

validateUploadSize("25 MB", maxSize); // true
validateUploadSize("100 MB", maxSize); // Error: exceeds maximum
```

### Storage Calculator [#storage-calculator]

```typescript
import { formatBytes, parseBytes } from "@visulima/humanizer";

function calculateRemainingStorage(totalStr: string, usedStr: string): { remaining: string; percentUsed: string } {
    const total = parseBytes(totalStr);
    const used = parseBytes(usedStr);
    const remaining = total - used;
    const percentUsed = ((used / total) * 100).toFixed(1);

    return {
        remaining: formatBytes(remaining, { decimals: 2 }),
        percentUsed: `${percentUsed}%`,
    };
}

const stats = calculateRemainingStorage("500 GB", "327 GB");
console.log(stats);
// { remaining: "173.00 GB", percentUsed: "65.4%" }
```

### Bandwidth Monitor [#bandwidth-monitor]

```typescript
import { formatBytes } from "@visulima/humanizer";

function displayBandwidth(bytesPerSecond: number) {
    // Show in appropriate unit for the speed
    const formatted = formatBytes(bytesPerSecond, {
        base: 10, // Network uses base 10
        decimals: 2,
    });

    console.log(`Download speed: ${formatted}/s`);
}

displayBandwidth(1250000); // => "Download speed: 1.25 MB/s"
displayBandwidth(125000000); // => "Download speed: 125.00 MB/s"
```


# Duration (/docs/packages/humanizer/usage/duration)



# Duration Usage [#duration-usage]

Learn how to format milliseconds to human-readable duration strings and parse duration strings back to milliseconds with extensive customization options.

## Format Duration [#format-duration]

Convert milliseconds to human-readable duration strings.

### Basic Formatting [#basic-formatting]

```typescript
import { duration } from "@visulima/humanizer";

duration(1000);
// => "1 second"

duration(3000);
// => "3 seconds"

duration(60000);
// => "1 minute"

duration(3600000);
// => "1 hour"

duration(97320000);
// => "1 day, 3 hours, 2 minutes"
```

### Specify Units [#specify-units]

Control which units to display:

```typescript
import { duration } from "@visulima/humanizer";

const ms = 97320000; // 1 day, 3 hours, 2 minutes

// Only hours and minutes
duration(ms, { units: ["h", "m"] });
// => "27 hours, 2 minutes"

// Only minutes
duration(ms, { units: ["m"] });
// => "1,622 minutes"

// Full precision
duration(ms, { units: ["d", "h", "m", "s", "ms"] });
// => "1 day, 3 hours, 2 minutes"
```

### Limit Output Units [#limit-output-units]

Show only the N largest units:

```typescript
import { duration } from "@visulima/humanizer";

const ms = 1000000000000; // Very long duration

// Show all units
duration(ms);
// => "31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds"

// Show only 2 largest
duration(ms, { largest: 2 });
// => "31 years, 8 months"

// Show only 3 largest
duration(ms, { largest: 3 });
// => "31 years, 8 months, 1 week"
```

### Rounding [#rounding]

Round the smallest unit for cleaner output:

```typescript
import { duration } from "@visulima/humanizer";

duration(1200);
// => "1.2 seconds"

duration(1200, { round: true });
// => "1 second"

duration(1600, { round: true });
// => "2 seconds"

// Rounding with multiple units
duration(97380000, { largest: 2, round: true });
// => "1 day, 3 hours"
```

### Decimal Precision [#decimal-precision]

Control the number of decimal points:

```typescript
import { duration } from "@visulima/humanizer";

duration(8123.456789);
// => "8.123456789 seconds"

duration(8123.456789, { maxDecimalPoints: 2 });
// => "8.12 seconds"

duration(8123.456789, { maxDecimalPoints: 3 });
// => "8.123 seconds"

// No decimals
duration(8123.456789, { maxDecimalPoints: 0 });
// => "8 seconds"
```

### Delimiters and Conjunctions [#delimiters-and-conjunctions]

Customize how units are joined:

```typescript
import { duration } from "@visulima/humanizer";

const ms = 22140000; // 6 hours, 9 minutes

// Default delimiter
duration(ms);
// => "6 hours, 9 minutes"

// Custom delimiter
duration(ms, { delimiter: " and " });
// => "6 hours and 9 minutes"

// Conjunction before last unit
duration(22141000, { conjunction: " and " });
// => "6 hours, 9 minutes, and 1 second"

// Without serial comma
duration(22141000, { conjunction: " and ", serialComma: false });
// => "6 hours, 9 minutes and 1 second"
```

### Spacer Between Count and Unit [#spacer-between-count-and-unit]

Customize spacing between numbers and unit names:

```typescript
import { duration } from "@visulima/humanizer";

const ms = 260040000; // 3 days, 14 minutes

// Default spacer
duration(ms);
// => "3 days, 14 minutes"

// Custom spacer
duration(ms, { spacer: " whole " });
// => "3 whole days, 14 whole minutes"

// No spacer
duration(ms, { spacer: "" });
// => "3days, 14minutes"
```

### Decimal Separator [#decimal-separator]

Customize the decimal point character:

```typescript
import { duration } from "@visulima/humanizer";

duration(1200);
// => "1.2 seconds"

duration(1200, { decimal: " point " });
// => "1 point 2 seconds"

duration(1200, { decimal: "," });
// => "1,2 seconds"
```

### Language Support [#language-support]

Use different languages for unit names:

```typescript
import { duration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as es } from "@visulima/humanizer/language/es";
import { durationLanguage as ja } from "@visulima/humanizer/language/ja";

// German
duration(3000, { language: de });
// => "3 Sekunden"

// Spanish
duration(3000, { language: es });
// => "3 segundos"

// Japanese
duration(3000, { language: ja });
// => "3 秒"
```

### Custom Unit Measures [#custom-unit-measures]

Override default unit lengths:

```typescript
import { duration } from "@visulima/humanizer";

// Default: Month ≈ 30.44 days
duration(2629800000);
// => "1 month"

// Custom: Month = exactly 30 days
duration(2629800000, {
    unitMeasures: {
        y: 31557600000,
        mo: 30 * 86400000,
        w: 604800000,
        d: 86400000,
        h: 3600000,
        m: 60000,
        s: 1000,
        ms: 1,
    },
});
// => "1 month, 10 hours, 30 minutes"
```

### Digit Replacements [#digit-replacements]

Use custom digits (e.g., for other numeral systems):

```typescript
import { duration } from "@visulima/humanizer";

duration(1234, {
    digitReplacements: ["Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine"],
});
// => "One.TwoThreeFour seconds"

// Arabic numerals (built into Arabic language)
import { durationLanguage as ar } from "@visulima/humanizer/language/ar";

duration(1234, { language: ar });
// => "١٫٢٣٤ ثانية"
```

## Parse Duration [#parse-duration]

Convert human-readable duration strings back to milliseconds.

### Natural Language Parsing [#natural-language-parsing]

```typescript
import { parseDuration } from "@visulima/humanizer";

parseDuration("1 day");
// => 86400000

parseDuration("1 day, 3 hours, 2 minutes");
// => 97320000

parseDuration("2 weeks");
// => 1209600000

parseDuration("1.5 years");
// => 47335428000
```

### Abbreviated Format [#abbreviated-format]

```typescript
import { parseDuration } from "@visulima/humanizer";

parseDuration("2h 30m");
// => 9000000

parseDuration("1h30m45s");
// => 5445000

parseDuration("5d 3h");
// => 442800000
```

### Colon Format (H:MM:SS or MM:SS) [#colon-format-hmmss-or-mmss]

```typescript
import { parseDuration } from "@visulima/humanizer";

// H:MM:SS format
parseDuration("1:25:05");
// => 5105000

// MM:SS format
parseDuration("15:30");
// => 930000

// Hours only
parseDuration("2:00:00");
// => 7200000
```

### ISO 8601 Duration Format [#iso-8601-duration-format]

```typescript
import { parseDuration } from "@visulima/humanizer";

parseDuration("PT2H30M5S");
// => 9005000

parseDuration("PT1H");
// => 3600000

parseDuration("PT30M");
// => 1800000

parseDuration("PT45S");
// => 45000
```

### Negative Durations [#negative-durations]

```typescript
import { parseDuration } from "@visulima/humanizer";

parseDuration("-3 weeks");
// => -1814400000

parseDuration("-2h 30m");
// => -9000000

parseDuration("-1:30:00");
// => -5400000
```

### Numbers Only (Default Unit) [#numbers-only-default-unit]

```typescript
import { parseDuration } from "@visulima/humanizer";

// Default unit is milliseconds
parseDuration("1500");
// => 1500

// Specify default unit
parseDuration("1500", { defaultUnit: "s" });
// => 1500000

parseDuration("10", { defaultUnit: "m" });
// => 600000

parseDuration("2", { defaultUnit: "h" });
// => 7200000
```

### Localized Parsing [#localized-parsing]

Parse duration strings in other languages:

```typescript
import { parseDuration } from "@visulima/humanizer";
import { durationLanguage as de } from "@visulima/humanizer/language/de";
import { durationLanguage as fr } from "@visulima/humanizer/language/fr";

// German
parseDuration("3 Stunden", { language: de });
// => 10800000

// French
parseDuration("2 jours et 5 heures", { language: fr });
// => 190800000
```

### Invalid Input Handling [#invalid-input-handling]

```typescript
import { parseDuration } from "@visulima/humanizer";

// Invalid strings return undefined
const result = parseDuration("invalid");
console.log(result); // undefined

// Check before using
function safeParse(input: string): number | null {
    const ms = parseDuration(input);
    return ms === undefined ? null : ms;
}

safeParse("2 hours"); // => 7200000
safeParse("invalid"); // => null
```

## Practical Examples [#practical-examples]

### API Timeout Configuration [#api-timeout-configuration]

```typescript
import { duration, parseDuration } from "@visulima/humanizer";

interface Config {
    timeout: string;
}

function setApiTimeout(config: Config) {
    const timeoutMs = parseDuration(config.timeout);

    if (timeoutMs === undefined) {
        throw new Error(`Invalid timeout: ${config.timeout}`);
    }

    console.log(`Timeout set to ${duration(timeoutMs, { units: ["s", "ms"] })}`);
    return timeoutMs;
}

setApiTimeout({ timeout: "30s" });
// => Timeout set to 30 seconds

setApiTimeout({ timeout: "2m 30s" });
// => Timeout set to 2 minutes, 30 seconds
```

### Uptime Display [#uptime-display]

```typescript
import { duration } from "@visulima/humanizer";

function displayUptime(startTime: number) {
    const uptime = Date.now() - startTime;

    return duration(uptime, {
        units: ["d", "h", "m"],
        largest: 3,
        round: true,
    });
}

const serverStart = Date.now() - 345678901;
console.log(`Server uptime: ${displayUptime(serverStart)}`);
// => Server uptime: 4 days, 0 hours, 1 minute
```

### Countdown Timer [#countdown-timer]

```typescript
import { duration } from "@visulima/humanizer";

function formatCountdown(endTime: number): string {
    const remaining = endTime - Date.now();

    if (remaining <= 0) {
        return "Expired";
    }

    return duration(remaining, {
        units: ["h", "m", "s"],
        largest: 3,
        round: true,
    });
}

const deadline = Date.now() + 7200000; // 2 hours from now
console.log(`Time remaining: ${formatCountdown(deadline)}`);
// => Time remaining: 2 hours
```

### Build Time Reporter [#build-time-reporter]

```typescript
import { duration } from "@visulima/humanizer";

function reportBuildTime(startTime: number, endTime: number) {
    const buildTime = endTime - startTime;

    return duration(buildTime, {
        units: ["m", "s", "ms"],
        largest: 2,
        maxDecimalPoints: 2,
    });
}

const start = Date.now();
// ... build process ...
const end = Date.now();

console.log(`Build completed in ${reportBuildTime(start, end)}`);
// => Build completed in 2 minutes, 34.56 seconds
```

### Cache TTL Display [#cache-ttl-display]

```typescript
import { duration } from "@visulima/humanizer";

interface CacheEntry {
    key: string;
    expiresAt: number;
}

function displayCacheStatus(entries: CacheEntry[]) {
    const now = Date.now();

    for (const entry of entries) {
        const ttl = entry.expiresAt - now;

        if (ttl <= 0) {
            console.log(`${entry.key}: Expired`);
        } else {
            const ttlStr = duration(ttl, {
                units: ["h", "m", "s"],
                largest: 2,
                round: true,
            });
            console.log(`${entry.key}: ${ttlStr} remaining`);
        }
    }
}

displayCacheStatus([
    { key: "user:123", expiresAt: Date.now() + 300000 },
    { key: "session:abc", expiresAt: Date.now() + 3600000 },
]);
// user:123: 5 minutes remaining
// session:abc: 1 hour remaining
```

### Scheduling System [#scheduling-system]

```typescript
import { parseDuration } from "@visulima/humanizer";

interface Task {
    name: string;
    interval: string;
}

function scheduleTask(task: Task) {
    const intervalMs = parseDuration(task.interval);

    if (intervalMs === undefined) {
        throw new Error(`Invalid interval: ${task.interval}`);
    }

    setInterval(() => {
        console.log(`Running task: ${task.name}`);
    }, intervalMs);

    console.log(`Scheduled "${task.name}" every ${task.interval}`);
}

scheduleTask({ name: "Cleanup", interval: "5 minutes" });
scheduleTask({ name: "Backup", interval: "1 hour" });
scheduleTask({ name: "Report", interval: "1 day" });
```

### Time Tracking [#time-tracking]

```typescript
import { duration } from "@visulima/humanizer";

class TimeTracker {
    private startTime: number | null = null;

    start() {
        this.startTime = Date.now();
    }

    stop(): string {
        if (!this.startTime) {
            return "Not started";
        }

        const elapsed = Date.now() - this.startTime;
        this.startTime = null;

        return duration(elapsed, {
            units: ["h", "m", "s"],
            largest: 3,
            maxDecimalPoints: 2,
        });
    }
}

const tracker = new TimeTracker();
tracker.start();
// ... do work ...
console.log(`Task completed in ${tracker.stop()}`);
// => Task completed in 3 minutes, 45.67 seconds
```

### Relative Time Display [#relative-time-display]

```typescript
import { duration } from "@visulima/humanizer";

function relativeTime(timestamp: number): string {
    const diff = Date.now() - timestamp;
    const absDiff = Math.abs(diff);

    const timeStr = duration(absDiff, {
        units: ["d", "h", "m"],
        largest: 1,
        round: true,
    });

    return diff < 0 ? `in ${timeStr}` : `${timeStr} ago`;
}

console.log(relativeTime(Date.now() - 3600000));
// => "1 hour ago"

console.log(relativeTime(Date.now() + 7200000));
// => "in 2 hours"
```


# Package Directory (/docs/packages)





Browse all **40+ production-ready TypeScript packages** organized by category. Each package is independently versioned, well-tested, and designed for Node.js, Bun, Deno, and Edge runtimes.

## CLI & Terminal [#cli--terminal]

Tools for building command-line applications, formatting terminal output, and managing colors.

<Cards>
  <Card title="Cerebro" description="Lightweight, extensible CLI framework" href="/docs/packages/cerebro" />

  <Card title="Pail" description="Configurable logger for Node.js, Edge and Browser" href="/docs/packages/pail" />

  <Card title="Command Line Args" description="Type-safe argument parsing" href="/docs/packages/command-line-args" />

  <Card title="Boxen" description="Beautiful boxes in the terminal" href="/docs/packages/boxen" />

  <Card title="Tabular" description="ASCII tables and grids" href="/docs/packages/tabular" />

  <Card title="ANSI" description="ANSI escape codes for terminal control" href="/docs/packages/ansi" />

  <Card title="Colorize" description="Terminal string styling with ANSI colors" href="/docs/packages/colorize" />

  <Card title="Is ANSI Color Supported" description="Detect terminal color support" href="/docs/packages/is-ansi-color-supported" />

  <Card title="Fmt" description="Printf-style string formatting" href="/docs/packages/fmt" />
</Cards>

## Data & Utilities [#data--utilities]

String manipulation, object utilities, deep cloning, content safety, and data transformation.

<Cards>
  <Card title="String" description="Comprehensive string manipulation" href="/docs/packages/string" />

  <Card title="Object" description="Dot notation and deep key operations" href="/docs/packages/object" />

  <Card title="Deep Clone" description="Fast deep cloning with circular refs" href="/docs/packages/deep-clone" />

  <Card title="Bytes" description="Uint8Array utilities" href="/docs/packages/bytes" />

  <Card title="Humanizer" description="Human-readable bytes and durations" href="/docs/packages/humanizer" />

  <Card title="Redact" description="GDPR-compliant data redaction" href="/docs/packages/redact" />

  <Card title="Content Safety" description="Profanity detection across 19 languages" href="/docs/packages/content-safety" />
</Cards>

## File System [#file-system]

File I/O, path handling, config parsing, caching, and storage backends.

<Cards>
  <Card title="FS" description="Human-friendly file system utilities" href="/docs/packages/fs" />

  <Card title="Path" description="Cross-platform path manipulation" href="/docs/packages/path" />

  <Card title="Find Cache Dir" description="Standard cache directory detection" href="/docs/packages/find-cache-dir" />

  <Card title="Package" description="Package management utilities" href="/docs/packages/package" />

  <Card title="TSConfig" description="TypeScript config parsing" href="/docs/packages/tsconfig" />

  <Card title="Storage" description="S3, Azure, GCS file storage" href="/docs/packages/storage" />

  <Card title="Storage Client" description="File upload for React, Vue, Svelte" href="/docs/packages/storage-client" />
</Cards>

## API & Web [#api--web]

REST APIs, middleware, pagination, OpenAPI generation, and HTML utilities.

<Cards>
  <Card title="HTML" description="XSS-safe HTML utilities" href="/docs/packages/html" />

  <Card title="Pagination" description="Cursor and offset pagination" href="/docs/packages/pagination" />

  <Card title="Health Check" description="Application health endpoints" href="/docs/packages/health-check" />

  <Card title="JSDoc OpenAPI" description="Generate OpenAPI from JSDoc" href="/docs/packages/jsdoc-open-api" />
</Cards>

## Error Handling [#error-handling]

Error parsing, source maps, debugging overlays, and inspection tools.

<Cards>
  <Card title="Error" description="Enhanced errors with AI solutions" href="/docs/packages/error" />

  <Card title="Error Handler" description="Global error handling middleware" href="/docs/packages/error-handler" />

  <Card title="Ono" description="Better errors with chaining" href="/docs/packages/ono" />

  <Card title="Source Map" description="Source map parsing and generation" href="/docs/packages/source-map" />

  <Card title="Inspector" description="Object pretty-printing and inspection" href="/docs/packages/inspector" />

  <Card title="Vite Overlay" description="Error overlay for Vite" href="/docs/packages/vite-overlay" />
</Cards>

## Internationalization & Communication [#internationalization--communication]

Locale data, email sending, and disposable email detection.

<Cards>
  <Card title="ISO Locale" description="Countries, currencies, timezones" href="/docs/packages/iso-locale" />

  <Card title="Disposable Email Domains" description="Block temporary email addresses" href="/docs/packages/disposable-email-domains" />

  <Card title="Email" description="Multi-provider email sending" href="/docs/packages/email" />
</Cards>

## Dev Tools [#dev-tools]

Development tooling and Prisma utilities.

<Cards>
  <Card title="Dev Toolbar" description="Vite dev toolbar with a11y and perf" href="/docs/packages/dev-toolbar" />
</Cards>


# API (/docs/packages/inspector/api)



# API Reference [#api-reference]

## `inspect(value, options?)` [#inspectvalue-options]

Inspect and format a value.

**Options:**

* `depth` (number): Max depth
* `colors` (boolean): Enable colors
* `showHidden` (boolean): Show hidden properties

**Returns:** Formatted string

**Example:**

```typescript
inspect(obj, {
    depth: 3,
    colors: true,
    showHidden: false,
});
```


# Introduction (/docs/packages/inspector)



# @visulima/inspector [#visulimainspector]

Advanced object inspection with customizable formatting, circular reference handling, and depth control.

## Key Features [#key-features]

* Deep object inspection
* Circular reference detection
* Custom formatting
* Syntax highlighting
* Depth control

## Quick Start [#quick-start]

```typescript
import { inspect } from "@visulima/inspector";

const obj = { name: "John", age: 30 };
console.log(inspect(obj));
```

<Cards>
  <Card title="Installation" href="/docs/packages/inspector/installation">
    Install
  </Card>

  <Card title="Quick Start" href="/docs/packages/inspector/quick-start">
    Get started
  </Card>

  <Card title="Usage" href="/docs/packages/inspector/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/inspector/api">
    API docs
  </Card>
</Cards>


# Installation (/docs/packages/inspector/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/inspector
```

## Import [#import]

```typescript
import { inspect } from "@visulima/inspector";
```


# Quick Start (/docs/packages/inspector/quick-start)



# Quick Start [#quick-start]

## Basic Inspection [#basic-inspection]

```typescript
import { inspect } from "@visulima/inspector";

const data = {
    user: { name: "John", age: 30 },
    items: [1, 2, 3],
};

console.log(inspect(data));
```

## With Options [#with-options]

```typescript
console.log(inspect(data, {
    depth: 3,
    colors: true,
}));
```


# Usage (/docs/packages/inspector/usage)



# Usage [#usage]

## Depth Control [#depth-control]

```typescript
import { inspect } from "@visulima/inspector";

inspect(deepObject, { depth: 2 });
inspect(deepObject, { depth: Infinity });
```

## Colors [#colors]

```typescript
inspect(object, { colors: true });
```

## Circular References [#circular-references]

```typescript
const obj = { name: "test" };
obj.self = obj;

inspect(obj); // Handles circular reference
```


# Getting Started (/docs/packages/interactive-manager/getting-started)



## Installation [#installation]

Install the package using your preferred package manager:



<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="pnpm">
    ```bash
    pnpm add @visulima/interactive-manager
    ```
  </Tab>

  <Tab value="npm">
    `bash npm install @visulima/interactive-manager `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/interactive-manager `
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @visulima/interactive-manager
    ```
  </Tab>
</Tabs>

## Basic Usage [#basic-usage]

### Setting Up [#setting-up]

The interactive manager requires two stream hooks — one for stdout and one for stderr:

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);
```

### Updating Output [#updating-output]

Once hooked, you can dynamically update terminal output:

```typescript
manager.hook();

// Write multiple lines
manager.update("stdout", ["Line 1", "Line 2", "Line 3"]);

// Update with new content (previous lines are erased)
manager.update("stdout", ["Updated line 1", "Updated line 2"]);

manager.unhook();
```

### Suspend and Resume [#suspend-and-resume]

Temporarily pause interactive mode to allow external output:

```typescript
manager.hook();
manager.update("stdout", ["Processing..."]);

// Pause interactive mode
manager.suspend("stdout");
console.log("This message appears normally");

// Resume interactive mode
manager.resume("stdout");
manager.update("stdout", ["Still processing..."]);

manager.unhook();
```

## See Also [#see-also]

* [Usage Guide](/docs/packages/interactive-manager/usage) - Complete API reference


# Interactive Manager (/docs/packages/interactive-manager)



A utility for managing interactive terminal output by coordinating stdout and stderr streams. Enables features like progress bars, spinners, and dynamic updates by temporarily capturing and controlling terminal output.

## Features [#features]

* **Stream Hooking** - Intercept stdout/stderr for dynamic output control
* **Cursor Management** - Hide/show cursor with ANSI escape sequences
* **Line Erasing** - Clear and rewrite terminal lines for smooth updates
* **Suspend/Resume** - Temporarily pause interactive mode for external output
* **History Replay** - Captured output is replayed when interactive mode ends
* **TypeScript** - Full type support out of the box

## Quick Example [#quick-example]

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

// Start interactive mode
manager.hook();

// Update output dynamically
manager.update("stdout", ["Processing...", "50% complete"]);

// End interactive mode
manager.unhook();
```

## Next Steps [#next-steps]

* [Getting Started](/docs/packages/interactive-manager/getting-started) - Install and set up
* [Usage Guide](/docs/packages/interactive-manager/usage) - Complete API reference


# Usage Guide (/docs/packages/interactive-manager/usage)



## InteractiveStreamHook [#interactivestreamhook]

Hooks into a Node.js WriteStream to capture output for interactive terminal applications.

### Constructor [#constructor]

```typescript
import { InteractiveStreamHook } from "@visulima/interactive-manager";

const hook = new InteractiveStreamHook(process.stdout);
```

### Methods [#methods]

#### active() [#active]

Activates the stream hook. All writes to the stream are captured in history.

```typescript
hook.active();
```

#### inactive(separateHistory?) [#inactiveseparatehistory]

Deactivates the hook and replays captured output.

```typescript
hook.inactive(); // Replay without separator
hook.inactive(true); // Add newline before replay
```

#### erase(count) [#erasecount]

Erases the specified number of lines from the terminal.

```typescript
hook.erase(3); // Erase 3 lines
```

#### renew() [#renew]

Restores the original stream write method and shows the cursor.

```typescript
hook.renew();
```

#### write(message) [#writemessage]

Writes directly to the underlying stream, bypassing the hook.

```typescript
hook.write("Direct output\n");
```

## InteractiveManager [#interactivemanager]

Coordinates stdout and stderr stream hooks for interactive terminal output.

### Constructor [#constructor-1]

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);
```

### Properties [#properties]

#### isHooked [#ishooked]

Whether the interactive hooks are currently active.

```typescript
if (manager.isHooked) {
    // Interactive mode is active
}
```

#### isSuspended [#issuspended]

Whether interactive mode is temporarily suspended.

```typescript
if (manager.isSuspended) {
    // Hooks are paused
}
```

#### lastLength [#lastlength]

Number of rows last written to the terminal.

```typescript
console.log(manager.lastLength);
```

#### outside [#outside]

Number of rows beyond the terminal height.

```typescript
console.log(manager.outside);
```

### Methods [#methods-1]

#### hook() [#hook]

Activates both stdout and stderr hooks.

```typescript
manager.hook();
```

#### unhook(separateHistory?) [#unhookseparatehistory]

Deactivates hooks and replays captured output.

```typescript
manager.unhook(); // With history separator
manager.unhook(false); // Without separator
```

#### update(stream, rows, from?) [#updatestream-rows-from]

Updates the terminal output with new content.

```typescript
manager.update("stdout", ["Line 1", "Line 2"]);
manager.update("stderr", ["Error output"]);

// Update starting from a specific line
manager.update("stdout", ["Updated"], 2);
```

#### suspend(stream, erase?) [#suspendstream-erase]

Temporarily suspends interactive mode.

```typescript
manager.suspend("stdout"); // Suspend and erase
manager.suspend("stdout", false); // Suspend without erasing
```

#### resume(stream, eraseRowCount?) [#resumestream-eraserowcount]

Resumes interactive mode after suspension.

```typescript
manager.resume("stdout");
manager.resume("stdout", 3); // Erase 3 rows on resume
```

#### erase(stream, count?) [#erasestream-count]

Erases lines from the terminal output.

```typescript
manager.erase("stdout"); // Erase lastLength lines
manager.erase("stdout", 5); // Erase 5 lines
```

## StreamType [#streamtype]

```typescript
type StreamType = "stderr" | "stdout";
```

## Integration with Spinners [#integration-with-spinners]

The interactive manager works with `@visulima/spinner` for animated spinner output:

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

manager.hook();

// Render spinner frames
const frames = ["⠋", "⠙", "⠹", "⠸"];
let i = 0;

const interval = setInterval(() => {
    manager.update("stdout", [`${frames[i % frames.length]} Loading...`]);
    i++;
}, 80);

// Later...
clearInterval(interval);
manager.update("stdout", ["✓ Done!"]);
manager.unhook(false);
```

## Integration with Progress Bars [#integration-with-progress-bars]

Works with `@visulima/progress-bar` for progress tracking:

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
import { ProgressBar } from "@visulima/progress-bar";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

const bar = new ProgressBar({ total: 100 }, manager);
bar.start();
bar.update(50);
bar.stop();
```


# API (/docs/packages/is-ansi-color-supported/api)



# API Reference [#api-reference]

## `isAnsiColorSupported(): number` [#isansicolorsupported-number]

Returns color support level.

**Returns:**

* `0` - No colors
* `1` - 16 colors
* `2` - 256 colors
* `3` - TrueColor

**Example:**

```typescript
const level = isAnsiColorSupported();
```


# Introduction (/docs/packages/is-ansi-color-supported)



# @visulima/is-ansi-color-supported [#visulimais-ansi-color-supported]

Detect terminal color support capabilities including ANSI 16 colors, 256 colors, and TrueColor (16 million colors).

## Quick Start [#quick-start]

```typescript
import { isAnsiColorSupported } from "@visulima/is-ansi-color-supported";

const colorLevel = isAnsiColorSupported();

if (colorLevel >= 3) {
    console.log("TrueColor supported!");
} else if (colorLevel >= 2) {
    console.log("256 colors supported");
} else if (colorLevel >= 1) {
    console.log("Basic ANSI colors supported");
} else {
    console.log("No color support");
}
```

## Color Levels [#color-levels]

* `0` - No color support
* `1` - Basic 16 colors (ANSI)
* `2` - 256 colors
* `3` - TrueColor (16 million colors)

<Cards>
  <Card title="Installation" href="/docs/packages/is-ansi-color-supported/installation">
    Install the package
  </Card>

  <Card title="Usage" href="/docs/packages/is-ansi-color-supported/usage">
    Learn how to detect colors
  </Card>

  <Card title="API" href="/docs/packages/is-ansi-color-supported/api">
    API documentation
  </Card>
</Cards>


# Installation (/docs/packages/is-ansi-color-supported/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/is-ansi-color-supported
```

## Import [#import]

```typescript
import { isAnsiColorSupported } from "@visulima/is-ansi-color-supported";
```


# Usage (/docs/packages/is-ansi-color-supported/usage)



# Usage [#usage]

## Check Color Support [#check-color-support]

```typescript
import { isAnsiColorSupported } from "@visulima/is-ansi-color-supported";

const level = isAnsiColorSupported();

switch (level) {
    case 3:
        console.log("TrueColor (16M colors)");
        break;
    case 2:
        console.log("256 colors");
        break;
    case 1:
        console.log("16 colors (ANSI)");
        break;
    default:
        console.log("No colors");
}
```

## Environment Detection [#environment-detection]

Automatically detects:

* CI environments
* Terminal capabilities
* Environment variables (FORCE\_COLOR, NO\_COLOR)
* TTY status


# API Reference (/docs/packages/iso-locale/api)



# API Reference [#api-reference]

## Countries [#countries]

### getByAlpha2(code: string) [#getbyalpha2code-string]

Get country by ISO 3166-1 alpha-2 code.

### getAllCountries() [#getallcountries]

Get all countries.

### getEmoji(code: string) [#getemojicode-string]

Get flag emoji for country.

## Currencies [#currencies]

### getByCode(code: string) [#getbycodecode-string]

Get currency by ISO 4217 code.

### getSymbol(code: string) [#getsymbolcode-string]

Get currency symbol.

### getByCountry(code: string) [#getbycountrycode-string]

Get currencies for a country.

## Regions [#regions]

### getRegionsForCountry(code: string) [#getregionsforcountrycode-string]

Get continent and subregion.

### getCountriesInContinent(continent: string) [#getcountriesincontinentcontinent-string]

Get all countries in continent.

## Timezones [#timezones]

### getTimezonesByCountry(code: string) [#gettimezonesbycountrycode-string]

Get IANA timezones for country.

### getPrimaryTimezone(code: string) [#getprimarytimezonecode-string]

Get primary timezone.

## Locale [#locale]

### parseBCP47Tag(tag: string) [#parsebcp47tagtag-string]

Parse BCP 47 language tag.

### generateBCP47Tag(lang: string, country: string) [#generatebcp47taglang-string-country-string]

Generate BCP 47 tag.


# Countries (/docs/packages/iso-locale/countries)



# Countries [#countries]

@visulima/iso-locale provides comprehensive ISO 3166-1 country data with support for multiple code formats, conversions, and utilities.

## Country Data Structure [#country-data-structure]

Each country includes:

* **name**: English name of the country
* **alpha2**: ISO 3166-1 alpha-2 code (2-letter, e.g., "US")
* **alpha3**: ISO 3166-1 alpha-3 code (3-letter, e.g., "USA")
* **numeric**: ISO 3166-1 numeric code (3-digit, e.g., "840")
* **currencies**: Array of ISO 4217 currency codes used in the country
* **languages**: Array of ISO 639-3 language codes
* **countryCallingCodes**: International call prefixes (e.g., \["+1"])
* **emoji**: Flag emoji (e.g., "🇺🇸")
* **ioc**: International Olympic Committee code (e.g., "USA")
* **status**: ISO status (e.g., "assigned", "reserved", "deleted")

## Getting Country Data [#getting-country-data]

### By Code [#by-code]

```typescript
import { getByAlpha2, getByAlpha3, getByNumeric } from "@visulima/iso-locale";

// Get by alpha-2 code
const country = getByAlpha2("US");
console.log(country.name); // "United States"

// Get by alpha-3 code
const country2 = getByAlpha3("USA");
console.log(country2.name); // "United States"

// Get by numeric code
const country3 = getByNumeric("840");
console.log(country3.name); // "United States"
```

### By Name [#by-name]

```typescript
import { getCountryByName, searchCountries } from "@visulima/iso-locale";

// Exact match
const country = getCountryByName("United States");
console.log(country?.alpha2); // "US"

// Partial search
const results = searchCountries("united");
console.log(results.length); // Multiple countries with "united" in name
```

## Code Conversion [#code-conversion]

Convert between different code formats:

```typescript
import { alpha2ToAlpha3, alpha3ToAlpha2, alpha2ToNumeric, numericToAlpha2, numericToAlpha3 } from "@visulima/iso-locale";

// Alpha-2 to Alpha-3
alpha2ToAlpha3("US"); // "USA"

// Alpha-3 to Alpha-2
alpha3ToAlpha2("USA"); // "US"

// Alpha-2 to Numeric
alpha2ToNumeric("US"); // "840"

// Numeric to Alpha-2
numericToAlpha2("840"); // "US"

// Numeric to Alpha-3
numericToAlpha3("840"); // "USA"
```

## Country Utilities [#country-utilities]

### Flag Emoji [#flag-emoji]

```typescript
import { getEmoji } from "@visulima/iso-locale";

getEmoji("US"); // "🇺🇸"
getEmoji("GB"); // "🇬🇧"
getEmoji("FR"); // "🇫🇷"
```

### Calling Codes [#calling-codes]

```typescript
import { getCallingCode, getCallingCodes } from "@visulima/iso-locale";

// Get first calling code
getCallingCode("US"); // "+1"

// Get all calling codes
getCallingCodes("US"); // ["+1"]
```

### Languages [#languages]

```typescript
import { getLanguages } from "@visulima/iso-locale";

getLanguages("US"); // ["eng"]
getLanguages("CA"); // ["eng", "fra"]
```

### IOC Code [#ioc-code]

```typescript
import { getIOC } from "@visulima/iso-locale";

getIOC("US"); // "USA"
getIOC("GB"); // "GBR"
```

## Validation [#validation]

```typescript
import { isValidCountry } from "@visulima/iso-locale";

isValidCountry("US"); // true
isValidCountry("USA"); // true
isValidCountry("840"); // true
isValidCountry("XX"); // false
```

## Indexed Access [#indexed-access]

For fast lookups, use the indexed maps:

```typescript
import { byAlpha2, byAlpha3, byNumeric } from "@visulima/iso-locale";

const country = byAlpha2["US"];
const country2 = byAlpha3["USA"];
const country3 = byNumeric["840"];
```

## All Countries [#all-countries]

Get all countries as an array:

```typescript
import { countriesAll } from "@visulima/iso-locale";

const allCountries = countriesAll;
console.log(allCountries.length); // ~250+ countries
```

## Examples [#examples]

### Find Country by User Input [#find-country-by-user-input]

```typescript
import { getByAlpha2, getCountryByName, searchCountries } from "@visulima/iso-locale";

function findCountry(input: string) {
    // Try as code first
    if (input.length === 2) {
        return getByAlpha2(input);
    }
    if (input.length === 3) {
        return getByAlpha3(input);
    }

    // Try exact name match
    const exact = getCountryByName(input);
    if (exact) return exact;

    // Try partial search
    const results = searchCountries(input);
    return results[0];
}
```

### Display Country Information [#display-country-information]

```typescript
import { getByAlpha2, getEmoji, getCallingCode, getLanguages } from "@visulima/iso-locale";

function displayCountryInfo(code: string) {
    const country = getByAlpha2(code);
    if (!country) return;

    console.log(`${getEmoji(code)} ${country.name}`);
    console.log(`Calling Code: ${getCallingCode(code)}`);
    console.log(`Languages: ${getLanguages(code).join(", ")}`);
    console.log(`Currencies: ${country.currencies.join(", ")}`);
}
```

## Next Steps [#next-steps]

* [Currencies](/docs/packages/iso-locale/currencies) - Working with currency data
* [Regions](/docs/packages/iso-locale/regions) - Working with regional data
* [API Reference](/docs/packages/iso-locale/api) - Complete API documentation


# Currencies (/docs/packages/iso-locale/currencies)



# Currencies [#currencies]

@visulima/iso-locale provides comprehensive ISO 4217 currency data with symbols, decimal places, and country associations.

## Currency Data Structure [#currency-data-structure]

Each currency includes:

* **code**: ISO 4217 alphabetic code (3-letter, e.g., "USD")
* **number**: ISO 4217 numeric code (3-digit, e.g., "840")
* **name**: Full currency name (e.g., "United States dollar")
* **decimals**: Number of decimal digits typically used (e.g., 2)
* **symbol**: Currency symbol (e.g., "$")

## Getting Currency Data [#getting-currency-data]

### By Code [#by-code]

```typescript
import { getByCode, getByNumber } from "@visulima/iso-locale";

// Get by alphabetic code
const currency = getByCode("USD");
console.log(currency.name); // "United States dollar"
console.log(currency.symbol); // "$"
console.log(currency.decimals); // 2

// Get by numeric code
const currency2 = getByNumber("840");
console.log(currency2.code); // "USD"
```

### By Name [#by-name]

```typescript
import { getCurrencyByName, searchCurrencies } from "@visulima/iso-locale";

// Exact match
const currency = getCurrencyByName("United States dollar");
console.log(currency?.code); // "USD"

// Partial search
const results = searchCurrencies("dollar");
console.log(results.length); // Multiple currencies with "dollar" in name
```

### By Country [#by-country]

```typescript
import { getByCountry } from "@visulima/iso-locale";

// Get currencies used in a country
const currencies = getByCountry("US");
console.log(currencies[0].code); // "USD"

// Get currencies for a country
const caCurrencies = getByCountry("CA");
console.log(caCurrencies.map((c) => c.code)); // ["CAD"]
```

## Currency Utilities [#currency-utilities]

### Get Symbol [#get-symbol]

```typescript
import { getSymbol } from "@visulima/iso-locale";

getSymbol("USD"); // "$"
getSymbol("EUR"); // "€"
getSymbol("GBP"); // "£"
getSymbol("JPY"); // "¥"
```

### Get Name [#get-name]

```typescript
import { getName } from "@visulima/iso-locale";

getName("USD"); // "United States dollar"
getName("EUR"); // "Euro"
```

### Get Countries Using Currency [#get-countries-using-currency]

```typescript
import { getCountriesByCurrency } from "@visulima/iso-locale";

// Get all countries using EUR
const countries = getCountriesByCurrency("EUR");
console.log(countries); // ["FR", "DE", "ES", "IT", ...]
```

## Validation [#validation]

```typescript
import { isValidCurrency } from "@visulima/iso-locale";

isValidCurrency("USD"); // true
isValidCurrency("840"); // true
isValidCurrency("XXX"); // false
```

## Indexed Access [#indexed-access]

For fast lookups, use the indexed maps:

```typescript
import { byCode, byNumber } from "@visulima/iso-locale";

const currency = byCode["USD"];
const currency2 = byNumber["840"];
```

## All Currencies [#all-currencies]

Get all currencies as an array:

```typescript
import { currenciesAll } from "@visulima/iso-locale";

const allCurrencies = currenciesAll;
console.log(allCurrencies.length); // ~180+ currencies
```

## Examples [#examples]

### Format Currency Amount [#format-currency-amount]

```typescript
import { getByCode, getSymbol } from "@visulima/iso-locale";

function formatCurrency(amount: number, currencyCode: string): string {
    const currency = getByCode(currencyCode);
    if (!currency) return `${amount} ${currencyCode}`;

    const symbol = getSymbol(currencyCode);
    const decimals = currency.decimals;

    return `${symbol}${amount.toFixed(decimals)}`;
}

formatCurrency(100, "USD"); // "$100.00"
formatCurrency(1000, "JPY"); // "¥1000" (0 decimals)
```

### Find Currency by Country [#find-currency-by-country]

```typescript
import { getByCountry } from "@visulima/iso-locale";

function getPrimaryCurrency(countryCode: string) {
    const currencies = getByCountry(countryCode);
    return currencies[0]?.code;
}

getPrimaryCurrency("US"); // "USD"
getPrimaryCurrency("GB"); // "GBP"
```

### Search Currencies [#search-currencies]

```typescript
import { searchCurrencies } from "@visulima/iso-locale";

// Find all dollar currencies
const dollars = searchCurrencies("dollar");
console.log(dollars.map((c) => c.code));
// ["USD", "CAD", "AUD", "NZD", ...]
```

## Next Steps [#next-steps]

* [Countries](/docs/packages/iso-locale/countries) - Working with country data
* [Regions](/docs/packages/iso-locale/regions) - Working with regional data
* [API Reference](/docs/packages/iso-locale/api) - Complete API documentation


# Introduction (/docs/packages/iso-locale)



# @visulima/iso-locale [#visulimaiso-locale]

Comprehensive ISO standards data for countries (ISO 3166), currencies (ISO 4217), regions (UN Geoscheme), timezones (IANA), and BCP 47 locale support.

## Key Features [#key-features]

* **Country Data** - ISO 3166-1 alpha-2/alpha-3 codes, flag emojis, calling codes
* **Currency Data** - ISO 4217 codes, symbols, country mappings
* **Region Data** - UN Geoscheme continents and subregions
* **Timezone Data** - IANA timezone database with country mappings
* **BCP 47 Support** - Parse and generate language tags
* **TypeScript** - Full type definitions

## Quick Start [#quick-start]

```typescript
import { getByAlpha2, getEmoji, getCurrency } from "@visulima/iso-locale";

const country = getByAlpha2("US");
console.log(country.name); // "United States"
console.log(getEmoji("US")); // "🇺🇸"
console.log(getCurrency("en-US")); // "USD"
```

## Use Cases [#use-cases]

```typescript
// Country selector
import { getAllCountries, getEmoji } from "@visulima/iso-locale";

const countries = getAllCountries().map((c) => ({
    code: c.alpha2,
    name: c.name,
    flag: getEmoji(c.alpha2),
}));

// Currency formatting
import { getSymbol } from "@visulima/iso-locale";

function formatPrice(amount: number, code: string) {
    return `${getSymbol(code)}${amount.toFixed(2)}`;
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/iso-locale/installation">
    Install and import
  </Card>

  <Card title="Quick Start" href="/docs/packages/iso-locale/quick-start">
    Get started
  </Card>

  <Card title="Usage" href="/docs/packages/iso-locale/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/iso-locale/api">
    API reference
  </Card>
</Cards>


# Installation (/docs/packages/iso-locale/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/iso-locale
```

## Import [#import]

```typescript
import { getByAlpha2, getEmoji, getCurrency } from "@visulima/iso-locale";
```

### Subpath Imports [#subpath-imports]

```typescript
import { getByAlpha2 } from "@visulima/iso-locale/countries";
import { getByCode } from "@visulima/iso-locale/currencies";
import { getTimezonesByCountry } from "@visulima/iso-locale/timezones";
```

## Requirements [#requirements]

* **Node.js:** 22.21 or higher


# Locale & BCP 47 (/docs/packages/iso-locale/locale)



# Locale & BCP 47 [#locale--bcp-47]

@visulima/iso-locale provides enhanced locale support with BCP 47 language tag parsing, generation, and currency mapping.

## Currency from Locale [#currency-from-locale]

Get currency code from locale or country code:

```typescript
import { getCurrency } from "@visulima/iso-locale";

// BCP 47 format
getCurrency("en-US"); // "USD"
getCurrency("pt-BR"); // "BRL"
getCurrency("zh-Hant-TW"); // "TWD"

// Underscore format
getCurrency("en_US"); // "USD"
getCurrency("pt_BR"); // "BRL"

// Direct country code
getCurrency("US"); // "USD"
getCurrency("GB"); // "GBP"
```

## BCP 47 Language Tags [#bcp-47-language-tags]

### Parse BCP 47 Tags [#parse-bcp-47-tags]

```typescript
import { parseBCP47Tag } from "@visulima/iso-locale";

const parsed = parseBCP47Tag("en-US");
console.log(parsed);
// { language: "en", country: "US" }

const parsed2 = parseBCP47Tag("zh-Hant-TW");
console.log(parsed2);
// { language: "zh", script: "Hant", country: "TW" }
```

### Generate BCP 47 Tags [#generate-bcp-47-tags]

```typescript
import { generateBCP47Tag } from "@visulima/iso-locale";

generateBCP47Tag("en", "US"); // "en-US"
generateBCP47Tag("fr", "FR"); // "fr-FR"
generateBCP47Tag("zh", "TW", "Hant"); // "zh-Hant-TW"
```

### Get BCP 47 Tags for Country [#get-bcp-47-tags-for-country]

```typescript
import { getBCP47Tags } from "@visulima/iso-locale";

// Single language country
getBCP47Tags("US"); // ["en-US"]

// Multi-language country
getBCP47Tags("CA"); // ["en-CA", "fr-CA"]
getBCP47Tags("CH"); // ["de-CH", "fr-CH", "it-CH", "rm-CH"]
```

### Validate BCP 47 Tags [#validate-bcp-47-tags]

```typescript
import { isValidBCP47Tag } from "@visulima/iso-locale";

isValidBCP47Tag("en-US"); // true
isValidBCP47Tag("zh-Hant-TW"); // true
isValidBCP47Tag("invalid"); // false
```

## ISO 639 Language Code Conversion [#iso-639-language-code-conversion]

Convert between ISO 639-3 (3-letter) and ISO 639-1 (2-letter) codes:

```typescript
import { iso6393To6391, convert6393To6391 } from "@visulima/iso-locale";

// Single conversion
iso6393To6391("eng"); // "en"
iso6393To6391("fra"); // "fr"
iso6393To6391("spa"); // "es"

// Array conversion
convert6393To6391(["eng", "fra", "spa"]); // ["en", "fr", "es"]
```

## Get Locales for Currency [#get-locales-for-currency]

Find all countries using a specific currency:

```typescript
import { getLocales } from "@visulima/iso-locale";

getLocales("EUR"); // ["FR", "DE", "ES", "IT", ...]
getLocales("USD"); // ["US", ...]
```

## Examples [#examples]

### Build Locale-Aware Currency Formatter [#build-locale-aware-currency-formatter]

```typescript
import { getCurrency, getSymbol, getByCode } from "@visulima/iso-locale";

function formatCurrencyByLocale(amount: number, locale: string): string {
    const currencyCode = getCurrency(locale);
    if (!currencyCode) return `${amount}`;

    const currency = getByCode(currencyCode);
    const symbol = getSymbol(currencyCode);
    const decimals = currency?.decimals ?? 2;

    return `${symbol}${amount.toFixed(decimals)}`;
}

formatCurrencyByLocale(100, "en-US"); // "$100.00"
formatCurrencyByLocale(100, "en-GB"); // "£100.00"
formatCurrencyByLocale(100, "fr-FR"); // "€100.00"
```

### Generate Locale Options for Select [#generate-locale-options-for-select]

```typescript
import { getBCP47Tags, getByAlpha2 } from "@visulima/iso-locale";

function getLocaleOptions(countryCode: string) {
    const tags = getBCP47Tags(countryCode);
    const country = getByAlpha2(countryCode);

    return tags.map((tag) => ({
        value: tag,
        label: `${tag} - ${country?.name}`,
    }));
}

getLocaleOptions("CA");
// [
//   { value: "en-CA", label: "en-CA - Canada" },
//   { value: "fr-CA", label: "fr-CA - Canada" }
// ]
```

### Parse User Locale Input [#parse-user-locale-input]

```typescript
import { parseBCP47Tag, getCurrency } from "@visulima/iso-locale";

function parseUserLocale(locale: string) {
    const parsed = parseBCP47Tag(locale);
    if (!parsed) {
        throw new Error(`Invalid locale: ${locale}`);
    }

    return {
        language: parsed.language,
        country: parsed.country,
        script: parsed.script,
        currency: parsed.country ? getCurrency(locale) : undefined,
    };
}

parseUserLocale("en-US");
// { language: "en", country: "US", currency: "USD" }
```

## Next Steps [#next-steps]

* [Countries](/docs/packages/iso-locale/countries) - Working with country data
* [Currencies](/docs/packages/iso-locale/currencies) - Working with currency data
* [API Reference](/docs/packages/iso-locale/api) - Complete API documentation


# Quick Start (/docs/packages/iso-locale/quick-start)



# Quick Start [#quick-start]

## Countries [#countries]

```typescript
import { getByAlpha2, getEmoji } from "@visulima/iso-locale";

const us = getByAlpha2("US");
console.log(us.name); // "United States"
console.log(getEmoji("US")); // "🇺🇸"
```

## Currencies [#currencies]

```typescript
import { getByCode, getSymbol } from "@visulima/iso-locale";

console.log(getSymbol("USD")); // "$"
console.log(getSymbol("EUR")); // "€"
```

## Timezones [#timezones]

```typescript
import { getTimezonesByCountry } from "@visulima/iso-locale";

console.log(getTimezonesByCountry("US"));
// ["America/New_York", "America/Los_Angeles", ...]
```

## BCP 47 [#bcp-47]

```typescript
import { parseBCP47Tag } from "@visulima/iso-locale";

const tag = parseBCP47Tag("en-US");
console.log(tag); // { language: "en", country: "US" }
```


# Regions (/docs/packages/iso-locale/regions)



# Regions [#regions]

@visulima/iso-locale provides comprehensive regional data based on the United Nations geoscheme, including continents, subregions, and intermediary regions.

## Region Data Structure [#region-data-structure]

Each region includes:

* **continent**: Continental region (e.g., "Africa", "Americas", "Asia", "Europe", "Oceania", "Antarctica")
* **intermediary**: Optional intermediary region (e.g., "Sub-Saharan Africa", "Latin America and the Caribbean")
* **subregion**: Geographical subregion (e.g., "Northern Africa", "Western Europe", "Eastern Asia")

## Getting Region Data [#getting-region-data]

### For a Country [#for-a-country]

```typescript
import { getRegionsForCountry } from "@visulima/iso-locale";

const region = getRegionsForCountry("US");
console.log(region.continent); // "Americas"
console.log(region.intermediary); // "North America"
console.log(region.subregion); // "Northern America"
```

## Finding Countries by Region [#finding-countries-by-region]

### By Continent [#by-continent]

```typescript
import { getCountriesInContinent } from "@visulima/iso-locale";

const africanCountries = getCountriesInContinent("Africa");
console.log(africanCountries.length); // ~50+ countries
console.log(africanCountries); // ["DZ", "EG", "KE", ...]

const europeanCountries = getCountriesInContinent("Europe");
console.log(europeanCountries.length); // ~40+ countries
```

### By Subregion [#by-subregion]

```typescript
import { getCountriesInSubregion } from "@visulima/iso-locale";

const westernEurope = getCountriesInSubregion("Western Europe");
console.log(westernEurope);
// ["AT", "BE", "FR", "DE", "LI", "LU", "MC", "NL", "CH"]

const easternAsia = getCountriesInSubregion("Eastern Asia");
console.log(easternAsia);
// ["CN", "HK", "MO", "KP", "JP", "MN", "KR"]
```

### By Intermediary Region [#by-intermediary-region]

```typescript
import { getCountriesInIntermediary } from "@visulima/iso-locale";

const subSaharanAfrica = getCountriesInIntermediary("Sub-Saharan Africa");
console.log(subSaharanAfrica.length); // ~40+ countries

const latinAmerica = getCountriesInIntermediary("Latin America and the Caribbean");
console.log(latinAmerica.length); // ~30+ countries
```

## Getting Available Regions [#getting-available-regions]

### All Continents [#all-continents]

```typescript
import { getContinents } from "@visulima/iso-locale";

const continents = getContinents();
console.log(continents);
// ["Africa", "Americas", "Antarctica", "Asia", "Europe", "Oceania"]
```

### All Subregions [#all-subregions]

```typescript
import { getSubregions } from "@visulima/iso-locale";

// Get all subregions
const allSubregions = getSubregions();
console.log(allSubregions.length); // ~20+ subregions

// Filter by continent
const europeanSubregions = getSubregions("Europe");
console.log(europeanSubregions);
// ["Eastern Europe", "Northern Europe", "Southern Europe", "Western Europe"]
```

### All Intermediary Regions [#all-intermediary-regions]

```typescript
import { getIntermediaryRegions } from "@visulima/iso-locale";

const intermediaries = getIntermediaryRegions();
console.log(intermediaries);
// ["Latin America and the Caribbean", "North America", "Sub-Saharan Africa"]
```

## Examples [#examples]

### Group Countries by Continent [#group-countries-by-continent]

```typescript
import { getCountriesInContinent, getContinents } from "@visulima/iso-locale";

function groupByContinent() {
    const continents = getContinents();
    const grouped: Record<string, string[]> = {};

    continents.forEach((continent) => {
        grouped[continent] = getCountriesInContinent(continent);
    });

    return grouped;
}
```

### Find Countries in Same Subregion [#find-countries-in-same-subregion]

```typescript
import { getRegionsForCountry, getCountriesInSubregion } from "@visulima/iso-locale";

function getNeighboringCountries(countryCode: string) {
    const region = getRegionsForCountry(countryCode);
    if (!region) return [];

    return getCountriesInSubregion(region.subregion).filter((code) => code !== countryCode);
}

getNeighboringCountries("DE");
// ["AT", "BE", "FR", "LI", "LU", "MC", "NL", "CH"]
```

### Filter Countries by Region [#filter-countries-by-region]

```typescript
import { getRegionsForCountry } from "@visulima/iso-locale";

function filterByRegion(countries: string[], continent: string) {
    return countries.filter((code) => {
        const region = getRegionsForCountry(code);
        return region?.continent === continent;
    });
}
```

## Next Steps [#next-steps]

* [Countries](/docs/packages/iso-locale/countries) - Working with country data
* [Timezones](/docs/packages/iso-locale/timezones) - Working with timezone data
* [API Reference](/docs/packages/iso-locale/api) - Complete API documentation


# Timezones (/docs/packages/iso-locale/timezones)



# Timezones [#timezones]

@visulima/iso-locale provides comprehensive IANA timezone database mappings, allowing you to find timezones for countries and countries for timezones.

## Getting Timezones [#getting-timezones]

### By Country [#by-country]

```typescript
import { getTimezonesByCountry, getPrimaryTimezone } from "@visulima/iso-locale";

// Get all timezones for a country
const timezones = getTimezonesByCountry("US");
console.log(timezones);
// ["America/New_York", "America/Los_Angeles", "America/Chicago", ...]

// Get primary timezone (first in list)
const primary = getPrimaryTimezone("US");
console.log(primary); // "America/Adak"
```

### Single Timezone Countries [#single-timezone-countries]

```typescript
import { getTimezonesByCountry } from "@visulima/iso-locale";

getTimezonesByCountry("GB"); // ["Europe/London"]
getTimezonesByCountry("FR"); // ["Europe/Paris"]
getTimezonesByCountry("JP"); // ["Asia/Tokyo"]
```

### Multi-Timezone Countries [#multi-timezone-countries]

```typescript
import { getTimezonesByCountry } from "@visulima/iso-locale";

// United States has many timezones
getTimezonesByCountry("US").length; // 29 timezones

// Canada has many timezones
getTimezonesByCountry("CA").length; // 27 timezones

// Australia has multiple timezones
getTimezonesByCountry("AU");
// ["Australia/Adelaide", "Australia/Brisbane", "Australia/Sydney", ...]

// Russia has many timezones
getTimezonesByCountry("RU").length; // 26 timezones
```

## Finding Countries by Timezone [#finding-countries-by-timezone]

```typescript
import { getCountriesForTimezone } from "@visulima/iso-locale";

// Find countries using a specific timezone
const countries = getCountriesForTimezone("Europe/London");
console.log(countries); // ["GB", ...]

const countries2 = getCountriesForTimezone("America/New_York");
console.log(countries2); // ["US"]
```

## All Timezones [#all-timezones]

```typescript
import { all as timezonesAll } from "@visulima/iso-locale";

const allTimezones = timezonesAll();
console.log(allTimezones.length); // 400+ timezones
console.log(allTimezones);
// ["Africa/Abidjan", "Africa/Accra", ...] (sorted)
```

## Validation [#validation]

```typescript
import { isValidTimezone } from "@visulima/iso-locale";

isValidTimezone("Europe/London"); // true
isValidTimezone("America/New_York"); // true
isValidTimezone("Invalid/Timezone"); // false
```

## Indexed Access [#indexed-access]

For fast lookups, use the indexed map:

```typescript
import { timezonesByCountry } from "@visulima/iso-locale";

const timezones = timezonesByCountry["US"];
console.log(timezones); // readonly array of timezones
```

## Examples [#examples]

### Get Primary Timezone for Country [#get-primary-timezone-for-country]

```typescript
import { getPrimaryTimezone } from "@visulima/iso-locale";

function getCountryTimezone(countryCode: string) {
    return getPrimaryTimezone(countryCode);
}

getCountryTimezone("US"); // "America/Adak"
getCountryTimezone("GB"); // "Europe/London"
```

### Find Countries in Same Timezone [#find-countries-in-same-timezone]

```typescript
import { getCountriesForTimezone, getTimezonesByCountry } from "@visulima/iso-locale";

function getCountriesInSameTimezone(countryCode: string) {
    const timezones = getTimezonesByCountry(countryCode);
    if (timezones.length === 0) return [];

    // Get countries for the primary timezone
    return getCountriesForTimezone(timezones[0]);
}
```

### Validate Timezone Before Use [#validate-timezone-before-use]

```typescript
import { isValidTimezone } from "@visulima/iso-locale";

function safeTimezoneOperation(timezone: string) {
    if (!isValidTimezone(timezone)) {
        throw new Error(`Invalid timezone: ${timezone}`);
    }

    // Use timezone with date libraries like date-fns, dayjs, etc.
    // Example with date-fns-tz:
    // import { zonedTimeToUtc } from "date-fns-tz";
    // return zonedTimeToUtc(new Date(), timezone);
}
```

### List All Countries with Timezones [#list-all-countries-with-timezones]

```typescript
import { getCountriesWithTimezones } from "@visulima/iso-locale";

const countries = getCountriesWithTimezones();
console.log(countries.length); // 200+ countries
```

## Next Steps [#next-steps]

* [Countries](/docs/packages/iso-locale/countries) - Working with country data
* [Regions](/docs/packages/iso-locale/regions) - Working with regional data
* [Locale & BCP 47](/docs/packages/iso-locale/locale) - Working with locales
* [API Reference](/docs/packages/iso-locale/api) - Complete API documentation


# Usage (/docs/packages/iso-locale/usage)



# Usage Guide [#usage-guide]

## Countries [#countries]

```typescript
import { getByAlpha2, getAllCountries, getEmoji } from "@visulima/iso-locale";

// Get by code
const country = getByAlpha2("DE");

// Get all
const all = getAllCountries();

// Get flag
console.log(getEmoji("FR")); // "🇫🇷"
```

## Currencies [#currencies]

```typescript
import { getByCode, getSymbol, getByCountry } from "@visulima/iso-locale";

const usd = getByCode("USD");
console.log(getSymbol("GBP")); // "£"
const currencies = getByCountry("US");
```

## Regions [#regions]

```typescript
import { getRegionsForCountry, getCountriesInContinent } from "@visulima/iso-locale";

const region = getRegionsForCountry("BR");
const europe = getCountriesInContinent("Europe");
```

## Timezones [#timezones]

```typescript
import { getTimezonesByCountry, getPrimaryTimezone } from "@visulima/iso-locale";

const zones = getTimezonesByCountry("CA");
const primary = getPrimaryTimezone("GB"); // "Europe/London"
```


# API Reference (/docs/packages/jsdoc-open-api/api)



# API Reference [#api-reference]

Complete API documentation for jsdoc-open-api.

## jsdocOpenApi() [#jsdocopenapi]

Main function to generate OpenAPI specification.

```typescript
function jsdocOpenApi(options: Options): Promise<OpenAPIObject>;
```

**Parameters:**

* `options` - Configuration options

**Returns:** Promise resolving to OpenAPI specification object

**Example:**

```javascript
import jsdocOpenApi from "@visulima/jsdoc-open-api";

const spec = await jsdocOpenApi({
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
        },
    },
    sources: ["./src/**/*.js"],
    output: "./swagger.json",
});
```

## Options [#options]

Configuration options interface.

```typescript
interface Options {
    definition: BaseDefinition;
    sources: string[];
    output?: string | false;
    verbose?: boolean;
}
```

### definition [#definition]

Base OpenAPI definition object.

```typescript
interface BaseDefinition {
    openapi: string;
    info: InfoObject;
    servers?: ServerObject[];
    security?: SecurityRequirementObject[];
    tags?: TagObject[];
    externalDocs?: ExternalDocumentationObject;
    components?: ComponentsObject;
}
```

### sources [#sources]

Array of glob patterns for source files.

* **Type**: `string[]`
* **Required**: Yes

**Example:**

```javascript
{
    sources: ["./src/routes/**/*.js", "./src/api/**/*.ts", "!./src/**/*.test.js"];
}
```

### output [#output]

Output file path or `false` to skip file writing.

* **Type**: `string | false`
* **Default**: `false`

**Example:**

```javascript
{
    output: "./public/swagger.json"; // Write to file
}

{
    output: false; // Don't write file
}
```

### verbose [#verbose]

Enable verbose logging.

* **Type**: `boolean`
* **Default**: `false`

## SwaggerCompilerPlugin [#swaggercompilerplugin]

Webpack plugin for automatic generation.

```typescript
class SwaggerCompilerPlugin {
    constructor(outputPath: string, sources: string[], definition: BaseDefinition, options?: { verbose?: boolean });
}
```

**Parameters:**

* `outputPath` - Absolute path for output file
* `sources` - Array of absolute source paths
* `definition` - Base OpenAPI definition
* `options` - Plugin options

**Example:**

```javascript
import { SwaggerCompilerPlugin } from "@visulima/jsdoc-open-api";

const plugin = new SwaggerCompilerPlugin(
    "/path/to/output/swagger.json",
    ["/path/to/src/**/*.js"],
    {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
        },
    },
    { verbose: true },
);

// Add to webpack config
module.exports = {
    plugins: [plugin],
};
```

## SpecBuilder [#specbuilder]

Low-level API for building specifications.

```typescript
class SpecBuilder {
    constructor(definition: BaseDefinition);

    addPath(path: string, method: string, operation: OperationObject): void;
    addSchema(name: string, schema: SchemaObject): void;
    addSecurityScheme(name: string, scheme: SecuritySchemeObject): void;
    addTag(tag: TagObject): void;

    build(): OpenAPIObject;
}
```

**Example:**

```javascript
import { SpecBuilder } from "@visulima/jsdoc-open-api";

const builder = new SpecBuilder({
    openapi: "3.0.0",
    info: {
        title: "My API",
        version: "1.0.0",
    },
});

builder.addPath("/users", "get", {
    summary: "Get users",
    responses: {
        200: { description: "Success" },
    },
});

const spec = builder.build();
```

## parseFile() [#parsefile]

Parse a single file for JSDoc comments.

```typescript
function parseFile(filePath: string): Promise<ParsedComment[]>;
```

**Parameters:**

* `filePath` - Absolute path to file

**Returns:** Array of parsed JSDoc comments

**Example:**

```javascript
import { parseFile } from "@visulima/jsdoc-open-api";

const comments = await parseFile("./src/routes/users.js");
console.log(comments);
```

## jsDocumentCommentsToOpenApi() [#jsdocumentcommentstoopenapi]

Convert JSDoc comments to OpenAPI paths.

```typescript
function jsDocumentCommentsToOpenApi(comments: ParsedComment[]): OpenAPIObject;
```

**Parameters:**

* `comments` - Array of parsed comments

**Returns:** OpenAPI object with paths

## Type Definitions [#type-definitions]

### OpenAPIObject [#openapiobject]

Complete OpenAPI specification.

```typescript
interface OpenAPIObject {
    openapi: string;
    info: InfoObject;
    servers?: ServerObject[];
    paths?: PathsObject;
    components?: ComponentsObject;
    security?: SecurityRequirementObject[];
    tags?: TagObject[];
    externalDocs?: ExternalDocumentationObject;
}
```

### InfoObject [#infoobject]

API information.

```typescript
interface InfoObject {
    title: string;
    version: string;
    description?: string;
    termsOfService?: string;
    contact?: ContactObject;
    license?: LicenseObject;
}
```

### ServerObject [#serverobject]

Server information.

```typescript
interface ServerObject {
    url: string;
    description?: string;
    variables?: Record<string, ServerVariableObject>;
}
```

### OperationObject [#operationobject]

API operation (endpoint).

```typescript
interface OperationObject {
    summary?: string;
    description?: string;
    operationId?: string;
    tags?: string[];
    parameters?: ParameterObject[];
    requestBody?: RequestBodyObject;
    responses: ResponsesObject;
    security?: SecurityRequirementObject[];
    deprecated?: boolean;
}
```


# JSDoc Comment Syntax (/docs/packages/jsdoc-open-api/concepts/syntax)



# JSDoc Comment Syntax [#jsdoc-comment-syntax]

Learn the two main syntaxes for defining OpenAPI specifications in JSDoc comments.

## Standard OpenAPI Syntax [#standard-openapi-syntax]

Use full OpenAPI YAML/JSON syntax within JSDoc comments.

### Basic Endpoint [#basic-endpoint]

```javascript
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     description: Retrieve a list of users from the database
 *     tags:
 *       - Users
 *     responses:
 *       200:
 *         description: Success
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 */
export function getUsers(req, res) {}
```

### With Parameters [#with-parameters]

```javascript
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         description: User ID
 *         schema:
 *           type: integer
 *       - name: include
 *         in: query
 *         description: Include related data
 *         schema:
 *           type: string
 *           enum: [posts, comments, profile]
 *     responses:
 *       200:
 *         description: User found
 *       404:
 *         description: User not found
 */
export function getUserById(req, res) {}
```

### With Request Body [#with-request-body]

```javascript
/**
 * @openapi
 * /users:
 *   post:
 *     summary: Create user
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               password:
 *                 type: string
 *                 minLength: 8
 *               name:
 *                 type: string
 *     responses:
 *       201:
 *         description: User created
 *       400:
 *         description: Validation error
 */
export function createUser(req, res) {}
```

## Short Syntax [#short-syntax]

Concise notation for common API definitions.

### Basic Endpoint [#basic-endpoint-1]

```javascript
/**
 * GET /users
 * @summary Get all users
 * @description Retrieve a list of users
 * @tags Users
 * @response 200 - Success
 */
export function getUsers(req, res) {}
```

### With Parameters [#with-parameters-1]

```javascript
/**
 * GET /users/{id}
 * @summary Get user by ID
 * @tags Users
 * @pathparam {integer} id.required - User ID
 * @queryparam {string} include - Include related data
 * @response 200 - User found
 * @response 404 - User not found
 */
export function getUserById(req, res) {}
```

### With Request Body [#with-request-body-1]

```javascript
/**
 * POST /users
 * @summary Create user
 * @tags Users
 * @bodyparam {string} email.required - User email
 * @bodyparam {string} password.required - User password (min 8 chars)
 * @bodyparam {string} name - User full name
 * @response 201 - User created
 * @response 400 - Validation error
 */
export function createUser(req, res) {}
```

## Schema Definitions [#schema-definitions]

Define reusable schemas.

### Component Schemas [#component-schemas]

```javascript
/**
 * @openapi
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - email
 *       properties:
 *         id:
 *           type: integer
 *         email:
 *           type: string
 *           format: email
 *         name:
 *           type: string
 *         createdAt:
 *           type: string
 *           format: date-time
 *
 *     Post:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *         title:
 *           type: string
 *         content:
 *           type: string
 *         authorId:
 *           type: integer
 */
```

### Referencing Schemas [#referencing-schemas]

```javascript
/**
 * @openapi
 * /users:
 *   post:
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/User'
 *     responses:
 *       201:
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */
export function createUser(req, res) {}
```

## Security Schemes [#security-schemes]

Define authentication methods.

### API Key [#api-key]

```javascript
/**
 * @openapi
 * components:
 *   securitySchemes:
 *     ApiKey:
 *       type: apiKey
 *       in: header
 *       name: X-API-Key
 */

/**
 * @openapi
 * /admin/users:
 *   get:
 *     security:
 *       - ApiKey: []
 *     responses:
 *       200:
 *         description: Success
 *       401:
 *         description: Unauthorized
 */
export function getAdminUsers(req, res) {}
```

### Bearer Token [#bearer-token]

```javascript
/**
 * @openapi
 * components:
 *   securitySchemes:
 *     BearerAuth:
 *       type: http
 *       scheme: bearer
 *       bearerFormat: JWT
 */

/**
 * @openapi
 * /profile:
 *   get:
 *     security:
 *       - BearerAuth: []
 *     summary: Get user profile
 */
export function getProfile(req, res) {}
```

## Tags and Groups [#tags-and-groups]

Organize endpoints with tags.

```javascript
/**
 * @openapi
 * tags:
 *   - name: Users
 *     description: User management endpoints
 *   - name: Posts
 *     description: Blog post endpoints
 *   - name: Admin
 *     description: Administrative endpoints
 */

/**
 * @openapi
 * /users:
 *   get:
 *     tags:
 *       - Users
 *     summary: Get all users
 */
export function getUsers(req, res) {}
```

## Multiple HTTP Methods [#multiple-http-methods]

Document multiple methods on same path.

```javascript
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *   put:
 *     summary: Update user
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/User'
 *   delete:
 *     summary: Delete user
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 */
export function handleUser(req, res) {}
```

## Response Examples [#response-examples]

Add example responses.

```javascript
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     responses:
 *       200:
 *         description: User found
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *             examples:
 *               user:
 *                 value:
 *                   id: 1
 *                   email: user@example.com
 *                   name: John Doe
 *                   createdAt: "2024-01-01T00:00:00Z"
 */
export function getUserById(req, res) {}
```

## Comparison [#comparison]

| Feature        | Standard Syntax            | Short Syntax        |
| -------------- | -------------------------- | ------------------- |
| Verbosity      | More verbose               | Concise             |
| Flexibility    | Full control               | Limited options     |
| Learning curve | OpenAPI knowledge required | Easier to learn     |
| Best for       | Complex APIs               | Simple endpoints    |
| Examples       | Full schema definitions    | Quick documentation |

Choose the syntax that best fits your needs - or mix both in the same project!


# Configuration (/docs/packages/jsdoc-open-api/configuration)



# Configuration [#configuration]

Configure jsdoc-open-api using configuration files or programmatic options.

## Configuration File [#configuration-file]

Create `.openapirc.js` in your project root:

```javascript
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
            description: "API documentation",
            contact: {
                name: "API Support",
                email: "support@example.com",
            },
            license: {
                name: "MIT",
                url: "https://opensource.org/licenses/MIT",
            },
        },
        servers: [
            {
                url: "https://api.example.com/v1",
                description: "Production server",
            },
            {
                url: "https://staging-api.example.com/v1",
                description: "Staging server",
            },
            {
                url: "http://localhost:3000",
                description: "Development server",
            },
        ],
    },
    sources: ["./src/routes/**/*.js", "./src/controllers/**/*.js"],
    output: "./public/swagger.json",
    verbose: false,
};
```

## Programmatic Configuration [#programmatic-configuration]

Pass options to the function:

```javascript
import jsdocOpenApi from "@visulima/jsdoc-open-api";

const spec = await jsdocOpenApi({
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
        },
    },
    sources: ["./src/**/*.js"],
    output: "./swagger.json",
    verbose: true,
});
```

## Definition Options [#definition-options]

### info [#info]

API metadata:

```javascript
{
  info: {
    title: "My API",                      // Required
    version: "1.0.0",                     // Required
    description: "API documentation",
    termsOfService: "https://example.com/terms",
    contact: {
      name: "API Support",
      url: "https://example.com/support",
      email: "support@example.com",
    },
    license: {
      name: "MIT",
      url: "https://opensource.org/licenses/MIT",
    },
  },
}
```

### servers [#servers]

API servers:

```javascript
{
  servers: [
    {
      url: "https://api.example.com",
      description: "Production",
      variables: {
        version: {
          default: "v1",
          enum: ["v1", "v2"],
        },
      },
    },
  ],
}
```

### security [#security]

Global security:

```javascript
{
  definition: {
    security: [
      {
        BearerAuth: [],
      },
    ],
    components: {
      securitySchemes: {
        BearerAuth: {
          type: "http",
          scheme: "bearer",
          bearerFormat: "JWT",
        },
      },
    },
  },
}
```

## Source Patterns [#source-patterns]

Specify files to parse:

```javascript
{
  sources: [
    "./src/routes/**/*.js",       // All JS files in routes
    "./src/api/**/*.ts",           // All TS files in api
    "./lib/controllers/*.{js,ts}", // JS or TS in controllers
    "!./src/**/*.test.js",         // Exclude test files
  ],
}
```

## Output Options [#output-options]

### File Output [#file-output]

```javascript
{
  output: "./public/swagger.json",  // Write to file
}
```

### No File Output [#no-file-output]

```javascript
{
  output: false,  // Don't write file, only return spec
}
```

## Verbosity [#verbosity]

Enable logging:

```javascript
{
  verbose: true,  // Enable verbose logging
}
```

## Environment-Based Configuration [#environment-based-configuration]

Use environment variables:

```javascript
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: process.env.npm_package_version || "1.0.0",
        },
        servers: [
            {
                url: process.env.API_URL || "http://localhost:3000",
            },
        ],
    },
    sources: ["./src/**/*.js"],
    output: process.env.SWAGGER_OUTPUT || "./swagger.json",
    verbose: process.env.VERBOSE === "true",
};
```

## TypeScript Configuration [#typescript-configuration]

For TypeScript projects:

```javascript
// .openapirc.js
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "TypeScript API",
            version: "1.0.0",
        },
    },
    sources: ["./src/**/*.ts", "!./src/**/*.test.ts", "!./src/**/*.spec.ts"],
    output: "./docs/api-spec.json",
};
```

## Multiple Configurations [#multiple-configurations]

Create environment-specific configs:

```javascript
// config/openapi.prod.js
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "Production API",
            version: "1.0.0",
        },
        servers: [
            {
                url: "https://api.example.com",
            },
        ],
    },
    sources: ["./dist/**/*.js"],
    output: "./public/swagger.json",
};

// config/openapi.dev.js
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "Development API",
            version: "1.0.0-dev",
        },
        servers: [
            {
                url: "http://localhost:3000",
            },
        ],
    },
    sources: ["./src/**/*.ts"],
    output: "./dev-swagger.json",
    verbose: true,
};
```

Use with CLI:

```bash
npx jsdoc-open-api generate --config ./config/openapi.prod.js
```


# Introduction (/docs/packages/jsdoc-open-api)



# @visulima/jsdoc-open-api [#visulimajsdoc-open-api]

Automatically generate OpenAPI/Swagger specifications from JSDoc comments in your JavaScript/TypeScript code. Supports multiple syntax styles, provides a CLI tool, and integrates with build systems like Webpack and Next.js.

## Key Features [#key-features]

**Generation Methods**

* **CLI Tool** - Command-line interface for quick generation
* **Programmatic API** - JavaScript/TypeScript API for build processes
* **Webpack Plugin** - Seamless integration with Webpack and Next.js
* **Build Automation** - Automatic regeneration during development

**Syntax Support**

* **Standard OpenAPI** - Full YAML/JSON syntax within JSDoc comments
* **Short Syntax** - Concise notation for common API definitions
* **Flexible Comments** - Multiple comment styles and formats
* **Type Inference** - Automatic type extraction from JSDoc tags

**OpenAPI Features**

* **OpenAPI 3.0+** - Full OpenAPI 3.x specification support
* **Paths & Operations** - HTTP methods, parameters, responses
* **Schemas & Models** - Request/response body definitions
* **Security** - Authentication and authorization schemes
* **Tags & Groups** - Organize endpoints with tags

**Performance**

* **Fast Parsing** - Optimized comment extraction
* **Incremental Generation** - Only processes changed files
* **Low Overhead** - Minimal impact on build times
* **Caching** - Smart caching for repeated builds

## Quick Start [#quick-start]

```javascript
import jsdocOpenApi from "@visulima/jsdoc-open-api";

const spec = await jsdocOpenApi({
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
        },
    },
    sources: ["./src/routes/**/*.js"],
});

console.log(spec);
```

## Use Cases [#use-cases]

### API Documentation Generation [#api-documentation-generation]

Automatically generate API documentation from your code:

```javascript
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     tags: [Users]
 *     responses:
 *       200:
 *         description: Success
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
export async function getUsers(req, res) {
    const users = await db.users.findMany();
    res.json(users);
}
```

Generate specification:

```bash
npx jsdoc-open-api generate src/routes/
```

### Next.js Integration [#nextjs-integration]

Integrate with Next.js using the Webpack plugin:

```javascript
// next.config.js
const withOpenApi = require("./with-open-api");

module.exports = withOpenApi({
    definition: {
        openapi: "3.0.0",
        info: {
            title: "Next.js API",
            version: "1.0.0",
        },
    },
    sources: ["./app/api/**/*.ts"],
    output: "public/swagger.json",
})({
    // Your Next.js config
});
```

### Build Process Integration [#build-process-integration]

Integrate into your build pipeline:

```javascript
// scripts/generate-api-docs.js
import jsdocOpenApi from "@visulima/jsdoc-open-api";
import { writeFileSync } from "fs";

async function generate() {
    const spec = await jsdocOpenApi({
        definition: {
            openapi: "3.0.0",
            info: {
                title: "API Documentation",
                version: process.env.npm_package_version,
            },
            servers: [
                {
                    url: "https://api.example.com",
                    description: "Production",
                },
            ],
        },
        sources: ["./src/api/**/*.ts"],
    });

    writeFileSync("./docs/api-spec.json", JSON.stringify(spec, null, 2));
    console.log("API specification generated!");
}

generate();
```

Add to `package.json`:

```json
{
    "scripts": {
        "docs": "node scripts/generate-api-docs.js",
        "prebuild": "npm run docs"
    }
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/jsdoc-open-api/installation">
    Install and set up jsdoc-open-api
  </Card>

  <Card title="Quick Start" href="/docs/packages/jsdoc-open-api/quick-start">
    Generate your first OpenAPI spec
  </Card>

  <Card title="Syntax Guide" href="/docs/packages/jsdoc-open-api/concepts/syntax">
    Learn the JSDoc comment syntax
  </Card>

  <Card title="API Reference" href="/docs/packages/jsdoc-open-api/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package is designed for build-time use:

* **Node.js** - Version 22.x and above
* **Webpack** - Version 5.x and above (for plugin usage)
* **Environment** - Build tools and development servers


# Installation (/docs/packages/jsdoc-open-api/installation)



# Installation [#installation]

Install jsdoc-open-api using your preferred package manager:

```bash npm2yarn
npm install @visulima/jsdoc-open-api
```

## Optional Dependencies [#optional-dependencies]

The CLI requires additional packages:

```bash npm2yarn
npm install commander cli-progress
```

These are listed as `optionalDependencies` and may install automatically depending on your package manager.

### For Webpack/Next.js [#for-webpacknextjs]

If using the Webpack plugin:

```bash npm2yarn
npm install webpack
```

## Import [#import]

### ESM (Recommended) [#esm-recommended]

```javascript
import jsdocOpenApi from "@visulima/jsdoc-open-api";
import { SwaggerCompilerPlugin } from "@visulima/jsdoc-open-api";
```

### CommonJS [#commonjs]

```javascript
const jsdocOpenApi = require("@visulima/jsdoc-open-api");
const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
```

### Subpath Imports [#subpath-imports]

```javascript
// CLI utilities
import { initCommand, generateCommand } from "@visulima/jsdoc-open-api/cli";

// Commander.js integration
import { program } from "@visulima/jsdoc-open-api/cli/commander";
```

## Requirements [#requirements]

* **Node.js**: 22.x or higher
* **Package Manager**: npm, yarn, pnpm, or bun
* **Build Tools**: Webpack 5.x (for plugin usage)

## CLI Setup [#cli-setup]

After installation, the CLI is available:

```bash
# Using npx
npx jsdoc-open-api --help

# Using pnpm
pnpm exec jsdoc-open-api --help

# Using yarn
yarn jsdoc-open-api --help
```

Initialize configuration:

```bash
npx jsdoc-open-api init
```

This creates `.openapirc.js`:

```javascript
module.exports = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "My API",
            version: "1.0.0",
        },
    },
    sources: ["./src/routes/**/*.js"],
    output: "./swagger.json",
};
```

## Verification [#verification]

Verify your installation by generating a simple spec:

```javascript
// test-generation.js
import jsdocOpenApi from "@visulima/jsdoc-open-api";

const spec = await jsdocOpenApi({
    definition: {
        openapi: "3.0.0",
        info: {
            title: "Test API",
            version: "1.0.0",
        },
    },
    sources: ["./src/**/*.js"],
});

console.log("Paths:", Object.keys(spec.paths || {}));
```

Run it:

```bash
node test-generation.js
```


# Quick Start (/docs/packages/jsdoc-open-api/quick-start)



# Quick Start [#quick-start]

Generate your first OpenAPI specification from JSDoc comments in under 5 minutes.

## Add JSDoc Comments [#add-jsdoc-comments]

Add OpenAPI documentation to your API endpoints:

```javascript
// src/routes/users.js

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     description: Retrieve a list of all users
 *     tags:
 *       - Users
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
export async function getUsers(req, res) {
    const users = await db.users.findMany();
    res.json(users);
}

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     tags:
 *       - Users
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: User found
 *       404:
 *         description: User not found
 */
export async function getUserById(req, res) {
    const user = await db.users.findUnique({ where: { id: req.params.id } });
    if (!user) {
        return res.status(404).json({ error: "User not found" });
    }
    res.json(user);
}
```

## Generate with CLI [#generate-with-cli]

Use the CLI to generate the specification:

```bash
# Initialize configuration
npx jsdoc-open-api init

# Generate specification
npx jsdoc-open-api generate src/routes/
```

Output `swaggerSpec.json`:

```json
{
    "openapi": "3.0.0",
    "info": {
        "title": "My API",
        "version": "1.0.0"
    },
    "paths": {
        "/users": {
            "get": {
                "summary": "Get all users",
                "description": "Retrieve a list of all users",
                "tags": ["Users"],
                "responses": {
                    "200": {
                        "description": "List of users"
                    }
                }
            }
        },
        "/users/{id}": {
            "get": {
                "summary": "Get user by ID",
                "tags": ["Users"],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": { "description": "User found" },
                    "404": { "description": "User not found" }
                }
            }
        }
    }
}
```

## Generate Programmatically [#generate-programmatically]

Use the JavaScript API:

```javascript
// scripts/generate-docs.js
import jsdocOpenApi from "@visulima/jsdoc-open-api";
import { writeFileSync } from "fs";

async function generate() {
    const spec = await jsdocOpenApi({
        definition: {
            openapi: "3.0.0",
            info: {
                title: "My API",
                version: "1.0.0",
                description: "API documentation",
            },
            servers: [
                {
                    url: "http://localhost:3000",
                    description: "Development server",
                },
            ],
        },
        sources: ["./src/routes/**/*.js"],
    });

    writeFileSync("./swagger.json", JSON.stringify(spec, null, 2));
    console.log("✅ OpenAPI spec generated!");
}

generate();
```

Run it:

```bash
node scripts/generate-docs.js
```

## Short Syntax [#short-syntax]

Use the concise short syntax:

```javascript
/**
 * GET /api/posts
 * @summary Get all posts
 * @tags Posts
 * @response 200 - Success
 */
export async function getPosts(req, res) {
    // ...
}

/**
 * POST /api/posts
 * @summary Create post
 * @tags Posts
 * @bodyparam {string} title.required - Post title
 * @bodyparam {string} content - Post content
 * @response 201 - Created
 * @response 400 - Validation error
 */
export async function createPost(req, res) {
    // ...
}
```

## Define Schemas [#define-schemas]

Add reusable schemas:

```javascript
/**
 * @openapi
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - email
 *       properties:
 *         id:
 *           type: integer
 *         email:
 *           type: string
 *           format: email
 *         name:
 *           type: string
 *         createdAt:
 *           type: string
 *           format: date-time
 */
```

Reference schemas in endpoints:

```javascript
/**
 * @openapi
 * /users:
 *   post:
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/User'
 *     responses:
 *       201:
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */
export async function createUser(req, res) {
    // ...
}
```

## View Documentation [#view-documentation]

Use Swagger UI to view your specification:

```javascript
// server.js with Express
import express from "express";
import swaggerUi from "swagger-ui-express";
import spec from "./swagger.json" assert { type: "json" };

const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));

app.listen(3000, () => {
    console.log("API docs: http://localhost:3000/api-docs");
});
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Syntax Guide" href="/docs/packages/jsdoc-open-api/concepts/syntax">
    Learn all JSDoc comment syntaxes
  </Card>

  <Card title="CLI Usage">
    Explore CLI commands and options
  </Card>

  <Card title="Webpack Integration">
    Integrate with build tools
  </Card>
</Cards>


# Authentication (/docs/packages/jsdoc-open-api/short/authentication)



## Authentication [#authentication]

Coming soon


# Describing Parameters (/docs/packages/jsdoc-open-api/short/describing-parameters)



## Describing Parameters [#describing-parameters]

Parameters are defined with `@pathParam`, `@queryParam`, `@headerParam`, `@cookieParam` or `@paramComponent`.
To describe a parameter, you specify its data type, name, and description.
To denote a parameter as optional, enclose its name in square brackets `[ ]`.
Here is an example:

```js
/**
 * GET /users/{userId}
 * @summary Get a user by ID.
 * @pathParam {integer} userId - Numeric ID of the user to get.
 * @queryParam {boolean} [verbose] - Return all user information.
 */
```

### Parameter types [#parameter-types]

OpenAPI 3.0 distinguishes between the following parameter types based on the parameter location.

* [path parameters](#Parameter-parameters), such as `/users/{id}`
* [query parameters](#Query-parameters), such as `/users?role=admin`
* [header parameters](#Header-parameters), such as `X-MyHeader: Value`
* [cookie parameters](#Cookie-parameters), which are passed in the `Cookie` header, such as `Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU`

### Parameter parameters [#parameter-parameters]

Path parameters are variable parts of a URL path.
They are typically used to point to a specific resource within a collection, such as a user identified by ID.
A URL can have several path parameters, each denoted with curly braces `{ }`.

```
GET /users/{id}
GET /cars/{carId}/drivers/{driverId}
GET /report.{format}
```

Each path parameter must be substituted with an actual value when the client makes an API call.
In OpenAPI, a path parameter is defined using `@pathParam`.
The parameter name must be the same as specified in the path.
Also remember path parameters are always required.
For example, the `/users/{id}` endpoint would be described as:

```js
/**
 * GET /users/{id}
 * @summary Get a user by ID.
 * @pathParam {integer} id - The user ID
 */
```

### Query parameters [#query-parameters]

Query parameters are the most common type of parameters.
They appear at the end of the request URL after a question mark (`?`),
with different `name=value` pairs separated by ampersands (`&`).
Query parameters can be required and optional.

Use `@queryParam` to denote query parameters:

```js
/**
 * @queryParam {integer} [offset] - The number of items to skip before starting to collect the result set
 * @queryParam {integer} [limit] - The numbers of items to return
 */
```

> **Note:** To describe API keys passed as query parameters, use `securitySchemes` and `security` instead.
> See Authentication.

### Header parameters [#header-parameters]

An API call may require that custom headers be sent with an HTTP request.
OpenAPI lets you define custom request headers with `@headerParam`.
For example, suppose, a call to `GET /ping` requires the `X-Request-ID` header:

```
GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac
```

You would define this operation as follows:

```js
/**
 * GET /ping
 * @summary Checks if the server is alive
 * @headerParam {string} X-Request-ID
 */
```

> **Note:** Header parameters named `Accept`, `Content-Type` and `Authorization` are not allowed.

### Cookie parameters [#cookie-parameters]

Operations can also pass parameters in the `Cookie` header, as `Cookie: name=value`.
Multiple cookie parameters are sent in the same header, separated by a semicolon, and space.

```
GET /api/users
Host: example.com
Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ
```

Use `@cookieParam` to define cookie parameters:

```js
/**
 * @cookieParam {integer} [debug]
 * @cookieParam {string} [csrftoken]
 */
```

> **Note:** To define cookie authentication, use `securitySchemes` and `security` instead.
> See Authentication.

### Required and optional parameters [#required-and-optional-parameters]

By default, all request parameters are treated as required.
You can enclose the parameter’s name in square brackets `[ ]` to mark it as optional.
Path parameters are always required.

### Default parameter values [#default-parameter-values]

Append `=value` to the variable name to specify the default value for an optional parameter.
The default value is the one that the server uses if the client does not supply the parameter value in the request.
The value type must be the same as the parameter’s data type.
A typical example is paging parameters such as offset and limit:

```
GET /users
GET /users?offset=30&limit=10
```

Assuming `offset` defaults to 0 and `limit` defaults to 20, you would define these parameters as:

```js
/**
 * @queryParam {integer} [offset=0] - The number of items to skip before starting to collect the result set.
 * @queryParam {integer} [limit=20] - The number of items to return.
 */
```

### Enum parameters [#enum-parameters]

You can restrict a parameter to a fixed set of values by adding the `enum` to the `schema`.
The enum values must be of the same type as the parameter data type.

```js
/**
 * @queryParam {Status} [status]
 */
```

```yaml
"components":
    "schemas":
        "Status":
            "type": "string"
            "enum":
                - "available"
                - "pending"
                - "sold"
```

### Reusable Parameters [#reusable-parameters]

Parameters can be defined in `components` to be reused elsewhere.
The following parameter definition:

```yaml
"components":
    "parameters":
        "ExampleParameter":
            "in": "query"
            "name": "limit"
            "schema":
                "type": "integer"
                "minimum": 1
                "maximum": 100
                "default": 20
            "required": false
            "description": "The number of items to return."
```

Can be used as:

```js
/**
 * @paramComponent {ExampleParameter}
 */
```


# Describing Request Body (/docs/packages/jsdoc-open-api/short/describing-request-body)



## Describing Request Body [#describing-request-body]

Request bodies are typically used with "create" and "update" operations (POST, PUT, PATCH).
For example, when creating a resource using POST or PUT,
the request body usually contains the representation of the resource to be created.

It’s important to unlike parameters, **request bodies are optional by default**.
To mark the body as required, use `@bodyRequired`.

```js
/**
 * POST /pets
 * @summary Add a new pet
 * @bodyDescription Optional description in *Markdown*
 * @bodyContent {Pet} application/json
 * @bodyContent {Pet} application/xml
 * @bodyContent {PetForm} application/x-www-form-urlencoded
 * @bodyContent {string} text/plain
 * @bodyRequired
 * @response 201 - Created
 */
```

`@bodyContent` allows wildcard media types.
For example, `image/*` represents all image types; `*/*` represents all types and is functionally equivalent to `application/octet-stream`.
Specific media types have preference over wildcard media types when interpreting the spec, for example, `image/png` > `image/*` > `*/*`.

> **Note:** `*/*` must be escaped in comments with `*\/*`.

```js
// Can be image/png, image/svg, image/gif, etc.
/**
 * PUT /avatar
 * @summary Upload an avatar
 * @bodyContent {binary} image/*
 * @bodyRequired
 * @response 201 - Created
 */
```

```js
// Can be anything.
/**
 * PUT /file
 * @summary Upload any file
 * @bodyContent {binary} *\/*
 * @bodyRequired
 * @response 201 - Created
 */
```

### Reusable request bodies [#reusable-request-bodies]

Request bodies can be defined in `components` to be reused elsewhere.
The following request body definition:

```yaml
"components":
    "requestBodies":
        "PetBody":
            "description": "A JSON object containing pet information"
            "required": true
            "content":
                "application/json":
                    "schema":
                        "$ref": "#/components/schemas/Pet"
```

Can be reused as:

```js
/**
 * POST /pets
 * @summary Add a new pet
 * @bodyComponent {PetBody}
 */

/**
 * PUT /pets/{petId}
 * @summary Update a pet
 * @bodyComponent {PetBody}
 */
```

### Form data [#form-data]

The term "form data" is used for the media types `application/x-www-form-urlencoded` and `multipart/form-data`,
which are commonly used to submit HTML forms.

* `application/x-www-form-urlencoded` is used to send ASCII text data as key=value pairs.
  The payload format is similar to query parameters.
* `multipart/form-data` allows submitting binary data as well as multiple media types in a single message (for example, image, and JSON).
  Each form field has its own section in the payload with internal HTTP headers.
  `multipart` requests are commonly used for file uploads.

To illustrate form data, consider an HTML POST form:

```html
<form action="http://example.com/survey" method="post">
    <input type="text" name="name" />
    <input type="number" name="fav_number" />
    <input type="submit" />
</form>
```

This form POSTs data to the form’s endpoint:

```
POST /survey HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28

name=Amy+Smith&fav_number=42
```

Form data is defined in `components` and modeled using a `type: object` schema where the object properties represent the form fields:

```yaml
"components":
    "schemas":
        "Survey":
            "type": "object"
            "properties":
                "name": # <!--- form field name
                    "type": "string"
                "fav_number": # <!--- form field name
                    "type": "integer"
            "required":
                - "name"
                - "fav_number"
```

It can be used with:

```js
/**
 * POST /survey
 * @bodyContent {Survey} application/x-www-form-urlencoded
 * @bodyRequired
 */
```


# Describing Responses (/docs/packages/jsdoc-open-api/short/describing-responses)



## Describing Responses [#describing-responses]

An API specification needs to specify the `responses` for all API operations.
Each operation must have at least one response defined, usually a successful response.
A response is defined by its HTTP status code and the data returned in the response body and/or headers.
Here is a minimal example:

```js
/**
 * GET /ping
 * @response 200 - OK
 * @responseContent {string} 200.text/plain
 */
```

### Response media types [#response-media-types]

An API can respond with various media types.
JSON is the most common format for data exchange, but not the only one possible.
To specify the response media types, use `@responseContent`.

```js
/**
 * GET /users
 * @summary Get all users
 * @response 200 - A list of users
 * @responseContent {ArrayOfUsers} 200.application/json
 * @responseContent {ArrayOfUsers} 200.application/json
 * @responseContent {string} 200.text/plain
 */

// This operation returns image
/**
 * GET /logo
 * @summary Get the logo image
 * @response 200 - Logo image in PNG format
 * @responseContent {binary} 200.image/png
 */
```

### HTTP status codes [#http-status-codes]

Each response definition starts with a status code, such as 200 or 404.
An operation typically returns one successful status code and one or more error statuses.
To define a range of response codes, you may use the following range definitions: 1XX, 2XX, 3XX, 4XX, and 5XX.
If a response range is defined using an explicit code,
the explicit code definition takes precedence over the range definition for that code.
Each response status requires a description.
For example, you can describe the conditions for error responses.
Markdown ([CommonMark](https://commonmark.org/help/)) can be used for rich text representation.

```js
/**
 * @response 200 - OK
 * @response 400 - Bad request. User ID must be an integer and larger than 0.
 * @response 401 - Authorization information is missing or invalid.
 * @response 404 - A user with the specified ID was not found.
 * @response 5XX - Unexpected error.
 */
```

An API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance.
However, it’s expected to cover successful responses and any known errors.
By "known errors" we mean, for example, a 404 Not Found response for an operation that returns a resource by ID,
or a 400 Bad Request response in case of invalid operation parameters.

### Response body [#response-body]

A response body can define:

* An `object` or an `array` — typically used with JSON and XML APIs
* A primitive data type such as a `number` or `string` – used for plain text responses
* A file – (see below)

Objects can be defined in `components`:

```yaml
"components":
    "schemas":
        "User":
            "type": "object"
            "properties":
                "id":
                    "type": "integer"
                    "description": "The user ID."
                "username":
                    "type": "string"
                    "description": "The user name."
```

And be used with:

```js
/**
 * @response 200 - A User object
 * @responseContent {User} 200.application/json
 */
```

### Response that returns a file [#response-that-returns-a-file]

An API operation can return a file, such as an image or PDF.
If the response returns the file alone,
you would typically use the `binary` type and specify the appropriate media type for the response content:

```js
/**
 * GET /report
 * @summary Returns the report in the PDF format
 * @response 200 - A PDF file
 * @responseContent {binary} 200.application/pdf
 */
```

Files can also be embedded into, say, JSON or XML as a base64-encoded string.
In this case, you would use something like:

```js
/**
 * GET /users/me
 * @summary Returns user information
 * @response 200 - A JSON object containing user name and avatar
 * @responseContent {User} 200.application/json
 */
```

```yaml
"components":
    "schemas":
        "User":
            "type": "object"
            "properties":
                "username":
                    "type": "string"
                "avatar": # <-- image embedded into JSON
                    "type": "string"
                    "format": "byte"
                    "description": "Base64-encoded contents of the avatar image"
```

### Empty response body [#empty-response-body]

Responses, such as 204 No Content, have no body.
To indicate the response body is empty, do not specify `@responseContent`:

```js
/**
 * @response 204 - The resource was deleted successfully.
 */
```

### Response headers [#response-headers]

Responses from an API can include custom headers to provide additional information on the result of an API call.
For example, a rate-limited API may provide the rate limit status via response headers as follows:

```
HTTP 1/1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2016-10-12T11:00:00Z

{ ... }
```

You can define custom `headers` for each response as follows:

```js
/**
 * GET /ping
 * @summary Checks if the server is alive.
 * @response 200 - OK
 * @responseHeader {integer} 200.X-RateLimit-Limit - Request limit per hour.
 * @responseHeader {integer} 200.X-RateLimit-Remaining - The number of requests left for the time window.
 * @responseHeader {date-time} 200.X-RateLimit-Reset - The UTC date/time at which the current rate limit window resets.
 */
```

, currently,
OpenAPI Specification does not permit to define common response headers for different response codes or different API operations.
You need to define the headers for each response individually.

### Response examples [#response-examples]

Examples can be defined in `components`:

```yaml
"components":
    "examples":
        "Jessica":
            "value":
                "id": 10
                "name": "Jessica Smith"
        "Ron":
            "value":
                "id": 11
                "name": "Ron Stewart"
```

And be used as:

```js
/**
 * POST /users
 * @summary Adds a new user
 * @response 200 - OK
 * @responseContent {User} 200.application/json
 * @responseExample {Jessica} 200.application/json.Jessica
 * @responseExample {Ron} 200.application/json.Ron
 */
```

### Default response [#default-response]

Sometimes, an operation can return multiple errors with different HTTP status codes,
but all of them have the same response structure:

```js
/**
 * @response 200 - Success
 * @responseContent {User} 200.application/json
 * @response 400 - Bad request
 * @responseContent {Error} 400.application/json
 * @response 404 - Not found
 * @responseContent {Error} 404.application/json
 */
```

You can use the default response to describe these errors collectively, not individually.
"Default" means this response is used for all HTTP codes that are not covered individually for this operation.

```js
/**
 * @response 200 - Success
 * @responseContent {User} 200.application/json
 * @response default - Unexpected error
 * @responseContent {Error} default.application/json
 */
```

### Reusing responses [#reusing-responses]

Responses can be defined in `components` to be reused elsewhere.
The following response definition:

```yaml
"components":
    "responses":
        "NotFound":
            "description": "The specified resource was not found"
            "content":
                "application/json":
                    "schema":
                        "$ref": "#/components/schemas/Error"
        "Unauthorized":
            "description": "Unauthorized"
            "content":
                "application/json":
                    "schema":
                        "$ref": "#/components/schemas/Error"
    "schemas":
        # Schema for error response body
        "Error":
            "type": "object"
            "properties":
                "code":
                    "type": "string"
                "message":
                    "type": "string"
            "required":
                - "code"
                - "message"
```

Can be reused as:

```js
/**
 * GET /users
 * @summary Gets a list of users.
 * @response 200 - OK
 * @responseContent {ArrayOfUsers} 200.application/json
 * @responseComponent {Unauthorized} 401
 */

/**
 * GET /users/{id}
 * @summary Gets a user by ID.
 * @response 200 - OK
 * @responseContent {User} 200.application/json
 * @responseComponent {Unauthorized} 401
 * @responseComponent {NotFound} 404
 */
```


# Troubleshooting (/docs/packages/jsdoc-open-api/troubleshooting)



# Troubleshooting [#troubleshooting]

Common issues and solutions when working with jsdoc-open-api.

## CLI Not Found [#cli-not-found]

**Problem**: `jsdoc-open-api: command not found`

**Solutions**:

1. Use npx:

```bash
npx jsdoc-open-api generate src/
```

2. Install dependencies:

```bash
npm install commander cli-progress
```

3. Check optional dependencies installed:

```bash
npm list commander cli-progress
```

## No Paths Generated [#no-paths-generated]

**Problem**: Generated spec has empty `paths` object

**Causes**:

1. **JSDoc comments missing `@openapi` tag:**

```javascript
// ❌ Won't be parsed
/**
 * Get all users
 */
export function getUsers() {}

// ✅ Will be parsed
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 */
export function getUsers() {}
```

2. **Wrong file paths in sources:**

```javascript
// Check your glob patterns
{
    sources: [
        "./src/routes/**/*.js", // Correct path?
    ];
}
```

3. **Files not matching glob pattern:**

```bash
# Test your glob patterns
npx glob "./src/routes/**/*.js"
```

## Invalid OpenAPI Specification [#invalid-openapi-specification]

**Problem**: Generated spec fails validation

**Solution**: Validate required fields:

```javascript
{
  definition: {
    openapi: "3.0.0",  // Required
    info: {
      title: "My API",   // Required
      version: "1.0.0",  // Required
    },
  },
}
```

## Webpack Plugin Not Working [#webpack-plugin-not-working]

**Problem**: Plugin doesn't generate spec in webpack build

**Solutions**:

1. **Verify webpack dependency:**

```bash
npm install webpack
```

2. **Check plugin configuration:**

```javascript
const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
const path = require("path");

new SwaggerCompilerPlugin(
    path.join(__dirname, "public/swagger.json"), // Absolute path
    [path.join(__dirname, "src/**/*.js")], // Absolute paths
    {
        /* definition */
    },
    { verbose: true }, // Enable logging
);
```

3. **Server-side only in Next.js:**

```javascript
webpack: (config, { isServer }) => {
    if (!isServer) return config; // Skip on client

    config.plugins.push(new SwaggerCompilerPlugin(/* ... */));
    return config;
};
```

## TypeScript Errors [#typescript-errors]

**Problem**: TypeScript type errors with imports

**Solution**: Install type definitions:

```bash
npm install --save-dev @types/swagger-jsdoc openapi-types
```

## Duplicate Paths [#duplicate-paths]

**Problem**: Same path defined multiple times causes conflicts

**Solution**: Consolidate path definitions:

```javascript
// ❌ Don't do this
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get users
 */

/**
 * @openapi
 * /users:
 *   post:
 *     summary: Create user
 */

// ✅ Do this
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get users
 *   post:
 *     summary: Create user
 */
```

## Schema References Not Working [#schema-references-not-working]

**Problem**: `$ref` references not resolving

**Cause**: Schema not defined in components

**Solution**: Define schemas first:

```javascript
/**
 * @openapi
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 */

/**
 * @openapi
 * /users:
 *   get:
 *     responses:
 *       200:
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */
```

## Performance Issues [#performance-issues]

**Problem**: Generation is slow

**Solutions**:

1. **Limit source files:**

```javascript
{
    sources: [
        "./src/routes/**/*.js",
        "!./src/**/*.test.js", // Exclude tests
        "!./node_modules/**", // Exclude node_modules
    ];
}
```

2. **Use specific paths:**

```javascript
// ❌ Slow
sources: ["./src/**/*.js"];

// ✅ Faster
sources: ["./src/routes/**/*.js", "./src/controllers/**/*.js"];
```

3. **Cache results:**

```javascript
let cachedSpec = null;

async function getSpec() {
    if (!cachedSpec) {
        cachedSpec = await jsdocOpenApi({
            /* options */
        });
    }
    return cachedSpec;
}
```

## YAML Syntax Errors [#yaml-syntax-errors]

**Problem**: YAML syntax errors in JSDoc comments

**Common mistakes:**

```javascript
// ❌ Wrong indentation
/**
 * @openapi
 * /users:
 * get:
 *   summary: Get users
 */

// ✅ Correct indentation (2 spaces)
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get users
 */

// ❌ Missing colon
/**
 * @openapi
 * /users
 *   get:
 *     summary: Get users
 */

// ✅ Colon after path
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get users
 */
```

## Debugging [#debugging]

Enable verbose logging:

```bash
# CLI
npx jsdoc-open-api generate -v src/

# Very verbose (debugging)
npx jsdoc-open-api generate -d src/
```

Programmatic:

```javascript
const spec = await jsdocOpenApi({
    definition: {
        /* ... */
    },
    sources: ["./src/**/*.js"],
    verbose: true, // Enable logging
});
```

## Validation [#validation]

Validate your generated spec:

```bash
# Using Swagger CLI
npm install -g @apidevtools/swagger-cli
swagger-cli validate swagger.json

# Using online validator
# Upload to https://editor.swagger.io/
```


# Channels (/docs/packages/notification/channels)



# Channels [#channels]

`@visulima/notification` ships six channels. Each has a typed payload.

## SMS [#sms]

```typescript
{ to: "+15555550100" | ["+1…", "+1…"], text: "…", from?: "…", mediaUrls?: ["https://…"] }
```

Providers: `twilio`, `vonage`, `plivo`, `messagebird`, `telnyx`.

## Push [#push]

```typescript
{ to: "token" | ["t1", "t2"], title?: "…", body: "…", data?: {}, imageUrl?: "…", badge?: 1, sound?: "default" }
```

Providers: `fcm`, `expo`.

## Chat [#chat]

```typescript
{ text: "…", to?: "channel-id", blocks?: <provider-specific>, threadId?: "…" }
```

Providers: `slack`, `discord`, `msteams`, `telegram`.

## In-app [#in-app]

```typescript
{ to: "subscriber-id", title?: "…", body: "…", data?: {}, actions?: [{ label: "Open", url: "…" }] }
```

Provider: `inAppProvider` from `@visulima/notification/channels/inapp`. See [Providers](/docs/packages/notification/providers).

## Webhook [#webhook]

```typescript
{ body: <json>, url?: "https://…", method?: "POST", headers?: {} }
```

Provider: `webhook`.

## Email [#email]

```typescript
{ from?: "…", to: "…", subject: "…", html?: "…", text?: "…", cc?, bcc?, replyTo?, attachments? }
```

The email channel delegates to a `@visulima/email` `Mail` instance via `emailChannel(mail)`. See
[Providers](/docs/packages/notification/providers#email).


# Digest (/docs/packages/notification/digest)



# Digest [#digest]

`@visulima/notification/digest` collapses a burst of events into **one** notification — the antidote to notification
fatigue ("50 people liked your post" instead of 50 pushes). Events are grouped by a key into a time (or cron) window;
when the window closes, every collected event is flushed together.

It is store-backed and edge-safe; [`croner`](https://github.com/hexagon/croner) is an optional peer used for cron
windows:

```sh
npm install @visulima/notification croner
```

## Usage [#usage]

```typescript
import { createDigester } from "@visulima/notification/digest";

const digester = createDigester<{ subscriberId: string; postId: string }>({
    // Group events into one window per subscriber + post.
    key: (event) => `${event.subscriberId}:${event.postId}`,
    // Collect for 10 minutes from the first event.
    window: { amount: 10, unit: "minutes" },
    // Called once when the window closes, with every event.
    onFlush: (events, key) => runtime.trigger(summaryWorkflow, { count: events.length, events }),
});

// On each incoming event:
await digester.add({ subscriberId: "u1", postId: "p1" }); // opens a window
await digester.add({ subscriberId: "u1", postId: "p1" }); // folds into the open window

// Flush closed windows on a timer (cron job, Cloudflare alarm, alongside runtime.sweep):
await digester.sweep();
```

`add` returns a boolean — `true` when it opened a new window for the key. `sweep(now?, limit?)` flushes every window
whose wake-at has passed (capped at `limit`, the rest carry to the next sweep) and returns how many it flushed; it
rejects a non-positive `limit`.

Flushing is **at-least-once**: a window is removed only after its `onFlush` resolves, so a throwing `onFlush` is retried
on the next sweep (and may run again if the subsequent removal fails) — make `onFlush` idempotent.

## Windows [#windows]

`window` is a [`Duration`](/docs/packages/workflow/steps): a number of milliseconds, a structured `{ amount, unit }`, or
a `{ cron }` expression. Pass a function `(event) => Duration` to vary the window per event. A window's close time is
fixed by its **first** event and later events do not extend it — including for cron: a `{ cron: "0 9 * * *" }` window
closes at the next 9am **after the first event of each burst**, not on an absolute daily schedule. Non-finite windows
(`NaN`/`Infinity`) and an impossible cron are rejected at `add` time.

## Stores [#stores]

`createDigester` defaults to an in-process store. For durability across restarts/instances pass an
`UnstorageDigestStore` (any [unstorage](https://unstorage.unjs.io) driver — Cloudflare KV/D1, Redis, filesystem):

```typescript
import { createDigester, UnstorageDigestStore } from "@visulima/notification/digest";
import { createStorage } from "unstorage";

const digester = createDigester({
    key: (event) => event.subscriberId,
    window: { amount: 1, unit: "hours" },
    onFlush: (events) => sendSummary(events),
    store: new UnstorageDigestStore(createStorage()),
});
```

Each window is a self-contained document (no shared index), so concurrent `add`s for different keys can't lose-update
each other; writes are still not transactional, so for high-contention
multi-writer setups prefer a store with atomic guarantees.

## Digest vs. workflow `step.digest` [#digest-vs-workflow-stepdigest]

This digester aggregates **before** triggering — it batches raw events and fires one workflow/notification per window.
That keeps the model simple and the engine store-agnostic. Combine it with [workflows](/docs/packages/notification/workflow)
by having `onFlush` trigger a notification workflow with the batched events.


# Events (/docs/packages/notification/events)



# Events [#events]

Subscribe to lifecycle events and build a per-message timeline.

```typescript
import { NotificationEventBus, MemoryEventStore } from "@visulima/notification/events";

const bus = new NotificationEventBus();
const store = new MemoryEventStore();

bus.on("sent", (event) => console.log("sent", event.messageId));
bus.on("failed", (event) => console.error("failed", event.messageId));
bus.on("*", (event) => store.append(event)); // wildcard: every event

bus.emit({ type: "sent", messageId: "m1", channel: "sms", provider: "twilio", timestamp: new Date() });

await store.timeline("m1"); // ordered events for message m1
```

## Event types [#event-types]

`queued`, `sent`, `delivered`, `failed`, `bounced`, `read`, `clicked`, `interacted`.

Provider webhooks can be normalised into these events via a provider's optional `parseEventBody(body, headers)` method,
then fed to the bus and store.

## Custom store [#custom-store]

Implement `EventStore` (`append` / `timeline`) to persist events in your database.


# Introduction (/docs/packages/notification/getting-started/introduction)



# Getting Started [#getting-started]

## Concepts [#concepts]

* **Channel** — a logical delivery medium: `sms`, `push`, `chat`, `inapp`, `webhook`, `email`.
* **Provider** — a concrete integration for a channel (e.g. `twilio` for `sms`). A provider declares its `id`, `channel`,
  capability `features`, and a `send` method.
* **Facade** — `createNotification({ <channel>: <provider> })` returns a `Notification` that dispatches messages to the
  matching provider per channel.
* **Message** — an object with a payload per channel: `{ sms: {...}, chat: {...} }`.
* **Receipt** — the discriminated result of a send: `{ successful: true, messageId, … }` or
  `{ successful: false, errorMessages, … }`.

## Creating a facade [#creating-a-facade]

```typescript
import { createNotification } from "@visulima/notification";
import { twilioProvider } from "@visulima/notification/providers/twilio";

const notify = createNotification({
    sms: twilioProvider({ accountSid: "AC…", authToken: "…", from: "+15555550100" }),
});
```

## The provider contract [#the-provider-contract]

Every provider is built with `defineProvider`:

```typescript
import { defineProvider } from "@visulima/notification";
import type { SmsPayload } from "@visulima/notification";

export const myProvider = defineProvider<{ apiKey: string }, SmsPayload>((config) => ({
    id: "my-provider",
    channel: "sms",
    features: { batchSending: false, media: false },
    initialize: () => {},
    isAvailable: () => Boolean(config?.apiKey),
    send: async (payload) => ({
        success: true,
        data: { channel: "sms", messageId: "…", provider: "my-provider", sent: true, timestamp: new Date() },
    }),
}));
```

## Next steps [#next-steps]

* [Sending notifications](/docs/packages/notification/getting-started/sending)


# Sending (/docs/packages/notification/getting-started/sending)



# Sending notifications [#sending-notifications]

## Multi-channel send [#multi-channel-send]

Each channel present in the message is delivered in parallel; you receive one receipt per channel.

```typescript
const receipts = await notify.send({
    sms: { to: "+15555550100", text: "Your code is 123" },
    chat: { text: "🚀 Deploy finished" },
    push: { to: ["device-token"], title: "Deploy", body: "Finished" },
});

for (const receipt of receipts) {
    if (receipt.successful) {
        console.log(`${receipt.channel}: ${receipt.messageId}`);
    } else {
        console.error(`${receipt.channel} failed:`, receipt.errorMessages);
    }
}
```

## Single channel [#single-channel]

```typescript
const receipt = await notify.sendToChannel("sms", { to: "+15555550100", text: "Hi" });
```

## Batch with bounded concurrency [#batch-with-bounded-concurrency]

```typescript
const messages = users.map((user) => ({ sms: { to: user.phone, text: `Hi ${user.name}` } }));

for await (const receipts of notify.sendMany(messages, { concurrency: 10 })) {
    // receipts for one message
}
```

## Fluent message builder [#fluent-message-builder]

`createNotificationMessage()` (or `new NotificationMessageBuilder()`) is a thin, chainable convenience for assembling a
multi-channel message — `.build()` returns the same plain object `send()` accepts.

```typescript
import { createNotificationMessage } from "@visulima/notification";

const message = createNotificationMessage()
    .sms({ to: "+15555550100", text: "Your code is 123" })
    .push({ to: ["device-token"], title: "Code", body: "123" })
    .idempotencyKey("login-otp-42")
    .build();

await notify.send(message);
```

## Lifecycle [#lifecycle]

`initialize()` is called lazily and once per provider before its first send. Call `notify.initialize()` to eagerly
initialise all providers, and `notify.shutdown()` to release provider resources.


# i18n (/docs/packages/notification/i18n)



# i18n [#i18n]

`@visulima/notification/i18n` localizes message content with
[ICU MessageFormat](https://formatjs.io/docs/core-concepts/icu-syntax/) (plurals, select, number/date) and
region → language → fallback resolution driven by the subscriber's locale. It is edge-safe and dependency-light.

It requires the `intl-messageformat` peer:

```sh
npm install @visulima/notification intl-messageformat
```

## Usage [#usage]

```typescript
import { createTranslator } from "@visulima/notification/i18n";

const t = createTranslator({
    fallbackLocale: "en",
    messages: {
        en: { likes: "{count, plural, one {# like} other {# likes}}", greeting: "Hi {name}" },
        de_DE: { likes: "{count, plural, one {# Like} other {# Likes}}", greeting: "Hallo {name}" },
    },
});

t.translate("de_DE", "likes", { count: 3 }); // "3 Likes"
t.translate("en", "greeting", { name: "Ada" }); // "Hi Ada"
t.translate("fr", "likes", { count: 1 }); // no fr table → falls back to en → "1 like"
```

## Locale resolution [#locale-resolution]

`translate(locale, key, values?)` resolves in order: the exact `locale`, its **language** subtag (`de-DE`/`de_DE` → `de`),
then the `fallbackLocale` (and its language). Table keys may use `-` or `_`; the locale passed to `Intl` is normalized to
BCP-47 internally. A missing key returns the key itself, or the result of an `onMissing(locale, key)` handler.

## In templates [#in-templates]

Drive `translate` from the subscriber's locale and feed the result into a [layout](/docs/packages/notification/layouts)
or channel payload. For a `{{t}}` helper, register `translate` with your template engine — e.g. a Handlebars helper:

```typescript
import Handlebars from "handlebars";

Handlebars.registerHelper("t", (key: string, options) => t.translate(options.data.root.locale, key, options.hash));
// template: "{{t 'greeting' name=user.name}}"
```

`has(locale, key)` reports whether a key resolves, and a bad ICU template / missing value throws an actionable
`NotificationError` so failures surface clearly rather than rendering a broken string.


# Introduction (/docs/packages/notification)



# Notification [#notification]

**Reusable, ESM-only, edge-ready multi-channel notifications**

`@visulima/notification` is the multi-channel sibling of [`@visulima/email`](/docs/packages/email). One typed facade
drives many channel providers — SMS, push, chat, in-app and webhook — while the email channel delegates straight to
`@visulima/email`, reusing its 29 providers, templates and deliverability tooling.

## Why @visulima/notification? [#why-visulimanotification]

* **Infra-free** - No Redis, Mongo, dashboard or SaaS account. `npm install` and send.
* **Edge-ready** - Every native provider is built on `fetch` with zero Node built-ins, so it runs unmodified on
  Cloudflare Workers, Vercel Edge, Deno and Bun.
* **Tree-shakeable** - Providers are imported from their own subpaths (`@visulima/notification/providers/<name>`); you
  only ship what you use.
* **Type-safe** - Per-channel payloads are typed end to end.
* **Multi-channel routing** - Channel-sequence fallback (`best-of`), broadcast (`all`), per-channel provider failover and
  round-robin.
* **Batteries included** - Middleware (retry, rate-limit, circuit-breaker, dedupe, logging), an event bus, a durable
  queue with a retrying worker, an in-app inbox store and subscriber preferences.

## How it positions [#how-it-positions]

The notification ecosystem splits into SaaS platforms (Knock, Courier — not self-hostable) and one heavy OSS platform
(Novu — needs a 6-service cluster). `@visulima/notification` fills the gap between them: a maintained, typed, edge-ready,
infra-free **send primitive**. It deliberately does not ship a hosted dashboard or visual workflow builder.

## Quick example [#quick-example]

```typescript
import { createNotification } from "@visulima/notification";
import { twilioProvider } from "@visulima/notification/providers/twilio";
import { slackProvider } from "@visulima/notification/providers/slack";

const notify = createNotification({
    sms: twilioProvider({ accountSid: "AC…", authToken: "…", from: "+15555550100" }),
    chat: slackProvider({ token: "xoxb-…", defaultChannel: "C123" }),
});

const receipts = await notify.send({
    sms: { to: "+15555550100", text: "Your code is 123" },
    chat: { text: "🚀 Deploy finished" },
});
```

## Next steps [#next-steps]

* [Installation](/docs/packages/notification/installation)
* [Getting Started](/docs/packages/notification/getting-started/introduction)
* [Channels](/docs/packages/notification/channels)
* [Providers](/docs/packages/notification/providers)


# Installation (/docs/packages/notification/installation)



# Installation [#installation]

`@visulima/notification` is available on npm.

```bash
npm install @visulima/notification
```

```bash
yarn add @visulima/notification
```

```bash
pnpm add @visulima/notification
```

## Requirements [#requirements]

* **Node.js**: 22.14+ or 24.10+ (for Node-only providers/runtimes). The core and native providers also run on edge
  runtimes (Cloudflare Workers, Vercel Edge), Deno and Bun.
* **TypeScript**: Optional but recommended for full type safety.

## Runtime support [#runtime-support]

Most providers use only `fetch` + Web Crypto (`globalThis.crypto.subtle`), so they run on **every** runtime including
**Cloudflare Workers**, Vercel Edge, Deno and Bun. Providers that need OAuth2 tokens (FCM push, Outlook365 via the email
channel) take a `getAccessToken` callback, so you supply the token without bundling a Node-only auth SDK. Even AWS SNS
and web-push are edge-safe — their SigV4 / VAPID signing is implemented with Web Crypto, not `node:crypto`.

A small number of providers/adapters are **Node-only** because the underlying protocol or SDK requires Node built-ins:
**APNs** (`node:http2` — APNs mandates HTTP/2) and the **BullMQ / pg-boss / SQS** queue adapters (Redis / Postgres / AWS
SDK). Import these only from a Node runtime; the rest of the package stays edge-deployable.

### Providers [#providers]

| Provider(s)                                               | Node | Deno | Bun | Cloudflare Workers / Edge |
| --------------------------------------------------------- | ---- | ---- | --- | ------------------------- |
| **SMS** twilio, vonage, plivo, messagebird, telnyx        | ✅    | ✅    | ✅   | ✅                         |
| **SMS** sns (Web Crypto SigV4)                            | ✅    | ✅    | ✅   | ✅                         |
| **Push** fcm, expo, web-push (Web Crypto VAPID)           | ✅    | ✅    | ✅   | ✅                         |
| **Push** apns                                             | ✅    | ❌    | ❌   | ❌ (needs `node:http2`)    |
| **Chat** slack, discord, msteams, telegram                | ✅    | ✅    | ✅   | ✅                         |
| webhook, inapp, mock, failover, roundrobin, opentelemetry | ✅    | ✅    | ✅   | ✅                         |
| email (via `@visulima/email`)                             | ✅    | ✅\*  | ✅\* | ✅\*                       |

\* The email channel's runtime support depends on the wrapped `@visulima/email` provider (e.g. SMTP is Node-only; Resend/SendGrid/etc. are edge-safe).

### Infrastructure modules [#infrastructure-modules]

| Module                                                                             | Node | Cloudflare Workers / Edge  |
| ---------------------------------------------------------------------------------- | ---- | -------------------------- |
| middleware (retry/rate-limit/circuit-breaker/dedupe/logging/suppression/telemetry) | ✅    | ✅                          |
| routing, preferences, events                                                       | ✅    | ✅                          |
| webhooks (signature verifiers — Web Crypto)                                        | ✅    | ✅                          |
| template engines (string/handlebars/liquid)                                        | ✅    | ✅                          |
| queue: memory, unstorage (KV)                                                      | ✅    | ✅                          |
| queue: bullmq, pg-boss, sqs                                                        | ✅    | ❌ (Redis/Postgres/AWS SDK) |

## Optional peer dependencies [#optional-peer-dependencies]

**Every provider is `fetch`-based — no per-provider SDK to install.** Optional peers are only needed by specific
**subpaths**; import the subpath → install the peer. Nothing is pulled in otherwise (all are declared `optional&#x60;), and if
a peer is missing you get an actionable error (e.g. &#x2A;"liquidjs is not installed. Please install it: pnpm add liquidjs"*).

| Subpath you import                                                           | Install               |
| ---------------------------------------------------------------------------- | --------------------- |
| `@visulima/notification/channels/email`                                      | `@visulima/email`     |
| `@visulima/notification/template/handlebars`                                 | `handlebars`          |
| `@visulima/notification/template/liquid`                                     | `liquidjs`            |
| `@visulima/notification/queue/unstorage`, `channels/inapp` (unstorage store) | `unstorage`           |
| `@visulima/notification/queue/bullmq&#x60; &#x2A;(Node-only)*                | `bullmq`              |
| `@visulima/notification/queue/pg-boss&#x60; &#x2A;(Node-only)*               | `pg-boss`             |
| `@visulima/notification/queue/sqs&#x60; &#x2A;(Node-only)*                   | `@aws-sdk/client-sqs` |
| `@visulima/notification/providers/opentelemetry`, `middleware` (telemetry)   | `@opentelemetry/api`  |
| `@visulima/notification/workflow`                                            | `@visulima/workflow`  |
| `@visulima/notification/digest` (cron windows only)                          | `croner`              |
| `@visulima/notification/i18n`                                                | `intl-messageformat`  |

The plain `./template/string` renderer, `MemoryQueue`, and time-based `./digest` windows need **no** peer.

## Next steps [#next-steps]

* [Getting Started](/docs/packages/notification/getting-started/introduction)


# Layouts (/docs/packages/notification/layouts)



# Layouts [#layouts]

`@visulima/notification/layouts` is the shared chrome — header, footer, brand, unsubscribe link — that every
notification body drops into. A layout is a template with a `{{content}}` slot; you render the per-notification body,
then wrap it. It reuses the package's [template engines](/docs/packages/notification/templates), so the default is
zero-dependency and edge-safe.

## Usage [#usage]

```typescript
import { defineLayout } from "@visulima/notification/layouts";

const branded = defineLayout({
    template: `
        <table class="wrapper">
            <tr><td><img src="https://app/logo.png" /></td></tr>
            <tr><td>{{content}}</td></tr>
            <tr><td class="footer">© ACME · <a href="{{unsubscribeUrl}}">unsubscribe</a></td></tr>
        </table>`,
});

const html = await branded.render("<p>Thanks for joining!</p>", { unsubscribeUrl: "https://app/u/123" });

await notify.sendToChannel("email", { from: "noreply@app.com", to: "user@x.com", subject: "Welcome", html });
```

`render(content, variables?)` injects `content` into the slot and renders the layout with `variables` — layout variables
(`unsubscribeUrl`, brand tokens, …) work for free.

## Slot & escaping [#slot--escaping]

The default renderer (`renderString`) inserts the slot value verbatim, so `{{content}}` is right for already-rendered
HTML. If you pass the **Handlebars** renderer, use the unescaped triple-stache `{{{content}}}` so the body is not
double-escaped:

```typescript
import { renderHandlebars } from "@visulima/notification/template/handlebars";

const layout = defineLayout({ render: renderHandlebars, template: "<main>{{{content}}}</main>" });
```

Use `slot` to rename the placeholder (e.g. `slot: "body"` → `{{body}}`).

## With workflows [#with-workflows]

Compose layouts inside a [workflow](/docs/packages/notification/workflow) email step — render the body, wrap it, send:

```typescript
await step.email("welcome", async () => ({
    from: "noreply@app.com",
    to: payload.email,
    subject: "Welcome",
    html: await branded.render("<p>Welcome!</p>", { unsubscribeUrl: payload.unsubscribeUrl }),
}));
```


# Middleware (/docs/packages/notification/middleware)



# Middleware [#middleware]

Middleware wraps every send. The first registered middleware is the outermost wrapper (runs first on the way in, last on
the way out).

```typescript
import { retryMiddleware, rateLimitMiddleware, circuitBreakerMiddleware, dedupeMiddleware, loggingMiddleware } from "@visulima/notification/middleware";

notify
    .use(loggingMiddleware())
    .use(retryMiddleware({ retries: 3, baseDelay: 250 }))
    .use(rateLimitMiddleware({ rate: 100, interval: 1000 }))
    .use(circuitBreakerMiddleware({ threshold: 5, resetTimeout: 30_000 }))
    .use(dedupeMiddleware({ ttl: 60_000 }));
```

## Built-ins [#built-ins]

| Middleware                 | Purpose                                                                   |
| -------------------------- | ------------------------------------------------------------------------- |
| `retryMiddleware`          | Retry failed sends with exponential backoff + jitter. `shouldRetry` hook. |
| `rateLimitMiddleware`      | Token-bucket throttle (`rate` per `interval`).                            |
| `circuitBreakerMiddleware` | Open the circuit after N consecutive failures; trial after cool-off.      |
| `dedupeMiddleware`         | Suppress duplicate sends within a TTL, keyed by `idempotencyKey`.         |
| `loggingMiddleware`        | Log each attempt and outcome.                                             |
| `suppressionMiddleware`    | Short-circuit sends to suppressed recipients (unsubscribe / bounce list). |
| `telemetryMiddleware`      | Emit an OpenTelemetry span + counter/histogram per send (optional peer).  |

```typescript
import { suppressionMiddleware, telemetryMiddleware } from "@visulima/notification/middleware";

notify.use(suppressionMiddleware({ isSuppressed: (recipient, channel) => suppressionList.has(recipient) })).use(telemetryMiddleware({ tracer })); // edge-safe; no-op without a tracer/meter
```

## Writing middleware [#writing-middleware]

```typescript
import type { Middleware } from "@visulima/notification";

const stamp: Middleware = async (context, next) => {
    context.payload.metadata = { ...context.payload.metadata, sentAt: Date.now() };

    return next(context);
};

notify.use(stamp);
```

The `context` carries `{ channel, provider, payload }`. Return the `Result` from `next(context)` (or short-circuit with
your own).


# Preferences (/docs/packages/notification/preferences)



# Preferences [#preferences]

Honour per-subscriber, per-channel opt-outs. Critical notifications bypass them.

```typescript
import { MemoryPreferenceStore, preferencesGate } from "@visulima/notification/preferences";
import { route } from "@visulima/notification/routing";

const prefs = new MemoryPreferenceStore();
prefs.set("user-1", { channels: { sms: false, push: true } });

// Channels default to allowed; only explicit `false` opts out.
prefs.isAllowed("user-1", "sms"); // false
prefs.isAllowed("user-1", "email"); // true (not set)
prefs.isAllowed("user-1", "sms", { critical: true }); // true (bypass)
```

## Using the gate [#using-the-gate]

`preferencesGate` turns a store into a `route(...)` gate. By default it resolves the subscriber id from each payload's
`to` field.

```typescript
await route(notify, message, { gate: preferencesGate(prefs) });

// Critical: ignore opt-outs (security alerts, etc.)
await route(notify, message, { gate: preferencesGate(prefs, { critical: true }) });

// Custom subscriber resolution
await route(notify, message, { gate: preferencesGate(prefs, { subscriberId: (p) => p.metadata?.userId }) });
```

## Custom store [#custom-store]

Implement `PreferenceStore` to back preferences with your database:

```typescript
import type { PreferenceStore } from "@visulima/notification/preferences";

const store: PreferenceStore = {
    get: async (id) => db.getPrefs(id),
    set: async (id, prefs) => db.savePrefs(id, prefs),
    isAllowed: async (id, channel, { critical } = {}) => critical || (await db.getPrefs(id)).channels[channel] !== false,
};
```


# Providers (/docs/packages/notification/providers)



# Providers [#providers]

Import providers from their own subpath so unused ones are tree-shaken.

## SMS [#sms]

```typescript
import { twilioProvider } from "@visulima/notification/providers/twilio";
import { vonageProvider } from "@visulima/notification/providers/vonage";
import { plivoProvider } from "@visulima/notification/providers/plivo";
import { messageBirdProvider } from "@visulima/notification/providers/messagebird";
import { telnyxProvider } from "@visulima/notification/providers/telnyx";

twilioProvider({ accountSid: "AC…", authToken: "…", from: "+1…" });
vonageProvider({ apiKey: "…", apiSecret: "…", from: "App" });
plivoProvider({ authId: "…", authToken: "…", from: "+1…" });
messageBirdProvider({ accessKey: "…", from: "App" });
telnyxProvider({ apiKey: "…", from: "+1…" });

// AWS SNS — edge-safe (Web Crypto SigV4, no node:crypto)
import { snsProvider } from "@visulima/notification/providers/sns";

snsProvider({ accessKeyId: "AKIA…", secretAccessKey: "…", region: "us-east-1" });
```

## Push [#push]

```typescript
import { fcmProvider } from "@visulima/notification/providers/fcm";
import { expoProvider } from "@visulima/notification/providers/expo";
import { webPushProvider } from "@visulima/notification/providers/web-push";
import { apnsProvider } from "@visulima/notification/providers/apns";

// Bring your own OAuth token provider (keeps the provider edge-safe).
fcmProvider({ projectId: "my-app", getAccessToken: async () => getGoogleAccessToken() });
expoProvider({ accessToken: "…" }); // accessToken optional

// web-push — edge-safe (Web Crypto VAPID + RFC 8291 aes128gcm). `to` is the PushSubscription.
webPushProvider({ vapidPublicKey: "…", vapidPrivateKey: "…", vapidSubject: "mailto:you@app.com" });

// APNs — NODE-ONLY (needs node:http2). Not Cloudflare-safe.
apnsProvider({ teamId: "…", keyId: "…", signingKey: "-----BEGIN PRIVATE KEY-----…", bundleId: "com.app", production: true });
```

## Chat [#chat]

```typescript
import { slackProvider } from "@visulima/notification/providers/slack";
import { discordProvider } from "@visulima/notification/providers/discord";
import { msTeamsProvider } from "@visulima/notification/providers/msteams";
import { telegramProvider } from "@visulima/notification/providers/telegram";

slackProvider({ token: "xoxb-…", defaultChannel: "C123" }); // or { webhookUrl }
discordProvider({ webhookUrl: "https://discord.com/api/webhooks/…" });
msTeamsProvider({ webhookUrl: "https://outlook.office.com/webhook/…" });
telegramProvider({ botToken: "123:ABC", defaultChatId: 123456 });
```

## In-app [#in-app]

```typescript
import { inAppProvider, MemoryInAppStore } from "@visulima/notification/channels/inapp";

const inapp = inAppProvider({ store: new MemoryInAppStore() });
const store = inapp.getInstance();

await store.list("user-1", { unreadOnly: true });
await store.unreadCount("user-1");
await store.markRead("notification-id");
await store.markAllRead("user-1");
```

## Webhook [#webhook]

```typescript
import { webhookProvider } from "@visulima/notification/providers/webhook";

webhookProvider({ url: "https://example.com/hook", headers: { Authorization: "Bearer …" } });
```

## Email [#email]

```typescript
import { createMail } from "@visulima/email";
import { resendProvider } from "@visulima/email/providers/resend";
import { emailChannel } from "@visulima/notification/channels/email";

const mail = createMail(resendProvider({ apiKey: "re_…" }));
const email = emailChannel(mail);
```

## Mock (testing) [#mock-testing]

```typescript
import { mockProvider } from "@visulima/notification/providers/mock";

const provider = mockProvider({ channel: "sms" });
// provider.getInstance().sent — recorded payloads
// mockProvider({ failWith: "boom" }) — deterministic failures
```

## OpenTelemetry wrapper [#opentelemetry-wrapper]

Wrap any provider to emit a span per send (edge-safe; `@opentelemetry/api` is an optional peer):

```typescript
import { otelProvider } from "@visulima/notification/providers/opentelemetry";
import { trace } from "@opentelemetry/api";

const sms = otelProvider(twilioProvider({ … }), { tracer: trace.getTracer("notification") });
```

See also the [`telemetryMiddleware`](/docs/packages/notification/middleware) for facade-level spans + metrics.


# Queue (/docs/packages/notification/queue)



# Queue & worker [#queue--worker]

Decouple enqueue from delivery. The default queue is in-process; back it with unstorage for durability.

```typescript
import { MemoryQueue, createQueueWorker } from "@visulima/notification/queue";

const queue = new MemoryQueue();

queue.enqueue({ sms: { to: "+15555550100", text: "Hi" } });
queue.enqueue({ chat: { text: "Hello" } }, { scheduledAt: Date.now() + 60_000 }); // delayed

const worker = createQueueWorker(queue, notify, {
    maxAttempts: 5,
    backoff: (attempt) => Math.min(30_000, 1000 * 2 ** (attempt - 1)),
    onDrop: (job, receipts) => console.error("dropped", job.id, receipts),
});

worker.start(); // poll continuously
// or
await worker.drain(); // process all currently-due jobs once, then resolve
```

A job is retried (with backoff) when any channel fails, and dropped after `maxAttempts`.

## Durable queue (unstorage) [#durable-queue-unstorage]

```typescript
import { UnstorageQueue } from "@visulima/notification/queue/unstorage";
import { createStorage } from "unstorage";
import redisDriver from "unstorage/drivers/redis";

const queue = new UnstorageQueue(createStorage({ driver: redisDriver({ base: "notify" }) }));
```

`UnstorageQueue` implements the same `NotificationQueue` interface, so the worker is identical. Any unstorage driver
(Redis, filesystem, Cloudflare KV, …) works.

## Durable adapters (Node-only) [#durable-adapters-node-only]

Ready-made adapters for the common backends. These need Node built-ins / SDKs, so they are **not** Cloudflare-safe (use
`MemoryQueue` or `UnstorageQueue` on the edge).

```typescript
import { createBullMqQueue } from "@visulima/notification/queue/bullmq"; // Redis (optional peer: bullmq)
import { createPgBossQueue } from "@visulima/notification/queue/pg-boss"; // Postgres (optional peer: pg-boss)
import { createSqsQueue } from "@visulima/notification/queue/sqs"; // AWS SQS (optional peer: @aws-sdk/client-sqs)

const queue = createBullMqQueue(bullQueue); // pass a configured client instance
```

Each implements the same `NotificationQueue` interface, so the worker is identical.

## Custom queue [#custom-queue]

Implement `NotificationQueue` (`enqueue` / `reserve` / `ack` / `retry` / `size`) to integrate any other store.


# Routing (/docs/packages/notification/routing)



# Routing [#routing]

There are two independent axes of routing.

## Provider-within-channel [#provider-within-channel]

Wrap several same-channel providers:

```typescript
import { failoverProvider } from "@visulima/notification/providers/failover";
import { roundRobinProvider } from "@visulima/notification/providers/roundrobin";

const sms = failoverProvider([twilioProvider({ … }), vonageProvider({ … })]); // try in order
const balanced = roundRobinProvider([plivoProvider({ … }), telnyxProvider({ … })]); // rotate (falls over by default)

const notify = createNotification({ sms });
```

## Channel-sequence routing [#channel-sequence-routing]

`route(...)` delivers across channels with a priority order and an optional gate.

```typescript
import { route } from "@visulima/notification/routing";

// best-of (default): try sms, then push, then email — stop at the first success
await route(notify, message, { order: ["sms", "push", "email"], mode: "best-of" });

// all: broadcast to every present channel in parallel
await route(notify, message, { mode: "all" });
```

### Gating [#gating]

A gate runs before each channel and skips it when it returns false. Use it for preferences, capability checks or
send-windows.

```typescript
await route(notify, message, {
    gate: (channel, payload) => channel !== "sms" || isWithinQuietHours() === false,
});
```

See [Preferences](/docs/packages/notification/preferences) for a ready-made preference gate.


# Templates (/docs/packages/notification/templates)



# Templates [#templates]

Render chat/push/SMS bodies from templates. Each engine lives on its own subpath so you only pull in the one you use.
All are edge-safe (pure JS — they run on Cloudflare Workers).

> **You don't need a template framework.** Templating is engine-agnostic: the extension point is a single function type,
> `TemplateRenderer`, not a framework. Use the zero-dep `renderString`, plug in Handlebars/Liquid, or wrap **any** engine
> in a \~5-line adapter (see [Custom renderer](#custom-renderer-any-engine)). The package never bundles a framework — keep
> the default for the edge, opt into a heavier engine only where you need its logic.

## Zero-dependency string renderer [#zero-dependency-string-renderer]

```typescript
import { renderString } from "@visulima/notification/template/string";

renderString("Hi {{ user.name }}, your code is {{ code }}", { code: "123", user: { name: "Ada" } });
// "Hi Ada, your code is 123"
```

Supports flat and nested `{{ a.b.c }}` placeholders; missing values render as empty strings.

## Handlebars / Liquid [#handlebars--liquid]

`handlebars` and `liquidjs` are **optional peers** — install the one you need.

```typescript
import { renderHandlebars } from "@visulima/notification/template/handlebars";
import { renderLiquid } from "@visulima/notification/template/liquid";

await renderHandlebars("<h1>Hello {{name}}!</h1>", { name: "John" });
await renderLiquid("Hello {{ name }}!", { name: "John" });
```

## The `TemplateRenderer` contract [#the-templaterenderer-contract]

Every renderer matches one type — this is the whole extension surface:

```typescript
import type { TemplateRenderer } from "@visulima/notification/template/string";

type TemplateRenderer = (template: unknown, data?: Record<string, unknown>, options?: Record<string, unknown>) => string | Promise<string>;
```

`renderString`, `renderHandlebars` and `renderLiquid` are simply implementations of it. Richer features — conditionals,
loops, partials/includes, helpers — come from the **engine you choose**; the package delegates rather than reimplementing
them.

## Custom renderer (any engine) [#custom-renderer-any-engine]

To use Eta, Mustache, Nunjucks, EJS, MJML — anything — wrap it in the contract. No package change, no framework lock-in:

```typescript
import type { TemplateRenderer } from "@visulima/notification/template/string";
import { Eta } from "eta";

const eta = new Eta();
const renderEta: TemplateRenderer = (template, data) => eta.renderString(template as string, data ?? {});

await notify.sendToChannel("chat", { text: await renderEta("Hi <%= it.name %>", { name: "Ada" }), to: "C123" });
```

For rich HTML **email**, prefer the email side (`@visulima/email` ships Liquid + jsx-email) and feed the rendered HTML
into the notification email channel.

## Composing with layouts & i18n [#composing-with-layouts--i18n]

A `TemplateRenderer` is what [layouts](/docs/packages/notification/layouts) and the rendered output of
[i18n](/docs/packages/notification/i18n) plug into — so "extending template usage" is composition over the same seam, not
a new framework. Pass your renderer to `defineLayout`, and feed `translate(...)` output as data:

```typescript
import { defineLayout } from "@visulima/notification/layouts";

const layout = defineLayout({ render: renderEta, template: "<main><%~ it.content %></main>" });
const html = await layout.render("<p>Welcome!</p>", { unsubscribeUrl });
```

## Using a renderer in a send [#using-a-renderer-in-a-send]

A renderer is just `(template, data?) => string | Promise<string>`. Render, then send:

```typescript
await notify.sendToChannel("chat", { text: await renderHandlebars(template, data), to: "C123" });
```


# Webhooks (/docs/packages/notification/webhooks)



# Webhooks [#webhooks]

Verify the signature of inbound provider webhooks and normalise them to the `NotificationEvent` shape. All verifiers use
Web Crypto (`globalThis.crypto.subtle`), so they run on Cloudflare Workers and other edge runtimes.

```typescript
import { twilioVerifier, slackVerifier, standardWebhookVerifier, snsVerifier } from "@visulima/notification/webhooks";

// Slack (v0 signing): HMAC-SHA256 of `v0:{timestamp}:{body}` with a 5-minute replay window
const ok = await slackVerifier.verify(rawBody, request.headers, signingSecret);

if (ok) {
    const event = slackVerifier.parse(rawBody); // -> NotificationEvent | undefined
}
```

## Available verifiers [#available-verifiers]

| Verifier                  | Scheme                                                              |
| ------------------------- | ------------------------------------------------------------------- |
| `twilioVerifier`          | `X-Twilio-Signature` — base64 HMAC-SHA1 of URL + sorted params.     |
| `slackVerifier`           | v0 signing — hex HMAC-SHA256 of `v0:{ts}:{body}` + replay window.   |
| `standardWebhookVerifier` | [Standard Webhooks](https://www.standardwebhooks.com/) HMAC-SHA256. |
| `snsVerifier`             | SNS envelope + subscription-confirmation handling.                  |

Each exposes `verify(payload, headers, secret) => Promise<boolean>` and `parse(body) => NotificationEvent | undefined`.

> SNS full RSA certificate-chain verification is a documented TODO; the verifier handles envelope/type parsing and
> subscription confirmation today.


# Workflows (/docs/packages/notification/workflow)



# Workflows [#workflows]

`@visulima/notification/workflow` turns the send primitive into **durable, code-first workflows**: a sequence of channel
sends with delays and conditional logic that survives process restarts. It is a thin layer over
[`@visulima/workflow`](/docs/packages/workflow) — `createNotificationWorkflow` returns a plain `WorkflowDefinition`, so
it plugs straight into a workflow runtime.

`@visulima/workflow` is an optional peer; install it alongside:

```sh
npm install @visulima/notification @visulima/workflow
```

## Defining a workflow [#defining-a-workflow]

```typescript
import { createNotification } from "@visulima/notification";
import { createNotificationWorkflow } from "@visulima/notification/workflow";
import { slackProvider } from "@visulima/notification/providers/slack";
import { fcmProvider } from "@visulima/notification/providers/fcm";
import { createRuntime } from "@visulima/workflow";

const notify = createNotification({
    chat: slackProvider({ token: "xoxb-…", defaultChannel: "C123" }),
    push: fcmProvider({ projectId: "app", getAccessToken: getToken }),
});

const onComment = createNotificationWorkflow<{ subscriberId: string; author: string }>(notify, {
    id: "comment-posted",
    run: async ({ step, payload }) => {
        // Each channel step delivers exactly once and records its receipt.
        await step.push("ping", () => ({ to: [payload.subscriberId], title: "New comment", body: payload.author }));

        // Durably pause — the process can exit and resume later.
        await step.delay("cool-off", { amount: 1, unit: "hours" });

        // Conditionally skip a step.
        await step.chat("recap", () => ({ text: `${payload.author} commented` }), {
            skip: ({ payload }) => payload.author === "bot",
        });
    },
});
```

## Running it [#running-it]

A notification workflow is an ordinary `WorkflowDefinition` — drive it with a workflow runtime:

```typescript
const runtime = createRuntime({ workflows: [onComment] });

await runtime.trigger(onComment, { subscriberId: "u1", author: "ada" });

// Resume delayed runs on a timer (cron job, Cloudflare alarm, …):
await runtime.sweep();
```

See the [workflow engine docs](/docs/packages/workflow) for durability, stores (memory / unstorage / SQL / Redis) and
the cross-process lease.

## The `step` object [#the-step-object]

| Step                                               | What it does                                                                                               |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `step.email / sms / push / chat / inApp / webhook` | Resolve a channel payload and deliver it through the bound facade **exactly once**; returns the `Receipt`. |
| `step.delay(id, duration)`                         | Durably pause (ms, `{ amount, unit }`, or `{ cron }`).                                                     |
| `step.custom(id, fn)`                              | Escape hatch to a raw engine step for non-send side effects.                                               |

Each channel step takes `(id, resolve, options?)`. `resolve` returns the channel payload (it receives `{ payload }`);
`options.skip` conditionally skips the send. Because sends go through the engine's `step`, they are recorded and **not
re-sent on replay**.

> **Delivery failures don't throw by default.** The facade returns a `FailureReceipt` (it doesn't throw), so a failed
> send is recorded as a completed step and **not retried** — check `receipt.successful`, or pass
> `{ throwOnFailure: true }` to turn a failure into a thrown error that fails the run and re-runs the step on the next
> resume/sweep:
>
> ```ts
> await step.email("critical", () => payload, { throwOnFailure: true });
> ```

> **Replay safety:** only work inside `step.*` runs exactly once. Bare side effects in the `run` body re-execute on every
> replay — see the [workflow durability docs](/docs/packages/workflow/durability).


# API Reference (/docs/packages/object/api)



# API Reference [#api-reference]

## Property Access [#property-access]

### getProperty [#getproperty]

```typescript
function getProperty<T>(object: Record<string, unknown>, path: string, defaultValue?: T): T | undefined;
```

Get a nested property value using dot notation.

**Parameters:**

* `object` - The source object
* `path` - Dot notation path (e.g., "user.profile.name")
* `defaultValue` - Value to return if property doesn't exist

**Returns:** Property value or default value

***

### setProperty [#setproperty]

```typescript
function setProperty(object: Record<string, unknown>, path: string, value: unknown): void;
```

Set a nested property value using dot notation.

***

### deleteProperty [#deleteproperty]

```typescript
function deleteProperty(object: Record<string, unknown>, path: string): boolean;
```

Delete a nested property using dot notation.

**Returns:** `true` if property was deleted

***

### hasProperty [#hasproperty]

```typescript
function hasProperty(object: Record<string, unknown>, path: string): boolean;
```

Check if a nested property exists.

***

### escapePath [#escapepath]

```typescript
function escapePath(path: string): string;
```

Escape special characters in a property path.

***

## Object Filtering [#object-filtering]

### pick [#pick]

```typescript
function pick<T extends Record<string, unknown>>(object: T, paths: string[]): Partial<T>;
```

Create a new object with only specified properties.

**Parameters:**

* `object` - Source object
* `paths` - Array of property paths to keep

**Example:**

```typescript
pick({ a: 1, b: 2, c: 3 }, ["a", "c"]);
// { a: 1, c: 3 }
```

***

### omit [#omit]

```typescript
function omit<T extends Record<string, unknown>>(object: T, paths: string[]): Partial<T>;
```

Create a new object without specified properties.

***

## Deep Operations [#deep-operations]

### deepKeys [#deepkeys]

```typescript
function deepKeys(object: Record<string, unknown>): string[];
```

Extract all nested keys from an object.

***

### deepKeysFromList [#deepkeysfromlist]

```typescript
function deepKeysFromList(list: Array<Record<string, unknown>>): string[];
```

Extract all possible keys from an array of objects.

***

## Type Checking [#type-checking]

### isPlainObject [#isplainobject]

```typescript
function isPlainObject(value: unknown): value is Record<string, unknown>;
```

Check if a value is a plain object.

**Returns:** `true` if value is a plain object

***

## Function Summary [#function-summary]

| Function           | Category   | Description                 |
| ------------------ | ---------- | --------------------------- |
| `getProperty`      | Access     | Get nested property value   |
| `setProperty`      | Access     | Set nested property value   |
| `deleteProperty`   | Access     | Delete nested property      |
| `hasProperty`      | Access     | Check if property exists    |
| `escapePath`       | Access     | Escape special characters   |
| `pick`             | Filtering  | Keep specified properties   |
| `omit`             | Filtering  | Remove specified properties |
| `deepKeys`         | Deep Ops   | Extract all nested keys     |
| `deepKeysFromList` | Deep Ops   | Extract keys from array     |
| `isPlainObject`    | Type Check | Check if plain object       |

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/object/usage">
    Learn how to use these functions
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# Introduction (/docs/packages/object)



# @visulima/object [#visulimaobject]

Powerful utilities for manipulating objects and arrays. Access nested properties with dot notation, filter objects with pick/omit, extract deep keys, and more—all with full TypeScript support.

## Key Features [#key-features]

**Dot Notation Access**

* Get, set, and delete nested properties
* Safe property access with fallbacks
* Support for arrays and complex paths
* Path escaping for special characters

**Object Filtering**

* Pick specific properties to keep
* Omit unwanted properties
* Works with nested paths
* Preserves object structure

**Deep Operations**

* Extract all nested keys
* Generate deep key lists
* Traverse complex objects
* Type-safe operations

**Type Safety**

* Full TypeScript support
* Type guards for plain objects
* Preserves nested types
* IntelliSense-friendly

## Quick Start [#quick-start]

Install the package:

```bash
npm install @visulima/object
```

Access nested properties:

```typescript
import { getProperty, setProperty } from "@visulima/object";

const user = {
    profile: {
        settings: {
            theme: "dark",
        },
    },
};

// Get nested value
const theme = getProperty(user, "profile.settings.theme");
console.log(theme); // "dark"

// Set nested value
setProperty(user, "profile.settings.theme", "light");
```

Filter object properties:

```typescript
import { pick, omit } from "@visulima/object";

const pokemon = { id: "007", name: "Squirtle", type: "water" };

const nameAndType = pick(pokemon, ["name", "type"]);
// { name: "Squirtle", type: "water" }

const withoutId = omit(pokemon, ["id"]);
// { name: "Squirtle", type: "water" }
```

## Use Cases [#use-cases]

### Configuration Management [#configuration-management]

Safely access and modify nested configuration:

```typescript
import { getProperty, setProperty, hasProperty } from "@visulima/object";

const config = {
    database: {
        host: "localhost",
        port: 5432,
    },
    cache: {
        enabled: true,
    },
};

// Check if property exists
if (!hasProperty(config, "database.password")) {
    setProperty(config, "database.password", process.env.DB_PASSWORD);
}

// Get with fallback
const port = getProperty(config, "database.port", 3000);
```

### API Response Filtering [#api-response-filtering]

Extract only needed fields from API responses:

```typescript
import { pick } from "@visulima/object";

async function fetchUser(id: string) {
    const response = await fetch(`/api/users/${id}`);
    const fullData = await response.json();

    // Return only public fields
    return pick(fullData, ["id", "name", "email", "profile.avatar", "profile.bio"]);
}
```

### Form Data Processing [#form-data-processing]

Clean sensitive data from form submissions:

```typescript
import { omit } from "@visulima/object";

function sanitizeFormData(data: Record<string, unknown>) {
    // Remove sensitive fields before logging
    return omit(data, ["password", "creditCard", "ssn", "payment.cardNumber"]);
}

const formData = {
    /* user input */
};
logger.info("Form submitted:", sanitizeFormData(formData));
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/object/installation">
    Learn how to install and import the package
  </Card>

  <Card title="Quick Start">
    Get started with common use cases
  </Card>

  <Card title="Usage Guide" href="/docs/packages/object/usage">
    Explore all functions with detailed examples
  </Card>

  <Card title="API Reference" href="/docs/packages/object/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

This package works in both Node.js and browser environments:

* **Node.js:** ≥22.13 ≤25.x
* **Browsers:** Modern browsers with ES6 support
* **Deno/Bun:** Fully compatible


# Installation & Quick Start (/docs/packages/object/installation)





# Installation & Quick Start [#installation--quick-start]

## Installation [#installation]

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/object `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/object `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/object `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/object `
  </Tab>
</Tabs>

## Import [#import]

```typescript
import { getProperty, setProperty, deleteProperty, hasProperty, pick, omit, deepKeys, isPlainObject } from "@visulima/object";
```

## Quick Start Examples [#quick-start-examples]

### Access Nested Properties [#access-nested-properties]

```typescript
import { getProperty, setProperty } from "@visulima/object";

const data = { user: { profile: { name: "Alice" } } };

// Get
const name = getProperty(data, "user.profile.name"); // "Alice"

// Set
setProperty(data, "user.profile.age", 30);
```

### Filter Objects [#filter-objects]

```typescript
import { pick, omit } from "@visulima/object";

const user = { id: 1, name: "Alice", password: "secret", email: "alice@example.com" };

// Keep only specific fields
const publicUser = pick(user, ["id", "name", "email"]);

// Remove sensitive fields
const safeUser = omit(user, ["password"]);
```

### Check Property Existence [#check-property-existence]

```typescript
import { hasProperty } from "@visulima/object";

const config = { api: { key: "abc123" } };

if (hasProperty(config, "api.key")) {
    console.log("API key configured");
}
```

## TypeScript Support [#typescript-support]

Full TypeScript support with type inference:

```typescript
import { getProperty, pick } from "@visulima/object";

interface User {
    id: number;
    profile: {
        name: string;
        settings: {
            theme: "light" | "dark";
        };
    };
}

const user: User = {
    /* ... */
};

// Type-safe access
const theme = getProperty(user, "profile.settings.theme");
// Type: "light" | "dark"

// Type-safe filtering
const filtered = pick(user, ["id", "profile.name"]);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/object/usage">
    Explore all functions with detailed examples
  </Card>

  <Card title="API Reference" href="/docs/packages/object/api">
    Complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/object/usage)



# Usage Guide [#usage-guide]

## Dot Notation Access [#dot-notation-access]

### Get Property [#get-property]

```typescript
import { getProperty } from "@visulima/object";

const obj = {
    user: {
        profile: {
            name: "Alice",
            age: 30,
        },
        posts: [{ title: "First Post" }, { title: "Second Post" }],
    },
};

// Get nested property
console.log(getProperty(obj, "user.profile.name")); // "Alice"

// Get array element
console.log(getProperty(obj, "user.posts.0.title")); // "First Post"

// Get with default value
console.log(getProperty(obj, "user.email", "not@found.com")); // "not@found.com"

// Get non-existent property
console.log(getProperty(obj, "missing.path")); // undefined
```

### Set Property [#set-property]

```typescript
import { setProperty } from "@visulima/object";

const obj = { user: { name: "Alice" } };

// Set existing nested property
setProperty(obj, "user.name", "Bob");

// Create new nested property
setProperty(obj, "user.profile.age", 30);
console.log(obj); // { user: { name: "Bob", profile: { age: 30 } } }

// Set array element
setProperty(obj, "user.tags.0", "developer");
```

### Delete Property [#delete-property]

```typescript
import { deleteProperty } from "@visulima/object";

const obj = {
    user: {
        name: "Alice",
        password: "secret",
        profile: { age: 30 },
    },
};

// Delete nested property
deleteProperty(obj, "user.password");

// Delete deeply nested
deleteProperty(obj, "user.profile.age");

console.log(obj); // { user: { name: "Alice", profile: {} } }
```

### Has Property [#has-property]

```typescript
import { hasProperty } from "@visulima/object";

const config = {
    database: {
        host: "localhost",
        port: 5432,
    },
};

console.log(hasProperty(config, "database.host")); // true
console.log(hasProperty(config, "database.password")); // false
console.log(hasProperty(config, "cache")); // false
```

### Escape Path [#escape-path]

```typescript
import { escapePath } from "@visulima/object";

// Escape special characters in property names
const path = escapePath("user.settings['theme.color']");
// Use this path with getProperty/setProperty
```

## Object Filtering [#object-filtering]

### Pick Properties [#pick-properties]

```typescript
import { pick } from "@visulima/object";

const pokemon = {
    id: "007",
    name: "Squirtle",
    type: "water",
    hp: 44,
    attack: 48,
    defense: 65,
};

// Pick specific properties
const basic = pick(pokemon, ["name", "type"]);
// { name: "Squirtle", type: "water" }

// Pick nested properties
const doc = {
    items: {
        keep: "📌",
        discard: "✂️",
        archive: "📦",
    },
};

const filtered = pick(doc, ["items.keep", "items.archive"]);
// { items: { keep: "📌", archive: "📦" } }
```

### Omit Properties [#omit-properties]

```typescript
import { omit } from "@visulima/object";

const user = {
    id: 1,
    name: "Alice",
    email: "alice@example.com",
    password: "secret",
    creditCard: "1234-5678",
};

// Remove sensitive data
const safe = omit(user, ["password", "creditCard"]);
// { id: 1, name: "Alice", email: "alice@example.com" }

// Omit nested properties
const doc = {
    items: {
        keep: "📌",
        discard: "✂️",
    },
};

const cleaned = omit(doc, ["items.discard"]);
// { items: { keep: "📌" } }
```

## Deep Keys [#deep-keys]

### Extract All Keys [#extract-all-keys]

```typescript
import { deepKeys } from "@visulima/object";

const obj = {
    user: {
        name: "Alice",
        profile: {
            age: 30,
            location: "NYC",
        },
    },
    settings: {
        theme: "dark",
    },
};

const keys = deepKeys(obj);
console.log(keys);
// ["user", "user.name", "user.profile", "user.profile.age", "user.profile.location", "settings", "settings.theme"]
```

### Deep Keys From List [#deep-keys-from-list]

```typescript
import { deepKeysFromList } from "@visulima/object";

const items = [
    { id: 1, name: "Item 1", meta: { price: 10 } },
    { id: 2, name: "Item 2", meta: { price: 20 } },
];

const keys = deepKeysFromList(items);
// Extract all possible keys from array of objects
```

## Type Checking [#type-checking]

### Is Plain Object [#is-plain-object]

```typescript
import { isPlainObject } from "@visulima/object";

console.log(isPlainObject({})); // true
console.log(isPlainObject({ key: "value" })); // true
console.log(isPlainObject(Object.create(null))); // true

console.log(isPlainObject([])); // false
console.log(isPlainObject(null)); // false
console.log(isPlainObject(new Date())); // false
console.log(isPlainObject(/regex/)); // false

class CustomClass {}
console.log(isPlainObject(new CustomClass())); // false
```

## Real-World Examples [#real-world-examples]

### Configuration Merging [#configuration-merging]

```typescript
import { getProperty, setProperty, hasProperty } from "@visulima/object";

function mergeConfig(base: Record<string, unknown>, overrides: Record<string, unknown>) {
    const merged = { ...base };

    for (const [key, value] of Object.entries(overrides)) {
        if (hasProperty(merged, key)) {
            setProperty(merged, key, value);
        }
    }

    return merged;
}
```

### API Response Transformation [#api-response-transformation]

```typescript
import { pick, omit } from "@visulima/object";

class UserService {
    async getPublicProfile(userId: string) {
        const user = await this.db.findUser(userId);

        // Return only public fields
        return pick(user, ["id", "username", "profile.avatar", "profile.bio", "stats.followers", "stats.following"]);
    }

    async sanitizeForLogs(data: Record<string, unknown>) {
        // Remove sensitive fields before logging
        return omit(data, ["password", "token", "creditCard", "ssn", "api.secret"]);
    }
}
```

### Dynamic Form Handling [#dynamic-form-handling]

```typescript
import { getProperty, setProperty } from "@visulima/object";

class FormState {
    private data: Record<string, unknown> = {};

    getValue(path: string, defaultValue?: unknown) {
        return getProperty(this.data, path, defaultValue);
    }

    setValue(path: string, value: unknown) {
        setProperty(this.data, path, value);
    }

    getErrors(path: string): string[] {
        return getProperty(this.data, `errors.${path}`, []);
    }
}

const form = new FormState();
form.setValue("user.email", "alice@example.com");
form.setValue("user.profile.age", 30);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/object/api">
    Complete API documentation with all parameters
  </Card>

  <Card title="Back to Overview">
    Return to package overview
  </Card>
</Cards>


# API (/docs/packages/ono/api)



# API Reference [#api-reference]

## `ono(message, ...args)` [#onomessage-args]

Create and throw an error.

## `ono(error, message, ...args)` [#onoerror-message-args]

Wrap an error with additional context.

## `ono.type(ErrorType, message, ...args)` [#onotypeerrortype-message-args]

Create specific error type.

**Example:**

```typescript
ono("Error: %s", message);
ono(originalError, "Context");
ono.type("TypeError", "Invalid");
```


# Introduction (/docs/packages/ono)



# @visulima/ono [#visulimaono]

Create and throw errors with better formatting, type checking, and error chaining support.

## Key Features [#key-features]

* Formatted error messages
* Error type utilities
* Error wrapping/chaining
* TypeScript support

## Quick Start [#quick-start]

```typescript
import { ono } from "@visulima/ono";

throw ono("Something went wrong");
throw ono(new Error("Original"), "Additional context");
```

<Cards>
  <Card title="Installation" href="/docs/packages/ono/installation">
    Install
  </Card>

  <Card title="Quick Start" href="/docs/packages/ono/quick-start">
    Get started
  </Card>

  <Card title="Usage" href="/docs/packages/ono/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/ono/api">
    API docs
  </Card>
</Cards>


# Installation (/docs/packages/ono/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/ono
```

## Import [#import]

```typescript
import { ono } from "@visulima/ono";
```


# Quick Start (/docs/packages/ono/quick-start)



# Quick Start [#quick-start]

## Basic Usage [#basic-usage]

```typescript
import { ono } from "@visulima/ono";

// Simple error
throw ono("File not found");

// With cause
try {
    // ...
} catch (error) {
    throw ono(error, "Failed to process");
}
```

## Formatted Messages [#formatted-messages]

```typescript
throw ono("User %s not found", userId);
throw ono("Invalid config: %j", config);
```


# Usage (/docs/packages/ono/usage)



# Usage [#usage]

## Error Wrapping [#error-wrapping]

```typescript
import { ono } from "@visulima/ono";

try {
    await fetchData();
} catch (err) {
    throw ono(err, "Failed to fetch data");
}
```

## Type-Specific Errors [#type-specific-errors]

```typescript
throw ono.type("TypeError", "Expected string");
throw ono.range("RangeError", "Value out of bounds");
```

## With Formatting [#with-formatting]

```typescript
throw ono("User %s has %d errors", username, errorCount);
```


# API Reference (/docs/packages/package/api)



# API Reference [#api-reference]

## findMonorepoRoot() [#findmonoreporoot]

Find monorepo root directory and strategy.

**Signature:**

```typescript
function findMonorepoRoot(cwd?: string): Promise<{ path: string; strategy: string } | null>;
```

**Strategies:** `pnpm`, `npm`, `yarn`, `lerna`, `turborepo`

## findPackageRoot() [#findpackageroot]

Find package root directory.

**Signature:**

```typescript
function findPackageRoot(cwd?: string): Promise<{ path: string; strategy: string } | null>;
```

## findPackageJson() [#findpackagejson]

Find and parse package.json/yaml/json5.

**Signature:**

```typescript
function findPackageJson(
    cwd?: string,
    options?: Options,
): Promise<{
    packageJson: PackageJson;
    path: string;
} | null>;
```

**Options:**

* `yaml` - Enable package.yaml support
* `json5` - Enable package.json5 support
* `resolveCatalog` - Resolve pnpm catalog dependencies

## readPackageJson() [#readpackagejson]

Read and parse package.json file.

**Signature:**

```typescript
function readPackageJson(path: string, options?: Options): Promise<PackageJson>;
```

## detectPackageManager() [#detectpackagemanager]

Detect which package manager is used.

**Signature:**

```typescript
function detectPackageManager(cwd?: string): Promise<"pnpm" | "npm" | "yarn" | null>;
```

## Lockfile parsers [#lockfile-parsers]

Subpath: `@visulima/package/lockfile` (also re-exported from the root).

Covers `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` (Classic v1 and Berry v2+), and `bun.lock`. Each entry is returned as a package-manager-agnostic `LockFileEntry` — name, resolved version, decoded SRI integrity (where available), and the declared `dependencies` / `peerDependencies` / `optionalDependencies` specifier maps.

### parseLockFile() / parseLockFileSync() [#parselockfile--parselockfilesync]

Walks up from `cwd` to find the nearest supported lockfile, reads it, and parses it in one call.

**Signature:**

```typescript
function parseLockFile(cwd?: URL | string): Promise<LockFileParseResult>;
function parseLockFileSync(cwd?: URL | string): LockFileParseResult;

interface LockFileParseResult {
    entries: LockFileEntry[];
    path: string;
    type: "bun" | "npm" | "pnpm" | "yarn";
}
```

### parseLockFileContent() [#parselockfilecontent]

Pure dispatcher — parses raw lockfile content of the given type.

**Signature:**

```typescript
function parseLockFileContent(content: string, type: LockFileType): LockFileEntry[];
```

### LockFileEntry shape [#lockfileentry-shape]

```typescript
interface LockFileEntry {
    name: string;
    version: string;
    integrity?: { algorithm: "sha256" | "sha384" | "sha512"; hex: string };
    dependencies?: Record<string, string>;
    peerDependencies?: Record<string, string>;
    optionalDependencies?: Record<string, string>;
}
```

### Format support matrix [#format-support-matrix]

| Lockfile          | Detected filename             | Name / version | SRI integrity | Per-entry edges |
| ----------------- | ----------------------------- | -------------- | ------------- | --------------- |
| npm               | `package-lock.json` (v2 / v3) | ✅              | ✅             | ✅               |
| pnpm              | `pnpm-lock.yaml` (v6 – v9)    | ✅              | ✅             | ✅               |
| Yarn Classic (v1) | `yarn.lock`                   | ✅              | ✅             | ✅               |
| Yarn Berry (v2+)  | `yarn.lock`                   | ✅              | ❌ see below   | ✅               |
| Bun               | `bun.lock`                    | ✅              | ✅             | ✅               |

**Yarn Berry integrity is not supported.** Berry records `checksum: 10c0/…` (XXH64), which is not a cryptographic hash and is outside the CycloneDX 1.7 `HashAlgorithm` enum. Berry entries come out of the parser with `integrity: undefined`. Callers that need Berry integrity must read `yarn.lock` directly.

**Binary `bun.lockb`** (Bun ≤ 1.0) is also unsupported; only the text `bun.lock` (Bun 1.1+) is recognised.

### Low-level parsers [#low-level-parsers]

Individual parsers are exported for callers that already have the raw content and don't need find-up:

```typescript
function parseNpmLockFile(content: string): LockFileEntry[];
function parsePnpmLockFile(content: string): LockFileEntry[];
function parseYarnLockFile(content: string): LockFileEntry[];
function parseBunLockFile(content: string): LockFileEntry[];

function decodeSriIntegrity(sri: string): LockFileIntegrity | undefined;
```

`decodeSriIntegrity` caps input at 1 KiB to avoid pathological `Buffer.from(…, "base64")` allocations.


# Introduction (/docs/packages/package)



# @visulima/package [#visulimapackage]

Comprehensive package management utilities for finding monorepo roots, detecting package managers, and parsing package.json, package.yaml, and package.json5 files.

## Key Features [#key-features]

* **Monorepo Detection** - Find monorepo roots (pnpm, npm, yarn, Lerna, Turborepo)
* **Package Detection** - Locate package roots and package.json files
* **Multi-Format Support** - Parse package.json, package.yaml, and package.json5
* **Catalog Resolution** - Resolve pnpm catalog dependencies
* **Package Manager Detection** - Identify which package manager is used
* **TypeScript** - Full type definitions

## Quick Start [#quick-start]

```typescript
import { findMonorepoRoot, findPackageJson } from "@visulima/package";

// Find monorepo root
const monorepo = await findMonorepoRoot();
console.log(monorepo.strategy); // "pnpm" | "npm" | "yarn" | "lerna"

// Find and parse package.json
const pkg = await findPackageJson();
console.log(pkg.packageJson.name);
```

## Use Cases [#use-cases]

```typescript
// Monorepo tooling
import { findMonorepoRoot } from "@visulima/package";

async function setupMonorepo() {
    const root = await findMonorepoRoot();
    if (root) {
        console.log(`Found ${root.strategy} monorepo at ${root.path}`);
    }
}

// Build tools
import { findPackageJson } from "@visulima/package";

const { packageJson } = await findPackageJson();
const version = packageJson.version;
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/package/installation">
    Install and import
  </Card>

  <Card title="Usage" href="/docs/packages/package/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/package/api">
    API reference
  </Card>
</Cards>


# Installation (/docs/packages/package/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/package
```

## Import [#import]

```typescript
import { findMonorepoRoot, findPackageRoot, findPackageJson, readPackageJson } from "@visulima/package";
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher


# Usage (/docs/packages/package/usage)



# Usage Guide [#usage-guide]

## Find Monorepo Root [#find-monorepo-root]

```typescript
import { findMonorepoRoot } from "@visulima/package";

const result = await findMonorepoRoot();
// => { path: '/path/to/monorepo', strategy: 'pnpm' }
```

Detects: pnpm, npm, yarn, Lerna, Turborepo

## Find Package Root [#find-package-root]

```typescript
import { findPackageRoot } from "@visulima/package";

const result = await findPackageRoot();
// => { path: '/path/to/package', strategy: 'package' }
```

## Find and Parse Package.json [#find-and-parse-packagejson]

```typescript
import { findPackageJson } from "@visulima/package";

// Supports package.json, package.yaml, package.json5
const result = await findPackageJson();
console.log(result.packageJson.name);

// With options
const result2 = await findPackageJson("/path", {
    yaml: true,
    json5: true,
    resolveCatalog: true, // Resolve pnpm catalog
});
```

## Read Package.json [#read-packagejson]

```typescript
import { readPackageJson } from "@visulima/package";

const pkg = await readPackageJson("/path/to/package.json");
```

## Detect Package Manager [#detect-package-manager]

```typescript
import { detectPackageManager } from "@visulima/package";

const pm = await detectPackageManager();
console.log(pm); // "pnpm" | "npm" | "yarn"
```


# @visulima/css-style-inject (/docs/packages/packem/api/css-style-inject)



# @visulima/css-style-inject [#visulimacss-style-inject]

A small runtime utility that injects a `<style>` tag into the document head (or a custom container). It is the default injector used by [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css) in `inject` mode, and supports server-side rendering by collecting CSS into a global store when `document` is unavailable.

This package is ESM-only (`"type": "module"` with no CommonJS exports) and requires Node.js `^22.14.0 || >= 24.10.0`.

## Installation [#installation]

```bash
npm install @visulima/css-style-inject
```

## Exports [#exports]

The package root exports one function and one constant:

```typescript
import { cssStyleInject, SSR_INJECT_ID } from '@visulima/css-style-inject'
```

### `cssStyleInject(css, options?)` [#cssstyleinjectcss-options]

Injects the given CSS. In the browser it creates and inserts a `<style>` tag; during SSR (when `document` is `undefined`) it stores the CSS on a global array for later rendering. Returns `void`. Empty CSS is a no-op.

```typescript
const cssStyleInject = (
  css: string,
  options?: {
    attributes?: Record<string, string>
    container?: string
    id?: string
    insertAt?: number | 'first' | 'last' | { before: string }
    nonce?: string
    singleTag?: boolean
  },
) => void
```

```typescript
import { cssStyleInject } from '@visulima/css-style-inject'

cssStyleInject('body { margin: 0; }', { id: 'reset' })
```

#### Options [#options]

* **id** (`string`) — Unique identifier for the style tag. Prevents duplicate injection: in the browser, injection is skipped if an element with the same `id` already exists; during SSR, a module with an already-seen `id` is not stored again.
* **insertAt** (`number | 'first' | 'last' | { before: string }`, default `'last'`) — Where to insert the tag. A `number` inserts at that index (`0` = first child); a negative number counts from the end, so `-1` appends after the last child. `'first'`/`'last'` insert as first/last child. `{ before: selector }` inserts before the first element matching the selector (falls back to last position if none matches).
* **singleTag** (`boolean`, default `false`) — Reuse a single cached `<style>` tag per container/`insertAt` key instead of creating a new one per call.
* **container** (`string`) — CSS selector for the container element. Defaults to the document head.
* **attributes** (`Record<string, string>`) — Extra attributes to set on the `<style>` tag. The reserved keys `id`, `type`, `nonce`, and any `on*` event-handler attributes are ignored for safety.
* **nonce** (`string`) — Nonce value for CSP compliance. Set via the IDL property so it is not reflected into a readable DOM attribute.

### `SSR_INJECT_ID` [#ssr_inject_id]

The constant key (`"__styleInject_SSR_MODULES"`) under which collected CSS is stored on `globalThis` during SSR. Use it to render the gathered styles on the server.

```typescript
const SSR_INJECT_ID = '__styleInject_SSR_MODULES'
```

#### SSR usage (Next.js example) [#ssr-usage-nextjs-example]

```jsx
// pages/_document.js
import React from 'react'
import { SSR_INJECT_ID } from '@visulima/css-style-inject'

const SSRInjectStyles = () => {
  if (!globalThis[SSR_INJECT_ID]) return null

  return (
    <>
      {globalThis[SSR_INJECT_ID].map((module) => (
        <style
          id={module.id}
          key={module.id}
          dangerouslySetInnerHTML={{ __html: module.css }}
        />
      ))}
    </>
  )
}
```

Each stored entry has the shape `{ css: string; id?: string }`.

## Related [#related]

* [@visulima/rollup-plugin-css](/docs/packages/packem/api/rollup-plugin-css)
* [CSS Processing Guide](/docs/packages/packem/guide/css)


# API Reference (/docs/packages/packem/api)



# API Reference [#api-reference]

Use Packem programmatically, write custom plugins, or hook into the build lifecycle. This section covers the public API for every package in the Packem ecosystem.

## Packages [#packages]

| Package                       | Description                                 | Docs                                               |
| ----------------------------- | ------------------------------------------- | -------------------------------------------------- |
| `@visulima/packem`            | Bundler core, CLI, and configuration API    | [API](/docs/packages/packem/api/packem)            |
| `@visulima/packem-rollup`     | Rollup plugins and transformer integrations | [API](/docs/packages/packem/api/packem-rollup)     |
| `@visulima/rollup-plugin-css` | CSS processing and optimization plugin      | [API](/docs/packages/packem/api/rollup-plugin-css) |
| `@visulima/css-style-inject`  | Runtime CSS injection utility               | [API](/docs/packages/packem/api/css-style-inject)  |
| `@visulima/packem-share`      | Shared types, utilities, and constants      | [API](/docs/packages/packem/api/packem-share)      |

## Programmatic usage [#programmatic-usage]

Run Packem from your own scripts instead of the CLI:

```typescript
import { build } from '@visulima/packem'

await build({
  root: process.cwd(),
  config: 'packem.config.ts',
})
```

## Plugin development [#plugin-development]

Packem uses Rollup under the hood, so any Rollup plugin works. Wrap yours in a function and add it to the `plugins` array:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [myCustomPlugin()],
  },
})
```

See the [plugins option](/docs/packages/packem/options/plugins) for configuration details.

## Specialized APIs [#specialized-apis]

* [packem](/docs/packages/packem/api/packem) — The main package: CLI commands, the `defineConfig` API, and transformer subpaths.
* [packem-rollup](/docs/packages/packem/api/packem-rollup) — Rollup plugins and transformer integration APIs.
* [rollup-plugin-css](/docs/packages/packem/api/rollup-plugin-css) — CSS plugin, loaders, and minifiers.
* [css-style-inject](/docs/packages/packem/api/css-style-inject) — Runtime CSS injection utility.
* [packem-share](/docs/packages/packem/api/packem-share) — Shared types, utilities, and constants.
* [require-cjs-transformer](/docs/packages/packem/api/require-cjs-transformer) — Transform ESM imports of CJS packages for better performance.
* [native-modules-plugin](/docs/packages/packem/api/native-modules-plugin) — Automatic handling of Node.js native addons.

## Build hooks [#build-hooks]

Hook into the build lifecycle to run custom logic:

```typescript
export default defineConfig({
  hooks: {
    'build:before': (context) => {
      console.log('Build starting...')
    },
    'build:done': (context) => {
      console.log(`Built in ${context.duration}ms`)
    },
  },
})
```

See the [hooks option](/docs/packages/packem/options/hooks) for the full list of available hooks.

## Environment variables [#environment-variables]

| Variable        | Description                                    |
| --------------- | ---------------------------------------------- |
| `PACKEM_CONFIG` | Path to config file (overrides auto-detection) |
| `NODE_ENV`      | Set to `production` for optimized builds       |
| `DEBUG`         | Set to `packem:*` for debug output             |


# native-modules-plugin (/docs/packages/packem/api/native-modules-plugin)



# native-modules-plugin [#native-modules-plugin]

Handles native Node.js addons (.node files) by copying them to the output directory and generating appropriate import statements.

## Installation [#installation]

The plugin is included with `@visulima/packem-rollup`:

```bash
npm install @visulima/packem
```

## Usage [#usage]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    nativeModules: {
      nativesDirectory: 'natives'
    }
  }
})
```

## API Reference [#api-reference]

### nativeModulesPlugin [#nativemodulesplugin]

```typescript
function nativeModulesPlugin(
  options?: NativeModulesOptions
): Plugin
```

Creates a Rollup plugin that handles native Node.js addons.

#### Parameters [#parameters]

* **options** (`NativeModulesOptions?`): Plugin configuration options

#### Returns [#returns]

A Rollup plugin instance.

## Options [#options]

### NativeModulesOptions [#nativemodulesoptions]

```typescript
interface NativeModulesOptions {
  /**
   * Custom subdirectory name for native modules within the output directory
   * @default 'natives'
   */
  nativesDirectory?: string
}
```

### nativesDirectory [#nativesdirectory]

**Type:** `string`\
&#x2A;*Default:** `'natives'`

The subdirectory name within the output directory where native modules will be copied. This directory will be created automatically.

**Example:**

```typescript
nativeModules: {
  nativesDirectory: 'native-addons'
}
```

## How It Works [#how-it-works]

The native modules plugin operates in two stages:

### Stage 1: Resolve and Load (Build Time) [#stage-1-resolve-and-load-build-time]

1. **Detection**: Identifies `.node` file imports in your code
2. **Resolution**: Resolves the file paths and validates accessibility
3. **Registration**: Registers native modules for copying
4. **Virtual Module**: Creates virtual module IDs for each native module

### Stage 2: Bundle Generation (Bundle Time) [#stage-2-bundle-generation-bundle-time]

1. **Directory Creation**: Creates the natives directory in the output
2. **File Copying**: Copies all registered `.node` files in parallel
3. **Import Generation**: Generates appropriate `require()` statements

## Examples [#examples]

### Basic Usage [#basic-usage]

```typescript
// src/index.ts
import myAddon from './my-addon.node'

export function useAddon() {
  return myAddon.someFunction()
}
```

**Output:**

```javascript
// dist/index.js
const myAddon = require("./natives/my-addon.node")

export function useAddon() {
  return myAddon.someFunction()
}
```

### Custom Directory [#custom-directory]

```typescript
export default defineConfig({
  transformer,
  rollup: {
    nativeModules: {
      nativesDirectory: 'addons'
    }
  }
})
```

**Output:**

```javascript
const myAddon = require("./addons/my-addon.node")
```

### Multiple Native Modules [#multiple-native-modules]

```typescript
// src/index.ts
import addon1 from './addon1.node'
import addon2 from './addon2.node'
import addon3 from './addon3.node'

export { addon1, addon2, addon3 }
```

**Output:**

```javascript
const addon1 = require("./natives/addon1.node")
const addon2 = require("./natives/addon2.node")
const addon3 = require("./natives/addon3.node")

export { addon1, addon2, addon3 }
```

## File Structure [#file-structure]

```
project/
├── src/
│   ├── index.ts
│   └── my-addon.node
├── dist/
│   ├── index.js
│   └── natives/
│       └── my-addon.node  # Copied here
└── package.json
```

## Import Patterns [#import-patterns]

The plugin supports various import patterns for native modules:

### Default Import [#default-import]

```typescript
import myAddon from './my-addon.node'
```

### Named Import [#named-import]

```typescript
import { someFunction } from './my-addon.node'
```

### Dynamic Import [#dynamic-import]

```typescript
const myAddon = await import('./my-addon.node')
```

## Error Handling [#error-handling]

The plugin provides clear error messages for common issues:

### File Not Found [#file-not-found]

```
Native module not found: /path/to/missing.node
```

### Output Directory Not Configured [#output-directory-not-configured]

```
Output directory not detected. Please ensure Rollup output options are configured.
```

### Module Registration Failed [#module-registration-failed]

```
Could not find staged native module for: /path/to/module.node
```

## Platform Considerations [#platform-considerations]

### Cross-Platform Builds [#cross-platform-builds]

Native modules are platform-specific. When building for multiple platforms:

1. **Separate builds**: Create separate builds for each target platform
2. **Conditional loading**: Use dynamic imports with platform detection
3. **Optional dependencies**: Mark platform-specific modules as optional

### Platform-Specific Imports [#platform-specific-imports]

```typescript
// src/native.ts
const isWindows = process.platform === 'win32'
const isMac = process.platform === 'darwin'
const isLinux = process.platform === 'linux'

let nativeModule
if (isWindows) {
  nativeModule = await import('./native.win32.node')
} else if (isMac) {
  nativeModule = await import('./native.darwin.node')
} else if (isLinux) {
  nativeModule = await import('./native.linux.node')
}

export default nativeModule
```

## Performance Considerations [#performance-considerations]

### Bundle Size [#bundle-size]

* Native modules are copied as-is to the output directory
* File size impacts distribution size but not bundle parsing time
* Consider compression for large native modules

### Load Time [#load-time]

* Native modules load faster than JavaScript bundles
* No JavaScript parsing overhead for native code
* Platform-specific optimization opportunities

## Troubleshooting [#troubleshooting]

### Module Not Copied [#module-not-copied]

1. **Verify import syntax**: Use relative imports for `.node` files
2. **Check file existence**: Ensure the `.node` file exists at build time
3. **Validate path resolution**: Confirm relative paths are correct

### Import Errors [#import-errors]

1. **Output directory**: Ensure the output directory is properly configured
2. **File permissions**: Check read/write permissions for native module files
3. **Platform compatibility**: Verify the native module matches the target platform

### Build Failures [#build-failures]

1. **Clean build**: Remove `dist/` and rebuild
2. **Dependency order**: Ensure native modules are built before bundling
3. **File watchers**: Restart file watchers after adding new native modules

## Integration Examples [#integration-examples]

### With Electron [#with-electron]

```typescript
// electron/main.ts
import { app, BrowserWindow } from 'electron'
import nativeAddon from './native-addon.node'

app.whenReady().then(() => {
  // Use native addon in main process
  const result = nativeAddon.initialize()
  
  const mainWindow = new BrowserWindow({
    webPreferences: {
      nodeIntegration: true
    }
  })
})
```

### With N-API [#with-n-api]

```typescript
// C++ addon with N-API
#include <napi.h>

Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set("version", Napi::String::New(env, "1.0.0"));
  return exports;
}

NODE_API_MODULE(addon, Init)
```

```typescript
// TypeScript usage
import addon from './addon.node'

console.log('Addon version:', addon.version)
```

## Related APIs [#related-apis]

* [`defineConfig`](/docs/packages/packem/api/packem#defineconfig) - Main configuration function
* [`BuildConfig`](/docs/packages/packem/api/packem#config-types) - Configuration interface
* [`PackemRollupOptions`](/docs/packages/packem/api/packem-rollup#packemrollupoptions) - Rollup configuration options

## See Also [#see-also]

* [Native Addons Guide](https://nodejs.org/api/addons.html) - Node.js native addons documentation
* [N-API Guide](https://nodejs.org/api/n-api.html) - N-API documentation
* [Electron Native Modules](https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules) - Electron-specific guide


# @visulima/packem-rollup (/docs/packages/packem/api/packem-rollup)



# @visulima/packem-rollup [#visulimapackem-rollup]

Rollup plugins and transformer integrations for Packem.

## Installation [#installation]

```bash
npm install @visulima/packem-rollup
```

## Transformers [#transformers]

### esbuild Transformer [#esbuild-transformer]

```typescript
import transformer from '@visulima/packem-rollup/transformer/esbuild'
```

Fast JavaScript/TypeScript transformer using esbuild.

### swc Transformer [#swc-transformer]

```typescript
import transformer from '@visulima/packem-rollup/transformer/swc'
```

Rust-powered transformer using swc.

### OXC Transformer [#oxc-transformer]

```typescript
import transformer from '@visulima/packem-rollup/transformer/oxc'
```

Next-generation JavaScript toolchain.

### sucrase Transformer [#sucrase-transformer]

```typescript
import transformer from '@visulima/packem-rollup/transformer/sucrase'
```

Lightweight JavaScript transformer.

### TypeScript Transformer [#typescript-transformer]

```typescript
import transformer from '@visulima/packem-rollup/transformer/typescript'
```

Official TypeScript compiler transformer.

## Plugins [#plugins]

### nativeModulesPlugin [#nativemodulesplugin]

```typescript
import { nativeModulesPlugin } from '@visulima/packem-rollup'
```

Handles native Node.js addons (.node files) by copying them to the output directory and generating appropriate import statements.

#### Usage [#usage]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    nativeModules: {
      nativesDirectory: 'natives'
    }
  }
})
```

#### Options [#options]

```typescript
interface NativeModulesOptions {
  /**
   * Custom subdirectory name for native modules within the output directory
   * @default 'natives'
   */
  nativesDirectory?: string
}
```

See [native-modules-plugin API docs](/docs/packages/packem/api/native-modules-plugin) for detailed documentation.

### require-cjs-transformer [#require-cjs-transformer]

```typescript
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'
```

Transform ESM imports of CJS packages to `require()` calls for better performance.

#### Usage [#usage-1]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      requireCJSTransformerPlugin({
        builtinNodeModules: true
      })
    ]
  }
})
```

#### Options [#options-1]

```typescript
interface RequireCJSPluginOptions {
  builtinNodeModules?: boolean
  cwd?: string
  additionalPackages?: string[]
  exclude?: string[]
  include?: string[]
  excludePatterns?: string[]
}
```

See [require-cjs-transformer API docs](/docs/packages/packem/api/require-cjs-transformer) for detailed documentation.

### minify-html-literals [#minify-html-literals]

```typescript
import { minifyHTMLLiteralsPlugin } from '@visulima/packem-rollup'
```

Automatically minifies HTML and CSS content within template literals during the build process. This plugin identifies tagged template literals containing HTML/CSS and applies minification to reduce bundle size.

:::note
This plugin only runs when minification is enabled in Packem (`minify: true` in your configuration).
:::

#### Usage [#usage-2]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: true, // Required for the plugin to run
  rollup: {
    minifyHTMLLiterals: {
      include: ['**/*.ts', '**/*.js'],
      failOnError: false
    }
  }
})
```

#### Options [#options-2]

```typescript
interface MinifyHTMLLiteralsOptions {
  /**
   * Pattern or array of patterns of files not to minify.
   */
  exclude?: FilterPattern;

  /**
   * If true, any errors while parsing or minifying will abort the bundle
   * process. Defaults to false, which will only show a warning.
   */
  failOnError?: boolean;

  /**
   * Pattern or array of patterns of files to minify.
   */
  include?: string | string[];

  /**
   * Override minify-html-literals function.
   */
  minifyHTMLLiterals?: typeof minifyHTMLLiterals;

  /**
   * Minify options, see
   * https://www.npmjs.com/package/minify-html-literals#options.
   */
  options?: Partial<MinifyHTMLLiteralsOptions>;
}
```

### Other Rollup Plugins [#other-rollup-plugins]

Packem includes several other Rollup plugins:

* **CSS Processing**: Sass, Less, Stylus, PostCSS support
* **Asset Handling**: Image and font processing
* **TypeScript**: Declaration file generation
* **Optimization**: Minification and tree shaking

## Utilities [#utilities]

### isPureCJS [#ispurecjs]

```typescript
import { isPureCJS } from '@visulima/packem-rollup'

const result = await isPureCJS('typescript', '/path/to/importer')
console.log(result) // true
```

Detects if a package is CommonJS-only.

#### Parameters [#parameters]

* **id** (`string`): Package name or path
* **importer** (`string`): Importing file path
* **rollupResolve** (`Function?`): Custom resolver function

#### Returns [#returns]

`Promise<boolean>` - True if the package is CJS-only.

## Types [#types]

### PackemRollupOptions [#packemrollupoptions]

```typescript
interface PackemRollupOptions {
  css?: CssOptions
  minifyHTMLLiterals?: MinifyHTMLLiteralsOptions | false
  nativeModules?: NativeModulesOptions | false
  requireCJS?: RequireCJSPluginOptions | false
  plugins?: Plugin[]
  // ... other Rollup options
}
```

Configuration options for Rollup in Packem.

### NativeModulesOptions [#nativemodulesoptions]

```typescript
interface NativeModulesOptions {
  /**
   * Custom subdirectory name for native modules within the output directory
   * @default 'natives'
   */
  nativesDirectory?: string
}
```

Configuration options for the native modules plugin.

### RequireCJSPluginOptions [#requirecjspluginoptions]

See [require-cjs-transformer API docs](/docs/packages/packem/api/require-cjs-transformer#requirecjspluginoptions).

## Examples [#examples]

### Basic Transformer Usage [#basic-transformer-usage]

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem-rollup/transformer/esbuild'

export default defineConfig({
  transformer: esbuildTransformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true
    }
  }
})
```

### Advanced Plugin Configuration [#advanced-plugin-configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem-rollup/transformer/swc'
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'

export default defineConfig({
  transformer,
  minify: true, // Required for minify-html-literals to run
  rollup: {
    minifyHTMLLiterals: {
      include: ['src/**/*.ts'],
      options: {
        minifyOptions: {
          collapseWhitespace: true,
          removeComments: true
        }
      }
    },
    plugins: [
      requireCJSTransformerPlugin({
        builtinNodeModules: true,
        additionalPackages: ['my-cjs-lib']
      })
    ]
  }
})
```

## Related [#related]

* [Packem Configuration](/docs/packages/packem/guide/configuration)
* [Transformers Guide](/docs/packages/packem/guide/transformers)
* [require-cjs-transformer Plugin](/docs/packages/packem/guide/require-cjs-transformer)
* [require-cjs-transformer Examples](/docs/packages/packem/examples/advanced/require-cjs-transformer)


# @visulima/packem-share (/docs/packages/packem/api/packem-share)



# @visulima/packem-share [#visulimapackem-share]

Shared types, utilities, and constants used across the Packem packages. It centralizes the build-context contracts, Rollup helper utilities, and the constants that drive module resolution and export handling.

This package is ESM-only (`"type": "module"` with no CommonJS exports) and requires Node.js `^22.14.0 || >= 24.10.0`. It has a `rollup` peer dependency.

## Installation [#installation]

```bash
npm install @visulima/packem-share
```

## Subpath exports [#subpath-exports]

The root re-exports everything from the three subpaths, which are also importable directly:

```typescript
import { /* constants, utils, types */ } from '@visulima/packem-share'
import { /* utils */ } from '@visulima/packem-share/utils'
import type { /* types */ } from '@visulima/packem-share/types'
import { /* constants */ } from '@visulima/packem-share/constants'
```

## Constants — `@visulima/packem-share/constants` [#constants--visulimapackem-shareconstants]

```typescript
import {
  VALID_EXPORT_EXTENSIONS,
  DEFAULT_EXTENSIONS,
  DEFAULT_LOADERS,
  PRODUCTION_ENV,
  DEVELOPMENT_ENV,
  RUNTIME_EXPORT_CONVENTIONS,
  SPECIAL_EXPORT_CONVENTIONS,
  EXCLUDE_REGEXP,
  ENDING_REGEX,
  CHUNKS_PACKEM_FOLDER,
  SHARED_PACKEM_FOLDER,
  ALLOWED_TRANSFORM_EXTENSIONS_REGEX,
} from '@visulima/packem-share/constants'
```

| Constant                             | Type                     | Description                                                       |
| ------------------------------------ | ------------------------ | ----------------------------------------------------------------- |
| `VALID_EXPORT_EXTENSIONS`            | `ReadonlyArray<string>`  | Valid file extensions for the `package.json` `exports` field.     |
| `DEFAULT_EXTENSIONS`                 | `string[]`               | Default extensions Packem processes (adds `.ctsx`/`.mtsx`).       |
| `DEFAULT_LOADERS`                    | `Record<string, Loader>` | Maps file extensions to esbuild loader types.                     |
| `PRODUCTION_ENV`                     | `string`                 | `"production"`.                                                   |
| `DEVELOPMENT_ENV`                    | `string`                 | `"development"`.                                                  |
| `RUNTIME_EXPORT_CONVENTIONS`         | `Set<string>`            | `edge-light`, `react-native`, `react-server`.                     |
| `SPECIAL_EXPORT_CONVENTIONS`         | `Set<string>`            | Runtime conventions plus the environment names.                   |
| `EXCLUDE_REGEXP`                     | `RegExp`                 | Matches `node_modules` for skipping processing.                   |
| `ENDING_REGEX`                       | `RegExp`                 | Matches file extensions, including `.d.ts`/`.d.mts`/`.d.cts`.     |
| `CHUNKS_PACKEM_FOLDER`               | `string`                 | `"packem_chunks"` — directory for generated chunks.               |
| `SHARED_PACKEM_FOLDER`               | `string`                 | `"packem_shared"` — directory for shared resources.               |
| `ALLOWED_TRANSFORM_EXTENSIONS_REGEX` | `RegExp`                 | Matches JS/TS files (and module variants) eligible for transform. |

## Utilities — `@visulima/packem-share/utils` [#utilities--visulimapackem-shareutils]

```typescript
import {
  arrayify,
  createRollupLogger,
  enhanceRollupError,
  FileCache,
  getCacheHash,
  getChunkFilename,
  getEntryFileNames,
  getDtsExtension,
  getOutputExtension,
  getHash,
  getPackageName,
  getRegexMatches,
  isBareSpecifier,
  isFromNodeModules,
  isOutsideProject,
  parseSpecifier,
  memoize,
  memoizeByKey,
  replaceContentWithinMarker,
  sortUserPlugins,
  svgToCssDataUri,
  svgToTinyDataUri,
  svgEncoder,
  warn,
} from '@visulima/packem-share/utils'

import type { RollupLogger, Memoized } from '@visulima/packem-share/utils'
```

* **`arrayify`** — Normalize a value into an array.
* **`createRollupLogger`*&#x2A; / &#x2A;*`RollupLogger`** — Build a Rollup-compatible logger.
* **`enhanceRollupError`** — Enrich Rollup errors with extra context.
* **`FileCache`** — Filesystem-backed cache class.
* **`getCacheHash`*&#x2A;, &#x2A;*`getHash`** — Hashing helpers.
* **`getChunkFilename`*&#x2A;, &#x2A;*`getEntryFileNames`** — Output filename helpers.
* **`getDtsExtension`*&#x2A;, &#x2A;*`getOutputExtension`** — Resolve declaration/output extensions.
* **`getPackageName`** — Extract a package name from a specifier.
* **`getRegexMatches`** — Collect all matches for a pattern.
* **`isBareSpecifier`*&#x2A;, &#x2A;*`isFromNodeModules`*&#x2A;, &#x2A;*`isOutsideProject`*&#x2A;, &#x2A;*`parseSpecifier`** — Import-specifier analysis.
* **`memoize`*&#x2A;, &#x2A;*`memoizeByKey`*&#x2A; / &#x2A;*`Memoized`** — Memoization helpers.
* **`replaceContentWithinMarker`** — Replace content between markers.
* **`sortUserPlugins`** — Order user-supplied plugins.
* **`svgToCssDataUri`*&#x2A;, &#x2A;*`svgToTinyDataUri`*&#x2A;, &#x2A;*`svgEncoder`** — SVG data-URI encoding.
* **`warn`** — Emit a warning.

## Types — `@visulima/packem-share/types` [#types--visulimapackem-sharetypes]

```typescript
import type {
  BuildContext,
  BuildContextBuildAssetAndChunk,
  BuildContextBuildEntry,
  BuildHooks,
  Environment,
  Format,
  Mode,
  Runtime,
} from '@visulima/packem-share/types'
```

### Core type aliases [#core-type-aliases]

```typescript
type Environment = 'production' | 'development' | undefined
type Mode = 'build' | 'jit' | 'watch'
type Format = 'cjs' | 'esm'
type Runtime =
  | 'browser' | 'bun' | 'deno' | 'edge-light' | 'electron'
  | 'node' | 'react-native' | 'react-server' | 'workerd' | undefined
```

### `BuildContext<T>` [#buildcontextt]

The context object passed to build hooks. Carries the resolved options, package manifest, logger, hookable instance, dependency tracking sets, and the collected build entries.

```typescript
type BuildContext<T = unknown> = {
  buildEntries: (BuildContextBuildAssetAndChunk | BuildContextBuildEntry)[]
  dependencyGraphMap: Map<string, Set<[string, string]>>
  environment: Environment
  hoistedDependencies: Set<string>
  hooks: Hookable<BuildHooks<T>>
  implicitDependencies: Set<string>
  jiti: Jiti
  logger: Pail
  mode: Mode
  options: T
  pkg: PackageJson
  tsconfig?: TsConfigResult
  usedDependencies: Set<string>
  warnings: Set<string>
}
```

### `BuildHooks<T>` [#buildhookst]

The lifecycle hooks contract. Each hook receives the `BuildContext` (some also receive a Rollup build/options/watcher object):

```typescript
interface BuildHooks<T> {
  'build:before': (context: BuildContext<T>) => Promise<void> | void
  'build:prepare': (context: BuildContext<T>) => Promise<void> | void
  'build:done': (context: BuildContext<T>) => Promise<void> | void
  'builder:before': (name: string, context: BuildContext<T>) => Promise<void> | void
  'builder:done': (name: string, context: BuildContext<T>) => Promise<void> | void
  'rollup:options': (context: BuildContext<T>, options: RollupOptions) => Promise<void> | void
  'rollup:build': (context: BuildContext<T>, build: RollupBuild) => Promise<void> | void
  'rollup:done': (context: BuildContext<T>) => Promise<void> | void
  'rollup:watch': (context: BuildContext<T>, watcher: RollupWatcher) => Promise<void> | void
  'rollup:dts:options': (context: BuildContext<T>, options: RollupOptions) => Promise<void> | void
  'rollup:dts:build': (context: BuildContext<T>, build: RollupBuild) => Promise<void> | void
  'rollup:dts:done': (context: BuildContext<T>) => Promise<void> | void
  /** @deprecated Use "builder:before" instead */
  'typedoc:before': (context: BuildContext<T>) => Promise<void> | void
  /** @deprecated Use "builder:done" instead */
  'typedoc:done': (context: BuildContext<T>) => Promise<void> | void
  'validate:before': (context: BuildContext<T>) => Promise<void> | void
  'validate:done': (context: BuildContext<T>) => Promise<void> | void
}
```

### `BuildContextBuildEntry` / `BuildContextBuildAssetAndChunk` [#buildcontextbuildentry--buildcontextbuildassetandchunk]

Describe a single emitted entry or asset/chunk, including its path, size breakdown (`bytes`/`gzip`/`brotli`), modules, chunks, exports, and dynamic imports.

## Related [#related]

* [Build Hooks](/docs/packages/packem/options/hooks)
* [@visulima/packem](/docs/packages/packem/api/packem)


# @visulima/packem (/docs/packages/packem/api/packem)



# @visulima/packem [#visulimapackem]

The main Packem package: a fast and modern bundler for Node.js and TypeScript. It ships the `packem` CLI, the configuration API, and the transformer integrations.

`@visulima/packem` is ESM-only (`"type": "module"` with no CommonJS exports). It requires Node.js `^22.14.0 || >= 24.10.0`.

## Installation [#installation]

```bash
npm install @visulima/packem
```

## CLI [#cli]

The package exposes a single binary, `packem`:

```json
{
  "bin": {
    "packem": "./dist/cli/index.js"
  }
}
```

### `packem build` [#packem-build]

Build the package using the resolved Packem configuration.

```bash
packem build [dir]
```

Selected options (run `packem build --help` for the full list):

* `--bundler <rollup|rolldown>` — Specify the bundler to use.
* `--dir <dir>` — The directory to build.
* `--target <target>` — Environments to support. The `target` in `tsconfig.json` is added automatically.
* `--config <file>` — Use a custom config file.
* `--tsconfig <file>` — Path to the `tsconfig.json` file.
* `--minify` — Minify the output.
* `--sourcemap` — Generate sourcemaps (experimental).
* `--watch` — Watch for changes.
* `--jit` — Stub the package for JIT compilation.
* `--env.<KEY>=<value>` — Compile-time environment variables (e.g. `--env.NODE_ENV=production`).
* `--env-file <file>` — Path to the `.env` file to load environment variables from.
* `--env-prefix <prefix>` — Prefix for environment variables to load from `.env` (default: `PACKEM_`).
* `--metafile` — Generate a meta file (experimental).
* `--license <file>` — Path to the license file.
* `--analyze` — Visualize and analyze the bundle.
* `--cjsInterop` — CJS interop mode (experimental).
* `--production` / `--development` — Run in production or development environment.
* `--no-clean` — Do not clean the `dist` directory before building.

### `packem init` [#packem-init]

Initialize a Packem configuration in your project.

```bash
packem init [dir]
```

Options:

* `--dir <dir>` — The directory to initialize.
* `--transformer <name>` — Choose a transformer.
* `--css` — Use CSS.
* `--css-minifier <name>` — Use a CSS minifier.
* `--typescript` — Use TypeScript.
* `--runtime <nodejs|browser>` — Specify the build runtime.

### `packem add` [#packem-add]

Add an optional Packem feature to your project.

```bash
packem add <feature>
```

Recognized features include `typedoc`, `react`, `solid`, `preact`, `vue`, `svelte`, and `css`.

Options:

* `--dir <dir>` — The directory to build.
* `--config <file>` — Use a custom config file.

### `packem migrate` [#packem-migrate]

Migrate from other bundlers (tsup, unbuild, bunchee, etc.) to Packem.

```bash
packem migrate [cwd]
```

Options:

* `--cwd <dir>` — The directory to migrate.
* `--dry-run` — Preview changes without applying them.

## Programmatic API [#programmatic-api]

The package root re-exports the `packem` runner alongside the core build types.

```typescript
import { packem } from '@visulima/packem'

await packem('./', {
  mode: 'build',
  environment: 'production',
})
```

### `packem(rootDirectory, options?)` [#packemrootdirectory-options]

```typescript
const packem = (rootDirectory: string, options?: PackemOptions) => Promise<void>
```

* **rootDirectory** (`string`) — The root directory of the project to bundle.
* **options** (`PackemOptions`) — Configuration options for the bundler.

### `PackemOptions` [#packemoptions]

Extends `BuildConfig` with a few runner-level fields:

```typescript
interface PackemOptions extends BuildConfig {
  /** The environment to build for. @default "production" */
  environment?: Environment
  /** Logger configuration options. */
  logger?: ConstructorOptions<string, string>
  /** The mode to run Packem in. @default "build" */
  mode?: Mode
}
```

### Exported types [#exported-types]

The package root also re-exports the following types:

```typescript
import type {
  BuildEntry,
  BuildOptions,
  RollupBuildOptions,
} from '@visulima/packem'

import type {
  TransformerFn,
  TransformerName,
} from '@visulima/packem'

import type {
  BuildContext,
  BuildContextBuildAssetAndChunk,
  BuildContextBuildEntry,
  BuildHooks,
  Environment,
  Mode,
  Runtime,
} from '@visulima/packem'
```

## Configuration — `@visulima/packem/config` [#configuration--visulimapackemconfig]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  entries: ['./src/index.ts'],
})
```

### `defineConfig(config)` [#defineconfigconfig]

Defines a build configuration. Accepts a static configuration object or a function that returns one.

```typescript
const defineConfig = (
  config: BuildConfig | BuildConfigFunction,
) => BuildConfig | BuildConfigFunction
```

```typescript
// Dynamic configuration
export default defineConfig((env, mode) => ({
  entries: ['./src/index.ts'],
  outDir: env === 'production' ? './dist' : './dev',
}))
```

### `definePreset(preset)` [#definepresetpreset]

Defines a reusable build preset.

```typescript
const definePreset = (preset: BuildPreset) => BuildPreset
```

```typescript
export default definePreset({
  name: 'my-preset',
  defaults: {
    entries: ['./src/index.ts'],
  },
  hooks: {
    'build:before': (context) => {
      // Custom build preparation logic
    },
  },
})
```

### Config types [#config-types]

The `config` subpath also re-exports these types:

```typescript
import type {
  BuildConfig,
  BuildConfigFunction,
  BuildPreset,
  BuildHooks,
} from '@visulima/packem/config'
```

### Framework presets [#framework-presets]

Ready-made presets are available as dedicated subpaths:

```typescript
import react from '@visulima/packem/config/preset/react'
import preact from '@visulima/packem/config/preset/preact'
import solid from '@visulima/packem/config/preset/solid'
import svelte from '@visulima/packem/config/preset/svelte'
import vue from '@visulima/packem/config/preset/vue'
```

## Transformers [#transformers]

Pick the transformer that compiles your TypeScript/JavaScript and pass it to `transformer` in your config.

### esbuild [#esbuild]

```typescript
import transformer from '@visulima/packem/transformer/esbuild'
```

### swc [#swc]

```typescript
import transformer from '@visulima/packem/transformer/swc'
```

### OXC [#oxc]

```typescript
import transformer from '@visulima/packem/transformer/oxc'
```

### sucrase [#sucrase]

```typescript
import transformer from '@visulima/packem/transformer/sucrase'
```

## Additional subpath exports [#additional-subpath-exports]

The `package.json` `exports` map also exposes:

* `@visulima/packem/css/loader/{sourcemap,less,postcss,sass,stylus,lightningcss,tailwindcss}` — CSS loaders.
* `@visulima/packem/css/minifier/{cssnano,lightningcss}` — CSS minifiers.
* `@visulima/packem/builder/typedoc` — TypeDoc documentation builder.
* `@visulima/packem/files` — Ambient declarations for asset imports (types only).
* `@visulima/packem/package.json` — The package manifest.

## Related [#related]

* [Packem Configuration](/docs/packages/packem/guide/configuration)
* [Transformers Guide](/docs/packages/packem/guide/transformers)
* [CLI Reference](/docs/packages/packem/guide/cli)
* [@visulima/packem-rollup](/docs/packages/packem/api/packem-rollup)


# require-cjs-transformer (/docs/packages/packem/api/require-cjs-transformer)



# require-cjs-transformer [#require-cjs-transformer]

Transform ESM imports of CommonJS-only packages to `require()` calls for better Node.js performance.

## Installation [#installation]

The plugin is included with `@visulima/packem-rollup`:

```bash
npm install @visulima/packem
```

## Usage [#usage]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true
    }
  }
})
```

## API Reference [#api-reference]

### requireCJSTransformerPlugin [#requirecjstransformerplugin]

```typescript
function requireCJSTransformerPlugin(
  options?: RequireCJSPluginOptions,
  logger?: Pail
): Plugin
```

Creates a Rollup plugin that transforms ESM imports of CJS packages.

#### Parameters [#parameters]

* **options** (`RequireCJSPluginOptions?`): Plugin configuration options
* **logger** (`Pail?`): Logger instance for debug output

#### Returns [#returns]

A Rollup plugin instance.

## Options [#options]

### RequireCJSPluginOptions [#requirecjspluginoptions]

```typescript
interface RequireCJSPluginOptions {
  /**
   * Transform Node.js built-in modules (fs, path, etc.) to use runtime helpers that check Node.js version compatibility
   * @default false
   */
  builtinNodeModules?: boolean

  /**
   * Custom working directory for module resolution
   * @default process.cwd()
   */
  cwd?: string

  /**
   * Additional packages to consider as CJS-only (force transformation)
   * @default []
   */
  additionalPackages?: string[]

  /**
   * Packages to exclude from transformation
   * @default []
   */
  exclude?: string[]

  /**
   * Include patterns for files to process
   * @default ['**/*.{js,jsx,ts,tsx,mjs,mts,cjs,cts}']
   */
  include?: string[]

  /**
   * Exclude patterns for files to skip
   * @default ['**/node_modules/**']
   */
  excludePatterns?: string[]
}
```

### builtinNodeModules [#builtinnodemodules]

**Type:** `boolean`\
&#x2A;*Default:** `false`

When enabled, transforms Node.js built-in modules to use runtime helpers that check Node.js version compatibility and fallback to `require()` when needed.

**Example:**

```typescript
// Input
import { readFileSync } from 'fs'
import { join } from 'path'

// Output (with builtinNodeModules: true)
const { readFileSync } = __cjs_getBuiltinModule("fs")
const { join } = __cjs_getBuiltinModule("path")
```

### cwd [#cwd]

**Type:** `string`\
&#x2A;*Default:** `process.cwd()`

Working directory for module resolution. Useful when the plugin runs in a different directory than the project root.

### additionalPackages [#additionalpackages]

**Type:** `string[]`\
&#x2A;*Default:** `[]`

Additional packages to force transformation for, even if they appear to be ESM-compatible.

**Example:**

```typescript
requireCJS: {
  additionalPackages: ['my-cjs-package', '@myorg/cjs-lib']
}
```

### exclude [#exclude]

**Type:** `string[]`\
&#x2A;*Default:** `[]`

Packages to exclude from transformation, even if they are detected as CJS-only.

**Example:**

```typescript
requireCJS: {
  exclude: ['some-package', '@myorg/esm-package']
}
```

### include [#include]

**Type:** `string[]`\
&#x2A;*Default:** `['**/*.{js,jsx,ts,tsx,mjs,mts,cjs,cts}']`

File patterns to include for transformation processing.

### excludePatterns [#excludepatterns]

**Type:** `string[]`\
&#x2A;*Default:** `['**/node_modules/**']`

File patterns to exclude from transformation processing.

## Examples [#examples]

### Basic Configuration [#basic-configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true
    }
  }
})
```

### Advanced Configuration [#advanced-configuration]

```typescript
export default defineConfig({
  transformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true,
      additionalPackages: ['my-cjs-lib'],
      exclude: ['some-esm-package'],
      include: ['src/**/*.{ts,tsx}'],
      excludePatterns: ['src/vendor/**']
    }
  }
})
```

### Programmatic Usage [#programmatic-usage]

```typescript
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'

const plugin = requireCJSTransformerPlugin({
  builtinNodeModules: true,
  additionalPackages: ['typescript']
})
```

## Transformation Examples [#transformation-examples]

### Named Imports [#named-imports]

```typescript
// Input
import { parse } from '@babel/parser'
import { transpile } from 'typescript'

// Output
const { parse } = require("@babel/parser")
const { transpile } = require("typescript")
```

### Default Imports [#default-imports]

```typescript
// Input
import typescript from 'typescript'
import parser from '@babel/parser'

// Output
const typescript = require("typescript")
const parser = require("@babel/parser")
```

### Namespace Imports [#namespace-imports]

```typescript
// Input
import * as ts from 'typescript'
import * as babel from '@babel/core'

// Output
const ts = require("typescript")
const babel = require("@babel/core")
```

### Node.js Built-ins [#nodejs-built-ins]

```typescript
// Input (with builtinNodeModules: true)
import { readFileSync } from 'fs'
import { join, dirname } from 'path'

// Output
const { readFileSync } = __cjs_getBuiltinModule("fs")
const { join, dirname } = __cjs_getBuiltinModule("path")
```

### Mixed Imports [#mixed-imports]

```typescript
// Input
import fs, { readFileSync } from 'fs'
import * as path from 'path'
import { join } from 'path'

// Output (with builtinNodeModules: true)
const fs = __cjs_getBuiltinModule("fs")
const { readFileSync } = __cjs_getBuiltinModule("fs")
const path = __cjs_getBuiltinModule("path")
const { join } = __cjs_getBuiltinModule("path")
```

## Detection Logic [#detection-logic]

The plugin automatically detects CJS-only packages by:

1. **Package.json Analysis**: Checks if `type: "commonjs"` is set
2. **Export Conditions**: Analyzes available export conditions
3. **Entry Points**: Verifies if only CommonJS entry points exist
4. **Additional Packages**: Includes user-specified packages
5. **Exclusions**: Respects user-defined exclusions

### Automatic Detection Examples [#automatic-detection-examples]

**CJS-only package** (transformed):

```json
{
  "name": "cjs-package",
  "main": "index.js",
  "type": "commonjs"
}
```

**ESM package** (not transformed):

```json
{
  "name": "esm-package",
  "type": "module",
  "exports": {
    ".": {
      "import": "./index.js",
      "types": "./index.d.ts"
    }
  }
}
```

**Dual package** (not transformed - has ESM exports):

```json
{
  "name": "dual-package",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}
```

## TypeScript Support [#typescript-support]

The plugin generates TypeScript declaration files that reflect the transformed imports:

```typescript
// Input types (from package)
export declare function parse(code: string): AST

// Generated declaration (transformed)
declare const parse: (code: string) => AST
export { parse }
```

## Rollup Integration [#rollup-integration]

The plugin integrates with Rollup's plugin system and provides:

* **Transform Hook**: Processes individual chunks during bundling
* **ResolveId Hook**: Handles module resolution for transformed imports
* **Logger Integration**: Uses Rollup's logging system for debug output

### Plugin Hooks [#plugin-hooks]

```typescript
interface Plugin {
  name: 'packem:require-cjs-transformer'
  version: string

  renderChunk: (code: string, chunk: RenderedChunk) => { code: string } | null
  resolveId: (id: string, importer?: string) => Promise<string | null>
}
```

## Performance Considerations [#performance-considerations]

### When to Use [#when-to-use]

* ✅ CLI tools with heavy CJS package usage
* ✅ Build tools and bundlers
* ✅ Applications with measurable startup time issues
* ✅ Development servers with frequent restarts

### When NOT to Use [#when-not-to-use]

* ❌ Simple applications with few CJS imports
* ❌ Libraries consumed by other packages
* ❌ When performance gain is negligible
* ❌ If you prefer simpler build configuration

### Benchmarking [#benchmarking]

```typescript
// Measure startup time impact
const start = Date.now()
await import('./dist/index.js')
const end = Date.now()
console.log(`Startup time: ${end - start}ms`)
```

## Error Handling [#error-handling]

### Common Errors [#common-errors]

**"Cannot resolve module"**

* Ensure the package is installed
* Check if the package name is spelled correctly
* Verify the package exports the expected modules

**"Plugin only works with ESM output"**

* Ensure your Rollup output format is ESM-compatible

**"Module not found in exclude list"**

* Check your `exclude` configuration
* Verify package names match exactly

### Debug Logging [#debug-logging]

Enable debug logging to troubleshoot transformation issues:

```typescript
export default defineConfig({
  // ... other config
  rollup: {
    requireCJS: {
      // ... options
    }
  }
})
```

The plugin logs transformation details with the prefix `packem:plugin-require-cjs`.

## Related APIs [#related-apis]

* [`defineConfig`](/docs/packages/packem/api/packem#defineconfig) - Main configuration function
* [`BuildConfig`](/docs/packages/packem/api/packem#config-types) - Configuration interface
* [`isPureCJS`](/docs/packages/packem/api/packem-rollup#ispurecjs) - Utility for detecting CJS packages


# @visulima/rollup-plugin-css (/docs/packages/packem/api/rollup-plugin-css)



# @visulima/rollup-plugin-css [#visulimarollup-plugin-css]

A comprehensive CSS processing plugin for [Packem](https://github.com/visulima/packem) that provides support for multiple CSS preprocessors, CSS modules, and advanced optimization features. It powers Packem's CSS pipeline but can also be used as a standalone Rollup plugin.

This package is ESM-only (`"type": "module"` with no CommonJS exports) and requires Node.js `^22.14.0 || >= 24.10.0`. The CSS processors you use (postcss, sass/sass-embedded, less, stylus, lightningcss, cssnano, tailwindcss) are optional peer dependencies — install only the ones you need.

## Installation [#installation]

```bash
npm install @visulima/rollup-plugin-css
```

## Exports [#exports]

The package root exports two plugin factories plus its public types:

```typescript
import {
  rollupCssPlugin,
  cssModulesTypesPlugin,
} from '@visulima/rollup-plugin-css'
```

### `rollupCssPlugin(options, browserTargets, cwd, sourceDirectory, environment, useSourcemap, debug, minify, alias)` [#rollupcsspluginoptions-browsertargets-cwd-sourcedirectory-environment-usesourcemap-debug-minify-alias]

The main CSS processing plugin. Returns a Rollup `Plugin`. It handles preprocessing, PostCSS, CSS modules, source maps, minification, and the configured integration mode (inject / extract / emit / inline).

```typescript
const plugin = rollupCssPlugin(
  { mode: 'extract', postcss: { plugins: [] } },
  ['> 1%'],          // browserTargets
  process.cwd(),     // cwd
  'src',             // sourceDirectory
  'production',      // environment
  true,              // useSourcemap
  false,             // debug
  false,             // minify
  {},                // alias
)
```

### `cssModulesTypesPlugin()` [#cssmodulestypesplugin]

Generates TypeScript declaration files (`.d.ts`) for CSS modules, enabling type-safe class-name usage. Use it alongside `rollupCssPlugin`.

```typescript
import { rollupCssPlugin, cssModulesTypesPlugin } from '@visulima/rollup-plugin-css'

export default {
  plugins: [
    rollupCssPlugin({ /* ...options, modules enabled */ }),
    cssModulesTypesPlugin(),
  ],
}
```

The generated declaration looks like:

```typescript
// styles.module.css.d.ts
declare const styles: {
  readonly container: string
  readonly button: string
  readonly active: string
}
export default styles
```

## Options — `StyleOptions` [#options--styleoptions]

The first argument to `rollupCssPlugin`. Key fields:

```typescript
interface StyleOptions {
  /** Aliases for URL and import paths. */
  alias?: Record<string, string>
  /** Auto-enable CSS Modules for files named [name].module.[ext]. @default false */
  autoModules?: RegExp | boolean | ((id: string) => boolean)
  /** Options for the cssnano minifier. */
  cssnano?: Options
  /** Generate TypeScript declaration files for input style files. */
  dts?: boolean
  /** Files to exclude from processing. */
  exclude?: ReadonlyArray<RegExp | string> | RegExp | string
  /** Extensions to process. @default [".css", ".pcss", ".postcss", ".sss"] */
  extensions?: string[]
  /** Files to include for processing. */
  include?: ReadonlyArray<RegExp | string> | RegExp | string
  /** Options for the Less loader. */
  less?: LESSLoaderOptions
  /** Options for LightningCSS. */
  lightningcss?: LightningCSSOptions
  /** Array of custom loaders. */
  loaders?: Loader[]
  /** Enable the CSS minifier. */
  minifier?: Minifier
  /**
   * Integration mode.
   * - "inject" (default) — embed CSS in JS and inject into <head> at runtime
   * - "extract" — extract CSS to a separate .css file
   * - "emit" — pass processed CSS along the build pipeline
   * - "inline" — embed CSS directly as strings in JS modules
   * @default "inject"
   */
  mode?:
    | 'emit' | 'extract' | 'inject' | 'inline'
    | ['extract', string]
    | ['inject', InjectOptions | ((varname: string, id: string) => string)]
  /** Use named exports alongside the default export. @default false */
  namedExports?: boolean | ((name: string) => string)
  /** Invoked on CSS file extraction; return boolean to control extraction. */
  onExtract?: (data: ExtractedData) => boolean
  /** Invoked on CSS file import before transformations. */
  onImport?: (code: string, id: string) => void
  /** Options for PostCSS. */
  postcss?: PostCSSOptions
  /** Options for the Sass loader. */
  sass?: SassLoaderOptions
  /** Enable/disable or configure sourcemaps. @default false */
  sourceMap?: boolean | 'inline' | [boolean | 'inline', SourceMapOptions] | [boolean | 'inline']
  /** Options for the Stylus loader. */
  stylus?: StylusLoaderOptions
}
```

### `InjectOptions` [#injectoptions]

Controls runtime injection when `mode` is `"inject"`:

```typescript
interface InjectOptions {
  /** Attributes set on the injected <style> tag(s). */
  attributes?: Record<string, string>
  /** Container for <style> tag(s) injection. @default "head" */
  container?: string
  /** Package method name to use. @default "cssStyleInject" */
  method?: string
  /** Package to import the CSS injector from. @default "@visulima/css-style-inject" */
  package?: string
  /** Insert <style> tag(s) at the beginning of the container. @default false */
  prepend?: boolean
  /** Inject CSS into a single <style> tag only. @default false */
  singleTag?: boolean
  /** Make the injector treeshakeable. Incompatible with namedExports. */
  treeshakeable?: boolean
}
```

## Loaders [#loaders]

Each loader is the `default` export of its subpath. The plugin runs preprocessor loaders before PostCSS.

```typescript
import sass from '@visulima/rollup-plugin-css/loader/sass'
import less from '@visulima/rollup-plugin-css/loader/less'
import stylus from '@visulima/rollup-plugin-css/loader/stylus'
import postcss from '@visulima/rollup-plugin-css/loader/postcss'
import lightningcss from '@visulima/rollup-plugin-css/loader/lightningcss'
import tailwindcss from '@visulima/rollup-plugin-css/loader/tailwindcss'
import sourcemap from '@visulima/rollup-plugin-css/loader/sourcemap'
```

| Subpath                 | Loader                                                  |
| ----------------------- | ------------------------------------------------------- |
| `./loader/sass`         | Sass/SCSS preprocessing (`sass` or `sass-embedded`)     |
| `./loader/less`         | Less compilation (`less`)                               |
| `./loader/stylus`       | Stylus compilation (`stylus`)                           |
| `./loader/postcss`      | PostCSS pipeline, CSS Modules, `@import`/url resolution |
| `./loader/lightningcss` | LightningCSS processing                                 |
| `./loader/tailwindcss`  | Tailwind Oxide engine integration                       |
| `./loader/sourcemap`    | Source map extraction                                   |

## Minifiers [#minifiers]

```typescript
import cssnano from '@visulima/rollup-plugin-css/minifier/cssnano'
import lightningcss from '@visulima/rollup-plugin-css/minifier/lightningcss'
```

Each is the `default` export of its subpath and implements the `Minifier` interface used by the `minifier` option.

## Utilities [#utilities]

```typescript
import { /* ... */ } from '@visulima/rollup-plugin-css/utils'
```

Internal helpers used by the plugin and loaders, available under the `./utils` subpath.

## Related [#related]

* [CSS Processing Guide](/docs/packages/packem/guide/css)
* [@visulima/css-style-inject](/docs/packages/packem/api/css-style-inject)
* [@visulima/packem-rollup](/docs/packages/packem/api/packem-rollup)


# Bundle Analysis (/docs/packages/packem/examples/advanced/bundle-analysis)



# Bundle Analysis [#bundle-analysis]

Packem ships two complementary ways to understand what ends up in your bundle: a visual treemap report via the `analyze` option, and machine-readable build metadata via the `metafile` flag.

## Overview [#overview]

* **`analyze`** — generates a `packem-bundle-analyze.html` treemap showing the makeup of your bundle (module sizes, gzip and brotli sizes).
* **`metafile`** — produces JSON metadata about the build that you can feed into external analysis tools.

:::note
`analyze` conflicts with watch mode — it runs during a one-off build, not while watching.
:::

## Visual Bundle Report [#visual-bundle-report]

Enable the visualizer through the `analyze` option (or the `--analyze` CLI flag). Packem writes `packem-bundle-analyze.html` at build time.

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  analyze: true
})
```

```bash
# Or via the CLI
packem build --analyze
```

The generated report includes gzip and brotli sizes by default and is titled "Packem Visualizer".

### Customizing the Visualizer [#customizing-the-visualizer]

You can pass options to the underlying visualizer through `rollup.visualizer` (it accepts `rollup-plugin-visualizer` options). Set it to `false` to suppress the report even when `analyze` is on.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  analyze: true,
  rollup: {
    visualizer: {
      // Treemap, sunburst, network, list or raw-data
      template: 'sunburst',
      gzipSize: true,
      brotliSize: true
    }
  }
})
```

:::note
Packem always forces the output `filename` to `packem-bundle-analyze.html` and the `title` to "Packem Visualizer"; other visualizer options are passed through.
:::

## Metafile [#metafile]

Pass the `--metafile` flag to make Packem emit build metadata in JSON format. You can feed the output into analysis tools like [bundle buddy](https://www.bundle-buddy.com/rollup) to see which modules take up space.

```bash
packem build --metafile
```

Files are written as `metafile-{bundleName}-{format}.json`, for example `metafile-test-cjs.json` and `metafile-test-es.json`.

:::note
The metafile feature is experimental. Enabling `metafile` or `analyze` also turns on source map generation, since both rely on source map data.
:::

## package.json [#packagejson]

```json
{
  "name": "@myorg/analyze-example",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "import": "./dist/index.mjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "analyze": "packem build --analyze",
    "meta": "packem build --metafile"
  },
  "devDependencies": {
    "@visulima/packem": "^2"
  }
}
```

## Notes [#notes]

* `analyze` produces a human-readable HTML treemap; `metafile` produces JSON for tooling — use them together for a full picture.
* Because both imply source maps, expect `.map` files (or inline maps) in the output when either is enabled.
* Use the analysis to spot accidentally bundled dependencies, then externalize them or split with [Dynamic Imports](/docs/packages/packem/examples/advanced/dynamic-imports).

## Related [#related]

* [Optimization Guide](/docs/packages/packem/guide/optimization)
* [Dynamic Imports](/docs/packages/packem/examples/advanced/dynamic-imports)
* [Duplicate packages](/docs/packages/packem/options/detect-duplicated)


# Custom Plugins (/docs/packages/packem/examples/advanced/custom-plugins)



# Custom Plugins [#custom-plugins]

Packem exposes a top-level `plugins` option so you can inject your own Rollup plugins into the build pipeline. Each entry controls *when* the plugin runs (`enforce`) and *which* pipeline it applies to (`type`).

## Overview [#overview]

The `plugins` option takes an array of objects with the following shape:

* `plugin` — the Rollup plugin instance (required).
* `enforce` — `"pre"` or `"post"`, similar to webpack loaders, to adjust application order. Omit it to run with the default group.
* `type` — `"build"` (default) or `"dts"`. A `dts` plugin only runs while declaration files are generated.

### Resolution order [#resolution-order]

Packem resolves plugins in this order:

* Alias
* User plugins with `enforce: 'pre'`
* Rollup core plugins
* User plugins without an `enforce` value
* Rollup build plugins
* User plugins with `enforce: 'post'`
* Rollup post-build plugins (minify, manifest, copy, reporting)

## Configuration [#configuration]

**packem.config.ts**

```typescript
import { optimizeLodashImports } from '@optimize-lodash/rollup-plugin'
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  plugins: [
    {
      enforce: 'pre',
      plugin: optimizeLodashImports()
      // type: "build" -> default value
    }
  ]
})
```

## Targeting the Declaration Pipeline [#targeting-the-declaration-pipeline]

Set `type: 'dts'` to run a plugin only when declaration files are generated:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import type { Plugin } from 'rollup'

const stripInternalComments = (): Plugin => ({
  name: 'strip-internal-comments',
  renderChunk(code) {
    return code.replace(/\/\*\* @internal \*\/[\s\S]*?\n/g, '')
  }
})

export default defineConfig({
  transformer,
  declaration: true,
  plugins: [
    {
      type: 'dts',
      plugin: stripInternalComments()
    }
  ]
})
```

## Multiple Plugins with Ordering [#multiple-plugins-with-ordering]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import replace from '@rollup/plugin-replace'
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  transformer,
  plugins: [
    {
      // runs before Rollup core plugins
      enforce: 'pre',
      plugin: replace({
        preventAssignment: true,
        values: { __VERSION__: '1.0.0' }
      })
    },
    {
      // runs after build plugins, before post-build reporting
      enforce: 'post',
      plugin: visualizer({ filename: 'stats.html' })
    }
  ]
})
```

## Notes [#notes]

* `plugin` accepts any standard Rollup `Plugin` instance, so the entire Rollup plugin ecosystem is available.
* Use `enforce: 'pre'` for transforms that must run before Packem's core resolution, and `enforce: 'post'` for output-stage plugins.
* A `type: 'dts'` plugin is skipped entirely when declarations are not being generated.

## Related [#related]

* [Plugins Option](/docs/packages/packem/options/plugins)
* [Plugins Guide](/docs/packages/packem/guide/plugins)
* [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis)


# Dynamic Imports (/docs/packages/packem/examples/advanced/dynamic-imports)



# Dynamic Imports [#dynamic-imports]

Packem supports dynamic `import()` expressions and uses them as code-split points. Modules loaded with `import()` are emitted into separate chunks that are only fetched when the importing code actually runs, keeping the initial bundle small.

## Overview [#overview]

Because Packem builds on Rollup, any `import()` call in your source becomes a code-splitting boundary. This is useful for:

* Lazy-loading heavy or rarely used features
* Splitting optional functionality out of the main entry
* Reducing startup cost for CLIs and servers

:::note
Dynamic imports are a supported, first-class feature of Packem (see the feature list in the package README).
:::

## Project Structure [#project-structure]

```
dynamic-imports-example/
├── src/
│   ├── index.ts
│   ├── heavy-feature.ts
│   └── reporter.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Source Files [#source-files]

**src/heavy-feature.ts**

```typescript
// A large module we only want to load on demand
export function runHeavyFeature(input: string): string {
  // ...imagine a lot of code here
  return `processed: ${input}`
}
```

**src/index.ts**

```typescript
export async function maybeRun(flag: boolean, input: string) {
  if (!flag) {
    return input
  }

  // Loaded lazily — emitted into its own chunk
  const { runHeavyFeature } = await import('./heavy-feature')

  return runHeavyFeature(input)
}
```

## Configuration [#configuration]

No special option is required — dynamic `import()` is split automatically.

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true,
  sourcemap: true
})
```

**package.json**

```json
{
  "name": "@myorg/dynamic-imports",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs"
    }
  },
  "scripts": {
    "build": "packem build"
  },
  "devDependencies": {
    "@visulima/packem": "^2"
  }
}
```

## Build Output [#build-output]

The dynamically imported module is placed in its own chunk and referenced via `import()` in the output:

```bash
$ packem build

dist/index.mjs            # entry — keeps the import() call
dist/heavy-feature.mjs    # split chunk, loaded on demand
```

```javascript
// dist/index.mjs (simplified)
export async function maybeRun(flag, input) {
  if (!flag) return input
  const { runHeavyFeature } = await import('./heavy-feature.mjs')
  return runHeavyFeature(input)
}
```

## Notes [#notes]

* Each unique dynamic import target becomes a separate chunk; shared dependencies between chunks are hoisted automatically by Rollup.
* If you want code shared across multiple bundles without a separate entry, prefer the [Shared Modules](/docs/packages/packem/examples/advanced/shared-modules) convention instead.
* Use [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis) to confirm how your code splits across chunks.

## Related [#related]

* [Shared Modules](/docs/packages/packem/examples/advanced/shared-modules)
* [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis)
* [Tree Shaking](/docs/packages/packem/options/tree-shaking)


# minify-html-literals Plugin (/docs/packages/packem/examples/advanced/minify-html-literals)



# minify-html-literals Plugin Example [#minify-html-literals-plugin-example]

This example demonstrates how to use the `minify-html-literals` plugin to automatically minify HTML and CSS content within template literals during the build process, reducing bundle size and improving performance.

## Overview [#overview]

The `minify-html-literals` plugin analyzes your JavaScript/TypeScript code and automatically identifies template literals tagged with HTML or containing HTML/CSS content. It then applies minification to reduce the size of your bundles.

:::note
This plugin only runs when minification is enabled in Packem (`minify: true` in your configuration).
:::

## Basic Example [#basic-example]

### Project Structure [#project-structure]

```
minify-html-example/
├── src/
│   ├── components/
│   │   ├── Button.ts
│   │   ├── Card.ts
│   │   └── Layout.ts
│   ├── styles/
│   │   ├── global.css
│   │   └── themes.css
│   ├── index.ts
│   └── utils.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Source Files [#source-files]

**src/components/Button.ts**

```typescript
import { html } from 'lit'

export class Button extends HTMLElement {
  render() {
    return html`
      <button class="btn btn-primary">
        <span class="btn-text">Click me</span>
      </button>
    `
  }
}
```

**src/components/Card.ts**

```typescript
import { html } from 'lit'

export class Card extends HTMLElement {
  render() {
    return html`
      <div class="card">
        <div class="card-header">
          <h2 class="card-title">Card Title</h2>
        </div>
        <div class="card-body">
          <p class="card-text">
            This is some example content for the card component.
            It has multiple lines and various HTML elements.
          </p>
        </div>
        <div class="card-footer">
          <button class="btn btn-secondary">Action</button>
        </div>
      </div>
    `
  }
}
```

**src/styles/global.css**

```css
.btn {
  display: inline-block;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;
  font-size: 1rem;
  text-decoration: none;
  transition: all 0.2s ease-in-out;
}

.btn-primary {
  background-color: #007bff;
  color: white;
}

.btn-primary:hover {
  background-color: #0056b3;
}

.btn-secondary {
  background-color: #6c757d;
  color: white;
}

.btn-secondary:hover {
  background-color: #545b62;
}

.btn-text {
  font-weight: 500;
}
```

**src/index.ts**

```typescript


// Register custom elements
customElements.define('my-button', Button)
customElements.define('my-card', Card)

export { Button, Card }
```

### Configuration [#configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem-rollup/transformer/esbuild'

export default defineConfig({
  transformer: esbuildTransformer,
  entry: {
    index: 'src/index.ts'
  },
  minify: true, // Required for the plugin to run
  rollup: {
    minifyHTMLLiterals: {
      // Include only TypeScript files
      include: ['**/*.ts'],
      // Don't fail the build on minification errors
      failOnError: false
    }
  }
})
```

## Advanced Configuration [#advanced-configuration]

### Custom Minification Options [#custom-minification-options]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem-rollup/transformer/esbuild'

export default defineConfig({
  transformer: esbuildTransformer,
  entry: {
    index: 'src/index.ts'
  },
  minify: true, // Required for the plugin to run
  rollup: {
    minifyHTMLLiterals: {
      include: ['src/**/*.ts'],
      failOnError: true, // Fail build on minification errors
      options: {
        // Custom HTML minification options
        minifyOptions: {
          collapseWhitespace: true,
          removeComments: true,
          removeEmptyAttributes: true,
          removeOptionalTags: true,
          minifyCSS: true,
          minifyJS: true
        },
        // Custom CSS minification options
        minifyCSSOptions: {
          level: 2, // Maximum compression
          compatibility: 'ie8'
        }
      }
    }
  }
})
```

### Using Tagged Template Literals [#using-tagged-template-literals]

**src/components/Modal.ts**

```typescript
import { html, css } from 'lit'

const modalStyles = css`
  .modal {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background: rgba(0, 0, 0, 0.5);
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 1000;
  }

  .modal-content {
    background: white;
    border-radius: 8px;
    padding: 2rem;
    max-width: 500px;
    width: 90%;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  }

  .modal-header {
    margin-bottom: 1rem;
  }

  .modal-title {
    margin: 0;
    font-size: 1.5rem;
    font-weight: bold;
  }

  .modal-body {
    margin-bottom: 1.5rem;
  }

  .modal-footer {
    display: flex;
    justify-content: flex-end;
    gap: 0.5rem;
  }
`

export class Modal extends HTMLElement {
  render() {
    return html`
      <div class="modal">
        <div class="modal-content">
          <div class="modal-header">
            <h2 class="modal-title">Modal Title</h2>
          </div>
          <div class="modal-body">
            <p>This is the modal content. The plugin will automatically minify both the HTML and CSS within this template literal.</p>
            <p>Notice how the CSS is also minified, reducing the bundle size significantly.</p>
          </div>
          <div class="modal-footer">
            <button class="btn btn-secondary">Cancel</button>
            <button class="btn btn-primary">Confirm</button>
          </div>
        </div>
      </div>
    `
  }

  static get styles() {
    return modalStyles
  }
}
```

## Custom Strategy Example [#custom-strategy-example]

### Using a Custom Minification Strategy [#using-a-custom-minification-strategy]

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem-rollup/transformer/esbuild'
import type { Strategy } from '@visulima/packem-rollup'

const customStrategy: Strategy = {
  async minifyHTML(html: string, options: any): Promise<string> {
    // Custom HTML minification logic
    return html
      .replace(/\s+/g, ' ')  // Replace multiple spaces with single space
      .replace(/>\s+</g, '><')  // Remove spaces between tags
      .trim()
  },

  async minifyCSS(css: string, options: any): Promise<string> {
    // Custom CSS minification logic
    return css
      .replace(/\/\*[\s\S]*?\*\//g, '')  // Remove comments
      .replace(/\s+/g, ' ')  // Replace multiple spaces
      .replace(/;\s*}/g, '}')  // Remove trailing semicolons
      .trim()
  }
}

export default defineConfig({
  transformer: esbuildTransformer,
  minify: true, // Required for the plugin to run
  rollup: {
    minifyHTMLLiterals: {
      include: ['src/**/*.ts'],
      options: {
        strategy: customStrategy
      }
    }
  }
})
```

## Performance Benefits [#performance-benefits]

### Before Minification [#before-minification]

```typescript
const template = html`
  <div class="container">
    <h1 class="title">
      Welcome to my app
    </h1>
    <p class="description">
      This is a description with lots of whitespace
      that will be removed during minification.
    </p>
  </div>
`

const styles = css`
  .container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
  }

  .title {
    font-size: 2rem;
    font-weight: bold;
    margin-bottom: 1rem;
  }

  .description {
    line-height: 1.6;
    color: #666;
  }
`
```

### After Minification [#after-minification]

```typescript
const template = html`<div class="container"><h1 class="title">Welcome to my app</h1><p class="description">This is a description with lots of whitespace that will be removed during minification.</p></div>`

const styles = css`.container{max-width:1200px;margin:0 auto;padding:20px}.title{font-size:2rem;font-weight:bold;margin-bottom:1rem}.description{line-height:1.6;color:#666}`
```

## Build Output [#build-output]

After running the build, the HTML and CSS content within your template literals will be automatically minified, resulting in smaller bundle sizes and better performance.

```bash
$ packem build

✓ Built in 1.2s
📦 Bundle size: 15.3 kB (minified)
```

## Related [#related]

* [Packem Rollup API Documentation](/docs/packages/packem/api/packem-rollup)
* [Configuration Guide](/docs/packages/packem/guide/configuration)
* [CSS Processing Guide](/docs/packages/packem/guide/css)


# Multi-Runtime (/docs/packages/packem/examples/advanced/multi-runtime)



# Multi-Runtime [#multi-runtime]

Packem can build a single source tree into runtime-specific bundles by reacting to the special export conditions in your `package.json`. Conditions like `node`, `browser`, `react-server`, and `edge-light` are treated as distinct platforms, each with its own input source file and output bundle.

## Overview [#overview]

Packem supports the following runtimes out of the box:

* `default`
* `node`
* `browser`
* `react-server`
* `edge-light`

For special platform conditions such as `react-server` and `edge-light`, Packem provides an *override input source file convention*: name a source file with the runtime suffix and Packem will compile it as a separate bundle for that condition.

:::note
The `edge-light` export injects a `process.env.EdgeRuntime` variable that is `true`; for every other runtime it resolves to `false`.
:::

## Project Structure [#project-structure]

```
multi-runtime-example/
├── src/
│   ├── index.ts                 # default / import condition
│   ├── index.react-server.ts    # react-server condition
│   └── index.edge-light.ts      # edge-light condition
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Source Files [#source-files]

**src/index.ts**

```typescript
export function getRuntime(): string {
  return 'node'
}
```

**src/index.react-server.ts**

```typescript
// Compiled into a dedicated react-server bundle
export function getRuntime(): string {
  return 'react-server'
}
```

**src/index.edge-light.ts**

```typescript
// process.env.EdgeRuntime is true in this bundle
export function getRuntime(): string {
  return process.env.EdgeRuntime ? 'edge-light' : 'node'
}
```

## Configuration [#configuration]

The conditional exports map drives the whole build. Packem reads it, matches the special conditions to the suffixed source files, and emits one bundle per condition.

**package.json**

```json
{
  "name": "@myorg/multi-runtime",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "react-server": "./dist/index.react-server.mjs",
      "edge-light": "./dist/index.edge-light.mjs",
      "import": "./dist/index.mjs"
    }
  },
  "scripts": {
    "build": "packem build"
  },
  "devDependencies": {
    "@visulima/packem": "^2"
  }
}
```

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

## Per-Entry Runtime [#per-entry-runtime]

When you configure entries explicitly, each entry carries its own `runtime` value. The supported runtimes are `browser`, `bun`, `deno`, `edge-light`, `electron`, `node`, `react-native`, `react-server`, and `workerd`.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  entries: [
    { input: 'src/index.ts', runtime: 'node' },
    { input: 'src/index.edge-light.ts', runtime: 'edge-light' }
  ]
})
```

## Build Output [#build-output]

```bash
$ packem build

dist/index.mjs                 # default / node
dist/index.react-server.mjs    # react-server condition
dist/index.edge-light.mjs      # edge-light condition (EdgeRuntime === true)
```

## Notes [#notes]

* Only the special platform conditions (`react-server`, `react-native`, `edge-light`) get their own input override file; the remaining conditions resolve against the default source.
* Combine this with [Shared Modules](/docs/packages/packem/examples/advanced/shared-modules) when several runtime bundles must share a single instance of a module.
* See the [Multi-Runtime guide](/docs/packages/packem/guide/multi-runtime) for the full conditional-exports reference.

## Related [#related]

* [Multi-Runtime Guide](/docs/packages/packem/guide/multi-runtime)
* [Shared Modules](/docs/packages/packem/examples/advanced/shared-modules)
* [Package Exports](/docs/packages/packem/options/package-exports)


# require-cjs-transformer Plugin (/docs/packages/packem/examples/advanced/require-cjs-transformer)



# require-cjs-transformer Plugin Example [#require-cjs-transformer-plugin-example]

This example demonstrates how to use the `require-cjs-transformer` plugin to automatically transform ESM imports of CommonJS-only packages into `require()` calls for better Node.js performance.

## Overview [#overview]

The `require-cjs-transformer` plugin solves a specific performance issue: when you import CommonJS-only packages using ESM syntax, Node.js must use the expensive `cjs-module-lexer` to analyze the CJS module. This plugin converts ESM imports to `require()` calls, allowing Node.js to skip this analysis step.

## Basic Example [#basic-example]

### Project Structure [#project-structure]

```
require-cjs-example/
├── src/
│   ├── index.ts
│   ├── parser.ts
│   └── utils.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Source Files [#source-files]

**src/index.ts**

```typescript
import { parseCode } from './parser'
import { processUtils } from './utils'

export function main() {
  const result = parseCode('const x = 1')
  const processed = processUtils(result)
  return processed
}
```

**src/parser.ts**

```typescript
// These packages are CJS-only and benefit from transformation
import { parse } from '@babel/parser'
import { transpile } from 'typescript'

export function parseCode(code: string) {
  // Parse with Babel
  const ast = parse(code, {
    sourceType: 'module',
    plugins: ['typescript']
  })

  // Transpile with TypeScript
  const js = transpile(code, {
    target: 'ES2020',
    module: 'ESNext'
  })

  return { ast, js }
}
```

**src/utils.ts**

```typescript
// Node.js built-ins also benefit from transformation
import { readFileSync } from 'fs'
import { join, dirname } from 'path'
import { fileURLToPath } from 'url'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)

export function processUtils(data: any) {
  // Read a config file
  const configPath = join(__dirname, 'config.json')
  const config = JSON.parse(readFileSync(configPath, 'utf8'))

  return {
    ...data,
    config
  }
}
```

### Configuration [#configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  emitESM: true,
  rollup: {
    requireCJS: {
      builtinNodeModules: true
    }
  }
})
```

**package.json**

```json
{
  "name": "@myorg/require-cjs-example",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "dependencies": {
    "@babel/parser": "^7.23.0",
    "typescript": "^5.3.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@types/node": "^20.0.0"
  }
}
```

### Output [#output]

After building, the ESM output (`dist/index.js`) will be transformed:

```javascript
// dist/index.js (transformed)
import { createRequire as __cjs_createRequire } from "node:module";
const __cjs_require = __cjs_createRequire(import.meta.url);

// Runtime capability helpers
const __cjs_getBuiltinModule = (module) => {
    // Check if we're in Node.js and version supports getBuiltinModule
    if (typeof process !== "undefined" && process.versions?.node) {
        const [major, minor] = process.versions.node.split(".").map(Number);
        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
            return process.getBuiltinModule(module);
        }
    }
    // Fallback to createRequire
    return __cjs_require(module);
};

const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;

const { parse } = __cjs_require("@babel/parser")
const { transpile } = __cjs_require("typescript")
const { readFileSync } = __cjs_getBuiltinModule("fs");
const { join, dirname } = __cjs_getBuiltinModule("path");
const { fileURLToPath } = __cjs_getBuiltinModule("url");
const { cwd } = __cjs_getProcess;

// ... rest of the transformed code
```

## Advanced Configuration [#advanced-configuration]

### Custom Package Detection [#custom-package-detection]

```typescript
export default defineConfig({
  transformer,
  emitESM: true,
  rollup: {
    requireCJS: {
      builtinNodeModules: true,
      additionalPackages: ['my-cjs-package'],
      exclude: ['some-package']
    }
  }
})
```

### Selective Transformation [#selective-transformation]

```typescript
export default defineConfig({
  transformer,
  emitESM: true,
  rollup: {
    requireCJS: {
      // Only transform specific packages
      builtinNodeModules: false,
      additionalPackages: ['typescript', '@babel/parser']
    }
  }
})
```

## Performance Comparison [#performance-comparison]

### Without the Plugin [#without-the-plugin]

```typescript
// src/parser.ts - Original ESM imports
import { parse } from '@babel/parser'
import { transpile } from 'typescript'

export function parseCode(code: string) {
  return { ast: parse(code), js: transpile(code) }
}
```

**Startup time**: \~50ms (includes cjs-module-lexer analysis)

### With the Plugin [#with-the-plugin]

```typescript
// dist/parser.js - Transformed to require calls
const { parse } = require('@babel/parser')
const { transpile } = require('typescript')

export function parseCode(code) {
  return { ast: parse(code), js: transpile(code) }
}
```

**Startup time**: \~30ms (skips cjs-module-lexer analysis)

## Use Cases [#use-cases]

### CLI Tools [#cli-tools]

CLI tools that use CJS-only packages benefit significantly:

```typescript
// src/cli.ts
import { Command } from 'commander'
import { readFileSync } from 'fs'
import { parse } from '@babel/parser'
import { transpile } from 'typescript'

const program = new Command()
program
  .command('analyze <file>')
  .action((file) => {
    const code = readFileSync(file, 'utf8')
    const ast = parse(code)
    const js = transpile(code)
    console.log('Analysis complete')
  })

program.parse()
```

### Build Tools [#build-tools]

Build tools and bundlers that process many files:

```typescript
// src/bundler.ts
import { parse } from '@babel/parser'
import { transpile } from 'typescript'
import { transform } from 'swc'
import { build } from 'esbuild'

export class Bundler {
  async processFile(file: string) {
    const code = await fs.readFile(file, 'utf8')

    // Multiple CJS-only transformers
    const ast = parse(code)
    const ts = transpile(code)
    const swc = transform(code)
    const esbuild = await build({ ... })

    return { ast, ts, swc, esbuild }
  }
}
```

### Development Servers [#development-servers]

Development servers that restart frequently:

```typescript
// src/dev-server.ts
import express from 'express'
import { transpile } from 'typescript'
import { parse } from '@babel/parser'

const app = express()

app.post('/transform', (req, res) => {
  const { code } = req.body
  const ast = parse(code)
  const js = transpile(code)
  res.json({ ast, js })
})

app.listen(3000)
```

## Migration Examples [#migration-examples]

### From Manual require() Calls [#from-manual-require-calls]

```typescript
// Before - manual require calls
const { parse } = require('@babel/parser')

export function transform(code) {
  return parse(code)
}

// After - ESM imports (plugin transforms automatically)
import { parse } from '@babel/parser'

export function transform(code) {
  return parse(code)
}
```

### From Dynamic Imports [#from-dynamic-imports]

```typescript
// Before - dynamic imports
export async function transform(code) {
  const { parse } = await import('@babel/parser')
  return parse(code)
}

// After - static imports (better performance)
import { parse } from '@babel/parser'

export function transform(code) {
  return parse(code)
}
```

## Testing the Transformation [#testing-the-transformation]

Create a test to verify the transformation works:

**test/transformation.test.js**

```javascript
import { readFileSync } from 'fs'
import { expect, test } from 'vitest'

test('transforms CJS imports correctly', () => {
  const esmOutput = readFileSync('dist/index.js', 'utf8')

  // Should contain require calls for CJS packages
  expect(esmOutput).toContain('require("@babel/parser")')
  expect(esmOutput).toContain('require("typescript")')

  // Should contain runtime capability helpers
  expect(esmOutput).toContain('const __cjs_getBuiltinModule = (module) => {')
  expect(esmOutput).toContain('const __cjs_getProcess = (() => {')
  expect(esmOutput).toContain('__cjs_getBuiltinModule("fs")')
  expect(esmOutput).toContain('__cjs_getProcess')

  // Should NOT contain original ESM imports
  expect(esmOutput).not.toContain('import { parse } from "@babel/parser"')
})
```

## Best Practices [#best-practices]

### When to Use [#when-to-use]

* ✅ CLI tools with many CJS dependencies
* ✅ Build tools and bundlers
* ✅ Applications with measurable startup time issues
* ✅ Development servers that restart frequently

### When NOT to Use [#when-not-to-use]

* ❌ Simple applications with few CJS imports
* ❌ Libraries that will be consumed by others
* ❌ When performance gain is negligible
* ❌ If you prefer simpler build configuration

### Performance Monitoring [#performance-monitoring]

Monitor the impact of the plugin:

```typescript
// Measure startup time
const start = Date.now()
import('./dist/index.js')
const end = Date.now()
console.log(`Startup time: ${end - start}ms`)
```

### Alternative Approaches [#alternative-approaches]

1. **Use ESM-compatible packages** when available
2. **Bundle with esbuild/swc** for better optimization
3. **Use dynamic imports** strategically
4. **Consider dual package publishing** for your own libraries

## Troubleshooting [#troubleshooting]

### Plugin Not Transforming [#plugin-not-transforming]

1. **Check `emitESM`**: Must be `true` for the plugin to activate
2. **Verify package detection**: Only CJS-only packages are transformed
3. **Check configuration**: Ensure `requireCJS` options are set correctly

### Build Errors [#build-errors]

1. **CommonJS compatibility**: Ensure target environment supports `require()`
2. **Module resolution**: Verify all packages are installed
3. **TypeScript issues**: Update import statements if needed

### Performance Issues [#performance-issues]

1. **Too many transformations**: Use `exclude` to skip unnecessary packages
2. **Bundle size increase**: Consider tree-shaking implications
3. **Debug overhead**: Disable in production if issues arise

## Related Examples [#related-examples]

* [Basic TypeScript Library](/docs/packages/packem/examples/basic-typescript) - Simple library setup
* [CLI Tool](/docs/packages/packem/examples/cli-tool) - Command-line application
* [Dual Package](/docs/packages/packem/examples/dual-package) - ESM and CJS compatibility


# Shared Modules (/docs/packages/packem/examples/advanced/shared-modules)



# Shared Modules [#shared-modules]

Sometimes you need to share code between bundles without exposing it as its own entry or export. Packem's shared module convention bundles such code into a single shared chunk that the different entry bundles reference.

## Overview [#overview]

Name a source file using the convention `[name].[layer]-runtime.[ext]` and Packem will pull it into a separate **layer** chunk that matches the layer in the file name. That chunk is built once and referenced by every entry that imports it.

This is especially valuable across multiple runtime bundles (for example `default` and `react-server`) where a module must keep a single shared instance across runtimes.

:::note
Shared Modules is an experimental feature. The layer in the file name (`shared` in `util.shared-runtime.js`) determines the shared chunk it lands in.
:::

## Project Structure [#project-structure]

```
shared-modules-example/
├── src/
│   ├── index.ts
│   ├── lite.ts
│   └── util.shared-runtime.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Source Files [#source-files]

**src/util.shared-runtime.ts**

```typescript
export function sharedUtil(): string {
  return 'shared'
}
```

**src/index.ts**

```typescript
import { sharedUtil as sharedUtility } from './util.shared-runtime'

export function full() {
  return sharedUtility()
}
```

**src/lite.ts**

```typescript
import { sharedUtil as sharedUtility } from './util.shared-runtime'

export function lite() {
  return sharedUtility()
}
```

Packem bundles `util.shared-runtime` into a separate `shared` layer chunk, which both `index` and `lite` reference instead of each inlining their own copy.

## Sharing Across Runtimes [#sharing-across-runtimes]

The same convention keeps a single instance of a module across different runtime bundles, such as `default` and `react-server`:

**src/app-context.shared-runtime.ts**

```typescript
'use client'

import { createContext } from 'react'

export const AppContext = createContext(null)
```

**src/index.ts**

```typescript
import { AppContext } from './app-context.shared-runtime'
```

**src/index.react-server.ts**

```typescript
import { AppContext } from './app-context.shared-runtime'
```

`app-context.shared-runtime` is bundled into one chunk with a single instance and is shared between the `default` and `react-server` bundles.

## Configuration [#configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

**package.json**

```json
{
  "name": "@myorg/shared-modules",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "import": "./dist/index.mjs"
    },
    "./lite": {
      "import": "./dist/lite.mjs"
    }
  },
  "scripts": {
    "build": "packem build"
  },
  "devDependencies": {
    "@visulima/packem": "^2"
  }
}
```

## Notes [#notes]

* The shared chunk is created only when a file matches the `[name].[layer]-runtime.[ext]` convention.
* Pair this with [Multi-Runtime](/docs/packages/packem/examples/advanced/multi-runtime) when the shared module must keep one instance across `react-server`/`edge-light` bundles.
* For lazy on-demand splitting instead of always-shared chunks, use [Dynamic Imports](/docs/packages/packem/examples/advanced/dynamic-imports).

## Related [#related]

* [Multi-Runtime](/docs/packages/packem/examples/advanced/multi-runtime)
* [Dynamic Imports](/docs/packages/packem/examples/advanced/dynamic-imports)
* [Multiple Exports](/docs/packages/packem/examples/multi-exports)


# WebAssembly (/docs/packages/packem/examples/advanced/webassembly)



# WebAssembly [#webassembly]

Packem can import and bundle `.wasm` modules. WebAssembly support is provided through the `rollup.wasm` option, which is backed by `@rollup/plugin-wasm` and accepts its full option set.

## Overview [#overview]

When enabled, `.wasm` files imported from your source are inlined or copied as part of the build, letting you instantiate compiled WebAssembly directly from JavaScript/TypeScript.

:::note
WebAssembly modules are a supported feature of Packem (see the feature list in the package README). Support is configured via `rollup.wasm`.
:::

## Project Structure [#project-structure]

```
wasm-example/
├── src/
│   ├── index.ts
│   └── add.wasm
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Source Files [#source-files]

**src/index.ts**

```typescript
// Import the compiled WebAssembly module
import addModule from './add.wasm'

export async function add(a: number, b: number): Promise<number> {
  const instance = await addModule()
  return (instance.exports.add as (a: number, b: number) => number)(a, b)
}
```

## Configuration [#configuration]

Enable WebAssembly handling through the `rollup.wasm` option. Passing an empty object turns it on with defaults; you can pass any `@rollup/plugin-wasm` option (such as `sync` or `maxFileSize`).

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true,
  rollup: {
    // Enable .wasm bundling (backed by @rollup/plugin-wasm)
    wasm: {}
  }
})
```

### Inlining Smaller Modules [#inlining-smaller-modules]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    wasm: {
      // Inline modules under this size; emit larger ones as separate files
      maxFileSize: 10_000,
      // Synchronously instantiate (Node-only, no async wrapper)
      sync: ['src/add.wasm']
    }
  }
})
```

To disable WebAssembly handling explicitly, set `rollup.wasm` to `false`.

**package.json**

```json
{
  "name": "@myorg/wasm-example",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs"
    }
  },
  "scripts": {
    "build": "packem build"
  },
  "devDependencies": {
    "@visulima/packem": "^2"
  }
}
```

## Build Output [#build-output]

```bash
$ packem build

dist/index.mjs        # JS entry, instantiates the wasm module
dist/index.d.ts       # type declarations
```

## Notes [#notes]

* `rollup.wasm` accepts the full `RollupWasmOptions` shape from `@rollup/plugin-wasm`; the most common options are `sync`, `maxFileSize`, `targetEnv`, and `publicPath`.
* Small modules can be inlined as base64 (via `maxFileSize`) to avoid a separate fetch; larger ones are emitted as standalone `.wasm` files.
* Combine with [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis) to see how WebAssembly assets contribute to your output size.

## Related [#related]

* [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis)
* [@visulima/packem-rollup API](/docs/packages/packem/api/packem-rollup)
* [Plugins](/docs/packages/packem/options/plugins)


# JavaScript Package (/docs/packages/packem/examples/basic-javascript)



# JavaScript Package [#javascript-package]

Build a modern, ESM-only JavaScript package with Packem. There is no entry list to maintain: Packem infers the build entries from your `package.json`, and `packem init` scaffolds the transformer and config for you, so the setup is effectively zero-config.

## Overview [#overview]

This example demonstrates:

* A plain JavaScript (no TypeScript) package
* ESM-only output
* Entry inference from `package.json#exports`
* Generating the config with `packem init`

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   └── index.js
├── package.json
└── packem.config.ts
```

### Source File [#source-file]

**src/index.js**

```javascript
/**
 * Slugify a string into a URL-friendly form.
 */
export function slugify(input) {
  return input
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '')
}

/**
 * Truncate a string to a maximum length.
 */
export function truncate(input, max = 80) {
  return input.length > max ? `${input.slice(0, max - 1)}…` : input
}
```

## Configuration [#configuration]

### package.json [#packagejson]

With `"type": "module"` and a single `exports` entry, Packem builds one ESM bundle.
No `main`/`require` condition means no CommonJS output is produced.

```json
{
  "name": "@myorg/my-package",
  "version": "1.0.0",
  "description": "A modern JavaScript package",
  "type": "module",
  "files": [
    "dist"
  ],
  "module": "./dist/index.mjs",
  "exports": {
    ".": "./dist/index.mjs"
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "esbuild": "^0.25.0"
  }
}
```

### Generating the config [#generating-the-config]

Run the interactive setup to pick a bundler and transformer and write the config file:

```bash
npx packem init
```

This scaffolds a minimal `packem.config.ts`:

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

<Callout type="info">
  Packem reads the entries straight from `package.json`. Add another subpath to `exports` and it is picked up automatically — no config change required.
</Callout>

## Building [#building]

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
└── index.mjs        # ESM entry
```

## Usage [#usage]

```javascript
import { slugify, truncate } from '@myorg/my-package'

slugify('Hello World!')          // "hello-world"
truncate('a very long sentence', 10) // "a very lo…"
```

## Next Steps [#next-steps]

* Add CommonJS output by introducing a `require` condition — see [Dual Package](/docs/packages/packem/examples/dual-package)
* Add a TypeScript entry — see [TypeScript Library](/docs/packages/packem/examples/basic-typescript)
* Pick a different [transformer](/docs/packages/packem/guide/transformers)


# Basic TypeScript Library (/docs/packages/packem/examples/basic-library)



# Basic TypeScript Library [#basic-typescript-library]

Learn how to create a TypeScript utility library with Packem, including TypeScript declarations, ESM/CJS dual support, and proper package.json configuration.

## Overview [#overview]

This example demonstrates:

* TypeScript library setup
* Automatic entry point detection
* Dual package (ESM + CJS) output
* TypeScript declaration generation
* Tree-shakable exports

## Project Setup [#project-setup]

Let's create a simple utility library with common functions:

### Directory Structure [#directory-structure]

```
my-utils/
├── src/
│   ├── index.ts
│   ├── math.ts
│   ├── string.ts
│   └── array.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Source Files [#source-files]

**src/math.ts**

```typescript
/**
 * Add two numbers
 */
export function add(a: number, b: number): number {
  return a + b
}

/**
 * Subtract two numbers
 */
export function subtract(a: number, b: number): number {
  return a - b
}

/**
 * Multiply two numbers
 */
export function multiply(a: number, b: number): number {
  return a * b
}

/**
 * Divide two numbers
 */
export function divide(a: number, b: number): number {
  if (b === 0) {
    throw new Error('Division by zero')
  }
  return a / b
}
```

**src/string.ts**

```typescript
/**
 * Capitalize the first letter of a string
 */
export function capitalize(str: string): string {
  if (!str) return str
  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()
}

/**
 * Convert string to camelCase
 */
export function camelCase(str: string): string {
  return str
    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => {
      return index === 0 ? word.toLowerCase() : word.toUpperCase()
    })
    .replace(/\s+/g, '')
}

/**
 * Convert string to kebab-case
 */
export function kebabCase(str: string): string {
  return str
    .replace(/([a-z])([A-Z])/g, '$1-$2')
    .replace(/\s+/g, '-')
    .toLowerCase()
}
```

**src/array.ts**

```typescript
/**
 * Remove duplicates from an array
 */
export function unique<T>(array: T[]): T[] {
  return [...new Set(array)]
}

/**
 * Chunk an array into smaller arrays
 */
export function chunk<T>(array: T[], size: number): T[][] {
  const chunks: T[][] = []
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size))
  }
  return chunks
}

/**
 * Flatten a nested array
 */
export function flatten<T>(array: (T | T[])[]): T[] {
  return array.reduce<T[]>((acc, val) => {
    return acc.concat(Array.isArray(val) ? flatten(val) : val)
  }, [])
}
```

**src/index.ts**

```typescript
// Math utilities
export { add, subtract, multiply, divide } from './math'

// String utilities  
export { capitalize, camelCase, kebabCase } from './string'

// Array utilities
export { unique, chunk, flatten } from './array'

// Default export with all utilities
export default {
  // Math
  add,
  subtract, 
  multiply,
  divide,
  // String
  capitalize,
  camelCase,
  kebabCase,
  // Array
  unique,
  chunk,
  flatten
}
```

## Configuration [#configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/utils",
  "version": "1.0.0",
  "description": "TypeScript utility library",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js", 
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./math": {
      "types": "./dist/math.d.ts",
      "import": "./dist/math.js", 
      "require": "./dist/math.cjs"
    },
    "./string": {
      "types": "./dist/string.d.ts",
      "import": "./dist/string.js",
      "require": "./dist/string.cjs"
    },
    "./array": {
      "types": "./dist/array.d.ts", 
      "import": "./dist/array.js",
      "require": "./dist/array.cjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch",
    "clean": "rm -rf dist"
  },
  "keywords": ["utilities", "typescript", "library"],
  "author": "Your Name",
  "license": "MIT",
  "devDependencies": {
    "@visulima/packem": "^2",
    "typescript": "^5.3.0"
  }
}
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext", 
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "allowJs": false,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### Packem Configuration [#packem-configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  rollup: {
    watch: {
      include: 'src/**'
    }
  }
})
```

## Building [#building]

Build the library:

```bash
npm run build
```

### Output Structure [#output-structure]

After building, you'll have:

```
dist/
├── index.js          # ESM main entry
├── index.cjs         # CJS main entry  
├── index.d.ts        # TypeScript declarations
├── math.js           # ESM math utilities
├── math.cjs          # CJS math utilities
├── math.d.ts         # Math type declarations
├── string.js         # ESM string utilities
├── string.cjs        # CJS string utilities
├── string.d.ts       # String type declarations
├── array.js          # ESM array utilities
├── array.cjs         # CJS array utilities
└── array.d.ts        # Array type declarations
```

## Usage Examples [#usage-examples]

### ESM Import (Recommended) [#esm-import-recommended]

```typescript
// Full import
import utils from '@myorg/utils'
console.log(utils.add(1, 2)) // 3

// Named imports 
import { add, capitalize, unique } from '@myorg/utils'
console.log(add(1, 2)) // 3
console.log(capitalize('hello')) // Hello
console.log(unique([1, 1, 2, 3])) // [1, 2, 3]

// Subpath imports (tree-shakable)
import { add, multiply } from '@myorg/utils/math'
import { camelCase } from '@myorg/utils/string'
import { chunk } from '@myorg/utils/array'
```

### CJS Require [#cjs-require]

```javascript
// Full require
const utils = require('@myorg/utils')
console.log(utils.add(1, 2)) // 3

// Destructured require
const { add, capitalize, unique } = require('@myorg/utils')

// Subpath requires  
const { add, multiply } = require('@myorg/utils/math')
```

## Testing the Library [#testing-the-library]

Create a simple test to verify everything works:

**test.mjs**

```javascript
import { add, capitalize, unique } from './dist/index.js'

console.log('Testing add:', add(2, 3)) // 5
console.log('Testing capitalize:', capitalize('hello world')) // Hello world  
console.log('Testing unique:', unique([1, 1, 2, 3, 3])) // [1, 2, 3]
console.log('✅ All tests passed!')
```

Run the test:

```bash
node test.mjs
```

## Key Features [#key-features]

### Tree Shaking [#tree-shaking]

Users can import only what they need:

```typescript
// Only imports the add function
import { add } from '@myorg/utils/math'

// Bundles only include the add function, not the entire library
```

### Type Safety [#type-safety]

Full TypeScript support with proper declarations:

```typescript
import { add } from '@myorg/utils'

add(1, 2)      // ✅ Valid
add('1', '2')  // ❌ Type error
add(1)         // ❌ Type error (missing parameter)
```

### Dual Package Support [#dual-package-support]

Works in both ESM and CJS environments:

```javascript
// ESM
import { add } from '@myorg/utils'

// CJS
const { add } = require('@myorg/utils')
```

## Publishing [#publishing]

Before publishing to npm:

1. **Build the library**:
   ```bash
   npm run build
   ```

2. **Test the output**:
   ```bash
   node test.mjs
   ```

3. **Publish to npm**:
   ```bash
   npm publish
   ```

<Callout type="info">
  Make sure to test your library in both ESM and CJS environments before publishing.
</Callout>

## Next Steps [#next-steps]

* Add unit tests with Jest or Vitest
* Set up CI/CD with GitHub Actions
* Add JSDoc comments for better documentation
* Consider adding a bundled UMD version for browsers
* Set up automated changelog generation

This basic library setup provides a solid foundation for most TypeScript utility libraries with proper tooling and modern JavaScript standards.


# TypeScript Library (/docs/packages/packem/examples/basic-typescript)



# TypeScript Library [#typescript-library]

Build a small TypeScript utility library with Packem that ships both ESM and CommonJS output plus TypeScript declarations. Packem reads your `package.json#exports` to figure out which entries to build, so there is no entry list to maintain by hand.

## Overview [#overview]

This example demonstrates:

* A TypeScript library with a single entry point
* Dual ESM + CJS output driven by `package.json#exports`
* Automatic `.d.ts` declaration generation
* Tree-shakable named exports

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-library/
├── src/
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Source Files [#source-files]

**src/index.ts**

```typescript
export interface GreetOptions {
  shout?: boolean
}

/**
 * Greet someone by name.
 */
export function greet(name: string, options: GreetOptions = {}): string {
  const message = `Hello, ${name}!`
  return options.shout ? message.toUpperCase() : message
}

/**
 * Sum a list of numbers.
 */
export function sum(values: number[]): number {
  return values.reduce((total, value) => total + value, 0)
}
```

## Configuration [#configuration]

### package.json [#packagejson]

Packem infers the entry points from the `exports` field. The `import`/`require`/`types`
conditions tell Packem which formats to emit.

```json
{
  "name": "@myorg/my-library",
  "version": "1.0.0",
  "description": "A simple TypeScript library",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "esbuild": "^0.25.0",
    "typescript": "^5.3.0"
  }
}
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### Packem Configuration [#packem-configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

<Callout type="info">
  Declarations are auto-detected: because `package.json` defines a `types` field, Packem generates `.d.ts` (plus `.d.mts`/`.d.cts`) without any extra option.
</Callout>

## Building [#building]

Run the build:

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── index.mjs        # ESM entry
├── index.cjs        # CJS entry
├── index.d.mts      # ESM declarations
├── index.d.cts      # CJS declarations
└── index.d.ts       # Declarations
```

## Usage [#usage]

### ESM [#esm]

```typescript
import { greet, sum } from '@myorg/my-library'

greet('world')              // "Hello, world!"
greet('world', { shout: true }) // "HELLO, WORLD!"
sum([1, 2, 3])              // 6
```

### CommonJS [#commonjs]

```javascript
const { greet, sum } = require('@myorg/my-library')

greet('world') // "Hello, world!"
```

## Next Steps [#next-steps]

* Add more entry points with [Multiple Exports](/docs/packages/packem/examples/multi-exports)
* Switch to another [transformer](/docs/packages/packem/guide/transformers) such as swc or oxc
* Configure declaration output with [Declaration Files](/docs/packages/packem/options/declaration-files)


# CLI Tool (/docs/packages/packem/examples/cli-tool)



# CLI Tool [#cli-tool]

Build a command-line tool with Packem. Any file referenced from `package.json#bin` is treated as an executable entry: Packem prepends a `#!/usr/bin/env node` hashbang automatically and marks the output file as executable (`chmod 0o755`), so the binary is ready to run after a build.

## Overview [#overview]

This example demonstrates:

* An executable entry inferred from `package.json#bin`
* Automatic hashbang (`#!/usr/bin/env node`) insertion
* The output file being made executable automatically
* Shipping a library entry alongside the CLI

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-cli/
├── src/
│   ├── cli.ts
│   └── index.ts
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

You do not need to write the hashbang yourself — Packem adds it during the build.

**src/cli.ts**

```typescript
import { run } from './index'

const [, , ...args] = process.argv

run(args)
```

**src/index.ts**

```typescript
/**
 * Run the CLI with the given arguments.
 */
export function run(args: string[]): void {
  const name = args[0] ?? 'world'
  console.log(`Hello, ${name}!`)
}
```

## Configuration [#configuration]

### package.json [#packagejson]

The `bin` field points at the built CLI file. Packem detects it and emits an
executable entry for it. The `exports` field also exposes the programmatic API.

```json
{
  "name": "@myorg/my-cli",
  "version": "1.0.0",
  "description": "A command-line tool",
  "type": "module",
  "files": [
    "dist"
  ],
  "bin": {
    "my-cli": "./dist/cli.mjs"
  },
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      }
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "esbuild": "^0.25.0",
    "typescript": "^5.3.0"
  }
}
```

<Callout type="info">
  `bin` can be a string (a single binary named after the package) or an object mapping command names to files. Each referenced file becomes its own executable entry.
</Callout>

### Packem Configuration [#packem-configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

## Building [#building]

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── cli.mjs          # executable, starts with #!/usr/bin/env node
├── index.mjs        # ESM library entry
└── index.d.mts      # declarations
```

The first line of `dist/cli.mjs` is the auto-inserted hashbang:

```javascript
#!/usr/bin/env node
// ...your bundled CLI code
```

## Running the CLI [#running-the-cli]

After building, the binary is executable directly:

```bash
./dist/cli.mjs Ada
# Hello, Ada!
```

Or via the linked command name once installed:

```bash
my-cli Ada
# Hello, Ada!
```

You can also import the API in another project:

```typescript
import { run } from '@myorg/my-cli'

run(['Grace'])
```

## Next Steps [#next-steps]

* Add multiple commands by listing more files under `bin`
* Expose extra subpaths — see [Multiple Exports](/docs/packages/packem/examples/multi-exports)
* Bundle into a single standalone binary with the `exe` option


# Bundle Size Limits (/docs/packages/packem/examples/configuration/bundle-limits)



# Bundle Size Limits [#bundle-size-limits]

This example shows how to enforce bundle size budgets with Packem's `validation.bundleLimit` option. You can set a single limit for the whole build, per-file (or per-glob) limits, and decide whether exceeding a limit should fail the build or only warn.

## Overview [#overview]

This example demonstrates:

* Setting a total bundle size budget
* Setting per-file and per-glob size limits
* Mixing byte numbers and human-readable strings (e.g. `"1MB"`)
* Controlling whether limit violations fail the build (`allowFail`)

## Configuration [#configuration]

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
    transformer,
    validation: {
        bundleLimit: {
            // Total size budget across all build entries.
            // Accepts a number of bytes or a string with a unit.
            limit: "1MB",

            // Per-file / per-glob limits. The key is matched against the
            // output path (relative to outDir) or as a glob pattern.
            limits: {
                "**/*.mjs": "500KB",
                "index.cjs": 1048576, // 1MB in bytes
            },

            // When true, the build still succeeds and a warning is emitted
            // instead of failing when a limit is exceeded.
            // @default false
            allowFail: false,
        },
    },
})
```

## Size units [#size-units]

The `limit` and each value in `limits` accept either:

* A number of bytes, e.g. `1048576`
* A string with a unit suffix: `"B"`, `"KB"`, `"MB"`, `"GB"`, or `"TB"`, e.g. `"500KB"`, `"1MB"`

```typescript
bundleLimit: {
    limit: 1048576,   // exact byte count
    // or
    limit: "1MB",     // parsed to bytes for you
}
```

## How `limits` keys are matched [#how-limits-keys-are-matched]

Each key in `limits` is matched against your build output. Packem first strips a leading `outDir` segment, then checks whether an output entry's path **ends with** the key, falling back to glob matching:

* `"index.cjs"` matches the emitted `index.cjs` entry
* `"**/*.mjs"` matches every emitted `.mjs` file via glob

If a key matches no output entry, it is skipped (a debug message is logged) rather than failing the build.

## Failing vs. warning [#failing-vs-warning]

By default a violation is reported and the build is treated as failed. Set `allowFail: true` to downgrade violations to warnings so the build still completes:

```typescript
validation: {
    bundleLimit: {
        limit: "250KB",
        allowFail: true, // warn, but do not fail the build
    },
}
```

## Running the build [#running-the-build]

```bash
packem build
```

If the total output or a matched file exceeds its limit, Packem reports the actual size against the limit, for example:

```text
Total file size exceeds the limit: 1.4 MB / 1.00 MB
File size exceeds the limit: dist/index.cjs (1.2 MB / 1.00 MB)
```

## Related Examples [#related-examples]

* [Package.json Validation](/docs/packages/packem/examples/configuration/package-validation) - Complete package.json validation setup
* [Dependency Validation](/docs/packages/packem/examples/configuration/dependency-validation) - Validate dependencies and detect issues
* [Extra Conditions](/docs/packages/packem/examples/configuration/extra-conditions) - Configure custom export conditions


# Dependency Validation (/docs/packages/packem/examples/configuration/dependency-validation)



# Dependency Validation [#dependency-validation]

Packem can warn you about two common dependency problems: packages that are **shamefully hoisted** (relied on transitively but not declared) and packages **listed in `package.json` but never imported**. This example shows the `validation.dependencies` block and how to exclude false positives.

## Overview [#overview]

This example demonstrates:

* Enabling hoisted and unused dependency checks
* Excluding specific packages from each check
* How framework presets configure these excludes
* Detecting packages that get bundled more than once

## Configuration [#configuration]

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
    transformer,
    validation: {
        dependencies: {
            // Warn when dependencies are used but not declared
            // (shamefully hoisted). Provide packages to ignore.
            hoisted: {
                exclude: [],
            },

            // Warn when dependencies are declared in package.json
            // but never imported. Exclude packages that are used
            // indirectly (e.g. by a runtime/JSX import).
            unused: {
                exclude: ["react", "react-dom"],
            },
        },
    },
})
```

## How it works [#how-it-works]

* **Hoisted check** — if a package ends up in your build without being declared in `package.json`, Packem reports: `These dependencies are shamefully hoisted: ...`.
* **Unused check** — every key in `dependencies` that is never imported by your source is reported: `These dependencies are listed in package.json but not used: ...`. Anything listed in `unused.exclude` is removed from that report.

## Excluding packages [#excluding-packages]

Each check takes an `exclude` array of package names. This is useful for dependencies that are present for runtime reasons but aren't statically imported — for example, `react` / `react-dom` as JSX runtimes:

```typescript
validation: {
    dependencies: {
        hoisted: { exclude: [] },
        unused: { exclude: ["react", "react-dom"] },
    },
}
```

The React, Preact, Solid, Svelte, and Vue presets configure these excludes for you so peer runtimes aren't flagged as unused.

## Disabling the checks [#disabling-the-checks]

Set a check to `false` to disable just that one, or set `dependencies` to `false` to disable both:

```typescript
// Disable only the unused check
validation: {
    dependencies: {
        hoisted: { exclude: [] },
        unused: false,
    },
}

// Disable both dependency checks
validation: {
    dependencies: false,
}
```

## Detecting duplicated packages [#detecting-duplicated-packages]

A related check finds packages that get **bundled more than once** (for example, two different versions resolved through your dependency tree). It is enabled by default and configured separately under `rollup.detectDuplicated`:

```typescript
export default defineConfig({
    transformer,
    rollup: {
        detectDuplicated: {
            // Skip specific packages/versions. Use "*" to ignore all versions.
            ignore: {
                lodash: ["*"],
            },
            // Fail the build when duplicates are found.
            throwErrorWhenDuplicated: false,
        },
    },
})
```

See the [Duplicate packages](/docs/packages/packem/options/detect-duplicated) option for the full list of `detectDuplicated` settings.

## Related Examples [#related-examples]

* [Package.json Validation](/docs/packages/packem/examples/configuration/package-validation) - Complete package.json validation setup
* [Bundle Size Limits](/docs/packages/packem/examples/configuration/bundle-limits) - Set up bundle size validation and limits
* [Duplicate packages](/docs/packages/packem/options/detect-duplicated) - Detect dependencies bundled more than once


# Extra Conditions (/docs/packages/packem/examples/configuration/extra-conditions)



# Extra Conditions Example [#extra-conditions-example]

This example demonstrates how to use the `extraConditions` option in package.json validation to allow custom export conditions.

## Configuration [#configuration]

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
    transformer,
    entries: [
        {
            input: "src/index.ts",
        },
    ],
    validation: {
        packageJson: {
            extraConditions: ["custom-bundler", "my-framework", "special-env"]
        }
    }
})
```

## Package.json Example [#packagejson-example]

```json
{
    "name": "my-package",
    "exports": {
        ".": {
            "custom-bundler": "./dist/custom.js",
            "my-framework": "./dist/framework.js",
            "special-env": "./dist/special.js",
            "import": "./dist/index.mjs",
            "require": "./dist/index.cjs",
            "default": "./dist/index.js"
        }
    }
}
```

## What this does [#what-this-does]

* Without `extraConditions`: Packem would warn about unknown conditions `custom-bundler`, `my-framework`, and `special-env`
* With `extraConditions`: These custom conditions are recognized as valid and no warnings are generated
* Unknown conditions not listed in `extraConditions` will still generate warnings

## Use Cases [#use-cases]

* Custom bundler-specific conditions
* Framework-specific export conditions
* Environment-specific conditions
* Tool-specific conditions
* Any custom export condition your package needs to support

## Standard Conditions [#standard-conditions]

Packem already recognizes these standard and community conditions without needing to add them to `extraConditions`:

### Standard Node.js Conditions [#standard-nodejs-conditions]

* `import` - ES modules
* `require` - CommonJS
* `node` - Node.js environment
* `default` - Fallback condition

### Community Conditions [#community-conditions]

* `browser` - Browser environment
* `development` - Development builds
* `production` - Production builds
* `types` - TypeScript declarations
* `react-native` - React Native platform
* `react-server` - React Server Components
* `edge-light` - Edge runtime environments

## Related Examples [#related-examples]

* [Package.json Validation](/docs/packages/packem/examples/configuration/package-validation) - Complete package.json validation setup
* [Bundle Size Limits](/docs/packages/packem/examples/configuration/bundle-limits) - Configure bundle size validation
* [Multi-Runtime Exports](/docs/packages/packem/examples/advanced/multi-runtime) - Target multiple runtimes with conditional exports


# Package.json Validation (/docs/packages/packem/examples/configuration/package-validation)



# Package.json Validation [#packagejson-validation]

Packem validates your `package.json` to make sure the fields needed to publish a working package are configured correctly. This example shows the full `validation.packageJson` shape and what each toggle controls.

## Overview [#overview]

This example demonstrates:

* Enabling validation for individual `package.json` fields
* Allowing custom export conditions and extra export extensions
* Turning specific checks on or off

## Configuration [#configuration]

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
    transformer,
    validation: {
        packageJson: {
            // Validate individual fields
            name: true,
            main: true,
            module: true,
            types: true,
            typesVersions: true,
            exports: true,
            files: true,
            bin: true,
            dependencies: true,
            engines: true,
            sideEffects: true,

            // Allow custom export conditions without warnings
            extraConditions: ["custom-bundler", "my-framework"],

            // Allow extra file extensions in the exports field
            allowedExportExtensions: [".css", ".wasm"],
        },
    },
})
```

## Available checks [#available-checks]

Every field below is an individual boolean toggle under `validation.packageJson`:

| Option                    | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| `name`                    | Validate the `name` field                                     |
| `main`                    | Validate the `main` field                                     |
| `module`                  | Validate the `module` field                                   |
| `types`                   | Validate the `types` field                                    |
| `typesVersions`           | Validate the `typesVersions` field                            |
| `exports`                 | Validate the `exports` field                                  |
| `files`                   | Validate the `files` field                                    |
| `bin`                     | Validate the `bin` field                                      |
| `dependencies`            | Validate dependencies                                         |
| `engines`                 | Validate the `engines` field                                  |
| `sideEffects`             | Validate the `sideEffects` field                              |
| `extraConditions`         | `string[]` of extra export conditions to treat as valid       |
| `allowedExportExtensions` | `string[]` of additional file extensions allowed in `exports` |

## What this does [#what-this-does]

* Packem checks that the enabled fields exist and point at files the build actually produces.
* `exports` validation flags unknown export conditions. Add custom ones to `extraConditions` so they don't warn (see the [Extra Conditions](/docs/packages/packem/examples/configuration/extra-conditions) example).
* `allowedExportExtensions` lets non-JS outputs (such as `.css` or `.wasm`) appear in `exports` without triggering an "unexpected extension" warning.

## Disabling a specific check [#disabling-a-specific-check]

Set any field toggle to `false` to skip just that check while keeping the rest:

```typescript
validation: {
    packageJson: {
        // Validate everything except the engines field
        name: true,
        main: true,
        types: true,
        exports: true,
        engines: false,
    },
}
```

## Disabling all validation [#disabling-all-validation]

To turn off every validator (package.json, bundle size, and dependencies) set `validation` to `false`:

```typescript
export default defineConfig({
    transformer,
    validation: false,
})
```

You can also pass `--no-validation` on the CLI:

```bash
packem build --no-validation
```

## Related Examples [#related-examples]

* [Extra Conditions](/docs/packages/packem/examples/configuration/extra-conditions) - Configure custom export conditions
* [Dependency Validation](/docs/packages/packem/examples/configuration/dependency-validation) - Validate dependencies and detect issues
* [Bundle Size Limits](/docs/packages/packem/examples/configuration/bundle-limits) - Set up bundle size validation and limits


# Basic CSS (/docs/packages/packem/examples/css/basic)





# Basic CSS [#basic-css]

Packem processes CSS imported from your JavaScript/TypeScript through the
[`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css) plugin. Plain
`.css` files run through PostCSS, and you control whether the result is injected
at runtime or extracted into separate `.css` files via the `mode` option.

## Overview [#overview]

This example demonstrates:

* Importing plain CSS into a TypeScript module
* Registering the PostCSS loader in `packem.config.ts`
* Switching between **inject** and **extract** output modes
* Minifying the output with cssnano

## Setup [#setup]

The PostCSS loader requires `postcss` to be installed. The CSS loaders ship with
Packem and are imported from the `@visulima/packem/css/loader/*` sub-paths.

```bash
npm install --save-dev postcss
```

If you want minified output, install cssnano as well:

```bash
npm install --save-dev cssnano
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.css
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.css**

```css
.btn {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;
}

.btn-primary {
  background-color: #007bff;
  color: white;
}
```

**src/index.ts**

```typescript
import './styles.css'

export function createButton() {
  const button = document.createElement('button')
  button.className = 'btn btn-primary'
  button.textContent = 'Click me'
  return button
}
```

## Configuration [#configuration]

CSS options live under `rollup.css` and are typed as `StyleOptions` from
`@visulima/rollup-plugin-css`. Register the PostCSS loader by importing it and
adding it to the `loaders` array.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      loaders: [postcssLoader],
    },
  },
})
```

## Output Modes [#output-modes]

The `mode` option selects how CSS reaches the bundle. The default is `"inject"`.

### Inject (default) [#inject-default]

Embeds the CSS inside the JavaScript bundle and injects it into `<head>` at
runtime. This requires `@visulima/css-style-inject` to be installed.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'inject',
      loaders: [postcssLoader],
    },
  },
})
```

```bash
npm install --save-dev @visulima/css-style-inject
```

### Extract [#extract]

Writes CSS to a separate `.css` file next to the generated JS. You can also pass
a path (relative to the output directory) to control the extraction location.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
    },
  },
})
```

To extract to a fixed file name, use the tuple form:

```typescript
css: {
  mode: ['extract', 'styles.css'],
  loaders: [postcssLoader],
}
```

### Inline [#inline]

Embeds the processed CSS as a string export in the JavaScript module without
runtime injection.

```typescript
css: {
  mode: 'inline',
  loaders: [postcssLoader],
}
```

## Minification [#minification]

CSS minification is enabled by passing a minifier object to the `minifier`
option. Packem provides cssnano and Lightning CSS minifiers as importable
sub-paths.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import cssnanoMinifier from '@visulima/packem/css/minifier/cssnano'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      minifier: cssnanoMinifier,
    },
  },
})
```

## Source Maps [#source-maps]

Enable CSS source maps with the `sourceMap` option:

```typescript
css: {
  mode: 'extract',
  loaders: [postcssLoader],
  sourceMap: true, // or 'inline'
}
```

## Building [#building]

```bash
packem build
```

<Callout type="info">
  Run `packem build --verbose` to see detailed CSS processing information for each
  file.
</Callout>

## Related [#related]

* [PostCSS](/docs/packages/packem/examples/css/postcss) — plugins and `postcss.config.js`
* [CSS Modules](/docs/packages/packem/examples/css/modules) — scoped class names
* [CSS Processing guide](/docs/packages/packem/guide/css)


# Less (/docs/packages/packem/examples/css/less)





# Less [#less]

Packem compiles `.less` files through the Less loader in
[`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css). The loader forwards
its options directly to the Less compiler.

## Overview [#overview]

This example demonstrates:

* Compiling Less with variables, mixins, and functions
* Registering the Less loader in `packem.config.ts`
* Passing Less compiler options

## Setup [#setup]

The Less loader requires the `less` package.

```bash
npm install --save-dev less
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.less
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.less**

```less
@primary-color: #007bff;
@border-radius: 0.25rem;

.button-style(@bg-color) {
  background-color: @bg-color;
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: @border-radius;
  cursor: pointer;

  &:hover {
    background-color: darken(@bg-color, 10%);
  }
}

.btn-primary {
  .button-style(@primary-color);
}
```

**src/index.ts**

```typescript
import './styles.less'

export function createButton() {
  const button = document.createElement('button')
  button.className = 'btn-primary'
  button.textContent = 'Click me'
  return button
}
```

## Configuration [#configuration]

Register the Less loader by importing it and adding it to `rollup.css.loaders`.
The `less` option accepts the standard Less compiler options
(`Less.Options`).

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import lessLoader from '@visulima/packem/css/loader/less'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lessLoader],
      less: {
        math: 'parens-division',
        paths: ['node_modules', 'src/styles'],
      },
    },
  },
})
```

<Callout type="info">
  The `less` option maps to `Less.Options`. See the
  [Less.js options documentation](https://lesscss.org/usage/#less-options) for the
  full list, including `math`, `paths`, `globalVars`, and `plugins`.
</Callout>

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Sass/SCSS](/docs/packages/packem/examples/css/sass)
* [Stylus](/docs/packages/packem/examples/css/stylus)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# Lightning CSS (/docs/packages/packem/examples/css/lightningcss)





# Lightning CSS [#lightning-css]

[Lightning CSS](https://lightningcss.dev/) is a Rust-based CSS parser,
transformer, and minifier. In Packem it is available two ways through
[`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css): as a **loader**
that transforms your CSS, and as a **minifier** for optimized output.

## Overview [#overview]

This example demonstrates:

* Using the Lightning CSS loader to transform CSS
* Using Lightning CSS as the minifier
* Configuring browser targets and draft features via the `lightningcss` option
* CSS Modules support through Lightning CSS

## Setup [#setup]

Install the `lightningcss` package.

```bash
npm install --save-dev lightningcss
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.css
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.css**

```css
.card {
  padding: 1rem;
  border: 1px solid #dee2e6;

  /* CSS nesting, transformed by Lightning CSS */
  .title {
    font-size: 1.25rem;
    font-weight: bold;
  }
}
```

**src/index.ts**

```typescript
import './styles.css'

export function createCard() {
  const card = document.createElement('div')
  card.className = 'card'
  return card
}
```

## Lightning CSS as a Loader [#lightning-css-as-a-loader]

Import the Lightning CSS loader and add it to `rollup.css.loaders`. The loader
transforms CSS with Lightning CSS, including nesting and other modern features.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import lightningcssLoader from '@visulima/packem/css/loader/lightningcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lightningcssLoader],
    },
  },
})
```

### Loader Options [#loader-options]

Lightning CSS transform options are passed via the `lightningcss` option. It
accepts the Lightning CSS `TransformOptions`, except for `code`, `filename`,
`minify`, `targets`, and `cssModules`, which the loader manages internally.
Browser `targets` are derived from your project's browserslist configuration.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lightningcssLoader],
      lightningcss: {
        // Enable draft-stage features
        drafts: {
          customMedia: true,
        },
      },
    },
  },
})
```

### CSS Modules with Lightning CSS [#css-modules-with-lightning-css]

The Lightning CSS loader supports CSS Modules. Configure them through the
`lightningcss.modules` option, which additionally accepts an `include` pattern
for selecting module files.

```typescript
css: {
  mode: 'extract',
  loaders: [lightningcssLoader],
  lightningcss: {
    modules: {
      // Treat *.module.* files as CSS Modules
      include: /\.module\./,
    },
  },
}
```

<Callout type="info">
  Lightning CSS does not resolve cross-file `composes from "..."` references. If
  you rely on those, use the [PostCSS loader](/docs/packages/packem/examples/css/postcss) for CSS
  Modules instead.
</Callout>

## Lightning CSS as a Minifier [#lightning-css-as-a-minifier]

You can minify with Lightning CSS regardless of which loader processed the CSS.
Import the minifier and assign it to the `minifier` option.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import lightningcssMinifier from '@visulima/packem/css/minifier/lightningcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      minifier: lightningcssMinifier,
    },
  },
})
```

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Basic CSS](/docs/packages/packem/examples/css/basic)
* [PostCSS](/docs/packages/packem/examples/css/postcss)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# CSS Modules (/docs/packages/packem/examples/css/modules)





# CSS Modules [#css-modules]

CSS Modules give you locally scoped class names, eliminating naming collisions.
Packem handles them through [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css)
and can generate scoped names automatically for `*.module.css` files.

## Overview [#overview]

This example demonstrates:

* Enabling CSS Modules for `*.module.*` files via `autoModules`
* Customizing scoped name generation
* Importing scoped class names into TypeScript
* Generating companion `.d.ts` files for type-safe class names

## Setup [#setup]

CSS Modules build on PostCSS, so install `postcss`:

```bash
npm install --save-dev postcss
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── Button.ts
│   └── Button.module.css
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/Button.module.css**

```css
.button {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;
}

.primary {
  background-color: #007bff;
  color: white;
}

.secondary {
  background-color: #6c757d;
  color: white;
}
```

**src/Button.ts**

```typescript
import styles from './Button.module.css'

export function createButton(variant: 'primary' | 'secondary' = 'primary') {
  const button = document.createElement('button')
  button.className = `${styles.button} ${styles[variant]}`
  button.textContent = 'Click me'
  return button
}
```

## Configuration [#configuration]

Enable CSS Modules with the `autoModules` option. It accepts a boolean, a
regular expression, or a function. When `true`, it applies to files named
`[name].module.[ext]` (for example `Button.module.css`).

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      autoModules: true,
    },
  },
})
```

To restrict CSS Modules to a custom pattern, pass a regular expression:

```typescript
css: {
  loaders: [postcssLoader],
  autoModules: /\.module\./,
}
```

### Customizing Scoped Names [#customizing-scoped-names]

Module behavior is configured through `postcss.modules`. The
`generateScopedName` placeholder controls the emitted class names (default
`"[name]_[local]_[hash:8]"`).

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      postcss: {
        modules: {
          generateScopedName: '[name]__[local]___[hash:base64:5]',
          exportGlobals: true,
        },
      },
    },
  },
})
```

Available `modules` options:

* `generateScopedName` — placeholder string or function for scoped name generation
* `mode` — default scoping mode (`"local"`, default)
* `exportGlobals` — export global class names
* `failOnWrongOrder` — fail on wrong composition order
* `include` — files to treat as CSS Modules

<Callout type="info">
  You can also enable modules through `postcss.modules` directly (set it to `true`
  or an options object) instead of using `autoModules`.
</Callout>

## Type-Safe Class Names [#type-safe-class-names]

Set the `dts` option to generate companion `.d.ts` files alongside your CSS
Modules, giving you IntelliSense and compile-time checks for class names.

```typescript
css: {
  mode: 'extract',
  loaders: [postcssLoader],
  autoModules: true,
  dts: true,
}
```

This emits a declaration file next to each module:

```typescript
// src/Button.module.css.d.ts (auto-generated)
declare const button: string
declare const primary: string
declare const secondary: string

interface ModulesExports {
  button: string
  primary: string
  secondary: string
}

declare const styles: ModulesExports
export default styles
export { button, primary, secondary }
```

## Named Exports [#named-exports]

Enable `namedExports` to export each class as a named binding alongside the
default export:

```typescript
css: {
  loaders: [postcssLoader],
  autoModules: true,
  namedExports: true,
}
```

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Basic CSS](/docs/packages/packem/examples/css/basic)
* [React with CSS Modules](/docs/packages/packem/examples/react/css-modules)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# PostCSS (/docs/packages/packem/examples/css/postcss)





# PostCSS [#postcss]

PostCSS is the default processing pipeline for CSS in Packem. The PostCSS loader
in [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css) automatically
picks up a `postcss.config.js` file and also accepts inline plugin configuration.

## Overview [#overview]

This example demonstrates:

* Using a `postcss.config.js` file with autoprefixer and other plugins
* Configuring plugins inline in `packem.config.ts`
* Controlling the config loader, `@import` resolution, and URL handling

## Setup [#setup]

Install `postcss` plus any plugins you need. `postcss-load-config` is used to
discover the config file.

```bash
npm install --save-dev postcss autoprefixer postcss-nested
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.css
├── postcss.config.js
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.css**

```css
.card {
  display: grid;
  gap: 1rem;

  .title {
    font-size: 1.25rem;
    font-weight: bold;
  }
}
```

**src/index.ts**

```typescript
import './styles.css'

export function createCard() {
  const card = document.createElement('div')
  card.className = 'card'
  return card
}
```

## Using a PostCSS Config File [#using-a-postcss-config-file]

The PostCSS loader detects and applies your `postcss.config.js` automatically.

```javascript
// postcss.config.js
export default {
  plugins: {
    'postcss-nested': {},
    autoprefixer: {},
  },
}
```

Then register the PostCSS loader:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
    },
  },
})
```

## Inline Plugin Configuration [#inline-plugin-configuration]

Plugins listed in the `postcss.plugins` option run *before* any plugins loaded
from the config file. Each entry can be a plugin instance, a module name string,
or a `[name, options]` tuple.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      postcss: {
        plugins: [
          'autoprefixer',
          ['postcss-custom-properties', { preserve: false }],
        ],
      },
    },
  },
})
```

## PostCSS Loader Options [#postcss-loader-options]

The `postcss` option exposes several sub-options:

* `config` — enable/disable or configure the config-file loader (set to `false`
  to ignore `postcss.config.js`, or pass `{ path, ctx }`)
* `plugins` — plugins applied before config-file plugins
* `import` — options for the CSS `@import` resolver (or `false` to disable)
* `url` — options for the CSS URL resolver (or `false` to disable)
* `modules` — enable/configure CSS Modules
* `parser`, `syntax`, `stringifier` — override the PostCSS parser/syntax/stringifier
* `to` — the `to` option for plugins that require it

```typescript
css: {
  loaders: [postcssLoader],
  postcss: {
    // Skip the postcss.config.js file and use inline plugins only
    config: false,
    plugins: ['autoprefixer'],
    // Disable the built-in @import resolver
    import: false,
  },
}
```

<Callout type="info">
  The built-in `@import` and URL resolvers run by default. Disable them by setting
  `postcss.import` or `postcss.url` to `false` when you want a plugin to handle
  them instead.
</Callout>

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Basic CSS](/docs/packages/packem/examples/css/basic)
* [CSS Modules](/docs/packages/packem/examples/css/modules)
* [Tailwind CSS](/docs/packages/packem/examples/react/tailwind)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# Sass/SCSS (/docs/packages/packem/examples/css/sass)





# Sass/SCSS [#sassscss]

Packem compiles `.scss` and `.sass` files through the Sass loader in
[`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css). It supports both
Dart Sass (`sass`) and the faster `sass-embedded` implementation.

## Overview [#overview]

This example demonstrates:

* Compiling SCSS with variables, mixins, and nesting
* Registering the Sass loader in `packem.config.ts`
* Configuring the Sass implementation and compiler options

## Setup [#setup]

The Sass loader requires a Sass implementation. Install either `sass` or
`sass-embedded`.

<Tabs items="['Dart Sass', 'Embedded Sass']">
  <Tab value="Dart Sass">
    ```bash
    npm install --save-dev sass
    ```
  </Tab>

  <Tab value="Embedded Sass">
    ```bash
    npm install --save-dev sass-embedded
    ```
  </Tab>
</Tabs>

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.scss
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.scss**

```scss
$primary-color: #007bff;
$border-radius: 0.25rem;

@mixin button-style($bg-color) {
  background-color: $bg-color;
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: $border-radius;
  cursor: pointer;

  &:hover {
    background-color: darken($bg-color, 10%);
  }
}

.btn-primary {
  @include button-style($primary-color);
}
```

**src/index.ts**

```typescript
import './styles.scss'

export function createButton() {
  const button = document.createElement('button')
  button.className = 'btn-primary'
  button.textContent = 'Click me'
  return button
}
```

## Configuration [#configuration]

Register the Sass loader by importing it and adding it to `rollup.css.loaders`.
The `sass` option accepts the Sass loader options, which extend the Sass
compiler's `StringOptions`.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import sassLoader from '@visulima/packem/css/loader/sass'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [sassLoader],
      sass: {
        implementation: 'sass', // or 'sass-embedded'
      },
    },
  },
})
```

### Compiler Options [#compiler-options]

The `sass` option forwards options to the underlying Sass compiler. The loader
also adds an `additionalData` hook for prepending shared variables or mixins to
every file, an `implementation` switch, and `warnRuleAsWarning`.

```typescript
css: {
  mode: 'extract',
  loaders: [sassLoader],
  sass: {
    implementation: 'sass-embedded',
    // Prepend shared variables/mixins to every entry file
    additionalData: `@use "src/styles/_variables.scss" as *;`,
    // Forwarded to the Sass compiler
    style: 'compressed',
  },
}
```

<Callout type="info">
  The `charset` and `indentedSyntax` options are managed by the loader and cannot
  be set directly. Use the `.sass` extension for indented syntax files.
</Callout>

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Less](/docs/packages/packem/examples/css/less)
* [Stylus](/docs/packages/packem/examples/css/stylus)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# Stylus (/docs/packages/packem/examples/css/stylus)





# Stylus [#stylus]

Packem compiles `.styl` files through the Stylus loader in
[`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css). The loader extends
the Stylus `RenderOptions` with extra helpers for include paths, plugins, and
shared data.

## Overview [#overview]

This example demonstrates:

* Compiling Stylus with its indentation-based syntax
* Registering the Stylus loader in `packem.config.ts`
* Configuring include paths, plugins, and prepended data

## Setup [#setup]

The Stylus loader requires the `stylus` package.

```bash
npm install --save-dev stylus
```

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── styles.styl
├── package.json
└── packem.config.ts
```

### Source Files [#source-files]

**src/styles.styl**

```stylus
primary-color = #007bff
border-radius = 0.25rem

button-style(bg-color)
  background-color bg-color
  color white
  padding 0.5rem 1rem
  border none
  border-radius border-radius
  cursor pointer

  &:hover
    background-color darken(bg-color, 10%)

.btn-primary
  button-style(primary-color)
```

**src/index.ts**

```typescript
import './styles.styl'

export function createButton() {
  const button = document.createElement('button')
  button.className = 'btn-primary'
  button.textContent = 'Click me'
  return button
}
```

## Configuration [#configuration]

Register the Stylus loader by importing it and adding it to
`rollup.css.loaders`. The `stylus` option extends Stylus `RenderOptions` with
loader-specific fields.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import stylusLoader from '@visulima/packem/css/loader/stylus'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [stylusLoader],
      stylus: {
        // Additional include paths
        include: ['node_modules', 'src/styles'],
        // Pre-defined variables/functions on the renderer
        define: { 'primary-color': '#007bff' },
        // Plugins applied via .use()
        use: ['nib'],
      },
    },
  },
})
```

The Stylus loader adds several options on top of the standard Stylus render
options:

* `additionalData` — prepend or append Stylus code (shared variables/mixins)
  before compilation
* `define` — pre-define variables/functions on the renderer
* `import` — files to pre-import before compiling
* `include` — additional include paths
* `includeCSS` — include regular CSS on `@import`
* `lineNumbers` — emit comments with the source Stylus line
* `use` — Stylus plugins to apply

<Callout type="info">
  See the
  [Stylus JS API documentation](https://stylus-lang.com/docs/js.html) for the
  underlying render options.
</Callout>

## Building [#building]

```bash
packem build
```

## Related [#related]

* [Sass/SCSS](/docs/packages/packem/examples/css/sass)
* [Less](/docs/packages/packem/examples/css/less)
* [CSS Processing guide](/docs/packages/packem/guide/css)


# Dual Package (ESM + CJS) (/docs/packages/packem/examples/dual-package)



# Dual Package (ESM + CJS) [#dual-package-esm--cjs]

Learn how to create packages that work seamlessly in both ESM (import) and CommonJS (require) environments, ensuring maximum compatibility across the JavaScript ecosystem.

## Overview [#overview]

This example demonstrates:

* Dual package configuration
* ESM and CJS output generation
* Conditional exports setup
* Runtime detection and compatibility
* Testing both environments
* Best practices for cross-compatibility

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
dual-package-example/
├── src/
│   ├── index.ts
│   ├── utils.ts
│   └── constants.ts
├── test/
│   ├── esm.test.mjs
│   └── cjs.test.cjs
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Source Code [#source-code]

### Main Entry Point [#main-entry-point]

**src/index.ts**

```typescript
// Core exports that work in both environments
export { createLogger, Logger } from './logger'
export { formatMessage, MessageFormatter } from './formatter'
export { ValidationError, validate } from './validator'

// Utility exports
export * from './utils'
export * from './constants'

// Default export for convenience
import { createLogger } from './logger'
import { formatMessage } from './formatter'
import { validate } from './validator'

const utils = {
  createLogger,
  formatMessage,
  validate
}

export default utils
```

### Logger Implementation [#logger-implementation]

**src/logger.ts**

```typescript
export interface LoggerOptions {
  level?: 'debug' | 'info' | 'warn' | 'error'
  timestamp?: boolean
  prefix?: string
}

export class Logger {
  private options: Required<LoggerOptions>

  constructor(options: LoggerOptions = {}) {
    this.options = {
      level: 'info',
      timestamp: true,
      prefix: '',
      ...options
    }
  }

  private shouldLog(level: string): boolean {
    const levels = ['debug', 'info', 'warn', 'error']
    const currentIndex = levels.indexOf(this.options.level)
    const messageIndex = levels.indexOf(level)
    return messageIndex >= currentIndex
  }

  private formatMessage(level: string, message: string): string {
    const parts: string[] = []
    
    if (this.options.timestamp) {
      parts.push(new Date().toISOString())
    }
    
    if (this.options.prefix) {
      parts.push(`[${this.options.prefix}]`)
    }
    
    parts.push(`[${level.toUpperCase()}]`)
    parts.push(message)
    
    return parts.join(' ')
  }

  debug(message: string): void {
    if (this.shouldLog('debug')) {
      console.debug(this.formatMessage('debug', message))
    }
  }

  info(message: string): void {
    if (this.shouldLog('info')) {
      console.info(this.formatMessage('info', message))
    }
  }

  warn(message: string): void {
    if (this.shouldLog('warn')) {
      console.warn(this.formatMessage('warn', message))
    }
  }

  error(message: string): void {
    if (this.shouldLog('error')) {
      console.error(this.formatMessage('error', message))
    }
  }
}

export function createLogger(options?: LoggerOptions): Logger {
  return new Logger(options)
}
```

### Message Formatter [#message-formatter]

**src/formatter.ts**

```typescript
export interface FormatOptions {
  uppercase?: boolean
  trim?: boolean
  maxLength?: number
}

export class MessageFormatter {
  static format(message: string, options: FormatOptions = {}): string {
    let result = message

    if (options.trim) {
      result = result.trim()
    }

    if (options.uppercase) {
      result = result.toUpperCase()
    }

    if (options.maxLength && result.length > options.maxLength) {
      result = result.substring(0, options.maxLength - 3) + '...'
    }

    return result
  }
}

export function formatMessage(message: string, options?: FormatOptions): string {
  return MessageFormatter.format(message, options)
}
```

### Validator [#validator]

**src/validator.ts**

```typescript
export class ValidationError extends Error {
  constructor(message: string) {
    super(message)
    this.name = 'ValidationError'
  }
}

export interface ValidationRule {
  required?: boolean
  minLength?: number
  maxLength?: number
  pattern?: RegExp
}

export function validate(value: string, rules: ValidationRule): boolean {
  if (rules.required && (!value || value.trim() === '')) {
    throw new ValidationError('Value is required')
  }

  if (rules.minLength && value.length < rules.minLength) {
    throw new ValidationError(`Value must be at least ${rules.minLength} characters`)
  }

  if (rules.maxLength && value.length > rules.maxLength) {
    throw new ValidationError(`Value must be no more than ${rules.maxLength} characters`)
  }

  if (rules.pattern && !rules.pattern.test(value)) {
    throw new ValidationError('Value does not match required pattern')
  }

  return true
}
```

### Utilities [#utilities]

**src/utils.ts**

```typescript
/**
 * Check if code is running in Node.js environment
 */
export function isNode(): boolean {
  return typeof process !== 'undefined' && 
         process.versions != null && 
         process.versions.node != null
}

/**
 * Check if code is running in browser environment
 */
export function isBrowser(): boolean {
  return typeof window !== 'undefined' && 
         typeof document !== 'undefined'
}

/**
 * Get current environment type
 */
export function getEnvironment(): 'node' | 'browser' | 'unknown' {
  if (isNode()) return 'node'
  if (isBrowser()) return 'browser'
  return 'unknown'
}

/**
 * Delay execution for specified milliseconds
 */
export function delay(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms))
}

/**
 * Create a simple UUID v4
 */
export function createId(): string {
  if (isNode()) {
    // Use crypto module in Node.js
    const crypto = require('crypto')
    return crypto.randomUUID()
  } else if (isBrowser() && 'crypto' in window && 'randomUUID' in window.crypto) {
    // Use Web Crypto API in browsers
    return window.crypto.randomUUID()
  } else {
    // Fallback implementation
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
      const r = Math.random() * 16 | 0
      const v = c === 'x' ? r : (r & 0x3 | 0x8)
      return v.toString(16)
    })
  }
}
```

### Constants [#constants]

**src/constants.ts**

```typescript
export const VERSION = '1.0.0'

export const LOG_LEVELS = {
  DEBUG: 0,
  INFO: 1,
  WARN: 2,
  ERROR: 3
} as const

export const DEFAULT_CONFIG = {
  logLevel: 'info',
  maxRetries: 3,
  timeout: 5000
} as const

export const FORMATS = {
  JSON: 'json',
  TEXT: 'text',
  XML: 'xml'
} as const
```

## Package Configuration [#package-configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/dual-package",
  "version": "1.0.0",
  "description": "Example dual package supporting both ESM and CommonJS",
  "type": "module",
  "files": [
    "dist",
    "README.md"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./logger": {
      "types": "./dist/logger.d.ts",
      "import": "./dist/logger.js",
      "require": "./dist/logger.cjs"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js",
      "require": "./dist/utils.cjs"
    },
    "./package.json": "./package.json"
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch",
    "clean": "rm -rf dist",
    "test": "npm run test:esm && npm run test:cjs",
    "test:esm": "node test/esm.test.mjs",
    "test:cjs": "node test/cjs.test.cjs",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "dual-package",
    "esm",
    "commonjs",
    "typescript",
    "utilities"
  ],
  "author": "Your Name",
  "license": "MIT",
  "devDependencies": {
    "@visulima/packem": "^2",
    "typescript": "^5.3.0"
  }
}
```

### Build Configuration [#build-configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  rollup: {
    watch: {
      include: 'src/**'
    }
  }
})
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "test"]
}
```

## Testing Both Environments [#testing-both-environments]

### ESM Test [#esm-test]

**test/esm.test.mjs**

```javascript
// Test ESM imports
import utils, { createLogger, formatMessage, validate, isNode } from '../dist/index.js'

console.log('🧪 Testing ESM imports...')

// Test named imports
const logger = createLogger({ prefix: 'TEST', level: 'debug' })
logger.info('ESM import test successful')

// Test formatMessage
const formatted = formatMessage('  hello world  ', { trim: true, uppercase: true })
console.log('Formatted message:', formatted)

// Test validation
try {
  validate('test', { required: true, minLength: 2 })
  console.log('✅ Validation passed')
} catch (error) {
  console.error('❌ Validation failed:', error.message)
}

// Test environment detection
console.log('Environment detected as:', isNode() ? 'Node.js' : 'Browser')

// Test default export
console.log('Default export available:', typeof utils === 'object')

console.log('✅ All ESM tests passed!')
```

### CommonJS Test [#commonjs-test]

**test/cjs.test.cjs**

```javascript
// Test CommonJS require
const utils = require('../dist/index.cjs')
const { createLogger, formatMessage, validate, isNode } = utils

console.log('🧪 Testing CommonJS require...')

// Test named imports
const logger = createLogger({ prefix: 'TEST', level: 'debug' })
logger.info('CommonJS require test successful')

// Test formatMessage
const formatted = formatMessage('  hello world  ', { trim: true, uppercase: true })
console.log('Formatted message:', formatted)

// Test validation
try {
  validate('test', { required: true, minLength: 2 })
  console.log('✅ Validation passed')
} catch (error) {
  console.error('❌ Validation failed:', error.message)
}

// Test environment detection
console.log('Environment detected as:', isNode() ? 'Node.js' : 'Browser')

// Test default export
console.log('Default export available:', typeof utils === 'object')

console.log('✅ All CommonJS tests passed!')
```

## Build and Test [#build-and-test]

### Build the Package [#build-the-package]

```bash
npm run build
```

### Output Structure [#output-structure]

After building, you'll have:

```
dist/
├── index.js          # ESM main entry
├── index.cjs         # CJS main entry
├── index.d.ts        # TypeScript declarations
├── logger.js         # ESM logger module
├── logger.cjs        # CJS logger module
├── logger.d.ts       # Logger type declarations
├── utils.js          # ESM utils module
├── utils.cjs         # CJS utils module
├── utils.d.ts        # Utils type declarations
└── ...
```

### Test Both Environments [#test-both-environments]

```bash
# Test ESM support
npm run test:esm

# Test CommonJS support  
npm run test:cjs

# Test both
npm test
```

## Usage Examples [#usage-examples]

### ESM Usage [#esm-usage]

```typescript
// Named imports
import { createLogger, formatMessage } from '@myorg/dual-package'

// Default import
import utils from '@myorg/dual-package'

// Subpath imports
import { createLogger } from '@myorg/dual-package/logger'
import { isNode, delay } from '@myorg/dual-package/utils'

const logger = createLogger({ level: 'debug' })
logger.info('Hello from ESM!')
```

### CommonJS Usage [#commonjs-usage]

```javascript
// Full require
const utils = require('@myorg/dual-package')
const { createLogger, formatMessage } = utils

// Destructured require
const { createLogger, formatMessage } = require('@myorg/dual-package')

// Subpath requires
const { createLogger } = require('@myorg/dual-package/logger')
const { isNode, delay } = require('@myorg/dual-package/utils')

const logger = createLogger({ level: 'debug' })
logger.info('Hello from CommonJS!')
```

### Browser Usage [#browser-usage]

```html
<!-- ESM in browser -->
<script type="module">
  import { createLogger } from './node_modules/@myorg/dual-package/dist/index.js'
  
  const logger = createLogger()
  logger.info('Hello from browser!')
</script>

<!-- Or with bundler -->
<script>
  import { createLogger } from '@myorg/dual-package'
  // Bundler will resolve the correct format
</script>
```

## Key Features [#key-features]

### Automatic Format Detection [#automatic-format-detection]

The package automatically provides the correct format based on how it's imported:

```javascript
// ESM - gets dist/index.js
import utils from '@myorg/dual-package'

// CommonJS - gets dist/index.cjs
const utils = require('@myorg/dual-package')
```

### Conditional Exports [#conditional-exports]

The `exports` field in package.json ensures correct resolution:

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}
```

### Runtime Compatibility [#runtime-compatibility]

Code works identically in both environments:

```typescript
// Same API in both ESM and CJS
const logger = createLogger()
logger.info('This works everywhere!')
```

## Best Practices [#best-practices]

### 1. Test Both Environments [#1-test-both-environments]

Always test both ESM and CommonJS to ensure compatibility:

```bash
npm run test:esm  # Test import syntax
npm run test:cjs  # Test require syntax
```

### 2. Use Conditional Exports [#2-use-conditional-exports]

Properly configure package.json exports:

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}
```

### 3. Avoid Environment-Specific Code [#3-avoid-environment-specific-code]

Write code that works in both environments:

```typescript
// ✅ Good - works everywhere
export function createId(): string {
  return Math.random().toString(36)
}

// ❌ Bad - Node.js specific
export function createId(): string {
  return require('crypto').randomUUID()
}
```

### 4. Handle Dependencies Carefully [#4-handle-dependencies-carefully]

Use appropriate external declarations:

```typescript
// Use dynamic imports for environment-specific features
export async function getNodeVersion(): Promise<string> {
  if (typeof process !== 'undefined') {
    return process.version
  }
  throw new Error('Not in Node.js environment')
}
```

<Callout type="info">
  Dual packages ensure maximum compatibility across the JavaScript ecosystem, making your library accessible to the widest possible audience.
</Callout>

## Common Issues [#common-issues]

### Module Resolution Errors [#module-resolution-errors]

Ensure your tsconfig.json has proper module resolution:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}
```

### Import/Require Mixing [#importrequire-mixing]

Don't mix import and require in the same file:

```javascript
// ❌ Don't do this
import { createLogger } from '@myorg/dual-package'
const utils = require('@myorg/dual-package')

// ✅ Choose one approach per file
import { createLogger } from '@myorg/dual-package'
import utils from '@myorg/dual-package'
```

This dual package example provides a robust foundation for creating libraries that work seamlessly in both ESM and CommonJS environments.


# Examples (/docs/packages/packem/examples)



# Examples [#examples]

Each example is a complete, working project you can use as a starting point. Pick the one closest to what you are building.

## Library starters [#library-starters]

| Example                                                                  | What it builds                                                      |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [Basic TypeScript Library](/docs/packages/packem/examples/basic-library) | A simple utility package with ESM output and `.d.ts` declarations   |
| [TypeScript Library](/docs/packages/packem/examples/basic-typescript)    | A TypeScript library with ESM + CJS output and declarations         |
| [JavaScript Package](/docs/packages/packem/examples/basic-javascript)    | A modern, zero-config JavaScript package                            |
| [Dual Package (ESM + CJS)](/docs/packages/packem/examples/dual-package)  | A library that ships both ESM and CJS for maximum compatibility     |
| [CLI Tool](/docs/packages/packem/examples/cli-tool)                      | A package with `bin` executables and auto hashbang insertion        |
| [Multiple Exports](/docs/packages/packem/examples/multi-exports)         | Multiple entry points via `package.json#exports` subpaths           |
| [React Component Library](/docs/packages/packem/examples/react-library)  | React components with CSS Modules, Server Components, and Storybook |
| [Monorepo](/docs/packages/packem/examples/monorepo)                      | Multiple packages in a single workspace with shared configuration   |

## Transformers [#transformers]

| Example                                                        | What it covers                                            |
| -------------------------------------------------------------- | --------------------------------------------------------- |
| [esbuild](/docs/packages/packem/examples/transformers/esbuild) | Fast bundling with the esbuild transformer                |
| [swc](/docs/packages/packem/examples/transformers/swc)         | Rust-powered compilation with swc (decorators, legacy TS) |
| [OXC](/docs/packages/packem/examples/transformers/oxc)         | The experimental next-generation OXC toolchain            |
| [sucrase](/docs/packages/packem/examples/transformers/sucrase) | Lightweight, fast alternative to Babel                    |

## CSS [#css]

| Example                                                          | What it covers                                      |
| ---------------------------------------------------------------- | --------------------------------------------------- |
| [Basic CSS](/docs/packages/packem/examples/css/basic)            | Plain CSS with PostCSS, injection and extraction    |
| [Sass/SCSS](/docs/packages/packem/examples/css/sass)             | Sass preprocessing with variables and mixins        |
| [Less](/docs/packages/packem/examples/css/less)                  | Less compilation                                    |
| [Stylus](/docs/packages/packem/examples/css/stylus)              | Stylus preprocessing                                |
| [CSS Modules](/docs/packages/packem/examples/css/modules)        | Scoped class names with automatic CSS Modules       |
| [PostCSS](/docs/packages/packem/examples/css/postcss)            | Advanced PostCSS configuration with plugins         |
| [Lightning CSS](/docs/packages/packem/examples/css/lightningcss) | Fast CSS processing/minification with Lightning CSS |

## React [#react]

| Example                                                                     | What it covers                                    |
| --------------------------------------------------------------------------- | ------------------------------------------------- |
| [React Library](/docs/packages/packem/examples/react/library)               | A React component library with TypeScript         |
| [CSS Modules](/docs/packages/packem/examples/react/css-modules)             | React components with scoped CSS Modules          |
| [Server Components](/docs/packages/packem/examples/react/server-components) | RSC and client components with directive handling |
| [Tailwind CSS](/docs/packages/packem/examples/react/tailwind)               | React components with Tailwind CSS via PostCSS    |

## Configuration recipes [#configuration-recipes]

| Example                                                                                     | What it covers                                        |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Extra Conditions](/docs/packages/packem/examples/configuration/extra-conditions)           | Custom export conditions in `package.json` validation |
| [Bundle Size Limits](/docs/packages/packem/examples/configuration/bundle-limits)            | Bundle size validation and per-file limits            |
| [Package.json Validation](/docs/packages/packem/examples/configuration/package-validation)  | Full `package.json` field validation setup            |
| [Dependency Validation](/docs/packages/packem/examples/configuration/dependency-validation) | Detect unused, hoisted, and duplicated dependencies   |

## Advanced [#advanced]

| Example                                                                                    | What it covers                                                       |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| [Multi-Runtime](/docs/packages/packem/examples/advanced/multi-runtime)                     | Conditional exports for node, browser, edge, and react-server        |
| [Dynamic Imports](/docs/packages/packem/examples/advanced/dynamic-imports)                 | Code splitting via dynamic `import()`                                |
| [Shared Modules](/docs/packages/packem/examples/advanced/shared-modules)                   | Shared chunks between bundles                                        |
| [WebAssembly](/docs/packages/packem/examples/advanced/webassembly)                         | Bundling `.wasm` modules                                             |
| [Custom Plugins](/docs/packages/packem/examples/advanced/custom-plugins)                   | Adding custom Rollup plugins via the `plugins` option                |
| [Bundle Analysis](/docs/packages/packem/examples/advanced/bundle-analysis)                 | Visualize and analyze bundle size                                    |
| [Minify HTML Literals](/docs/packages/packem/examples/advanced/minify-html-literals)       | Automatically minify HTML and CSS inside template literals           |
| [require-cjs-transformer](/docs/packages/packem/examples/advanced/require-cjs-transformer) | Transform ESM imports of CJS packages for better runtime performance |

## Quick start [#quick-start]

Copy one of these to bootstrap a new project:

```bash
# TypeScript library
npx degit visulima/packem/examples/basic-library my-lib
cd my-lib && npm install && npm run build

# React component library
npx degit visulima/packem/examples/react-library my-components
cd my-components && npm install && npm run build
```


# Monorepo Setup (/docs/packages/packem/examples/monorepo)



# Monorepo Setup [#monorepo-setup]

Learn how to set up a monorepo with multiple packages using Packem, including shared configuration, cross-package dependencies, and coordinated builds.

## Overview [#overview]

This example demonstrates:

* Monorepo structure with multiple packages
* Shared Packem configuration
* Cross-package dependencies
* Coordinated build scripts
* TypeScript project references
* Package versioning and publishing

## Project Structure [#project-structure]

```
my-monorepo/
├── packages/
│   ├── core/                    # Core utilities package
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── ui/                      # UI components package
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── cli/                     # CLI tools package
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── shared-config/           # Shared build configuration
│       ├── packem.config.ts
│       └── package.json
├── package.json                 # Root package.json
├── pnpm-workspace.yaml         # Workspace configuration
├── tsconfig.json               # Root TypeScript config
└── turbo.json                  # Turborepo configuration (optional)
```

## Root Configuration [#root-configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/monorepo",
  "version": "1.0.0",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "build": "pnpm run --recursive --filter='!shared-config' build",
    "dev": "pnpm run --recursive --filter='!shared-config' dev",
    "clean": "pnpm run --recursive clean",
    "typecheck": "tsc --build",
    "release": "changeset publish"
  },
  "devDependencies": {
    "@changesets/cli": "^2.26.0",
    "@visulima/packem": "^2",
    "typescript": "^5.3.0",
    "turbo": "^1.10.0"
  },
  "packageManager": "pnpm@8.0.0"
}
```

### Workspace Configuration [#workspace-configuration]

**pnpm-workspace.yaml**

```yaml
packages:
  - 'packages/*'
```

### Root TypeScript Configuration [#root-typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "composite": true
  },
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" },
    { "path": "./packages/cli" }
  ],
  "files": []
}
```

## Shared Configuration Package [#shared-configuration-package]

### packages/shared-config/package.json [#packagesshared-configpackagejson]

```json
{
  "name": "@myorg/shared-config",
  "version": "1.0.0",
  "private": true,
  "main": "packem.config.js",
  "files": [
    "packem.config.js"
  ],
  "dependencies": {
    "@visulima/packem": "workspace:*"
  }
}
```

### packages/shared-config/packem.config.ts [#packagesshared-configpackemconfigts]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export const createPackemConfig = (options: {
  external?: string[]
  css?: boolean
  react?: boolean
} = {}) => {
  const { external = [], css = false, react = false } = options

  return defineConfig({
    transformer,
    sourcemap: true,
    declaration: true,
    externals: [
      // Common externals
      'react',
      'react-dom',
      ...external
    ],
    rollup: {
      ...(css && {
        css: {
          mode: 'extract'
        }
      }),
      watch: {
        include: 'src/**'
      }
    }
  })
}

// Default configuration
export default createPackemConfig()
```

## Core Package [#core-package]

### packages/core/package.json [#packagescorepackagejson]

```json
{
  "name": "@myorg/core",
  "version": "1.0.0",
  "description": "Core utilities and types",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils/index.d.ts",
      "import": "./dist/utils/index.js",
      "require": "./dist/utils/index.cjs"
    },
    "./types": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/types/index.js",
      "require": "./dist/types/index.cjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch",
    "clean": "rm -rf dist",
    "typecheck": "tsc --build"
  },
  "devDependencies": {
    "@myorg/shared-config": "workspace:*",
    "@visulima/packem": "workspace:*",
    "typescript": "^5.3.0"
  }
}
```

### packages/core/src/index.ts [#packagescoresrcindexts]

```typescript
// Utils
export * from './utils'

// Types
export * from './types'

// Main API
export interface CoreConfig {
  debug?: boolean
  environment?: 'development' | 'production' | 'test'
}

export class Core {
  private config: CoreConfig

  constructor(config: CoreConfig = {}) {
    this.config = {
      debug: false,
      environment: 'production',
      ...config
    }
  }

  log(message: string) {
    if (this.config.debug) {
      console.log(`[Core] ${message}`)
    }
  }

  getConfig() {
    return { ...this.config }
  }
}

export function createCore(config?: CoreConfig) {
  return new Core(config)
}
```

### packages/core/src/utils/index.ts [#packagescoresrcutilsindexts]

```typescript
/**
 * Utility functions
 */

export function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value)
}

export function isEmpty(value: unknown): boolean {
  if (value === null || value === undefined) return true
  if (typeof value === 'string') return value.length === 0
  if (Array.isArray(value)) return value.length === 0
  if (isObject(value)) return Object.keys(value).length === 0
  return false
}

export function deepMerge<T extends Record<string, any>>(
  target: T,
  source: Partial<T>
): T {
  const result = { ...target }

  for (const key in source) {
    const sourceValue = source[key]
    const targetValue = result[key]

    if (isObject(sourceValue) && isObject(targetValue)) {
      result[key] = deepMerge(targetValue, sourceValue)
    } else if (sourceValue !== undefined) {
      result[key] = sourceValue
    }
  }

  return result
}

export function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
): T {
  let timeout: NodeJS.Timeout | undefined

  return ((...args: Parameters<T>) => {
    clearTimeout(timeout)
    timeout = setTimeout(() => func(...args), wait)
  }) as T
}
```

### packages/core/src/types/index.ts [#packagescoresrctypesindexts]

```typescript
/**
 * Shared type definitions
 */

export interface BaseEntity {
  id: string
  createdAt: Date
  updatedAt: Date
}

export interface User extends BaseEntity {
  email: string
  name: string
  role: 'admin' | 'user' | 'guest'
}

export interface APIResponse<T = unknown> {
  data: T
  success: boolean
  message?: string
  error?: string
}

export type Environment = 'development' | 'production' | 'test'

export interface LogLevel {
  level: 'debug' | 'info' | 'warn' | 'error'
  timestamp: Date
  message: string
  meta?: Record<string, unknown>
}
```

### packages/core/tsconfig.json [#packagescoretsconfigjson]

```json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "composite": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### packages/core/packem.config.ts [#packagescorepackemconfigts]

```typescript
import { createPackemConfig } from '@myorg/shared-config'

export default createPackemConfig()
```

## UI Package [#ui-package]

### packages/ui/package.json [#packagesuipackagejson]

```json
{
  "name": "@myorg/ui",
  "version": "1.0.0",
  "description": "React UI components",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./components": {
      "types": "./dist/components/index.d.ts",
      "import": "./dist/components/index.js",
      "require": "./dist/components/index.cjs"
    }
  },
  "sideEffects": [
    "**/*.css"
  ],
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch",
    "clean": "rm -rf dist",
    "typecheck": "tsc --build"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "dependencies": {
    "@myorg/core": "workspace:*"
  },
  "devDependencies": {
    "@myorg/shared-config": "workspace:*",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "@visulima/packem": "workspace:*",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typescript": "^5.3.0"
  }
}
```

### packages/ui/src/index.ts [#packagesuisrcindexts]

```typescript
// Re-export core types that UI components need
export type { User, APIResponse } from '@myorg/core'

// Export components
export * from './components'
```

### packages/ui/src/components/index.ts [#packagesuisrccomponentsindexts]

```typescript
export { Button } from './Button'
export { UserCard } from './UserCard'

export type { ButtonProps } from './Button'
export type { UserCardProps } from './UserCard'
```

### packages/ui/src/components/Button.tsx [#packagesuisrccomponentsbuttontsx]

```typescript
'use client'

import React from 'react'

export interface ButtonProps 
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', children, className, ...props }, ref) => {
    const baseClasses = 'px-4 py-2 rounded font-medium transition-colors'
    const variantClasses = {
      primary: 'bg-blue-500 text-white hover:bg-blue-600',
      secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300'
    }
    const sizeClasses = {
      sm: 'px-2 py-1 text-sm',
      md: 'px-4 py-2',
      lg: 'px-6 py-3 text-lg'
    }

    const finalClassName = [
      baseClasses,
      variantClasses[variant],
      sizeClasses[size],
      className
    ].filter(Boolean).join(' ')

    return (
      <button
        ref={ref}
        className={finalClassName}
        {...props}
      >
        {children}
      </button>
    )
  }
)

Button.displayName = 'Button'
```

### packages/ui/src/components/UserCard.tsx [#packagesuisrccomponentsusercardtsx]

```typescript
import React from 'react'
import type { User } from '@myorg/core'
import { Button } from './Button'

export interface UserCardProps {
  user: User
  onEdit?: (user: User) => void
  onDelete?: (user: User) => void
}

export function UserCard({ user, onEdit, onDelete }: UserCardProps) {
  return (
    <div className="border rounded-lg p-4 bg-white shadow-sm">
      <div className="flex justify-between items-start mb-2">
        <h3 className="text-lg font-semibold">{user.name}</h3>
        <span className="text-sm text-gray-500 capitalize">{user.role}</span>
      </div>
      
      <p className="text-gray-600 mb-4">{user.email}</p>
      
      <div className="flex gap-2">
        {onEdit && (
          <Button 
            variant="secondary" 
            size="sm"
            onClick={() => onEdit(user)}
          >
            Edit
          </Button>
        )}
        
        {onDelete && (
          <Button 
            variant="primary" 
            size="sm"
            onClick={() => onDelete(user)}
          >
            Delete
          </Button>
        )}
      </div>
    </div>
  )
}
```

### packages/ui/tsconfig.json [#packagesuitsconfigjson]

```json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "outDir": "dist",
    "rootDir": "src",
    "composite": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "references": [
    { "path": "../core" }
  ]
}
```

### packages/ui/packem.config.ts [#packagesuipackemconfigts]

```typescript
import { createPackemConfig } from '@myorg/shared-config'

export default createPackemConfig({
  external: ['@myorg/core'],
  css: true,
  react: true
})
```

## CLI Package [#cli-package]

### packages/cli/package.json [#packagesclipackagejson]

```json
{
  "name": "@myorg/cli",
  "version": "1.0.0",
  "description": "Command line tools",
  "type": "module",
  "files": [
    "dist",
    "bin"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "bin": {
    "myorg": "./bin/myorg.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "packem build && npm run build:bin",
    "build:bin": "echo '#!/usr/bin/env node\nrequire(\"../dist/cli.cjs\")' > bin/myorg.js && chmod +x bin/myorg.js",
    "dev": "packem build --watch",
    "clean": "rm -rf dist bin",
    "typecheck": "tsc --build"
  },
  "dependencies": {
    "@myorg/core": "workspace:*",
    "commander": "^11.0.0"
  },
  "devDependencies": {
    "@myorg/shared-config": "workspace:*",
    "@types/node": "^20.0.0",
    "@visulima/packem": "workspace:*",
    "typescript": "^5.3.0"
  }
}
```

### packages/cli/src/index.ts [#packagesclisrcindexts]

```typescript
export { createCLI } from './cli'
export { runCommand } from './commands'
```

### packages/cli/src/cli.ts [#packagesclisrcclits]

```typescript
#!/usr/bin/env node

import { Command } from 'commander'
import { createCore } from '@myorg/core'
import { buildCommand } from './commands/build'
import { devCommand } from './commands/dev'

export function createCLI() {
  const core = createCore({ debug: true })
  const program = new Command()

  program
    .name('@myorg/cli')
    .description('Monorepo development tools')
    .version('1.0.0')

  // Build command
  program
    .command('build')
    .description('Build all packages')
    .option('-w, --watch', 'Watch for changes')
    .action(buildCommand)

  // Dev command
  program
    .command('dev')
    .description('Start development mode')
    .action(devCommand)

  return { program, core }
}

// CLI entry point
if (import.meta.url === `file://${process.argv[1]}`) {
  const { program } = createCLI()
  program.parse()
}
```

### packages/cli/src/commands/index.ts [#packagesclisrccommandsindexts]

```typescript
export { buildCommand } from './build'
export { devCommand } from './dev'

export function runCommand(name: string, ...args: any[]) {
  console.log(`Running command: ${name}`, args)
}
```

### packages/cli/src/commands/build.ts [#packagesclisrccommandsbuildts]

```typescript
import { createCore } from '@myorg/core'

export async function buildCommand(options: { watch?: boolean }) {
  const core = createCore({ debug: true })
  
  core.log('Starting build...')
  
  if (options.watch) {
    core.log('Watching for changes...')
    // Watch mode implementation
  } else {
    core.log('Building packages...')
    // Build implementation
  }
  
  core.log('Build completed!')
}
```

### packages/cli/src/commands/dev.ts [#packagesclisrccommandsdevts]

```typescript
import { createCore } from '@myorg/core'

export async function devCommand() {
  const core = createCore({ debug: true })
  
  core.log('Starting development mode...')
  
  // Development server implementation
  
  core.log('Development server started!')
}
```

### packages/cli/tsconfig.json [#packagesclitsconfigjson]

```json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "composite": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "references": [
    { "path": "../core" }
  ]
}
```

### packages/cli/packem.config.ts [#packagesclipackemconfigts]

```typescript
import { createPackemConfig } from '@myorg/shared-config'

export default createPackemConfig({
  external: ['@myorg/core', 'commander']
})
```

## Build Scripts and Workflows [#build-scripts-and-workflows]

### Turborepo Configuration (Optional) [#turborepo-configuration-optional]

**turbo.json**

```json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "typecheck": {
      "dependsOn": ["^build"]
    },
    "clean": {
      "cache": false
    }
  }
}
```

## Building the Monorepo [#building-the-monorepo]

### Install Dependencies [#install-dependencies]

```bash
pnpm install
```

### Build All Packages [#build-all-packages]

```bash
# Build all packages in correct order
pnpm run build

# Or with Turborepo
turbo build
```

### Development Mode [#development-mode]

```bash
# Watch all packages
pnpm run dev

# Or with Turborepo
turbo dev
```

### Clean All Packages [#clean-all-packages]

```bash
pnpm run clean
```

## Key Benefits [#key-benefits]

### Shared Configuration [#shared-configuration]

* Single source of truth for build configuration
* Easy to maintain and update across packages
* Consistent build output across all packages

### Cross-Package Dependencies [#cross-package-dependencies]

* Type-safe imports between packages
* Automatic rebuild when dependencies change
* Proper dependency resolution

### Coordinated Builds [#coordinated-builds]

* Build packages in correct dependency order
* Parallel builds where possible
* Incremental builds with caching

## Package Publishing [#package-publishing]

### Using Changesets [#using-changesets]

```bash
# Add a changeset
npx changeset

# Version packages
npx changeset version

# Publish packages
npx changeset publish
```

### Individual Package Publishing [#individual-package-publishing]

```bash
# Build and publish specific package
cd packages/core
pnpm build
npm publish
```

<Callout type="info">
  This monorepo setup provides a scalable foundation for large projects with multiple related packages while maintaining build consistency and developer experience.
</Callout>

## Next Steps [#next-steps]

* Add automated testing across packages
* Set up GitHub Actions for CI/CD
* Implement automated dependency updates
* Add package size tracking and optimization
* Set up automated changelog generation
* Configure automated security scanning


# Multiple Exports (/docs/packages/packem/examples/multi-exports)



# Multiple Exports [#multiple-exports]

Expose several entry points from one package using `package.json#exports` subpaths. Packem maps each subpath key (`.`, `./utils`, …) to a build entry based on the file paths in its conditions, so consumers can import exactly the slice they need and bundlers can tree-shake the rest.

## Overview [#overview]

This example demonstrates:

* Multiple entry points via `exports` subpaths
* How Packem maps each subpath to a build entry
* Dual ESM + CJS output per entry
* Per-subpath TypeScript declarations

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-package/
├── src/
│   ├── index.ts
│   └── utils.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Source Files [#source-files]

**src/index.ts**

```typescript
export interface User {
  id: string
  name: string
}

export function createUser(name: string): User {
  return { id: crypto.randomUUID(), name }
}
```

**src/utils.ts**

```typescript
export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max)
}

export function range(start: number, end: number): number[] {
  return Array.from({ length: end - start }, (_, index) => start + index)
}
```

## Configuration [#configuration]

### package.json [#packagejson]

Each key under `exports` is a subpath. Packem reads the file paths in the
`import`/`require`/`types` conditions and creates one entry per subpath, matching
the output filenames you declare here. The `.` key maps to `src/index.ts` and
`./utils` maps to `src/utils.ts`.

```json
{
  "name": "@myorg/my-package",
  "version": "1.0.0",
  "description": "A package with multiple entry points",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    },
    "./utils": {
      "import": {
        "types": "./dist/utils.d.mts",
        "default": "./dist/utils.mjs"
      },
      "require": {
        "types": "./dist/utils.d.cts",
        "default": "./dist/utils.cjs"
      }
    },
    "./package.json": "./package.json"
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "esbuild": "^0.25.0",
    "typescript": "^5.3.0"
  }
}
```

<Callout type="info">
  The output file name (`./dist/utils.mjs`) tells Packem to look for the matching source file (`src/utils.ts`). Keep your source filenames aligned with the export targets and the mapping is automatic.
</Callout>

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### Packem Configuration [#packem-configuration]

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

## Building [#building]

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── index.mjs        # "." ESM entry
├── index.cjs        # "." CJS entry
├── index.d.mts
├── index.d.cts
├── index.d.ts
├── utils.mjs        # "./utils" ESM entry
├── utils.cjs        # "./utils" CJS entry
├── utils.d.mts
├── utils.d.cts
└── utils.d.ts
```

## Usage [#usage]

### Importing subpaths [#importing-subpaths]

```typescript
// Root entry
import { createUser } from '@myorg/my-package'

// Subpath entry — only the utils module is loaded
import { clamp, range } from '@myorg/my-package/utils'

createUser('Ada')
clamp(12, 0, 10) // 10
```

### CommonJS [#commonjs]

```javascript
const { createUser } = require('@myorg/my-package')
const { clamp } = require('@myorg/my-package/utils')
```

## Next Steps [#next-steps]

* Add a CLI entry with [CLI Tool](/docs/packages/packem/examples/cli-tool)
* Add runtime-specific outputs with [Multi-Runtime](/docs/packages/packem/examples/advanced/multi-runtime)
* Review automatic exports handling in [Package Exports](/docs/packages/packem/options/package-exports)


# CSS Modules (/docs/packages/packem/examples/react/css-modules)



# CSS Modules [#css-modules]

Build React components with locally scoped CSS Modules. Class names are hashed at build time so styles never collide across components.

## Overview [#overview]

This example demonstrates:

* React components styled with CSS Modules
* Automatic scoping for `*.module.css` files via `autoModules`
* Generated, collision-free class names
* Extracted `.css` output alongside your JavaScript
* Auto-generated TypeScript declarations for CSS Module imports

CSS Modules are powered by [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css), which Packem configures through the `rollup.css` option.

## Project Structure [#project-structure]

```
react-ui-lib/
├── src/
│   ├── Button.tsx
│   ├── Button.module.css
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Component Implementation [#component-implementation]

**src/Button.tsx**

```tsx
'use client'

import React from 'react'

import styles from './Button.module.css'

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={`${styles.button} ${styles[variant]}`}
        {...props}
      >
        {children}
      </button>
    )
  }
)

Button.displayName = 'Button'
```

**src/Button.module.css**

```css
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 0.5rem 1rem;
  border: 1px solid transparent;
  border-radius: 0.375rem;
  font-weight: 500;
  cursor: pointer;
}

.primary {
  background-color: #3b82f6;
  color: white;
}

.secondary {
  background-color: #6b7280;
  color: white;
}
```

**src/index.ts**

```typescript
export { Button } from './Button'
export type { ButtonProps } from './Button'
```

## Configuration [#configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/react-ui",
  "version": "1.0.0",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "sideEffects": [
    "**/*.css"
  ],
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typescript": "^5.3.0"
  }
}
```

<Callout type="info">
  Listing `"**/*.css"` under `sideEffects` ensures the extracted stylesheets are preserved during tree shaking when the library is consumed.
</Callout>

### Packem Configuration [#packem-configuration]

Enable the React preset and turn on CSS Modules through `rollup.css`. `autoModules` opts every `*.module.css` file into scoped class names, and `mode: 'extract'` writes the styles to companion `.css` files:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
  sourcemap: true,
  declaration: true,
  rollup: {
    css: {
      mode: 'extract',
      autoModules: true,
      postcss: {
        modules: {
          generateScopedName: '[name]__[local]___[hash:base64:5]',
        },
      },
    },
  },
})
```

The `autoModules` option accepts a regular expression if you want to control which files are treated as modules:

```typescript
rollup: {
  css: {
    mode: 'extract',
    // Only files matching `.module.` become CSS Modules
    autoModules: /\.module\./,
  },
}
```

### TypeScript Configuration [#typescript-configuration]

CSS Module imports are typed via auto-generated companion declaration files. To let TypeScript resolve `import styles from './Button.module.css'`, add a global ambient declaration:

**src/css-modules.d.ts**

```typescript
declare module '*.module.css' {
  const styles: { readonly [key: string]: string }
  export default styles
}
```

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Building [#building]

```bash
npm run build
```

### Output [#output]

```
dist/
├── index.js          # ESM entry
├── index.cjs         # CJS entry
├── index.d.ts        # TypeScript declarations
└── Button.module.css # Extracted, scoped styles
```

At build time, class names are rewritten using the `generateScopedName` pattern:

```tsx
// Source
import styles from './Button.module.css'
<button className={styles.button} />

// Generated class name, e.g.
// Button__button___a1b2c
```

## Key Features [#key-features]

### Scoped by Default [#scoped-by-default]

Every class declared in a `*.module.css` file is rewritten to a unique, hashed name. Two components can both use `.button` without conflicting.

### Extract vs. Inject [#extract-vs-inject]

This example uses `mode: 'extract'` to emit standalone `.css` files. If you prefer the styles embedded in JavaScript and injected at runtime, use `mode: 'inject'` (which requires `@visulima/css-style-inject`). See the [CSS guide](/docs/packages/packem/guide/css) for all modes.

## Next Steps [#next-steps]

* Add [Tailwind CSS](/docs/packages/packem/examples/react/tailwind) for utility-first styling
* Read the full [CSS Processing guide](/docs/packages/packem/guide/css)
* Set up a [React Library](/docs/packages/packem/examples/react/library) with externalized React


# React Library (/docs/packages/packem/examples/react/library)



# React Library [#react-library]

Create a production-ready React component library with TypeScript, externalized React, and optimized bundling for both server and client environments.

## Overview [#overview]

This example demonstrates:

* React component library setup with the `react` preset
* TypeScript with React types and declaration generation
* React and React DOM externalized (kept out of the bundle as peer dependencies)
* Tree-shakable, dual ESM + CJS output
* `"use client"` directive support for interactive components

## Project Structure [#project-structure]

```
react-ui-lib/
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Card.tsx
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Component Implementation [#component-implementation]

**src/components/Button.tsx**

```tsx
'use client'

import React from 'react'

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', children, ...props }, ref) => {
    return (
      <button ref={ref} data-variant={variant} {...props}>
        {children}
      </button>
    )
  }
)

Button.displayName = 'Button'
```

**src/components/Card.tsx**

```tsx
import React from 'react'

export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode
}

export const Card = React.forwardRef<HTMLDivElement, CardProps>(
  ({ children, ...props }, ref) => {
    return (
      <div ref={ref} {...props}>
        {children}
      </div>
    )
  }
)

Card.displayName = 'Card'
```

**src/index.ts**

```typescript
export { Button } from './components/Button'
export type { ButtonProps } from './components/Button'

export { Card } from './components/Card'
export type { CardProps } from './components/Card'
```

## Configuration [#configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/react-ui",
  "version": "1.0.0",
  "description": "Modern React component library",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typescript": "^5.3.0"
  }
}
```

<Callout type="info">
  Because `react` and `react-dom` are declared as `peerDependencies`, Packem automatically treats them as external and keeps them out of your bundle. They are resolved from the consuming application at runtime.
</Callout>

### Packem Configuration [#packem-configuration]

**Quick setup (recommended)**

Use the `add` command to configure React and install the required dependencies:

```bash
npx packem add react
```

**packem.config.ts — string preset**

The simplest way to enable React is the `react` string preset:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
  sourcemap: true,
  declaration: true,
})
```

**packem.config.ts — preset function**

For more control, use `createReactPreset`. Set `compiler: true` to enable the React Compiler:

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    // Enable React Compiler for automatic optimizations
    compiler: false,
    // Additional Babel presets (optional)
    presets: [],
    // Additional Babel plugins (optional)
    plugins: [],
  }),
  transformer,
  sourcemap: true,
  declaration: true,
})
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Building [#building]

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── index.js       # ESM entry
├── index.cjs      # CJS entry
└── index.d.ts     # TypeScript declarations
```

## Usage [#usage]

```tsx
import { Button, Card } from '@myorg/react-ui'

function App() {
  return (
    <Card>
      <Button variant="primary" onClick={() => alert('Clicked!')}>
        Click me
      </Button>
    </Card>
  )
}
```

## Key Features [#key-features]

### External Dependencies [#external-dependencies]

React and React DOM are externalized through the `peerDependencies` field, so they are never bundled into your library.

### Directive Support [#directive-support]

Components that opt into client-side interactivity can declare `"use client"` at the top of the file. Packem preserves the directive in the output. See [Server Components](/docs/packages/packem/examples/react/server-components) for the full directive and `react-server` workflow.

## Next Steps [#next-steps]

* Add [CSS Modules](/docs/packages/packem/examples/react/css-modules) for scoped component styling
* Add [Tailwind CSS](/docs/packages/packem/examples/react/tailwind) via PostCSS
* Build [Server Components](/docs/packages/packem/examples/react/server-components) with `"use client"` / `"use server"` directives


# Server Components (/docs/packages/packem/examples/react/server-components)



# Server Components [#server-components]

Build a library that ships both React Server Components and Client Components. Packem preserves the `"use client"` and `"use server"` directives and scopes the client/server boundaries so app bundlers like Next.js can integrate them correctly.

## Overview [#overview]

This example demonstrates:

* Library directives `"use client"` and `"use server"`
* How Packem preserves and hoists directives in the output
* A dedicated `react-server` runtime bundle via an input-source override
* Conditional exports that point app bundlers at the right entry

## How Packem Handles Directives [#how-packem-handles-directives]

From the Packem behavior:

* If you use `"use client"` or `"use server"` in an **entry file**, the directive is preserved on top and the entry's output becomes a client component.
* If you use `"use client"` or `"use server"` in a file that is a **dependency** of an entry, that file is split into a separate chunk and the directive is hoisted to the top of that chunk.

This means client and server boundaries stay properly scoped: when the library is integrated into an app such as Next.js, the app bundler can transform the client components and server actions correctly.

## Project Structure [#project-structure]

```
react-rsc-lib/
├── src/
│   ├── Counter.tsx              # client component
│   ├── actions.ts              # server actions
│   ├── ServerInfo.tsx          # server component
│   ├── index.ts                # default runtime entry
│   └── index.react-server.ts   # react-server runtime entry
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Component Implementation [#component-implementation]

**src/Counter.tsx** — a client component

```tsx
'use client'

import React from 'react'

export function Counter() {
  const [count, setCount] = React.useState(0)

  return (
    <button onClick={() => setCount((c) => c + 1)}>
      Count: {count}
    </button>
  )
}
```

**src/actions.ts** — server actions

```typescript
'use server'

export async function submitForm(data: FormData) {
  const name = data.get('name')
  // ...persist on the server
  return { ok: true, name }
}
```

**src/ServerInfo.tsx** — a server component (no directive needed)

```tsx
import React from 'react'

export async function ServerInfo() {
  const now = new Date().toISOString()

  return <p>Rendered on the server at {now}</p>
}
```

**src/index.ts** — the default entry

```typescript
export { Counter } from './Counter'
export { submitForm } from './actions'
export { ServerInfo } from './ServerInfo'
```

**src/index.react-server.ts** — the `react-server` runtime entry

This override file is bundled separately for the `react-server` condition. Here you can expose a server-safe surface (for example omitting client-only components):

```typescript
export { submitForm } from './actions'
export { ServerInfo } from './ServerInfo'
```

<Callout type="info">
  The input-source override convention is `src/index.react-server.{ext}`. Packem builds it into a distinct `react-server` bundle that you wire up through the `react-server` export condition.
</Callout>

## Configuration [#configuration]

### package.json [#packagejson]

The `react-server` condition is a special platform condition. Place it before the generic `import`/`require` conditions so app bundlers running in the server layer resolve it first:

```json
{
  "name": "@myorg/react-rsc",
  "version": "1.0.0",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "react-server": "./dist/index.react-server.js",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typescript": "^5.3.0"
  }
}
```

### Packem Configuration [#packem-configuration]

The `react` preset handles the JSX/Babel setup. Packem detects the directives in your source and the `react-server` override entry from the `exports` map automatically:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
  sourcemap: true,
  declaration: true,
})
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Building [#building]

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── index.js                 # default runtime entry (client boundary preserved)
├── index.cjs
├── index.d.ts
├── index.react-server.js    # react-server runtime bundle
└── ...chunks/               # hoisted "use client" / "use server" chunks
```

The `"use client"` directive from `Counter.tsx` is preserved at the top of its chunk, and the `"use server"` directive from `actions.ts` is hoisted to the top of the server-action chunk, so consuming bundlers can identify each boundary.

## Shared Modules Across Runtimes [#shared-modules-across-runtimes]

When the default and `react-server` bundles need to share a single instance of a module (for example a React context), use the shared module convention `[name].shared-runtime.{ext}`:

```tsx
'use client'

// src/app-context.shared-runtime.ts
import React from 'react'

export const AppContext = React.createContext(null)
```

Import it from both entries:

```typescript
// src/index.ts
import { AppContext } from './app-context.shared-runtime'

// src/index.react-server.ts
import { AppContext } from './app-context.shared-runtime'
```

Packem bundles `app-context.shared-runtime` into a single chunk shared across both runtime bundles, ensuring only one instance exists.

## Next Steps [#next-steps]

* Read the [Multi-Runtime guide](/docs/packages/packem/guide/multi-runtime) for more runtime conditions
* Set up a plain [React Library](/docs/packages/packem/examples/react/library)
* Add [CSS Modules](/docs/packages/packem/examples/react/css-modules) for scoped client styles


# Tailwind CSS (/docs/packages/packem/examples/react/tailwind)



# Tailwind CSS [#tailwind-css]

Style React components with Tailwind CSS. Tailwind runs through PostCSS as part of Packem's CSS pipeline, so utility classes are compiled and the resulting stylesheet is extracted alongside your components.

## Overview [#overview]

This example demonstrates:

* React components using Tailwind utility classes
* Tailwind CSS v4 wired in through PostCSS
* A single extracted stylesheet for the whole library
* The `react` preset for JSX handling

Tailwind is processed by the PostCSS loader from [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css), configured through Packem's `rollup.css` option.

## Installation [#installation]

```bash
npm install --save-dev tailwindcss @tailwindcss/postcss postcss
```

## Project Structure [#project-structure]

```
react-tailwind-lib/
├── src/
│   ├── Button.tsx
│   ├── styles.css      # Tailwind entry stylesheet
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Component Implementation [#component-implementation]

**src/styles.css** — import Tailwind

```css
@import 'tailwindcss';
```

**src/Button.tsx**

```tsx
'use client'

import React from 'react'

import './styles.css'

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', children, ...props }, ref) => {
    const base =
      'inline-flex items-center justify-center rounded-md px-4 py-2 font-medium'
    const variants = {
      primary: 'bg-blue-600 text-white hover:bg-blue-700',
      secondary: 'bg-gray-600 text-white hover:bg-gray-700',
    }

    return (
      <button
        ref={ref}
        className={`${base} ${variants[variant]}`}
        {...props}
      >
        {children}
      </button>
    )
  }
)

Button.displayName = 'Button'
```

**src/index.ts**

```typescript
export { Button } from './Button'
export type { ButtonProps } from './Button'
```

## Configuration [#configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/react-tailwind",
  "version": "1.0.0",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./styles.css": "./dist/styles.css"
  },
  "sideEffects": [
    "**/*.css"
  ],
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@tailwindcss/postcss": "^4.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "postcss": "^8.4.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "tailwindcss": "^4.0.0",
    "typescript": "^5.3.0"
  }
}
```

<Callout type="info">
  Exposing the compiled stylesheet through an `"./styles.css"` export lets consumers import it once: `import '@myorg/react-tailwind/styles.css'`.
</Callout>

### Packem Configuration [#packem-configuration]

Enable the React preset and register Tailwind as a PostCSS plugin. `mode: 'extract'` writes the compiled utilities to a single `.css` file:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
  sourcemap: true,
  declaration: true,
  rollup: {
    css: {
      mode: 'extract',
      postcss: {
        plugins: ['@tailwindcss/postcss'],
      },
    },
  },
})
```

If you prefer an explicit PostCSS config file, point the loader at it instead:

```js
// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  preset: 'react',
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
    },
  },
})
```

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Building [#building]

```bash
npm run build
```

### Output [#output]

```
dist/
├── index.js     # ESM entry
├── index.cjs    # CJS entry
├── index.d.ts   # TypeScript declarations
└── styles.css   # Compiled Tailwind utilities
```

## Usage [#usage]

```tsx
import { Button } from '@myorg/react-tailwind'
import '@myorg/react-tailwind/styles.css'

function App() {
  return <Button variant="primary">Click me</Button>
}
```

## Tailwind Oxide (Alternative) [#tailwind-oxide-alternative]

Packem also ships a dedicated Tailwind loader backed by Tailwind's Rust-based Oxide engine. See the [CSS guide](/docs/packages/packem/guide/css) for details on the `@visulima/packem/css/loader/tailwindcss` loader and the required `@tailwindcss/node` / `@tailwindcss/oxide` dependencies.

## Next Steps [#next-steps]

* Combine Tailwind with scoped [CSS Modules](/docs/packages/packem/examples/react/css-modules)
* Read the full [CSS Processing guide](/docs/packages/packem/guide/css)
* Set up a [React Library](/docs/packages/packem/examples/react/library) with externalized React


# React Component Library (/docs/packages/packem/examples/react-library)



# React Component Library [#react-component-library]

Create a production-ready React component library with TypeScript, CSS Modules, and optimized bundling for both server and client components.

## Overview [#overview]

This example demonstrates:

* React component library setup
* TypeScript with React types
* CSS Modules for scoped styling
* Server and Client component separation
* Tree-shakable exports
* Storybook integration ready
* Proper peer dependencies

## Project Structure [#project-structure]

```
react-ui-lib/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.module.css
│   │   │   └── index.ts
│   │   ├── Card/
│   │   │   ├── Card.tsx
│   │   │   ├── Card.module.css
│   │   │   └── index.ts
│   │   └── index.ts
│   ├── hooks/
│   │   ├── useLocalStorage.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── cn.ts
│   │   └── index.ts
│   ├── types/
│   │   └── index.ts
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Component Implementation [#component-implementation]

### Button Component [#button-component]

**src/components/Button/Button.tsx**

```typescript
'use client'

import React from 'react'
import { cn } from '../../utils/cn'
import styles from './Button.module.css'

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean
  children: React.ReactNode
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({
    className,
    variant = 'primary',
    size = 'md',
    loading = false,
    disabled,
    children,
    ...props
  }, ref) => {
    return (
      <button
        className={cn(
          styles.button,
          styles[variant],
          styles[size],
          loading && styles.loading,
          className
        )}
        disabled={disabled || loading}
        ref={ref}
        {...props}
      >
        {loading && <span className={styles.spinner} />}
        <span className={loading ? styles.content : undefined}>
          {children}
        </span>
      </button>
    )
  }
)

Button.displayName = 'Button'
```

**src/components/Button/Button.module.css**

```css
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  border-radius: 0.375rem;
  border: 1px solid transparent;
  font-weight: 500;
  transition: all 0.2s ease-in-out;
  cursor: pointer;
  position: relative;
  outline: none;
}

.button:focus-visible {
  ring: 2px solid #3b82f6;
  ring-offset: 2px;
}

.button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Variants */
.primary {
  background-color: #3b82f6;
  color: white;
}

.primary:hover:not(:disabled) {
  background-color: #2563eb;
}

.secondary {
  background-color: #6b7280;
  color: white;
}

.secondary:hover:not(:disabled) {
  background-color: #4b5563;
}

.outline {
  background-color: transparent;
  border-color: #d1d5db;
  color: #374151;
}

.outline:hover:not(:disabled) {
  background-color: #f9fafb;
  border-color: #9ca3af;
}

.ghost {
  background-color: transparent;
  color: #374151;
}

.ghost:hover:not(:disabled) {
  background-color: #f3f4f6;
}

/* Sizes */
.sm {
  height: 2rem;
  padding: 0 0.75rem;
  font-size: 0.875rem;
}

.md {
  height: 2.5rem;
  padding: 0 1rem;
  font-size: 0.875rem;
}

.lg {
  height: 3rem;
  padding: 0 1.5rem;
  font-size: 1rem;
}

/* Loading state */
.loading {
  cursor: not-allowed;
}

.content {
  opacity: 0;
}

.spinner {
  position: absolute;
  width: 1rem;
  height: 1rem;
  border: 2px solid transparent;
  border-top: 2px solid currentColor;
  border-radius: 50%;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}
```

**src/components/Button/index.ts**

```typescript
export { Button } from './Button'
export type { ButtonProps } from './Button'
```

### Card Component [#card-component]

**src/components/Card/Card.tsx**

```typescript
import React from 'react'
import { cn } from '../../utils/cn'
import styles from './Card.module.css'

export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode
  padding?: 'none' | 'sm' | 'md' | 'lg'
  shadow?: 'none' | 'sm' | 'md' | 'lg'
}

export const Card = React.forwardRef<HTMLDivElement, CardProps>(
  ({ className, children, padding = 'md', shadow = 'md', ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={cn(
          styles.card,
          styles[`padding-${padding}`],
          styles[`shadow-${shadow}`],
          className
        )}
        {...props}
      >
        {children}
      </div>
    )
  }
)

Card.displayName = 'Card'

export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode
}

export const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
  ({ className, children, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={cn(styles.header, className)}
        {...props}
      >
        {children}
      </div>
    )
  }
)

CardHeader.displayName = 'CardHeader'

export interface CardContentProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode
}

export const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
  ({ className, children, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={cn(styles.content, className)}
        {...props}
      >
        {children}
      </div>
    )
  }
)

CardContent.displayName = 'CardContent'
```

**src/components/Card/Card.module.css**

```css
.card {
  background-color: white;
  border-radius: 0.5rem;
  border: 1px solid #e5e7eb;
  overflow: hidden;
}

/* Padding variants */
.padding-none {
  padding: 0;
}

.padding-sm {
  padding: 0.75rem;
}

.padding-md {
  padding: 1.5rem;
}

.padding-lg {
  padding: 2rem;
}

/* Shadow variants */
.shadow-none {
  box-shadow: none;
}

.shadow-sm {
  box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
}

.shadow-md {
  box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
}

.shadow-lg {
  box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
}

.header {
  padding-bottom: 1rem;
  border-bottom: 1px solid #f3f4f6;
  margin-bottom: 1rem;
}

.content {
  /* Content styles */
}
```

**src/components/Card/index.ts**

```typescript
export { Card, CardHeader, CardContent } from './Card'
export type { CardProps, CardHeaderProps, CardContentProps } from './Card'
```

### Utility Functions [#utility-functions]

**src/utils/cn.ts**

```typescript
/**
 * Utility function to combine class names
 */
export function cn(...classes: (string | undefined | null | false)[]): string {
  return classes.filter(Boolean).join(' ')
}
```

**src/utils/index.ts**

```typescript
export { cn } from './cn'
```

### Custom Hooks [#custom-hooks]

**src/hooks/useLocalStorage.ts**

```typescript
'use client'

import { useState, useEffect } from 'react'

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((val: T) => T)) => void] {
  // State to store our value
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === "undefined") {
      return initialValue
    }

    try {
      const item = window.localStorage.getItem(key)
      return item ? JSON.parse(item) : initialValue
    } catch (error) {
      console.error(`Error reading localStorage key "${key}":`, error)
      return initialValue
    }
  })

  // Return a wrapped version of useState's setter function that persists the new value to localStorage
  const setValue = (value: T | ((val: T) => T)) => {
    try {
      // Allow value to be a function so we have the same API as useState
      const valueToStore = value instanceof Function ? value(storedValue) : value
      setStoredValue(valueToStore)

      // Save to localStorage
      if (typeof window !== "undefined") {
        window.localStorage.setItem(key, JSON.stringify(valueToStore))
      }
    } catch (error) {
      console.error(`Error setting localStorage key "${key}":`, error)
    }
  }

  return [storedValue, setValue]
}
```

**src/hooks/index.ts**

```typescript
export { useLocalStorage } from './useLocalStorage'
```

### Type Definitions [#type-definitions]

**src/types/index.ts**

```typescript
export interface BaseProps {
  className?: string
  children?: React.ReactNode
}

export type Size = 'sm' | 'md' | 'lg'
export type Variant = 'primary' | 'secondary' | 'outline' | 'ghost'
```

### Main Exports [#main-exports]

**src/components/index.ts**

```typescript
// Components
export * from './Button'
export * from './Card'
```

**src/index.ts**

```typescript
// Components
export * from './components'

// Hooks
export * from './hooks'

// Utils
export * from './utils'

// Types
export * from './types'
```

## Configuration [#configuration]

### package.json [#packagejson]

```json
{
  "name": "@myorg/react-ui",
  "version": "1.0.0",
  "description": "Modern React component library",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./components": {
      "types": "./dist/components/index.d.ts",
      "import": "./dist/components/index.js",
      "require": "./dist/components/index.cjs"
    },
    "./hooks": {
      "types": "./dist/hooks/index.d.ts",
      "import": "./dist/hooks/index.js",
      "require": "./dist/hooks/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils/index.d.ts",
      "import": "./dist/utils/index.js",
      "require": "./dist/utils/index.cjs"
    }
  },
  "sideEffects": [
    "**/*.css"
  ],
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch",
    "clean": "rm -rf dist",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "react",
    "components",
    "ui",
    "typescript",
    "library"
  ],
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "@visulima/packem": "^2",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typescript": "^5.3.0"
  }
}
```

### Packem Configuration [#packem-configuration]

**Quick Setup (Recommended):**

Use the `add` command to automatically configure React:

```bash
npx packem add react
```

This will automatically set up the React preset and install all necessary dependencies.

**packem.config.ts - Using String Preset**

The simplest way to use the React preset is with a string:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react', // Use React preset for Babel configuration
  transformer,
  sourcemap: true,
  declaration: true,
})
```

**packem.config.ts - Using Config Preset Function**

For more control, use the `createReactPreset` function:

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    // Enable React Compiler for automatic optimizations
    compiler: false, // Set to true to enable React Compiler
    
    // Customize Babel presets (optional)
    presets: [
      // Additional presets can be added here
    ],
    
    // Customize Babel plugins (optional)
    plugins: [
      // Additional plugins can be added here
    ]
  }),
  transformer,
  sourcemap: true,
  declaration: true,
})
```

**With React Compiler:**

Enable React Compiler optimizations:

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: true // Enable React Compiler optimization
  }),
  transformer,
  sourcemap: true,
  declaration: true,
})
```

**Alternative: Manual Babel Configuration**

If you need complete control, you can configure Babel manually:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['react', 'react-dom'],
  rollup: {
    babel: {
      presets: [
        ['@babel/preset-react', { runtime: 'automatic' }]
        // Note: TypeScript is handled by the transformer via parser plugins
        // Babel only needs to parse TypeScript syntax, not transform it
      ]
    },
  }
})
```

#### Parallel Babel transforms [#parallel-babel-transforms]

Babel transforms can run across a pool of worker threads to speed up larger builds.
This is enabled automatically: Packem runs transforms in-process for small builds and
spins up workers once enough files match (so small builds and tests don't pay the
worker startup cost).

```typescript
export default defineConfig({
  transformer,
  rollup: {
    babel: {
      presets: [['@babel/preset-react', { runtime: 'automatic' }]],
      // Defaults shown — usually you don't need to set these:
      parallel: true,        // `false` to always transform in-process,
                             // or a number to cap the worker count (default: min(cpus, 4))
      parallelThreshold: 20, // matched files required before workers kick in
    },
  },
})
```

Parallel mode requires fully serializable Babel options. If a non-serializable option
is present (for example a plugin passed as a live function, or a `babel` option supplied
as a function), Packem silently falls back to in-process transforms.

### TypeScript Configuration [#typescript-configuration]

**tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Usage Examples [#usage-examples]

### Basic Usage [#basic-usage]

```typescript
import { Button, Card, CardHeader, CardContent } from '@myorg/react-ui'

function App() {
  return (
    <Card>
      <CardHeader>
        <h2>Welcome</h2>
      </CardHeader>
      <CardContent>
        <p>This is a sample card with a button.</p>
        <Button variant="primary" onClick={() => alert('Clicked!')}>
          Click me
        </Button>
      </CardContent>
    </Card>
  )
}
```

### With Hooks [#with-hooks]

```typescript
import { Button, useLocalStorage } from '@myorg/react-ui'

function Counter() {
  const [count, setCount] = useLocalStorage('counter', 0)

  return (
    <div>
      <p>Count: {count}</p>
      <Button onClick={() => setCount(count + 1)}>
        Increment
      </Button>
    </div>
  )
}
```

### Tree-shakable Imports [#tree-shakable-imports]

```typescript
// Only import what you need
import { Button } from '@myorg/react-ui/components'
import { useLocalStorage } from '@myorg/react-ui/hooks'
import { cn } from '@myorg/react-ui/utils'
```

## Building and Testing [#building-and-testing]

Build the library:

```bash
npm run build
```

### Output Structure [#output-structure]

```
dist/
├── index.js              # ESM main entry
├── index.cjs             # CJS main entry
├── index.d.ts            # TypeScript declarations
├── components/
│   ├── index.js
│   ├── index.cjs
│   ├── index.d.ts
│   ├── Button/
│   │   ├── index.js
│   │   ├── index.cjs
│   │   ├── index.d.ts
│   │   └── Button.module.css
│   └── Card/
│       ├── index.js
│       ├── index.cjs
│       ├── index.d.ts
│       └── Card.module.css
├── hooks/
└── utils/
```

## Key Features [#key-features]

### CSS Modules Support [#css-modules-support]

CSS is automatically processed and scoped:

```typescript
// Styles are automatically imported and scoped
import styles from './Button.module.css'

// Generated class names: Button__button___a1b2c
<button className={styles.button}>Click me</button>
```

### Server Components Ready [#server-components-ready]

Components work in both server and client environments:

```typescript
'use client' // Only when needed for interactivity

export const Button = () => {
  // This works in Next.js App Router
}
```

### Type Safety [#type-safety]

Full TypeScript support with proper component props:

```typescript
<Button
  variant="primary"    // ✅ Valid variant
  size="lg"           // ✅ Valid size
  loading={true}      // ✅ Boolean prop
  onClick={handleClick} // ✅ Event handler
/>
```

### External Dependencies [#external-dependencies]

React and React DOM are properly externalized and won't be bundled.

## Advanced Usage [#advanced-usage]

### Custom Styling [#custom-styling]

```typescript
import { Button } from '@myorg/react-ui'

// Override styles with custom classes
<Button className="my-custom-button" variant="primary">
  Custom Button
</Button>
```

### Compound Components [#compound-components]

```typescript
import { Card, CardHeader, CardContent } from '@myorg/react-ui'

<Card padding="lg" shadow="lg">
  <CardHeader>
    <h3>Card Title</h3>
  </CardHeader>
  <CardContent>
    <p>Card content goes here</p>
  </CardContent>
</Card>
```

<Callout type="info">
  This example provides a solid foundation for React component libraries with modern tooling, proper TypeScript support, and CSS Modules for styling.
</Callout>

## Next Steps [#next-steps]

* Add Storybook for component documentation
* Set up Jest and React Testing Library for testing
* Add accessibility (a11y) features and testing
* Implement dark mode support
* Add more complex components (Modal, Dropdown, etc.)
* Set up automated visual regression testing


# esbuild (/docs/packages/packem/examples/transformers/esbuild)





# esbuild Transformer [#esbuild-transformer]

The **esbuild** transformer is the recommended choice for most Packem projects. Written in Go, it offers the best balance of speed, TypeScript support, and stability.

## Overview [#overview]

This example shows how to build a TypeScript library using the esbuild transformer and how to tune the esbuild-specific options that Packem exposes through `rollup.esbuild`.

esbuild handles:

* TypeScript and modern JavaScript transformation (type stripping, down-leveling)
* JSX (React, Preact, and other runtimes)
* Tree shaking and source maps

<Callout type="info">
  esbuild transforms each file as it passes through Rollup (the default `bundler`). Type checking is **not** performed during transformation — run `tsc --noEmit` separately for type validation.
</Callout>

## When to Use [#when-to-use]

* Most TypeScript and JavaScript libraries
* React applications and component libraries
* Large codebases that need fast rebuilds in watch mode

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-lib/
├── src/
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Packem Configuration [#packem-configuration]

The transformer is selected by importing it and assigning it to `transformer`. esbuild-specific options live under `rollup.esbuild`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      // Optionally preserve symbol names during minification
      // (off by default — opt in only if you rely on runtime name reflection)
      keepNames: true,
      // Override the character set of the output
      charset: 'utf8',
      // Map custom extensions to esbuild loaders
      loaders: {
        '.json': 'json'
      }
    }
  }
})
```

<Callout type="info">
  `target` is resolved automatically from your `tsconfig.json` `compilerOptions.target` and the build runtime, so you usually do not need to set it manually. You can still override it via `rollup.esbuild.target`.
</Callout>

### Minimal Configuration [#minimal-configuration]

When you do not need to customize anything, the transformer alone is enough — Packem provides sensible esbuild defaults (JSX from your tsconfig, tree shaking, smaller source maps):

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer
})
```

## Building [#building]

```bash
packem build
```

## Notes [#notes]

* `keepNames` defaults to `false`. It wraps every named function/closure in an `Object.defineProperty` call, which can slow down closure-heavy code in published builds — opt in only when you need runtime `.name` reflection.
* `keepNames` is also forced off automatically when minification is disabled or the tsconfig target is `es5`, because combining it with repeated transforms breaks tree shaking.
* Source maps follow the top-level `sourcemap` option; esbuild's `sourcesContent` is disabled by default to keep maps small.
* esbuild does not type-check. Pair it with `tsc --noEmit` in CI for type safety.


# OXC (/docs/packages/packem/examples/transformers/oxc)





# OXC Transformer [#oxc-transformer]

The **OXC** transformer is built on the next-generation, Rust-based [oxc](https://oxc.rs) toolchain. It aims to be one of the fastest JavaScript/TypeScript transformers available.

<Callout type="warning">
  OXC is **experimental** and under active development. Some features may be unstable or change between releases — use with caution in production environments.
</Callout>

## Overview [#overview]

This example shows how to select the OXC transformer. OXC compilation is driven almost entirely by your `tsconfig.json` and the build runtime — Packem derives the TypeScript and JSX settings for you, so there is very little to configure by hand.

OXC handles:

* TypeScript transformation (type stripping, down-leveling to a resolved target)
* JSX (classic and automatic runtimes)
* Source maps

## When to Use [#when-to-use]

* Experimental projects willing to adopt bleeding-edge tooling
* Performance research and benchmarking
* Contributing to or evaluating the next generation of JavaScript tooling

For production libraries, prefer **esbuild** or **swc**, which are stable and feature-complete.

## Project Setup [#project-setup]

### TypeScript Configuration [#typescript-configuration]

OXC reads JSX and target settings from your tsconfig. A typical setup:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  }
}
```

### Packem Configuration [#packem-configuration]

Selecting the transformer is all that most projects need — the JSX runtime, pragma, and TypeScript options are resolved from your tsconfig automatically:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/oxc'

export default defineConfig({
  transformer
})
```

<Callout type="info">
  Unlike esbuild, swc, and sucrase, OXC's transform options are managed internally by Packem (target resolution, JSX runtime, TypeScript flags, and source maps are all set from your tsconfig and top-level options). There is no large user-facing `rollup.oxc` block to tune for typical builds.
</Callout>

## Building [#building]

```bash
packem build
```

## Notes [#notes]

* OXC's `target` is resolved from your tsconfig `compilerOptions.target` plus the build runtime, the same way esbuild's target is resolved.
* JSX `refresh` (React Fast Refresh) is disabled — it is not needed for a library build.
* Declaration files are generated by Packem's dedicated declaration plugin, not by OXC.
* Because OXC is experimental, validate your output carefully and consider falling back to esbuild or swc if you hit transformation issues.


# sucrase (/docs/packages/packem/examples/transformers/sucrase)





# sucrase Transformer [#sucrase-transformer]

The **sucrase** transformer is a lightweight, JavaScript-based alternative to Babel. It focuses on speed and simplicity with a deliberately smaller feature set, making it a good fit for straightforward TypeScript projects.

## Overview [#overview]

This example shows how to build a simple TypeScript library with the sucrase transformer. Sucrase options are exposed through `rollup.sucrase`, mapping directly to sucrase's own `transforms` and related options.

sucrase handles:

* TypeScript type stripping
* Basic JSX transformation
* Fast, single-pass compilation with minimal overhead

<Callout type="warning">
  sucrase does **not** support decorators or advanced transformations. If you need decorators or decorator metadata, use the [swc transformer](/docs/packages/packem/examples/transformers/swc) instead.
</Callout>

## When to Use [#when-to-use]

* Simple TypeScript projects without decorators
* Lightweight packages that prioritize a minimal toolchain
* Rapid prototyping, tutorials, and educational projects

## Project Setup [#project-setup]

### Directory Structure [#directory-structure]

```
my-lib/
├── src/
│   └── index.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

### Packem Configuration [#packem-configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/sucrase'

export default defineConfig({
  transformer,
  rollup: {
    sucrase: {
      // Which sucrase transforms to run
      transforms: ['typescript'],
      // Skip down-leveling of modern ES syntax for faster builds
      disableESTransforms: true,
      // Enable production mode (removes development-only JSX output)
      production: true
    }
  }
})
```

For a project that also uses JSX, add the `jsx` transform:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/sucrase'

export default defineConfig({
  transformer,
  rollup: {
    sucrase: {
      transforms: ['typescript', 'jsx'],
      jsxRuntime: 'automatic'
    }
  }
})
```

<Callout type="info">
  Packem already derives a sensible sucrase configuration from your tsconfig — it adds the `jsx` transform automatically when your tsconfig `jsx` option is a React variant, and sets `production` from the build environment. The examples above show the options explicitly so you can see what is configurable.
</Callout>

### Minimal Configuration [#minimal-configuration]

The transformer alone works out of the box for TypeScript projects:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/sucrase'

export default defineConfig({
  transformer
})
```

## Building [#building]

```bash
packem build
```

## Notes [#notes]

* sucrase feeds Rollup, which requires ESM input — Packem therefore never enables the `imports` transform (it would rewrite ESM to `require()` and break Rollup's static module graph).
* By default Packem sets `disableESTransforms: true`, `preserveDynamicImport: true`, and derives `enableLegacyTypeScriptModuleInterop` from your tsconfig `esModuleInterop` setting.
* Source map quality is more basic than esbuild or swc; sucrase is best for projects where compilation speed and simplicity matter more than advanced output features.


# swc (/docs/packages/packem/examples/transformers/swc)





# swc Transformer [#swc-transformer]

The **swc** transformer is a Rust-powered alternative to esbuild with the most comprehensive transformation feature set. It is the best choice when you need decorators — both legacy (`experimentalDecorators`) and the modern stage 3 syntax.

## Overview [#overview]

This example shows how to build a library that uses decorators with the swc transformer. swc options are exposed through `rollup.swc`, including the full `jsc` (JavaScript compiler) configuration.

swc handles:

* TypeScript and modern JavaScript transformation
* Legacy and stage 3 decorators, with optional decorator metadata
* JSX for React, Preact, and other runtimes
* Minification

<Callout type="info">
  Packem automatically externalizes `@swc/helpers` when the swc transformer is active (swc emits imports from it with `externalHelpers: true`). Make sure `@swc/helpers` is available to consumers of your package.
</Callout>

## When to Use [#when-to-use]

* Projects using decorators (legacy or stage 3)
* Code that relies on `emitDecoratorMetadata` (e.g. dependency injection frameworks)
* Applications where build performance is critical and you want the broadest feature coverage

## Project Setup [#project-setup]

### TypeScript Configuration [#typescript-configuration]

Decorator behavior is driven by your `tsconfig.json`. Packem reads these flags and configures swc accordingly:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

### Packem Configuration [#packem-configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  rollup: {
    swc: {
      jsc: {
        // Keep original class names through the transform
        keepClassNames: true,
        parser: {
          syntax: 'typescript',
          // Enable legacy decorator parsing (mirrors experimentalDecorators)
          decorators: true
        },
        transform: {
          // Use the legacy (TypeScript) decorator implementation
          legacyDecorator: true,
          // Emit design:type metadata for reflection
          decoratorMetadata: true
        }
      }
    }
  }
})
```

<Callout type="info">
  Most of the `jsc` block is derived from your tsconfig automatically — `parser.decorators` follows `experimentalDecorators`, `transform.legacyDecorator` follows `experimentalDecorators`, and `transform.decoratorMetadata` follows `emitDecoratorMetadata`. The example above shows the keys explicitly so you can see what Packem configures; you only need to override them when you want different behavior.
</Callout>

### Minimal Configuration [#minimal-configuration]

For projects without special requirements, the transformer alone is enough — Packem applies sensible swc defaults from your tsconfig:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer
})
```

## Building [#building]

```bash
packem build
```

## Notes [#notes]

* swc options are a `jsc`-based configuration object passed via `rollup.swc`; the `configFile`, `filename`, and `swcrc` keys are managed by Packem and cannot be set.
* By default Packem enables `jsc.externalHelpers`, `jsc.keepClassNames`, and `jsc.loose`, and sets the React/JSX options from your tsconfig.
* `sourceMaps` is controlled by the top-level `sourcemap` option and passed through to swc.
* Minification is wired to the top-level `minify` option.


# CLI Reference (/docs/packages/packem/guide/cli)





# CLI Reference [#cli-reference]

Packem exposes four commands: `build`, `init`, `add`, and `migrate`. Run them through your package manager, for example `npx packem build` or `pnpm exec packem build`.

## `packem build` [#packem-build]

Build the package using the resolved packem configuration.

```bash
packem build [options]
```

### General options [#general-options]

| Flag                 | Type   | Description                                                                                                               |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `--dir <path>`       | string | The directory to build. Defaults to `.`.                                                                                  |
| `--config <path>`    | string | Use a custom config file.                                                                                                 |
| `--tsconfig <path>`  | string | Path to the `tsconfig.json` file.                                                                                         |
| `-t, --target <env>` | string | Environments to support. The `target` in `tsconfig.json` is added automatically; defaults to the current Node.js version. |

### Output options [#output-options]

| Flag                  | Type                   | Description                                                                                                |
| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--minify`            | boolean                | Minify the output.                                                                                         |
| `--sourcemap`         | boolean                | Generate source maps (experimental).                                                                       |
| `--dts-only`          | boolean                | Only generate `.d.ts` files.                                                                               |
| `--no-clean`          | boolean                | Do not clean the `dist` directory before building.                                                         |
| `--unbundle`          | boolean                | Preserve the source file structure instead of bundling into a single file.                                 |
| `--exe`               | boolean                | Bundle the output into a standalone executable via Node.js SEA (requires Node.js >= 25.7.0, single entry). |
| `--runtime <runtime>` | `node` \| `browser`    | Specify the build runtime.                                                                                 |
| `--bundler <bundler>` | `rollup` \| `rolldown` | Specify the bundler to use.                                                                                |
| `--cjsInterop`        | boolean                | CJS interop mode — can export default and named exports (experimental).                                    |

### Development options [#development-options]

| Flag                    | Type                   | Description                                                                   |
| ----------------------- | ---------------------- | ----------------------------------------------------------------------------- |
| `--watch`               | boolean                | Watch for changes and rebuild. Conflicts with `--jit`.                        |
| `--jit`                 | boolean                | Stub the package for JIT compilation. Conflicts with `--watch`.               |
| `--onSuccess <command>` | string                 | Execute a command after a successful build (especially useful in watch mode). |
| `--killSignal <signal>` | `SIGTERM` \| `SIGKILL` | Signal used to kill the `onSuccess` child process.                            |

### Environment options [#environment-options]

| Flag                    | Type       | Description                                                                          |
| ----------------------- | ---------- | ------------------------------------------------------------------------------------ |
| `--production`          | boolean    | Run in the production environment. Conflicts with `--development`.                   |
| `--development`         | boolean    | Run in the development environment. Conflicts with `--production`.                   |
| `--env.<KEY>=<value>`   | repeatable | Compile-time environment variables, e.g. `--env.NODE_ENV=production`.                |
| `--env-file <path>`     | string     | Path to a `.env` file to load environment variables from.                            |
| `--env-prefix <prefix>` | string     | Prefix for environment variables loaded from the `.env` file. Defaults to `PACKEM_`. |

<Callout type="info">
  CLI environment variables override values loaded from a `.env` file. The `--env` flag splits on the first `=`, so values that contain `=` (such as URLs with query strings) are preserved.
</Callout>

### Analysis options [#analysis-options]

| Flag               | Type    | Description                                                                                       |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `--analyze`        | boolean | Visualize and analyze the bundle (writes `packem-bundle-analyze.html`). Conflicts with `--watch`. |
| `--metafile`       | boolean | Generate a metadata JSON file per bundle (experimental).                                          |
| `--typedoc`        | boolean | Generate type documentation.                                                                      |
| `--license <path>` | string  | Path to the license file.                                                                         |

### Dependency options [#dependency-options]

| Flag                | Type       | Description                                                                     |
| ------------------- | ---------- | ------------------------------------------------------------------------------- |
| `--external <list>` | repeatable | Mark a dependency as external. Comma-separated, e.g. `--external lodash,react`. |
| `--no-external`     | boolean    | Do not bundle external dependencies.                                            |

### Other flags [#other-flags]

| Flag              | Type    | Description                |
| ----------------- | ------- | -------------------------- |
| `--no-validation` | boolean | Disable output validation. |
| `--no-cache`      | boolean | Disable the file cache.    |

<Callout type="info">
  `--no-validation` overrides validation supplied by a preset, but not validation you set explicitly in `packem.config.ts`.
</Callout>

### Examples [#examples]

```bash
# Build for production (minifies automatically)
packem build --production

# Watch with development environment
packem build --watch --development

# Inject a compile-time variable
packem build --env.API_URL=https://api.example.com

# Use the experimental rolldown bundler
packem build --bundler rolldown
```

## `packem init` [#packem-init]

Initialize packem configuration. Runs an interactive wizard that detects your project and writes a `packem.config.ts` (or `.js`) file.

```bash
packem init [options]
```

| Flag                   | Type                            | Description                                   |
| ---------------------- | ------------------------------- | --------------------------------------------- |
| `--dir <path>`         | string                          | The directory to initialize. Defaults to `.`. |
| `--transformer <name>` | `esbuild` \| `swc` \| `sucrase` | Choose a transformer.                         |
| `--runtime <runtime>`  | `node` \| `browser`             | Specify the build runtime.                    |
| `--css`                | boolean                         | Set up CSS support.                           |
| `--css-minifier`       | boolean                         | Set up a CSS minifier.                        |
| `--typescript`         | boolean                         | Use TypeScript.                               |

The wizard asks about TypeScript, the build runtime, the transformer, and optional CSS loaders/minifiers, installs the matching dependencies, and writes the config file.

## `packem add` [#packem-add]

Add an optional feature to an existing packem project. The feature is passed as an argument and the command edits your existing config file in place.

```bash
packem add <feature> [options]
```

Supported features: `typedoc`, `react`, `solid`, `preact`, `vue`, `svelte`, `css`.

| Flag              | Type   | Description                             |
| ----------------- | ------ | --------------------------------------- |
| `--dir <path>`    | string | The project directory. Defaults to `.`. |
| `--config <path>` | string | Use a custom config file.               |

Framework features (`react`, `solid`, `preact`, `vue`, `svelte`) add the matching preset to your config and install the required dependencies. `css` runs an interactive loader/minifier selection. `typedoc` wires up the TypeDoc builder.

```bash
npx packem add react
npx packem add css
npx packem add typedoc
```

<Callout type="info">
  If the git working tree has uncommitted changes, `add` asks for confirmation before editing the config, since the edit cannot be cleanly undone otherwise.
</Callout>

## `packem migrate` [#packem-migrate]

Migrate a project from another bundler (tsup, unbuild, bunchee) to packem. The command rewrites bundler dependencies and `package.json` build scripts to use packem.

```bash
packem migrate [options]
```

| Flag           | Type    | Description                                |
| -------------- | ------- | ------------------------------------------ |
| `--cwd <path>` | string  | The directory to migrate. Defaults to `.`. |
| `--dry-run`    | boolean | Preview changes without applying them.     |

<Callout type="warning">
  `migrate` modifies your files and warns that uncommitted changes may be lost. Use `--dry-run` first to preview the changes. Bundler config files (such as `tsup.config.ts`) are reported but not migrated automatically — they require manual conversion to `packem.config.ts`.
</Callout>

```bash
# Preview the migration
packem migrate --dry-run

# Apply the migration
packem migrate
```

## Next steps [#next-steps]

* [Getting Started](/docs/packages/packem/guide/getting-started) — install packem and run your first build.
* [Watch Mode](/docs/packages/packem/guide/watch-mode) — the development workflow.
* [Configuration](/docs/packages/packem/guide/configuration) — configure the build.


# Configuration (/docs/packages/packem/guide/configuration)





# Configuration [#configuration]

Learn how to configure Packem to meet your specific project requirements with detailed examples and best practices.

## Configuration File [#configuration-file]

Packem uses a `packem.config.ts` file for configuration. This file should be placed in your project root.

### Basic Configuration [#basic-configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true
})
```

## Configuration Options [#configuration-options]

### Core Options [#core-options]

#### transformer [#transformer]

Specify which transformer to use for code compilation:

```typescript
// esbuild (default, fastest)
import esbuild from '@visulima/packem/transformer/esbuild'

// swc (Rust-powered)
import swc from '@visulima/packem/transformer/swc'

// OXC (experimental)
import oxc from '@visulima/packem/transformer/oxc'

// sucrase (lightweight)
import sucrase from '@visulima/packem/transformer/sucrase'

export default defineConfig({
  transformer: esbuild // or swc, oxc, sucrase
})
```

#### bundler [#bundler]

Choose the bundler backend. Rollup is the default and fully-supported path; the
experimental [Rolldown](https://rolldown.rs) backend is opt-in:

```typescript
export default defineConfig({
  bundler: 'rollup',   // default
  // or
  bundler: 'rolldown', // experimental — omit `transformer`, DTS still routes through Rollup
})
```

See the [bundler option](/docs/packages/packem/options/bundler) for the full Rolldown caveats.

#### sourcemap [#sourcemap]

Control source map generation:

```typescript
export default defineConfig({
  sourcemap: true,        // Generate source maps
  sourcemap: false,       // No source maps
  sourcemap: 'inline',    // Inline source maps
  sourcemap: 'hidden'     // Hidden source maps
})
```

#### declaration [#declaration]

Generate TypeScript declaration files:

```typescript
export default defineConfig({
  declaration: true,      // Generate .d.ts files
  declaration: false,     // Skip declaration generation
  declaration: 'compatible', // Generate compatible declarations
  declaration: 'node16'   // Generate node16 declarations
})
```

#### minify [#minify]

Control code minification:

```typescript
export default defineConfig({
  minify: true,           // Enable minification
  minify: false,          // Disable minification
})
```

#### banner / footer [#banner--footer]

Prepend (`banner`) or append (`footer`) text to the build output — useful for
license headers, runtime directives, or shims. The values map onto Rollup/Rolldown's
`output.banner` / `output.footer`, so both bundler backends honour them and they apply
to **both** the CommonJS and ESM bundles.

```typescript
export default defineConfig({
  // A bare string (or function) targets the JS output only:
  banner: "/*! my-lib v1.0.0 | MIT */",
  footer: (chunk) => `/* built ${chunk.fileName} */`,
})
```

Use the object form to target the JavaScript bundle (`js`) and the generated
declaration files (`dts`) independently:

```typescript
export default defineConfig({
  banner: {
    js: "'use client';",
    dts: "// AUTO-GENERATED — do not edit",
  },
})
```

<Callout type="info">
  A bare `banner`/`footer` value never touches the declaration files — opt declarations in
  explicitly via the `{ dts }` form. An explicit `rollup.dts.banner`/`footer` takes
  precedence over the top-level option.
</Callout>

### Entry Points [#entry-points]

#### Automatic Detection [#automatic-detection]

Packem automatically detects entry points from your `package.json`:

```json
{
  "exports": {
    ".": "./src/index.ts",
    "./utils": "./src/utils.ts"
  }
}
```

#### Manual Configuration [#manual-configuration]

Override automatic detection:

```typescript
export default defineConfig({
  entries: [
    'src/index.ts',
    'src/cli.ts',
    'src/utils.ts'
  ]
})
```

#### Entry Objects [#entry-objects]

Use objects for more control:

```typescript
export default defineConfig({
  entries: [
    {
      input: 'src/index.ts',
      outDir: 'dist'
    },
    {
      input: 'src/cli.ts',
      outDir: 'dist/bin'
    }
  ]
})
```

### Rollup Configuration [#rollup-configuration]

Packem is built on Rollup, so you can use any Rollup options:

```typescript
export default defineConfig({
  rollup: {
    external: ['react', 'react-dom'],
    output: {
      banner: '/* My Library v1.0.0 */',
      footer: '/* End of bundle */'
    },
    plugins: [
      // Additional Rollup plugins
    ],
    watch: {
      include: 'src/**',
      exclude: 'node_modules/**'
    }
  }
})
```

### CSS Configuration [#css-configuration]

**Quick Setup:**

Use the `add` command to interactively configure CSS loaders:

```bash
npx packem add css
```

This will:

* Prompt you to select a main CSS loader (PostCSS, Lightning CSS, or Tailwind CSS)
* Ask about additional loaders (Sass, Less, Stylus)
* Optionally configure CSS minification
* Install all necessary dependencies
* Update your `packem.config.ts` automatically

**Manual Configuration:**

```typescript
import postcssLoader from '@visulima/packem/css/loader/postcss'
import sassLoader from '@visulima/packem/css/loader/sass'
import lessLoader from '@visulima/packem/css/loader/less'
import stylusLoader from '@visulima/packem/css/loader/stylus'
import sourceMapLoader from '@visulima/packem/css/loader/sourcemap'
import cssnanoMinifier from '@visulima/packem/css/minifier/cssnano'
import lightningcssMinifier from '@visulima/packem/css/minifier/lightningcss'

export default defineConfig({
  rollup: {
    css: {
      mode: 'extract', // or 'inject'
      loaders: [postcssLoader, sassLoader, lessLoader, stylusLoader, sourceMapLoader],
      minifier: cssnanoMinifier
    }
  }
})
```

### Native Modules Configuration [#native-modules-configuration]

Configure native Node.js addon (.node files) handling:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  rollup: {
    nativeModules: {
      nativesDirectory: 'natives' // Custom directory name
    }
  }
})
```

The native modules plugin automatically:

* Detects `.node` file imports
* Copies native modules to the output directory
* Generates appropriate `require()` statements
* Handles name collisions and platform-specific files

**Options:**

* `nativesDirectory`: Directory name for native modules (default: `'natives'`)

After bundling, the `.node` file will be copied to `dist/natives/` and the import will be automatically rewritten to load from the correct location at runtime.

> \[!NOTE]
>
> * Native modules are platform and architecture-specific. Make sure to distribute the correct `.node` files for your target platforms.
> * This only works with direct `.node` imports. If you're using packages that dynamically load native modules via `bindings` or `node-pre-gyp`, you'll need to handle them separately.

#### Handling dependencies with native modules [#handling-dependencies-with-native-modules]

If you're using packages with native modules (like `chokidar` which depends on `fsevents`):

* **If in `dependencies`/`peerDependencies`**: ✅ Works automatically - these are externalized (not bundled)
* **If in `devDependencies`**: ⚠️ Will be bundled. If they use `bindings()` or `node-pre-gyp` patterns, move them to `dependencies` instead, or use `optionalDependencies` if they're optional.

Example - if you have `chokidar` in `devDependencies` and get build errors, move it to `dependencies`:

```json
{
    "dependencies": {
        "chokidar": "^3.0.0"
    }
}
```

This externalizes it (users will need to install it), avoiding the need to bundle its native modules.

## Advanced Configurations [#advanced-configurations]

### Multi-Format Builds [#multi-format-builds]

Build multiple output formats by configuring package.json properly:

```json
{
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}
```

### Environment-Specific Config [#environment-specific-config]

```typescript
const isDev = process.env.NODE_ENV === 'development'

export default defineConfig({
  sourcemap: isDev,
  minify: !isDev,
  declaration: !isDev,
  rollup: {
    watch: isDev ? {
      include: 'src/**'
    } : undefined
  }
})
```

### Conditional Configuration [#conditional-configuration]

```typescript
import esbuildTransformer from '@visulima/packem/transformer/esbuild'
import swcTransformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer: process.env.TRANSFORMER === 'swc'
    ? swcTransformer
    : esbuildTransformer,

  externals: process.env.BUNDLE_DEPS
    ? []
    : ['react', 'react-dom']
})
```

### Library-Specific Configurations [#library-specific-configurations]

#### React Library [#react-library]

**Quick Setup (Recommended):**

Use the `add` command to automatically configure React:

```bash
npx packem add react
```

This will:

* Add `preset: 'react'` to your config
* Install React, React DOM, and Babel dependencies
* Automatically detect TypeScript and add `@types/react` and `@types/react-dom` if TypeScript is installed
* Prompt you to add TypeScript if not already installed

**Manual Configuration:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react', // Automatically configures Babel for React
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['react', 'react-dom'],
  rollup: {
    css: {
      mode: 'extract'
    }
  }
})
```

**With React Compiler:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: true // Enable React Compiler optimization
  }),
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['react', 'react-dom'],
  rollup: {
    css: {
      mode: 'extract'
    }
  }
})
```

**Manual Configuration:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['react', 'react-dom'],
  rollup: {
    babel: {
      presets: [
        ['@babel/preset-react', { runtime: 'automatic' }],
        ['@babel/preset-typescript', { allExtensions: true, isTSX: true }]
      ]
    },
    css: {
      mode: 'extract'
    }
  }
})
```

#### SolidJS Library [#solidjs-library]

**Quick Setup (Recommended):**

Use the `add` command to automatically configure SolidJS:

```bash
npx packem add solid
```

This will:

* Add `preset: 'solid'` to your config
* Install SolidJS and Babel dependencies

**Manual Configuration:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'solid', // Automatically configures Babel for SolidJS
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['solid-js', 'solid-js/web', 'solid-js/store'],
  rollup: {
    css: {
      mode: 'extract'
    }
  }
})
```

**With SSR Support:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createSolidPreset } from '@visulima/packem/config/preset/solid'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createSolidPreset({
    solidOptions: {
      generate: 'ssr',
      hydratable: true
    }
  }),
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['solid-js', 'solid-js/web', 'solid-js/store'],
  rollup: {
    css: {
      mode: 'extract'
    }
  }
})
```

**Manual Configuration:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  declaration: true,
  externals: ['solid-js', 'solid-js/web', 'solid-js/store'],
  rollup: {
    babel: {
      presets: [
        ['babel-preset-solid', { generate: 'dom' }],
        ['@babel/preset-typescript', { allExtensions: true, isTSX: true }],
        ['@babel/preset-env', { bugfixes: true, targets: 'last 2 years' }]
      ]
    },
    css: {
      mode: 'extract'
    }
  }
})
```

#### Node.js Library [#nodejs-library]

```typescript
export default defineConfig({
  transformer,
  runtime: 'node',
  externals: (id) => !id.startsWith('.') && !id.startsWith('/')
})
```

#### CLI Tool [#cli-tool]

```typescript
export default defineConfig({
  entries: [
    {
      input: 'src/cli.ts',
      executable: true
    }
  ],
  externals: ['fs', 'path', 'process']
})
```

#### Browser Library [#browser-library]

```typescript
export default defineConfig({
  transformer,
  runtime: 'browser',
  minify: true
})
```

## Configuration Patterns [#configuration-patterns]

### Shared Configuration [#shared-configuration]

Create reusable configuration:

```typescript
// config/base.ts
export const baseConfig = {
  transformer,
  sourcemap: true,
  declaration: true
}

// packem.config.ts
import { baseConfig } from './config/base'

export default defineConfig({
  ...baseConfig,
  // Project-specific overrides
})
```

### Factory Functions [#factory-functions]

```typescript
// config/factory.ts
export function createConfig(options: {
  runtime: 'node' | 'browser'
}) {
  return defineConfig({
    transformer,
    runtime: options.runtime,
    minify: options.runtime === 'browser',
    rollup: {
      external: options.runtime === 'node'
        ? (id) => !id.startsWith('.')
        : []
    }
  })
}

// packem.config.ts
import { createConfig } from './config/factory'

export default createConfig({
  runtime: 'node'
})
```

<Callout type="info">
  Output formats (CommonJS / ESM) are derived from your `package.json` `exports`,
  `main`, and `module` fields — there is no top-level `format` or `target` option.
  Set the JavaScript language target via `rollup.esbuild.target`, your `tsconfig.json`,
  or `browserTargets`.
</Callout>

### Plugin System [#plugin-system]

```typescript
// plugins/banner.ts
export function bannerPlugin(text: string) {
  return {
    rollup: {
      output: {
        banner: text
      }
    }
  }
}

// packem.config.ts
export default defineConfig({
  transformer,
  ...bannerPlugin('/* My Library */'),
})
```

## TypeScript Integration [#typescript-integration]

### Declaration Files [#declaration-files]

Generate TypeScript declaration files alongside your bundle:

```typescript
export default defineConfig({
  transformer,
  declaration: true, // 'compatible' | 'node16' | false also accepted
})
```

See the [declaration option](#declaration) above for the meaning of each value.

### Path Mapping [#path-mapping]

Packem reads your `tsconfig.json` automatically and resolves TypeScript path
mappings. Configure the paths in `tsconfig.json`:

```json
// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}
```

Path resolution is enabled by default. To resolve mapped paths to absolute
paths, enable the `rollup.tsconfigPaths` plugin option:

```typescript
export default defineConfig({
  transformer,
  rollup: {
    tsconfigPaths: {
      resolveAbsolutePath: true
    }
  }
})
```

## Debugging Configuration [#debugging-configuration]

### Verbose Output [#verbose-output]

Enable debug mode for verbose logging during the build:

```typescript
export default defineConfig({
  transformer,
  debug: true
})
```

### Bundle Analysis [#bundle-analysis]

```typescript
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      visualizer({
        filename: 'dist/stats.html',
        open: true
      })
    ]
  }
})
```

## Best Practices [#best-practices]

### Performance Optimization [#performance-optimization]

```typescript
export default defineConfig({
  transformer: esbuild, // Fastest transformer
  sourcemap: false,     // Disable in production
  declaration: 'node16', // Emit only .d.mts + .d.cts (skip the extra .d.ts)
  rollup: {
    treeshake: true,    // Enable tree shaking
    external: [         // Externalize dependencies
      'react',
      'react-dom'
    ]
  }
})
```

### Development Experience [#development-experience]

```typescript
const isDev = process.env.NODE_ENV === 'development'

export default defineConfig({
  sourcemap: isDev ? true : false,
  declaration: !isDev,
  rollup: {
    watch: isDev ? {
      include: 'src/**',
      clearScreen: false
    } : undefined
  }
})
```

<Callout type="info">
  Always test your configuration with both development and production builds to ensure everything works correctly.
</Callout>

## Common Issues [#common-issues]

### External Dependencies [#external-dependencies]

Make sure to externalize peer dependencies:

```typescript
export default defineConfig({
  rollup: {
    external: ['react', 'react-dom', 'lodash']
  }
})
```

### CSS Processing [#css-processing]

Configure CSS loaders properly:

```typescript
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  rollup: {
    css: {
      mode: 'extract',     // Extract CSS to a separate file ('inject' is the default)
      autoModules: true,   // Treat *.module.css files as CSS modules
      loaders: [postcssLoader]
    }
  }
})
```

### Declaration Generation [#declaration-generation]

Ensure TypeScript configuration is correct:

```typescript
// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist"
  }
}
```

This configuration guide provides a comprehensive foundation for setting up Packem in any project scenario.


# CSS Processing (/docs/packages/packem/guide/css)





# CSS Processing [#css-processing]

Packem provides first-class support for CSS and all major CSS preprocessors. From vanilla CSS to advanced CSS Modules, Packem handles all your styling needs through the [`@visulima/rollup-plugin-css`](/docs/packages/packem/api/rollup-plugin-css) plugin.

CSS options are configured under `rollup.css` and are typed as `StyleOptions` from `@visulima/rollup-plugin-css`. The CSS loaders and minifiers ship with Packem and are imported from the `@visulima/packem/css/loader/*` and `@visulima/packem/css/minifier/*` sub-paths. Register a loader by adding it to the `loaders` array.

## Supported CSS Technologies [#supported-css-technologies]

<div className="feature-grid">
  <div className="feature-card">
    <h3>
      CSS
    </h3>

    <p>
      Standard CSS with PostCSS processing and optimization
    </p>
  </div>

  <div className="feature-card">
    <h3>
      Sass/SCSS
    </h3>

    <p>
      Sass and SCSS preprocessing with Dart Sass or Embedded Sass
    </p>
  </div>

  <div className="feature-card">
    <h3>
      Less
    </h3>

    <p>
      Less preprocessing with full feature support
    </p>
  </div>

  <div className="feature-card">
    <h3>
      Stylus
    </h3>

    <p>
      Stylus preprocessing with expressive syntax
    </p>
  </div>

  <div className="feature-card">
    <h3>
      PostCSS
    </h3>

    <p>
      PostCSS with autoprefixer and plugin ecosystem
    </p>
  </div>

  <div className="feature-card">
    <h3>
      CSS Modules
    </h3>

    <p>
      Scoped CSS with automatic class name generation
    </p>
  </div>

  <div className="feature-card">
    <h3>
      Lightning CSS
    </h3>

    <p>
      Fast CSS parsing, transformation, and minification
    </p>
  </div>

  <div className="feature-card">
    <h3>
      cssnano
    </h3>

    <p>
      Advanced CSS minification and optimization
    </p>
  </div>
</div>

## Basic CSS Support [#basic-css-support]

Packem processes CSS files imported in your JavaScript/TypeScript code. Register the PostCSS loader to enable plain `.css` processing:

```typescript
// src/index.ts
import './styles.css'

export function createButton() {
  const button = document.createElement('button')
  button.className = 'btn btn-primary'
  button.textContent = 'Click me'
  return button
}
```

```css
/* src/styles.css */
.btn {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;
}

.btn-primary {
  background-color: #007bff;
  color: white;
}
```

## Configuration [#configuration]

Configure CSS processing in your `packem.config.ts`. The PostCSS loader requires `postcss` to be installed.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
    },
  },
})
```

### Available `css` options [#available-css-options]

The `css` option accepts the following keys (typed as `StyleOptions`):

* `mode` — how CSS is delivered: `"inject"` (default), `"extract"`, `"emit"`, or `"inline"`. See [Output Modes](#output-modes).
* `loaders` — array of CSS loaders to register (PostCSS, Sass, Less, Stylus, Lightning CSS, Tailwind CSS).
* `autoModules` — enable CSS Modules for `*.module.*` files. Accepts a boolean, RegExp, or function (`@default false`).
* `minifier` — a minifier object (cssnano or Lightning CSS). See [Minification](#minification).
* `cssnano` — options for the cssnano minifier.
* `lightningcss` — options for Lightning CSS.
* `postcss` — PostCSS options (plugins, modules, etc.).
* `sass` / `less` / `stylus` — preprocessor loader options.
* `extensions` — file extensions to process (`@default [".css", ".pcss", ".postcss", ".sss"]`).
* `include` / `exclude` — file filters (RegExp, string, or array).
* `alias` — URL and import path aliases.
* `sourceMap` — source map control: `boolean`, `"inline"`, or a tuple with `SourceMapOptions` (`@default false`).
* `dts` — generate `.d.ts` files for style imports.
* `namedExports` — export each class as a named binding (`@default false`).
* `onImport` / `onExtract` — lifecycle callbacks.

## Sass/SCSS [#sassscss]

Packem supports both Sass and SCSS syntax with Dart Sass or Embedded Sass.

### Installation [#installation]

<Tabs items="['Dart Sass', 'Embedded Sass']">
  <Tab value="Dart Sass">
    ```bash
    npm install --save-dev sass
    ```
  </Tab>

  <Tab value="Embedded Sass">
    ```bash
    npm install --save-dev sass-embedded
    ```
  </Tab>
</Tabs>

### Usage [#usage]

```scss
// src/styles.scss
$primary-color: #007bff;
$border-radius: 0.25rem;

@mixin button-style($bg-color) {
  background-color: $bg-color;
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: $border-radius;
  cursor: pointer;

  &:hover {
    background-color: darken($bg-color, 10%);
  }
}

.btn-primary {
  @include button-style($primary-color);
}
```

### Configuration [#configuration-1]

Register the Sass loader and pass options on the `sass` key. The Sass options are passed directly to the Dart Sass / Embedded Sass compiler. Select the implementation with `implementation` (`"sass"` or `"sass-embedded"`).

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import sassLoader from '@visulima/packem/css/loader/sass'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [sassLoader],
      sass: {
        implementation: 'sass', // or 'sass-embedded'
        style: 'compressed',
        loadPaths: ['node_modules', 'src/styles'],
      },
    },
  },
})
```

## Less [#less]

Less preprocessing with full feature support.

### Installation [#installation-1]

```bash
npm install --save-dev less
```

### Usage [#usage-1]

```less
// src/styles.less
@primary-color: #007bff;
@border-radius: 0.25rem;

.button-style(@bg-color) {
  background-color: @bg-color;
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: @border-radius;
  cursor: pointer;

  &:hover {
    background-color: darken(@bg-color, 10%);
  }
}

.btn-primary {
  .button-style(@primary-color);
}
```

### Configuration [#configuration-2]

Register the Less loader and pass Less.js compiler options directly on the `less` key.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import lessLoader from '@visulima/packem/css/loader/less'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lessLoader],
      less: {
        math: 'parens-division',
        paths: ['node_modules', 'src/styles'],
      },
    },
  },
})
```

## Stylus [#stylus]

Stylus preprocessing with expressive syntax.

### Installation [#installation-2]

```bash
npm install --save-dev stylus
```

### Usage [#usage-2]

```stylus
// src/styles.styl
primary-color = #007bff
border-radius = 0.25rem

button-style(bg-color)
  background-color bg-color
  color white
  padding 0.5rem 1rem
  border none
  border-radius border-radius
  cursor pointer

  &:hover
    background-color darken(bg-color, 10%)

.btn-primary
  button-style(primary-color)
```

### Configuration [#configuration-3]

Register the Stylus loader and pass Stylus render options directly on the `stylus` key.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import stylusLoader from '@visulima/packem/css/loader/stylus'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [stylusLoader],
      stylus: {
        compress: true,
        paths: ['node_modules', 'src/styles'],
        use: ['nib'],
      },
    },
  },
})
```

## PostCSS [#postcss]

PostCSS processing with plugin ecosystem support.

### Installation [#installation-3]

```bash
npm install --save-dev postcss postcss-load-config
```

### Configuration [#configuration-4]

Create a `postcss.config.js` file:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer'),
    require('postcss-custom-properties'),
    require('cssnano')({
      preset: 'default'
    })
  ]
}
```

Or configure directly in Packem on the `postcss` key:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      postcss: {
        plugins: [
          'autoprefixer',
          ['postcss-custom-properties', { preserve: false }],
          ['cssnano', { preset: 'default' }]
        ]
      }
    }
  }
})
```

### Popular PostCSS Plugins [#popular-postcss-plugins]

* **autoprefixer** - Add vendor prefixes automatically
* **postcss-custom-properties** - CSS custom properties support
* **postcss-nested** - Nested CSS rules
* **postcss-import** - Inline @import rules
* **tailwindcss** - Utility-first CSS framework

## CSS Modules [#css-modules]

CSS Modules provide locally scoped CSS to avoid naming conflicts. Enable them with the `autoModules` option, which applies to files named `[name].module.[ext]` (for example `Button.module.css`).

### Enable CSS Modules [#enable-css-modules]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      autoModules: true,
    },
  },
})
```

To restrict CSS Modules to a custom pattern, pass a regular expression to `autoModules`. Module name generation is customized through `postcss.modules`:

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      autoModules: /\.module\./,
      postcss: {
        modules: {
          generateScopedName: '[name]__[local]___[hash:base64:5]',
          exportGlobals: true,
        },
      },
    },
  },
})
```

<Callout type="info">
  You can also enable modules through `postcss.modules` directly (set it to `true`
  or an options object) instead of using `autoModules`.
</Callout>

### Usage [#usage-3]

```css
/* src/Button.module.css */
.button {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;
}

.primary {
  background-color: #007bff;
  color: white;
}

.secondary {
  background-color: #6c757d;
  color: white;
}
```

```typescript
// src/Button.ts
import styles from './Button.module.css'

export function createButton(variant: 'primary' | 'secondary' = 'primary') {
  const button = document.createElement('button')
  button.className = `${styles.button} ${styles[variant]}`
  button.textContent = 'Click me'
  return button
}
```

### CSS Modules with TypeScript [#css-modules-with-typescript]

Set the `dts` option to generate companion `.d.ts` files alongside your CSS Modules, giving you IntelliSense and compile-time checks for class names.

```typescript
css: {
  mode: 'extract',
  loaders: [postcssLoader],
  autoModules: true,
  dts: true,
}
```

This emits a declaration file next to each module:

```typescript
// src/Button.module.css.d.ts (auto-generated)
declare const button: string
declare const primary: string
declare const secondary: string

interface ModulesExports {
  button: string
  primary: string
  secondary: string
}

declare const styles: ModulesExports
export default styles
export { button, primary, secondary }
```

### Named Exports [#named-exports]

Enable `namedExports` to export each class as a named binding alongside the default export:

```typescript
css: {
  loaders: [postcssLoader],
  autoModules: true,
  namedExports: true,
}
```

## Lightning CSS [#lightning-css]

Lightning CSS provides fast CSS parsing, transformation, and minification, written in Rust. It can be used as a loader, and as a minifier (see [Minification](#minification)).

### Installation [#installation-4]

```bash
npm install --save-dev lightningcss
```

### Configuration [#configuration-5]

Register the Lightning CSS loader and pass Lightning CSS transform options on the `lightningcss` key. Browser targets are derived from your project's browserslist configuration.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import lightningcssLoader from '@visulima/packem/css/loader/lightningcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lightningcssLoader],
      lightningcss: {
        drafts: {
          customMedia: true,
        },
      },
    },
  },
})
```

<Callout type="info">
  The `targets`, `minify`, `code`, `filename`, and `cssModules` Lightning CSS
  options are managed by Packem internally and are not configurable through the
  `lightningcss` key. Browser targets come from your browserslist configuration.
</Callout>

### Features [#features]

* **Fast parsing** - Written in Rust for maximum performance
* **Modern CSS** - Support for CSS nesting, custom media queries, etc.
* **Browser targets** - Automatic feature detection based on your browserslist
* **Minification** - Built-in CSS minification when used as a minifier

## Minification [#minification]

CSS minification is enabled by passing a **minifier object** to the `minifier` option. Packem ships two built-in minifiers as importable sub-paths:

* `@visulima/packem/css/minifier/cssnano` — cssnano (requires `cssnano` installed)
* `@visulima/packem/css/minifier/lightningcss` — Lightning CSS (requires `lightningcss` installed)

<Callout type="warn">
  There is no boolean `minify` / `minimize` option for CSS. Minification is opt-in
  by assigning a minifier object to `minifier`.
</Callout>

### cssnano [#cssnano]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import cssnanoMinifier from '@visulima/packem/css/minifier/cssnano'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      minifier: cssnanoMinifier,
      cssnano: {
        preset: ['default', {
          discardComments: { removeAll: true },
        }],
      },
    },
  },
})
```

### Lightning CSS [#lightning-css-1]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import lightningcssMinifier from '@visulima/packem/css/minifier/lightningcss'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      minifier: lightningcssMinifier,
    },
  },
})
```

## Output Modes [#output-modes]

The `mode` option controls how CSS reaches the bundle. The default is `"inject"`.

### Extract [#extract]

Writes CSS to a separate `.css` file next to the generated JS.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
    },
  },
})
```

To extract to a fixed file name (relative to the output directory), use the tuple form:

```typescript
css: {
  mode: ['extract', 'styles.css'],
  loaders: [postcssLoader],
}
```

### Inject (default) [#inject-default]

Embeds the CSS inside the JavaScript bundle and injects it into `<head>` at runtime. This requires `@visulima/css-style-inject` to be installed.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'inject',
      loaders: [postcssLoader],
    },
  },
})
```

```bash
npm install --save-dev @visulima/css-style-inject
```

You can also pass injector options or your own injector function with the tuple form `['inject', options | fn]`.

### Inline [#inline]

Embeds the processed CSS as a string export in the JavaScript module without runtime injection.

```typescript
css: {
  mode: 'inline',
  loaders: [postcssLoader],
}
```

### Emit [#emit]

Emits pure processed CSS and passes it along the build pipeline. Useful for preprocessing CSS before it is consumed by other plugins.

```typescript
css: {
  mode: 'emit',
  loaders: [postcssLoader],
}
```

### Runtime Injection [#runtime-injection]

When using `inject` mode, Packem relies on `@visulima/css-style-inject`. You can also call it directly for dynamic, runtime-generated styles:

```typescript
import { injectStyles } from '@visulima/css-style-inject'

const css = `
  .dynamic-styles {
    color: red;
    font-weight: bold;
  }
`

injectStyles(css, {
  id: 'dynamic-styles',
  prepend: false
})
```

## Source Maps [#source-maps]

Enable CSS source maps with the `sourceMap` option:

```typescript
css: {
  mode: 'extract',
  loaders: [postcssLoader],
  sourceMap: true, // or 'inline'
}
```

You can also pass a tuple with `SourceMapOptions`, e.g. `sourceMap: [true, { /* options */ }]`.

## Advanced Features [#advanced-features]

### CSS Custom Properties [#css-custom-properties]

```css
:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --border-radius: 0.25rem;
}

.btn {
  background-color: var(--primary-color);
  border-radius: var(--border-radius);
}
```

### CSS Nesting (with PostCSS or Lightning CSS) [#css-nesting-with-postcss-or-lightning-css]

```css
.card {
  padding: 1rem;
  border: 1px solid #dee2e6;

  .title {
    font-size: 1.25rem;
    font-weight: bold;
    margin-bottom: 0.5rem;
  }

  .content {
    color: #6c757d;

    p {
      margin-bottom: 1rem;

      &:last-child {
        margin-bottom: 0;
      }
    }
  }
}
```

### Container Queries [#container-queries]

```css
.card {
  container-type: inline-size;
}

@container (min-width: 400px) {
  .card-content {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 1rem;
  }
}
```

## Framework Integration [#framework-integration]

### React [#react]

```tsx
// React with CSS Modules
import styles from './Button.module.css'

interface ButtonProps {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
}

export function Button({ variant = 'primary', children }: ButtonProps) {
  return (
    <button className={`${styles.button} ${styles[variant]}`}>
      {children}
    </button>
  )
}
```

### Vue [#vue]

```vue
<template>
  <button :class="[styles.button, styles[variant]]">
    <slot />
  </button>
</template>

<script setup lang="ts">
import styles from './Button.module.css'

interface Props {
  variant?: 'primary' | 'secondary'
}

withDefaults(defineProps<Props>(), {
  variant: 'primary'
})
</script>
```

## Troubleshooting [#troubleshooting]

### CSS Not Loading [#css-not-loading]

1. **Check imports** - Ensure CSS files are imported in your JavaScript/TypeScript
2. **Register a loader** - Add the relevant loader (e.g. `postcssLoader`) to the `loaders` array
3. **Verify file paths** - Check that CSS file paths are correct

### Preprocessor Errors [#preprocessor-errors]

1. **Install dependencies** - Make sure preprocessor packages are installed (`sass`, `less`, `stylus`)
2. **Register the loader** - Add the matching loader to `css.loaders`
3. **Check syntax** - Verify preprocessor syntax is correct

### CSS Modules Not Working [#css-modules-not-working]

1. **Enable CSS Modules** - Set `css.autoModules: true` (or configure `css.postcss.modules`)
2. **File naming** - Use the `.module.css` suffix for CSS Modules files
3. **Import syntax** - Use `import styles from './file.module.css'`

### Performance Issues [#performance-issues]

1. **Enable minification** - Assign a minifier to `css.minifier`
2. **Extract CSS** - Use `css.mode: 'extract'` for better caching
3. **Optimize imports** - Remove unused CSS imports
4. **Use Lightning CSS** - Switch to the Lightning CSS loader/minifier for better performance

<Callout type="tip">
  Use `packem build --verbose` to see detailed CSS processing information and identify issues.
</Callout>

## Examples [#examples]

Check out our CSS examples:

* [Basic CSS Processing](/docs/packages/packem/examples/css/basic)
* [Sass/SCSS Integration](/docs/packages/packem/examples/css/sass)
* [CSS Modules](/docs/packages/packem/examples/css/modules)
* [PostCSS Configuration](/docs/packages/packem/examples/css/postcss)
* [Lightning CSS](/docs/packages/packem/examples/css/lightningcss)
* [React with CSS Modules](/docs/packages/packem/examples/react/css-modules)

***

Need more help? Check the [CSS troubleshooting guide](/docs/packages/packem/guide/troubleshooting/css) or explore [CSS examples](/docs/packages/packem/examples/css/basic).


# Debug & Profiling (/docs/packages/packem/guide/debug)



# Debug & Profiling [#debug--profiling]

Learn how to debug your Packem builds and profile performance to identify bottlenecks and optimize your build process.

## Build Profiling [#build-profiling]

Performing a performance analysis can help you identify performance bottlenecks in your project, allowing for targeted optimization.

### Node.js Profiling [#nodejs-profiling]

When Packem executes a build, it will include the runtime overhead of both JavaScript and Rust code, and the overhead of data communication between JavaScript and Rust.

In general, the performance overhead on the JavaScript side will be greater than that on the Rust side. You can use Node.js profiling to analyze the overhead on the JS side, which helps to identify performance bottlenecks on the JS side.

For example, to perform the CPU profiling analysis, run the following command in the root directory of your project:

```bash
# dev
node --cpu-prof ./node_modules/@visulima/packem/bin/packem.js dev

# build
node --cpu-prof ./node_modules/@visulima/packem/bin/packem.js build

# Set higher precision sampling interval
node --cpu-prof --cpu-prof-interval=100 ./node_modules/@visulima/packem/bin/packem.js build
```

The above commands will generate a `*.cpuprofile` file. We can use [speedscope](https://www.speedscope.app/) to visualize this file:

```bash
# Install speedscope
npm install -g speedscope

# View cpuprofile content
# Replace the name with the local file name
speedscope CPU.date.000000.00000.0.001.cpuprofile
```

## Debug Mode [#debug-mode]

Packem provides debug options to help troubleshoot build issues and get more detailed information about the build process.

### Debug Build Output [#debug-build-output]

Packem includes a `--debug` flag that enables additional logging and debugging information during the build process:

```bash
# Enable debug logging during build
packem build --debug

# Enable debug logging in watch mode
packem build --watch --debug
```

When debug mode is enabled, you'll see additional log messages prefixed with `packem` that provide insight into:

* Configuration loading and processing
* Plugin registration and execution
* Build steps and file processing
* Internal operations and decisions

### Verbose Logging [#verbose-logging]

In debug mode, Packem will output detailed information about:

* **System Information**: Node.js version, bundler version, transformer being used
* **Configuration**: Which config files are loaded and their paths
* **Build Process**: Entry detection, file processing, and build phases
* **Plugin Activity**: Plugin initialization and processing details

Example debug output:

```bash
$ packem build --debug

00:35:12 INFO      [packem] [system] Using node 25.1.0
00:35:12 INFO      [packem] [bundler] Using rollup 4.53.2 with browser build runtime
00:35:12 INFO      [packem] [transformer] Using swc ^1.15.1
00:35:12 INFO      [packem] Automatically detected entries: src/index.tsx [esm] [cjs] [dts]
00:35:12 INFO      [packem] Using typescript version: ^5.9.3
00:35:12 INFO      [packem] Building examples_packem_transformer_swc
00:35:12 INFO      [packem] Cleaning dist directory: `./dist`
00:35:12 INFO      [packem] Preparing build for browser runtime
```

### TypeDoc Debug Information [#typedoc-debug-information]

When using TypeDoc for documentation generation, the debug flag also enables TypeDoc's configuration display, showing how TypeDoc is configured internally.


# Getting Started (/docs/packages/packem/guide/getting-started)





# Getting Started [#getting-started]

This guide takes you from zero to a published-ready bundle. You will install Packem, configure your `package.json`, and run your first build.

## Install Packem [#install-packem]

Add Packem as a dev dependency:

```bash
npm install --save-dev @visulima/packem
```

## Scaffold your project [#scaffold-your-project]

The quickest way to set up is the interactive init command:

```bash
npx packem init
```

It will analyze your project, ask about your preferences (transformer, CSS preprocessor, etc.), generate a `packem.config.ts`, and update your `package.json` with recommended settings.

<Callout type="info">
  The init command detects existing configurations and suggests optimal settings for your project.
</Callout>

## Add optional features [#add-optional-features]

After init, you can enable additional presets:

```bash
npx packem add react     # React preset and dependencies
npx packem add solid     # SolidJS preset and dependencies
npx packem add css       # CSS loaders (PostCSS, Sass, Less, etc.)
npx packem add typedoc   # TypeDoc documentation generation
```

Each command updates your config and installs the necessary dependencies.

## Project structure [#project-structure]

Packem expects a conventional layout:

```
my-package/
├── src/
│   ├── index.ts          # Main entry point
│   ├── cli.ts            # CLI entry (optional)
│   └── utils/
│       └── helper.ts
├── package.json
├── packem.config.ts
└── tsconfig.json
```

## Configure package.json [#configure-packagejson]

Packem reads your `package.json` to decide what to build and how. Pick the pattern that matches your use case:

<Tabs items="[&#x22;ESM Library&#x22;, &#x22;Dual Package (ESM + CJS)&#x22;, &#x22;CLI Tool&#x22;]">
  <Tab value="ESM Library">
    ```json
    {
      "name": "my-package",
      "type": "module",
      "files": ["dist"],
      "main": "./dist/index.js",
      "module": "./dist/index.js",
      "types": "./dist/index.d.ts",
      "exports": {
        ".": {
          "types": "./dist/index.d.ts",
          "default": "./dist/index.js"
        }
      },
      "scripts": {
        "build": "packem build",
        "dev": "packem build --watch"
      }
    }
    ```
  </Tab>

  <Tab value="Dual Package (ESM + CJS)">
    ```json
    {
      "name": "my-package",
      "files": ["dist"],
      "main": "./dist/index.cjs",
      "module": "./dist/index.mjs",
      "types": "./dist/index.d.ts",
      "exports": {
        ".": {
          "import": {
            "types": "./dist/index.d.mts",
            "default": "./dist/index.mjs"
          },
          "require": {
            "types": "./dist/index.d.cts",
            "default": "./dist/index.cjs"
          }
        }
      },
      "scripts": {
        "build": "packem build",
        "dev": "packem build --watch"
      }
    }
    ```
  </Tab>

  <Tab value="CLI Tool">
    ```json
    {
      "name": "my-cli",
      "type": "module",
      "files": ["dist"],
      "bin": "./dist/cli.js",
      "exports": {
        ".": {
          "types": "./dist/index.d.ts",
          "default": "./dist/index.js"
        }
      },
      "scripts": {
        "build": "packem build",
        "dev": "packem build --watch"
      }
    }
    ```
  </Tab>
</Tabs>

Packem detects entry points from the `exports`, `main`, `module`, and `bin` fields automatically — no duplicate configuration needed.

## Write your config [#write-your-config]

Create `packem.config.ts` in the project root:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

## Run the build [#run-the-build]

```bash
npm run build
```

Packem will find your source files in `src/`, transform them with esbuild, and write the output to `dist/`:

```
my-package/
├── dist/
│   ├── index.js       # Bundled JavaScript
│   └── index.d.ts     # TypeScript declarations
└── ...
```

For development, use watch mode so Packem rebuilds on every save:

```bash
npm run dev
```

## Full example [#full-example]

Here is a minimal library from scratch:

**src/index.ts**

```typescript
export function greet(name: string): string {
  return `Hello, ${name}!`
}

export function add(a: number, b: number): number {
  return a + b
}
```

**package.json**

```json
{
  "name": "my-utils",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "packem build"
  }
}
```

**packem.config.ts**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

Run `npm run build` and you are done.

## Troubleshooting [#troubleshooting]

**Entry points not found** — Make sure your `package.json` has `exports`, `main`, or `module` fields and that the matching source files exist in `src/`.

**TypeScript errors** — Verify you have a valid `tsconfig.json` and TypeScript installed.

**Build failing** — Run `packem build --verbose` for detailed error output.

Need more help? [Open an issue](https://github.com/visulima/packem/issues) on GitHub.

## Next steps [#next-steps]

* [Configuration](/docs/packages/packem/guide/configuration) — Customize entry points, output, and build behavior.
* [Transformers](/docs/packages/packem/guide/transformers) — Pick the right compiler for your project.
* [CSS Processing](/docs/packages/packem/guide/css) — Add Sass, Less, PostCSS, and CSS Modules.


# Guide (/docs/packages/packem/guide)



# Guide [#guide]

Whether you are publishing your first npm package or maintaining a monorepo with dozens of libraries, these guides walk you through every step — from installation to production builds.

## Recommended reading order [#recommended-reading-order]

If you are new to Packem, start at the top and work your way down. Each guide builds on the previous one.

1. [Introduction](/docs/packages/packem/guide/introduction) — What Packem is, how it works, and when to use it.
2. [Getting Started](/docs/packages/packem/guide/getting-started) — Install Packem and create your first bundle in under five minutes.
3. [Configuration](/docs/packages/packem/guide/configuration) — Customize entry points, output formats, and build behavior.
4. [Transformers](/docs/packages/packem/guide/transformers) — Pick the right compiler (esbuild, swc, OXC, sucrase, or TypeScript).
5. [CSS Processing](/docs/packages/packem/guide/css) — Add support for CSS, Sass, Less, Stylus, PostCSS, and CSS Modules.
6. [Debug and Profiling](/docs/packages/packem/guide/debug) — Diagnose build issues and measure performance.

## Working with Packem [#working-with-packem]

Task-focused guides for everyday development:

* [package.json Setup](/docs/packages/packem/guide/package-json) — Drive entries, formats, and declarations from your `package.json`.
* [TypeScript](/docs/packages/packem/guide/typescript) — Declaration files, isolated declarations, and type checking.
* [React](/docs/packages/packem/guide/react) — Build React component libraries, including Server Components.
* [Multi-Runtime Builds](/docs/packages/packem/guide/multi-runtime) — Target Node.js, browser, edge, and react-server from one build.
* [Plugins](/docs/packages/packem/guide/plugins) — Extend the build with Rollup plugins.
* [Optimization](/docs/packages/packem/guide/optimization) — Minification, tree shaking, and bundle size.
* [Watch Mode](/docs/packages/packem/guide/watch-mode) — Rebuild automatically during development.
* [CLI](/docs/packages/packem/guide/cli) — Every command and flag the `packem` CLI offers.

## Migrating to Packem [#migrating-to-packem]

Coming from another bundler? Start here:

* [From tsup](/docs/packages/packem/guide/migration/tsup) — Automated migration via `packem migrate`.
* [From unbuild](/docs/packages/packem/guide/migration/unbuild) — Automated migration via `packem migrate`.
* [From Rollup](/docs/packages/packem/guide/migration/rollup) — Map your Rollup config to Packem.
* [From webpack](/docs/packages/packem/guide/migration/webpack) — Move a webpack library build to Packem.

## Troubleshooting [#troubleshooting]

When something goes wrong:

* [Common Issues](/docs/packages/packem/guide/troubleshooting/common-issues) — Frequent problems and their fixes.
* [TypeScript](/docs/packages/packem/guide/troubleshooting/typescript) — Declaration and type-checking errors.
* [CSS](/docs/packages/packem/guide/troubleshooting/css) — Styling and preprocessor problems.
* [Build Errors](/docs/packages/packem/guide/troubleshooting/build-errors) — Diagnose and resolve build failures.

## Already familiar with Packem? [#already-familiar-with-packem]

Jump straight to the reference material:

* [Configuration Options](/docs/packages/packem/options) — Every option explained with examples.
* [API Reference](/docs/packages/packem/api) — Programmatic usage, hooks, and plugin development.
* [Examples](/docs/packages/packem/examples) — Copy-and-paste starter projects for common setups.


# Introduction (/docs/packages/packem/guide/introduction)



# Introduction [#introduction]

Packem is a bundler for Node.js and TypeScript libraries. It reads your `package.json` exports, picks the right entry points, and produces optimized ESM, CJS, or IIFE bundles — with TypeScript declarations, CSS processing, and tree shaking included.

Under the hood it uses Rollup for bundling and lets you swap in the compiler that fits your project: esbuild, swc, OXC, sucrase, or the official TypeScript compiler. An experimental [Rolldown](https://rolldown.rs) backend is also selectable via the [`bundler`](/docs/packages/packem/options/bundler) option.

## How Packem differs from plain Rollup [#how-packem-differs-from-plain-rollup]

Rollup is a powerful general-purpose bundler, but shipping a library still requires wiring up dozens of plugins and options. Packem handles that for you:

* **Package.json driven** — Entry points, output formats, and declaration paths are read directly from your `package.json` exports. No duplicate configuration.
* **Built-in TypeScript declarations** — Generate `.d.ts` files automatically, including isolated declarations.
* **Multiple transformers** — Switch compilers with a single config change instead of swapping plugin chains.
* **CSS pipeline included** — Sass, Less, Stylus, PostCSS, and CSS Modules work without extra setup.
* **Multi-runtime exports** — Target Node.js, browser, edge-light, and react-server from one build.

## What it bundles [#what-it-bundles]

Packem handles everything a modern library needs:

* **TypeScript and JavaScript** — `.ts`, `.tsx`, `.js`, and `.jsx` files with modern syntax support.
* **Type declarations** — `.d.ts` generation with isolated declaration support.
* **Multiple output formats** — ESM, CJS, and IIFE in a single build.
* **CSS and preprocessors** — CSS, Sass, Less, Stylus, PostCSS, and CSS Modules.
* **React components** — Server Components, Client Components, and server actions.
* **Assets** — JSON, WASM, text files, and Node.js native addons.
* **Dynamic imports** — Code splitting with shared modules across entry points.

Tree shaking, minification, source maps, and bundle analysis are built in.

## Choosing a transformer [#choosing-a-transformer]

Each transformer makes a different trade-off between speed and feature coverage:

| Transformer | Speed     | TypeScript         | JSX | Decorators |
| ----------- | --------- | ------------------ | --- | ---------- |
| esbuild     | Fastest   | Yes                | Yes | No         |
| swc         | Very fast | Yes                | Yes | Yes        |
| OXC         | Very fast | Yes                | Yes | Partial    |
| sucrase     | Fast      | Yes                | Yes | No         |
| TypeScript  | Moderate  | Full type checking | Yes | Yes        |

Most projects should start with **esbuild**. Switch to **swc** if you need decorator support, or to **TypeScript** if you need full type checking during the build. See [Transformers](/docs/packages/packem/guide/transformers) for configuration details.

## Package.json as the source of truth [#packagejson-as-the-source-of-truth]

Packem reads your `package.json` to determine:

* Entry points from `exports`, `main`, `module`, and `bin` fields
* Output formats (ESM/CJS) from export conditions
* Declaration output from the `types` field
* Build targets and compatibility requirements

This keeps your build configuration and your package's public API in sync.

## Credits [#credits]

Packem builds on the work of the open-source community. In particular:

* **Rollup** — The bundling engine and plugin system that powers Packem.
* **esbuild** — Demonstrated what fast native compilation looks like.
* **tsup** — Inspired the out-of-the-box developer experience and many CLI options.
* **unbuild** — Inspired the hooks system and configuration patterns.
* **swc** and **OXC** — Pushing the limits of JavaScript compilation performance.

## Next steps [#next-steps]

* [Getting Started](/docs/packages/packem/guide/getting-started) — Install Packem and create your first bundle.
* [Configuration](/docs/packages/packem/guide/configuration) — Customize your build for production.
* [Examples](/docs/packages/packem/examples/) — Copy-and-paste starters for common setups.


# From Rollup (/docs/packages/packem/guide/migration/rollup)





# From Rollup [#from-rollup]

Packem is built **on top of Rollup**. Migrating from a hand-written `rollup.config.js` is less about replacing your bundler and more about deleting boilerplate: Packem automates the parts you used to wire up by hand — entry detection, multi-format output, declaration generation, externalization, and plugin ordering — while still letting raw Rollup options pass straight through.

<Callout type="info">
  There is no `packem migrate` path for plain Rollup. The `migrate` command only rewrites `tsup`, `unbuild`, and `bunchee` projects. For Rollup, follow the manual steps below.
</Callout>

## What Packem automates [#what-packem-automates]

| Plain Rollup config                                       | Packem                                                                              |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `input: 'src/index.ts'`                                   | Inferred from `package.json` `exports`, `main`, `module`, `bin`                     |
| `output: [{ format: 'es' }, { format: 'cjs' }]`           | Inferred from export conditions (`import`/`require`) and extensions (`.mjs`/`.cjs`) |
| `output.dir` / `output.file`                              | `outDir` config option (default `dist`)                                             |
| `@rollup/plugin-typescript` / `@rollup/plugin-esbuild`    | The `transformer` option (esbuild/swc/OXC/sucrase)                                  |
| `rollup-plugin-dts` for `.d.ts`                           | `declaration` option (built in via `@visulima/rollup-plugin-dts`)                   |
| `@rollup/plugin-node-resolve` + `@rollup/plugin-commonjs` | Built in (oxc-based resolution)                                                     |
| `external: [...]`                                         | `externals` option; `dependencies`/`peerDependencies` external by default           |
| `@rollup/plugin-replace` for env                          | `--env.KEY=value` / `envFile`                                                       |
| `output.banner` / `output.footer`                         | `banner` / `footer` options                                                         |
| Manual `plugins: [...]`                                   | `plugins` option (with `enforce: 'pre' \| 'post'`)                                  |
| Any remaining Rollup option                               | The `rollup` passthrough option                                                     |

## Step-by-step [#step-by-step]

### 1. Replace input/output with package.json exports [#1-replace-inputoutput-with-packagejson-exports]

A typical dual-format Rollup config:

```javascript
// rollup.config.js
import esbuild from 'rollup-plugin-esbuild'
import dts from 'rollup-plugin-dts'

export default [
  {
    input: 'src/index.ts',
    output: [
      { file: 'dist/index.mjs', format: 'es' },
      { file: 'dist/index.cjs', format: 'cjs' },
    ],
    plugins: [esbuild()],
    external: ['react'],
  },
  {
    input: 'src/index.ts',
    output: { file: 'dist/index.d.ts', format: 'es' },
    plugins: [dts()],
  },
]
```

Becomes this `package.json` — the two output objects and the separate dts pass both collapse into the `exports` map:

```json
{
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "scripts": {
    "build": "packem build"
  }
}
```

### 2. Pick a transformer [#2-pick-a-transformer]

Whatever plugin handled TypeScript/JSX in your Rollup config maps to a transformer:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

The matching `external: ['react']` is unnecessary if `react` is in your `dependencies` or `peerDependencies` — those are externalized automatically.

### 3. Keep your custom Rollup plugins [#3-keep-your-custom-rollup-plugins]

Plugins that have no Packem equivalent go in the `plugins` option. Use `enforce` to control ordering relative to Packem's built-in plugins, and `type: 'dts'` to run a plugin only during declaration generation:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { optimizeLodashImports } from '@optimize-lodash/rollup-plugin'

export default defineConfig({
  transformer,
  plugins: [
    {
      enforce: 'pre',
      plugin: optimizeLodashImports(),
    },
  ],
})
```

Resolved plugin order is: alias → user `enforce: 'pre'` → Rollup core → user plugins (no enforce) → Rollup build plugins → user `enforce: 'post'` → Rollup post-build plugins (minify, copy, reporting).

### 4. Pass through raw Rollup options [#4-pass-through-raw-rollup-options]

Anything Packem does not surface as a top-level option lives under `rollup`. This is also where CSS loaders and external-resolution tweaks go:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    // Rollup / transformer passthrough options
  },
})
```

### 5. Replace env and banner plugins [#5-replace-env-and-banner-plugins]

`@rollup/plugin-replace` for `process.env.NODE_ENV` is replaced by compile-time env injection:

```bash
packem build --env.NODE_ENV=production
```

`output.banner` / `output.footer` become the `banner` / `footer` options, which can target JS and declaration output independently:

```typescript
export default defineConfig({
  transformer,
  banner: { js: "'use client';", dts: '// Generated types' },
})
```

## Gotchas [#gotchas]

* **One config produces many outputs.** A single Packem build emits ESM, CJS, and declarations together based on your exports — you no longer maintain an array of Rollup config objects or a separate dts pass.
* **No `input`/`output` keys.** Entries and formats come from `package.json`. If you need an entry that is not part of your public API, add it to `exports` or use the `entries` config option directly.
* **Resolution and CommonJS interop are built in.** Drop `@rollup/plugin-node-resolve` and `@rollup/plugin-commonjs`; Packem resolves modules (oxc-based) and produces statically analyzable CJS output itself.
* **Don't double-externalize.** Listing `dependencies` in `externals` is redundant — they are already external. Use `externals` only for packages you want forced external that aren't declared as deps, and `--no-external` to inline everything.
* **The `rollup` option is an escape hatch, not the main surface.** Reach for it only for options Packem doesn't expose directly. Most plain-Rollup configs shrink to a transformer plus a handful of top-level options.

## Next steps [#next-steps]

* [Plugins](/docs/packages/packem/guide/plugins) — Add and order custom Rollup plugins.
* [Bundler](/docs/packages/packem/options/bundler) — Rollup (default) or the experimental Rolldown backend.
* [Dependencies](/docs/packages/packem/options/externals) — How externalization works.


# From tsup (/docs/packages/packem/guide/migration/tsup)





# From tsup [#from-tsup]

[tsup](https://github.com/egoist/tsup) and Packem solve the same problem — bundling TypeScript libraries — but take different approaches to configuration. tsup is **option-driven**: you list entries, formats, and flags in `tsup.config.ts`. Packem is **package.json-driven**: it reads your `exports`, `main`, `module`, and `bin` fields to decide what to build and in which formats.

Packem ships a `migrate` command that rewrites your `package.json` dependencies and scripts automatically. The bundler config itself still needs a manual pass, which this guide walks you through.

## Run the automated migration [#run-the-automated-migration]

From your project root:

```bash
packem migrate
```

This will:

* Replace `tsup` / `tsup-node` in your `dependencies`, `devDependencies`, and `peerDependencies` with `@visulima/packem`.
* Rewrite `scripts` that invoke `tsup` to call `packem build` instead.
* Detect a `tsup.config.*` file or an inline `tsup` field in `package.json` and warn you that the config requires a manual conversion (it is **not** auto-converted).

Preview every change without writing anything:

```bash
packem migrate --dry-run
```

After running it, install dependencies with your package manager and continue with the config conversion below.

<Callout type="warning">
  `packem migrate` modifies files in place and uncommitted changes can be lost. Commit your work first, or use `--dry-run` to preview.
</Callout>

## Option mapping [#option-mapping]

| tsup config / flag                 | Packem equivalent                                                                                                                       |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `entry` / `--entry`                | Inferred from `package.json` `exports`, `main`, `module`, `bin`. No `entry` option — see below.                                         |
| `format: ['esm', 'cjs']`           | Inferred from the export condition (`import`/`require`) and file extension (`.mjs`/`.cjs`). No `format` option.                         |
| `dts: true`                        | `declaration: true` in `packem.config.ts` (or `--dts-only` to emit only `.d.ts`). Auto-enabled when `package.json` has a `types` field. |
| `minify: true` / `--minify`        | `minify: true` or `--minify`                                                                                                            |
| `sourcemap: true` / `--sourcemap`  | `sourcemap: true` or `--sourcemap`                                                                                                      |
| `clean: true`                      | Cleaning is on by default; disable with `--no-clean`                                                                                    |
| `watch: true` / `--watch`          | `--watch`                                                                                                                               |
| `target: 'node18'` / `--target`    | `target` config option or `--target` (tsconfig `target` is added automatically)                                                         |
| `external: [...]` / `--external`   | `externals` config option or `--external lodash,react`. `dependencies` and `peerDependencies` are external by default.                  |
| `noExternal`                       | Bundle a dependency by not listing it as a dep, or use `--no-external` to inline all                                                    |
| `platform: 'node' \| 'browser'`    | `runtime: 'node' \| 'browser'` or `--runtime`                                                                                           |
| `env` / `--env.KEY=value`          | `--env.KEY=value` (replaced at compile time)                                                                                            |
| `onSuccess`                        | `onSuccess` config option or `--onSuccess "node dist/index.js"`                                                                         |
| `esbuildPlugins`                   | Use the esbuild transformer plus the `rollup` passthrough / `plugins` option                                                            |
| `tsup` inline `package.json` field | Move to `packem.config.ts`; delete the field                                                                                            |

## Step-by-step [#step-by-step]

### 1. Move your entries into package.json exports [#1-move-your-entries-into-packagejson-exports]

tsup declares entries explicitly:

```typescript
// tsup.config.ts
import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts', 'src/cli.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})
```

Packem reads them from `package.json`. The `exports` map below produces both an ESM and a CJS build of `src/index.ts`, plus declarations, with no entry list:

```json
{
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "bin": "./dist/cli.mjs",
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  }
}
```

Packem matches `src/index.ts` to the `"."` export and `src/cli.ts` to `bin`. The `import`/`require` conditions drive the ESM/CJS split that `format` controlled in tsup.

### 2. Write packem.config.ts [#2-write-packemconfigts]

Replace `tsup.config.ts` with `packem.config.ts`. Pick a transformer — esbuild is the closest match to tsup, which uses esbuild internally:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

Carry over only the flags you actually set in tsup. `declaration` can be omitted when `package.json` has a `types` field — Packem turns it on automatically.

### 3. Map the remaining options [#3-map-the-remaining-options]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  minify: true,
  declaration: true,
  runtime: 'node',
  externals: ['some-peer-only-dep'],
})
```

### 4. Update scripts [#4-update-scripts]

If you skipped `packem migrate`, change your scripts by hand:

```json
{
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  }
}
```

### 5. Delete the old config [#5-delete-the-old-config]

Remove `tsup.config.ts` (and any inline `tsup` field in `package.json`) once the build passes.

## Gotchas [#gotchas]

* **No `entry` and no `format` options.** This is the biggest mental shift. Entries come from `package.json` exports/bin; output format comes from the export condition and file extension. If a build is missing, check that the matching `exports` entry and the corresponding `src/` file both exist.
* **Declarations follow your exports.** With dual ESM/CJS exports that point at `.d.mts` and `.d.cts`, Packem emits matching extension-specific declaration files. A single `.d.ts` is enough for an ESM-only package.
* **`dependencies` are external by default.** tsup users often rely on `noExternal` or `external` lists. In Packem, anything in `dependencies`/`peerDependencies` is already external. Use `--no-external` only if you want everything inlined.
* **`onSuccess` as a function needs the config file.** The `--onSuccess` flag takes a shell string. To run JavaScript (e.g. start a dev server) use the `onSuccess` function form in `packem.config.ts`.
* **Config conversion is manual.** `packem migrate` never rewrites `tsup.config.ts` — it only warns. Translate the options yourself using the table above.

## Next steps [#next-steps]

* [Configuration](/docs/packages/packem/guide/configuration) — Full option reference.
* [Transformers](/docs/packages/packem/guide/transformers) — esbuild, swc, OXC, and sucrase.
* [Package.json Setup](/docs/packages/packem/guide/package-json) — How exports drive entries and formats.


# From unbuild (/docs/packages/packem/guide/migration/unbuild)





# From unbuild [#from-unbuild]

[unbuild](https://github.com/unjs/unbuild) and Packem share a lineage: both are Rollup-based library bundlers that lean on `package.json` and a `build.config` style file, and both can infer entries automatically. Migrating is mostly a one-to-one translation of unbuild's `BuildConfig` into Packem's `defineConfig`, with Packem doing even more inference from your `exports` map.

Packem ships a `migrate` command that handles the `package.json` rewrites for you.

## Run the automated migration [#run-the-automated-migration]

From your project root:

```bash
packem migrate
```

This will:

* Replace `unbuild` in your `dependencies`, `devDependencies`, and `peerDependencies` with `@visulima/packem`.
* Rewrite `scripts` that invoke `unbuild` to call `packem build` instead.
* Detect a `build.config.*` file and warn you that it needs a manual conversion (it is **not** auto-converted).

Preview without writing anything:

```bash
packem migrate --dry-run
```

<Callout type="warning">
  `packem migrate` modifies files in place and uncommitted changes can be lost. Commit first, or use `--dry-run`.
</Callout>

## Option mapping [#option-mapping]

unbuild's `build.config.ts` exports a `BuildConfig`. Most fields have a direct Packem counterpart:

| unbuild `BuildConfig`                                          | Packem equivalent                                                                         |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `entries: ['src/index']`                                       | Inferred from `package.json` `exports`/`main`/`module`/`bin`, or the `entries` option     |
| `entries` with mkdist (`{ builder: 'mkdist', input: 'src/' }`) | `unbundle: true` (preserves the source file structure)                                    |
| `declaration: true`                                            | `declaration: true` (also auto-detected from a `types` field)                             |
| `declaration: 'compatible' \| 'node16'`                        | `declaration: 'compatible' \| 'node16'` (same values)                                     |
| `clean: true`                                                  | On by default; disable with `--no-clean`                                                  |
| `sourcemap: true`                                              | `sourcemap: true` or `--sourcemap`                                                        |
| `rollup.emitCJS` / `cjsBridge`                                 | Express CJS output via a `require` condition in `exports`; `cjsInterop: true` for interop |
| `rollup.inlineDependencies`                                    | `--no-external` (inline) or curate `externals`                                            |
| `externals: [...]`                                             | `externals` option; `dependencies`/`peerDependencies` external by default                 |
| `alias`                                                        | `alias` option (also inferred from tsconfig `paths`)                                      |
| `replace`                                                      | `--env.KEY=value` / `envFile` for env constants                                           |
| `hooks`                                                        | `hooks` option                                                                            |
| `failOnWarn`                                                   | Covered by the built-in validator (`validation`)                                          |
| `preset`                                                       | `preset` option                                                                           |
| `outDir`                                                       | `outDir` option (default `dist`)                                                          |
| Per-entry `outDir` / `format`                                  | Per-entry settings via the `entries` array                                                |

## Step-by-step [#step-by-step]

### 1. Translate build.config.ts [#1-translate-buildconfigts]

A common unbuild config:

```typescript
// build.config.ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index'],
  declaration: true,
  clean: true,
  rollup: {
    emitCJS: true,
  },
})
```

The `emitCJS` flag and the explicit entry both move into `package.json` — a `require` condition produces the CJS output, and the `"."` export plus `src/index.ts` replace the `entries` list:

```json
{
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    }
  },
  "scripts": {
    "build": "packem build"
  }
}
```

Then `packem.config.ts` only needs a transformer; `declaration` is auto-detected from the `types` field, and `clean` is already the default:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

<Callout type="info">
  Unlike unbuild, Packem requires a `transformer` (under the default Rollup backend). esbuild is the recommended default.
</Callout>

### 2. Keep explicit entries when you need them [#2-keep-explicit-entries-when-you-need-them]

If you relied on unbuild's `entries` array for entries outside your public `exports`, use Packem's `entries` option. It accepts a string or a richer object with per-entry `declaration`, `runtime`, `cjs`/`esm`, and `outDir`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  entries: [
    'src/index.ts',
    { input: 'src/cli.ts', executable: true },
  ],
})
```

### 3. Map the mkdist builder to unbundle [#3-map-the-mkdist-builder-to-unbundle]

unbuild's `mkdist` builder transpiles a directory file-by-file without bundling. Packem's equivalent is **unbundle mode**, which preserves the source file structure instead of bundling into single files:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  unbundle: true,
})
```

Or per build: `packem build --unbundle`.

### 4. Carry over hooks, aliases, and externals [#4-carry-over-hooks-aliases-and-externals]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  alias: {
    '~': './src',
  },
  externals: ['some-undeclared-peer'],
  hooks: {
    // Same lifecycle-hook idea as unbuild's `hooks`
  },
})
```

### 5. Delete build.config.ts [#5-delete-buildconfigts]

Once `packem build` produces the same `dist/`, remove `build.config.ts`.

## Gotchas [#gotchas]

* **A transformer is required.** unbuild picks its compiler for you; Packem makes it an explicit choice under the default Rollup backend. Add `transformer` to your config or the build will refuse to run.
* **`emitCJS` → export conditions.** There is no `emitCJS` flag. Dual output comes from having both `import` and `require` conditions (or `.mjs`/`.cjs` extensions) in `package.json`.
* **mkdist becomes `unbundle`.** If you used the mkdist builder for unbundled, directory-preserving output, switch to `unbundle: true` rather than expecting a bundled single file.
* **Inlining dependencies is opt-in.** unbuild's `inlineDependencies` has no single equivalent — declared deps are external by default; use `--no-external` to inline everything, or curate `externals`.
* **Config conversion is manual.** `packem migrate` rewrites `package.json` only and warns about `build.config.*`. Translate the config yourself using the table above.

## Next steps [#next-steps]

* [Configuration](/docs/packages/packem/guide/configuration) — Full option reference.
* [Unbundle](/docs/packages/packem/options/unbundle) — Preserve source file structure (the mkdist equivalent).
* [Entry](/docs/packages/packem/options/entry) — Configure explicit entry points.


# From Webpack (/docs/packages/packem/guide/migration/webpack)





# From Webpack [#from-webpack]

Webpack is an application bundler tuned for shipping apps to a browser. Packem is a **library bundler** tuned for publishing packages to npm. If you have been using Webpack to build a library, migrating means trading `webpack.config.js` — entry, output, loaders, externals, plugins — for a package.json-driven build with a small `packem.config.ts`.

<Callout type="info">
  There is no `packem migrate` path for Webpack. The `migrate` command only rewrites `tsup`, `unbuild`, and `bunchee` projects. Migrate from Webpack by hand using the mapping below.
</Callout>

## Concept mapping [#concept-mapping]

| Webpack concept                                              | Packem equivalent                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `entry: './src/index.ts'`                                    | Inferred from `package.json` `exports`, `main`, `module`, `bin`           |
| `output.path`                                                | `outDir` config option (default `dist`)                                   |
| `output.filename`                                            | Output names follow the `exports` map and file extensions                 |
| `output.library` / `libraryTarget: 'commonjs2'` / `'module'` | Export conditions: `require` → CJS, `import` → ESM                        |
| `module.rules` with `babel-loader` / `ts-loader`             | The `transformer` option (esbuild/swc/OXC/sucrase)                        |
| `module.rules` with `css-loader` / `style-loader`            | Built-in CSS support via `rollup.css` loaders                             |
| `resolve.alias`                                              | `alias` config option (also inferred from tsconfig `paths`)               |
| `resolve.extensions`                                         | Handled automatically                                                     |
| `externals`                                                  | `externals` option; `dependencies`/`peerDependencies` external by default |
| `DefinePlugin` / `EnvironmentPlugin`                         | `--env.KEY=value` / `envFile` (compile-time replacement)                  |
| `TerserPlugin` / `optimization.minimize`                     | `minify: true` or `--minify`                                              |
| `devtool: 'source-map'`                                      | `sourcemap: true` or `--sourcemap`                                        |
| `target: 'node' \| 'web'`                                    | `runtime: 'node' \| 'browser'` or `--runtime`                             |
| `watch: true`                                                | `--watch`                                                                 |
| `.d.ts` via a separate tsc/plugin step                       | `declaration` option (built in)                                           |
| Code splitting / dynamic `import()`                          | Supported automatically                                                   |

## Step-by-step [#step-by-step]

### 1. Declare your output through package.json [#1-declare-your-output-through-packagejson]

A library-mode Webpack config:

```javascript
// webpack.config.js
module.exports = {
  entry: './src/index.ts',
  output: {
    path: __dirname + '/dist',
    filename: 'index.js',
    library: { type: 'module' },
  },
  experiments: { outputModule: true },
  externals: ['react'],
  module: {
    rules: [{ test: /\.tsx?$/, use: 'ts-loader' }],
  },
}
```

Becomes a `package.json` that describes the public API. The `library`/`output` block is replaced by the `exports` conditions, and `externals: ['react']` is unnecessary once `react` is a declared dependency:

```json
{
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "packem build"
  }
}
```

To ship both CJS and ESM (the `libraryTarget: 'commonjs2'` + module case), use dual conditions:

```json
{
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    }
  }
}
```

### 2. Replace loaders with a transformer [#2-replace-loaders-with-a-transformer]

`ts-loader`, `babel-loader`, and `swc-loader` all collapse into a single transformer choice:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

esbuild is the fastest default; swc is closest to a Babel-heavy setup (decorators, custom transforms).

### 3. Move CSS rules into the CSS loaders [#3-move-css-rules-into-the-css-loaders]

Webpack `css-loader` / `style-loader` / `sass-loader` chains map to Packem's built-in CSS loaders configured under `rollup.css`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import sassLoader from '@visulima/packem/css/loader/sass'
import sourceMapLoader from '@visulima/packem/css/loader/sourcemap'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      loaders: [postcssLoader, sassLoader, sourceMapLoader],
    },
  },
})
```

### 4. Translate aliases and externals [#4-translate-aliases-and-externals]

`resolve.alias` becomes the `alias` option (Packem also reads tsconfig `paths` automatically). `externals` becomes the `externals` option — but remember that declared dependencies are external by default:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  alias: {
    '@components': './src/components',
  },
  externals: ['some-undeclared-peer'],
})
```

### 5. Translate DefinePlugin and optimization [#5-translate-defineplugin-and-optimization]

`DefinePlugin` constants become compile-time env injection:

```bash
packem build --env.NODE_ENV=production --env.API_URL=https://api.example.com
```

`optimization.minimize` / `TerserPlugin` become `minify`, and `devtool` becomes `sourcemap`:

```typescript
export default defineConfig({
  transformer,
  minify: true,
  sourcemap: true,
})
```

## Gotchas [#gotchas]

* **Packem builds libraries, not apps.** There is no dev server, HTML templating, asset hashing for deployment, or HMR. If you were using Webpack to serve an application, Packem is not a drop-in replacement for that part of your toolchain — keep Webpack/Vite for the app and use Packem for publishable packages.
* **No `entry`/`output` configuration.** Entries come from `package.json` exports/bin; output names and formats come from export conditions and extensions. Add non-public entries via the `entries` config option if needed.
* **Externals are inverted from app builds.** In Webpack app builds you bundle everything; in a library you externalize dependencies. Packem externalizes `dependencies`/`peerDependencies` by default — only inline with `--no-external` when you truly need a self-contained bundle.
* **CSS defaults to injection.** Packem's default CSS mode is `inject` (CSS embedded in JS, added to `<head>` at runtime). For a separate `.css` file (like `MiniCssExtractPlugin`), use extract mode in the CSS loader options.
* **Declarations are first-class.** Drop any separate `tsc --emitDeclarationOnly` step or dts plugin — set `declaration: true` (or just add a `types` field to `package.json` and Packem auto-detects it).

## Next steps [#next-steps]

* [CSS Processing](/docs/packages/packem/guide/css) — Sass, Less, Stylus, PostCSS, and CSS Modules.
* [Transformers](/docs/packages/packem/guide/transformers) — Choosing between esbuild, swc, OXC, and sucrase.
* [Multi-Runtime](/docs/packages/packem/guide/multi-runtime) — Browser, node, and edge conditional exports.


# Multi-Runtime (/docs/packages/packem/guide/multi-runtime)





# Multi-Runtime [#multi-runtime]

Packem can target multiple runtimes from a single build: **default**, **node**, **browser**, **edge-light**, and **react-server**. Runtime-specific output is driven by the conditional `exports` map in your `package.json`, together with a source-file naming convention that lets you provide a different implementation per runtime.

## Runtime-specific source files [#runtime-specific-source-files]

Special platforms such as `react-server`, `react-native`, and `edge-light` may need different exports or different code paths. Packem provides an override source-file convention: name a source file after the export condition and Packem builds it as a separate bundle.

For example, this `exports` map produces three distinct bundles:

```json
{
  "exports": {
    "react-server": "./dist/react-server.mjs",
    "edge-light": "./dist/edge-light.mjs",
    "import": "./dist/index.mjs"
  }
}
```

Each condition is matched to its own source file under `src` (for example `src/index.react-server.ts` for the `react-server` condition), so you can ship a tailored implementation for each runtime.

<Callout type="info">
  The `edge-light` export injects `process.env.EdgeRuntime` as `true`; for all other runtimes it evaluates to `false`. You can branch on it in your code to remove runtime-incompatible paths.
</Callout>

## The `runtime` option [#the-runtime-option]

The global build runtime can also be set in your config or via the CLI. The `init` command writes a `runtime` value into the generated config:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'node', // 'node' | 'browser'
})
```

Or from the command line:

```bash
packem build --runtime browser
```

<Callout type="info">
  The `--runtime` CLI flag accepts `node` or `browser`. The finer-grained `react-server`, `edge-light`, and `react-native` runtimes are selected through the conditional `exports` map and source-file convention described above.
</Callout>

## `production` and `development` conditions [#production-and-development-conditions]

If you separate `production` and `development` exports conditions, Packem injects `process.env.NODE_ENV` for you (when present), so you do not need to inject it manually:

```json
{
  "exports": {
    "development": "./dist/index.development.mjs",
    "production": "./dist/index.production.mjs"
  }
}
```

* When the `production` condition is defined and the file ends with `*.production.*`, the bundle is **minified**.
* When the `development` condition is defined and the file ends with `*.development.*`, the bundle is **not minified**.

## Sharing modules across runtimes [#sharing-modules-across-runtimes]

Modules that must exist as a single instance across multiple runtime bundles (for example a React context shared between `default` and `react-server`) use the shared module convention `[name].shared-runtime.[ext]`:

```js
// src/util.shared-runtime.js
export function sharedUtil() {
  /* ... */
}
```

```js
// src/index.js
import { sharedUtil } from './util.shared-runtime'
```

```js
// src/index.react-server.js
import { sharedUtil } from './util.shared-runtime'
```

The shared module is bundled into a separate chunk referenced by every runtime bundle. See [React Support](/docs/packages/packem/guide/react) for the React-specific use of this convention.

## Next steps [#next-steps]

* [Package.json Setup](/docs/packages/packem/guide/package-json) — how exports conditions map to entries.
* [React Support](/docs/packages/packem/guide/react) — react-server and client/server boundaries.
* [Multi-Runtime example](/docs/packages/packem/examples/advanced/multi-runtime) — a complete project.


# Optimization (/docs/packages/packem/guide/optimization)





# Optimization [#optimization]

Packem ships several built-in mechanisms for keeping bundles small and fast: minification, tree shaking, and bundle analysis. This guide covers how to enable each one.

## Minification [#minification]

The `minify` option toggles minification of the JavaScript output:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: true,
})
```

Or from the command line:

```bash
packem build --minify
```

<Callout type="info">
  When `--minify` is passed and `--sourcemap` is not specified, source maps are enabled by default. When building with `--production` (or `NODE_ENV=production`), minification is enabled automatically.
</Callout>

### Condition-driven minification [#condition-driven-minification]

If your `package.json` defines `production` and `development` export conditions, Packem minifies the matching outputs automatically:

* A file ending in `*.production.*` for the `production` condition is **minified**.
* A file ending in `*.development.*` for the `development` condition is **not minified**.

```json
{
  "exports": {
    "development": "./dist/index.development.mjs",
    "production": "./dist/index.production.mjs"
  }
}
```

See [Multi-Runtime](/docs/packages/packem/guide/multi-runtime) for the full conditional-exports behavior and the [Minify option](/docs/packages/packem/options/minify) for details.

## Tree shaking [#tree-shaking]

Dead-code elimination is handled by Rollup. You can tune its behavior with `rollup.treeshake`, which is passed straight through to Rollup's `treeshake` option:

```typescript
export default defineConfig({
  transformer,
  rollup: {
    treeshake: {
      moduleSideEffects: 'no-external',
      propertyReadSideEffects: false,
    },
  },
})
```

Marking your package as side-effect free in `package.json` lets consumers' bundlers shake it harder:

```json
{
  "sideEffects": false
}
```

### Removing dead code with environment variables [#removing-dead-code-with-environment-variables]

Pass compile-time environment variables with the `--env` flag. Packem replaces matching references and lets Rollup strip the now-unreachable branches:

```bash
packem build --env.NODE_ENV=production
```

This replaces `process.env.NODE_ENV` with `'production'` and removes the code guarded by other values.

## Bundle analysis [#bundle-analysis]

Pass `--analyze` to generate a visual report of your bundle makeup as `packem-bundle-analyze.html`:

```bash
packem build --analyze
```

The report includes gzip and brotli sizes for each module. You can also set the option in config:

```typescript
export default defineConfig({
  transformer,
  analyze: true,
})
```

<Callout type="info">
  `--analyze` enables source maps so the analyzer can attribute bytes accurately.
</Callout>

### Metafile [#metafile]

For machine-readable build metadata, pass `--metafile`. Packem writes a JSON file per bundle (for example `metafile-<name>-cjs.json` and `metafile-<name>-es.json`) that you can feed to analysis tools such as [bundle buddy](https://www.bundle-buddy.com/rollup):

```bash
packem build --metafile
```

## Unbundle mode [#unbundle-mode]

For some libraries, preserving the source file structure (one output file per module) produces better tree shaking for consumers than a single bundled file. Enable it with `unbundle`:

```typescript
export default defineConfig({
  transformer,
  unbundle: true,
})
```

Or via the CLI:

```bash
packem build --unbundle
```

See [Unbundle](/docs/packages/packem/options/unbundle) for details.

## Next steps [#next-steps]

* [Minify option](/docs/packages/packem/options/minify) — the minification reference.
* [Plugins](/docs/packages/packem/guide/plugins) — add analysis plugins like the visualizer.
* [CLI Reference](/docs/packages/packem/guide/cli) — every build flag.


# Package.json Setup (/docs/packages/packem/guide/package-json)





# Package.json Setup [#packagejson-setup]

Packem reads your `package.json` to decide **what** to build and **how**. Entry points, output formats, and declaration paths are all derived from the standard fields — `exports`, `main`, `module`, `types`, and `bin` — so there is no duplicate configuration between your build and your package's public API.

## How entries are detected [#how-entries-are-detected]

Packem recognizes a file convention: files in your `src` folder are treated as entry files and matched against the export names in `package.json`.

* `src/index.ts` matches the export name `"."` (the main export).
* The output **format** is chosen from the exports condition and the file extension:
  * CommonJS for `require`, ESM for `import` (by condition).
  * CommonJS for `.cjs`, ESM for `.mjs` (by extension, regardless of condition).

<Callout type="info">
  The `src` source directory and the `dist` output directory are both configurable in your `packem.config.ts`. See [Source Directory](/docs/packages/packem/options/source-dir) and [Output Directory](/docs/packages/packem/options/output-directory).
</Callout>

## The `exports` field [#the-exports-field]

The [`exports` field](https://nodejs.org/api/packages.html#exports-sugar) defines conditions that map consumers to the right file. Packem builds an output for each condition it finds and matches it to the corresponding source file.

```json
{
  "files": ["dist"],
  "exports": {
    "import": "./dist/index.mjs",
    "require": "./dist/index.cjs"
  },
  "scripts": {
    "build": "packem build"
  }
}
```

### Subpath exports [#subpath-exports]

Add more keys to `exports` to expose multiple entry points. Each subpath maps to its own source file under `src`.

<Tabs items="[&#x22;ESM only&#x22;, &#x22;Dual (ESM + CJS)&#x22;]">
  <Tab value="ESM only">
    ```json
    {
      "type": "module",
      "files": ["dist"],
      "exports": {
        ".": {
          "types": "./dist/index.d.ts",
          "default": "./dist/index.js"
        },
        "./utils": {
          "types": "./dist/utils.d.ts",
          "default": "./dist/utils.js"
        }
      }
    }
    ```
  </Tab>

  <Tab value="Dual (ESM + CJS)">
    ```json
    {
      "files": ["dist"],
      "main": "./dist/index.cjs",
      "module": "./dist/index.mjs",
      "exports": {
        ".": {
          "import": {
            "types": "./dist/index.d.mts",
            "default": "./dist/index.mjs"
          },
          "require": {
            "types": "./dist/index.d.cts",
            "default": "./dist/index.cjs"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

See the [Entry option](/docs/packages/packem/options/entry) for the full entry-inference reference.

## `main` and `module` [#main-and-module]

`main` and `module` are recognized alongside `exports` to define entry points. They are most useful for the older resolution algorithm and for consumers that do not read the `exports` map.

```json
{
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs"
}
```

## `types` [#types]

When building a TypeScript library, point the `types` field at the declaration file for your main entry. Packem generates the declaration files automatically.

```json
{
  "types": "./dist/index.d.ts"
}
```

When you use `.mjs`/`.cjs` outputs with modern module resolution (`node16` or above), TypeScript expects extension-matched declaration files (`.d.mts` / `.d.cts`). Packem generates the right declaration files to match each condition and extension:

```json
{
  "files": ["dist"],
  "exports": {
    "import": {
      "types": "./dist/index.d.mts",
      "default": "./dist/index.mjs"
    },
    "require": {
      "types": "./dist/index.d.cts",
      "default": "./dist/index.cjs"
    }
  }
}
```

See [TypeScript](/docs/packages/packem/guide/typescript) and [Declaration Files](/docs/packages/packem/options/declaration-files) for details.

## `bin` — executables [#bin--executables]

Use the `bin` field to build executables. The source-file matching follows the same convention as regular entries.

<Callout type="info">
  Packem automatically preserves and prepends the shebang to the executable file, and sets the correct executable permissions.
</Callout>

A single binary maps `src/bin/index.ts` to the configured output:

```
|- src/
  |- bin/
    |- index.ts
```

```json
{
  "bin": "./dist/bin/index.cjs"
}
```

Use `.mjs` when `"type": "module"` is set:

```json
{
  "type": "module",
  "bin": "./dist/bin/index.mjs"
}
```

Multiple binaries each map to their own source file:

```
|- src/
  |- bin/
    |- foo.ts
    |- bar.ts
```

```json
{
  "bin": {
    "foo": "./dist/bin/foo.cjs",
    "bar": "./dist/bin/bar.cjs"
  }
}
```

## `typesVersions` (Node 10 compatibility) [#typesversions-node-10-compatibility]

To support the legacy Node 10 type resolution, Packem can generate a `typesVersions` map for you. Enable it through `node10Compatibility` in your config:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  node10Compatibility: {
    typeScriptVersion: '>=5.0', // the TypeScript version you want to support
    writeToPackageJson: true,
  },
})
```

## `files` [#files]

List `dist` (or your output directory) in the `files` array so the built output is included when the package is published:

```json
{
  "files": ["dist"]
}
```

## External dependencies [#external-dependencies]

All `dependencies` and `peerDependencies` are marked as external automatically and are not included in the bundle. To bundle them instead, pass the `--no-external` flag or configure [Dependencies](/docs/packages/packem/options/externals).

## Validation [#validation]

Packem can validate that your `package.json` fields point at files that were actually built. See the package validation examples for [Package.json validation](/docs/packages/packem/examples/configuration/package-validation) and [extra export conditions](/docs/packages/packem/examples/configuration/extra-conditions).

## Next steps [#next-steps]

* [TypeScript](/docs/packages/packem/guide/typescript) — declaration generation and isolated declarations.
* [Multi-Runtime](/docs/packages/packem/guide/multi-runtime) — conditional exports for different runtimes.
* [Entry option](/docs/packages/packem/options/entry) — the full entry reference.


# Plugins (/docs/packages/packem/guide/plugins)





# Plugins [#plugins]

Packem builds on Rollup, so you can extend a build with any Rollup plugin. User plugins are registered through the `rollup.plugins` option, where each entry describes the plugin, when it runs relative to Packem's built-in plugins, and which build it applies to.

## Adding a plugin [#adding-a-plugin]

Each entry in `rollup.plugins` is an object with a `plugin` property holding the Rollup plugin instance:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import inject from '@rollup/plugin-inject'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      { plugin: inject({ Buffer: ['buffer', 'Buffer'] }) },
    ],
  },
})
```

## Plugin shape [#plugin-shape]

The `rollup.plugins` array accepts objects with the following properties:

| Property  | Type                 | Description                                                                               |
| --------- | -------------------- | ----------------------------------------------------------------------------------------- |
| `plugin`  | `Plugin`             | The Rollup plugin instance.                                                               |
| `enforce` | `"pre"` \| `"post"`  | When the plugin runs relative to Packem's built-in plugins. Omit for the normal position. |
| `type`    | `"build"` \| `"dts"` | Which build the plugin applies to. Defaults to the JavaScript (`build`) bundle.           |

## Enforce order [#enforce-order]

`enforce` controls where the plugin sits in the pipeline relative to Packem's own plugins:

* `"pre"` — runs **before** the built-in plugins.
* `"post"` — runs **after** the built-in plugins.
* omitted — runs in the **normal** position, between pre and post.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      { enforce: 'pre', plugin: myEarlyPlugin() },
      { plugin: myNormalPlugin() },
      { enforce: 'post', plugin: myLatePlugin() },
    ],
  },
})
```

## Targeting the build or declaration output [#targeting-the-build-or-declaration-output]

Packem runs two passes: the JavaScript bundle (`build`) and the TypeScript declaration bundle (`dts`). The `type` property decides which pass a plugin participates in:

* `type: "build"` (or omitted) — applies to the JavaScript bundle only.
* `type: "dts"` — applies to the declaration (`.d.ts`) build only.

```typescript
export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      // Only runs during the JavaScript build
      { plugin: jsOnlyPlugin() },
      // Only runs during declaration generation
      { type: 'dts', plugin: dtsOnlyPlugin() },
    ],
  },
})
```

<Callout type="info">
  A plugin with no `type` is applied to the `build` bundle, not the declaration build. To process the declaration output, set `type: "dts"` explicitly.
</Callout>

## A custom plugin [#a-custom-plugin]

Any object that satisfies Rollup's plugin interface works:

```typescript
import type { Plugin } from 'rollup'

function bannerPlugin(): Plugin {
  return {
    name: 'banner',
    renderChunk(code) {
      return `/* built with packem */\n${code}`
    },
  }
}

export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      { plugin: bannerPlugin() },
    ],
  },
})
```

<Callout type="info">
  For prepending or appending text to the output, Packem also has dedicated `banner` and `footer` options that target the JavaScript and declaration files independently.
</Callout>

## Babel and framework presets [#babel-and-framework-presets]

Babel-based framework transforms (React, SolidJS, Preact, Vue, Svelte) are not registered through `rollup.plugins`. They are wired up via the `rollup.babel` option or a [preset](/docs/packages/packem/guide/react), which run Babel **before** the main transformer. Babel transforms can also run across a pool of worker threads for larger builds:

| Option              | Default | Description                                                                                                            |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `parallel`          | `true`  | `false` always transforms in-process; `true` auto-enables workers above the threshold; a number caps the worker count. |
| `parallelThreshold` | `20`    | Number of matched files required before the worker pool is created.                                                    |

Parallel mode requires fully serializable Babel options. If a non-serializable option is present (for example a plugin passed as a live function), Packem silently falls back to in-process transforms.

## Next steps [#next-steps]

* [Plugins option](/docs/packages/packem/options/plugins) — the option reference.
* [React Support](/docs/packages/packem/guide/react) — framework presets and the Babel pipeline.
* [Optimization](/docs/packages/packem/guide/optimization) — bundle analysis and minification.


# React Support (/docs/packages/packem/guide/react)





# React Support [#react-support]

Packem builds React component libraries, including **Server Components**, **Client Components**, and **server actions**. It understands the `"use client"` and `"use server"` directives and scopes the client/server boundaries correctly so the consuming app's bundler (such as Next.js) can transform them as intended.

## Quick setup [#quick-setup]

The fastest way to enable React is the `add` command:

```bash
npx packem add react
```

This will:

* Add `preset: 'react'` to your config.
* Install `react`, `react-dom`, and the Babel dependencies.
* Detect TypeScript and add `@types/react` and `@types/react-dom` if TypeScript is installed (or prompt you to add TypeScript if it is not).

## Manual configuration [#manual-configuration]

The React preset configures Babel for JSX transformation:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
})
```

For more control you can configure Babel directly through `rollup.babel`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],
  rollup: {
    babel: {
      presets: [
        ['@babel/preset-react', { runtime: 'automatic' }],
      ],
    },
  },
})
```

<Callout type="info">
  When Babel is used with React, it runs **before** your main transformer (esbuild/swc/etc.), turning JSX into JavaScript. TypeScript syntax is parsed by the transformer's parser plugins, not transformed by Babel. See [Plugins](/docs/packages/packem/guide/plugins) for more on the Babel pipeline, including parallel transforms.
</Callout>

## Server and Client Components [#server-and-client-components]

Packem supports building server components and server actions with the library directives `"use client"` and `"use server"`. It generates the corresponding chunks for client and server, scoping the boundaries properly. When the library is integrated into an app such as Next.js, the app bundler can transform the client components and server actions correctly.

How directives are handled:

* If `"use client"` or `"use server"` appears in an **entry file**, it is preserved at the top and that entry's output file becomes a client component.
* If `"use client"` or `"use server"` appears in a file that is used as a **dependency** of an entry, that file is split into a separate chunk and the directive is hoisted to the top of that chunk.

```tsx
// src/button.tsx
'use client'

import { useState } from 'react'

export function Button() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

The directive on the entry above is preserved in the output, marking `dist/button.js` as a client component.

## Shared modules across runtimes [#shared-modules-across-runtimes]

When you build multiple runtime bundles (for example `default` and `react-server` together), some modules must remain a single shared instance across both. Use the shared module convention `[name].shared-runtime.[ext]` so the module is bundled into one chunk shared by every runtime bundle:

```js
'use client'

// src/app-context.shared-runtime.js
export const AppContext = React.createContext(null)
```

```js
// src/index.js
import { AppContext } from './app-context.shared-runtime'
```

```js
// src/index.react-server.js
import { AppContext } from './app-context.shared-runtime'
```

`app-context.shared-runtime` is bundled into a separate chunk with only one instance, shared among the different runtime bundles. See [Multi-Runtime](/docs/packages/packem/guide/multi-runtime) for how the `react-server` and other runtime entries are wired up.

## CSS in React libraries [#css-in-react-libraries]

Packem processes CSS Modules and preprocessors imported by your components. See the [CSS Processing](/docs/packages/packem/guide/css) guide and the [React with CSS Modules](/docs/packages/packem/examples/react/css-modules) example.

## Next steps [#next-steps]

* [Multi-Runtime](/docs/packages/packem/guide/multi-runtime) — react-server, edge-light, and other runtime bundles.
* [Plugins](/docs/packages/packem/guide/plugins) — the Babel pipeline and presets.
* [Server Components example](/docs/packages/packem/examples/react/server-components) — a full setup.


# require-cjs-transformer Plugin (/docs/packages/packem/guide/require-cjs-transformer)





# require-cjs-transformer Plugin [#require-cjs-transformer-plugin]

The `require-cjs-transformer` plugin automatically transforms ESM imports of CommonJS-only packages into `require()` calls. This optimization improves Node.js performance by skipping the expensive cjs-module-lexer overhead for packages that only provide CJS builds.

## Why Use This Plugin? [#why-use-this-plugin]

### The Problem [#the-problem]

Many popular packages in the JavaScript ecosystem still only provide CommonJS (CJS) builds:

* `typescript`
* `@babel/parser`
* `eslint`
* `cjs-module-lexer`
* `esbuild`
* And many others...

When you import these packages using ESM syntax:

```typescript
import { parse } from '@babel/parser'
import { transpile } from 'typescript'
```

Node.js must use the `cjs-module-lexer` to analyze the CJS module and create ESM compatibility. This analysis is expensive and happens on every import, impacting startup performance.

### The Solution [#the-solution]

The `require-cjs-transformer` plugin automatically converts ESM imports of CJS-only packages to `require()` calls:

```typescript
// Input (ESM import)
import { parse } from '@babel/parser'
import { transpile } from 'typescript'

// Output (transformed to require)
const { parse } = require('@babel/parser')
const { transpile } = require('typescript')
```

This allows Node.js to skip the cjs-module-lexer analysis entirely, providing better performance.

## Performance Impact [#performance-impact]

<Callout type="info">
  **Important:** Only use this plugin if the performance benefit is significant for your use case. The plugin adds complexity and maintenance overhead.
</Callout>

For applications that heavily use CJS-only packages, this plugin can provide measurable performance improvements. However, for most applications, the performance difference is negligible.

## Configuration [#configuration]

### Basic Setup [#basic-setup]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true
    }
  }
})
```

### Options [#options]

```typescript
interface RequireCJSPluginOptions {
  /**
   * Transform Node.js built-in modules (fs, path, etc.)
   * @default false
   */
  builtinNodeModules?: boolean

  /**
   * Custom CWD for resolving modules
   * @default process.cwd()
   */
  cwd?: string

  /**
   * Additional packages to consider as CJS-only
   * @default []
   */
  additionalPackages?: string[]

  /**
   * Packages to exclude from transformation
   * @default []
   */
  exclude?: string[]
}
```

### Advanced Configuration [#advanced-configuration]

```typescript
export default defineConfig({
  transformer,
  rollup: {
    requireCJS: {
      builtinNodeModules: true,
      additionalPackages: ['my-cjs-package'],
      exclude: ['some-package']
    }
  }
})
```

## How It Works [#how-it-works]

### Automatic Detection [#automatic-detection]

The plugin automatically detects which packages are CJS-only by:

1. Checking if the package has `type: "commonjs"` in its package.json
2. Analyzing the package's export conditions
3. Verifying if only CJS entry points are available

### Node.js Built-ins [#nodejs-built-ins]

When `builtinNodeModules: true` is set, the plugin generates runtime checks to automatically choose the most efficient approach for the executing environment:

```typescript
// Input
import { readFileSync } from 'fs'
import { join } from 'path'
import { cwd } from 'process'

// Output (runtime-detected)
import { createRequire as __cjs_createRequire } from "node:module";
const __cjs_require = __cjs_createRequire(import.meta.url);

// Runtime capability helpers
const __cjs_getBuiltinModule = (module) => {
    // Check if we're in Node.js and version supports getBuiltinModule
    if (typeof process !== "undefined" && process.versions?.node) {
        const [major, minor] = process.versions.node.split(".").map(Number);
        // Node.js 20.16.0+ and 22.3.0+
        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
            return process.getBuiltinModule(module);
        }
    }
    // Fallback to createRequire
    return __cjs_require(module);
};

const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;

// Use helpers for clean module resolution
const { readFileSync } = __cjs_getBuiltinModule("fs");
const { join } = __cjs_getBuiltinModule("path");
const { cwd } = __cjs_getProcess;
```

The generated code automatically detects the runtime environment and Node.js version at execution time, providing optimal performance in any supported environment.

### Selective Transformation [#selective-transformation]

The plugin only transforms imports that are determined to be CJS-only. ESM packages are left untouched:

```typescript
// ESM package - NOT transformed
import { someFunction } from 'esm-package'

// CJS package - transformed to require
const { someFunction } = require('cjs-package')
```

## Usage Examples [#usage-examples]

### Basic Usage [#basic-usage]

```typescript
// src/index.ts
import { transpile } from 'typescript'
import { parse } from '@babel/parser'
import { readFileSync } from 'fs'

export function processCode(code: string) {
  const ast = parse(code)
  const js = transpile(code)
  const file = readFileSync('file.txt')
  return { ast, js, file }
}
```

After transformation:

```typescript
// dist/index.mjs
import { createRequire as __cjs_createRequire } from "node:module";
const __cjs_require = __cjs_createRequire(import.meta.url);

// Runtime capability helpers
const __cjs_getBuiltinModule = (module) => {
    // Check if we're in Node.js and version supports getBuiltinModule
    if (typeof process !== "undefined" && process.versions?.node) {
        const [major, minor] = process.versions.node.split(".").map(Number);
        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
            return process.getBuiltinModule(module);
        }
    }
    // Fallback to createRequire
    return __cjs_require(module);
};

const { transpile } = __cjs_require("typescript")
const { parse } = __cjs_require("@babel/parser")
const { readFileSync } = __cjs_getBuiltinModule("fs")

export function processCode(code) {
  const ast = parse(code)
  const js = transpile(code)
  const file = readFileSync('file.txt')
  return { ast, js, file }
}
```

### React Component Library [#react-component-library]

```typescript
// src/Button.tsx
import React from 'react'
import { transpile } from 'typescript'

export function Button({ children }) {
  // Use typescript for runtime transpilation
  const code = transpile('const x = 1')
  return <button>{children}</button>
}
```

### CLI Tool [#cli-tool]

```typescript
// src/cli.ts
import { Command } from 'commander'
import { readFileSync } from 'fs'
import { parse } from '@babel/parser'

const program = new Command()
program
  .argument('<file>')
  .action((file) => {
    const content = readFileSync(file, 'utf8')
    const ast = parse(content)
    console.log(ast)
  })

program.parse()
```

## Ecosystem Appeal [#ecosystem-appeal]

<Callout type="warning">
  We encourage the JavaScript ecosystem to continue its transition toward ESM. If you maintain a package that is still CJS-only, please consider offering an ESM build or migrating fully to ESM.
</Callout>

The need for plugins like `require-cjs-transformer` highlights the importance of the ecosystem's transition to ESM. By providing ESM builds, packages can:

* Eliminate the cjs-module-lexer overhead
* Provide better tree-shaking capabilities
* Offer improved performance for all consumers
* Reduce complexity in build tools

## When NOT to Use [#when-not-to-use]

### Don't use this plugin if: [#dont-use-this-plugin-if]

* Your application doesn't heavily use CJS-only packages
* Performance is not a critical concern
* You prefer to keep your build configuration simple
* You're building for environments where `require()` is not available

### Alternative Approaches [#alternative-approaches]

1. **Use ESM-compatible packages**: Choose packages that provide ESM builds
2. **Runtime requires**: Use dynamic `require()` calls where needed

## Troubleshooting [#troubleshooting]

### Plugin Not Transforming Imports [#plugin-not-transforming-imports]

1. **Verify package detection**: The plugin only transforms detected CJS packages
2. **Check exclude list**: Make sure the package isn't in the `exclude` array

### Build Errors [#build-errors]

1. **CommonJS compatibility**: Ensure your environment supports `require()`
2. **Module resolution**: Verify package paths are correct
3. **TypeScript types**: Update type imports if needed

### Performance Issues [#performance-issues]

If you experience performance issues:

1. **Disable the plugin**: Remove the `requireCJS` configuration
2. **Selective transformation**: Use `exclude` to skip problematic packages
3. **Alternative bundling**: Consider using a different bundling strategy

## Migration Guide [#migration-guide]

### From Manual require() Calls [#from-manual-require-calls]

```typescript
// Before
const { parse } = require('@babel/parser')
const { transpile } = require('typescript')

// After - plugin handles this automatically
import { parse } from '@babel/parser'
import { transpile } from 'typescript'
```

### From Dynamic Imports [#from-dynamic-imports]

```typescript
// Before
const { parse } = await import('@babel/parser')

// After - plugin provides static transformation
import { parse } from '@babel/parser'
```

## See Also [#see-also]

* [Performance Impact Study](https://x.com/sanxiaozhizi/status/1968580207322808812)
* [Node.js ESM Documentation](https://nodejs.org/api/esm.html)
* [cjs-module-lexer Repository](https://github.com/nodejs/cjs-module-lexer)
* [ESM Migration Guide](/docs/packages/packem/guide/migration/rollup)


# Transformers (/docs/packages/packem/guide/transformers)





# Transformers [#transformers]

Packem supports multiple transformers to convert your TypeScript and modern JavaScript into optimized bundles. Each transformer has its own strengths and trade-offs.

## Available Transformers [#available-transformers]

Packem provides **4 high-performance transformers**:

* **esbuild** - Fastest compilation, great for most projects
* **swc** - Rust-powered with excellent performance and features
* **OXC** - Next-generation toolchain (experimental)
* **sucrase** - Lightweight and fast alternative to Babel

## Transformer Comparison [#transformer-comparison]

| Feature         | esbuild        | swc                | OXC             | sucrase         |
| --------------- | -------------- | ------------------ | --------------- | --------------- |
| **Speed**       | ⚡⚡⚡ Very Fast  | ⚡⚡⚡ Very Fast      | ⚡⚡⚡ Very Fast   | ⚡⚡ Fast         |
| **TypeScript**  | ✅ Excellent    | ✅ Excellent        | ✅ Good          | ✅ Good          |
| **JSX**         | ✅ Full Support | ✅ Full Support     | ✅ Full Support  | ✅ Basic Support |
| **Decorators**  | ✅ Stage 3      | ✅ Legacy + Stage 3 | ⚠️ Limited      | ❌ No            |
| **Source Maps** | ✅ Excellent    | ✅ Excellent        | ✅ Good          | ✅ Basic         |
| **Bundle Size** | Small          | Small              | Small           | Smallest        |
| **Stability**   | ✅ Stable       | ✅ Stable           | ⚠️ Experimental | ✅ Stable        |
| **Language**    | Go             | Rust               | Rust            | JavaScript      |

## esbuild Transformer [#esbuild-transformer]

**Recommended for most projects.** esbuild provides the best balance of speed, features, and stability.

### Configuration [#configuration]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    // Additional esbuild options can be passed here
  }
})
```

### Features [#features]

* ✅ **Fastest compilation** - Written in Go for maximum performance
* ✅ **TypeScript native** - Built-in TypeScript support without additional tools
* ✅ **JSX support** - React, Preact, Vue JSX transformations
* ✅ **Modern JS** - ES2015+ syntax transformations
* ✅ **Tree shaking** - Dead code elimination
* ✅ **Source maps** - High-quality debugging information

### Use Cases [#use-cases]

* Most TypeScript and JavaScript projects
* React applications and component libraries
* Large codebases requiring fast compilation
* Development environments needing quick rebuilds

## swc Transformer [#swc-transformer]

**Best for advanced features.** swc is written in Rust and offers the most comprehensive transformation features.

### Configuration [#configuration-1]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  rollup: {
    // SWC-specific options
  }
})
```

### Features [#features-1]

* ✅ **Rust-powered performance** - Extremely fast compilation
* ✅ **Advanced decorators** - Both legacy and stage 3 decorators
* ✅ **Comprehensive JSX** - React, Preact, Vue, Solid.js support
* ✅ **Plugin ecosystem** - Extensible with custom transformations
* ✅ **Minification** - Built-in code minification
* ✅ **Source maps** - Excellent debugging support

### Use Cases [#use-cases-1]

* Projects using decorators (experimental or legacy)
* Applications requiring custom transformations
* Projects prioritizing cutting-edge JavaScript features
* Large applications where build performance is critical

## OXC Transformer [#oxc-transformer]

**Experimental next-generation toolchain.** OXC aims to be the fastest JavaScript/TypeScript toolchain.

### Configuration [#configuration-2]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/oxc'

export default defineConfig({
  transformer,
  rollup: {
    // OXC-specific options
  }
})
```

### Features [#features-2]

* ✅ **Cutting-edge performance** - Designed for maximum speed
* ✅ **Modern architecture** - Built from the ground up for efficiency
* ✅ **TypeScript support** - Native TypeScript compilation
* ⚠️ **Experimental** - Active development, some features may be unstable
* ✅ **Future-focused** - Targets latest JavaScript standards

### Use Cases [#use-cases-2]

* Experimental projects willing to use bleeding-edge tools
* Performance-critical applications
* Projects contributing to the JavaScript tooling ecosystem
* Testing next-generation build tools

<Callout type="warning">
  OXC is experimental and under active development. Use with caution in production environments.
</Callout>

## sucrase Transformer [#sucrase-transformer]

**Lightweight and simple.** sucrase focuses on speed and simplicity with a smaller feature set.

### Configuration [#configuration-3]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/sucrase'

export default defineConfig({
  transformer,
  rollup: {
    // Sucrase-specific options
  }
})
```

### Features [#features-3]

* ✅ **Minimal overhead** - Smallest transformer bundle size
* ✅ **Fast compilation** - Quick TypeScript and JSX transformation
* ✅ **Simple setup** - Minimal configuration required
* ❌ **Limited features** - No decorators or advanced transformations
* ✅ **Reliable** - Stable and well-tested

### Use Cases [#use-cases-3]

* Simple TypeScript projects without decorators
* Lightweight applications prioritizing bundle size
* Rapid prototyping and development
* Educational projects and tutorials

## Choosing a Transformer [#choosing-a-transformer]

### Decision Matrix [#decision-matrix]

**For most projects:** Start with **esbuild**

* Fastest, most stable, excellent TypeScript support
* Great ecosystem compatibility
* Proven track record in production

**For advanced features:** Choose **swc**

* Need decorators (experimental or legacy)
* Custom transformations required
* Want cutting-edge JavaScript features

**For experimentation:** Try **OXC**

* Contributing to tooling ecosystem
* Performance research and testing
* Willing to handle experimental issues

**For simplicity:** Use **sucrase**

* Simple TypeScript without decorators
* Minimizing bundle size
* Quick prototyping

### Performance Benchmarks [#performance-benchmarks]

Based on typical TypeScript projects:

```
esbuild:  ~0.1s for 1000 files
swc:      ~0.12s for 1000 files  
OXC:      ~0.08s for 1000 files (experimental)
sucrase:  ~0.15s for 1000 files
```

<Callout type="info">
  Actual performance varies based on project size, complexity, and system specifications. Always benchmark with your specific codebase.
</Callout>

## Advanced Configuration [#advanced-configuration]

### Environment-Specific Transformers [#environment-specific-transformers]

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem/transformer/esbuild'
import swcTransformer from '@visulima/packem/transformer/swc'

const isDev = process.env.NODE_ENV === 'development'

export default defineConfig({
  // Use esbuild for development (faster), swc for production (more features)
  transformer: isDev ? esbuildTransformer : swcTransformer
})
```

### Conditional Transformer Loading [#conditional-transformer-loading]

```typescript
import { defineConfig } from '@visulima/packem/config'

// Dynamically load transformer based on availability
const getTransformer = async () => {
  try {
    return (await import('@visulima/packem/transformer/swc')).default
  } catch {
    return (await import('@visulima/packem/transformer/esbuild')).default
  }
}

export default defineConfig({
  transformer: await getTransformer()
})
```

## Common Issues [#common-issues]

### TypeScript Errors [#typescript-errors]

**esbuild:**

* Type checking is disabled by default for speed
* Use `tsc --noEmit` for type checking in CI/CD

**swc:**

* More comprehensive type checking available
* May be slower due to additional analysis

### JSX Configuration [#jsx-configuration]

Make sure your `tsconfig.json` has correct JSX settings:

```json
{
  "compilerOptions": {
    "jsx": "react-jsx", // For React 17+
    "jsxImportSource": "react" // or your JSX library
  }
}
```

### Source Map Issues [#source-map-issues]

All transformers support source maps, but quality may vary:

```typescript
export default defineConfig({
  sourcemap: true, // Enable source maps
  transformer // Your chosen transformer
})
```

This transformer guide helps you choose the right tool for your specific project requirements and performance goals.


# Build Errors (/docs/packages/packem/guide/troubleshooting/build-errors)





# Build Errors [#build-errors]

When a Packem build throws or exits with code 1, the message almost always names the exact misconfiguration. This page maps the real errors Packem emits to their fixes: failing on warnings, transformer/bundler mismatches, unknown transformers, and externalization failures.

## Build fails because of warnings [#build-fails-because-of-warnings]

### Problem [#problem]

The build prints warnings and then exits with:

```
Exiting with code (1). You can change this behavior by setting `failOnWarn: false`.
```

### Cause [#cause]

Packem collects warnings during the build (`Build is done with some warnings:` followed by the list). When `failOnWarn` is enabled, any accumulated warning turns into a non-zero exit at the end.

### Solution [#solution]

Either fix the warnings the build reports, or disable the fail-on-warn behavior:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  failOnWarn: false
})
```

<Callout type="warning">
  Prefer fixing warnings over silencing them. Many warnings (missing `package.json` fields, unused dependencies, incorrect export condition order) point at problems that break consumers of your published package.
</Callout>

## `transformer` set together with `bundler: "rolldown"` [#transformer-set-together-with-bundler-rolldown]

### Problem [#problem-1]

The build refuses to start with:

```
The `transformer` option is not supported when `bundler: "rolldown"`. Rolldown uses its own oxc-based transform — remove `transformer` from your packem config.
```

### Cause [#cause-1]

The experimental Rolldown backend ships its own oxc-based transform and always uses it. The `esbuild`/`swc`/`sucrase`/`oxc` transformer adapters only apply under the default `"rollup"` bundler. Setting both is a configuration mistake, so Packem refuses to build rather than silently ignoring the option.

### Solution [#solution-1]

When using Rolldown, omit `transformer` entirely:

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  bundler: 'rolldown'
  // no `transformer` here
})
```

To keep a transformer, stay on the default Rollup backend (drop the `bundler` option or set `bundler: "rollup"`).

<Callout type="info">
  Even with `bundler: "rolldown"`, `.d.ts` generation still routes through Rollup. Rollup is pulled in automatically when Rolldown is combined with `declaration: true`.
</Callout>

## Unknown or missing transformer [#unknown-or-missing-transformer]

### Problem [#problem-2]

The build throws:

```
Unknown transformer, check your transformer options or install one of the supported transformers: esbuild, swc, sucrase
```

### Cause [#cause-2]

Under the default Rollup backend a transformer is required, and the one you configured could not be resolved — usually because the transformer package is not installed, or the import is wrong.

### Solution [#solution-2]

Import a transformer and pass it as the `transformer` option:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer
})
```

Make sure the backing package is installed (for example `esbuild`, `@swc/core`, or `sucrase`). If you run the interactive init and pass an invalid name, you will see `Invalid transformer, please choose one of 'swc', 'sucrase' or 'esbuild'`.

## Externalization / unresolved module errors [#externalization--unresolved-module-errors]

### Problem [#problem-3]

The build fails resolving an import:

```
Failed to resolve the module "left-pad" imported by "src/index.ts"
Is the module installed? Note:
 ↳ to inline a module into your bundle, install it to "devDependencies".
 ↳ to depend on a module via import/require, install it to "dependencies".
```

### Cause [#cause-3]

By default an unresolved import (`UNRESOLVED_IMPORT`) is a hard error. Packem externalizes everything in `dependencies` and `peerDependencies` automatically; anything else must be resolvable on disk to be bundled.

### Solution [#solution-3]

Place the module where it belongs:

* Install under `devDependencies` to **bundle** it into the output.
* Install under `dependencies` / `peerDependencies` to keep it **external**.

To downgrade unresolved imports from error to warning, set `unresolvedImportBehavior`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolve: {
      unresolvedImportBehavior: 'warn'
    }
  }
})
```

## Duplicate entry names [#duplicate-entry-names]

### Problem [#problem-4]

The build throws:

```
Duplicate rollup input name "index" — one maps to "...", another to "...". Each entry must have a unique name.
```

### Cause [#cause-4]

Two entries resolved to the same output name but point at different source files. Rollup needs a unique name per input.

### Solution [#solution-4]

Give the colliding entries distinct names (or distinct output subpaths in your `package.json` `exports`) so each maps to one source file.

## Output extension map errors [#output-extension-map-errors]

### Problem [#problem-5]

The build throws one of:

```
Invalid output extension map: <key> must be "cjs" or "esm"
Invalid output extension map: <key> must not start with a dot. Example: "cjs": "c.js", "esm": "m.js"
Invalid output extension map: <key> must be different from the other key
```

### Cause [#cause-5]

`outputExtensionMap` only accepts the keys `cjs` and `esm`, the extension values must not start with a dot, and the two extensions must differ.

### Solution [#solution-5]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  outputExtensionMap: {
    cjs: 'c.js',
    esm: 'm.js'
  }
})
```

## Related [#related]

* [Common Issues](/docs/packages/packem/guide/troubleshooting/common-issues)
* [TypeScript Problems](/docs/packages/packem/guide/troubleshooting/typescript)
* [Transformers](/docs/packages/packem/guide/transformers)
* [Bundler](/docs/packages/packem/options/bundler)


# Common Issues (/docs/packages/packem/guide/troubleshooting/common-issues)





# Common Issues [#common-issues]

This page covers the problems people hit most often when bundling with Packem: nothing gets built, dependencies fail to resolve, output lands in the wrong place, or the package.json validators flag your configuration. Each section follows a problem → cause → solution structure and uses the real messages Packem emits.

## No entries detected [#no-entries-detected]

### Problem [#problem]

The build stops immediately with one of:

```
No source files found in 'src' directory. Please provide entries manually.
```

```
No entries detected. Please provide entries manually.
```

### Cause [#cause]

Packem's `auto` preset infers entry points from your `package.json` `exports`, `main`, `module`, and `types` fields and then maps them back to source files in your source directory (`src` by default). If none of those fields are configured — or they point at output paths that have no matching source file — there is nothing to infer.

### Solution [#solution]

Configure your `package.json` `exports` so each output maps to a source file:

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}
```

With `./dist/index.mjs` declared, Packem looks for `./src/index.ts` (or `.js`, `.tsx`, etc.) and builds it. Alternatively, define entries explicitly in `packem.config.ts`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  entries: ['src/index.ts']
})
```

<Callout type="warning">
  When you map exports to wildcard patterns, Packem warns `Could not find entrypoints matching pattern` and `Could not find entrypoint for` if a declared output has no source behind it. Treat those warnings as a sign that your `exports` and source tree are out of sync.
</Callout>

## Externals not resolving [#externals-not-resolving]

### Problem [#problem-1]

The build fails with:

```
Failed to resolve the module "some-package" imported by "src/index.ts"
Is the module installed? Note:
 ↳ to inline a module into your bundle, install it to "devDependencies".
 ↳ to depend on a module via import/require, install it to "dependencies".
```

### Cause [#cause-1]

Packem treats this `UNRESOLVED_IMPORT` as a hard error by default. The two hints in the message are the actual fix paths: where a dependency lives in `package.json` determines whether it gets inlined into the bundle or left external.

By default, everything in `dependencies` and `peerDependencies` is marked external automatically and is **not** included in the bundle. Packages you want bundled in must be resolvable on disk.

### Solution [#solution-1]

* To **bundle** a module into your output, install it under `devDependencies`.
* To **depend** on a module at runtime (kept external), install it under `dependencies` or `peerDependencies`.

If you want an unresolved import to warn instead of failing the build, set `unresolvedImportBehavior` to `"warn"`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolve: {
      unresolvedImportBehavior: 'warn'
    }
  }
})
```

You can also bundle declared `dependencies` instead of externalizing them with the CLI flag:

```bash
packem build --no-external
```

## Output directory and file names [#output-directory-and-file-names]

### Problem [#problem-2]

Files land somewhere unexpected, or you can't find the generated `dist`.

### Cause [#cause-2]

Packem resolves the output directory from your TypeScript config first: `compilerOptions.outDir` is used when present, falling back to `dist`. The validators also check that your `package.json` `files` field includes that directory.

### Solution [#solution-2]

If your `files` array does not list the output directory, Packem warns:

```
The 'files' field in your package.json is missing the 'dist' directory. Ensure the output directory is included.
```

Add it so your published package actually ships the build:

```json
{
  "files": ["dist"]
}
```

To change where output goes, set `outDir` in `compilerOptions` of `tsconfig.json`, and keep the `files` field in sync.

## Validation failures [#validation-failures]

### Problem [#problem-3]

The build prints `package.json` validation warnings, or fails outright when `failOnWarn` is enabled.

### Cause [#cause-3]

Packem validates `package.json` against what is required to publish a working package. Real warnings include:

* `Missing main export ".". Subpaths exports should include a main export entry`
* `The 'name' field is missing in your package.json. Please provide a valid package name.`
* `The 'module' field is missing in your package.json, but you are emitting ES modules.`
* `Incorrect condition order at <path>. Standard conditions should be ordered: node-addons > node > import > require > module-sync > default`
* `These dependencies are listed in package.json but not used: <list>`
* `These dependencies are shamefully hoisted: <list>`

### Solution [#solution-3]

Fix the underlying `package.json` field the warning points at. Conditions inside `exports` are order-sensitive — `types` must come first and `default` last, with `import`/`require` in between. For a clean publish, also run [publint](https://github.com/bluwy/publint) and [Are the Types Wrong?](https://arethetypeswrong.github.io).

If you need to skip validation entirely (for example, in a fast inner-loop build), pass `--no-validation`:

```bash
packem build --no-validation
```

<Callout type="info">
  Use `packem build --verbose` to see exactly which entries were inferred and how each was mapped to a source file.
</Callout>

## Related [#related]

* [TypeScript Problems](/docs/packages/packem/guide/troubleshooting/typescript)
* [CSS Issues](/docs/packages/packem/guide/troubleshooting/css)
* [Build Errors](/docs/packages/packem/guide/troubleshooting/build-errors)


# CSS Issues (/docs/packages/packem/guide/troubleshooting/css)





# CSS Issues [#css-issues]

Packem processes CSS through [`@visulima/rollup-plugin-css`](https://github.com/visulima/packem/tree/main/packages/rollup-plugin-css), configured under the `rollup.css` key. This page covers the most common CSS problems: styles not extracting or injecting, PostCSS configuration, and CSS Modules.

## CSS not extracted or injected [#css-not-extracted-or-injected]

### Problem [#problem]

You import a CSS file but nothing ends up in the output, or it lands inline when you expected a separate `.css` file (or vice versa).

### Cause [#cause]

The CSS plugin's `mode` controls where processed CSS goes, and the default is `"inject"` — CSS is embedded inside the JS bundle and injected into `<head>` at runtime. The available modes are:

* `"inject"&#x60; &#x2A;(default)* — embeds CSS inside JS and injects it into `<head>` at runtime.
* `"extract"` — extracts CSS to the same location as the JS file but with a `.css` extension.
* `"emit"` — emits pure processed CSS and passes it along the build pipeline for other plugins.

If you expected a standalone stylesheet but never set `mode`, you got the default injection behavior instead.

### Solution [#solution]

Set the mode explicitly under `rollup.css`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract'
    }
  }
})
```

If CSS still does not show up at all, confirm the basics:

1. The CSS file is actually imported from your JS/TS entry (`import './styles.css'`).
2. The import path is correct.
3. CSS processing is not disabled (`rollup.css` is not set to `false`).

## PostCSS config not applied [#postcss-config-not-applied]

### Problem [#problem-1]

Your PostCSS plugins (autoprefixer, cssnano, Tailwind) do not run.

### Cause [#cause-1]

Packem reads PostCSS configuration either from a standalone `postcss.config.js` (via `postcss-load-config`) or from the loaders you register on `rollup.css`. PostCSS support also requires its dependencies to be installed — they are not bundled by default.

### Solution [#solution-1]

Install the PostCSS toolchain:

```bash
npm install --save-dev postcss postcss-load-config postcss-modules \
  postcss-modules-extract-imports postcss-modules-local-by-default \
  postcss-modules-scope postcss-modules-values postcss-value-parser icss-utils
```

Register the PostCSS loader in `packem.config.ts`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import postcssLoader from '@visulima/packem/css/loader/postcss'
import sourceMapLoader from '@visulima/packem/css/loader/sourcemap'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      loaders: [postcssLoader, sourceMapLoader]
    }
  }
})
```

A standalone `postcss.config.js` is picked up automatically:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer'),
    require('cssnano')({ preset: 'default' })
  ]
}
```

## Preprocessor errors (Sass, Less, Stylus) [#preprocessor-errors-sass-less-stylus]

### Problem [#problem-2]

Importing `.scss`, `.less`, or `.styl` throws or produces no output.

### Cause [#cause-2]

Preprocessor support is opt-in: the preprocessor package must be installed, and its loader must be registered on `rollup.css`. Without the loader, the file is treated as plain CSS.

### Solution [#solution-2]

Install the preprocessor and register its loader. For example, Less:

```bash
npm install --save-dev less
```

```typescript
import { defineConfig } from '@visulima/packem/config'
import lessLoader from '@visulima/packem/css/loader/less'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      loaders: [lessLoader]
    }
  }
})
```

For Sass, `sass-embedded` is recommended (`sass` and `node-sass` also work).

## CSS Modules not scoping [#css-modules-not-scoping]

### Problem [#problem-3]

Class names from a CSS Modules file come through unhashed, or `import styles from './x.module.css'` returns an empty object.

### Cause [#cause-3]

CSS Modules in Packem are driven by the `autoModules` option, which scopes files named `[name].module.[ext]` (for example `foo.module.css`, `bar.module.stylus`). If `autoModules` is off, or the file is not named with the `.module.` infix, it is processed as a normal global stylesheet.

### Solution [#solution-3]

Enable `autoModules` and use the `.module.` naming convention:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      mode: 'extract',
      autoModules: true
    }
  }
})
```

```typescript
// src/Button.ts
import styles from './Button.module.css'

button.className = styles.button
```

<Callout type="warning">
  The `.module.` infix is required for `autoModules` to kick in. A file named `Button.css` is global even with `autoModules: true`; rename it to `Button.module.css`.
</Callout>

## Related [#related]

* [CSS Processing](/docs/packages/packem/guide/css)
* [Common Issues](/docs/packages/packem/guide/troubleshooting/common-issues)
* [Build Errors](/docs/packages/packem/guide/troubleshooting/build-errors)


# TypeScript Problems (/docs/packages/packem/guide/troubleshooting/typescript)





# TypeScript Problems [#typescript-problems]

Declaration generation in Packem runs on top of [`@visulima/rollup-plugin-dts`](https://github.com/visulima/packem/tree/main/packages/rollup-plugin-dts). This page covers the things that go wrong with TypeScript builds: declarations not appearing, isolated-declarations requirements, missing tsconfig, and path mapping.

## No `.d.ts` files generated [#no-dts-files-generated]

### Problem [#problem]

The JavaScript bundles build fine, but no `.d.ts`, `.d.mts`, or `.d.cts` files appear in your output.

### Cause [#cause]

Packem only generates declarations when something asks for them. With the `auto` preset, declaration generation is enabled when your `package.json` references types — that means one of:

* a `types` field, or
* a `types` condition inside `exports`, or
* a declaration file path (`*.d.ts` / `*.d.mts` / `*.d.cts`) referenced in your output paths.

If none of these are present, the `declaration` option resolves to `false` and no declarations are emitted.

### Solution [#solution]

Add a `types` field (or `types` condition) to `package.json` so Packem knows you want declarations:

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}
```

Or enable it explicitly in your config:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

The `declaration` option accepts `true`, `false`, `"compatible"`, or `"node16"`. Use `"node16"` (or matching `.d.mts` / `.d.cts` outputs) when you publish under modern `module`/`moduleResolution` so the declaration extension matches the JS condition.

## Missing tsconfig.json [#missing-tsconfigjson]

### Problem [#problem-1]

The build fails with:

```
Cannot build declaration files without a tsconfig.json
```

### Cause [#cause-1]

Declaration generation requires a TypeScript program, which Packem builds from your `tsconfig.json`. When `declaration` is enabled but no `tsconfig.json` is found at the project root, it cannot proceed.

### Solution [#solution-1]

Add a `tsconfig.json` to your project root. A minimal one is enough:

```json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "isolatedModules": true
  }
}
```

## isolatedModules warning [#isolatedmodules-warning]

### Problem [#problem-2]

Packem prints a warning about `isolatedModules` even though the build succeeds:

```
'compilerOptions.isolatedModules' is not enabled in tsconfig.
Because none of the third-party transpiler, packem uses under the hood is type-aware, some techniques or features often used in TypeScript are not properly checked and can cause mis-compilation or even runtime errors.
To mitigate this, you should set the isolatedModules option to true in tsconfig and let your IDE warn you when such incompatible constructs are used.
```

### Cause [#cause-2]

The transformers Packem uses (esbuild, swc, sucrase, oxc) operate file-by-file and are not type-aware. Constructs that rely on cross-file type information — such as re-exporting a type without `export type` — can mis-compile silently. The `isolatedModules` flag makes your IDE and `tsc` flag those constructs ahead of time.

### Solution [#solution-2]

Set `isolatedModules` in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "isolatedModules": true
  }
}
```

## Isolated declarations (TypeScript 5.5+) [#isolated-declarations-typescript-55]

### Problem [#problem-3]

You enabled `isolatedDeclarations` and want to know why it behaves differently, or it isn't being used.

### Cause [#cause-3]

When `"isolatedDeclarations": true` is set in `tsconfig.json`, Packem uses oxc's `isolatedDeclarationSync` to emit `.d.ts` files **without** running full type inference. This is faster but stricter: every exported value must have an explicit, inferable type annotation, otherwise TypeScript's isolated-declarations rules reject it. This feature requires **TypeScript 5.5 or higher**.

### Solution [#solution-3]

If you are on TypeScript below 5.5, isolated declarations are not available — remove `isolatedDeclarations` from your tsconfig and Packem falls back to full declaration generation. If you are on 5.5+ and hit isolated-declaration errors, add explicit return-type and export annotations to the symbols TypeScript complains about:

```typescript
// Rejected under isolatedDeclarations — return type is inferred
export function make() {
  return { a: 1 }
}

// Accepted — explicit annotation
export function make(): { a: number } {
  return { a: 1 }
}
```

<Callout type="info">
  Isolated declarations is an experimental feature. Enable it only when your codebase already annotates its public API explicitly.
</Callout>

## tsconfig paths and aliases [#tsconfig-paths-and-aliases]

### Problem [#problem-4]

Path aliases like `@/utils` resolve in your editor but the declaration build does not pick them up.

### Cause [#cause-4]

Packem forwards your tsconfig `baseUrl` and `paths` for module resolution during the JS build. Declaration generation, however, does **not** support aliases — alias rewriting is not applied inside the type declarations.

### Solution [#solution-4]

Use real relative paths in code that needs type declarations, or avoid aliases for your published surface area. As the project README states:

> Aliases are not supported in type declaration generation. If you need type support, do not use aliases.

## Related [#related]

* [Common Issues](/docs/packages/packem/guide/troubleshooting/common-issues)
* [Build Errors](/docs/packages/packem/guide/troubleshooting/build-errors)
* [Declaration Files](/docs/packages/packem/options/declaration-files)


# TypeScript (/docs/packages/packem/guide/typescript)





# TypeScript [#typescript]

Packem has first-class TypeScript support. It compiles `.ts` and `.tsx` files with your chosen [transformer](/docs/packages/packem/guide/transformers) and bundles `.d.ts` declaration files automatically — including the extension-matched `.d.mts` / `.d.cts` variants that modern module resolution requires.

## Declaration generation [#declaration-generation]

Declaration output is controlled by the `declaration` option. It accepts a boolean or one of two string modes:

| Value                      | Behavior                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `"compatible"` (or `true`) | `src/index.ts` generates `dist/index.d.mts`, `dist/index.d.cts`, and `dist/index.d.ts`.                      |
| `"node16"`                 | `src/index.ts` generates `dist/index.d.mts` and `dist/index.d.cts`.                                          |
| `false`                    | Disable declaration generation.                                                                              |
| `undefined`                | Auto-detect from `package.json`: if a `types` field is present it becomes `"compatible"`, otherwise `false`. |

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: 'compatible',
})
```

<Callout type="info">
  Leave `declaration` unset and Packem will turn it on automatically whenever your `package.json` has a `types` field. See [Declaration Files](/docs/packages/packem/options/declaration-files) for the full reference.
</Callout>

## Matching declarations to extensions [#matching-declarations-to-extensions]

When you ship `.mjs`/`.cjs` outputs with `node16` (or newer) module resolution, TypeScript expects declaration files whose extension matches the JavaScript file. Packem generates `.d.mts` for ESM and `.d.cts` for CommonJS so the types resolve correctly per condition:

```json
{
  "files": ["dist"],
  "exports": {
    "import": {
      "types": "./dist/index.d.mts",
      "default": "./dist/index.mjs"
    },
    "require": {
      "types": "./dist/index.d.cts",
      "default": "./dist/index.cjs"
    }
  }
}
```

### Hybrid (Node 10 + Node 16) resolution [#hybrid-node-10--node-16-resolution]

To support both legacy and modern resolvers, keep a `types` field for Node 10 and the extension-matched declarations in `exports`:

```json
{
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    "import": {
      "types": "./dist/index.d.mts",
      "default": "./dist/index.mjs"
    },
    "require": {
      "types": "./dist/index.d.cts",
      "default": "./dist/index.cjs"
    }
  }
}
```

You can additionally generate a `typesVersions` map for Node 10 compatibility:

```typescript
export default defineConfig({
  transformer,
  node10Compatibility: {
    typeScriptVersion: '>=5.0',
    writeToPackageJson: true,
  },
})
```

## Isolated declarations (TypeScript 5.5+) [#isolated-declarations-typescript-55]

Declaration generation runs on top of [`@visulima/rollup-plugin-dts`](/docs/packages/packem/api/packem-rollup). Enable TypeScript's isolated declarations feature in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}
```

With this set, Packem uses oxc's `isolatedDeclarationSync` to emit `.d.ts` files without running full type inference — no extra configuration required. Isolated declarations are significantly faster because they avoid whole-program type analysis, at the cost of requiring explicit type annotations on exported symbols.

<Callout type="warning">
  Isolated declaration support requires TypeScript 5.5 or higher and is considered experimental.
</Callout>

## tsconfig.json [#tsconfigjson]

Packem reads your `tsconfig.json`. Path aliases declared under `compilerOptions.paths` are inferred automatically.

```json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

<Callout type="warning">
  Aliases are not supported in type declaration generation. If you need type support across your modules, do not use aliases for those imports.
</Callout>

You can point Packem at a specific tsconfig with the `--tsconfig` CLI flag:

```bash
packem build --tsconfig tsconfig.build.json
```

## Type checking and transformers [#type-checking-and-transformers]

Most transformers (esbuild, swc, OXC, sucrase) strip types without performing full type checking, which is what makes them fast. For type safety, run `tsc --noEmit` as a separate step in your CI pipeline. See [Transformers](/docs/packages/packem/guide/transformers) for the trade-offs of each compiler.

## Declarations-only builds [#declarations-only-builds]

To emit only declaration files without building the JavaScript output, use the `dtsOnly` option or the `--dts-only` CLI flag:

```bash
packem build --dts-only
```

## Next steps [#next-steps]

* [Declaration Files](/docs/packages/packem/options/declaration-files) — the full declaration reference.
* [Transformers](/docs/packages/packem/guide/transformers) — choose the compiler for your project.
* [Package.json Setup](/docs/packages/packem/guide/package-json) — wiring up the `types` field.


# Watch Mode (/docs/packages/packem/guide/watch-mode)





# Watch Mode [#watch-mode]

Watch mode rebuilds your package whenever a source file changes, giving you a fast inner development loop. Enable it with the `--watch` flag:

```bash
packem build --watch
```

A common pattern is to wire it into a `dev` script:

```json
{
  "scripts": {
    "build": "packem build",
    "dev": "packem build --watch"
  }
}
```

## What gets watched [#what-gets-watched]

Packem watches your source directory plus the files that define the build:

* everything under your `src` (source) directory
* `package.json`
* `packem.config.*`
* `tsconfig.json` and `tsconfig.*.json`

`.git`, `node_modules`, and `test-results` directories are ignored.

When TypeScript declaration generation is enabled, Packem starts a second watcher for the `.d.ts` build so declarations are regenerated alongside the JavaScript output.

## Rebuild on config and package.json changes [#rebuild-on-config-and-packagejson-changes]

Rollup's own watcher rebuilds with the same options it started with — it cannot pick up new entry points. To handle this, Packem additionally watches `package.json` and your `packem.config.*`:

* When &#x2A;*`package.json`** changes, Packem closes the watchers, re-infers entries from the updated file, and restarts watching. This is how new entry points are picked up.
* When &#x2A;*`packem.config.*`** changes, Packem prints a notice asking you to restart `packem`, because the watcher cannot reload the config in place (a config change can alter the bundler, transformer, output format, externals, and more).

<Callout type="warning">
  After editing `packem.config.ts` in watch mode, stop and restart `packem build --watch` for the changes to take effect.
</Callout>

## Run a command after each build [#run-a-command-after-each-build]

Use `--onSuccess` to run a command after every successful build — useful for restarting a server during development:

```bash
packem build --watch --onSuccess "node dist/index.js"
```

`onSuccess` can also be a function that returns a `Promise`. This form requires `packem.config.ts` instead of the CLI flag:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  async onSuccess() {
    // Start a long-running task, like a server
  },
})
```

You can return a cleanup function from `onSuccess`; Packem runs it before the next rebuild:

```typescript
import http from 'node:http'

export default defineConfig({
  transformer,
  onSuccess() {
    const server = http.createServer((request, res) => {
      res.end('Hello World!')
    })

    server.listen(3000)

    return () => {
      server.close()
    }
  },
})
```

To control how the child process started by `onSuccess` is terminated, use `--killSignal` (`SIGTERM` or `SIGKILL`).

## Customizing the watcher [#customizing-the-watcher]

You can extend the watch configuration through `rollup.watch`, which accepts Rollup's `WatcherOptions`. Any `include` patterns you add are merged with Packem's defaults:

```typescript
export default defineConfig({
  transformer,
  rollup: {
    watch: {
      include: ['extra-dir/**/*'],
    },
  },
})
```

## Next steps [#next-steps]

* [Watch option](/docs/packages/packem/options/watch) — the option reference.
* [On Success](/docs/packages/packem/options/on-success) — post-build commands.
* [CLI Reference](/docs/packages/packem/guide/cli) — every build flag.


# Packem (/docs/packages/packem)



# Packem [#packem]

A bundler for Node.js and TypeScript libraries. Point it at your `package.json` and get optimized ESM, CJS, and IIFE bundles — with TypeScript declarations, CSS processing, and tree shaking out of the box.

```bash
npm install --save-dev @visulima/packem
npx packem init
npx packem build
```

## Why Packem? [#why-packem]

* **Zero config** — Reads entry points, output formats, and types from your `package.json`. No duplicate configuration.
* **Fast** — Choose between esbuild, swc, OXC, or sucrase. Switch compilers with one config change.
* **TypeScript first** — Generates `.d.ts` declarations automatically, including isolated declarations.
* **CSS included** — Sass, Less, Stylus, PostCSS, and CSS Modules work without extra plugins.
* **React ready** — Server Components, Client Components, and server actions are supported.
* **Multi-runtime** — Target Node.js, browser, edge-light, and react-server from a single build.

## Pick a transformer [#pick-a-transformer]

| Transformer | Speed     | Decorators | Type checking |
| ----------- | --------- | ---------- | ------------- |
| esbuild     | Fastest   | No         | No            |
| swc         | Very fast | Yes        | No            |
| OXC         | Very fast | Partial    | No            |
| sucrase     | Fast      | No         | No            |
| TypeScript  | Moderate  | Yes        | Yes           |

Most projects should start with **esbuild**. See [Transformers](/docs/packages/packem/guide/transformers) for details.

## Packages [#packages]

| Package                       | Description                                 |
| ----------------------------- | ------------------------------------------- |
| `@visulima/packem`            | Bundler core and CLI                        |
| `@visulima/packem-rollup`     | Rollup plugins and transformer integrations |
| `@visulima/rollup-plugin-css` | CSS processing and optimization             |
| `@visulima/css-style-inject`  | Runtime CSS injection utility               |
| `@visulima/packem-share`      | Shared types and constants                  |

## Next steps [#next-steps]

* [Getting Started](/docs/packages/packem/guide/getting-started) — Install Packem and build your first library.
* [Configuration](/docs/packages/packem/guide/configuration) — Customize your build for production.
* [Examples](/docs/packages/packem/examples/) — Copy-and-paste starters for common setups.
* [API Reference](/docs/packages/packem/api/) — Programmatic usage, hooks, and plugin development.


# alias (/docs/packages/packem/options/alias)



# alias [#alias]

Defines custom path aliases for module resolution, similar to TypeScript’s `paths` or Webpack’s `resolve.alias`. Useful for shortening import paths or redirecting modules.

**Type:** `Record<string, string>`\
&#x2A;*Default:** `{}`

## Example [#example]

```typescript
export default defineConfig({
  alias: {
    '@utils': './src/utils',
    '@components': './src/components'
  }
})
```


# allowedExportExtensions (/docs/packages/packem/options/allowed-export-extensions)



# allowedExportExtensions [#allowedexportextensions]

Additional file extensions to consider valid in exports field validation. These will be added to the standard valid extensions.

## Type [#type]

```typescript
allowedExportExtensions?: string[]
```

## Default [#default]

`undefined` (only standard extensions are allowed)

## Description [#description]

By default, packem validates that export paths in your `package.json` have valid file extensions. The standard valid extensions are:

* `.js`, `.mjs`, `.cjs` - JavaScript files
* `.ts`, `.mts`, `.cts` - TypeScript files
* `.d.ts`, `.d.mts`, `.d.cts` - TypeScript declaration files
* `.jsx`, `.tsx` - React files
* `.json` - JSON files
* `.node` - Node.js native addons

Use `extraExportExtensions` to add custom extensions for assets like images, CSS files, or other non-JavaScript files.

## Examples [#examples]

### Basic Usage [#basic-usage]

```typescript
// packem.config.ts
import { defineConfig } from "@visulima/packem/config";

export default defineConfig({
    validation: {
        packageJson: {
            allowedExportExtensions: [".svg", ".css", ".png", ".jpg", ".jpeg", ".gif", ".webp"],
        },
    },
});
```

### With package.json exports [#with-packagejson-exports]

```json
{
  "exports": {
    ".": "./dist/index.mjs",
    "./images": "./dist/images/icon.svg",
    "./assets": "./dist/assets/logo.svg",
    "./styles": "./dist/styles.css"
  }
}
```

With `allowedExportExtensions: [".svg", ".css"]`, these export paths will be considered valid and won't generate warnings.

### Common Asset Extensions [#common-asset-extensions]

Here are some common extensions you might want to add:

```typescript
allowedExportExtensions: [
    // Images
    ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".bmp", ".tiff",
    // Styles
    ".css", ".scss", ".sass", ".less", ".styl",
    // Fonts
    ".woff", ".woff2", ".ttf", ".eot", ".otf",
    // Documents
    ".pdf", ".md", ".txt",
    // Data
    ".xml", ".yaml", ".yml", ".toml"
]
```

## Notes [#notes]

* Extensions should include the leading dot (e.g., `".svg"` not `"svg"`)
* This option only affects validation warnings, not the actual build process
* Use in combination with `ignoreExportKeys` to exclude asset exports from build processing
* Use with `rollup.copy` to copy asset files to the output directory


# analyze (/docs/packages/packem/options/analyze)



# analyze [#analyze]

Enables bundle analysis and reporting. When true, generates a bundle analysis report after build.

**Type:** `boolean`\
&#x2A;*Default:** `undefined`

## Example [#example]

```typescript
export default defineConfig({
  analyze: true
})
```


# Barrel files (/docs/packages/packem/options/barrel)



## Overview [#overview]

Barrel files (e.g., `index.ts`) re‑export from multiple modules for ergonomic imports. They can hurt tree‑shaking and create cycles.
Debarrel rewrites imports that target a barrel file into direct imports from source files at build time (best for dev/test speed and tree‑shaking)

## Debarrel [#debarrel]

Rewrites `import { X } from "./components"` to `import { X } from "./components/X"` (based on re‑exports) during transform.

Enable via Packem config (built-in):

```ts
import { defineConfig } from "@visulima/packem/config";

export default defineConfig({
  rollup: {
    debarrel: {
      // include: [/\.([cm]?tsx?|jsx)$/],
      // possibleBarrelFiles: [/index\.(t|j)sx?$/],
    },
  },
});
```

Notes:

* Targets TS/JS and JSX variants; you can further scope via `include`
* Works purely at build time; no runtime overhead

## Tests [#tests]

See integration tests under `packages/packem/__tests__/intigration`:

* `barrel.test.ts` (general barrel usage)


# builder (/docs/packages/packem/options/builder)



# builder [#builder]

Custom builder functions for advanced build scenarios. Allows you to hook into and extend the build process programmatically.

**Type:** `Record<string, (context, cachePath, fileCache, logged) => Promise<void>>`\
&#x2A;*Default:** `undefined`

## Example [#example]

```typescript
export default defineConfig({
  builder: {
    custom: async (context, cachePath, fileCache, logged) => {
      // Custom build logic here
    }
  }
})
```


# Bundler (/docs/packages/packem/options/bundler)





# Bundler [#bundler]

Packem can build with one of two backends. By default it uses [Rollup](https://rollupjs.org) — the full-featured, fully-supported path. You can opt into the experimental [Rolldown](https://rolldown.rs) backend (a Rust-based, oxc-powered bundler) with the `bundler` option.

```typescript
export default defineConfig({
  bundler: 'rollup',   // default
  // or
  bundler: 'rolldown', // experimental
})
```

## CLI flag [#cli-flag]

You can also select the backend per build without editing the config file:

```sh
packem build --bundler rolldown
```

The flag accepts `rollup` or `rolldown`; any other value is rejected.

## Rolldown backend (experimental) [#rolldown-backend-experimental]

<Callout type="warning">
  The Rolldown backend is **experimental** and not yet at full feature parity with Rollup. Rollup remains the default and the fully-supported path — opting into Rolldown does not deprecate it.
</Callout>

When you select Rolldown, keep these in mind:

* **No `transformer` option.** Rolldown ships its own oxc-based transform and always uses it, so omit the `transformer` option when `bundler` is `'rolldown'`. The `esbuild` / `swc` / `sucrase` / `oxc` transformer adapters only apply under the default `'rollup'` backend.

  ```typescript
  // ✅ Rolldown — no transformer
  export default defineConfig({
    bundler: 'rolldown',
  })

  // ❌ Rolldown + transformer is not supported
  export default defineConfig({
    bundler: 'rolldown',
    transformer: esbuild, // remove this
  })
  ```

* **Declaration files route through Rollup.** Even with `bundler: 'rolldown'`, `.d.ts` generation (and DTS watching) still runs through Rollup. Rollup is pulled in automatically when Rolldown is combined with `declaration: true`, so you don't need to configure anything — but Rollup remains a build-time dependency in that case.

## Choosing a backend [#choosing-a-backend]

|                   | Rollup (default)                            | Rolldown (experimental) |
| ----------------- | ------------------------------------------- | ----------------------- |
| Stability         | Fully supported                             | Experimental, opt-in    |
| Transformer       | Pluggable (esbuild, swc, oxc, sucrase, tsc) | Built-in oxc only       |
| Declaration files | Native                                      | Routed through Rollup   |
| Speed             | Baseline                                    | Faster bundling         |

For the detailed support matrix and the criteria for graduating Rolldown out of experimental status, see [Rolldown backend status](https://github.com/visulima/packem/blob/main/docs/rolldown-status).

***

## Related Options [#related-options]

* [Transformers](/docs/packages/packem/options/transformers) - Choose the code transformer (Rollup backend only)
* [Declaration Files](/docs/packages/packem/options/declaration-files) - TypeScript `.d.ts` generation


# Cleaning (/docs/packages/packem/options/cleaning)





# Cleaning [#cleaning]

The `clean` option controls whether Packem empties the output directory before each build, so that stale artifacts from previous builds are not left behind.

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  clean: true,
})
```

## Default [#default]

`clean` defaults to `true` — the output directory is cleaned before every build.

## Disabling cleaning [#disabling-cleaning]

Set `clean: false` to keep existing files in the output directory:

```typescript
export default defineConfig({
  clean: false,
})
```

## CLI flag [#cli-flag]

There is a `--no-clean` flag on `packem build` that disables cleaning for a single build without editing the config file:

```bash
packem build --no-clean
```

The flag is described as "Do not clean the dist directory before building". There is no separate `--clean` flag — cleaning is on by default, and `--no-clean` opts out.

<Callout type="info">
  The directory that gets cleaned is the resolved output directory (the `outDir` option, which defaults to your tsconfig `outDir` or `dist`).
</Callout>

***

## Related Options [#related-options]

* [Output Directory](/docs/packages/packem/options/output-directory) - Where build artifacts are written
* [Watch Mode](/docs/packages/packem/options/watch) - Rebuild on file changes


# Config File (/docs/packages/packem/options/config-file)





# Config File [#config-file]

Packem supports configuration files to customize your build process. While many options can be set via CLI flags, configuration files provide a more maintainable and powerful way to configure complex builds.

## Configuration File Discovery [#configuration-file-discovery]

Packem automatically discovers configuration files in the following order:

1. `packem.config.ts`
2. `packem.config.js`
3. `packem.config.mjs`
4. `packem.config.cjs`

<Callout type="tip">
  TypeScript configuration files (`packem.config.ts`) are recommended as they provide type safety and autocomplete support.
</Callout>

## Basic Configuration [#basic-configuration]

### TypeScript Configuration [#typescript-configuration]

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  // The transformer is imported and passed as a value
  transformer,

  // Generate source maps for every output
  sourcemap: true,
})
```

<Callout type="info">
  The `transformer` is **imported and passed as a value**, not selected with a
  string. Swap the import to choose a different one — e.g.
  `@visulima/packem/transformer/swc`, `/oxc`, or `/sucrase`. Output formats are
  derived from your `package.json`; you rarely need to set `rollup.output`
  manually.
</Callout>

### JavaScript Configuration [#javascript-configuration]

```javascript
// packem.config.js
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

### CommonJS Configuration [#commonjs-configuration]

```javascript
// packem.config.cjs
const { defineConfig } = require('@visulima/packem/config')
const transformer = require('@visulima/packem/transformer/esbuild')

module.exports = defineConfig({
  transformer,
})
```

## Configuration Schema [#configuration-schema]

The `defineConfig` function provides full TypeScript support and validation:

```typescript
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  // Entry points (optional - auto-detected from package.json)
  entries?: BuildEntry[] | string[]

  // The transformer instance, imported and passed as a value
  transformer?: TransformerFn

  // Generate source maps for every output
  sourcemap?: boolean

  // Minify the output (the active transformer performs the minification)
  minify?: boolean

  // Target runtime environment
  runtime?: 'node' | 'browser' | 'edge-light' | 'react-server' | 'bun' | 'deno' | 'workerd' | 'electron' | 'react-native'

  // Browserslist queries used for transpilation
  browserTargets?: string[]

  // Rollup configuration. Transformer-specific options and CSS options
  // nest here, NOT at the top level.
  rollup?: {
    plugins?: Plugin[]

    // Transformer-specific options
    esbuild?: EsbuildOptions | false
    swc?: SwcPluginConfig | false
    oxc?: OxcOptions | false
    sucrase?: SucrasePluginConfig | false

    // CSS configuration (see the CSS guide for the full StyleOptions shape)
    css?: {
      mode?: 'inject' | 'extract' | 'emit' | 'inline'
      autoModules?: boolean | RegExp | ((id: string) => boolean)
      loaders?: Loader[]
      sourceMap?: boolean | 'inline'
      // ... other CSS options
    }

    // Watcher options, used when the build runs with --watch
    watch?: WatcherOptions | false
    // ... other Rollup options
  }

  // Build hooks (each receives the build context)
  hooks?: {
    'build:before'?: (context) => void | Promise<void>
    'build:done'?: (context) => void | Promise<void>
    // ... other hooks (rollup:options, validate:before, …)
  }
})
```

## Advanced Configuration [#advanced-configuration]

### Conditional Configuration [#conditional-configuration]

Configure different options based on environment:

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem/transformer/esbuild'
import swcTransformer from '@visulima/packem/transformer/swc'

const isDevelopment = process.env.NODE_ENV === 'development'

export default defineConfig({
  // Import each transformer you want to switch between, then pick one
  transformer: isDevelopment ? esbuildTransformer : swcTransformer,

  sourcemap: isDevelopment,

  rollup: {
    plugins: [
      // Development plugins
      ...(isDevelopment ? [devPlugin()] : []),
      // Production plugins
      ...(isDevelopment ? [] : [prodPlugin()])
    ]
  }
})
```

### Function-Based Configuration [#function-based-configuration]

Use a function for dynamic configuration:

The configuration function receives `(environment, mode)`, where
`environment` is `"production" | "development" | undefined` and `mode` is
`"build" | "jit" | "watch"`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem/transformer/esbuild'
import swcTransformer from '@visulima/packem/transformer/swc'

export default defineConfig((environment, mode) => {
  const isProduction = environment === 'production'

  return {
    transformer: isProduction ? swcTransformer : esbuildTransformer,

    sourcemap: !isProduction,

    rollup: {
      // CSS options nest under `rollup.css`
      css: {
        mode: isProduction ? 'extract' : 'inject',
        autoModules: true
      }
    }
  }
})
```

### Async Configuration [#async-configuration]

The configuration function may be `async` and return a `Promise`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig(async () => {
  const { default: extraPlugins } = await import('./build/plugins.js')

  return {
    transformer,

    rollup: {
      plugins: extraPlugins,
    },
  }
})
```

## Configuration Merging [#configuration-merging]

Packem automatically merges configurations from multiple sources:

1. **Default configuration** - Sensible defaults
2. **Configuration file** - Your custom configuration
3. **CLI flags** - Command-line overrides

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  outDir: 'dist',
})
```

```bash
# CLI flags override config file
packem build --outDir build
```

## Environment Variables [#environment-variables]

Access environment variables in your configuration:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  outDir: process.env.PACKEM_OUTPUT_DIR || 'dist',
  sourcemap: process.env.NODE_ENV !== 'production',
})
```

To inject values into the **bundled source** at compile time (rather than into
the config itself), use `.env` files or the `--env.*` CLI flag described below —
Packem replaces matching `process.env.*` references in your code.

### Loading from .env Files [#loading-from-env-files]

You can load compile-time environment variables from `.env` files:

```typescript
export default defineConfig({
  // Path to the .env file (relative to project root or absolute)
  envFile: '.env',

  // Prefix to filter environment variables (default: 'PACKEM_')
  // Only variables starting with this prefix will be loaded
  envPrefix: 'PACKEM_',

  // ...
})
```

**CLI Options:**

You can also specify these via command-line flags:

```bash
# Load from .env file
packem build --env-file .env

# Custom prefix
packem build --env-file .env --env-prefix BUILD_

# CLI options override config file options
packem build --env-file .env.production --env-prefix PROD_
```

**How it works:**

1. Variables are loaded from the specified `.env` file
2. Only variables matching the `envPrefix` are included (default: `PACKEM_`)
3. Variables are replaced at compile-time in your source code
4. CLI `--env.*` variables override `.env` file variables

**Example:**

```bash
# .env file
PACKEM_API_URL=https://api.example.com
PACKEM_VERSION=1.0.0
OTHER_VAR=ignored  # Not loaded (doesn't match prefix)
```

```typescript
// src/index.ts
export const apiUrl = process.env.PACKEM_API_URL;
export const version = process.env.PACKEM_VERSION;
```

After building, these will be replaced with their actual values at compile-time.

## Configuration Validation [#configuration-validation]

Packem validates your configuration and provides helpful error messages:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  runtime: 'invalid', // ❌ TypeScript error: not a valid runtime

  rollup: {
    output: {
      format: 'unknown' // ❌ TypeScript error
    }
  }
})
```

## Custom Configuration Location [#custom-configuration-location]

Specify a custom configuration file location:

<Tabs items="['CLI Flag', 'Environment Variable']">
  <Tab value="CLI Flag">
    ```bash
    packem build --config ./configs/packem.config.ts
    ```
  </Tab>

  <Tab value="Environment Variable">
    ```bash
    PACKEM_CONFIG=./configs/packem.config.ts packem build
    ```
  </Tab>
</Tabs>

## Configuration Presets [#configuration-presets]

Packem provides built-in presets for common use cases, and you can also create your own reusable configuration presets.

### Built-in Presets [#built-in-presets]

#### React Preset [#react-preset]

The React preset configures Babel to handle React JSX transformation. Babel runs **before** your main transformer (esbuild/SWC/etc.), transforming JSX into JavaScript that the transformer can then process. TypeScript is handled by the transformer via parser plugins, not by Babel.

**Quick Setup:**

Use the `add` command to automatically configure React:

```bash
npx packem add react
```

This will automatically set up the React preset and install all necessary dependencies.

**Basic Usage:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react',
  transformer,
})
```

**With React Compiler:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: true
  }),
  transformer,
})
```

**With React Compiler Annotation Mode:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: {
      compilationMode: 'annotation',
      panicThreshold: 'critical_errors'
    }
  }),
  transformer,
})
```

**Custom Options:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: true,
    plugins: [],      // Additional Babel plugins
    presets: []       // Additional Babel presets
  }),
  transformer,
})
```

**How it works:**

1. **Babel** (runs first): Transforms JSX → JS (handles JSX transformation with React Compiler if enabled)
2. **Transformer** (esbuild/SWC/etc.): Processes the code and handles TypeScript transformation via parser plugins
3. **Rollup plugins**: Can parse the code since it's pure JavaScript

**React Preset Options:**

* `compiler`: Enable React Compiler optimization
  * `boolean`: Enable with default options
  * `object`: Configure compiler options
    * `compilationMode`: `"infer"` (default) or `"annotation"` - In annotation mode, only files with `"use memo"` directive are processed
    * `panicThreshold`: `"critical_errors"` (default) or `"all_errors"`
* `plugins`: Additional Babel plugins to include
* `presets`: Additional Babel presets to include

**Note:** The React preset automatically excludes `react` and `react-dom` from unused dependency validation, as these are typically peer dependencies. TypeScript is handled by the transformer (esbuild/SWC/etc.) via parser plugins, not by Babel. This matches the approach used by `@vitejs/plugin-react`.

#### SolidJS Preset [#solidjs-preset]

The SolidJS preset configures Babel to handle SolidJS JSX transformation. Babel runs **before** your main transformer (esbuild/SWC/etc.), transforming JSX into JavaScript that the transformer can then process. TypeScript is handled by the transformer via parser plugins, not by Babel.

**Quick Setup:**

Use the `add` command to automatically configure SolidJS:

```bash
npx packem add solid
```

This will automatically set up the SolidJS preset and install all necessary dependencies.

**Basic Usage:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'solid',
  transformer,
})
```

**With Custom Solid Options:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createSolidPreset } from '@visulima/packem/config/preset/solid'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createSolidPreset({
    solidOptions: {
      generate: 'ssr',
      hydratable: true,
      moduleName: 'solid-js/web'
    }
  }),
  transformer,
})
```

**With Custom Babel Options:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createSolidPreset } from '@visulima/packem/config/preset/solid'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createSolidPreset({
    solidOptions: {
      generate: 'dom'
    },
    env: {
      targets: 'last 2 years'
    },
    typescript: true
  }),
  transformer,
})
```

**How it works:**

1. **Babel** (runs first): Transforms JSX → JS (handles JSX transformation with Solid preset)
2. **Transformer** (esbuild/SWC/etc.): Processes the code and handles TypeScript transformation via parser plugins
3. **Rollup plugins**: Can parse the code since it's pure JavaScript

**Solid Preset Options:**

* `solidOptions`: Configure SolidJS-specific options
  * `moduleName`: Runtime module name (default: `"solid-js/web"`)
  * `generate`: Output mode - `"dom"` (default) or `"ssr"` for server-side rendering
  * `hydratable`: Enable hydratable markers (default: `false`)
  * `delegateEvents`: Enable automatic event delegation (default: `true`)
  * `wrapConditionals`: Enable smart conditional detection (default: `true`)
  * `contextToCustomElements`: Set render context on Custom Elements (default: `true`)
  * `builtIns`: Array of Component exports to auto-import
* `env`: Enable @babel/preset-env (default: `true`)
  * `boolean`: Enable with default targets (`"last 2 years"`)
  * `object`: Configure with custom targets
* `plugins`: Additional Babel plugins to include
* `presets`: Additional Babel presets to include

**Note:** The Solid preset automatically excludes `solid-js`, `solid-js/web`, and `solid-js/store` from unused dependency validation, as these are typically peer dependencies. TypeScript is handled by the transformer (esbuild/SWC/etc.) via parser plugins, not by Babel.

#### Vue Preset [#vue-preset]

The Vue preset configures Rollup with `unplugin-vue` to handle Vue 3 Single File Components (SFCs). The plugin processes `.vue` files and compiles them for Rollup bundling.

**Quick Setup:**

Use the `add` command to automatically configure Vue:

```bash
npx packem add vue
```

This will automatically set up the Vue preset and install all necessary dependencies.

**Basic Usage:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'vue',
  transformer,
})
```

**With Custom Options:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createVuePreset } from '@visulima/packem/config/preset/vue'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createVuePreset({
    pluginOptions: {
      customElement: true,
      include: [/\.vue$/],
      exclude: [/\.vue\.test\.vue$/],
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('my-')
        }
      }
    }
  }),
  transformer,
})
```

**How it works:**

1. **Rollup Plugin** (unplugin-vue): Processes `.vue` files, extracts `<script>`, `<template>`, and `<style>` blocks
2. **Transformer** (esbuild/SWC/etc.): Processes the compiled JavaScript and handles TypeScript transformation
3. **CSS Processing**: Styles are handled by Packem's CSS processing pipeline

**Vue Preset Options:**

* `pluginOptions`: Configure the Vue plugin options
  * `customElement`: Enable custom elements mode (default: `false`)
  * `include`: Include patterns for Vue files (default: `[/\.vue$/]`)
  * `exclude`: Exclude patterns for Vue files
  * `template`: Template compiler options
    * `compilerOptions`: Vue template compiler options
      * `isCustomElement`: Function to determine if a tag is a custom element

**Note:** The Vue preset automatically excludes `vue` from unused dependency validation, as it's typically a peer dependency.

#### Svelte Preset [#svelte-preset]

The Svelte preset configures Rollup with `rollup-plugin-svelte` to handle Svelte components. The plugin processes `.svelte` files and compiles them for Rollup bundling.

**Quick Setup:**

Use the `add` command to automatically configure Svelte:

```bash
npx packem add svelte
```

This will automatically set up the Svelte preset and install all necessary dependencies.

**Basic Usage:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'svelte',
  transformer,
})
```

**With Custom Options:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createSveltePreset } from '@visulima/packem/config/preset/svelte'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createSveltePreset({
    pluginOptions: {
      compilerOptions: {
        generate: 'ssr',
        hydratable: true,
        customElement: false
      },
      include: [/\.svelte$/],
      exclude: [/\.svelte\.test\.svelte$/],
      preprocess: {
        // Preprocessor options
      }
    }
  }),
  transformer,
})
```

**How it works:**

1. **Rollup Plugin** (rollup-plugin-svelte): Processes `.svelte` files, compiles components to JavaScript
2. **Transformer** (esbuild/SWC/etc.): Processes the compiled JavaScript and handles TypeScript transformation
3. **CSS Processing**: Styles are extracted and handled by Packem's CSS processing pipeline

**Svelte Preset Options:**

* `pluginOptions`: Configure the Svelte plugin options
  * `compilerOptions`: Svelte compiler options
    * `generate`: Output mode - `"dom"` (default) or `"ssr"` for server-side rendering
    * `hydratable`: Enable hydratable markers (default: `false`)
    * `customElement`: Compile components to custom elements (default: `false`)
    * `dev`: Enable dev mode (default: `false`)
  * `include`: Include patterns for Svelte files (default: `[/\.svelte$/]`)
  * `exclude`: Exclude patterns for Svelte files
  * `preprocess`: Preprocessor options for Svelte components

**Note:** The Svelte preset automatically excludes `svelte` from unused dependency validation, as it's typically a peer dependency.

### Custom Presets [#custom-presets]

Create reusable configuration presets:

```typescript
// configs/presets.ts
import transformer from '@visulima/packem/transformer/esbuild'

export const libraryPreset = {
  transformer,
  sourcemap: true,
  declaration: true,
  hooks: {
    'build:before': async () => {
      console.log('Preset hook: Preparing library build')
    }
  }
}

export const cliPreset = {
  transformer,
  outDir: 'bin',
}
```

```typescript
// packem.config.ts
import { defineConfig } from '@visulima/packem/config'
import { libraryPreset } from './configs/presets'

export default defineConfig({
  ...libraryPreset,

  // Override specific options
  rollup: {
    ...libraryPreset.rollup,
    css: {
      mode: 'extract'
    }
  },

  // Hooks from preset are automatically merged
  // You can add your own hooks or override preset hooks
  hooks: {
    'build:done': async () => {
      console.log('User hook: Build completed')
    }
    // Preset's 'build:before' hook is still registered
  }
})
```

<Callout type="tip">
  Hooks from presets are automatically merged with your configuration. If you define the same hook in both, your hook will take precedence.
</Callout>

## Configuration Composition [#configuration-composition]

`defineConfig` takes a plain object, so you can compose configuration from
multiple sources with object spreading — later spreads win:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'
import baseConfig from './base.config'
import cssConfig from './css.config'

export default defineConfig({
  ...baseConfig,
  ...cssConfig,

  // Additional overrides
  transformer,
  rollup: {
    ...baseConfig.rollup,
    ...cssConfig.rollup,
  },
})
```

## IDE Support [#ide-support]

### TypeScript IntelliSense [#typescript-intellisense]

Get full autocomplete and type checking in your configuration:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  rollup: {
    output: {
      // TypeScript autocompletes Rollup options here
      format: '|' // Shows: 'es' | 'cjs' | 'iife' | 'umd' | 'system'
    }
  }
})
```

### Configuration Schema [#configuration-schema-1]

Import the `BuildConfig` type for better IDE support:

```typescript
import { defineConfig } from '@visulima/packem/config'
import type { BuildConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

const config: BuildConfig = {
  transformer,
  sourcemap: true,
}

export default defineConfig(config)
```

## Debugging Configuration [#debugging-configuration]

Enable debug mode to see the resolved configuration:

```bash
# Debug configuration resolution
PACKEM_DEBUG=1 packem build

# Debug specific areas
PACKEM_DEBUG=config,rollup packem build
```

Or programmatically:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  debug: true, // Enable debug logging

  transformer,
  // ... rest of config
})
```

## Configuration Examples [#configuration-examples]

### React Library [#react-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],

  rollup: {
    esbuild: {
      jsx: 'automatic',
      jsxImportSource: 'react'
    }
  }
})
```

### Node.js CLI Tool [#nodejs-cli-tool]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  rollup: {
    output: {
      banner: '#!/usr/bin/env node'
    }
  }
})
```

### Library with CSS [#library-with-css]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['express', 'mongoose'],

  rollup: {
    css: {
      mode: 'extract',
      autoModules: true
    }
  }
})
```

***

## Related Options [#related-options]

* [Entry](/docs/packages/packem/options/entry) - Configure entry points
* [Output Format](/docs/packages/packem/options/output-format) - Control output formats
* [Transformers](/docs/packages/packem/options/transformers) - Choose and configure transformers
* [Hooks](/docs/packages/packem/options/hooks) - Build lifecycle hooks


# debug (/docs/packages/packem/options/debug)



# debug [#debug]

Enables verbose debug logging for troubleshooting and development.

**Type:** `boolean`\
&#x2A;*Default:** `false`

## Example [#example]

```typescript
export default defineConfig({
  debug: true
})
```


# Declaration Files (dts) (/docs/packages/packem/options/declaration-files)





# Declaration Files (dts) [#declaration-files-dts]

Packem provides comprehensive TypeScript declaration file generation with support for both traditional and isolated declarations. Declaration files (`.d.ts`) are essential for TypeScript libraries to provide type information to consumers.

## Automatic Detection [#automatic-detection]

Packem automatically enables declaration file generation when it detects TypeScript usage in your project:

* TypeScript files (`.ts`, `.tsx`) in your source code
* `types` or `typings` field in your `package.json`
* `tsconfig.json` file in your project

```json
{
  "name": "my-library",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}
```

## Configuration [#configuration]

The `declaration` option is a boolean or one of the string modes `"compatible"` / `"node16"`:

| Value          | Behaviour                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `"compatible"` | Generates `dist/index.d.mts`, `dist/index.d.cts` **and** `dist/index.d.ts`.                                   |
| `true`         | Equivalent to `"compatible"`.                                                                                 |
| `"node16"`     | Generates `dist/index.d.mts` and `dist/index.d.cts` only.                                                     |
| `false`        | Disables declaration generation.                                                                              |
| `undefined`    | Auto-detect from `package.json`: if a `types` field is present → `"compatible"`, otherwise `false`. (default) |

### Enable/Disable Declaration Generation [#enabledisable-declaration-generation]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  // Explicitly enable declaration generation ("compatible")
  declaration: true,
})
```

To restrict output to the dual `.d.mts` / `.d.cts` files only, use `"node16"`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: 'node16',
})
```

### Per-format Declaration Control [#per-format-declaration-control]

If you need to emit only one declaration flavour without triggering the matching JavaScript build, use `declarationCjs` and `declarationEsm`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  // Generate .d.cts without producing a CJS JS bundle
  declarationCjs: true,
  // Generate .d.mts without producing an ESM JS bundle
  declarationEsm: true,
})
```

## Isolated Declarations [#isolated-declarations]

Isolated declarations are a TypeScript 5.5+ feature that dramatically improves declaration generation performance by avoiding expensive type inference. Packem's DTS pipeline (powered by [`@visulima/rollup-plugin-dts`](https://github.com/visulima/packem/tree/main/packages/rollup-plugin-dts)) detects isolated declarations automatically and uses the fast oxc-based generator when available, falling back to `tsc` otherwise.

<Callout type="info">
  Isolated declarations can be 10-100x faster than traditional declaration generation for large projects.
</Callout>

### Enable Isolated Declarations [#enable-isolated-declarations]

Add `"isolatedDeclarations": true` to your `tsconfig.json`. Packem picks it up automatically — there is no Packem-level option for it.

```json
// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}
```

Your `packem.config.ts` stays minimal:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

### Isolated Declarations Requirements [#isolated-declarations-requirements]

For isolated declarations to work, your TypeScript code must follow certain patterns:

```typescript
// ✅ Good - Explicit return types
export function greet(name: string): string {
  return `Hello, ${name}!`
}

// ✅ Good - Explicit interface
export interface User {
  id: number
  name: string
}

// ❌ Bad - Inferred return type
export function greet(name: string) {
  return `Hello, ${name}!`
}

// ❌ Bad - Inferred type
export const config = {
  apiUrl: 'https://api.example.com'
}

// ✅ Good - Explicit type
export const config: { apiUrl: string } = {
  apiUrl: 'https://api.example.com'
}
```

<Callout type="warning">
  Isolated declarations require explicit type annotations on all exported declarations. This is a TypeScript compiler requirement, not a Packem limitation.
</Callout>

<Callout type="info">
  **JSDoc comments:** The oxc-based generator does not preserve JSDoc comments. If your library's API documentation relies on JSDoc in `.d.ts` output, turn off `isolatedDeclarations` in tsconfig so Packem falls back to `tsc` (which preserves comments when `removeComments` is not `true`).
</Callout>

## Declaration File Formats [#declaration-file-formats]

Packem generates declaration files that match your output formats:

### ESM/CJS Dual Package [#esmcjs-dual-package]

```json
{
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  }
}
```

Packem will generate:

* `dist/index.d.mts` - ESM declaration file
* `dist/index.d.cts` - CJS declaration file

### Legacy Node.js Compatibility [#legacy-nodejs-compatibility]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    node10Compatibility: {
      typeScriptVersion: '>=5.0',
      writeToPackageJson: true
    }
  }
})
```

This generates `typesVersions` in your `package.json` for Node.js 10 compatibility:

```json
{
  "types": "./dist/index.d.ts",
  "typesVersions": {
    ">=5.0": {
      "*": ["./dist/index.d.ts"]
    }
  }
}
```

## Include/Exclude Filters [#includeexclude-filters]

Control which source files have `.d.ts` declarations generated using `include` and `exclude` patterns.
This is useful when you want to skip declaration generation for specific files (e.g., test utilities, internal helpers).

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true,

  rollup: {
    dts: {
      // Only generate declarations for files in src/
      include: ['src/**/*.ts'],
      // Skip test files and internal modules
      exclude: ['src/**/*.test.ts', 'src/internal/**']
    }
  }
})
```

Patterns accept minimatch glob strings, regular expressions, or arrays of either. When neither `include` nor `exclude` is specified, all source files are processed.

## Inlining Types from External Packages [#inlining-types-from-external-packages]

Packem automatically inlines types from **optional peer dependencies** and **optional dependencies** into your `.d.ts` output, while keeping them external for JS. This prevents `TS2307` errors for consumers who don't install all your optional peers.

### Automatic Behavior [#automatic-behavior]

Types are automatically inlined for:

* Packages in `optionalDependencies`
* Packages in `peerDependencies` that are marked as optional in `peerDependenciesMeta`

```json
{
  "peerDependencies": {
    "webpack": "^5.0.0",
    "vite": "^5.0.0",
    "react": "^18.0.0"
  },
  "peerDependenciesMeta": {
    "webpack": { "optional": true },
    "vite": { "optional": true }
  }
}
```

With this config, types from `webpack` and `vite` are automatically inlined in `.d.ts` output (since they're optional), while `react` stays external (since it's a required peer).

### Manual Configuration [#manual-configuration]

Use `rollup.dts.resolve` to add extra packages or override the automatic behavior:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    dts: {
      // Add extra packages on top of auto-detected ones
      resolve: ['some-extra-package', /^@farmfe\//]
    }
  }
})
```

Options:

* `true` — inline types from all node\_modules
* `false` — disable auto-resolution, keep all dependencies external in `.d.ts`
* `(string | RegExp)[]` — merged with auto-detected optional peers/deps

## Multiple Entry Points [#multiple-entry-points]

Generate declarations for multiple entry points:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils.ts',
    cli: 'src/cli.ts'
  },

  declaration: true
})
```

This generates:

* `dist/index.d.ts`
* `dist/utils.d.ts`
* `dist/cli.d.ts`

## Declaration Maps [#declaration-maps]

Declaration maps let IDEs navigate from compiled declaration files back to the original TypeScript source. They are driven by the TypeScript `declarationMap` compiler option — enable it in your `tsconfig.json`:

```json
// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true
  }
}
```

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

## Path Mapping [#path-mapping]

Resolve TypeScript path mappings in declarations:

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
```

```typescript
// src/index.ts
import { helper } from '@utils/helper'
import { Component } from '@/components/Component'
```

Packem automatically resolves these paths in the generated declarations.

## Validation [#validation]

Validate your declaration files with external tools:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true,

  hooks: {
    'build:done': async () => {
      // Run attw (Are The Types Wrong?)
      await import('@arethetypeswrong/core').then(({ analyze }) => {
        return analyze('./package.json')
      })
    }
  }
})
```

## Performance Optimization [#performance-optimization]

### Use Isolated Declarations [#use-isolated-declarations]

For maximum performance, enable isolated declarations in your `tsconfig.json`. Packem uses the oxc-based fast path automatically:

```json
// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}
```

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

### Incremental Compilation [#incremental-compilation]

Enable TypeScript incremental compilation:

```json
// tsconfig.json
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
```

## Troubleshooting [#troubleshooting]

### Declaration Generation Fails [#declaration-generation-fails]

1. **Check TypeScript version**: Ensure you're using TypeScript 4.5 or later
2. **Verify tsconfig.json**: Ensure your TypeScript configuration is valid
3. **Check for type errors**: Fix any TypeScript compilation errors
4. **Use explicit types**: For isolated declarations, ensure all exports have explicit types

### Missing Types [#missing-types]

```typescript
// Add explicit return type
export function myFunction(): string {
  return 'hello'
}

// Add explicit interface
export interface MyConfig {
  apiUrl: string
}
```

### Path Resolution Issues [#path-resolution-issues]

Ensure your `tsconfig.json` paths are correctly configured:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"]
}
```

### Missing JSDoc Comments in Declaration Files [#missing-jsdoc-comments-in-declaration-files]

If JSDoc comments are missing from your generated `.d.ts` files:

1. **Check `removeComments`**: Ensure `removeComments` is not `true` in your `tsconfig.json`. TypeScript strips all comments (including JSDoc) from declaration output when this is enabled.
2. **Isolated declarations strip comments**: The oxc-based fast path used when `isolatedDeclarations: true` is set does not preserve JSDoc. Turn off `isolatedDeclarations` in tsconfig to fall back to `tsc`, which preserves comments.

```json
// tsconfig.json
{
  "compilerOptions": {
    "removeComments": false
  }
}
```

### Performance Issues [#performance-issues]

1. **Use isolated declarations** for large projects
2. **Enable incremental compilation** in TypeScript
3. **Exclude test files** from declaration generation using `rollup.dts.exclude`

## Examples [#examples]

### Basic Library [#basic-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

### React Component Library [#react-component-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  declaration: true,

  externals: ['react', 'react-dom'],

  rollup: {
    esbuild: {
      jsx: 'automatic',
      jsxImportSource: 'react'
    }
  }
})
```

### High-Performance Library [#high-performance-library]

Enable isolated declarations in `tsconfig.json` and let Packem use the fast oxc-based generator:

```json
// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}
```

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  declaration: true
})
```

***

## Known Limitations [#known-limitations]

### Isolated Declarations (oxc fast path) [#isolated-declarations-oxc-fast-path]

* **JSDoc comments are not preserved.** The oxc-based generator strips all comments. Turn off `isolatedDeclarations` in tsconfig (to fall back to `tsc`) if your library relies on JSDoc in `.d.ts` files.
* **Triple-slash directives are not preserved.** `/// <reference types="..." />` directives in source files are stripped by oxc. They are preserved when using the `dtsInput` mode with pre-generated `.d.ts` files.

### TypeScript Compiler (tsc) [#typescript-compiler-tsc]

* **JSDoc comments are stripped when `removeComments: true`** in your `tsconfig.json`. Ensure this is set to `false` if you want JSDoc comments in your declaration output.
* **Triple-slash directives are not always emitted.** TypeScript only includes `/// <reference>` directives in `.d.ts` output when it determines they are necessary for the output types. Source-level directives may be omitted.

### DTS Bundling [#dts-bundling]

* **Namespace imports for complex types.** When inlining types from external packages via `rollup.dts.resolve`, packages with complex type dependencies may produce namespace imports (`import * as pkg from 'pkg'`) in the output rather than fully inlining all type definitions.
* **`@babel/generator` is used for code generation.** Any upstream Babel bugs with TypeScript AST nodes may affect the bundled `.d.ts` output.

***

## Related Options [#related-options]

* [Transformers](/docs/packages/packem/options/transformers) - Choose compatible transformers
* [Output Format](/docs/packages/packem/options/output-format) - Match declaration formats to output formats
* [TSConfig](/docs/packages/packem/options/declaration-files) - TypeScript configuration integration
* [Package Exports](/docs/packages/packem/options/package-exports) - Automatic exports generation


# Duplicate packages (/docs/packages/packem/options/detect-duplicated)



## Overview [#overview]

When several of your dependencies depend on different versions of the same package — or the same version resolved from different locations (for example, distinct peer-dependency variants under pnpm) — that package ends up **bundled more than once**. This inflates bundle size and can cause subtle bugs when two copies of a library don't share state.

Packem ships a built-in detector that walks the final module graph after each build and reports any package that was bundled multiple times, along with the files that imported each copy.

It is **enabled by default**.

## Example output [#example-output]

```text
WARNING  packages ms is bundled multiple times!

  ms:
    - 2.0.0 imported by packages/pkg1/index.js
    - 2.1.3 imported by packages/pkg2/index.js
```

A runnable demo lives in [`examples/duplicated-packages`](https://github.com/visulima/packem/tree/main/examples/duplicated-packages).

## Configuration [#configuration]

Configure (or disable) it through the `rollup.detectDuplicated` option:

```ts
import { defineConfig } from "@visulima/packem/config";

export default defineConfig({
  rollup: {
    detectDuplicated: {
      // Stop reporting specific packages/versions. Use "*" to ignore all versions.
      ignore: {
        axios: ["0.27.2"],
        lodash: ["*"],
      },

      // Only report duplicates imported directly by your own source,
      // ignoring those pulled in transitively by another dependency.
      // @default true
      deep: true,

      // Fail the build (non-zero exit) when duplicates are found.
      // @default false
      throwErrorWhenDuplicated: false,

      // Build a custom report from the collected data instead of the default one.
      // customErrorMessage: (packagesInfo) => `...`,
    },
  },
});
```

### Disable it [#disable-it]

```ts
import { defineConfig } from "@visulima/packem/config";

export default defineConfig({
  rollup: {
    detectDuplicated: false,
  },
});
```

## Options [#options]

| Option                     | Type                                     | Default | Description                                                                                                    |
| -------------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `deep`                     | `boolean`                                | `true`  | When `false`, only duplicates imported directly by your own source are reported (transitive ones are ignored). |
| `ignore`                   | `Record<string, string[]>`               | `{}`    | Packages/versions to skip. Pass `"*"` as a version to ignore every version of that package.                    |
| `throwErrorWhenDuplicated` | `boolean`                                | `false` | Fail the build when duplicates are detected instead of only warning.                                           |
| `customErrorMessage`       | `(packagesInfo: PackagesInfo) => string` | —       | Replace the default report with your own message, built from the collected duplicate map.                      |

## Notes [#notes]

* The detector inspects the **bundled** module graph, so dependencies that are externalized (not bundled) are never flagged.
* Detection runs at `buildEnd`, which means it works correctly with Packem's build cache and watch mode — there is no extra module resolution cost.
* Set `detectDuplicated: false` if you don't want the check (for example, in a project that intentionally bundles multiple versions).

## Tests [#tests]

See `packages/packem/__tests__/intigration/detect-duplicated.test.ts`.


# Entry Points (/docs/packages/packem/options/entry)





# Entry Points [#entry-points]

Entry points define which files Packem should process as the starting points for your build. Packem can automatically detect entry points from your `package.json` or you can configure them explicitly.

## Basic Configuration [#basic-configuration]

### Single Entry Point [#single-entry-point]

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  entries: ['./src/index.ts']
})
```

### Multiple Entry Points [#multiple-entry-points]

```typescript
export default defineConfig({
  entries: [
    './src/index.ts',
    './src/cli.ts',
    './src/worker.ts'
  ]
})
```

### Entry Objects [#entry-objects]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      name: 'main'
    },
    {
      input: './src/cli.ts',
      name: 'cli',
      executable: true
    }
  ]
})
```

## Automatic Detection [#automatic-detection]

### From Package.json Exports [#from-packagejson-exports]

If no entries are specified, Packem automatically detects them from your `package.json`:

```json
{
  "exports": {
    ".": "./src/index.ts",
    "./utils": "./src/utils.ts",
    "./cli": "./src/cli.ts"
  }
}
```

This automatically creates entries for all export paths.

### From Package.json Fields [#from-packagejson-fields]

```json
{
  "main": "./src/index.ts",
  "module": "./src/index.ts",
  "bin": {
    "my-cli": "./src/cli.ts"
  }
}
```

Packem detects entries from:

* `main` field
* `module` field
* `bin` field (marked as executable)
* `exports` field

## Entry Configuration Options [#entry-configuration-options]

### Entry Object Properties [#entry-object-properties]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',      // Source file path
      name: 'index',                // Output name
      outDir: './dist',             // Custom output directory
      runtime: 'node',              // Target runtime
      declaration: true,            // Generate .d.ts files
      executable: true,             // Add shebang for CLI tools
      cjs: true,                    // Generate CJS output
      esm: true                     // Generate ESM output
    }
  ]
})
```

## Manual Entry Configuration [#manual-entry-configuration]

You can override automatic detection by specifying entries in your configuration file:

### Simple String Entries [#simple-string-entries]

```typescript
export default defineConfig({
  entries: [
    './src/index.ts',
    './src/cli.ts'
  ]
})
```

### Object Entries [#object-entries]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      name: 'main',
      runtime: 'node'
    },
    {
      input: './src/browser.ts', 
      name: 'browser',
      runtime: 'browser'
    }
  ]
})
```

### Mixed Entries [#mixed-entries]

```typescript
export default defineConfig({
  entries: [
    './src/index.ts',           // Simple string
    {                           // Object configuration
      input: './src/cli.ts',
      name: 'cli',
      executable: true
    }
  ]
})
```

## Glob Patterns [#glob-patterns]

Use glob patterns to match multiple files:

```typescript
export default defineConfig({
  entries: [
    './src/components/*.ts',
    './src/utils/**/*.ts'
  ]
})
```

## Conditional Entries [#conditional-entries]

### Environment-Based [#environment-based]

```typescript
export default defineConfig({
  entries: [
    './src/index.ts',
    ...(process.env.NODE_ENV === 'development' ? ['./src/dev.ts'] : []),
    ...(process.env.BUILD_CLI === 'true' ? ['./src/cli.ts'] : [])
  ]
})
```

### Feature Flags [#feature-flags]

```typescript
export default defineConfig({
  entries: [
    './src/index.ts',
    ...(process.env.ENABLE_WORKER ? [
      {
        input: './src/worker.ts',
        name: 'worker',
        runtime: 'browser'
      }
    ] : [])
  ]
})
```

## Runtime-Specific Entries [#runtime-specific-entries]

### Node.js Entries [#nodejs-entries]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/server.ts',
      name: 'server',
      runtime: 'node',
      cjs: true
    }
  ]
})
```

### Browser Entries [#browser-entries]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/client.ts',
      name: 'client', 
      runtime: 'browser',
      esm: true
    }
  ]
})
```

### Universal Entries [#universal-entries]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/universal.ts',
      name: 'universal',
      cjs: true,
      esm: true
    }
  ]
})
```

## Output Configuration [#output-configuration]

### Custom Output Directory [#custom-output-directory]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      outDir: './build'
    }
  ]
})
```

### Per-Entry Output [#per-entry-output]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/core.ts',
      outDir: './dist/core'
    },
    {
      input: './src/utils.ts', 
      outDir: './dist/utils'
    }
  ]
})
```

## TypeScript Declaration Files [#typescript-declaration-files]

### Enable Declarations [#enable-declarations]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      declaration: true
    }
  ]
})
```

### Declaration Modes [#declaration-modes]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      declaration: 'compatible'  // or 'node16'
    }
  ]
})
```

## Executable Entries [#executable-entries]

### CLI Tools [#cli-tools]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/cli.ts',
      name: 'cli',
      executable: true
    }
  ]
})
```

This automatically:

* Adds shebang (`#!/usr/bin/env node`)
* Sets executable permissions
* Configures for Node.js runtime

## Monorepo Entries [#monorepo-entries]

### Workspace Packages [#workspace-packages]

```typescript
export default defineConfig({
  entries: [
    {
      input: './packages/core/src/index.ts',
      name: 'core',
      outDir: './packages/core/dist'
    },
    {
      input: './packages/utils/src/index.ts',
      name: 'utils', 
      outDir: './packages/utils/dist'
    }
  ]
})
```

### Cross-Package Dependencies [#cross-package-dependencies]

```typescript
export default defineConfig({
  entries: [
    './packages/*/src/index.ts'
  ],
  
  rollup: {
    external: ['@myorg/core', '@myorg/utils']
  }
})
```

## Advanced Patterns [#advanced-patterns]

### Dynamic Entry Generation [#dynamic-entry-generation]

```typescript
import { glob } from 'glob'

const componentEntries = glob.sync('./src/components/*/index.ts').map(file => ({
  input: file,
  name: file.split('/').slice(-2, -1)[0]
}))

export default defineConfig({
  entries: [
    './src/index.ts',
    ...componentEntries
  ]
})
```

### Entry Aliases [#entry-aliases]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      fileAlias: 'main'
    }
  ]
})
```

### Export Key Mapping [#export-key-mapping]

```typescript
export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      exportKey: new Set(['.', './main'])
    }
  ]
})
```

## Validation and Debugging [#validation-and-debugging]

### Entry Validation [#entry-validation]

Packem automatically validates entries:

* Checks if source files exist
* Warns about missing files
* Validates entry configuration
* Checks for conflicts

### Debug Entry Detection [#debug-entry-detection]

```typescript
export default defineConfig({
  debug: true,  // Shows entry detection process
  entries: [
    './src/index.ts'
  ]
})
```

## Troubleshooting [#troubleshooting]

### Entry Not Found [#entry-not-found]

<Callout type="warning">
  If Packem can't find your entry files, check the file paths and ensure they exist.
</Callout>

```typescript
// ❌ Wrong - file doesn't exist
export default defineConfig({
  entries: ['./src/missing.ts']
})

// ✅ Correct - file exists
export default defineConfig({
  entries: ['./src/index.ts']
})
```

### Conflicting Entries [#conflicting-entries]

```typescript
// ❌ Wrong - same output name
export default defineConfig({
  entries: [
    { input: './src/a.ts', name: 'main' },
    { input: './src/b.ts', name: 'main' }  // Conflict!
  ]
})

// ✅ Correct - unique names
export default defineConfig({
  entries: [
    { input: './src/a.ts', name: 'a' },
    { input: './src/b.ts', name: 'b' }
  ]
})
```

### Missing Package.json Exports [#missing-packagejson-exports]

If automatic detection isn't working:

```json
{
  "exports": {
    ".": "./src/index.ts"
  }
}
```

Or specify entries manually:

```typescript
export default defineConfig({
  entries: ['./src/index.ts']
})
```

***

## Related Options [#related-options]

* [Output Format](/docs/packages/packem/options/output-format) - Configure output formats
* [Output Directory](/docs/packages/packem/options/output-directory) - Control output locations
* [Declaration Files](/docs/packages/packem/options/declaration-files) - TypeScript declarations
* [Externals](/docs/packages/packem/options/externals) - External dependencies


# Externals (/docs/packages/packem/options/externals)





# External Dependencies [#external-dependencies]

External dependencies are modules that should not be bundled with your library. Instead, they are expected to be provided by the consuming application. Externalizing dependencies keeps your bundle small and avoids shipping duplicate copies of packages like React or Node.js built-ins.

Packem exposes two related controls:

* **`externals`** — a top-level array that force-marks specific specifiers (or patterns) as external.
* **`rollup.resolveExternals`** — automatic classification of `package.json` dependency groups and Node.js built-ins, plus an `exclude` list to force-bundle specific specifiers.

## Default Behavior [#default-behavior]

<Callout type="info">
  You usually need **no externals configuration at all**. By default Packem already externalizes your `dependencies`, `peerDependencies`, `optionalDependencies`, and Node.js built-in modules (`fs`, `path`, `node:url`, …).
</Callout>

The default classification is:

| Group                  | Externalized by default? |
| ---------------------- | ------------------------ |
| `dependencies`         | yes (`deps: true`)       |
| `peerDependencies`     | yes (`peerDeps: true`)   |
| `optionalDependencies` | yes (`optDeps: true`)    |
| Node.js built-ins      | yes (`builtins: true`)   |
| `devDependencies`      | no (`devDeps: false`)    |

Because of this, most libraries only need to declare their runtime packages in `package.json` and let Packem do the rest. Reach for the options below when you need to deviate from the defaults.

## The `externals` Array [#the-externals-array]

Use the top-level `externals` option to force-externalize additional specifiers that would not otherwise be classified as external. It accepts an array of strings and/or `RegExp` values — it is **not** a function.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],
})
```

* **Strings** are matched against the import specifier.
* **`RegExp`** values are tested against the import id, which is handy for whole scopes or families of packages.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: [
    'react',
    'react-dom',
    /^@myscope\//, // every package under the @myscope/ namespace
  ],
})
```

### React library example [#react-library-example]

A typical React component library declares `react` and `react-dom` as peer dependencies. They are then externalized automatically. If you also want to make sure the JSX runtime entry points stay external, list them explicitly:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom', 'react/jsx-runtime'],
})
```

### Monorepo scope example [#monorepo-scope-example]

To keep every workspace package under a shared scope external (so each one is resolved at runtime rather than inlined), use a `RegExp`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: [/^@mycompany\//],
})
```

## Automatic Classification: `rollup.resolveExternals` [#automatic-classification-rollupresolveexternals]

`rollup.resolveExternals` controls how Packem classifies dependency groups and Node.js built-ins. You only need it when you want to change the defaults shown above.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolveExternals: {
      deps: true,
      peerDeps: true,
      optDeps: true,
      builtins: true,
      devDeps: false,
    },
  },
})
```

### Options [#options]

| Option           | Type                           | Default | Description                                                                                          |
| ---------------- | ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `builtins`       | `boolean`                      | `true`  | Mark Node.js built-ins (`path`, `fs`, …) as external. Set to `false` to use shims/polyfills instead. |
| `builtinsPrefix` | `"add" \| "ignore" \| "strip"` | `"add"` | How to handle the `node:` prefix on built-in imports.                                                |
| `deps`           | `boolean`                      | `true`  | Mark `dependencies` as external.                                                                     |
| `devDeps`        | `boolean`                      | `false` | Mark `devDependencies` as external.                                                                  |
| `optDeps`        | `boolean`                      | `true`  | Mark `optionalDependencies` as external.                                                             |
| `peerDeps`       | `boolean`                      | `true`  | Mark `peerDependencies` as external.                                                                 |
| `exclude`        | `(RegExp \| string)[]`         | `[]`    | Specifiers forced to be **bundled**, overriding every other rule.                                    |

### Force-bundling with `exclude` [#force-bundling-with-exclude]

The `exclude` list does the opposite of `externals`: matching specifiers are forced **into** the bundle even if they would otherwise be classified as external (for example a `dependency` or `peerDependency`). This is useful for tiny, ESM-only packages you would rather inline.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolveExternals: {
      // Bundle this package even though it is a dependency:
      exclude: ['some-tiny-esm-only-pkg', /^@internal\//],
    },
  },
})
```

* **Strings** are matched as exact specifiers.
* **`RegExp`** values are tested against the import id.

`exclude` overrides all other rules — `deps`, `peerDeps`, `optDeps`, and `builtins` — so a matched specifier is always bundled.

### Bundle everything (for IIFE / standalone output) [#bundle-everything-for-iife--standalone-output]

When producing a self-contained bundle (such as an IIFE for the browser), turn off every classification so nothing is left external:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolveExternals: {
      deps: false,
      peerDeps: false,
      optDeps: false,
      builtins: false,
    },
  },
})
```

If you only need to bundle a few specific packages rather than everything, list them in `exclude` instead of disabling whole groups.

## Node.js Built-ins and the `node:` Prefix [#nodejs-built-ins-and-the-node-prefix]

`builtinsPrefix` controls how Packem rewrites imports of Node.js built-in modules:

* `"add"` (default) — turns `'path'` into `'node:path'`.
* `"strip"` — turns `'node:path'` into `'path'`.
* `"ignore"` — leaves names exactly as written.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    resolveExternals: {
      builtins: true,
      builtinsPrefix: 'add', // 'path' -> 'node:path'
    },
  },
})
```

To bundle Node.js built-ins with shims/polyfills instead of externalizing them, set `builtins: false`.

## Validating Externals [#validating-externals]

You can verify your externalization is working by inspecting the output in the `build:done` hook:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],
  hooks: {
    'build:done': async () => {
      const { readFile } = await import('node:fs/promises')
      const bundle = await readFile('dist/index.mjs', 'utf-8')

      if (bundle.includes('React.createElement')) {
        throw new Error('react was bundled instead of being left external')
      }
    },
  },
})
```

## Troubleshooting [#troubleshooting]

### A package is being bundled when it should be external [#a-package-is-being-bundled-when-it-should-be-external]

* Make sure it is listed in your `package.json` under `dependencies`, `peerDependencies`, or `optionalDependencies` — those groups are externalized by default.
* If it is not a declared dependency, add it to the top-level `externals` array.
* Check that it is not matched by an `exclude` pattern in `rollup.resolveExternals`, which would force it to be bundled.

### A package is external when it should be bundled [#a-package-is-external-when-it-should-be-bundled]

* Add the specifier (or a matching `RegExp`) to `rollup.resolveExternals.exclude`. `exclude` overrides all other classification rules.
* Alternatively, disable the relevant group (`deps`, `peerDeps`, `optDeps`, `builtins`) if you want to change classification wholesale.

### Node.js built-ins appear with an unexpected `node:` prefix [#nodejs-built-ins-appear-with-an-unexpected-node-prefix]

* Adjust `builtinsPrefix` to `"add"`, `"strip"`, or `"ignore"` depending on the prefix style you want in the output.

***

## Related Options [#related-options]

* [Output Format](/docs/packages/packem/options/output-format) - Configure output formats
* [Package Exports](/docs/packages/packem/options/package-exports) - Package.json exports


# failOnWarn (/docs/packages/packem/options/fail-on-warn)



# failOnWarn [#failonwarn]

If true, the build will fail on any warning. Useful for enforcing strict build hygiene in CI.

**Type:** `boolean`\
&#x2A;*Default:** `true`

## Example [#example]

```typescript
export default defineConfig({
  failOnWarn: false // Allow warnings without failing
})
```


# fileCache (/docs/packages/packem/options/file-cache)



# fileCache [#filecache]

Enables or disables the file cache for faster rebuilds. Disabling may help with debugging or in CI environments.

**Type:** `boolean`\
&#x2A;*Default:** `true`

## Example [#example]

```typescript
export default defineConfig({
  fileCache: false
})
```


# Hooks (/docs/packages/packem/options/hooks)





# Hooks [#hooks]

Hooks allow you to tap into Packem's build lifecycle and execute custom logic at specific points during the build process. This enables advanced customization and integration with external tools.

Hooks are registered through the `hooks` option and are powered by [hookable](https://github.com/unjs/hookable). Every hook receives the active `BuildContext` as its first argument; some hooks receive an additional argument (for example the Rollup build, the resolved Rollup options, or the watcher).

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  hooks: {
    'build:before': async (context) => {
      context.logger.info('Build starting...')
    },
    'build:done': async (context) => {
      context.logger.info('Build completed!')
    },
  },
})
```

## Hook Merging [#hook-merging]

When using presets, hooks from both the preset and your configuration are automatically merged. This means:

* **Hooks from presets are preserved** - Preset hooks (like the Solid preset's `rollup:options` hook) are automatically included
* **User config hooks take precedence** - If both preset and user config define the same hook, your hook will be used
* **Multiple hooks can coexist** - Different hooks from preset and user config are all registered

```typescript
// Preset defines: hooks: { 'rollup:options': presetHook }
// Your config defines: hooks: { 'build:before': myHook }

// Result: Both hooks are registered
// - 'rollup:options' uses presetHook
// - 'build:before' uses myHook
```

<Callout type="tip">
  Hooks are merged automatically when using presets. You don't need to manually combine them.
</Callout>

## Available Hooks [#available-hooks]

Packem exposes the following hooks (defined by the `BuildHooks` type). Each callback may be synchronous or return a `Promise`.

| Hook                 | Arguments            | When it runs                                              |
| -------------------- | -------------------- | --------------------------------------------------------- |
| `build:prepare`      | `(context)`          | Before the build context is fully set up.                 |
| `build:before`       | `(context)`          | Right before the build starts.                            |
| `build:done`         | `(context)`          | After the build finishes.                                 |
| `builder:before`     | `(name, context)`    | Before an individual builder runs.                        |
| `builder:done`       | `(name, context)`    | After an individual builder finishes.                     |
| `rollup:options`     | `(context, options)` | After the Rollup options are assembled, before bundling.  |
| `rollup:build`       | `(context, build)`   | After Rollup produces the build.                          |
| `rollup:done`        | `(context)`          | After the Rollup build completes.                         |
| `rollup:watch`       | `(context, watcher)` | After the Rollup watcher is created.                      |
| `rollup:dts:options` | `(context, options)` | After the declaration-build Rollup options are assembled. |
| `rollup:dts:build`   | `(context, build)`   | After the declaration build is produced.                  |
| `rollup:dts:done`    | `(context)`          | After the declaration build completes.                    |
| `validate:before`    | `(context)`          | Before validation runs.                                   |
| `validate:done`      | `(context)`          | After validation runs.                                    |

<Callout type="warning">
  `typedoc:before` and `typedoc:done` still exist but are deprecated. Use `builder:before` and `builder:done` instead.
</Callout>

### Build Lifecycle [#build-lifecycle]

```typescript
export default defineConfig({
  hooks: {
    'build:prepare': async (context) => {
      context.logger.info('Preparing build context...')
    },

    'build:before': async (context) => {
      context.logger.info('Build starting...')
    },

    'build:done': async (context) => {
      context.logger.info('Build completed!')
    },
  },
})
```

### Rollup Hooks [#rollup-hooks]

```typescript
export default defineConfig({
  hooks: {
    'rollup:options': async (context, options) => {
      // Inspect or mutate the resolved Rollup options
      context.logger.debug('Rollup input:', options.input)
    },

    'rollup:build': async (context, build) => {
      context.logger.info('Rollup build produced')
    },

    'rollup:done': async (context) => {
      context.logger.info('Rollup finished')
    },
  },
})
```

### Declaration (DTS) Hooks [#declaration-dts-hooks]

```typescript
export default defineConfig({
  hooks: {
    'rollup:dts:options': async (context, options) => {
      // Adjust the declaration-build Rollup options
    },

    'rollup:dts:build': async (context, build) => {
      context.logger.info('Declaration build produced')
    },

    'rollup:dts:done': async (context) => {
      context.logger.info('Declaration build finished')
    },
  },
})
```

### Validation Hooks [#validation-hooks]

```typescript
export default defineConfig({
  hooks: {
    'validate:before': async (context) => {
      context.logger.info('Running validation...')
    },

    'validate:done': async (context) => {
      context.logger.info('Validation finished')
    },
  },
})
```

## Common Use Cases [#common-use-cases]

### Code Generation [#code-generation]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      // Generate types from schema
      const { generateTypes } = await import('./scripts/generate-types')
      await generateTypes()
    },
  },
})
```

### Asset Processing [#asset-processing]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      // Optimize images
      const { optimizeImages } = await import('./scripts/optimize-images')
      await optimizeImages('dist/assets')
    },
  },
})
```

### Version Management [#version-management]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      // Update version in files
      const { writeFile } = await import('node:fs/promises')
      const version = process.env.npm_package_version

      await writeFile(
        'src/version.ts',
        `export const VERSION = '${version}'`
      )
    },
  },
})
```

### Bundle Analysis [#bundle-analysis]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      // Inspect the entries Packem produced
      for (const entry of context.buildEntries) {
        context.logger.info(`${entry.path}: ${entry.size?.bytes ?? 0} bytes`)
      }
    },
  },
})
```

## Advanced Patterns [#advanced-patterns]

### Conditional Hooks [#conditional-hooks]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      if (process.env.NODE_ENV === 'production') {
        // Production-only tasks
        await deployToS3()
      }

      if (process.env.ANALYZE_BUNDLE) {
        // Optional bundle analysis
        await generateBundleReport()
      }
    },
  },
})
```

### Async Hook Chains [#async-hook-chains]

A hook value may be a single function or an array of functions. All registered functions run in order.

```typescript
export default defineConfig({
  hooks: {
    'build:before': [
      async () => {
        console.log('Step 1: Clean dist')
        await cleanDist()
      },

      async () => {
        console.log('Step 2: Generate types')
        await generateTypes()
      },

      async () => {
        console.log('Step 3: Copy assets')
        await copyAssets()
      },
    ],
  },
})
```

### Error Handling [#error-handling]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      try {
        await riskyOperation()
      } catch (error) {
        console.warn('Optional operation failed:', error.message)
        // Continue build despite error
      }
    },
  },
})
```

## Validation Integration [#validation-integration]

### Reacting to Validation [#reacting-to-validation]

Use the `validate:before` and `validate:done` hooks to run custom checks around Packem's built-in validation (such as `attw`, `bundleLimit`, `dependencies` and `packageJson`).

```typescript
export default defineConfig({
  validation: {
    bundleLimit: {
      limit: '50KB',
    },
  },
  hooks: {
    'validate:before': async (context) => {
      context.logger.info('Starting validation pass')
    },

    'validate:done': async (context) => {
      context.logger.info('Validation pass complete')
    },
  },
})
```

## Testing Integration [#testing-integration]

### Test Hooks [#test-hooks]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      if (process.env.RUN_TESTS) {
        const { exec } = await import('node:child_process')
        const { promisify } = await import('node:util')
        const execAsync = promisify(exec)

        try {
          await execAsync('npm test')
          console.log('Tests passed!')
        } catch (error) {
          console.error('Tests failed:', error.message)
          process.exit(1)
        }
      }
    },
  },
})
```

### Coverage Reports [#coverage-reports]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      if (process.env.GENERATE_COVERAGE) {
        await generateCoverageReport()
        await uploadCoverageToService()
      }
    },
  },
})
```

## Deployment Hooks [#deployment-hooks]

### Automatic Deployment [#automatic-deployment]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      if (process.env.AUTO_DEPLOY === 'true') {
        console.log('Deploying to production...')

        // Upload to CDN
        await uploadToCDN('dist')

        // Update service
        await updateService()

        // Send notification
        await sendDeploymentNotification()
      }
    },
  },
})
```

### Environment-Specific Deployments [#environment-specific-deployments]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      const env = process.env.DEPLOY_ENV

      switch (env) {
        case 'staging':
          await deployToStaging()
          break
        case 'production':
          await deployToProduction()
          break
        default:
          console.log('No deployment configured')
      }
    },
  },
})
```

## Performance Monitoring [#performance-monitoring]

### Build Metrics [#build-metrics]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      // Record build start time
      global.buildStartTime = Date.now()
    },

    'build:done': async () => {
      // Calculate build duration
      const duration = Date.now() - global.buildStartTime
      console.log(`Build completed in ${duration}ms`)

      // Send metrics to monitoring service
      await sendMetrics({
        buildDuration: duration,
        timestamp: Date.now(),
      })
    },
  },
})
```

### Bundle Size Tracking [#bundle-size-tracking]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      const bundleSizes = Object.fromEntries(
        context.buildEntries.map((entry) => [entry.path, entry.size?.bytes ?? 0])
      )

      // Track bundle size changes
      await trackBundleSizes(bundleSizes)

      // Alert if bundle size increased significantly
      await checkBundleSizeThresholds(bundleSizes)
    },
  },
})
```

## Debugging Hooks [#debugging-hooks]

### Hook Logging [#hook-logging]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async (context) => {
      context.logger.info('Starting build process')
    },

    'rollup:done': async (context) => {
      context.logger.info('Rollup bundling finished')
    },

    'build:done': async (context) => {
      context.logger.info('Build completed successfully')
    },
  },
})
```

### Hook Performance [#hook-performance]

```typescript
function withTiming(hookName: string, fn: Function) {
  return async (...args: any[]) => {
    const start = Date.now()
    await fn(...args)
    const duration = Date.now() - start
    console.log(`Hook ${hookName} took ${duration}ms`)
  }
}

export default defineConfig({
  hooks: {
    'build:before': withTiming('build:before', async () => {
      await heavyOperation()
    }),
  },
})
```

## Troubleshooting [#troubleshooting]

### Hook Errors [#hook-errors]

<Callout type="warning">
  Hook errors can interrupt the build process. Use proper error handling.
</Callout>

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      try {
        await riskyOperation()
      } catch (error) {
        console.error('Hook error:', error)
        // Decide whether to continue or fail
        if (error.critical) {
          throw error // Fail the build
        }
        // Otherwise continue
      }
    },
  },
})
```

### Async Hook Issues [#async-hook-issues]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      // Ensure all async operations complete
      await Promise.all([
        operation1(),
        operation2(),
        operation3(),
      ])
    },
  },
})
```

### Hook Order Dependencies [#hook-order-dependencies]

```typescript
export default defineConfig({
  hooks: {
    'build:before': [
      // Order matters - dependencies first
      async () => await setupDependencies(),
      async () => await configureEnvironment(),
      async () => await startServices(),
    ],
  },
})
```

***

## Related Options [#related-options]

* [Plugins](/docs/packages/packem/options/plugins) - Rollup plugins
* [Watch](/docs/packages/packem/options/watch) - File watching
* [Build](/docs/packages/packem/guide/cli) - Build configuration
* [Scripts](/docs/packages/packem/options/on-success) - Custom scripts


# ignoreExportKeys (/docs/packages/packem/options/ignore-export-keys)



# ignoreExportKeys [#ignoreexportkeys]

Array of export keys to ignore during entry inference. Useful for excluding exports that only contain images or other non-JavaScript assets.

## Type [#type]

```typescript
ignoreExportKeys?: string[]
```

## Default [#default]

`undefined` (no exports are ignored)

## Description [#description]

When packem processes your `package.json` exports, it tries to find corresponding source files for each export. However, some exports may only contain non-JavaScript assets (like images, CSS files, etc.) that don't have corresponding source files to build.

By default, packem will generate warnings for exports where it can't find source files. Use `ignoreExportKeys` to tell packem to skip these exports entirely.

## Examples [#examples]

### Basic Usage [#basic-usage]

```typescript
// packem.config.ts
import type { BuildConfig } from "@visulima/packem";

const config: BuildConfig = {
  ignoreExportKeys: ["images", "assets", "styles"],
};

export default config;
```

### With package.json exports [#with-packagejson-exports]

```json
{
  "exports": {
    ".": "./dist/index.mjs",
    "./images": "./dist/images/icon.png",
    "./assets": "./dist/assets/logo.svg",
    "./styles": "./dist/styles.css"
  }
}
```

With `ignoreExportKeys: ["images", "assets", "styles"]`, only the main export (`"."`) will be processed as a build entry.

### With wildcard patterns [#with-wildcard-patterns]

```json
{
  "exports": {
    ".": "./dist/index.mjs",
    "./icons/*": "./dist/icons/*",
    "./assets/*": "./dist/assets/*"
  }
}
```

With `ignoreExportKeys: ["icons", "assets"]`, both `"./icons/*"` and `"./assets/*"` wildcard patterns will be ignored, and only the main export (`"."`) will be processed as a build entry.

### CLI Usage [#cli-usage]

```bash
packem build --ignore-export-keys=images,assets,styles
```

## Notes [#notes]

* Export keys are matched without the `./` prefix (e.g., `"./images"` matches `"images"`)
* **Wildcard patterns are supported**: Export keys starting with the ignored key are also ignored (e.g., `"images"` will ignore both `"./images"` and `"./images/*"`)
* Ignored exports are still included in the final `package.json` for consumers
* No warnings are generated for ignored exports
* Works with both simple string exports and nested conditional exports

## Related Options [#related-options]

When using `ignoreExportKeys` with asset exports, you may also want to configure:

* `validation.packageJson.allowedExportExtensions` - Add custom file extensions to the valid export extensions list
* `rollup.copy` - Copy asset files to the output directory


# Configuration Options (/docs/packages/packem/options)



# Configuration Options [#configuration-options]

All options are set in `packem.config.ts` using `defineConfig`. This page lists every available option grouped by category. Click through to the individual pages for examples and details.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  // ...options below
})
```

## Input and output [#input-and-output]

| Option                                                                     | Description                                              |
| -------------------------------------------------------------------------- | -------------------------------------------------------- |
| [entry](/docs/packages/packem/options/entry)                               | Configure entry points and automatic detection           |
| [config-file](/docs/packages/packem/options/config-file)                   | Config file setup, formats, and environment variables    |
| [output-directory](/docs/packages/packem/options/output-directory)         | Control where built files are written                    |
| [output-format](/docs/packages/packem/options/output-format)               | ESM, CJS, IIFE output formats                            |
| [output-extension-map](/docs/packages/packem/options/output-extension-map) | Custom file extensions for output files                  |
| [source-dir](/docs/packages/packem/options/source-dir)                     | Source directory for entry point resolution              |
| [root-dir](/docs/packages/packem/options/root-dir)                         | Project root directory                                   |
| [name](/docs/packages/packem/options/name)                                 | Package name override                                    |
| [package-exports](/docs/packages/packem/options/package-exports)           | How `package.json#exports` drives entries and validation |

## Build behavior [#build-behavior]

| Option                                                               | Description                                                |
| -------------------------------------------------------------------- | ---------------------------------------------------------- |
| [bundler](/docs/packages/packem/options/bundler)                     | Bundler backend: Rollup (default) or experimental Rolldown |
| [transformers](/docs/packages/packem/options/transformers)           | Choose the code transformer (esbuild, swc, OXC, sucrase)   |
| [target](/docs/packages/packem/options/target)                       | JavaScript compilation target (ES2020, ESNext, etc.)       |
| [platform](/docs/packages/packem/options/platform)                   | Target runtime/environment (node, browser, edge)           |
| [declaration-files](/docs/packages/packem/options/declaration-files) | TypeScript `.d.ts` generation and isolated declarations    |
| [minify](/docs/packages/packem/options/minify)                       | Toggle minification (handled by the active transformer)    |
| [tree-shaking](/docs/packages/packem/options/tree-shaking)           | Dead-code elimination via `rollup.treeshake`               |
| [source-maps](/docs/packages/packem/options/source-maps)             | Source map generation                                      |
| [externals](/docs/packages/packem/options/externals)                 | External dependency handling                               |
| [alias](/docs/packages/packem/options/alias)                         | Module path aliases                                        |
| [shims](/docs/packages/packem/options/shims)                         | ESM/CJS interop shims (`cjsInterop`, `rollup.shim`)        |
| [unbundle](/docs/packages/packem/options/unbundle)                   | Preserve source file structure instead of bundling         |
| [cleaning](/docs/packages/packem/options/cleaning)                   | Clean the output directory before building                 |
| [barrel](/docs/packages/packem/options/barrel)                       | Barrel file optimization                                   |

## Plugins and hooks [#plugins-and-hooks]

| Option                                           | Description               |
| ------------------------------------------------ | ------------------------- |
| [plugins](/docs/packages/packem/options/plugins) | Rollup plugin integration |
| [hooks](/docs/packages/packem/options/hooks)     | Build lifecycle hooks     |
| [builder](/docs/packages/packem/options/builder) | Builder configuration     |

## Development [#development]

| Option                                                     | Description                       |
| ---------------------------------------------------------- | --------------------------------- |
| [watch](/docs/packages/packem/options/watch)               | Watch mode and file watching      |
| [debug](/docs/packages/packem/options/debug)               | Debug output and diagnostics      |
| [silent-mode](/docs/packages/packem/options/silent-mode)   | Logging verbosity controls        |
| [analyze](/docs/packages/packem/options/analyze)           | Bundle analysis and visualization |
| [on-success](/docs/packages/packem/options/on-success)     | Post-build commands               |
| [fail-on-warn](/docs/packages/packem/options/fail-on-warn) | Treat warnings as errors          |

## Advanced [#advanced]

| Option                                                                               | Description                               |
| ------------------------------------------------------------------------------------ | ----------------------------------------- |
| [file-cache](/docs/packages/packem/options/file-cache)                               | Persistent file cache for faster rebuilds |
| [jiti](/docs/packages/packem/options/jiti)                                           | Runtime TypeScript config loading         |
| [kill-signal](/docs/packages/packem/options/kill-signal)                             | Process termination signal                |
| [typedoc](/docs/packages/packem/options/typedoc)                                     | TypeDoc documentation generation          |
| [ignore-export-keys](/docs/packages/packem/options/ignore-export-keys)               | Exclude specific export keys              |
| [allowed-export-extensions](/docs/packages/packem/options/allowed-export-extensions) | Custom file extensions in exports         |


# jiti (/docs/packages/packem/options/jiti)



# jiti [#jiti]

Advanced: Options for the [jiti](https://github.com/unjs/jiti) runtime used to load entry files. Rarely needed unless customizing module loading.

**Type:** `Omit<JitiOptions, "onError" | "transform">`\
&#x2A;*Default:** `{ alias: {}, debug: false, interopDefault: true }`

## Example [#example]

```typescript
export default defineConfig({
  jiti: {
    debug: true
  }
})
```


# killSignal (/docs/packages/packem/options/kill-signal)



# killSignal [#killsignal]

Specifies the signal used to terminate child processes during the build.

**Type:** `"SIGKILL" | "SIGTERM"`\
&#x2A;*Default:** `undefined`

## Example [#example]

```typescript
export default defineConfig({
  killSignal: 'SIGTERM'
})
```


# Minify (/docs/packages/packem/options/minify)





# Minify [#minify]

`minify` is a simple boolean toggle that turns minification on or off. When enabled, the **active transformer** (esbuild, swc, or oxc — whichever you configured via the [`transformer`](/docs/packages/packem/guide/transformers) option) minifies the emitted output. Packem does not ship a separate minifier or a minifier-selection mechanism: the minifier *is* the transformer.

```typescript
minify?: boolean
```

There is no string form (`'esbuild'`, `'swc'`, …), no object form, and no function form. `minify` is either `true` or `false`.

## Default behavior [#default-behavior]

`minify` defaults to `true` when `NODE_ENV === 'production'`, and `false` otherwise. You usually don't need to set it at all — building in production mode enables minification automatically.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  // minify is implicitly true when NODE_ENV === 'production'
})
```

## Enabling minification explicitly [#enabling-minification-explicitly]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: true,
})
```

### Conditional minification [#conditional-minification]

Drive the toggle from the environment when you want a single config to behave differently across builds:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: process.env.NODE_ENV === 'production',
})
```

## The minifier is your transformer [#the-minifier-is-your-transformer]

Because minification is performed by the active transformer, switching the transformer also switches which engine minifies your output. To minify with esbuild:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: true,
})
```

To minify with swc instead, just import a different transformer:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  minify: true,
})
```

The `minify: true` flag is unchanged — only the imported `transformer` decides which engine does the work.

## Preserving function & class names (`keepNames`) [#preserving-function--class-names-keepnames]

When using the esbuild transformer, esbuild can preserve original `function`/`class` names through minification (so `fn.name` and stack traces stay readable). Packem leaves this **off by default** — matching esbuild's own default — and lets you opt in via the transformer's rollup config. `keepNames` nests under `rollup.esbuild`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  minify: true,
  rollup: {
    esbuild: {
      keepNames: true, // opt in when you rely on runtime name reflection
    },
  },
})
```

<Callout type="warning">
  `keepNames` wraps every name-inferred function/closure in `__name(fn, "name")` (an `Object.defineProperty` call). For a **named closure created inside a hot function** (recursion, per-element, per-call), that `defineProperty` runs on *every* invocation — which can make a closure-heavy **published** (minified) build several times slower than its dev build, where minification (and thus `keepNames`) is off. Only enable it for packages that genuinely need runtime `fn.name`/`Class.name`; stack-trace preservation after minification is usually the consuming app bundler's concern. See [issue #207](https://github.com/visulima/packem/issues/207).
</Callout>

## HTML / CSS template-literal minification [#html--css-template-literal-minification]

Minification of HTML and CSS embedded in tagged template literals is a separate, opt-in feature configured under `rollup.minifyHTMLLiterals` — not via `minify`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    minifyHTMLLiterals: {},
  },
})
```

See the [Minify HTML literals example](/docs/packages/packem/examples/advanced/minify-html-literals) for details.

## CSS minification [#css-minification]

CSS minification is **not** controlled by `minify`. It is configured through the `css` option's `minifier`. See the [CSS guide](/docs/packages/packem/guide/css) for the full configuration.

***

## Related Options [#related-options]

* [Target](/docs/packages/packem/options/target) - Compilation targets
* [Source Maps](/docs/packages/packem/options/source-maps) - Debug information
* [Tree Shaking](/docs/packages/packem/options/tree-shaking) - Dead code elimination
* [Analyze](/docs/packages/packem/options/analyze) - Bundle size analysis
* [CSS](/docs/packages/packem/guide/css) - CSS handling and minification
* [Optimization](/docs/packages/packem/guide/optimization) - Build optimization guide


# name (/docs/packages/packem/options/name)



# name [#name]

The name of the build, used for output file naming and logging.

**Type:** `string`\
&#x2A;*Default:** Derived from `package.json` name or `'default'`

## Example [#example]

```typescript
export default defineConfig({
  name: 'my-library'
})
```


# onSuccess / onSuccessTimeout (/docs/packages/packem/options/on-success)



# onSuccess / onSuccessTimeout [#onsuccess--onsuccesstimeout]

Runs a command or function after a successful build. `onSuccessTimeout` sets a timeout for this action.

**Type:**

* `onSuccess`: `string | (() => Promise<void>)`
* `onSuccessTimeout`: `number` (ms)\
  &#x2A;*Default:** `undefined`

## Example [#example]

```typescript
export default defineConfig({
  onSuccess: 'echo Build complete!',
  onSuccessTimeout: 5000
})
```


# Output Directory (/docs/packages/packem/options/output-directory)





# Output Directory [#output-directory]

The output directory determines where Packem writes your built files, assets, and generated code. Proper configuration ensures your build artifacts are organized and accessible.

## Basic Configuration [#basic-configuration]

### Default Directory [#default-directory]

By default, Packem outputs to the `dist` directory:

```typescript
export default defineConfig({
  // Uses 'dist' by default
})
```

### Custom Directory [#custom-directory]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'build' // Custom output directory
    }
  }
})
```

### Multiple Directories [#multiple-directories]

```typescript
export default defineConfig({
  rollup: {
    output: [
      { format: 'esm', dir: 'dist/esm' },
      { format: 'cjs', dir: 'dist/cjs' },
      { format: 'iife', dir: 'dist/browser' }
    ]
  }
})
```

## Directory Structure [#directory-structure]

### Flat Structure [#flat-structure]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      // All files in root
      entryFileNames: '[name].js',
      chunkFileNames: '[name].js',
      assetFileNames: '[name].[ext]'
    }
  }
})
```

### Organized Structure [#organized-structure]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      // Organized by type
      entryFileNames: 'js/[name].js',
      chunkFileNames: 'chunks/[name]-[hash].js',
      assetFileNames: 'assets/[name]-[hash].[ext]'
    }
  }
})
```

### Format-Based Structure [#format-based-structure]

```typescript
export default defineConfig({
  rollup: {
    output: [
      {
        format: 'esm',
        dir: 'dist/esm',
        entryFileNames: '[name].mjs'
      },
      {
        format: 'cjs',
        dir: 'dist/cjs',
        entryFileNames: '[name].cjs'
      }
    ]
  }
})
```

## File Naming Patterns [#file-naming-patterns]

### Entry Files [#entry-files]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      entryFileNames: (chunkInfo) => {
        // Custom naming logic
        if (chunkInfo.name === 'index') {
          return 'main.js'
        }
        return '[name]-[hash].js'
      }
    }
  }
})
```

### Chunk Files [#chunk-files]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      chunkFileNames: 'chunks/[name]-[hash].js'
    }
  }
})
```

### Asset Files [#asset-files]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      assetFileNames: (assetInfo) => {
        const extType = assetInfo.name.split('.').pop()
        
        if (/png|jpe?g|svg|gif|tiff|bmp|ico/i.test(extType)) {
          return 'images/[name]-[hash].[ext]'
        }
        
        if (/css|scss|sass|less|styl/i.test(extType)) {
          return 'styles/[name]-[hash].[ext]'
        }
        
        return 'assets/[name]-[hash].[ext]'
      }
    }
  }
})
```

## Package.json Integration [#packagejson-integration]

### Automatic Directory Detection [#automatic-directory-detection]

```json
{
  "main": "./lib/index.js",
  "module": "./esm/index.js",
  "exports": {
    ".": {
      "import": "./esm/index.js",
      "require": "./lib/index.js"
    }
  }
}
```

```typescript
export default defineConfig({
  // Automatically uses 'lib' and 'esm' directories
  rollup: {
    output: [
      { format: 'cjs', dir: 'lib' },
      { format: 'esm', dir: 'esm' }
    ]
  }
})
```

### Custom Export Paths [#custom-export-paths]

```json
{
  "exports": {
    ".": {
      "import": "./dist/modern/index.mjs",
      "require": "./dist/legacy/index.cjs"
    }
  }
}
```

```typescript
export default defineConfig({
  rollup: {
    output: [
      { format: 'esm', dir: 'dist/modern' },
      { format: 'cjs', dir: 'dist/legacy' }
    ]
  }
})
```

## Directory Cleaning [#directory-cleaning]

### Automatic Cleaning [#automatic-cleaning]

```typescript
export default defineConfig({
  clean: true, // Clean output directory before build
  
  rollup: {
    output: {
      dir: 'dist'
    }
  }
})
```

### Selective Cleaning [#selective-cleaning]

```typescript
export default defineConfig({
  clean: ['dist/**/*.js', 'dist/**/*.css'], // Clean specific patterns
  
  rollup: {
    output: {
      dir: 'dist'
    }
  }
})
```

### Custom Cleaning [#custom-cleaning]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      const { rimraf } = await import('rimraf')
      await rimraf('dist')
    }
  },
  
  rollup: {
    output: {
      dir: 'dist'
    }
  }
})
```

## Asset Handling [#asset-handling]

### Static Assets [#static-assets]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      assetFileNames: 'assets/[name]-[hash].[ext]'
    },
    
    plugins: [
      // Copy static assets
      copy({
        targets: [
          { src: 'public/*', dest: 'dist' }
        ]
      })
    ]
  }
})
```

### CSS Assets [#css-assets]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      assetFileNames: (assetInfo) => {
        if (assetInfo.name?.endsWith('.css')) {
          return 'styles/[name]-[hash].[ext]'
        }
        return 'assets/[name]-[hash].[ext]'
      }
    }
  }
})
```

### Image Assets [#image-assets]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      assetFileNames: (assetInfo) => {
        const imageExts = ['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp']
        const ext = assetInfo.name?.split('.').pop()?.toLowerCase()
        
        if (imageExts.includes(ext)) {
          return 'images/[name]-[hash].[ext]'
        }
        
        return 'assets/[name]-[hash].[ext]'
      }
    }
  }
})
```

## Monorepo Configuration [#monorepo-configuration]

### Package-Specific Directories [#package-specific-directories]

```typescript
// packages/ui/packem.config.ts
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      entryFileNames: '[name].js'
    }
  }
})

// packages/utils/packem.config.ts
export default defineConfig({
  rollup: {
    output: {
      dir: 'lib', // Different directory per package
      entryFileNames: '[name].js'
    }
  }
})
```

### Shared Output Directory [#shared-output-directory]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: '../../dist/packages/my-package',
      entryFileNames: '[name].js'
    }
  }
})
```

## Development vs Production [#development-vs-production]

### Environment-Specific Directories [#environment-specific-directories]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: process.env.NODE_ENV === 'production' ? 'dist' : 'dev',
      entryFileNames: '[name].js'
    }
  }
})
```

## Advanced Patterns [#advanced-patterns]

### Dynamic Directory Names [#dynamic-directory-names]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: `dist/${process.env.BUILD_TARGET || 'default'}`,
      entryFileNames: '[name].js'
    }
  }
})
```

### Conditional Outputs [#conditional-outputs]

```typescript
export default defineConfig({
  rollup: {
    output: process.env.DUAL_PACKAGE ? [
      { format: 'esm', dir: 'dist/esm' },
      { format: 'cjs', dir: 'dist/cjs' }
    ] : {
      format: 'esm',
      dir: 'dist'
    }
  }
})
```

### Platform-Specific Directories [#platform-specific-directories]

```typescript
export default defineConfig({
  rollup: {
    output: [
      {
        format: 'esm',
        dir: 'dist/node',
        platform: 'node'
      },
      {
        format: 'esm',
        dir: 'dist/browser',
        platform: 'browser'
      }
    ]
  }
})
```

## Directory Permissions [#directory-permissions]

### Setting Permissions [#setting-permissions]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      const { chmod } = await import('fs/promises')
      await chmod('dist', 0o755)
    }
  },
  
  rollup: {
    output: {
      dir: 'dist'
    }
  }
})
```

### Ownership [#ownership]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      const { chown } = await import('fs/promises')
      const { getuid, getgid } = await import('process')
      await chown('dist', getuid(), getgid())
    }
  }
})
```

## Troubleshooting [#troubleshooting]

### Directory Not Found [#directory-not-found]

<Callout type="warning">
  Ensure the output directory exists or can be created.
</Callout>

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      const { mkdir } = await import('fs/promises')
      await mkdir('dist', { recursive: true })
    }
  }
})
```

### Permission Errors [#permission-errors]

```typescript
export default defineConfig({
  hooks: {
    'build:before': async () => {
      const { access, constants } = await import('fs/promises')
      
      try {
        await access('dist', constants.W_OK)
      } catch {
        throw new Error('Output directory is not writable')
      }
    }
  }
})
```

### Path Conflicts [#path-conflicts]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      // Avoid conflicts with reserved names
      entryFileNames: (chunkInfo) => {
        const reserved = ['index', 'main', 'lib']
        if (reserved.includes(chunkInfo.name)) {
          return `${chunkInfo.name}-bundle.js`
        }
        return '[name].js'
      }
    }
  }
})
```

## Performance Considerations [#performance-considerations]

### SSD Optimization [#ssd-optimization]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      // Optimize for SSD performance
      compact: true,
      generatedCode: {
        preset: 'es2015'
      }
    }
  }
})
```

### Network Drives [#network-drives]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: process.env.CI ? '/tmp/dist' : 'dist', // Use local storage in CI
      entryFileNames: '[name].js'
    }
  }
})
```

### Large Files [#large-files]

```typescript
export default defineConfig({
  rollup: {
    output: {
      dir: 'dist',
      // Split large chunks
      maxParallelFileOps: 5,
      chunkFileNames: 'chunks/[name]-[hash].js'
    }
  }
})
```

***

## Related Options [#related-options]

* [Output Format](/docs/packages/packem/options/output-format) - Configure output formats
* [Entry](/docs/packages/packem/options/entry) - Configure entry points
* [Assets](/docs/packages/packem/guide/introduction) - Handle static assets
* [Clean](/docs/packages/packem/options/cleaning) - Clean output directories


# outputExtensionMap (/docs/packages/packem/options/output-extension-map)



# outputExtensionMap [#outputextensionmap]

Customizes the file extensions for different output formats (e.g., ESM, CJS). Useful for non-standard file naming.

**Type:** `Record<Format, string>`\
&#x2A;*Default:** `undefined`

## Example [#example]

```typescript
export default defineConfig({
  outputExtensionMap: {
    esm: 'mjs',
    cjs: 'cjs'
  }
})
```


# Output Format (/docs/packages/packem/options/output-format)





# Output Format [#output-format]

Packem supports multiple output formats to ensure your library works across different JavaScript environments. The output format determines how your bundled code is structured and how it can be consumed by other applications.

## Supported Formats [#supported-formats]

### ESM (ES Modules) [#esm-es-modules]

Modern standard for JavaScript modules with `import`/`export` syntax.

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      file: 'dist/index.mjs'
    }
  }
})
```

### CJS (CommonJS) [#cjs-commonjs]

Traditional Node.js module format with `require`/`module.exports`.

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'cjs',
      file: 'dist/index.cjs'
    }
  }
})
```

### IIFE (Immediately Invoked Function Expression) [#iife-immediately-invoked-function-expression]

Browser-compatible format that creates a global variable.

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'iife',
      file: 'dist/index.global.js',
      name: 'MyLibrary' // Global variable name
    }
  }
})
```

### UMD (Universal Module Definition) [#umd-universal-module-definition]

Works in both browser and Node.js environments.

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'umd',
      file: 'dist/index.umd.js',
      name: 'MyLibrary'
    }
  }
})
```

## Automatic Format Detection [#automatic-format-detection]

Packem automatically determines output formats based on your `package.json`:

### From Package Type [#from-package-type]

```json
{
  "type": "module",
  "main": "./dist/index.js"
}
```

→ Generates ESM format

```json
{
  "type": "commonjs",
  "main": "./dist/index.js"
}
```

→ Generates CJS format

### From Export Conditions [#from-export-conditions]

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}
```

→ Generates both ESM and CJS formats

## Multiple Output Formats [#multiple-output-formats]

Generate multiple formats in a single build:

```typescript
export default defineConfig({
  rollup: {
    output: [
      // ESM build
      {
        format: 'esm',
        file: 'dist/index.mjs'
      },
      // CJS build
      {
        format: 'cjs',
        file: 'dist/index.cjs'
      },
      // Browser build
      {
        format: 'iife',
        file: 'dist/index.global.js',
        name: 'MyLibrary'
      }
    ]
  }
})
```

## Format-Specific Configuration [#format-specific-configuration]

### ESM Configuration [#esm-configuration]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
      // ESM-specific options
      exports: 'named', // or 'default', 'auto'
      generatedCode: {
        preset: 'es2015'
      }
    }
  }
})
```

### CJS Configuration [#cjs-configuration]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'cjs',
      file: 'dist/index.cjs',
      // CJS-specific options
      exports: 'auto',
      esModule: false,
      interop: 'auto'
    }
  }
})
```

### IIFE Configuration [#iife-configuration]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'iife',
      file: 'dist/index.global.js',
      name: 'MyLibrary',
      // IIFE-specific options
      globals: {
        'react': 'React',
        'react-dom': 'ReactDOM'
      },
      extend: true // Extend existing global
    }
  }
})
```

## File Extensions [#file-extensions]

Packem uses appropriate file extensions based on format:

### Automatic Extensions [#automatic-extensions]

```typescript
export default defineConfig({
  rollup: {
    output: [
      { format: 'esm', dir: 'dist' }, // → .mjs
      { format: 'cjs', dir: 'dist' }, // → .cjs
      { format: 'iife', dir: 'dist' } // → .js
    ]
  }
})
```

### Custom Extensions [#custom-extensions]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      dir: 'dist',
      entryFileNames: '[name].esm.js' // Custom extension
    }
  }
})
```

## Package.json Integration [#packagejson-integration]

### Dual Package Setup [#dual-package-setup]

```json
{
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}
```

```typescript
export default defineConfig({
  rollup: {
    output: [
      { format: 'esm', file: 'dist/index.mjs' },
      { format: 'cjs', file: 'dist/index.cjs' }
    ]
  }
})
```

### Conditional Exports [#conditional-exports]

```json
{
  "exports": {
    ".": {
      "development": "./dist/index.development.js",
      "production": "./dist/index.production.js",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    }
  }
}
```

## Runtime-Specific Formats [#runtime-specific-formats]

### Node.js Optimized [#nodejs-optimized]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'cjs',
      file: 'dist/index.node.js',
      // Node.js optimizations
      preferConst: true,
      compact: true
    }
  }
})
```

### Browser Optimized [#browser-optimized]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'iife',
      file: 'dist/index.browser.js',
      name: 'MyLibrary',
      // Browser optimizations
      sourcemap: true,
      compact: true
    }
  }
})
```

### Edge Runtime [#edge-runtime]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      file: 'dist/index.edge.mjs',
      // Edge runtime optimizations
      generatedCode: {
        preset: 'es2022'
      }
    }
  }
})
```

## Advanced Configuration [#advanced-configuration]

### Code Splitting [#code-splitting]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      dir: 'dist',
      // Enable code splitting
      manualChunks: {
        vendor: ['react', 'react-dom'],
        utils: ['lodash', 'date-fns']
      }
    }
  }
})
```

### Dynamic Imports [#dynamic-imports]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      dir: 'dist',
      // Configure dynamic import format
      chunkFileNames: 'chunks/[name]-[hash].js',
      dynamicImportFunction: 'import'
    }
  }
})
```

### Tree Shaking [#tree-shaking]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
      // Preserve modules for better tree shaking
      preserveModules: true,
      preserveModulesRoot: 'src'
    }
  }
})
```

## Format Validation [#format-validation]

Packem validates that your `package.json` `exports` map matches the formats it
produces. This runs automatically; configure it through the `validation` option
rather than a manual hook:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  validation: {
    packageJson: {
      exports: true,
    },
  },
})
```

See the [validation docs](/docs/packages/packem/guide/package-json) for the full set of checks.

## Interoperability [#interoperability]

### ESM/CJS Interop [#esmcjs-interop]

```typescript
export default defineConfig({
  cjsInterop: true, // Enable automatic interop
  
  rollup: {
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs',
        exports: 'named'
      },
      {
        format: 'cjs',
        file: 'dist/index.cjs',
        exports: 'auto',
        interop: 'auto'
      }
    ]
  }
})
```

### Default Export Handling [#default-export-handling]

```typescript
// For libraries with default exports
export default defineConfig({
  rollup: {
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs',
        exports: 'default'
      },
      {
        format: 'cjs',
        file: 'dist/index.cjs',
        exports: 'default'
      }
    ]
  }
})
```

## Framework-Specific Formats [#framework-specific-formats]

### React Library [#react-library]

```typescript
export default defineConfig({
  rollup: {
    external: ['react', 'react-dom'],
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs',
        globals: {
          'react': 'React',
          'react-dom': 'ReactDOM'
        }
      },
      {
        format: 'cjs',
        file: 'dist/index.cjs'
      }
    ]
  }
})
```

### Vue Library [#vue-library]

```typescript
export default defineConfig({
  rollup: {
    external: ['vue'],
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs'
      },
      {
        format: 'umd',
        file: 'dist/index.umd.js',
        name: 'MyVueLibrary',
        globals: {
          'vue': 'Vue'
        }
      }
    ]
  }
})
```

## Troubleshooting [#troubleshooting]

### Format Mismatch [#format-mismatch]

<Callout type="warning">
  Ensure your package.json exports match your actual output formats.
</Callout>

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs", // Must be ESM
      "require": "./dist/index.cjs"  // Must be CJS
    }
  }
}
```

### Global Name Conflicts [#global-name-conflicts]

For IIFE/UMD builds, ensure unique global names:

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'iife',
      name: 'MyUniqueLibraryName', // Avoid conflicts
      extend: false // Don't extend existing globals
    }
  }
})
```

### External Dependencies [#external-dependencies]

`dependencies`, `peerDependencies`, and Node built-ins are externalized by
default. Use the top-level `externals` array to force-externalize extra
packages, and `rollup.resolveExternals` to change classification:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],
})
```

See the [externals option](/docs/packages/packem/options/externals) for the full classification
controls (`deps`, `peerDeps`, `exclude`, …).

## Performance Considerations [#performance-considerations]

### Format-Specific Optimizations [#format-specific-optimizations]

```typescript
export default defineConfig({
  rollup: {
    output: [
      // Development build
      {
        format: 'esm',
        file: 'dist/index.development.mjs',
        sourcemap: true,
        compact: false
      },
      // Production build
      {
        format: 'esm',
        file: 'dist/index.production.mjs',
        sourcemap: false,
        compact: true
      }
    ]
  }
})
```

### Bundle Size Optimization [#bundle-size-optimization]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
      // Optimize for size
      compact: true,
      generatedCode: {
        preset: 'es2015',
        arrowFunctions: true,
        constBindings: true,
        objectShorthand: true
      }
    }
  }
})
```

***

## Related Options [#related-options]

* [Output Directory](/docs/packages/packem/options/output-directory) - Configure where files are written
* [Entry](/docs/packages/packem/options/entry) - Configure entry points for different formats
* [Package Exports](/docs/packages/packem/options/package-exports) - Automatic package.json exports
* [Target](/docs/packages/packem/options/target) - JavaScript compilation targets


# Package Exports (/docs/packages/packem/options/package-exports)





# Package Exports [#package-exports]

Packem treats your `package.json#exports` map as the source of truth for what your package ships. It reads the `exports` field to **infer build entries**, and it **validates** the field against the Node.js specification after building.

<Callout type="info">
  Packem derives entries from the `exports` you declare — you describe the public surface of your package in `package.json`, and Packem figures out which source files map to each entry.
</Callout>

## Entry inference from `exports` [#entry-inference-from-exports]

During entry inference, Packem walks the `exports` map (via `extractExportFilenames`) and pairs each declared output path with a matching source file. Conditional keys such as `import`, `require`, and `types`, plus subpath patterns (e.g. `"./*"`), are all understood. A `package.json` like this:

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}
```

tells Packem to build two entries (`index` and `utils`) and to emit ESM, CJS, and declaration output for them.

## Validating `exports` [#validating-exports]

After the build, Packem validates the `exports` field according to the [Node.js packages specification](https://nodejs.org/api/packages.html#exports) (conditional exports, subpath exports, and the exports sugar form). You can toggle this through the validation options:

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  validation: {
    packageJson: {
      exports: true, // set to false to skip exports validation
    },
  },
})
```

## Related export options [#related-export-options]

Two adjacent options shape how entry inference and validation treat the `exports` map. Each has its own dedicated page:

* **`ignoreExportKeys`** — an array of export keys to skip during entry inference, useful for excluding keys that only point at images or other non-JavaScript assets, e.g. `["images", "assets", "icons"]`. See [Ignore Export Keys](/docs/packages/packem/options/ignore-export-keys).
* **`validation.packageJson.allowedExportExtensions`** — extra file extensions to treat as valid inside the `exports` field during validation. See [Allowed Export Extensions](/docs/packages/packem/options/allowed-export-extensions).

You can also widen the set of accepted conditional-export keys during validation with `validation.packageJson.extraConditions` (e.g. `["custom", "my-bundler"]`).

***

## Related Options [#related-options]

* [Ignore Export Keys](/docs/packages/packem/options/ignore-export-keys) - Exclude keys from entry inference
* [Allowed Export Extensions](/docs/packages/packem/options/allowed-export-extensions) - Extra extensions for exports validation
* [Declaration Files](/docs/packages/packem/options/declaration-files) - `.d.ts` output referenced by `types` conditions
* [Shims](/docs/packages/packem/options/shims) - ESM/CJS interop for the emitted entries


# Platform (/docs/packages/packem/options/platform)





# Platform [#platform]

Packem does **not** have a literal `platform` option. Instead, the runtime platform a build targets is controlled by three real options on `BuildOptions`:

* `runtime?: Runtime` — the runtime environment (Node, browser, edge, etc.)
* `environment?: Environment` — `"production"` or `"development"`
* `browserTargets?: string[]` — browserslist queries used when transpiling for browsers

<Callout type="warning">
  The option names on this page — `runtime`, `environment`, and `browserTargets` — are the real fields. There is no `platform` key.
</Callout>

## `runtime` [#runtime]

`runtime` selects the target runtime. The accepted values of the `Runtime` type are:

```typescript
type Runtime =
  | "browser"
  | "bun"
  | "deno"
  | "edge-light"
  | "electron"
  | "node"
  | "react-native"
  | "react-server"
  | "workerd"
  | undefined;
```

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  runtime: 'node',
})
```

### CLI flag [#cli-flag]

A `--runtime` flag exists on `packem build`, but it is **narrower** than the config option — it accepts only `node` or `browser`:

```bash
packem build --runtime node
packem build --runtime browser
```

Any other value is rejected. To target `edge-light`, `workerd`, `deno`, and the other runtimes, set `runtime` in your config file.

## `environment` [#environment]

`environment` selects the build environment. The `Environment` type is:

```typescript
type Environment = "production" | "development" | undefined;
```

The environment also influences other defaults — for example, [minification](/docs/packages/packem/options/minify) defaults to `true` in `production` and `false` otherwise. On the CLI, `--production` and `--development` (which conflict with each other) set the environment:

```bash
packem build --production
packem build --development
```

## `browserTargets` [#browsertargets]

`browserTargets` is an array of [browserslist](https://github.com/browserslist/browserslist) queries used to drive transpilation for browser builds. It defaults to the resolved result of `browserslist()` (i.e. your `.browserslistrc` or `package.json#browserslist`).

```typescript
export default defineConfig({
  runtime: 'browser',
  browserTargets: ['chrome 58', 'firefox 57'],
})
```

When the global runtime is `"node"`, `browserTargets` is cleared, but the resolved value is preserved internally (`resolvedBrowserTargets`) so that individual browser-runtime entries in an otherwise Node package keep their intended targets.

***

## Related Options [#related-options]

* [Target](/docs/packages/packem/options/target) - JavaScript language/feature targets
* [Transformers](/docs/packages/packem/options/transformers) - The engine that performs transpilation
* [Bundler](/docs/packages/packem/options/bundler) - Choose the bundler backend


# Plugins (/docs/packages/packem/options/plugins)





# Plugins [#plugins]

Packem leverages Rollup's powerful plugin ecosystem to extend functionality. You can use any Rollup plugin or create custom plugins to handle specific build requirements.

## Basic Plugin Usage [#basic-plugin-usage]

### Adding Plugins [#adding-plugins]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { nodeResolve } from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [
      nodeResolve(),
      commonjs()
    ]
  }
})
```

### Built-in Plugins [#built-in-plugins]

Packem wires up the resolution, CommonJS, JSON and TypeScript handling it needs internally — you do not register these yourself. To add your own plugins, pass them through `rollup.plugins`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { nodeResolve } from '@rollup/plugin-node-resolve'

export default defineConfig({
  transformer,
  rollup: {
    plugins: [nodeResolve()],
  },
})
```

## Common Plugins [#common-plugins]

### Node Resolution [#node-resolution]

```typescript
import { nodeResolve } from '@rollup/plugin-node-resolve'

export default defineConfig({
  rollup: {
    plugins: [
      nodeResolve({
        preferBuiltins: true,
        browser: false,
        exportConditions: ['node']
      })
    ]
  }
})
```

### CommonJS Support [#commonjs-support]

```typescript
import commonjs from '@rollup/plugin-commonjs'

export default defineConfig({
  rollup: {
    plugins: [
      commonjs({
        include: ['node_modules/**'],
        exclude: ['node_modules/some-esm-package/**']
      })
    ]
  }
})
```

### JSON Import [#json-import]

```typescript
import json from '@rollup/plugin-json'

export default defineConfig({
  rollup: {
    plugins: [
      json({
        compact: true,
        namedExports: true
      })
    ]
  }
})
```

### Replace Variables [#replace-variables]

```typescript
import replace from '@rollup/plugin-replace'

export default defineConfig({
  rollup: {
    plugins: [
      replace({
        'process.env.NODE_ENV': JSON.stringify('production'),
        '__VERSION__': JSON.stringify(process.env.npm_package_version),
        preventAssignment: true
      })
    ]
  }
})
```

## Framework Plugins [#framework-plugins]

### React [#react]

**Quick Setup (Recommended):**

Use the `add` command to automatically configure React:

```bash
npx packem add react
```

This will:

* Add `preset: 'react'` to your config
* Install React, React DOM, and Babel dependencies
* Automatically detect TypeScript and add `@types/react` and `@types/react-dom` if TypeScript is installed
* Prompt you to add TypeScript if not already installed

**Manual Configuration:**

Packem provides a built-in React preset that configures Babel for React JSX transformation:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'react', // Automatically configures Babel for React
  transformer,
})
```

**With React Compiler:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createReactPreset } from '@visulima/packem/config/preset/react'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createReactPreset({
    compiler: true // Enable React Compiler optimization
  }),
  transformer,
})
```

**Manual Babel Configuration:**

If you need more control, you can configure Babel manually:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['react', 'react-dom'],
  rollup: {
    babel: {
      presets: [
        ['@babel/preset-react', { runtime: 'automatic' }]
        // Note: TypeScript is handled by the transformer via parser plugins
        // Babel only needs to parse TypeScript syntax, not transform it
      ],
      plugins: [
        // Add custom Babel plugins here
      ]
    }
  }
})
```

**Note:** When using Babel with React, Babel runs **before** your main transformer (esbuild/SWC/etc.), transforming JSX into JavaScript. TypeScript is handled by the transformer via parser plugins, not by Babel. This ensures that Rollup plugins can properly parse the code.

**Parallel transforms:** Babel transforms can run across a pool of worker threads to speed up larger builds. This is enabled automatically — transforms run in-process for small builds and spin up workers once enough files match (so small builds and tests don't pay the worker startup cost). You can tune it via `rollup.babel`:

| Option              | Default | Description                                                                                                                                     |
| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `parallel`          | `true`  | `false` always transforms in-process; `true` auto-enables workers above the threshold; a number caps the worker count (default `min(cpus, 4)`). |
| `parallelThreshold` | `20`    | Number of matched files required before the worker pool is created.                                                                             |

Parallel mode requires fully serializable Babel options. If a non-serializable option is present (for example a plugin passed as a live function, or a `babel` option supplied as a function as in the Solid preset), Packem silently falls back to in-process transforms.

### SolidJS [#solidjs]

**Quick Setup (Recommended):**

Use the `add` command to automatically configure SolidJS:

```bash
npx packem add solid
```

This will:

* Add `preset: 'solid'` to your config
* Install SolidJS and Babel dependencies

**Manual Configuration:**

Packem provides a built-in Solid preset that configures Babel for SolidJS JSX transformation:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'solid', // Automatically configures Babel for SolidJS
  transformer,
})
```

**With SSR Support:**

```typescript
import { defineConfig } from '@visulima/packem/config'
import { createSolidPreset } from '@visulima/packem/config/preset/solid'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: createSolidPreset({
    solidOptions: {
      generate: 'ssr',
      hydratable: true
    }
  }),
  transformer,
})
```

**Manual Babel Configuration:**

If you need more control, you can configure Babel manually:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  externals: ['solid-js', 'solid-js/web', 'solid-js/store'],
  rollup: {
    babel: {
      presets: [
        ['babel-preset-solid', { generate: 'dom' }],
        ['@babel/preset-env', { bugfixes: true, targets: 'last 2 years' }]
        // Note: TypeScript is handled by the transformer via parser plugins
        // Babel only needs to parse TypeScript syntax, not transform it
      ],
      plugins: [
        // Add custom Babel plugins here
      ]
    }
  }
})
```

**Note:** When using Babel with SolidJS, Babel runs **before** your main transformer (esbuild/SWC/etc.), transforming JSX into JavaScript. TypeScript is handled by the transformer via parser plugins, not by Babel. This ensures that Rollup plugins can properly parse the code.

### Vue [#vue]

```typescript
import Vue from 'unplugin-vue/rollup'

export default defineConfig({
  rollup: {
    plugins: [
      Vue({
        include: [/\.vue$/],
        customElement: false
      })
    ]
  }
})
```

**Note:** For Vue 3 projects, you can also use the Vue preset instead of manually configuring the plugin:

```typescript
export default defineConfig({
  preset: 'vue'
})
```

### Svelte [#svelte]

```typescript
import svelte from 'rollup-plugin-svelte'

export default defineConfig({
  rollup: {
    plugins: [
      svelte({
        compilerOptions: {
          hydratable: true
        }
      })
    ]
  }
})
```

**Note:** For Svelte projects, you can also use the Svelte preset instead of manually configuring the plugin:

```typescript
export default defineConfig({
  preset: 'svelte'
})
```

## Asset Plugins [#asset-plugins]

### Copy Files [#copy-files]

```typescript
import copy from 'rollup-plugin-copy'

export default defineConfig({
  rollup: {
    plugins: [
      copy({
        targets: [
          { src: 'src/assets/*', dest: 'dist/assets' },
          { src: 'public/favicon.ico', dest: 'dist' }
        ]
      })
    ]
  }
})
```

### Image Processing [#image-processing]

```typescript
import image from '@rollup/plugin-image'

export default defineConfig({
  rollup: {
    plugins: [
      image({
        include: ['**/*.png', '**/*.jpg', '**/*.jpeg', '**/*.gif'],
        limit: 8192 // Inline images smaller than 8KB
      })
    ]
  }
})
```

### URL Assets [#url-assets]

```typescript
import url from '@rollup/plugin-url'

export default defineConfig({
  rollup: {
    plugins: [
      url({
        limit: 10 * 1024, // 10KB
        include: ['**/*.svg', '**/*.png', '**/*.jpg'],
        emitFiles: true
      })
    ]
  }
})
```

### Data URI imports (`?data-uri`) [#data-uri-imports-data-uri]

Inline files as data URIs at import sites. SVG files are encoded as tiny, human-readable data URIs; other file types are base64-encoded.

```typescript
import { defineConfig } from '@visulima/packem/config'
import { dataUriPlugin } from '@visulima/packem-rollup/plugins'

export default defineConfig({
  rollup: {
    plugins: [
      dataUriPlugin({
        // Optional: when using output in an <img srcset="..."> attribute
        // spaces are encoded as %20 to be srcset-safe
        srcset: false
      })
    ]
  }
})
```

Usage examples:

```ts
// SVG ? tiny data URI (not base64), whitespace-collapsed
import icon from './assets/icon.svg?data-uri'

// Any other file ? base64 data URI with appropriate mime type
import txt from './assets/readme.txt?data-uri'
```

Notes:

* Only imports ending with `?data-uri` are transformed; regular imports are unaffected.
* SVGs are encoded as `data:image/svg+xml,....` (tiny URI). Others as `data:<mime>;base64,...`.
* For `srcset` attributes, enable `{ srcset: true }` to encode spaces as `%20`.

## Development Plugins [#development-plugins]

### Live Reload [#live-reload]

```typescript
import livereload from 'rollup-plugin-livereload'

export default defineConfig({
  rollup: {
    plugins: [
      ...(process.env.NODE_ENV === 'development' ? [
        livereload({
          watch: 'dist',
          port: 35729
        })
      ] : [])
    ]
  }
})
```

### Serve Files [#serve-files]

```typescript
import serve from 'rollup-plugin-serve'

export default defineConfig({
  rollup: {
    plugins: [
      ...(process.env.NODE_ENV === 'development' ? [
        serve({
          open: true,
          contentBase: 'dist',
          port: 3000
        })
      ] : [])
    ]
  }
})
```

## Analysis Plugins [#analysis-plugins]

### Bundle Analyzer [#bundle-analyzer]

```typescript
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  rollup: {
    plugins: [
      visualizer({
        filename: 'dist/stats.html',
        open: true,
        gzipSize: true
      })
    ]
  }
})
```

### Bundle Size [#bundle-size]

```typescript
import bundleSize from 'rollup-plugin-bundle-size'

export default defineConfig({
  rollup: {
    plugins: [
      bundleSize()
    ]
  }
})
```

### License Check [#license-check]

```typescript
import license from 'rollup-plugin-license'

export default defineConfig({
  rollup: {
    plugins: [
      license({
        sourcemap: true,
        banner: {
          commentStyle: 'regular',
          content: {
            file: path.join(__dirname, 'LICENSE')
          }
        },
        thirdParty: {
          output: path.join(__dirname, 'dist', 'dependencies.txt')
        }
      })
    ]
  }
})
```

## Custom Plugins [#custom-plugins]

### Simple Plugin [#simple-plugin]

```typescript
function customPlugin() {
  return {
    name: 'custom-plugin',

    buildStart() {
      console.log('Build started!')
    },

    transform(code, id) {
      if (id.endsWith('.custom')) {
        return `export default ${JSON.stringify(code)}`
      }
      return null
    },

    generateBundle() {
      console.log('Bundle generated!')
    }
  }
}

export default defineConfig({
  rollup: {
    plugins: [
      customPlugin()
    ]
  }
})
```

### Advanced Plugin [#advanced-plugin]

```typescript
function advancedPlugin(options = {}) {
  const { include = '**/*.js', exclude = 'node_modules/**' } = options

  return {
    name: 'advanced-plugin',

    buildStart(opts) {
      // Plugin initialization
      this.addWatchFile('config.json')
    },

    resolveId(id, importer) {
      // Custom module resolution
      if (id === 'virtual:my-module') {
        return id
      }
      return null
    },

    load(id) {
      // Load custom modules
      if (id === 'virtual:my-module') {
        return 'export const msg = "Hello from virtual module"'
      }
      return null
    },

    transform(code, id) {
      // Transform code
      if (include.test && include.test(id) && !exclude.test(id)) {
        return {
          code: code.replace(/OLD_SYNTAX/g, 'NEW_SYNTAX'),
          map: null
        }
      }
      return null
    }
  }
}
```

## Plugin Configuration [#plugin-configuration]

### Conditional Plugins [#conditional-plugins]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      // Always included
      nodeResolve(),
      commonjs(),

      // Development only
      ...(process.env.NODE_ENV === 'development' ? [
        serve({ contentBase: 'dist' }),
        livereload()
      ] : []),

      // Production only
      ...(process.env.NODE_ENV === 'production' ? [
        terser(),
        visualizer()
      ] : [])
    ]
  }
})
```

### Plugin Options [#plugin-options]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      nodeResolve({
        // Prefer built-in Node.js modules
        preferBuiltins: true,

        // Include/exclude packages
        include: ['node_modules/**'],
        exclude: ['node_modules/problematic-package/**'],

        // Custom conditions
        exportConditions: ['node', 'import'],

        // Browser compatibility
        browser: false
      })
    ]
  }
})
```

### Plugin Ordering [#plugin-ordering]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      // 1. Module resolution
      nodeResolve(),

      // 2. Format conversion
      commonjs(),

      // 3. Code transformation
      typescript(),
      // Babel is configured via rollup.babel option or React preset
      // See React section above for examples

      // 4. Asset processing
      postcss(),
      image(),

      // 5. Development tools
      ...(isDev ? [serve(), livereload()] : []),

      // 6. Production optimization
      ...(isProd ? [terser(), visualizer()] : [])
    ]
  }
})
```

## Plugin Ecosystem [#plugin-ecosystem]

### Essential Plugins [#essential-plugins]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { nodeResolve } from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
import replace from '@rollup/plugin-replace'
import json from '@rollup/plugin-json'

export default defineConfig({
  transformer,
  rollup: {
    // Babel is configured via rollup.babel option (not as a plugin)
    // For React, use preset: 'react' instead
    babel: {
      presets: ['@babel/preset-env'],
      plugins: []
    },
    plugins: [
      nodeResolve(),
      commonjs(),
      replace({ preventAssignment: true }),
      json()
    ]
  }
})
```

### CSS Plugins [#css-plugins]

```typescript
import postcss from 'rollup-plugin-postcss'
import autoprefixer from 'autoprefixer'
import cssnano from 'cssnano'

export default defineConfig({
  rollup: {
    plugins: [
      postcss({
        extract: true,
        minimize: true,
        plugins: [
          autoprefixer(),
          cssnano()
        ]
      })
    ]
  }
})
```

### Testing Plugins [#testing-plugins]

```typescript
import istanbul from 'rollup-plugin-istanbul'

export default defineConfig({
  rollup: {
    plugins: [
      ...(process.env.NODE_ENV === 'test' ? [
        istanbul({
          exclude: ['test/**/*', 'node_modules/**/*']
        })
      ] : [])
    ]
  }
})
```

## Plugin Development [#plugin-development]

### Plugin Template [#plugin-template]

```typescript
interface PluginOptions {
  include?: string | RegExp | (string | RegExp)[]
  exclude?: string | RegExp | (string | RegExp)[]
  [key: string]: any
}

function myPlugin(options: PluginOptions = {}): Plugin {
  const filter = createFilter(options.include, options.exclude)

  return {
    name: 'my-plugin',

    buildStart(opts) {
      // Initialize plugin
    },

    resolveId(id, importer) {
      // Resolve imports
      return null
    },

    load(id) {
      // Load modules
      return null
    },

    transform(code, id) {
      if (!filter(id)) return null

      // Transform code
      return {
        code: transformedCode,
        map: sourceMap
      }
    },

    generateBundle(opts, bundle) {
      // Process bundle
    },

    writeBundle(opts, bundle) {
      // After bundle written
    }
  }
}
```

### Plugin Testing [#plugin-testing]

```typescript
import { rollup } from 'rollup'
import myPlugin from './my-plugin'

async function testPlugin() {
  const bundle = await rollup({
    input: 'test/fixtures/input.js',
    plugins: [
      myPlugin({
        // Test options
      })
    ]
  })

  const { output } = await bundle.generate({
    format: 'esm'
  })

  console.log(output[0].code)
}
```

## Troubleshooting [#troubleshooting]

### Plugin Conflicts [#plugin-conflicts]

<Callout type="warning">
  Some plugins may conflict with each other. Check plugin documentation for compatibility.
</Callout>

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      // Order matters - resolve conflicts by reordering
      nodeResolve(),
      commonjs(),

      // Avoid duplicate functionality
      // Note: When using Babel with React preset, Babel handles JSX transformation
      // TypeScript is handled by the transformer (esbuild/SWC) via parser plugins
    ]
  }
})
```

### Plugin Errors [#plugin-errors]

```typescript
export default defineConfig({
  rollup: {
    onwarn(warning, warn) {
      // Handle plugin warnings
      if (warning.plugin === 'problematic-plugin') {
        return // Ignore warnings from this plugin
      }
      warn(warning)
    }
  }
})
```

### Performance Issues [#performance-issues]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      // Use plugin caching
      somePlugin({
        cache: true
      }),

      // Limit plugin scope
      anotherPlugin({
        include: 'src/**',
        exclude: 'node_modules/**'
      })
    ]
  }
})
```

***

## Related Options [#related-options]

* [Rollup](/docs/packages/packem/options/plugins) - Rollup configuration
* [Transform](/docs/packages/packem/options/transformers) - Code transformation
* [Assets](/docs/packages/packem/guide/introduction) - Asset handling
* [External](/docs/packages/packem/options/externals) - External dependencies


# rootDir (/docs/packages/packem/options/root-dir)



# rootDir [#rootdir]

The root directory of your project. Used as the base for resolving all relative paths.

**Type:** `string`\
&#x2A;*Default:** Project root directory

## Example [#example]

```typescript
export default defineConfig({
  rootDir: __dirname
})
```


# Shims (/docs/packages/packem/options/shims)





# Shims [#shims]

When you publish ESM and CommonJS output from the same source, two interop problems show up: CommonJS globals (`__dirname`, `__filename`, `require`) do not exist in ESM, and default-export shapes differ between the two module systems. Packem addresses both with two real options.

## `cjsInterop` [#cjsinterop]

`cjsInterop` enables CommonJS interop handling for ESM modules. It is a top-level `BuildOptions` field and defaults to `false`.

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  cjsInterop: true,
})
```

When enabled, Packem applies its CommonJS-interop Rollup plugin and adjusts warning handling (for example, it suppresses the `MIXED_EXPORTS` warning that would otherwise fire). The plugin's own behaviour can be tuned through `rollup.cjsInterop`, which defaults to `{ addDefaultProperty: false }`:

```typescript
export default defineConfig({
  cjsInterop: true,
  rollup: {
    cjsInterop: {
      addDefaultProperty: true,
    },
  },
})
```

## ESM `__dirname` / `__filename` / `require` shim [#esm-__dirname--__filename--require-shim]

The ESM shim rewrites CommonJS-only globals so that code using `__dirname`, `__filename`, or a global `require(...)` keeps working when emitted as ESM. It is configured via `rollup.shim` (an `EsmShimCjsSyntaxOptions | false`).

<Callout type="warning">
  The shim is only applied when **both** `cjsInterop` is truthy **and** `rollup.shim` is set. In source the gate is literally `cjsInterop && rollup.shim` — enabling one without the other does nothing.
</Callout>

```typescript
export default defineConfig({
  cjsInterop: true,
  rollup: {
    shim: {
      // EsmShimCjsSyntaxOptions (e.g. include/exclude filters)
    },
  },
})
```

### What the shim injects [#what-the-shim-injects]

The shim scans each chunk for `__filename`, `__dirname`, and global `require(...)` usage and, only when found, prepends the matching imports after the last static import. For example:

* `__filename` / `__dirname` → `import __cjs_url__ from "node:url"` (and `node:path` for `__dirname`)
* global `require(...)` → `import __cjs_mod__ from "node:module"`

Each injected line is marked with a `// -- packem CommonJS … shim --` comment, so Packem will not double-shim already-shimmed output. To disable the shim entirely, set `rollup.shim: false`.

***

## Related Options [#related-options]

* [Bundler](/docs/packages/packem/options/bundler) - Shims run on the Rollup backend
* [Package Exports](/docs/packages/packem/options/package-exports) - How ESM/CJS entries map to `exports`
* [Target](/docs/packages/packem/options/target) - Node target affects which interop you need


# Silent Mode (/docs/packages/packem/options/silent-mode)





# Silent Mode [#silent-mode]

<Callout type="warning">
  Packem has **no** `silent` config option and **no** `--silent` CLI flag. Logging verbosity is controlled by the `debug` option / `--debug` behaviour and the environment flags described below.
</Callout>

Build output verbosity in Packem is driven by a debug/verbose toggle rather than a "silent" switch. The only verbosity-related control that exists in the config is `debug`.

## `debug` [#debug]

The `debug` option enables verbose logging. It is part of `BuildOptions`:

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  debug: true,
})
```

When enabled, Packem emits additional `logger.debug(...)` output (for example, where the config file was found) and passes `debug` through to [jiti](https://github.com/unjs/jiti), which loads your config and entry files.

## Environment flags [#environment-flags]

The `--production` and `--development` CLI flags (mutually exclusive) set the build [environment](/docs/packages/packem/options/platform), which in turn affects defaults such as minification. They do not silence logging, but they are the primary way to switch a build's mode from the command line:

```bash
packem build --production
packem build --development
```

## What does not exist [#what-does-not-exist]

For accuracy, note the following are **not** available:

* No `silent: true` config key.
* No `--silent` or `--quiet` CLI flag.
* No `logLevel` / `verbosity` config option.

If you need quieter output, the practical lever is to leave `debug` off (its default), which suppresses the verbose debug stream.

***

## Related Options [#related-options]

* [Platform](/docs/packages/packem/options/platform) - `environment` and the `--production` / `--development` flags
* [Watch Mode](/docs/packages/packem/options/watch) - Development workflow logging


# sourceDir (/docs/packages/packem/options/source-dir)



# sourceDir [#sourcedir]

The directory containing your source files. Used for entry detection and output mapping.

**Type:** `string`\
&#x2A;*Default:** `'src'`

## Example [#example]

```typescript
export default defineConfig({
  sourceDir: 'lib'
})
```


# Source Maps (/docs/packages/packem/options/source-maps)





# Source Maps [#source-maps]

Source maps provide a way to map compiled code back to the original source code, enabling debugging of the original code in browsers and other tools. Packem supports various source map formats and configurations.

## Basic Configuration [#basic-configuration]

### Enable Source Maps [#enable-source-maps]

The simplest way to enable source maps for every output is the top-level `sourcemap` boolean:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
})
```

For per-output control, set `sourcemap` on the Rollup output instead:

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true
    }
  }
})
```

### Source Map Types [#source-map-types]

```typescript
export default defineConfig({
  rollup: {
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs',
        sourcemap: true // External source map
      },
      {
        format: 'cjs',
        file: 'dist/index.cjs',
        sourcemap: 'inline' // Inline source map
      },
      {
        format: 'iife',
        file: 'dist/index.global.js',
        sourcemap: 'hidden' // No reference comment
      }
    ]
  }
})
```

## Source Map Formats [#source-map-formats]

### External Source Maps [#external-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true, // Creates .map files
      sourcemapFile: 'dist/index.js.map'
    }
  }
})
```

### Inline Source Maps [#inline-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: 'inline' // Embedded in the bundle
    }
  }
})
```

### Hidden Source Maps [#hidden-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: 'hidden' // Generated but not referenced
    }
  }
})
```

## Environment-Specific Configuration [#environment-specific-configuration]

### Development vs Production [#development-vs-production]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: process.env.NODE_ENV === 'development' ? true : false
    }
  }
})
```

### Conditional Source Maps [#conditional-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: process.env.GENERATE_SOURCEMAP !== 'false'
    }
  }
})
```

## Transformer-Specific Source Maps [#transformer-specific-source-maps]

Transformer source map options live under the matching transformer key inside `rollup`.

### esbuild Source Maps [#esbuild-source-maps]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  sourcemap: true,
  rollup: {
    esbuild: {
      sourceMap: true,
    },
  },
})
```

### SWC Source Maps [#swc-source-maps]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  sourcemap: true,
  rollup: {
    swc: {
      sourceMaps: true,
    },
  },
})
```

## CSS Source Maps [#css-source-maps]

CSS source maps are configured via the `sourceMap` option of the CSS processor, which lives under `rollup.css`. It accepts `true`, `false`, or `'inline'`.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    css: {
      sourceMap: true,
    },
  },
})
```

For inline CSS source maps:

```typescript
export default defineConfig({
  rollup: {
    css: {
      sourceMap: 'inline',
    },
  },
})
```

## Advanced Configuration [#advanced-configuration]

### Source Map Paths [#source-map-paths]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      sourcemapPathTransform: (relativeSourcePath, sourcemapPath) => {
        // Transform source paths in source maps
        return relativeSourcePath.replace('../src/', 'src/')
      }
    }
  }
})
```

### Source Content Inclusion [#source-content-inclusion]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      sourcemapExcludeSources: false, // Include source content
      sourcemapFile: 'dist/index.js.map'
    }
  }
})
```

### Base URL Configuration [#base-url-configuration]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      sourcemapBaseUrl: 'https://cdn.example.com/src/'
    }
  }
})
```

## Framework Integration [#framework-integration]

### React Source Maps [#react-source-maps]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      react({
        // Preserve JSX source locations
        development: true
      })
    ],
    
    output: {
      sourcemap: true
    }
  }
})
```

### Vue Source Maps [#vue-source-maps]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      vue({
        // Include template source maps
        sourceMap: true
      })
    ],
    
    output: {
      sourcemap: true
    }
  }
})
```

## Debugging Configuration [#debugging-configuration]

### Browser DevTools [#browser-devtools]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      // Optimize for browser debugging
      sourcemapExcludeSources: false
    }
  }
})
```

### Node.js Debugging [#nodejs-debugging]

```typescript
export default defineConfig({
  rollup: {
    output: {
      format: 'cjs',
      sourcemap: true,
      // Enable source map support
      banner: 'require("source-map-support").install();'
    }
  }
})
```

### VS Code Integration [#vs-code-integration]

```json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Bundle",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/dist/index.js",
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}
```

## Performance Considerations [#performance-considerations]

### Source Map Size [#source-map-size]

```typescript
export default defineConfig({
  rollup: {
    output: {
      // Smaller source maps
      sourcemap: process.env.NODE_ENV === 'development' ? true : 'hidden'
    }
  }
})
```

### Build Performance [#build-performance]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      // Exclude sources content for faster builds
      sourcemapExcludeSources: true
    }
  }
})
```

### Network Performance [#network-performance]

```typescript
export default defineConfig({
  rollup: {
    output: {
      // Use hidden source maps for production
      sourcemap: process.env.NODE_ENV === 'production' ? 'hidden' : true
    }
  }
})
```

## Source Map Validation [#source-map-validation]

### Verification [#verification]

```typescript
export default defineConfig({
  hooks: {
    'build:done': async () => {
      // Validate source maps
      const { SourceMapConsumer } = await import('source-map')
      const fs = await import('fs/promises')
      
      const mapContent = await fs.readFile('dist/index.js.map', 'utf-8')
      const consumer = await new SourceMapConsumer(JSON.parse(mapContent))
      
      // Test source map accuracy
      const originalPosition = consumer.originalPositionFor({
        line: 1,
        column: 0
      })
      
      console.log('Source map validation:', originalPosition)
      consumer.destroy()
    }
  }
})
```

### Testing Tools [#testing-tools]

```typescript
export default defineConfig({
  rollup: {
    plugins: [
      {
        name: 'sourcemap-test',
        generateBundle(options, bundle) {
          // Test source map generation
          Object.keys(bundle).forEach(fileName => {
            if (fileName.endsWith('.map')) {
              const map = JSON.parse(bundle[fileName].source)
              console.log(`Source map for ${fileName}:`, {
                version: map.version,
                sources: map.sources.length,
                mappings: map.mappings.length
              })
            }
          })
        }
      }
    ]
  }
})
```

## Troubleshooting [#troubleshooting]

### Missing Source Maps [#missing-source-maps]

<Callout type="warning">
  If source maps aren't working, ensure all transformers have source map support enabled.
</Callout>

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  // Enable source maps at all levels
  sourcemap: true,
  rollup: {
    output: {
      sourcemap: true,
    },
    esbuild: {
      sourceMap: true,
    },
    css: {
      sourceMap: true,
    },
  },
})
```

### Incorrect Source Paths [#incorrect-source-paths]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      sourcemapPathTransform: (relativeSourcePath) => {
        // Fix source paths
        return relativeSourcePath.replace(/\\/g, '/')
      }
    }
  }
})
```

### Large Source Maps [#large-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      // Exclude node_modules from source maps
      sourcemapIgnoreList: (relativeSourcePath) => {
        return relativeSourcePath.includes('node_modules')
      }
    }
  }
})
```

## Security Considerations [#security-considerations]

### Production Source Maps [#production-source-maps]

```typescript
export default defineConfig({
  rollup: {
    output: {
      // Don't expose source maps in production
      sourcemap: process.env.NODE_ENV === 'development' ? true : false
    }
  }
})
```

### Source Content Protection [#source-content-protection]

```typescript
export default defineConfig({
  rollup: {
    output: {
      sourcemap: true,
      // Don't include source content in production
      sourcemapExcludeSources: process.env.NODE_ENV === 'production'
    }
  }
})
```

***

## Related Options [#related-options]

* [Target](/docs/packages/packem/options/target) - Compilation targets
* [Minify](/docs/packages/packem/options/minify) - Code minification
* [Watch](/docs/packages/packem/options/watch) - Development workflow
* [Debug](/docs/packages/packem/options/debug) - Debugging options


# Target (/docs/packages/packem/options/target)





# Target [#target]

The compilation target determines which JavaScript features and runtime environments your code should support. Packem does **not** expose a single top-level `target` option. Instead, the target is driven by three real mechanisms:

* **`runtime`** - the target runtime environment (`node`, `browser`, `edge-light`, `react-server`, `bun`, `deno`, `workerd`, `electron`, `react-native`).
* **`browserTargets`** - an array of [browserslist](https://github.com/browserslist/browserslist) queries used for transpilation.
* **The transformer's own `target`** - e.g. `rollup.esbuild.target` or `rollup.swc.jsc.target`, and your `tsconfig.json` `compilerOptions.target`.

<Callout type="warning">
  There is no top-level `target: 'es2020'` option. Set the ECMAScript target through the active transformer (for example `rollup.esbuild.target`) or your `tsconfig.json`.
</Callout>

## ECMAScript Target [#ecmascript-target]

The ECMAScript syntax level is controlled by the active transformer. Configure it under the matching transformer key inside `rollup`.

### esbuild [#esbuild]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
  },
})
```

### SWC [#swc]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/swc'

export default defineConfig({
  transformer,
  rollup: {
    swc: {
      jsc: {
        target: 'es2020',
        parser: {
          syntax: 'typescript',
          tsx: true,
        },
      },
    },
  },
})
```

### TypeScript / tsconfig [#typescript--tsconfig]

When using the TypeScript transformer (or to influence type-aware behavior), the ECMAScript target comes from your `tsconfig.json`:

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"]
  }
}
```

### Available ECMAScript Levels [#available-ecmascript-levels]

These are the values accepted by transformer `target` options (e.g. `rollup.esbuild.target`):

* `es5` - ES5 (2009) - Maximum compatibility
* `es2015` / `es6` - ES2015 (2015) - Classes, arrow functions, let/const
* `es2016` - ES2016 (2016) - Exponentiation operator
* `es2017` - ES2017 (2017) - Async/await, Object.entries/values
* `es2018` - ES2018 (2018) - Rest/spread, async iteration
* `es2019` - ES2019 (2019) - Optional catch binding, flat/flatMap
* `es2020` - ES2020 (2020) - Optional chaining, nullish coalescing
* `es2021` - ES2021 (2021) - Logical assignment, numeric separators
* `es2022` - ES2022 (2022) - Top-level await, private fields
* `esnext` - Latest features

## Browser Targets [#browser-targets]

Use the top-level `browserTargets` option to drive transpilation with browserslist queries.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  browserTargets: [
    'chrome 90',
    'firefox 88',
    'safari 14',
    'edge 90',
  ],
})
```

### Browserslist Integration [#browserslist-integration]

`browserTargets` accepts the same query syntax as a `.browserslistrc` file or the `browserslist` field in `package.json`. You may also configure browserslist in `package.json` directly:

```json
// package.json
{
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead"
  ]
}
```

## Runtime Targets [#runtime-targets]

The `runtime` option selects the target runtime environment. This affects defaults such as externalization, conditions, and whether `browserTargets` apply.

### Node.js [#nodejs]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'node',
})
```

### Browser [#browser]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'browser',
  browserTargets: ['> 1%', 'last 2 versions'],
})
```

### Edge Runtime [#edge-runtime]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'edge-light', // Vercel Edge Runtime
  rollup: {
    output: {
      format: 'esm',
    },
  },
})
```

### React Server Components [#react-server-components]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'react-server',
  rollup: {
    external: ['react', 'react-dom'],
    output: {
      format: 'esm',
    },
  },
})
```

### Available Runtimes [#available-runtimes]

`runtime` accepts: `browser`, `bun`, `deno`, `edge-light`, `electron`, `node`, `react-native`, `react-server`, `workerd`.

## Feature Support (esbuild) [#feature-support-esbuild]

esbuild lets you toggle individual language features via its `supported` map. These live under `rollup.esbuild`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
      supported: {
        'optional-chaining': true,
        'nullish-coalescing': true,
        'bigint': false, // Disable if not supported
        'top-level-await': true,
      },
    },
  },
})
```

## Output Code Generation [#output-code-generation]

Rollup can downlevel some generated glue code via `output.generatedCode`. This is independent of the transformer target.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    output: {
      generatedCode: {
        preset: 'es2015',
        arrowFunctions: true,
        constBindings: true,
        objectShorthand: true,
      },
    },
  },
})
```

## Multiple Output Formats [#multiple-output-formats]

To produce several output formats, provide an array of outputs. Rollup outputs do not have a per-output `target`; the syntax level is set once via the transformer.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    output: [
      {
        format: 'esm',
        file: 'dist/index.mjs',
      },
      {
        format: 'cjs',
        file: 'dist/index.cjs',
      },
    ],
  },
})
```

## Library Targets [#library-targets]

### Modern Library [#modern-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
    },
  },
})
```

### Node.js Library [#nodejs-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  runtime: 'node',
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    output: {
      format: 'cjs',
      file: 'dist/index.cjs',
    },
    external: ['fs', 'path', 'url'], // Node.js built-ins
  },
})
```

## Framework Targets [#framework-targets]

### React Library [#react-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    external: ['react', 'react-dom'],
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
    },
  },
})
```

### Vue Library [#vue-library]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  preset: 'vue',
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
    },
    external: ['vue'],
    output: {
      format: 'esm',
      file: 'dist/index.mjs',
    },
  },
})
```

## Environment-Specific Configuration [#environment-specific-configuration]

Because `defineConfig` accepts a plain object (or a function), you can compute the target from environment variables:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: process.env.NODE_ENV === 'production' ? 'es2020' : 'esnext',
    },
  },
})
```

## Troubleshooting [#troubleshooting]

### Syntax Errors [#syntax-errors]

<Callout type="warning">
  If you encounter syntax errors, your transformer target might be too old for the features you're using. Raise `rollup.esbuild.target` (or the equivalent for your transformer) or your `tsconfig.json` `compilerOptions.target`.
</Callout>

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  rollup: {
    esbuild: {
      target: 'es2020',
      supported: {
        'optional-chaining': true,
      },
    },
  },
})
```

### Browser Compatibility [#browser-compatibility]

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
  browserTargets: [
    'chrome 60',
    'firefox 55',
    'safari 12',
    'edge 79',
  ],
})
```

***

## Related Options [#related-options]

* [Transformer](/docs/packages/packem/options/transformers) - Choose JavaScript transformer
* [Output Format](/docs/packages/packem/options/output-format) - Configure output formats
* [Minify](/docs/packages/packem/options/minify) - Code minification


# Transformers (/docs/packages/packem/options/transformers)





# Transformers [#transformers]

The `transformer` option selects the engine that converts your TypeScript and modern JavaScript source into the output Packem bundles. It is the option-reference companion to the [Transformers guide](/docs/packages/packem/guide/transformers), which compares the engines in detail.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,
})
```

## Setting the transformer [#setting-the-transformer]

`transformer` is a function (`TransformerFn`), not a string. You import the adapter you want from `@visulima/packem` and pass it straight through to `defineConfig`.

```typescript
import esbuild from '@visulima/packem/transformer/esbuild'
import swc from '@visulima/packem/transformer/swc'
import oxc from '@visulima/packem/transformer/oxc'
import sucrase from '@visulima/packem/transformer/sucrase'
```

There are **four** transformer import paths:

| Import path                            | Engine                   |
| -------------------------------------- | ------------------------ |
| `@visulima/packem/transformer/esbuild` | esbuild (Go)             |
| `@visulima/packem/transformer/swc`     | swc (Rust)               |
| `@visulima/packem/transformer/oxc`     | OXC (Rust, experimental) |
| `@visulima/packem/transformer/sucrase` | sucrase (JavaScript)     |

<Callout type="info">
  Under the default `bundler: 'rollup'` backend, `transformer` is **required** — Packem refuses to build without it. See the [Transformers guide](/docs/packages/packem/guide/transformers) for how to choose between the four engines.
</Callout>

## When each transformer applies [#when-each-transformer-applies]

The `transformer` option only takes effect under the default `'rollup'` [bundler](/docs/packages/packem/options/bundler). The esbuild / swc / oxc / sucrase adapters are Rollup plugins, so they are only invoked on the Rollup path.

When you select `bundler: 'rolldown'`, Rolldown ships its own oxc-based transform and always uses it. In that case the `transformer` option **must be omitted** — passing one is a configuration mistake and Packem will refuse to build.

```typescript
// ✅ Rollup (default) — transformer required
export default defineConfig({
  bundler: 'rollup',
  transformer: esbuild,
})

// ✅ Rolldown — no transformer
export default defineConfig({
  bundler: 'rolldown',
})
```

## Switching transformers conditionally [#switching-transformers-conditionally]

Because `transformer` is just a value, you can swap engines based on the environment:

```typescript
import esbuild from '@visulima/packem/transformer/esbuild'
import swc from '@visulima/packem/transformer/swc'

const isDev = process.env.NODE_ENV === 'development'

export default defineConfig({
  transformer: isDev ? esbuild : swc,
})
```

***

## Related Options [#related-options]

* [Bundler](/docs/packages/packem/options/bundler) - Rollup (transformer-driven) vs Rolldown (built-in oxc)
* [Target](/docs/packages/packem/options/target) - Compilation targets passed to the transformer
* [Minification](/docs/packages/packem/options/minify) - Output minification


# Tree Shaking (/docs/packages/packem/options/tree-shaking)





# Tree Shaking [#tree-shaking]

Tree shaking removes code that is never used from the final bundle. Packem does **not** expose a top-level `treeshake` option — tree-shaking is configured through the `rollup.treeshake` passthrough, which forwards directly to [Rollup's `treeshake` options](https://rollupjs.org/configuration-options/#treeshake).

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  rollup: {
    treeshake: {
      preset: 'smallest',
      moduleSideEffects: true,
    },
  },
})
```

<Callout type="info">
  There is no `defineConfig({ treeshake })` key. Always nest it under `rollup`.
</Callout>

## Defaults [#defaults]

Packem configures Rollup's tree-shaking with these defaults:

```typescript
{
  // preserve side-effect-only imports
  moduleSideEffects: true,
  // Rollup's most optimal tree-shaking (drops unused getter reads)
  preset: 'smallest',
}
```

The `smallest` preset is Rollup's most aggressive setting, while `moduleSideEffects: true` keeps `import './side-effect'`-style imports intact so global side effects are not dropped.

## Customizing tree-shaking [#customizing-tree-shaking]

Because `rollup.treeshake` is a straight passthrough, any Rollup tree-shake option is available:

```typescript
export default defineConfig({
  rollup: {
    treeshake: {
      preset: 'recommended',
      propertyReadSideEffects: false,
      unknownGlobalSideEffects: false,
      tryCatchDeoptimization: false,
    },
  },
})
```

### Marking side-effect-free code [#marking-side-effect-free-code]

To let the bundler drop more code, declare your package side-effect-free in `package.json`:

```json
{
  "sideEffects": false
}
```

Combine that with `moduleSideEffects` to fine-tune which imports are preserved.

***

## Related Options [#related-options]

* [Minification](/docs/packages/packem/options/minify) - Shrink the remaining code
* [Bundler](/docs/packages/packem/options/bundler) - Tree-shaking applies to the Rollup backend
* [Target](/docs/packages/packem/options/target) - Modern targets enable more aggressive shaking


# typedoc (/docs/packages/packem/options/typedoc)



# typedoc [#typedoc]

Options for generating API documentation with [TypeDoc](https://typedoc.org/). Set to `false` to disable.

**Type:** `TypeDocumentOptions | false`\
&#x2A;*Default:** `{}`

## Quick Setup [#quick-setup]

Use the `add` command to automatically configure TypeDoc:

```bash
npx packem add typedoc
```

This will:

* Add TypeDoc builder configuration to your `packem.config.ts`
* Install TypeDoc and related plugins
* Set up the builder for documentation generation

## Example [#example]

```typescript
export default defineConfig({
  typedoc: {
    format: 'markdown',
    output: 'docs/api'
  }
})
```


# Unbundle (/docs/packages/packem/options/unbundle)





# Unbundle [#unbundle]

The `unbundle` option switches Packem from bundling everything into a single file to **preserving the original source file structure**. Each module is emitted as its own output file, mirroring the directory layout of your source tree.

```typescript
import { defineConfig } from '@visulima/packem/config'

export default defineConfig({
  unbundle: true,
})
```

## Default [#default]

`unbundle` defaults to `false` — Packem bundles your modules together.

## What "preserved structure" means [#what-preserved-structure-means]

With `unbundle: true`, instead of inlining imported modules into one output, every module becomes a separate file at a path that matches its source location. For example, if `src/index.ts` re-exports from `./a/indexA` and `./b/indexB`:

```
src/index.ts        →  dist/index.js
src/a/indexA.ts     →  dist/a/indexA.js
src/b/indexB.ts     →  dist/b/indexB.js
```

The import graph between those files is kept, so `dist/index.js` still imports from `dist/a/indexA.js` rather than containing its code.

<Callout type="info">
  This is the "preserve modules" style of output: useful when consumers want to import individual files, when you want maximal tree-shakeability for downstream bundlers, or when you need the output layout to mirror the source layout.
</Callout>

## CLI flag [#cli-flag]

`unbundle` can also be enabled per build from the command line:

```bash
packem build --unbundle
```

The flag is described as "Enable unbundle mode to preserve source file structure instead of bundling into a single file".

***

## Related Options [#related-options]

* [Output Directory](/docs/packages/packem/options/output-directory) - Where the preserved structure is written
* [Tree Shaking](/docs/packages/packem/options/tree-shaking) - Dead-code elimination across modules
* [Package Exports](/docs/packages/packem/options/package-exports) - Mapping entries to `package.json#exports`


# Watch Mode (/docs/packages/packem/options/watch)





# Watch Mode [#watch-mode]

Watch mode rebuilds your project whenever a file in the module graph changes,
giving you fast feedback during development. It is driven by Rollup's native
watcher.

<Callout type="info">
  Watch mode is enabled from the **CLI**, not from a config option. There is no
  top-level `watch` key in `packem.config.ts`; watcher tuning lives under
  `rollup.watch`.
</Callout>

## Enable Watch Mode [#enable-watch-mode]

```bash
# Long form
packem build --watch

# Short form
packem build -w
```

Run a command after every successful rebuild with `--onSuccess` (handy for
restarting a server):

```bash
packem build --watch --onSuccess "node dist/index.mjs"
```

## Tuning the Watcher [#tuning-the-watcher]

Watcher behaviour is configured through `rollup.watch`, which accepts Rollup's
[`WatcherOptions`](https://rollupjs.org/configuration-options/#watch). These
options only take effect when the build is started with `--watch`.

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  rollup: {
    watch: {
      // Restrict which files are watched
      include: 'src/**',
      exclude: ['**/*.test.ts', 'node_modules/**'],

      // Clear the console before each rebuild
      clearScreen: true,

      // Delay (ms) before a rebuild starts after a change
      buildDelay: 0,

      // Re-run the build without writing files to disk
      skipWrite: false,
    },
  },
})
```

### Supported `rollup.watch` keys [#supported-rollupwatch-keys]

| Key           | Type                                       | Description                                               |
| ------------- | ------------------------------------------ | --------------------------------------------------------- |
| `include`     | `string \| RegExp \| (string \| RegExp)[]` | Limit watching to these files                             |
| `exclude`     | `string \| RegExp \| (string \| RegExp)[]` | Skip watching these files                                 |
| `clearScreen` | `boolean`                                  | Clear the screen before each rebuild                      |
| `buildDelay`  | `number`                                   | Throttle rebuilds by this many milliseconds               |
| `skipWrite`   | `boolean`                                  | Run the build but don't write output files                |
| `chokidar`    | `ChokidarOptions`                          | Options passed through to the underlying chokidar watcher |

### Polling for problematic file systems [#polling-for-problematic-file-systems]

Native file events do not work reliably on some network drives, containers, or
virtual machines. Fall back to polling by passing chokidar options:

```typescript
export default defineConfig({
  transformer,

  rollup: {
    watch: {
      chokidar: {
        usePolling: true,
        interval: 1000,
      },
    },
  },
})
```

## CSS in Watch Mode [#css-in-watch-mode]

Imported CSS (and preprocessor) files are part of the module graph, so editing a
watched stylesheet triggers a rebuild automatically. Configure CSS handling
under `rollup.css`:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'

export default defineConfig({
  transformer,

  rollup: {
    css: {
      mode: 'extract',
      loaders: [postcssLoader],
      // Emit source maps while iterating
      sourceMap: true,
    },
  },
})
```

## Reacting to Watch Events [#reacting-to-watch-events]

There is no dedicated "watch closed" hook. Use the `rollup:watch` hook to access
the Rollup watcher instance and subscribe to its events (including `END` and
`ERROR`) for cleanup or custom logging:

```typescript
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'

export default defineConfig({
  transformer,

  hooks: {
    'rollup:watch': (context, watcher) => {
      watcher.on('event', (event) => {
        if (event.code === 'END') {
          console.log('Rebuild complete')
        }

        if (event.code === 'ERROR') {
          console.error('Rebuild failed:', event.error)
        }
      })

      // Clean up when the process is terminated
      process.on('SIGINT', () => {
        watcher.close()
        process.exit(0)
      })
    },
  },
})
```

## Faster Rebuilds [#faster-rebuilds]

Watch mode reuses Packem's persistent file cache when it is enabled, so
unchanged modules are not re-transformed between rebuilds:

```typescript
export default defineConfig({
  transformer,
  fileCache: true,
})
```

See [file cache](/docs/packages/packem/options/file-cache) for details.

***

## Related Options [#related-options]

* [On Success](/docs/packages/packem/options/on-success) - Run a command after each successful build
* [File Cache](/docs/packages/packem/options/file-cache) - Persistent cache for faster rebuilds
* [Source Maps](/docs/packages/packem/options/source-maps) - Debug information


# Rolldown Status (/docs/packages/packem/rolldown-status)



# Rolldown backend: support status and graduation criteria [#rolldown-backend-support-status-and-graduation-criteria]

> **Updated 2026-06-16 (rolldown 1.0.3).** Four of five graduation criteria are
> met: the rolldown suite **gates merges** (folded into the `test` matrix across
> node 22/24/25 + macOS), **native DTS landed*&#x2A; (PR #208, plan 015), the
> **`.rolldown.snap` family is portable + gating*&#x2A;, and the wizard hint dropped
> &#x2A;"experimental"*. The only open item is the `packem-rolldown` placeholder
> package decision (low-urgency; it is private and unpublished).

## 1. Status today [#1-status-today]

| Dimension                | State                                                                                                                                                                                                                                                                                                                    | Source                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Wizard label             | **"fast, native DTS"*&#x2A; — the &#x2A;"experimental"* qualifier was dropped now that the CI-gating and native-DTS criteria are met (the earlier "falls back to rollup for DTS" clause is also gone).                                                                                                                   | `packages/packem/src/bundler/first-run-wizard.ts:52`                             |
| CI job                   | **Gating** — folded into the `test` matrix via a `bundler: [rollup, rolldown]` dimension, so the full rolldown suite runs on node 22/24/25 (ubuntu) + node 22 (macOS) and is **required** through `test-required-check` (which `needs: [files-changed, test]`). The standalone advisory `test-rolldown` job was removed. | `.github/workflows/test.yml` (`test` job, `bundler` matrix)                      |
| DTS generation (build)   | **Routes through rolldown natively** when `bundler: "rolldown"` (PR #208). Rollup is no longer pulled in for the DTS path under rolldown; the `@visulima/rollup-plugin-dts` virtual-module guard makes `emitDtsOnly` work under rolldown.                                                                                | `packages/packem/src/packem/index.ts`                                            |
| DTS watching             | **Runs natively through rolldown** when rolldown is the bundler — the bundle watcher and the DTS watcher both use the rolldown-native watch path (PR #208). No rollup fallback for the watch DTS path.                                                                                                                   | `packages/packem/src/rollup/watch.ts:278-296, 341`                               |
| `packem-rolldown` pkg    | Empty `export {}` placeholder. No rolldown-only plugins have landed yet. The package is **private (`"private": true`) and not published** — pinned at `1.0.0-alpha.0` while its siblings advance, so it is not released on alpha bumps.                                                                                  | `packages/packem-rolldown/src/index.ts`, `packages/packem-rolldown/package.json` |
| Local suite (2026-06-16) | **rolldown: 476 passed / 0 failed / 37 skipped** (41 files passed, 4 skipped); **rollup: 505 passed / 0 failed / 8 skipped**. The earlier 5 snapshot failures (absolute worktree paths in `externals.test.ts`/`css.test.ts`) are fixed by the `normalizeRolldownOutput` portability helper.                              | `pnpm run test:bundlers` in `packages/packem`                                    |

## 2. Graduation criteria (proposed) [#2-graduation-criteria-proposed]

Each checkbox is a decision point for the maintainer, not a preset constraint.

* [x] **CI stability**: &#x2A;*met (2026-06-16).** Rather than keep a standalone
  `test-rolldown` job and add it to `test-required-check.needs` after N green
  runs, the rolldown suite was folded directly into the `test` matrix via a
  `bundler: [rollup, rolldown]` dimension. Because `test-required-check`
  already `needs: [files-changed, test]`, every rolldown matrix leg (node
  22/24/25 + macOS) now gates merges alongside rollup. The flakiness that
  motivated the advisory carve-out was traced to non-portable snapshots
  (machine-specific absolute pnpm paths and content-derived chunk hashes)
  and fixed with a rolldown-only `normalizeRolldownOutput` helper, so the
  "20 consecutive green runs" probation is moot — the root cause is resolved,
  not merely observed-stable.

* [x] **Native DTS**: &#x2A;*met (2026-06-16, PR #208 / plan 015).*&#x2A; Rolldown-native
  DTS generation landed — packem routes the DTS path through rolldown when
  rolldown is the selected bundler, the rollup-DTS fallback pull-in is gone,
  and the wizard hint's &#x2A;"falls back to rollup for DTS"* clause was dropped.
  The plan-012 GO path below records how the blocker was cleared.

  Plan-012 spike (2026-06-11, on branch
  `advisor/012-rolldown-dts-spike`) returned &#x2A;*GO (conditional)**:
  `@visulima/rollup-plugin-dts` is \~97% rolldown-compatible today (rolldown
  1.0.3). The single hard blocker was a one-line virtual-module guard in
  `packages/rollup-plugin-dts/src/generate.ts`: `if (id.startsWith("\0"))`
  prevents the plugin's `transform` hook from clobbering rolldown's injected
  `\0rolldown/runtime.js` module, which previously caused a fatal
  `RUNTIME_MODULE_SYMBOL_NOT_FOUND` error.

  **Progress (2026-06-11, plan 014 merged):** the plugin side is DONE — the
  virtual-module guard landed, rolldown is declared as an optional peer (+
  dev) dependency, the `rollupBuild as rolldownBuild` alias misnomer in
  `__tests__/index.test.ts` is fixed, and a real rolldown test lane
  (`packages/rollup-plugin-dts/__tests__/rolldown.test.ts`, 4 fixtures × both
  `emitDtsOnly` modes, content assertions) enforces the compat claim.
  Remaining before this criterion can be ticked (plan 015): update
  `packages/packem/src/packem/index.ts` and `packages/packem/src/rollup/watch.ts`
  to route DTS through rolldown when rolldown is the selected bundler, and
  decide on stripping rolldown `//#region` comments from emitted d.ts.

* [x] **Snapshot currency**: &#x2A;*met (2026-06-16).** The `.rolldown.snap` family
  is now exercised by the **gating** rolldown matrix legs on every qualifying
  PR, and the snapshots were made machine/CI-portable (the
  `normalizeRolldownOutput` helper rewrites absolute pnpm-store paths to
  `<root>` and content-derived chunk hashes to `[HASH]`), so a green CI run
  now proves currency. Regenerate with
  `PACKEM_TEST_BUNDLER=rolldown pnpm exec vitest run "<path>" -u` from
  `packages/packem`.

* [ ] **Package decision**: decide the fate of `packages/packem-rolldown`
  — either (a) activate it when the first rolldown-only plugin lands and
  export it from `src/index.ts`, or (b) delete the placeholder and recreate
  it when real content exists. The package is already private and unpublished
  (pinned at `1.0.0-alpha.0`), so there is no consumer-facing cost either way;
  keeping the reserved barrel is near-zero overhead. Open, low-urgency.

* [x] **Wizard label**: &#x2A;*met (2026-06-16).*&#x2A; The &#x2A;"experimental"* qualifier was
  dropped from the wizard hint in
  `packages/packem/src/bundler/first-run-wizard.ts:52`; it now reads
  `"fast, native DTS"`. This was the last user-visible graduation signal, and
  its prerequisites (CI stability + native DTS) were already met.

## 3. What graduation changes (file-by-line) [#3-what-graduation-changes-file-by-line]

All rows below are now **DONE**.

| Criterion                  | Status | File / change                                                                                                                                                                                                                           |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CI stability (criterion 1) | DONE   | Achieved differently than originally planned: instead of adding a `test-rolldown` job to `test-required-check.needs`, rolldown was folded into the `test` matrix (`bundler` dimension), which `test-required-check` already depends on. |
| Native DTS — wizard hint   | DONE   | `first-run-wizard.ts:52&#x60; — the &#x2A;"falls back to rollup for DTS"* clause was removed.                                                                                                                                           |
| Native DTS lands           | DONE   | `packages/packem/src/packem/index.ts` — the rollup-DTS fallback pull-in and informational log line were removed; DTS routes through rolldown natively (PR #208).                                                                        |
| Native DTS lands (watch)   | DONE   | `packages/packem/src/rollup/watch.ts` — DTS watch under rolldown updated alongside PR #208.                                                                                                                                             |
| Wizard label (criterion 5) | DONE   | `first-run-wizard.ts:52` — `"experimental"` qualifier dropped; hint now `"fast, native DTS"`.                                                                                                                                           |

## 4. Non-goals [#4-non-goals]

The following are explicitly **out of scope** for rolldown graduation:

* **Removing the rollup backend.** Rollup remains the default and the
  full-featured path. Graduation means rolldown reaches feature parity for
  the common case, not that rollup is deprecated.
* **Rolldown-only features.** Any capability that rolldown supports but rollup
  does not (e.g., native module federation, rolldown-specific chunk semantics)
  is a separate roadmap item, not a graduation blocker.
* **Changing the rolldown version pin** (`rolldown@1.0.3` in
  `pnpm-workspace.yaml`). Version upgrades follow the normal dependency
  process; graduation criteria are feature-based, not version-based.


# API Reference (/docs/packages/pagination/api)



# API Reference [#api-reference]

## paginate() [#paginate]

Offset-based pagination.

```typescript
function paginate<T>(items: T[], options: { page: number; limit: number }): Promise<PaginationResult<T>>;
```

## cursorPaginate() [#cursorpaginate]

Cursor-based pagination.

```typescript
function cursorPaginate<T>(items: T[], options: { cursor?: string; limit: number }): Promise<CursorPaginationResult<T>>;
```

## Types [#types]

```typescript
interface PaginationResult<T> {
    data: T[];
    metadata: {
        total: number;
        page: number;
        pages: number;
        hasMore: boolean;
    };
}
```


# Introduction (/docs/packages/pagination)



# @visulima/pagination [#visulimapagination]

Flexible pagination utilities supporting both cursor-based and offset-based pagination with metadata generation.

## Key Features [#key-features]

* **Cursor Pagination** - Efficient for large datasets
* **Offset Pagination** - Traditional page-based pagination
* **Metadata** - Total count, page info, has more
* **Framework Agnostic** - Works with any framework
* **TypeScript** - Full type definitions

## Quick Start [#quick-start]

```typescript
import { paginate } from "@visulima/pagination";

const result = await paginate(query, {
    page: 1,
    limit: 10,
});

console.log(result.data);
console.log(result.metadata);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/pagination/installation">
    Install and setup
  </Card>

  <Card title="Usage" href="/docs/packages/pagination/usage">
    Pagination patterns
  </Card>

  <Card title="API" href="/docs/packages/pagination/api">
    API reference
  </Card>
</Cards>


# Installation (/docs/packages/pagination/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/pagination
```

## Import [#import]

```typescript
import { paginate, cursorPaginate } from "@visulima/pagination";
```


# Usage (/docs/packages/pagination/usage)



# Usage Guide [#usage-guide]

## Offset Pagination [#offset-pagination]

```typescript
import { paginate } from "@visulima/pagination";

const result = await paginate(items, {
    page: 1,
    limit: 20,
});

// result.data - paginated items
// result.metadata.total
// result.metadata.pages
// result.metadata.hasMore
```

## Cursor Pagination [#cursor-pagination]

```typescript
import { cursorPaginate } from "@visulima/pagination";

const result = await cursorPaginate(query, {
    cursor: "eyJpZCI6MTAwfQ==",
    limit: 20,
});

// result.data
// result.metadata.nextCursor
// result.metadata.hasMore
```

## With Prisma [#with-prisma]

```typescript
const result = await paginate(await prisma.user.findMany(), { page: 1, limit: 10 });
```


# API Reference (/docs/packages/pail/api)



# API Reference [#api-reference]

Complete API documentation for Pail.

## Core Functions [#core-functions]

### `createPail<T, L>(options?)` [#createpailt-loptions]

Creates a new Pail logger instance.

**Type Parameters:**

* `T` - Custom logger type names (default: `string`)
* `L` - Custom log level types (default: `string`)

**Parameters:**

* `options?` - Configuration options (see [Configuration](/docs/packages/pail/configuration))

**Returns:** `PailServerType<T, L>` (server) or `PailBrowserType<T, L>` (browser)

**Example:**

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevel: "debug",
    types: {
        http: { label: "HTTP", logLevel: "info" },
    },
});
```

### `pail` [#pail]

Default pre-configured logger instance.

**Example:**

```typescript
import { pail } from "@visulima/pail";

pail.info("Hello world");
```

## Logger Methods [#logger-methods]

### Logging Methods [#logging-methods]

All default log types are available as methods:

```typescript
logger.alert(message, ...args);
logger.critical(message, ...args);
logger.debug(message, ...args);
logger.emergency(message, ...args);
logger.error(message, ...args);
logger.info(message, ...args);
logger.log(message, ...args);
logger.notice(message, ...args);
logger.pending(message, ...args);
logger.start(message, ...args);
logger.stop(message, ...args);
logger.success(message, ...args);
logger.trace(message, ...args);
logger.await(message, ...args);
logger.wait(message, ...args);
logger.warn(message, ...args);
logger.warning(message, ...args);
logger.watch(message, ...args);
logger.complete(message, ...args);
```

**Parameters:**

* `message` - Message string, Error object, or Message object
* `...args` - Additional context arguments

**Example:**

```typescript
logger.info("User logged in", { userId: 123 });
logger.error(new Error("Something went wrong"));
logger.complete({
    prefix: "[task]",
    message: "Task completed",
    suffix: "(@user)",
});
```

### `scope<N>(...name: string[]): PailServerType<N, L>` [#scopenname-string-pailservertypen-l]

Creates a scoped logger instance.

**Parameters:**

* `...name` - Scope names (one or more)

**Returns:** New logger instance with scope applied

**Example:**

```typescript
const scopedLogger = logger.scope("api", "users");
scopedLogger.info("Message"); // Includes scope
```

### `unscope(): void` [#unscope-void]

Removes the current scope.

**Example:**

```typescript
logger.scope("api");
logger.unscope(); // Removes scope
```

### `time(label?: string): void` [#timelabel-string-void]

Starts a timer with the specified label.

**Parameters:**

* `label` - Timer label (default: `"default"`)

**Example:**

```typescript
logger.time("operation");
// ... work ...
logger.timeEnd("operation");
```

### `timeLog(label?: string, ...data: unknown[]): void` [#timeloglabel-string-data-unknown-void]

Logs the current elapsed time for a timer without stopping it.

**Parameters:**

* `label` - Timer label (uses last timer if not specified)
* `...data` - Additional data to include

**Example:**

```typescript
logger.time("task");
logger.timeLog("task"); // Logs current elapsed time
logger.timeEnd("task");
```

### `timeEnd(label?: string): void` [#timeendlabel-string-void]

Stops a timer and logs the final elapsed time.

**Parameters:**

* `label` - Timer label (uses last timer if not specified)

**Example:**

```typescript
logger.time("operation");
logger.timeEnd("operation"); // Logs final time
```

### `count(label?: string): void` [#countlabel-string-void]

Increments and logs a counter.

**Parameters:**

* `label` - Counter label (default: `"default"`)

**Example:**

```typescript
logger.count("requests"); // Logs: "requests: 1"
logger.count("requests"); // Logs: "requests: 2"
```

### `countReset(label?: string): void` [#countresetlabel-string-void]

Resets a counter to zero.

**Parameters:**

* `label` - Counter label (default: `"default"`)

**Example:**

```typescript
logger.count("requests");
logger.countReset("requests"); // Resets counter
```

### `group(label?: string): void` [#grouplabel-string-void]

Starts a log group.

**Parameters:**

* `label` - Group label (default: `"console.group"`)

**Example:**

```typescript
logger.group("Database Operations");
logger.info("Connecting...");
logger.info("Querying...");
logger.groupEnd();
```

### `groupEnd(): void` [#groupend-void]

Ends the current log group.

**Example:**

```typescript
logger.group("Operations");
logger.groupEnd();
```

### `disable(): void` [#disable-void]

Disables all logging output.

**Example:**

```typescript
logger.disable();
logger.info("Won't be logged");
```

### `enable(): void` [#enable-void]

Enables logging output.

**Example:**

```typescript
logger.disable();
logger.enable();
logger.info("Will be logged");
```

### `isEnabled(): boolean` [#isenabled-boolean]

Checks if logging is currently enabled.

**Returns:** `true` if enabled, `false` if disabled

**Example:**

```typescript
if (logger.isEnabled()) {
    logger.debug("Logger is active");
}
```

### `pause(): void` [#pause-void]

Pauses logging and starts queuing messages.

**Example:**

```typescript
logger.pause();
logger.info("Queued");
logger.resume(); // Messages are now output
```

### `resume(): void` [#resume-void]

Resumes logging and flushes all queued messages.

**Example:**

```typescript
logger.pause();
logger.resume(); // Queued messages are output
```

### `raw(message: string, ...arguments_: unknown[]): void` [#rawmessage-string-arguments_-unknown-void]

Logs a raw message bypassing normal processing.

**Parameters:**

* `message` - Raw message string
* `...arguments_` - Additional arguments

**Example:**

```typescript
logger.raw("Direct message", { data: "value" });
```

### `clear(): void` [#clear-void]

Clears the console/terminal output.

**Example:**

```typescript
logger.clear();
```

## Server-Only Methods [#server-only-methods]

### `wrapConsole(): void` [#wrapconsole-void]

Wraps the global console methods to redirect them through the logger.

**Example:**

```typescript
logger.wrapConsole();
console.log("Goes through logger");
logger.restoreConsole();
```

### `restoreConsole(): void` [#restoreconsole-void]

Restores the original global console methods.

**Example:**

```typescript
logger.wrapConsole();
logger.restoreConsole();
```

### `wrapStd(): void` [#wrapstd-void]

Wraps stdout and stderr streams to redirect them through the logger.

**Example:**

```typescript
logger.wrapStd();
process.stdout.write("Goes through logger");
logger.restoreStd();
```

### `restoreStd(): void` [#restorestd-void]

Restores the original stdout and stderr streams.

**Example:**

```typescript
logger.wrapStd();
logger.restoreStd();
```

### `wrapAll(): void` [#wrapall-void]

Wraps all output sources (console and streams).

**Example:**

```typescript
logger.wrapAll();
// All output goes through logger
logger.restoreAll();
```

### `restoreAll(): void` [#restoreall-void]

Restores all wrapped output sources.

**Example:**

```typescript
logger.wrapAll();
logger.restoreAll();
```

### `wrapException(): void` [#wrapexception-void]

Wraps uncaught exception and unhandled rejection handlers.

**Example:**

```typescript
logger.wrapException();
// Uncaught errors will be logged automatically
```

### `getInteractiveManager(): InteractiveManager | undefined` [#getinteractivemanager-interactivemanager--undefined]

Gets the interactive manager instance if interactive mode is enabled.

**Returns:** InteractiveManager instance or `undefined`

**Example:**

```typescript
const logger = createPail({ interactive: true });
const manager = logger.getInteractiveManager();
```

### `createProgressBar(options: SingleBarOptions): ProgressBar` [#createprogressbaroptions-singlebaroptions-progressbar]

Creates a single progress bar. Requires interactive mode.

**Parameters:**

* `options` - Progress bar configuration

**Returns:** ProgressBar instance

**Example:**

```typescript
const logger = createPail({ interactive: true });
const bar = logger.createProgressBar({ total: 100 });
bar.start();
bar.update(50);
bar.stop();
```

### `createMultiProgressBar(options?: MultiBarOptions): MultiProgressBar` [#createmultiprogressbaroptions-multibaroptions-multiprogressbar]

Creates a multi-bar progress manager. Requires interactive mode.

**Parameters:**

* `options?` - Multi-bar configuration

**Returns:** MultiProgressBar instance

**Example:**

```typescript
const logger = createPail({ interactive: true });
const multiBar = logger.createMultiProgressBar();
const bar1 = multiBar.create(100);
```

### `createSpinner(options?: SpinnerOptions): Spinner` [#createspinneroptions-spinneroptions-spinner]

Creates a single spinner. Requires interactive mode.

**Parameters:**

* `options?` - Spinner configuration

**Returns:** Spinner instance

**Example:**

```typescript
const logger = createPail({ interactive: true });
const spinner = logger.createSpinner({ name: "dots" });
spinner.start("Loading...");
spinner.succeed("Done");
```

### `createMultiSpinner(options?: SpinnerOptions): MultiSpinner` [#createmultispinneroptions-spinneroptions-multispinner]

Creates a multi-spinner manager. Requires interactive mode.

**Parameters:**

* `options?` - Spinner configuration

**Returns:** MultiSpinner instance

**Example:**

```typescript
const logger = createPail({ interactive: true });
const multiSpinner = logger.createMultiSpinner();
const spinner1 = multiSpinner.create("Loading 1");
```

## Error Classes [#error-classes]

### `PailError` [#pailerror]

Self-documenting error class with structured context fields.

**Constructor:**

```typescript
new PailError(options: PailErrorOptions | string);
```

**Properties:**

* `message` - Error message
* `status` - HTTP status code (default: `500`)
* `why` - Human-readable explanation of why the error occurred
* `fix` - Suggested fix or remediation steps
* `link` - URL to documentation or issue tracker
* `cause` - Original error that caused this error

**Methods:**

* `toJSON()` - Returns a plain object representation
* `toString()` - Returns a formatted string representation

**Example:**

```typescript
import { PailError } from "@visulima/pail";

throw new PailError({
    message: "Database connection failed",
    why: "The connection pool is exhausted",
    fix: "Increase the pool size in your database config or check for connection leaks",
    link: "https://docs.example.com/db-pool",
    status: 503,
    cause: originalError,
});
```

### `createPailError(options)` [#createpailerroroptions]

Factory function that creates a `PailError` instance.

**Parameters:**

* `options` - `PailErrorOptions | string` - Error options or message string

**Returns:** `PailError` instance

**Example:**

```typescript
import { createPailError } from "@visulima/pail";

const error = createPailError({
    message: "API rate limit exceeded",
    why: "Too many requests in the current time window",
    fix: "Implement exponential backoff or reduce request frequency",
    status: 429,
});
```

### `PailErrorOptions` [#pailerroroptions]

Options for creating a PailError.

```typescript
interface PailErrorOptions {
    message: string;
    cause?: unknown;
    fix?: string;
    link?: string;
    status?: number;
    why?: string;
}
```

## Types [#types]

### `ConstructorOptions<T, L>` [#constructoroptionst-l]

Configuration options for creating a logger.

```typescript
interface ConstructorOptions<T extends string, L extends string> {
    disabled?: boolean;
    logLevel?: LiteralUnion<ExtendedRfc5424LogLevels, L>;
    logLevels?: Partial<Record<ExtendedRfc5424LogLevels, number>> & Record<L, number>;
    messages?: {
        timerEnd?: string;
        timerStart?: string;
    };
    processors?: Processor<L>[];
    rawReporter?: Reporter<L>;
    reporters?: Reporter<L>[];
    scope?: string[] | string;
    throttle?: number;
    throttleMin?: number;
    types?: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>;
}
```

### `ServerConstructorOptions<T, L>` [#serverconstructoroptionst-l]

Server-specific configuration options.

```typescript
interface ServerConstructorOptions<T extends string, L extends string> extends ConstructorOptions<T, L> {
    interactive?: boolean;
    stderr: NodeJS.WriteStream;
    stdout: NodeJS.WriteStream;
}
```

### `ExtendedRfc5424LogLevels` [#extendedrfc5424loglevels]

Standard log levels.

```typescript
type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";
```

### `Message` [#message]

Structured message object.

```typescript
interface Message {
    context?: any[];
    message: any;
    prefix?: string;
    suffix?: string;
}
```

## Utilities [#utilities]

### `renderObjectTree(tree, options?)` [#renderobjecttreetree-options]

Renders an object as an ASCII tree structure.

**Parameters:**

* `tree` - The object or array to render
* `options?` - Configuration options (see [Object Tree Usage](/docs/packages/pail/usage/object-tree))

**Returns:** `string | string[]` - Formatted tree as string or array of lines

**Example:**

```typescript
import { renderObjectTree } from "@visulima/pail/object-tree";

const obj = {
    name: "John",
    age: 30,
    address: {
        street: "Main St",
        city: "New York",
    },
};

console.log(renderObjectTree(obj));
```

**See also:** [Object Tree Rendering](/docs/packages/pail/usage/object-tree) for detailed usage and examples.

## Related [#related]

* [Configuration](/docs/packages/pail/configuration) - Configuration guide
* [Examples](/docs/packages/pail/examples) - Usage examples
* [Object Tree Rendering](/docs/packages/pail/usage/object-tree) - Object tree utility


# Comparison (/docs/packages/pail/comparison)



# Comparison with Other Logging Libraries [#comparison-with-other-logging-libraries]

Choosing the right logging library depends on your specific needs. This guide helps you understand when Pail is the right choice compared to popular alternatives.

## Quick Comparison [#quick-comparison]

| Feature                  | Pail                                                                       | Pino   | Winston   | Consola      | TSLog  |
| ------------------------ | -------------------------------------------------------------------------- | ------ | --------- | ------------ | ------ |
| **Browser Support**      | ✅                                                                          | ❌      | ❌         | ✅            | ❌      |
| **Server Support**       | ✅                                                                          | ✅      | ✅         | ✅            | ✅      |
| **Pretty Output**        | ✅                                                                          | ❌      | ✅         | ✅            | ❌      |
| **JSON Output**          | ✅                                                                          | ✅      | ✅         | ✅            | ✅      |
| **TypeScript**           | ✅                                                                          | ✅      | ✅         | ✅            | ✅      |
| **Custom Types**         | ✅                                                                          | ❌      | ❌         | ✅            | ❌      |
| **Processors**           | ✅                                                                          | ❌      | ❌         | ❌            | ❌      |
| **Interactive Features** | ✅ Progress bars, Multi-bars, Spinners, Multi-spinners, Interactive Manager | ❌      | ❌         | ❌            | ❌      |
| **Performance**          | ⚡⚡ Very Fast                                                               | ⚡ Fast | 🐌 Slower | ⚡⚡ Very Fast | ⚡ Fast |
| **Bundle Size**          | Small                                                                      | Small  | Large     | Medium       | Medium |

## Detailed Comparisons [#detailed-comparisons]

### Pail vs Pino [#pail-vs-pino]

**Choose Pino if:**

* You're already heavily invested in Pino's ecosystem
* You need specific Pino plugins or integrations
* You prefer Pino's API style

**Choose Pail if:**

* You need browser support
* You want pretty-printed logs for development
* You need custom log types (like `http`, `db`, etc.)
* You want built-in interactive features (progress bars, multi-progress bars, spinners, multi-spinners, interactive manager)
* You need processors for data transformation
* You want a unified logging solution for both browser and server
* You want better performance - Pail is **faster than Pino** in benchmarks

**Performance:** Based on benchmarks, Pail server is **faster than Pino** across all scenarios:

* Basic logging: Pail (\~12M ops/sec) vs Pino (\~1.9M ops/sec) - **6x faster**
* Object logging: Pail (\~12M ops/sec) vs Pino (\~1.8M ops/sec) - **6.7x faster**
* Deep objects: Pail (\~12M ops/sec) vs Pino (\~79K ops/sec) - **156x faster**
* Long strings: Pail (\~12M ops/sec) vs Pino (\~175K ops/sec) - **69x faster**

Pail combines superior performance with better developer experience.

```typescript
// Pino - Fast but limited
import pino from "pino";
const logger = pino();
logger.info({ userId: 123 }, "User logged in");

// Pail - More features, still fast
import { pail } from "@visulima/pail";
pail.info("User logged in", { userId: 123 });
pail.http("GET /api/users 200"); // Custom types
```

### Pail vs Winston [#pail-vs-winston]

**Choose Winston if:**

* You need extensive third-party transport plugins
* You're migrating from an existing Winston setup
* You need specific Winston ecosystem integrations

**Choose Pail if:**

* You want a modern, TypeScript-first API
* You need browser support
* You want better performance
* You prefer a simpler, more intuitive API
* You need interactive features (progress bars, multi-progress bars, spinners, multi-spinners, interactive manager)

**Performance:** Pail is significantly faster than Winston, especially for high-volume logging scenarios.

```typescript
// Winston - More verbose
import winston from "winston";
const logger = winston.createLogger({
    transports: [new winston.transports.Console()],
});
logger.info("Message", { metadata: "value" });

// Pail - Cleaner API
import { pail } from "@visulima/pail";
pail.info("Message", { metadata: "value" });
```

### Pail vs Consola [#pail-vs-consola]

**Choose Consola if:**

* You're already using Nuxt.js (Consola is built for Nuxt)
* You need Nuxt-specific integrations
* You prefer Consola's API style

**Choose Pail if:**

* You need more advanced features (processors, custom types)
* You want better TypeScript support
* You need interactive terminal features (progress bars, multi-progress bars, spinners, multi-spinners, interactive manager)
* You want more control over output formatting
* You need RFC 5424 compliant log levels

**Performance:** Both are extremely fast. Pail is faster for object logging (\~12M vs \~11M ops/sec), while Consola has a slight edge for basic string logging. Pail offers significantly more features while maintaining comparable performance.

```typescript
// Consola - Simple and clean
import { createConsola } from "consola";
const logger = createConsola();
logger.info("Message");

// Pail - More powerful
import { pail } from "@visulima/pail";
pail.info("Message");
pail.http("GET /api/users"); // Custom types
const bar = pail.createProgressBar({ total: 100 }); // Single progress bar
const multiBar = pail.createMultiProgressBar(); // Multi-progress bars
const spinner = pail.createSpinner(); // Single spinner
const multiSpinner = pail.createMultiSpinner(); // Multi-spinners
```

### Pail vs TSLog [#pail-vs-tslog]

**Choose TSLog if:**

* You need very specific TypeScript-only features
* You prefer TSLog's type system
* You're building TypeScript-only applications

**Choose Pail if:**

* You need browser support
* You want pretty output for development
* You need custom log types
* You want progress bars and interactive features
* You need processors for data transformation

**Performance:** Both are performant, with Pail offering more features while maintaining good performance.

## Key Differentiators [#key-differentiators]

### 1. Universal Support [#1-universal-support]

Pail is one of the few logging libraries that works seamlessly in both browser and server environments with the same API:

```typescript
// Works in both browser and server
import { pail } from "@visulima/pail";
pail.info("Works everywhere!");
```

### 2. Custom Log Types [#2-custom-log-types]

Pail's custom types feature allows semantic logging that matches your domain:

```typescript
const logger = createPail({
    types: {
        http: { badge: "🌐", color: "blue", label: "HTTP", logLevel: "info" },
        db: { badge: "💾", color: "cyan", label: "DB", logLevel: "debug" },
    },
});

logger.http("GET /api/users 200");
logger.db("Query executed");
```

### 3. Processors [#3-processors]

Processors allow you to transform log data before it's output:

```typescript
import RedactProcessor from "@visulima/pail/processor/redact";
import CallerProcessor from "@visulima/pail/processor/caller";

const logger = createPail({
    processors: [
        new CallerProcessor(), // Add file/line info
        new RedactProcessor(), // Uses standard rules, or pass custom rules as first parameter
    ],
});
```

### 4. Interactive Mode [#4-interactive-mode]

Comprehensive interactive terminal features:

**Progress Bars:**

* Single progress bars (`createProgressBar`)
* Multi-progress bars (`createMultiProgressBar`) - Display multiple bars simultaneously

**Spinners:**

* Single spinners (`createSpinner`)
* Multi-spinners (`createMultiSpinner`) - Manage multiple spinners

**Interactive Manager:**

* Direct access to `InteractiveManager` for advanced control

```typescript
const logger = createPail({ interactive: true });

// Single progress bar
const bar = logger.createProgressBar({ total: 100 });
bar.start();
bar.update(50);
bar.stop();

// Multi-progress bars
const multiBar = logger.createMultiProgressBar();
const bar1 = multiBar.create(100);
const bar2 = multiBar.create(200);

// Single spinner
const spinner = logger.createSpinner({ name: "dots" });
spinner.start("Loading...");
spinner.succeed("Done");

// Multi-spinners
const multiSpinner = logger.createMultiSpinner();
const spinner1 = multiSpinner.create("Task 1");
const spinner2 = multiSpinner.create("Task 2");

// Interactive manager
const manager = logger.getInteractiveManager();
manager?.hook(); // Enable interactive mode
manager?.unhook(); // Disable interactive mode
```

### 5. Built-in Throttling [#5-built-in-throttling]

Prevent log spam automatically:

```typescript
const logger = createPail({
    throttle: 1000, // Throttle duplicate logs
    throttleMin: 5, // After 5 duplicates
});
```

## Performance Benchmarks [#performance-benchmarks]

Based on our benchmarks (see [benchmarks](https://github.com/visulima/visulima/tree/main/packages/pail/__bench__)):

### Server Performance (operations per second) [#server-performance-operations-per-second]

| Scenario           | Pail Server | Consola | Pino   | Winston |
| ------------------ | ----------- | ------- | ------ | ------- |
| **Basic logging**  | \~12.3M     | \~12.9M | \~1.9M | \~549K  |
| **Object logging** | \~12.0M     | \~11.4M | \~1.8M | \~497K  |
| **Deep objects**   | \~12.4M     | \~12.4M | \~79K  | \~19K   |
| **Long strings**   | \~12.1M     | \~12.9M | \~175K | \~71K   |

### Key Performance Insights [#key-performance-insights]

* **Pail is fastest** for object and deep object logging (tied with Consola)
* **Pail is 6-156x faster than Pino** depending on the scenario
* **Pail is 20-175x faster than Winston** across all scenarios
* **Browser performance**: Pail browser is optimized (\~1M ops/sec for basic logging)

Pail combines top-tier performance with rich features, making it an excellent choice for both development and production.

## Migration Guide [#migration-guide]

If you're migrating from another logger:

### From Pino [#from-pino]

```typescript
// Before (Pino)
pino.info({ userId: 123 }, "User logged in");

// After (Pail)
pail.info("User logged in", { userId: 123 });
```

### From Winston [#from-winston]

```typescript
// Before (Winston)
winston.info("Message", { metadata: "value" });

// After (Pail)
pail.info("Message", { metadata: "value" });
```

### From Consola [#from-consola]

```typescript
// Before (Consola)
consola.info("Message");

// After (Pail)
pail.info("Message");
```

## When to Choose Pail [#when-to-choose-pail]

Pail is ideal when you need:

* ✅ **Universal logging** - Same API for browser and server
* ✅ **Developer experience** - Pretty output, custom types, scoping
* ✅ **Advanced features** - Processors, throttling, interactive mode (progress bars, multi-bars, spinners, multi-spinners, interactive manager)
* ✅ **TypeScript** - Full type safety and IntelliSense
* ✅ **Performance** - Fast enough for production workloads
* ✅ **Flexibility** - Highly configurable and extensible

## When Not to Choose Pail [#when-not-to-choose-pail]

Consider alternatives if:

* ❌ You need **specific Winston transports** (use Winston)
* ❌ You're **migrating from Consola** in Nuxt (may be easier to stay)
* ❌ You only need **simple console.log** (use native console)
* ❌ You're already heavily invested in **Pino's ecosystem** (but note: Pail is faster!)

## Summary [#summary]

Pail offers the best combination of **top-tier performance**, **rich features**, and **excellent developer experience**. Benchmark results show:

* **6-156x faster than Pino** depending on logging scenario
* **20-175x faster than Winston** across all scenarios
* **Competitive with Consola** (fastest for object logging, tied for deep objects)
* **Universal support** for browser and server with same API

Pail is particularly strong when you need:

1. **Universal browser/server support** - Same API everywhere
2. **Top performance** - Faster than Pino, competitive with fastest loggers
3. **Rich developer experience** - Pretty output, custom types, scoping
4. **Advanced interactive features** - Progress bars, multi-progress bars, spinners, multi-spinners, and interactive manager
5. **Modern TypeScript-first API** - Full type safety

For most applications, Pail provides the optimal combination of **speed**, **power**, and **ease of use**.

## Related [#related]

* [Installation](/docs/packages/pail/installation) - Get started with Pail
* [Basic Usage](/docs/packages/pail/usage/basic) - Learn the basics
* [Performance Benchmarks](https://github.com/visulima/visulima/tree/main/packages/pail/__bench__) - See detailed benchmarks


# Log Levels (/docs/packages/pail/concepts/log-levels)



# Log Levels [#log-levels]

Pail adheres to the log levels defined in [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424) extended with a `trace` level. Each level has a numeric priority where lower numbers indicate higher severity.

## Standard Log Levels [#standard-log-levels]

### Emergency (8) [#emergency-8]

**Highest priority** - System is unusable. This should trigger immediate alerts.

```typescript
pail.emergency("System is down!");
```

### Alert (7) [#alert-7]

Action must be taken immediately. Example: Entire website down, database unavailable, etc. This should trigger SMS alerts and wake you up.

```typescript
pail.alert("Database connection lost!");
```

### Critical (6) [#critical-6]

Critical conditions. Example: Application component unavailable, unexpected exception.

```typescript
pail.critical("Failed to initialize core service");
```

### Error (5) [#error-5]

Runtime errors that do not require immediate action but should typically be logged and monitored.

```typescript
pail.error("Failed to process user request", error);
```

### Warning (4) [#warning-4]

Exceptional occurrences that are not errors. Examples: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.

```typescript
pail.warn("Using deprecated API, please update");
```

### Notice (3) [#notice-3]

Normal but significant events.

```typescript
pail.notice("User authentication successful");
```

### Informational (2) [#informational-2]

Interesting events. Examples: User logs in, SQL logs.

```typescript
pail.info("User logged in", { userId: 123 });
```

### Debug (1) [#debug-1]

Detailed debug information.

```typescript
pail.debug("Processing request", { requestId: "abc123" });
```

### Trace (2) [#trace-2]

Very detailed and fine-grained informational events. Similar to debug but even more verbose.

```typescript
pail.trace("Entering function", { functionName: "processData" });
```

## Log Level Priority [#log-level-priority]

When you set a log level, only messages at that level or higher priority will be logged. For example, if you set the log level to `warning`, you'll see:

* ✅ Emergency
* ✅ Alert
* ✅ Critical
* ✅ Error
* ✅ Warning
* ❌ Notice
* ❌ Informational
* ❌ Debug
* ❌ Trace

## Setting Log Levels [#setting-log-levels]

### Via Configuration [#via-configuration]

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevel: "warning", // Only show warning and above
});
```

### Via Environment Variable [#via-environment-variable]

```bash
PAIL_LOG_LEVEL=debug node app.js
```

### Automatic Detection [#automatic-detection]

Pail automatically detects log levels based on environment:

* **Development/Debug**: `NODE_ENV=debug` or `DEBUG=1` → `debug`
* **Test**: `NODE_ENV=test` → `warning`
* **Production**: Default → `informational`

```typescript
// Automatically uses appropriate level based on NODE_ENV
import { pail } from "@visulima/pail";
```

## Custom Log Levels [#custom-log-levels]

You can define custom log levels with numeric priorities:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevels: {
        verbose: 0, // Lower than debug
        custom: 10, // Higher than emergency
    },
    logLevel: "verbose",
});
```

## Logger Type Log Levels [#logger-type-log-levels]

Each logger type (like `success`, `error`, etc.) can have its own log level:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    types: {
        http: {
            label: "HTTP",
            color: "blue",
            logLevel: "info", // HTTP logs use 'info' level
        },
    },
});

logger.http("GET /api/users 200"); // Uses 'info' level
```

## Best Practices [#best-practices]

1. **Use appropriate levels** - Match the severity of your log messages
2. **Set production levels** - Use `informational` or `warning` in production
3. **Use debug/trace sparingly** - These are for development only
4. **Consider your audience** - What information do operators need vs. developers?

## Related [#related]

* [Configuration](/docs/packages/pail/configuration) - Learn how to configure log levels
* [Basic Usage](/docs/packages/pail/usage/basic) - See log levels in action


# Processors (/docs/packages/pail/concepts/processors)



# Processors [#processors]

Processors modify or enhance log metadata before it reaches reporters. They run in sequence and can add context, transform data, or filter information.

## Built-in Processors [#built-in-processors]

### MessageFormatterProcessor [#messageformatterprocessor]

Formats log messages using string interpolation (like `util.format`). This is added by default.

```typescript
import { createPail } from "@visulima/pail";
// MessageFormatterProcessor is included by default

const logger = createPail();

logger.info("User %s logged in", "John");
// Message is formatted: "User John logged in"
```

### CallerProcessor [#callerprocessor]

Adds caller information (filename, line number, column number) to log metadata.

```typescript
import { createPail } from "@visulima/pail";
import CallerProcessor from "@visulima/pail/processor/caller";

const logger = createPail({
    processors: [new CallerProcessor()],
});

logger.info("This message includes caller info");
// Meta includes: file, line, column
```

### RedactProcessor [#redactprocessor]

Redacts sensitive information from log messages. Requires `@visulima/redact` package.

```bash
npm install @visulima/redact
```

```typescript
import { createPail } from "@visulima/pail";
import RedactProcessor from "@visulima/pail/processor/redact";

const logger = createPail({
    processors: [
        new RedactProcessor(
            [
                // Redact patterns
                { key: "card", pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, replacement: "[REDACTED]" }, // Credit cards
                { key: "email", pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, replacement: "[EMAIL]" }, // Emails
            ],
            { exclude: [] }, // Optional options
        ),
    ],
});

logger.info("User email: user@example.com");
// Output: "User email: [EMAIL]"
```

### ErrorProcessor [#errorprocessor]

Serializes error objects with cause chains to a standard format that can be serialized.

```typescript
import { createPail } from "@visulima/pail";
// ErrorProcessor would be added if available

logger.error(new Error("Something went wrong"));
// Error is properly serialized with stack trace
```

### SamplingProcessor [#samplingprocessor]

Controls log volume in production by implementing head sampling (random per-level) and tail sampling (force-keep based on conditions).

```typescript
import { createPail } from "@visulima/pail";
import SamplingProcessor from "@visulima/pail/processor/sampling";

const logger = createPail({
    processors: [
        new SamplingProcessor({
            // Head sampling: random percentage per level
            head: {
                debug: 0, // Drop all debug logs
                informational: 10, // Keep 10% of info logs
                warning: 50, // Keep 50% of warnings
                error: 100, // Keep all errors
            },
            // Tail sampling: force-keep based on conditions
            tail: [
                // Always keep logs with errors
                (meta) => meta.error !== undefined,
                // Always keep logs from payment scope
                (meta) => meta.scope?.includes("payment") ?? false,
            ],
        }),
    ],
});

logger.info("Most of these will be dropped"); // 90% dropped
logger.error("All errors are kept"); // 100% kept
```

Head sampling is evaluated first for broad volume control. Tail sampling can then override to force-keep important logs regardless of head sampling decisions.

### EnvironmentProcessor [#environmentprocessor]

Automatically detects and adds runtime environment information to log metadata. Reads from environment variables used by popular hosting platforms (Vercel, AWS, GCP, Fly.io, Railway, Render, Heroku, Cloudflare).

```typescript
import { createPail } from "@visulima/pail";
import EnvironmentProcessor from "@visulima/pail/processor/environment";

const logger = createPail({
    processors: [
        new EnvironmentProcessor({
            // Optional: override auto-detected values
            overrides: { service: "my-api" },
            // Optional: include process ID and hostname
            includePid: true,
            includeHostname: true,
        }),
    ],
});

logger.info("Server started");
// Meta includes: { __env: { service: "my-api", environment: "production", version: "1.2.3", ... } }
```

Auto-detected fields include:

* `service` - From `SERVICE_NAME`, `APP_NAME`, or platform variables
* `version` - From `APP_VERSION` or `npm_package_version`
* `environment` - From `NODE_ENV`, `ENVIRONMENT`, or `APP_ENV`
* `region` - From `AWS_REGION`, `VERCEL_REGION`, `FLY_REGION`, etc.
* `commit` - From `COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, etc. (truncated to 7 chars)

## Processor Order [#processor-order]

Processors run in the order they are added:

```typescript
const logger = createPail({
  processors: [
    new CallerProcessor(),      // 1. Add caller info
    new RedactProcessor(...),   // 2. Redact sensitive data
    // Processors run sequentially
  ],
});
```

## Creating Custom Processors [#creating-custom-processors]

Implement the `Processor` interface:

```typescript
import type { Processor, Meta } from "@visulima/pail";

class TimestampProcessor<L extends string = string> implements Processor<L> {
    public process(meta: Meta<L>): Meta<L> {
        return {
            ...meta,
            timestamp: Date.now(), // Add custom field
        };
    }
}

const logger = createPail({
    processors: [new TimestampProcessor()],
});
```

### Stringify-Aware Processor [#stringify-aware-processor]

If your processor needs to serialize objects:

```typescript
import type { StringifyAwareProcessor, Meta } from "@visulima/pail";

class SerializationProcessor<L extends string = string> implements StringifyAwareProcessor<L> {
    private stringify: typeof JSON.stringify | undefined;

    public setStringify(stringify: typeof JSON.stringify): void {
        this.stringify = stringify;
    }

    public process(meta: Meta<L>): Meta<L> {
        // Use this.stringify for serialization
        return meta;
    }
}
```

## Example: Request ID Processor [#example-request-id-processor]

Add request IDs to all logs:

```typescript
import type { Processor, Meta } from "@visulima/pail";

class RequestIdProcessor<L extends string = string> implements Processor<L> {
    private requestId: string;

    public constructor(requestId: string) {
        this.requestId = requestId;
    }

    public process(meta: Meta<L>): Meta<L> {
        return {
            ...meta,
            context: [...(meta.context || []), { requestId: this.requestId }],
        };
    }
}

// Use in request handler
const logger = createPail({
    processors: [new RequestIdProcessor(req.id)],
});
```

## Example: Environment Processor [#example-environment-processor]

For environment information, use the built-in `EnvironmentProcessor` (see [above](#environmentprocessor)). For custom environment data beyond what is auto-detected:

```typescript
import type { Processor, Meta } from "@visulima/pail";
import EnvironmentProcessor from "@visulima/pail/processor/environment";

const logger = createPail({
    processors: [
        new EnvironmentProcessor({
            overrides: {
                service: "my-custom-service",
                version: "2.0.0",
            },
        }),
    ],
});
```

## Processor Best Practices [#processor-best-practices]

1. **Keep processors focused** - Each processor should do one thing well
2. **Maintain immutability** - Return new objects, don't mutate input
3. **Consider performance** - Processors run for every log message
4. **Order matters** - Place processors in logical order
5. **Type safety** - Use TypeScript for better processor development

## Related [#related]

* [Reporters](/docs/packages/pail/concepts/reporters) - Learn about output destinations
* [Configuration](/docs/packages/pail/configuration) - Configure processors
* [API Reference](/docs/packages/pail/api) - Complete processor API


# Reporters (/docs/packages/pail/concepts/reporters)



# Reporters [#reporters]

Reporters are responsible for writing log messages to various destinations. They receive processed log metadata and format it for output.

## Built-in Reporters [#built-in-reporters]

### JsonReporter [#jsonreporter]

Outputs structured JSON logs. Available for both browser and server.

**Server:**

```typescript
import { createPail } from "@visulima/pail";
import { JsonReporter } from "@visulima/pail/reporter/json";

const logger = createPail({
    reporters: [new JsonReporter()],
});

logger.info("Server started", { port: 3000 });
// Output: {"type":{"name":"info","level":"informational"},"message":"Server started","context":[{"port":3000}],"date":"2024-01-01T12:00:00.000Z"}
```

**Browser:**

```typescript
import { createPail } from "@visulima/pail/browser";
import { JsonReporter } from "@visulima/pail/reporter/json";

const logger = createPail({
    reporters: [new JsonReporter()],
});
```

### PrettyReporter [#prettyreporter]

Beautiful formatted console output with colors and styling. Available for both browser and server.

**Server:**

```typescript
import { createPail } from "@visulima/pail";
import { PrettyReporter } from "@visulima/pail/reporter/pretty";

const logger = createPail({
    reporters: [new PrettyReporter()],
});

logger.success("Operation completed");
// Output: ✓ success Operation completed
```

**Browser:**

```typescript
import { createPail } from "@visulima/pail/browser";
import { PrettyReporter } from "@visulima/pail/reporter/pretty";

const logger = createPail({
    reporters: [new PrettyReporter()],
});
```

### SimpleReporter [#simplereporter]

Simple formatted output with error inspection. &#x2A;*Server only.**

```typescript
import { createPail } from "@visulima/pail";
import { SimpleReporter } from "@visulima/pail/reporter/simple";

const logger = createPail({
    reporters: [new SimpleReporter()],
});
```

### FileReporter (JsonFileReporter) [#filereporter-jsonfilereporter]

Writes logs to rotating files. &#x2A;*Server only.** Requires `rotating-file-stream` package.

```typescript
import { createPail } from "@visulima/pail";
import { JsonFileReporter } from "@visulima/pail/reporter/file";

const logger = createPail({
    reporters: [
        new JsonFileReporter({
            filePath: "/var/log/app.log",
            interval: "1d", // Rotate daily
            size: "10M", // Rotate when file reaches 10MB
            compress: "gzip",
        }),
    ],
});
```

## Reporter Comparison [#reporter-comparison]

| Reporter         | Browser | Server | Output Format  | Use Case                            |
| ---------------- | ------- | ------ | -------------- | ----------------------------------- |
| `JsonReporter`   | ✅       | ✅      | JSON           | Structured logging, log aggregation |
| `PrettyReporter` | ✅       | ✅      | Formatted text | Development, debugging              |
| `SimpleReporter` | ❌       | ✅      | Simple text    | Minimal output                      |
| `FileReporter`   | ❌       | ✅      | JSON files     | Production logging                  |

## Using Multiple Reporters [#using-multiple-reporters]

You can use multiple reporters simultaneously:

```typescript
import { createPail } from "@visulima/pail";
import { JsonReporter } from "@visulima/pail/reporter/json";
import { PrettyReporter } from "@visulima/pail/reporter/pretty";
import { JsonFileReporter } from "@visulima/pail/reporter/file";

const logger = createPail({
    reporters: [
        new PrettyReporter(), // Console output
        new JsonFileReporter({ filePath: "./logs/app.log" }), // File output
    ],
});

logger.info("Message"); // Sent to both reporters
```

## Creating Custom Reporters [#creating-custom-reporters]

Implement the `Reporter` interface:

```typescript
import type { Reporter, ReadonlyMeta } from "@visulima/pail";

class CustomReporter<L extends string = string> implements Reporter<L> {
    public log(meta: ReadonlyMeta<L>): void {
        // Your custom logic here
        console.log(`[${meta.type.name}] ${meta.message}`);
    }
}

const logger = createPail({
    reporters: [new CustomReporter()],
});
```

### Stream-Aware Reporter (Server) [#stream-aware-reporter-server]

For server-side reporters that need stdout/stderr:

```typescript
import type { StreamAwareReporter } from "@visulima/pail";

class StreamReporter<L extends string = string> implements StreamAwareReporter<L> {
    #stdout: NodeJS.WriteStream;
    #stderr: NodeJS.WriteStream;

    public setStdout(stdout: NodeJS.WriteStream): void {
        this.#stdout = stdout;
    }

    public setStderr(stderr: NodeJS.WriteStream): void {
        this.#stderr = stderr;
    }

    public log(meta: ReadonlyMeta<L>): void {
        const stream = meta.type.level === "error" ? this.#stderr : this.#stdout;
        stream.write(`${JSON.stringify(meta)}\n`);
    }
}
```

### Logger Types Aware Reporter [#logger-types-aware-reporter]

To customize output based on logger types:

```typescript
import type { LoggerTypesAwareReporter, LoggerTypesConfig } from "@visulima/pail";

class TypesAwareReporter<T extends string, L extends string = string> implements LoggerTypesAwareReporter<T, L> {
    private types: LoggerTypesConfig<T, L> = {};

    public setLoggerTypes(types: LoggerTypesConfig<T, L>): void {
        this.types = types;
    }

    public log(meta: ReadonlyMeta<L>): void {
        const typeConfig = this.types[meta.type.name];
        // Use typeConfig for custom formatting
    }
}
```

## Reporter Options [#reporter-options]

### JsonReporter Options [#jsonreporter-options]

```typescript
import { JsonReporter } from "@visulima/pail/reporter/json";

new JsonReporter({
    error: {
        // Error serialization options
        includeStack: true,
        includeCause: true,
    },
});
```

### PrettyReporter Options [#prettyreporter-options]

```typescript
import { PrettyReporter } from "@visulima/pail/reporter/pretty";

new PrettyReporter({
    uppercase: {
        label: true, // Uppercase labels
    },
    bold: {
        label: false,
    },
    underline: {
        label: false,
        message: false,
    },
});
```

### FileReporter Options [#filereporter-options]

```typescript
import { JsonFileReporter } from "@visulima/pail/reporter/file";

new JsonFileReporter({
    filePath: "./logs/app.log",
    interval: "1d", // Daily rotation
    size: "10M", // Rotate at 10MB
    compress: "gzip", // Compress old files
    writeImmediately: false, // Buffer writes
});
```

## Raw Reporter [#raw-reporter]

The raw reporter bypasses normal processing and is used internally for direct output:

```typescript
const logger = createPail({
    rawReporter: new CustomRawReporter(),
});

logger.raw("Direct message"); // Uses rawReporter
```

## Related [#related]

* [Processors](/docs/packages/pail/concepts/processors) - Learn about log processors
* [Configuration](/docs/packages/pail/configuration) - Configure reporters
* [API Reference](/docs/packages/pail/api) - Complete reporter API


# Configuration (/docs/packages/pail/configuration)



# Configuration [#configuration]

Pail is highly configurable. This guide covers all configuration options.

## Basic Configuration [#basic-configuration]

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevel: "debug",
    scope: "my-module",
    disabled: false,
});
```

## Configuration Options [#configuration-options]

### Log Level [#log-level]

Set the minimum log level to display:

```typescript
const logger = createPail({
    logLevel: "warning", // Only show warning and above
});
```

**Default:** Automatically detected based on environment:

* `NODE_ENV=debug` or `DEBUG=1` → `debug`
* `NODE_ENV=test` → `warning`
* Otherwise → `informational`

**Environment Variable:** `PAIL_LOG_LEVEL=debug`

### Custom Log Levels [#custom-log-levels]

Define custom log levels with numeric priorities:

```typescript
const logger = createPail({
    logLevels: {
        verbose: 0, // Lower than debug
        custom: 10, // Higher than emergency
    },
    logLevel: "verbose",
});
```

### Scope [#scope]

Set initial scope for the logger:

```typescript
const logger = createPail({
    scope: "api", // Single scope
    // or
    scope: ["api", "users"], // Multiple scopes
});
```

### Disabled [#disabled]

Disable logging entirely:

```typescript
const logger = createPail({
    disabled: true, // All logs are ignored
});
```

### Throttling [#throttling]

Configure spam prevention:

```typescript
const logger = createPail({
    throttle: 1000, // Throttle window in ms (default: 1000)
    throttleMin: 5, // Minimum duplicates before throttling (default: 5)
});
```

Throttling prevents the same log message from being repeated too frequently.

### Timer Messages [#timer-messages]

Customize timer messages:

```typescript
const logger = createPail({
    messages: {
        timerStart: "Starting timer...",
        timerEnd: "Completed in:",
    },
});
```

### Reporters [#reporters]

Configure output destinations:

```typescript
import { PrettyReporter } from "@visulima/pail/reporter/pretty";
import { JsonReporter } from "@visulima/pail/reporter/json";

const logger = createPail({
    reporters: [new PrettyReporter(), new JsonReporter()],
});
```

### Processors [#processors]

Add processors to modify log metadata:

```typescript
import CallerProcessor from "@visulima/pail/processor/caller";
import RedactProcessor from "@visulima/pail/processor/redact";

const logger = createPail({
    processors: [
        new CallerProcessor(),
        new RedactProcessor(), // Uses standard rules, or pass custom rules: new RedactProcessor(rules, options),
    ],
});
```

### Custom Types [#custom-types]

Define custom log types:

```typescript
const logger = createPail({
    types: {
        http: {
            badge: "🌐",
            color: "blue",
            label: "HTTP",
            logLevel: "info",
        },
    },
});
```

### Raw Reporter [#raw-reporter]

Configure the raw reporter (for `logger.raw()`):

```typescript
import { RawReporter } from "@visulima/pail";

const logger = createPail({
    rawReporter: new CustomRawReporter(),
});
```

## Server-Specific Options [#server-specific-options]

### Interactive Mode [#interactive-mode]

Enable interactive features (progress bars, spinners):

```typescript
const logger = createPail({
    interactive: true,
});
```

### Streams [#streams]

Customize stdout/stderr streams:

```typescript
import { createPail } from "@visulima/pail";
import { stderr, stdout } from "node:process";

const logger = createPail({
    stdout: customStdout,
    stderr: customStderr,
});
```

## Complete Configuration Example [#complete-configuration-example]

```typescript
import { createPail } from "@visulima/pail";
import { PrettyReporter } from "@visulima/pail/reporter/pretty";
import { CallerProcessor } from "@visulima/pail/processor/caller";

const logger = createPail({
    // Log level
    logLevel: process.env.NODE_ENV === "production" ? "info" : "debug",

    // Scope
    scope: ["app", "api"],

    // Throttling
    throttle: 2000,
    throttleMin: 10,

    // Custom types
    types: {
        http: {
            badge: "🌐",
            color: "blue",
            label: "HTTP",
            logLevel: "info",
        },
        db: {
            badge: "💾",
            color: "cyan",
            label: "DB",
            logLevel: "debug",
        },
    },

    // Reporters
    reporters: [
        new PrettyReporter({
            uppercase: { label: true },
        }),
    ],

    // Processors
    processors: [new CallerProcessor()],

    // Timer messages
    messages: {
        timerStart: "⏱️  Started:",
        timerEnd: "✅ Completed in:",
    },

    // Server-specific
    interactive: true,
});
```

## Environment-Based Configuration [#environment-based-configuration]

Create different configurations for different environments:

```typescript
const isDevelopment = process.env.NODE_ENV === "development";
const isProduction = process.env.NODE_ENV === "production";

const logger = createPail({
    logLevel: isDevelopment ? "debug" : "info",
    reporters: isProduction
        ? [new JsonReporter()] // Structured logs in production
        : [new PrettyReporter()], // Pretty output in development
    processors: isProduction ? [new RedactProcessor(), new CallerProcessor()] : [new CallerProcessor()],
});
```

## TypeScript Configuration [#typescript-configuration]

For TypeScript projects, define custom types:

```typescript
type CustomLogTypes = "http" | "db" | "cache";
type CustomLogLevels = "verbose" | "custom";

const logger = createPail<CustomLogTypes, CustomLogLevels>({
    types: {
        http: { label: "HTTP", logLevel: "info" },
        db: { label: "DB", logLevel: "debug" },
        cache: { label: "CACHE", logLevel: "debug" },
    },
    logLevels: {
        verbose: 0,
        custom: 10,
    },
});
```

## Related [#related]

* [API Reference](/docs/packages/pail/api) - Complete API documentation
* [Examples](/docs/packages/pail/examples) - Configuration examples


# Examples (/docs/packages/pail/examples)



# Examples [#examples]

Real-world examples demonstrating how to use Pail in various scenarios.

## Express.js API Server [#expressjs-api-server]

```typescript
import express from "express";
import { createPail } from "@visulima/pail";
import { PrettyReporter } from "@visulima/pail/reporter/pretty";
import CallerProcessor from "@visulima/pail/processor/caller";

const logger = createPail({
    scope: "api",
    types: {
        http: {
            badge: "🌐",
            color: "blue",
            label: "HTTP",
            logLevel: "info",
        },
    },
    reporters: [new PrettyReporter()],
    processors: [new CallerProcessor()],
});

const app = express();

// Request logging middleware
app.use((req, res, next) => {
    const requestId = req.headers["x-request-id"] || `req-${Date.now()}`;
    const requestLogger = logger.scope("request", requestId);
    req.logger = requestLogger;

    requestLogger.http(`${req.method} ${req.path}`);

    const start = Date.now();
    res.on("finish", () => {
        const duration = Date.now() - start;
        requestLogger.http(`${req.method} ${req.path} ${res.statusCode}`, {
            duration: `${duration}ms`,
        });
    });

    next();
});

app.get("/users", async (req, res) => {
    req.logger.time("query");
    const users = await db.query("SELECT * FROM users");
    req.logger.timeEnd("query");

    res.json(users);
});

app.listen(3000, () => {
    logger.info("Server started on port 3000");
});
```

## Next.js Application [#nextjs-application]

```typescript
// lib/logger.ts
import { createPail } from "@visulima/pail";

export const logger = createPail({
    scope: "nextjs",
    logLevel: process.env.NODE_ENV === "production" ? "info" : "debug",
});

// app/api/users/route.ts
import { logger } from "@/lib/logger";

export async function GET() {
    const apiLogger = logger.scope("api", "users");

    apiLogger.info("Fetching users");

    try {
        const users = await fetchUsers();
        apiLogger.success(`Fetched ${users.length} users`);
        return Response.json(users);
    } catch (error) {
        apiLogger.error("Failed to fetch users", error);
        return Response.json({ error: "Failed to fetch users" }, { status: 500 });
    }
}
```

## CLI Tool with Progress Bars [#cli-tool-with-progress-bars]

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    interactive: true,
    scope: "cli",
});

const processFiles = async (files: string[]) => {
    const multiBar = logger.createMultiProgressBar();

    const uploadBar = multiBar.create(files.length, 0, {
        format: "Uploading [{bar}] {percentage}% | {value}/{total} files",
    });

    const processBar = multiBar.create(files.length, 0, {
        format: "Processing [{bar}] {percentage}% | {value}/{total} files",
    });

    uploadBar.start();
    processBar.start();

    for (let i = 0; i < files.length; i++) {
        await uploadFile(files[i]);
        uploadBar.update(i + 1);

        await processFile(files[i]);
        processBar.update(i + 1);
    }

    multiBar.stop();
    logger.success(`Processed ${files.length} files`);
};
```

## Background Job Processor [#background-job-processor]

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    types: {
        job: {
            badge: "⚙️",
            color: "cyan",
            label: "JOB",
            logLevel: "info",
        },
        jobStart: {
            badge: "▶️",
            color: "green",
            label: "JOB_START",
            logLevel: "info",
        },
        jobComplete: {
            badge: "✅",
            color: "greenBright",
            label: "JOB_COMPLETE",
            logLevel: "info",
        },
        jobError: {
            badge: "❌",
            color: "red",
            label: "JOB_ERROR",
            logLevel: "error",
        },
    },
});

const processJob = async (jobId: string) => {
    const jobLogger = logger.scope("job", jobId);

    jobLogger.jobStart("Starting job", { jobId });

    try {
        jobLogger.job("Processing step 1");
        await step1();

        jobLogger.job("Processing step 2");
        await step2();

        jobLogger.jobComplete("Job completed", { jobId });
    } catch (error) {
        jobLogger.jobError("Job failed", error);
        throw error;
    }
};
```

## Database Logger [#database-logger]

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    types: {
        db: {
            badge: "💾",
            color: "cyan",
            label: "DATABASE",
            logLevel: "debug",
        },
        dbQuery: {
            badge: "🔍",
            color: "blueBright",
            label: "QUERY",
            logLevel: "debug",
        },
        dbError: {
            badge: "❌",
            color: "red",
            label: "DB_ERROR",
            logLevel: "error",
        },
    },
});

// Database wrapper
const db = {
    async query(sql: string, params?: any[]) {
        logger.dbQuery(sql, { params });
        logger.time("query");

        try {
            const result = await dbClient.query(sql, params);
            logger.timeEnd("query");
            return result;
        } catch (error) {
            logger.dbError("Query failed", error);
            logger.timeEnd("query");
            throw error;
        }
    },
};
```

## Production Logging Setup [#production-logging-setup]

```typescript
import { createPail } from "@visulima/pail";
import { JsonReporter } from "@visulima/pail/reporter/json";
import { JsonFileReporter } from "@visulima/pail/reporter/file";
import RedactProcessor from "@visulima/pail/processor/redact";
import CallerProcessor from "@visulima/pail/processor/caller";
import SamplingProcessor from "@visulima/pail/processor/sampling";
import EnvironmentProcessor from "@visulima/pail/processor/environment";

const logger = createPail({
    logLevel: process.env.PAIL_LOG_LEVEL || "info",
    reporters: [
        new JsonReporter(), // Console output (for log aggregation)
        new JsonFileReporter({
            filePath: "/var/log/app.log",
            interval: "1d",
            size: "100M",
            compress: "gzip",
        }),
    ],
    processors: [
        new CallerProcessor(),
        new RedactProcessor(
            [
                // Redact credit cards
                { key: "card", pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, replacement: "[CARD]" },
                // Redact emails
                { key: "email", pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, replacement: "[EMAIL]" },
                // Redact SSNs
                { key: "ssn", pattern: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: "[SSN]" },
            ],
            { exclude: [] }, // Optional options
        ),
        // Sample debug logs at 10%, keep all errors
        new SamplingProcessor({
            debug: 10,
            trace: 5,
        }),
        // Auto-detect runtime environment
        new EnvironmentProcessor({
            includePid: true,
            includeHostname: true,
        }),
    ],
});
```

## Self-Documenting Errors [#self-documenting-errors]

```typescript
import { createPail, PailError, createPailError } from "@visulima/pail";

const logger = createPail();

// Throw errors with actionable context
try {
    const config = loadConfig();
} catch (error) {
    throw new PailError({
        message: "Failed to load configuration",
        why: "The config file is missing or malformed",
        fix: "Create a config.json file in the project root, or set the CONFIG_PATH environment variable",
        link: "https://docs.example.com/configuration",
        status: 500,
        cause: error,
    });
}

// Use the factory function for convenience
const error = createPailError({
    message: "API rate limit exceeded",
    why: "Too many requests in the current time window",
    fix: "Implement exponential backoff or reduce request frequency",
    status: 429,
});

// PailError serializes cleanly to JSON
logger.error(error);
// JSON output includes why, fix, link fields for easy debugging
```

## React Component Logger [#react-component-logger]

```typescript
// hooks/useLogger.ts
import { useEffect, useRef } from "react";
import { pail } from "@visulima/pail";

export const useLogger = (componentName: string) => {
  const loggerRef = useRef(pail.scope("component", componentName));

  useEffect(() => {
    loggerRef.current.info("Component mounted");

    return () => {
      loggerRef.current.info("Component unmounted");
    };
  }, []);

  return loggerRef.current;
};

// components/UserProfile.tsx
import { useLogger } from "@/hooks/useLogger";

export const UserProfile = ({ userId }: { userId: string }) => {
  const logger = useLogger("UserProfile");

  useEffect(() => {
    logger.debug("Loading user", { userId });
    // ... load user
  }, [userId]);

  return <div>...</div>;
};
```

## Error Tracking Integration [#error-tracking-integration]

```typescript
import { createPail } from "@visulima/pail";
import { JsonReporter } from "@visulima/pail/reporter/json";

class ErrorTrackingReporter implements Reporter {
    public log(meta: ReadonlyMeta) {
        if (meta.type.level === "error" || meta.type.level === "critical") {
            // Send to error tracking service
            errorTrackingService.captureError(meta.error || meta.message, {
                level: meta.type.level,
                context: meta.context,
                scope: meta.scope,
            });
        }
    }
}

const logger = createPail({
    reporters: [new JsonReporter(), new ErrorTrackingReporter()],
});
```

## Testing Setup [#testing-setup]

```typescript
// test/setup.ts
import { createPail } from "@visulima/pail";

// Disable logging in tests by default
export const testLogger = createPail({
    disabled: process.env.DEBUG !== "1",
    logLevel: "warning", // Only show warnings and errors
});

// Enable for specific tests
export const enableTestLogging = () => {
    testLogger.enable();
    // Note: logLevel cannot be changed after creation.
    // Create a new logger if you need a different log level.
};
```

## Related [#related]

* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations
* [Configuration](/docs/packages/pail/configuration) - Configuration options


# Introduction (/docs/packages/pail)





Pail is a powerful, flexible logging library for Node.js, Edge, and Browser environments. It gives you structured logging with pretty or JSON output, scoped loggers, built-in timers, and a pluggable processor/reporter architecture — all with full TypeScript support.

## Features at a Glance [#features-at-a-glance]

* **Structured and pretty output** — JSON, formatted console, simple text, and rotating file reporters
* **Pluggable architecture** — Custom processors and reporters to fit any workflow
* **Scoped loggers and timers** — Organize logs by context with built-in performance timing
* **Interactive terminal UI** — Progress bars, spinners, and interactive managers
* **Production-ready** — Log sampling, throttling, sensitive data redaction, and environment detection
* **Wide events and framework middleware** — Request-scoped logging for Express, Fastify, Hono, Elysia, SvelteKit, and Next.js
* **Cross-platform** — Works in Node.js, Bun, Edge runtimes, and browsers (ESM-only, Node.js ≥ 20.19)

## Quick Start [#quick-start]

```bash
npm i @visulima/pail
```

```typescript
import { pail } from "@visulima/pail";

pail.success("Operation successful");
pail.debug("Hello", "from", "L59");
pail.pending("Write release notes for %s", "1.2.0");
pail.critical(new Error("Unable to acquire lock"));
```

## Core Concepts [#core-concepts]

Pail is built around three pillars: **log levels** following [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424) (extended with `trace`), **reporters** that write to different destinations (console, files, JSON), and **processors** that enrich or transform log metadata before it reaches reporters.

<Callout title="Extensible by design">
  Every part of the pipeline — from message formatting to output — can be replaced or extended with your own processors and reporters. See the [Processors
  guide](/docs/packages/pail/concepts/processors) to get started.
</Callout>

## What's Next? [#whats-next]

<Cards>
  <Card title="Installation" description="Set up Pail in your project" href="/docs/packages/pail/installation" />

  <Card title="Basic Usage" description="Start logging with simple examples" href="/docs/packages/pail/usage/basic" />

  <Card title="Wide Events" description="Structured request-scoped logging" href="/docs/packages/pail/usage/wide-events" />

  <Card title="Framework Middleware" description="Auto-logging for Express, Fastify, Hono, and more" href="/docs/packages/pail/middleware/overview" />

  <Card title="Configuration" description="Customize Pail to your needs" href="/docs/packages/pail/configuration" />

  <Card title="Comparison" description="How Pail compares to Pino, Winston, Consola" href="/docs/packages/pail/comparison" />

  <Card title="API Reference" description="Complete API documentation" href="/docs/packages/pail/api" />
</Cards>


# Installation (/docs/packages/pail/installation)



# Installation [#installation]

Pail is available as an npm package and can be installed using your preferred package manager.

## Package Managers [#package-managers]

### npm [#npm]

```bash
npm install @visulima/pail
```

### yarn [#yarn]

```bash
yarn add @visulima/pail
```

### pnpm [#pnpm]

```bash
pnpm add @visulima/pail
```

## Requirements [#requirements]

* **Node.js**: 20.19 or higher, up to 25.x
* **TypeScript**: Optional but recommended for full type safety

## Environment Support [#environment-support]

Pail supports:

* **Node.js** (CommonJS and ESM)
* **Edge Runtime** (Cloudflare Workers, Vercel Edge, etc.)
* **Browser** (Modern browsers with ES module support)

## Optional Dependencies [#optional-dependencies]

Some features require optional peer dependencies:

### Redact Processor [#redact-processor]

For sensitive data redaction:

```bash
npm install @visulima/redact
# or
yarn add @visulima/redact
# or
pnpm add @visulima/redact
```

### File Reporter [#file-reporter]

For file-based logging (server only):

```bash
npm install rotating-file-stream
# or
yarn add rotating-file-stream
# or
pnpm add rotating-file-stream
```

## Import Methods [#import-methods]

### Server (Node.js) [#server-nodejs]

```typescript
import { pail, createPail } from "@visulima/pail";
// or
import { pail, createPail } from "@visulima/pail/server";
```

### Browser [#browser]

```typescript
import { pail, createPail } from "@visulima/pail/browser";
```

### Auto-detection [#auto-detection]

```typescript
import { pail, createPail } from "@visulima/pail";
```

The default import automatically selects the appropriate implementation based on your environment.

## TypeScript Support [#typescript-support]

Pail is written in TypeScript and provides full type definitions. No additional type packages are required.

```typescript
import type { Pail, LoggerFunction } from "@visulima/pail";
```

## Verify Installation [#verify-installation]

After installation, verify that Pail is working correctly:

```typescript
import { pail } from "@visulima/pail";

pail.info("Pail is installed and working!");
```

If you see the log message, installation was successful!

## Next Steps [#next-steps]

* [Basic Usage](/docs/packages/pail/usage/basic) - Learn how to use Pail
* [Configuration](/docs/packages/pail/configuration) - Configure Pail for your needs


# Elysia (/docs/packages/pail/middleware/elysia)



# Elysia Plugin [#elysia-plugin]

The Elysia adapter uses `derive` to inject a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) into every handler's context. The event auto-emits on response or error.

## Setup [#setup]

```typescript
import { Elysia } from "elysia";
import { createPail } from "@visulima/pail";
import { pailPlugin } from "@visulima/pail/middleware/elysia";

const logger = createPail();
const app = new Elysia();

pailPlugin(app, { pail: logger });

app.listen(3000);
```

## Accessing the Logger [#accessing-the-logger]

### Via `context.log` (auto-injected) [#via-contextlog-auto-injected]

The `log` property is injected into every handler context via Elysia's `derive`:

```typescript
app.get("/api/users", ({ log }) => {
    log.set({ user: { id: 1 } });
    log.info("Fetched user list");
    return { ok: true };
});
```

### Via `useLogger()` [#via-uselogger]

Access the logger from anywhere in the async call stack using `AsyncLocalStorage`:

```typescript
import { useLogger } from "@visulima/pail/middleware/elysia";

async function fetchUser(id: number) {
    const log = useLogger();
    log.set({ user: { id } });
    log.info("Querying database");
    // ...
}
```

## How It Works [#how-it-works]

The plugin registers three Elysia hooks (all with `as: "global"`):

1. **`derive`** — Creates a `WideEvent`, stores it in `AsyncLocalStorage` via `enterWith()`, and returns `{ log: logger }` to inject into context
2. **`onAfterHandle`** — Emits the event with the response status (defaults to 200)
3. **`onError`** — Emits the event with the error

A `WeakSet` tracks emitted requests to prevent double-emission if both hooks fire.

## Error Handling [#error-handling]

Errors are automatically captured by the `onError` hook:

```typescript
app.get("/api/fail", ({ log }) => {
    log.set({ user: { id: 1 } });
    throw new Error("Something went wrong");
    // Wide event emits with error via onError hook
});
```

## Route Configuration [#route-configuration]

```typescript
pailPlugin(app, {
    pail: logger,
    service: "api-gateway",
    exclude: ["/health", "/metrics"],
    include: ["/api/**"],
    routes: {
        "/api/auth/**": { service: "auth-service" },
    },
});
```

## TypeScript [#typescript]

```typescript
import type { PailElysiaInstance } from "@visulima/pail/middleware/elysia";
```

## Exported Types [#exported-types]

| Export                | Description                               |
| --------------------- | ----------------------------------------- |
| `pailPlugin`          | Register the plugin on an Elysia instance |
| `useLogger`           | Retrieve logger from `AsyncLocalStorage`  |
| `PailElysiaInstance`  | Elysia instance type with derive/hook API |
| `ElysiaPluginOptions` | Options type for `pailPlugin()`           |
| `WideEvent`           | Re-exported `WideEvent` class             |


# Express (/docs/packages/pail/middleware/express)



# Express Middleware [#express-middleware]

The Express adapter attaches a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) to every request. The event auto-emits when the response finishes.

## Setup [#setup]

```typescript
import express from "express";
import { createPail } from "@visulima/pail";
import { pailMiddleware } from "@visulima/pail/middleware/express";

const app = express();
const logger = createPail();

app.use(pailMiddleware({ pail: logger }));
```

## Accessing the Logger [#accessing-the-logger]

### Via `req.log` [#via-reqlog]

```typescript
app.get("/api/users", (req, res) => {
    req.log.set({ user: { id: 1 } });
    req.log.info("Fetched user list");
    res.json({ ok: true });
});
```

### Via `useLogger()` [#via-uselogger]

Access the logger from anywhere in the async call stack — no need to pass `req` around:

```typescript
import { useLogger } from "@visulima/pail/middleware/express";

// In a service function:
async function processOrder(orderId: number) {
    const log = useLogger();
    log.set({ order: { id: orderId } });
    log.info("Processing order");
    // ...
}
```

```typescript
app.post("/api/orders", async (req, res) => {
    req.log.set({ user: { id: req.userId } });
    await processOrder(req.body.orderId); // useLogger() works here
    res.json({ ok: true });
});
```

## How It Works [#how-it-works]

1. On each request, the middleware creates a `WideEvent` with the request method, path, headers, and a request ID
2. The logger is attached to `req.log` and stored in `AsyncLocalStorage`
3. When the response `"finish"` event fires, the event is emitted with the response status code
4. If the route is excluded, `next()` is called immediately with no logging overhead

## Request ID [#request-id]

The middleware reads `x-request-id` from incoming headers. If not present, it generates a UUID via `crypto.randomUUID()`. The request ID is included in the emitted wide event data.

## Route Exclusion [#route-exclusion]

```typescript
app.use(
    pailMiddleware({
        pail: logger,
        exclude: ["/health", "/ready", "/_next/**"],
        include: ["/api/**"],
    }),
);
```

## Service Names [#service-names]

```typescript
app.use(
    pailMiddleware({
        pail: logger,
        service: "api-gateway",
        routes: {
            "/api/auth/**": { service: "auth-service" },
            "/api/billing/**": { service: "billing-service" },
        },
    }),
);
```

## TypeScript [#typescript]

The middleware exports types for use in your route handlers:

```typescript
import type { PailRequest, PailResponse, PailNextFunction } from "@visulima/pail/middleware/express";

const handler = (req: PailRequest, res: PailResponse, next: PailNextFunction) => {
    req.log?.set({ user: { id: 1 } });
    res.json({ ok: true });
};
```

## Exported Types [#exported-types]

| Export                     | Description                                   |
| -------------------------- | --------------------------------------------- |
| `pailMiddleware`           | Factory function returning Express middleware |
| `useLogger`                | Retrieve logger from `AsyncLocalStorage`      |
| `PailRequest`              | Express request with `log?: WideEvent`        |
| `PailResponse`             | Express response type                         |
| `PailNextFunction`         | Express next function type                    |
| `PailExpressMiddleware`    | The middleware function signature             |
| `ExpressMiddlewareOptions` | Options type for `pailMiddleware()`           |
| `WideEvent`                | Re-exported `WideEvent` class                 |


# Fastify (/docs/packages/pail/middleware/fastify)



# Fastify Plugin [#fastify-plugin]

The Fastify adapter registers lifecycle hooks that attach a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) to every request. The event auto-emits on response or error.

## Setup [#setup]

```typescript
import Fastify from "fastify";
import { createPail } from "@visulima/pail";
import { pailPlugin } from "@visulima/pail/middleware/fastify";

const app = Fastify();
const logger = createPail();

pailPlugin(app, { pail: logger });

app.listen({ port: 3000 });
```

## Accessing the Logger [#accessing-the-logger]

### Via `request.log` [#via-requestlog]

```typescript
app.get("/api/users", async (request, reply) => {
    request.log.set({ user: { id: 1 } });
    request.log.info("Fetched user list");
    return { ok: true };
});
```

### Via `useLogger()` [#via-uselogger]

Access the logger from anywhere in the async call stack:

```typescript
import { useLogger } from "@visulima/pail/middleware/fastify";

async function fetchUser(id: number) {
    const log = useLogger();
    log.set({ user: { id } });
    log.info("Querying database");
    // ...
}
```

## How It Works [#how-it-works]

The plugin registers three Fastify hooks:

1. **`onRequest`** — Creates a `WideEvent`, attaches it to `request.log`, and enters `AsyncLocalStorage` context
2. **`onResponse`** — Emits the event with the response status code
3. **`onError`** — Emits the event with the error (prevents double-emit if both fire)

If the route is excluded, the `onRequest` hook calls `done()` immediately and no logger is attached.

## Request ID [#request-id]

The plugin reads `x-request-id` from incoming headers. If not present, it generates a UUID. The request ID is included in the emitted wide event.

## Route Configuration [#route-configuration]

```typescript
pailPlugin(app, {
    pail: logger,
    service: "api-gateway",
    exclude: ["/health", "/metrics"],
    include: ["/api/**"],
    routes: {
        "/api/auth/**": { service: "auth-service" },
    },
});
```

## TypeScript [#typescript]

```typescript
import type { PailFastifyRequest, PailFastifyReply } from "@visulima/pail/middleware/fastify";

app.get("/api/users", async (request: PailFastifyRequest, reply: PailFastifyReply) => {
    request.log?.set({ user: { id: 1 } });
    return { ok: true };
});
```

## Exported Types [#exported-types]

| Export                 | Description                                  |
| ---------------------- | -------------------------------------------- |
| `pailPlugin`           | Register the plugin on a Fastify instance    |
| `useLogger`            | Retrieve logger from `AsyncLocalStorage`     |
| `PailFastifyRequest`   | Fastify request with `log?: WideEvent`       |
| `PailFastifyReply`     | Fastify reply type                           |
| `PailFastifyInstance`  | Fastify instance type with hook registration |
| `FastifyPluginOptions` | Options type for `pailPlugin()`              |
| `WideEvent`            | Re-exported `WideEvent` class                |


# Hono (/docs/packages/pail/middleware/hono)



# Hono Middleware [#hono-middleware]

The Hono adapter attaches a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) to the Hono context. The event auto-emits when the handler completes or throws.

## Setup [#setup]

```typescript
import { Hono } from "hono";
import { createPail } from "@visulima/pail";
import { pailMiddleware } from "@visulima/pail/middleware/hono";

const app = new Hono();
const logger = createPail();

app.use("*", pailMiddleware({ pail: logger }));
```

## Accessing the Logger [#accessing-the-logger]

### Via `c.get("log")` [#via-cgetlog]

```typescript
app.get("/api/users", (c) => {
    const log = c.get("log");
    log.set({ user: { id: 1 } });
    log.info("Fetched user list");
    return c.json({ ok: true });
});
```

### Via `useLogger(c)` [#via-useloggerc]

A typed helper that retrieves the logger from context and throws if the middleware isn't registered:

```typescript
import { useLogger } from "@visulima/pail/middleware/hono";

app.get("/api/users", (c) => {
    const log = useLogger(c);
    log.set({ user: { id: 1 } });
    return c.json({ ok: true });
});
```

> **Note:** Unlike other adapters, Hono's `useLogger()` requires the context argument `c`. Hono stores the logger on the context object rather than in `AsyncLocalStorage`.

## How It Works [#how-it-works]

1. The middleware creates a `WideEvent` with request method, path, headers, and request ID
2. The logger is stored on the Hono context via `c.set("log", logger)`
3. The handler runs inside a try/catch:
   * **Success:** emits with `c.res.status`
   * **Error:** emits with the error, then re-throws

## Error Handling [#error-handling]

Errors are caught, logged, and re-thrown so Hono's error handling pipeline still works:

```typescript
app.get("/api/fail", async (c) => {
    const log = useLogger(c);
    log.set({ user: { id: 1 } });
    throw new Error("Something went wrong");
    // Wide event emits with error before Hono's onError handles it
});
```

## Route Configuration [#route-configuration]

```typescript
app.use(
    "*",
    pailMiddleware({
        pail: logger,
        service: "api-gateway",
        exclude: ["/health", "/metrics"],
        include: ["/api/**"],
        routes: {
            "/api/auth/**": { service: "auth-service" },
        },
    }),
);
```

## TypeScript [#typescript]

```typescript
import type { PailHonoContext } from "@visulima/pail/middleware/hono";

app.get("/api/users", (c: PailHonoContext) => {
    const log = c.get("log");
    log.set({ user: { id: 1 } });
    return c.json({ ok: true });
});
```

## Exported Types [#exported-types]

| Export                  | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `pailMiddleware`        | Factory function returning Hono middleware       |
| `useLogger`             | Retrieve logger from Hono context (`c` required) |
| `PailHonoContext`       | Hono context type                                |
| `PailHonoNext`          | Hono next function type                          |
| `PailHonoMiddleware`    | The middleware function signature                |
| `HonoMiddlewareOptions` | Options type for `pailMiddleware()`              |
| `WideEvent`             | Re-exported `WideEvent` class                    |


# Next.js (/docs/packages/pail/middleware/nextjs)



# Next.js Integration [#nextjs-integration]

The Next.js adapter has two parts:

1. **Edge middleware** (`pailMiddleware`) — Sets `x-request-id` and `x-pail-start` headers
2. **Handler wrapper** (`createWithPail`) — Creates wide events for route handlers and server actions

## Setup [#setup]

### 1. Edge Middleware (optional but recommended) [#1-edge-middleware-optional-but-recommended]

```typescript
// middleware.ts
import { NextResponse } from "next/server";
import { pailMiddleware } from "@visulima/pail/middleware/next";

export default pailMiddleware(NextResponse, {
    exclude: ["/_next/**", "/favicon.ico"],
});

export const config = {
    matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```

The edge middleware:

* Generates or propagates `x-request-id`
* Sets `x-pail-start` timestamp for downstream duration calculation
* Skips excluded routes

### 2. Handler Wrapper [#2-handler-wrapper]

```typescript
// lib/pail.ts
import { createPail } from "@visulima/pail";
import { createWithPail } from "@visulima/pail/middleware/next";

const logger = createPail();
export const withPail = createWithPail({ pail: logger });
```

## Route Handlers [#route-handlers]

Wrap your route handlers with `withPail`:

```typescript
// app/api/users/route.ts
import { withPail } from "@/lib/pail";
import { useLogger } from "@visulima/pail/middleware/next";

export const GET = withPail(async (request: Request) => {
    const log = useLogger();
    log.set({ user: { id: 1 } });
    log.info("Fetched user list");
    return Response.json({ ok: true });
});

export const POST = withPail(async (request: Request) => {
    const log = useLogger();
    const body = await request.json();
    log.set({ action: "create", body });
    return Response.json({ created: true }, { status: 201 });
});
```

## Server Actions [#server-actions]

`withPail` also works with server actions:

```typescript
// app/actions.ts
"use server";

import { withPail } from "@/lib/pail";
import { useLogger } from "@visulima/pail/middleware/next";

export const createUser = withPail(async (formData: FormData) => {
    const log = useLogger();
    const name = formData.get("name");
    log.set({ action: "createUser", name });
    // ...
});
```

> **Note:** When the first argument is not a `Request` object, the wide event uses `"UNKNOWN"` method and `"/"` path.

## Accessing the Logger [#accessing-the-logger]

### Via `useLogger()` [#via-uselogger]

Access the logger from anywhere in the async call stack:

```typescript
import { useLogger } from "@visulima/pail/middleware/next";

async function fetchUser(id: number) {
    const log = useLogger();
    log.set({ user: { id } });
    log.info("Querying database");
    // ...
}
```

## How It Works [#how-it-works]

### `createWithPail` wrapper [#createwithpail-wrapper]

1. Extracts method, path, headers, and request ID from the `Request` argument (if present)
2. Creates a `WideEvent` via `createMiddlewareLogger()`
3. Runs the handler inside `AsyncLocalStorage.run()` so `useLogger()` works
4. On success: emits with the `Response.status` (or 200 for non-Response returns)
5. On error: emits with the error, extracts `status`/`statusCode` from error, then re-throws

### Request ID propagation [#request-id-propagation]

If the edge middleware ran first, the `x-request-id` header is already set on the request. The handler wrapper picks it up and uses it for the wide event, ensuring consistent request IDs across edge and server.

## Route Configuration [#route-configuration]

```typescript
// lib/pail.ts
export const withPail = createWithPail({
    pail: logger,
    service: "web-app",
    exclude: ["/health"],
    include: ["/api/**"],
    routes: {
        "/api/auth/**": { service: "auth-service" },
    },
});
```

## Error Handling [#error-handling]

Errors are captured with their status code and re-thrown:

```typescript
export const GET = withPail(async () => {
    const error = new Error("Not found");
    (error as any).status = 404;
    throw error;
    // Wide event emits with { status: 404, error: { ... } }
});
```

The wrapper checks for `error.status` and `error.statusCode` properties, defaulting to 500.

## Exported Types [#exported-types]

| Export                      | Description                              |
| --------------------------- | ---------------------------------------- |
| `pailMiddleware`            | Edge middleware factory                  |
| `createWithPail`            | Handler wrapper factory                  |
| `useLogger`                 | Retrieve logger from `AsyncLocalStorage` |
| `PailNextMiddlewareOptions` | Options for the edge middleware          |
| `NextPailOptions`           | Options for `createWithPail()`           |
| `WideEvent`                 | Re-exported `WideEvent` class            |


# Middleware Overview (/docs/packages/pail/middleware/overview)



# Framework Middleware [#framework-middleware]

Pail provides first-class middleware adapters for popular web frameworks. Each adapter automatically creates a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) that:

* Accumulates context throughout the request lifecycle
* Auto-emits a single structured log when the response completes or an error occurs
* Is accessible via `req.log` / `request.log` / `context.log` and `useLogger()`
* Supports route inclusion/exclusion via glob patterns
* Supports per-route service name overrides
* Automatically filters sensitive headers

## Supported Frameworks [#supported-frameworks]

| Framework | Import Path                           | Access Pattern                     |
| --------- | ------------------------------------- | ---------------------------------- |
| Express   | `@visulima/pail/middleware/express`   | `req.log` / `useLogger()`          |
| Fastify   | `@visulima/pail/middleware/fastify`   | `request.log` / `useLogger()`      |
| Hono      | `@visulima/pail/middleware/hono`      | `c.get("log")` / `useLogger(c)`    |
| Elysia    | `@visulima/pail/middleware/elysia`    | `context.log` / `useLogger()`      |
| SvelteKit | `@visulima/pail/middleware/sveltekit` | `event.locals.log` / `useLogger()` |
| Next.js   | `@visulima/pail/middleware/next`      | `useLogger()`                      |

## Shared Options [#shared-options]

All middleware adapters accept the `PailMiddlewareOptions` interface:

```typescript
interface PailMiddlewareOptions {
    /** The pail logger instance (required) */
    pail: Pail;
    /** Default service name for all wide events */
    service?: string;
    /** Glob patterns for paths to include in logging */
    include?: string[];
    /** Glob patterns for paths to exclude from logging (takes precedence) */
    exclude?: string[];
    /** Route-specific configuration; maps glob patterns to config */
    routes?: Record<string, { service?: string }>;
}
```

## Route Configuration [#route-configuration]

All adapters support glob-based route configuration:

```typescript
pailMiddleware({
    pail: logger,
    service: "api-gateway",
    exclude: ["/health", "/metrics", "/_next/**"],
    include: ["/api/**"],
    routes: {
        "/api/auth/**": { service: "auth-service" },
        "/api/payments/**": { service: "payments-service" },
    },
});
```

### Pattern Matching [#pattern-matching]

| Pattern | Matches                      | Example                            |
| ------- | ---------------------------- | ---------------------------------- |
| `*`     | Any characters except `/`    | `/api/*` matches `/api/users`      |
| `**`    | Any characters including `/` | `/api/**` matches `/api/users/123` |
| `?`     | A single character           | `/api/v?` matches `/api/v1`        |

* Exclusions always take precedence over inclusions
* If no `include` patterns are provided, all non-excluded paths are logged
* Route service overrides apply to the first matching pattern

## Sensitive Header Filtering [#sensitive-header-filtering]

All adapters automatically filter these headers before including them in the wide event:

* `authorization`
* `cookie`
* `set-cookie`
* `x-api-key`
* `x-auth-token`
* `proxy-authorization`

## `useLogger()` — Access from Anywhere [#uselogger--access-from-anywhere]

Every adapter (except Hono) uses `AsyncLocalStorage` to propagate the logger through the async call stack. This means you can access the request-scoped logger from any function called during the request:

```typescript
// In a service function, far from the route handler:
import { useLogger } from "@visulima/pail/middleware/express";

export async function fetchUserProfile(userId: number) {
    const log = useLogger();
    log.set({ user: { id: userId } });
    log.info("Fetching user profile");
    // ...
}
```

> **Hono** uses context-based storage instead of `AsyncLocalStorage`. Pass the Hono context to `useLogger(c)`.

## Peer Dependencies [#peer-dependencies]

The framework adapters don't import framework packages directly — they use minimal internal type definitions. However, peer dependencies are declared for documentation and compatibility signaling:

```json
{
    "peerDependencies": {
        "express": ">=4.0",
        "fastify": ">=4.0",
        "hono": ">=4.0",
        "elysia": ">=1.0",
        "@sveltejs/kit": ">=2.0",
        "next": ">=14.0"
    },
    "peerDependenciesMeta": {
        "express": { "optional": true },
        "fastify": { "optional": true },
        "hono": { "optional": true },
        "elysia": { "optional": true },
        "@sveltejs/kit": { "optional": true },
        "next": { "optional": true }
    }
}
```

All peer dependencies are optional — only install the ones you actually use.

## Next Steps [#next-steps]

* [Express](/docs/packages/pail/middleware/express) — Express middleware guide
* [Fastify](/docs/packages/pail/middleware/fastify) — Fastify plugin guide
* [Hono](/docs/packages/pail/middleware/hono) — Hono middleware guide
* [Elysia](/docs/packages/pail/middleware/elysia) — Elysia plugin guide
* [SvelteKit](/docs/packages/pail/middleware/sveltekit) — SvelteKit hooks guide
* [Next.js](/docs/packages/pail/middleware/nextjs) — Next.js integration guide


# SvelteKit (/docs/packages/pail/middleware/sveltekit)



# SvelteKit Hooks [#sveltekit-hooks]

The SvelteKit adapter provides `handle` and `handleError` hooks that attach a request-scoped [Wide Event](/docs/packages/pail/usage/wide-events) to every request. The event auto-emits when the response is sent or an error occurs.

## Setup [#setup]

### Using `createPailHooks` (recommended) [#using-createpailhooks-recommended]

```typescript
// src/hooks.server.ts
import { createPail } from "@visulima/pail";
import { createPailHooks } from "@visulima/pail/middleware/sveltekit";

const logger = createPail();
const { handle, handleError } = createPailHooks({ pail: logger });

export { handle, handleError };
```

### Using individual hooks [#using-individual-hooks]

```typescript
// src/hooks.server.ts
import { createPail } from "@visulima/pail";
import { pailHandle, pailHandleError } from "@visulima/pail/middleware/sveltekit";

const logger = createPail();

export const handle = pailHandle({ pail: logger });
export const handleError = pailHandleError();
```

## Accessing the Logger [#accessing-the-logger]

### Via `event.locals.log` [#via-eventlocalslog]

In server load functions, actions, and API routes:

```typescript
// src/routes/api/users/+server.ts
import type { RequestHandler } from "./$types";

export const GET: RequestHandler = async ({ locals }) => {
    locals.log.set({ user: { id: 1 } });
    locals.log.info("Fetched user list");
    return new Response(JSON.stringify({ ok: true }));
};
```

```typescript
// src/routes/+page.server.ts
import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = async ({ locals }) => {
    locals.log.set({ page: "home" });
    return { title: "Home" };
};
```

### Via `useLogger()` [#via-uselogger]

Access the logger from anywhere in the async call stack:

```typescript
import { useLogger } from "@visulima/pail/middleware/sveltekit";

async function fetchUser(id: number) {
    const log = useLogger();
    log.set({ user: { id } });
    log.info("Querying database");
    // ...
}
```

## How It Works [#how-it-works]

### `pailHandle` [#pailhandle]

1. Creates a `WideEvent` with the request method, pathname, headers, and request ID
2. Attaches the logger to `event.locals.log`
3. Enters `AsyncLocalStorage` context via `storage.run()`
4. Calls `resolve(event)` to handle the request
5. On success: emits with `response.status`
6. On error: emits with the error, then re-throws

### `pailHandleError` [#pailhandleerror]

Records errors to the wide event logger if one exists on `event.locals.log`. This ensures errors caught by SvelteKit's error boundary are included in the wide event.

## Route Configuration [#route-configuration]

```typescript
const { handle, handleError } = createPailHooks({
    pail: logger,
    service: "web-app",
    exclude: ["/health", "/_app/**"],
    include: ["/api/**", "/dashboard/**"],
    routes: {
        "/api/auth/**": { service: "auth-service" },
    },
});
```

## TypeScript [#typescript]

For typed `event.locals.log`, augment SvelteKit's `App.Locals`:

```typescript
// src/app.d.ts
import type { WideEvent } from "@visulima/pail/middleware/sveltekit";

declare global {
    namespace App {
        interface Locals {
            log: WideEvent;
        }
    }
}
```

Use the exported types for custom hook compositions:

```typescript
import type { PailSvelteKitEvent, PailSvelteKitHandle } from "@visulima/pail/middleware/sveltekit";
```

## Exported Types [#exported-types]

| Export                          | Description                              |
| ------------------------------- | ---------------------------------------- |
| `pailHandle`                    | Create a SvelteKit `handle` hook         |
| `pailHandleError`               | Create a SvelteKit `handleError` hook    |
| `createPailHooks`               | Create both hooks at once                |
| `useLogger`                     | Retrieve logger from `AsyncLocalStorage` |
| `PailSvelteKitEvent`            | SvelteKit event with `locals.log`        |
| `PailSvelteKitHandle`           | Handle hook function type                |
| `PailSvelteKitHandleError`      | HandleError hook function type           |
| `PailSvelteKitHandleInput`      | Input for the handle hook                |
| `PailSvelteKitHandleErrorInput` | Input for the handleError hook           |
| `PailSvelteKitResolve`          | SvelteKit resolve function type          |
| `SvelteKitHandleOptions`        | Options type for `pailHandle()`          |
| `WideEvent`                     | Re-exported `WideEvent` class            |


# Troubleshooting (/docs/packages/pail/troubleshooting)



# Troubleshooting [#troubleshooting]

Common issues and their solutions when using Pail.

## Logs Not Appearing [#logs-not-appearing]

### Issue: No output from logger [#issue-no-output-from-logger]

**Possible Causes:**

1. **Logger is disabled**

   ```typescript
   logger.disable(); // Check if disabled somewhere
   logger.enable(); // Re-enable
   ```

2. **Log level too high**

   ```typescript
   // If logLevel is "error", debug/info won't show
   const logger = createPail({ logLevel: "debug" });
   ```

3. **No reporters configured**

   ```typescript
   // Make sure reporters are added
   const logger = createPail({
       reporters: [new PrettyReporter()],
   });
   ```

4. **Environment variable override**
   ```bash
   # Check PAIL_LOG_LEVEL
   echo $PAIL_LOG_LEVEL
   ```

## TypeScript Errors [#typescript-errors]

### Issue: Custom types not recognized [#issue-custom-types-not-recognized]

**Solution:** Explicitly type the logger:

```typescript
type CustomTypes = "http" | "db";

const logger = createPail<CustomTypes>({
    types: {
        http: { label: "HTTP", logLevel: "info" },
        db: { label: "DB", logLevel: "debug" },
    },
});
```

### Issue: Property does not exist on logger [#issue-property-does-not-exist-on-logger]

**Solution:** Check that the type is defined in configuration:

```typescript
// Make sure custom type is in types config
const logger = createPail({
    types: {
        custom: { label: "CUSTOM", logLevel: "info" },
    },
});

logger.custom("Message"); // Now works
```

## Performance Issues [#performance-issues]

### Issue: Slow logging in production [#issue-slow-logging-in-production]

**Solutions:**

1. **Increase log level**

   ```typescript
   const logger = createPail({
       logLevel: "warning", // Reduce verbosity
   });
   ```

2. **Disable processors in production**

   ```typescript
   const logger = createPail({
       processors:
           process.env.NODE_ENV === "production"
               ? [] // No processors in production
               : [new CallerProcessor()],
   });
   ```

3. **Use JSON reporter in production**
   ```typescript
   const logger = createPail({
       reporters:
           process.env.NODE_ENV === "production"
               ? [new JsonReporter()] // Faster
               : [new PrettyReporter()],
   });
   ```

## Interactive Mode Issues [#interactive-mode-issues]

### Issue: Progress bars/spinners not working [#issue-progress-barsspinners-not-working]

**Possible Causes:**

1. **Interactive mode not enabled**

   ```typescript
   const logger = createPail({ interactive: true }); // Required
   ```

2. **Not running in terminal**
   * Interactive mode only works in terminal environments
   * Won't work in browser or non-TTY environments

3. **Streams not available**
   ```typescript
   // Make sure stdout/stderr are available
   const logger = createPail({
       interactive: true,
       stdout: process.stdout,
       stderr: process.stderr,
   });
   ```

## File Reporter Issues [#file-reporter-issues]

### Issue: File reporter not writing [#issue-file-reporter-not-writing]

**Possible Causes:**

1. **Missing dependency**

   ```bash
   npm install rotating-file-stream
   ```

2. **Permissions issue**

   ```bash
   # Check file permissions
   ls -la /var/log/app.log
   # Ensure write permissions
   ```

3. **Invalid file path**
   ```typescript
   // Use absolute paths
   new JsonFileReporter({
       filePath: "/absolute/path/to/log.log", // Not relative
   });
   ```

## Redact Processor Issues [#redact-processor-issues]

### Issue: Sensitive data not redacted [#issue-sensitive-data-not-redacted]

**Possible Causes:**

1. **Missing dependency**

   ```bash
   npm install @visulima/redact
   ```

2. **Pattern not matching**

   ```typescript
   // Test your regex pattern
   const pattern = /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g;
   "1234-5678-9012-3456".match(pattern); // Should match
   ```

3. **Processor order**
   ```typescript
   // RedactProcessor should run before other processors
   const logger = createPail({
       processors: [
           new RedactProcessor(), // First
           new CallerProcessor(), // Second
       ],
   });
   ```

## Scope Issues [#scope-issues]

### Issue: Scope not appearing in logs [#issue-scope-not-appearing-in-logs]

**Check:**

1. **Reporter supports scopes**
   * All built-in reporters support scopes
   * Custom reporters need to handle `meta.scope`

2. **Scope is set correctly**
   ```typescript
   const scopedLogger = logger.scope("api");
   scopedLogger.info("Message"); // Should include scope
   ```

## Browser Issues [#browser-issues]

### Issue: Logger not working in browser [#issue-logger-not-working-in-browser]

**Solutions:**

1. **Use browser import**

   ```typescript
   import { createPail } from "@visulima/pail/browser";
   ```

2. **Check browser compatibility**
   * Requires modern browser with ES module support
   * Check browser console for errors

3. **Use browser-compatible reporters**
   ```typescript
   // PrettyReporter and JsonReporter work in browser
   // FileReporter and SimpleReporter don't
   ```

## Environment Variable Issues [#environment-variable-issues]

### Issue: Environment variables not working [#issue-environment-variables-not-working]

**Check:**

1. **Variable name**

   ```bash
   # Correct
   PAIL_LOG_LEVEL=debug node app.js

   # Not
   LOG_LEVEL=debug node app.js
   ```

2. **Setting before import**
   ```typescript
   // Set before creating logger
   process.env.PAIL_LOG_LEVEL = "debug";
   import { createPail } from "@visulima/pail";
   ```

## Getting Help [#getting-help]

If you're still experiencing issues:

1. **Check the [API Reference](/docs/packages/pail/api)** for correct usage
2. **Review [Examples](/docs/packages/pail/examples)** for working code
3. **Open an issue** on [GitHub](https://github.com/visulima/visulima/issues)
4. **Check [CHANGELOG.md](https://github.com/visulima/visulima/blob/main/packages/pail/CHANGELOG)** for breaking changes

## Related [#related]

* [Configuration](/docs/packages/pail/configuration) - Configuration options
* [API Reference](/docs/packages/pail/api) - Complete API documentation


# Basic Usage (/docs/packages/pail/usage/basic)



# Basic Usage [#basic-usage]

This guide covers the fundamental logging operations in Pail.

## Default Logger [#default-logger]

Pail provides a pre-configured logger instance ready to use:

```typescript
import { pail } from "@visulima/pail";

pail.info("Server started");
pail.success("Operation completed");
pail.error("Something went wrong", error);
```

## Log Types [#log-types]

Pail provides semantic log types for different purposes:

### Informational Logs [#informational-logs]

```typescript
pail.info("User logged in", { userId: 123 });
pail.log("General message");
```

### Success Messages [#success-messages]

```typescript
pail.success("File uploaded successfully");
```

### Warnings [#warnings]

```typescript
pail.warn("Using deprecated API");
pail.warning("High memory usage detected");
```

### Errors [#errors]

```typescript
pail.error("Failed to connect to database", error);
pail.critical("System failure", criticalError);
pail.emergency("System is down!");
pail.alert("Immediate action required");
```

### Debug and Trace [#debug-and-trace]

```typescript
pail.debug("Processing request", { requestId: "abc" });
pail.trace("Entering function", { functionName: "processData" });
```

### Status Messages [#status-messages]

```typescript
pail.pending("Task in progress...");
pail.complete("Task completed");
pail.start("Starting process");
pail.stop("Process stopped");
pail.await("Waiting for response");
pail.wait("Waiting...");
pail.watch("Watching for changes");
```

## Message Formats [#message-formats]

### Simple String [#simple-string]

```typescript
pail.info("Hello world");
```

### String Interpolation [#string-interpolation]

```typescript
pail.info("User %s logged in", "John");
pail.success("Completed %d tasks", 5);
```

### Multiple Arguments [#multiple-arguments]

```typescript
pail.debug("Processing", "request", { id: 123 });
// All arguments are included in context
```

### Structured Message Object [#structured-message-object]

```typescript
pail.complete({
    prefix: "[task]",
    message: "Fix issue #59",
    suffix: "(@prisis)",
});
```

### Error Objects [#error-objects]

```typescript
try {
    // ...
} catch (error) {
    pail.error(error); // Error object is automatically serialized
    pail.error("Operation failed", error); // With additional context
}
```

### Objects and Arrays [#objects-and-arrays]

```typescript
pail.info({ userId: 123, action: "login" });
pail.debug([1, 2, 3, 4, 5]);
```

## Creating Custom Loggers [#creating-custom-loggers]

Create a logger with custom configuration:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    logLevel: "debug",
    scope: "my-module",
});

logger.info("Module initialized");
```

## Enabling and Disabling [#enabling-and-disabling]

```typescript
logger.disable(); // Stop all logging
logger.info("This won't be logged");

logger.enable(); // Resume logging
logger.info("This will be logged");

if (logger.isEnabled()) {
    logger.debug("Logger is active");
}
```

## Pausing and Resuming [#pausing-and-resuming]

Queue messages during critical operations:

```typescript
logger.pause(); // Start queuing messages
logger.info("Message 1"); // Queued
logger.warn("Message 2"); // Queued

logger.resume(); // Flush all queued messages
logger.info("Message 3"); // Output immediately
```

## Console Integration [#console-integration]

### Wrap Console (Browser) [#wrap-console-browser]

```typescript
logger.wrapConsole(); // Redirect console.* to logger
console.log("Goes through logger");
console.error("Also goes through logger");

logger.restoreConsole(); // Restore original console
```

### Wrap Streams (Server) [#wrap-streams-server]

```typescript
logger.wrapStd(); // Redirect stdout/stderr to logger
process.stdout.write("Goes through logger");

logger.restoreStd(); // Restore original streams
```

### Wrap Everything (Server) [#wrap-everything-server]

```typescript
logger.wrapAll(); // Wraps both console and streams
// All output goes through logger

logger.restoreAll(); // Restore everything
```

## Exception Handling [#exception-handling]

Automatically log uncaught exceptions:

```typescript
logger.wrapException(); // Sets up global error handlers

// Uncaught errors will be logged automatically
throw new Error("This will be logged");
```

## Raw Logging [#raw-logging]

Bypass normal processing:

```typescript
logger.raw("Direct message", { data: "value" });
// Uses rawReporter, bypasses processors
```

## Next Steps [#next-steps]

* [Scoped Loggers](/docs/packages/pail/usage/scoped) - Organize logs by context
* [Custom Types](/docs/packages/pail/usage/custom-types) - Create custom log types
* [Timers](/docs/packages/pail/usage/timers) - Measure performance


# Custom Types (/docs/packages/pail/usage/custom-types)



# Custom Types [#custom-types]

Custom log types allow you to create semantic logging methods that better represent your application's domain.

## Creating Custom Types [#creating-custom-types]

Define custom types when creating a logger:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    types: {
        http: {
            badge: "🌐",
            color: "blue",
            label: "HTTP",
            logLevel: "info",
        },
        db: {
            badge: "💾",
            color: "cyan",
            label: "DATABASE",
            logLevel: "debug",
        },
    },
});

logger.http("GET /api/users 200");
logger.db("Query executed", { query: "SELECT * FROM users" });
```

## Type Configuration [#type-configuration]

Each custom type requires:

* **`label`** (required) - Display label for the log type
* **`logLevel`** (required) - The log level to use
* **`color`** (optional) - ANSI color for styling
* **`badge`** (optional) - Icon or symbol prefix

```typescript
{
  label: "HTTP",           // Required: Display name
  logLevel: "info",        // Required: Log level
  color: "blue",           // Optional: Color name
  badge: "🌐",            // Optional: Icon/symbol
}
```

## Available Colors [#available-colors]

Pail supports ANSI colors from `@visulima/colorize`:

* `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
* `blackBright`, `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
* `gray`

```typescript
const logger = createPail({
    types: {
        success: { color: "greenBright", label: "SUCCESS", logLevel: "info" },
        warning: { color: "yellowBright", label: "WARNING", logLevel: "warning" },
    },
});
```

## Overriding Default Types [#overriding-default-types]

You can override default types to customize their appearance:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    types: {
        error: {
            badge: "❌",
            color: "redBright",
            label: "ERROR",
            logLevel: "error",
        },
        success: {
            badge: "✅",
            color: "greenBright",
            label: "SUCCESS",
            logLevel: "info",
        },
    },
});

logger.error("Custom error style");
logger.success("Custom success style");
```

## Real-World Examples [#real-world-examples]

### HTTP Logger [#http-logger]

```typescript
const logger = createPail({
    types: {
        http: {
            badge: "🌐",
            color: "blue",
            label: "HTTP",
            logLevel: "info",
        },
        httpError: {
            badge: "⚠️",
            color: "red",
            label: "HTTP_ERROR",
            logLevel: "error",
        },
    },
});

logger.http("GET /api/users 200", { duration: 45 });
logger.httpError("POST /api/users 500", { error: "Database error" });
```

### Database Logger [#database-logger]

```typescript
const logger = createPail({
    types: {
        db: {
            badge: "💾",
            color: "cyan",
            label: "DATABASE",
            logLevel: "debug",
        },
        dbQuery: {
            badge: "🔍",
            color: "blueBright",
            label: "QUERY",
            logLevel: "debug",
        },
        dbError: {
            badge: "❌",
            color: "red",
            label: "DB_ERROR",
            logLevel: "error",
        },
    },
});

logger.db("Connected to database");
logger.dbQuery("SELECT * FROM users", { duration: 12 });
logger.dbError("Connection failed", error);
```

### Security Logger [#security-logger]

```typescript
const logger = createPail({
    types: {
        security: {
            badge: "🔒",
            color: "yellow",
            label: "SECURITY",
            logLevel: "warning",
        },
        auth: {
            badge: "🔐",
            color: "magenta",
            label: "AUTH",
            logLevel: "info",
        },
    },
});

logger.security("Suspicious activity detected", { ip: "192.168.1.1" });
logger.auth("User logged in", { userId: 123 });
```

### Background Job Logger [#background-job-logger]

```typescript
const logger = createPail({
    types: {
        job: {
            badge: "⚙️",
            color: "cyan",
            label: "JOB",
            logLevel: "info",
        },
        jobStart: {
            badge: "▶️",
            color: "green",
            label: "JOB_START",
            logLevel: "info",
        },
        jobComplete: {
            badge: "✅",
            color: "greenBright",
            label: "JOB_COMPLETE",
            logLevel: "info",
        },
        jobError: {
            badge: "❌",
            color: "red",
            label: "JOB_ERROR",
            logLevel: "error",
        },
    },
});

logger.jobStart("Processing queue");
logger.job("Processing item", { itemId: 456 });
logger.jobComplete("Queue processed", { itemsProcessed: 100 });
logger.jobError("Job failed", error);
```

## TypeScript Support [#typescript-support]

Custom types are fully typed:

```typescript
import { createPail } from "@visulima/pail";

type CustomTypes = "http" | "db" | "cache";

const logger = createPail<CustomTypes>({
    types: {
        http: { label: "HTTP", logLevel: "info" },
        db: { label: "DB", logLevel: "debug" },
        cache: { label: "CACHE", logLevel: "debug" },
    },
});

// TypeScript knows about custom types
logger.http("GET /api/users"); // ✅ Type-safe
logger.db("Query executed"); // ✅ Type-safe
logger.cache("Cache hit"); // ✅ Type-safe
logger.unknown("Test"); // ❌ Type error
```

## Combining with Scopes [#combining-with-scopes]

Custom types work great with scoped loggers:

```typescript
const apiLogger = logger.scope("api");

apiLogger.http("GET /users 200");
apiLogger.http("POST /users 201");
// Output: [api] 🌐 HTTP GET /users 200
```

## Best Practices [#best-practices]

1. **Use semantic names** - Names should reflect their purpose
2. **Consistent styling** - Use consistent colors/badges for similar types
3. **Appropriate log levels** - Match log levels to severity
4. **Document your types** - Keep a reference of custom types
5. **Don't overuse** - Too many types can be confusing

## Related [#related]

* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations
* [Configuration](/docs/packages/pail/configuration) - Configure logger types


# Error Handling (/docs/packages/pail/usage/error-handling)



# Error Handling [#error-handling]

Pail provides `PailError`, a self-documenting error class that extends standard errors with fields that make log entries immediately actionable. Inspired by [evlog](https://github.com/HugoRCD/evlog)'s structured error approach, these fields are particularly useful for AI-assisted log analysis and structured debugging.

## PailError [#pailerror]

`PailError` extends the native `Error` class with additional context fields:

* **`why`** - Explains what caused the failure
* **`fix`** - Suggests how to resolve the issue
* **`link`** - Points to relevant documentation or issue tracker
* **`status`** - HTTP status code (defaults to 500)

### Basic Usage [#basic-usage]

```typescript
import { PailError, createPailError } from "@visulima/pail";

// Using the class directly
throw new PailError({
    message: "Payment processing failed",
    status: 402,
    why: "The customer's card was declined by the payment provider",
    fix: "Retry with a different payment method or contact the card issuer",
    link: "https://docs.example.com/payments/declined",
});

// Using the factory function
throw createPailError("Connection timeout");

// Simple string shorthand
throw new PailError("Something went wrong");
```

### With Pail Logger [#with-pail-logger]

PailError integrates naturally with Pail's error logging:

```typescript
import { createPail, PailError } from "@visulima/pail";

const logger = createPail();

try {
    await connectToDatabase();
} catch (cause) {
    const error = new PailError({
        message: "Database connection failed",
        why: "Connection pool exhausted after 30s timeout",
        fix: "Increase pool size in DATABASE_POOL_SIZE or check for connection leaks",
        link: "https://docs.example.com/database/pool-config",
        status: 503,
        cause,
    });

    logger.error(error);
    // Output includes all self-documenting fields
}
```

### Error Chaining with `cause` [#error-chaining-with-cause]

PailError supports the standard `cause` property for error chaining:

```typescript
try {
    await fetchData();
} catch (originalError) {
    throw new PailError({
        message: "Failed to load user profile",
        why: "The upstream user service returned an error",
        fix: "Check if the user service is healthy at /health",
        cause: originalError,
    });
}
```

### Serialization [#serialization]

PailError includes a `toJSON()` method for structured logging:

```typescript
const error = new PailError({
    message: "Auth failed",
    status: 401,
    why: "Token expired",
    fix: "Refresh the authentication token",
});

console.log(JSON.stringify(error));
// {
//   "name": "PailError",
//   "message": "Auth failed",
//   "status": 401,
//   "why": "Token expired",
//   "fix": "Refresh the authentication token",
//   "stack": "..."
// }
```

The `toString()` method also includes all self-documenting fields:

```typescript
console.log(error.toString());
// PailError [401]: Auth failed
//   Why: Token expired
//   Fix: Refresh the authentication token
```

### `createPailError` Factory [#createpailerror-factory]

A convenient shorthand for creating PailError instances:

```typescript
import { createPailError } from "@visulima/pail";

// String shorthand
const simple = createPailError("Something went wrong");

// Full options
const detailed = createPailError({
    message: "Rate limit exceeded",
    status: 429,
    why: "Too many requests from this IP in the last minute",
    fix: "Implement exponential backoff or reduce request frequency",
    link: "https://docs.example.com/rate-limits",
});
```

### Standalone Import [#standalone-import]

PailError is also available as a standalone import:

```typescript
import { PailError, createPailError } from "@visulima/pail/error";
import type { PailErrorOptions } from "@visulima/pail/error";
```

## Best Practices [#best-practices]

1. **Always include `why`** - The most useful field for debugging. Explain what went wrong in plain language.
2. **Include `fix` for actionable errors** - When you know what the user or developer should do, tell them.
3. **Use `link` for complex issues** - Point to documentation, runbooks, or issue trackers.
4. **Set `status` for HTTP errors** - Makes it easy to map errors to HTTP responses.
5. **Chain with `cause`** - Preserve the original error for full stack trace analysis.

## Related [#related]

* [Processors](/docs/packages/pail/concepts/processors) - Process and enrich error metadata
* [API Reference](/docs/packages/pail/api) - Complete PailError API
* [Examples](/docs/packages/pail/examples) - Real-world error handling examples


# Interactive Mode (/docs/packages/pail/usage/interactive)



# Interactive Mode [#interactive-mode]

Interactive mode enables dynamic terminal UI by coordinating stdout/stderr streams. &#x2A;*Server only.**

> **Breaking Change:** Spinners and progress bars have been extracted into separate packages.
> Use `@visulima/spinner` and `@visulima/progress-bar` directly with pail's interactive manager.

## Setup [#setup]

Enable interactive mode when creating a logger:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    interactive: true,
});
```

## Using Spinners [#using-spinners]

Install `@visulima/spinner`:

```bash
pnpm add @visulima/spinner
```

Use pail's interactive manager with the spinner:

```typescript
import { createPail } from "@visulima/pail";
import { Spinner } from "@visulima/spinner";

const logger = createPail({ interactive: true });
const manager = logger.getInteractiveManager();

const spinner = new Spinner({ name: "dots" }, manager);

spinner.start("Loading...");
// ... do work ...
spinner.succeed("Done!");
```

### Spinner with Colorize Styling [#spinner-with-colorize-styling]

```typescript
import colorize from "@visulima/colorize";
import { Spinner } from "@visulima/spinner";

const spinner = new Spinner(
    {
        name: "dots",
        style: (text) => colorize.bold.blue(text),
    },
    manager,
);
```

### Multiple Spinners [#multiple-spinners]

```typescript
import { MultiSpinner } from "@visulima/spinner";

const multi = new MultiSpinner({ name: "dots" }, manager);

const s1 = multi.create("Loading users");
const s2 = multi.create("Loading posts");

s1.start();
s2.start();

s1.succeed("Users loaded");
s2.succeed("Posts loaded");

multi.stop();
```

## Using Progress Bars [#using-progress-bars]

Install `@visulima/progress-bar`:

```bash
pnpm add @visulima/progress-bar
```

Use pail's interactive manager with the progress bar:

```typescript
import { createPail } from "@visulima/pail";
import { ProgressBar } from "@visulima/progress-bar";

const logger = createPail({ interactive: true });
const manager = logger.getInteractiveManager();

const bar = new ProgressBar(
    {
        total: 100,
        format: "Downloading [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}",
    },
    manager,
);

bar.start();

for (let i = 0; i <= 100; i++) {
    bar.update(i);
    await sleep(50);
}

bar.stop();
```

### Multiple Progress Bars [#multiple-progress-bars]

```typescript
import { MultiProgressBar } from "@visulima/progress-bar";

const multi = new MultiProgressBar({}, manager);

const bar1 = multi.create(100);
const bar2 = multi.create(200);

bar1.update(50);
bar2.update(100);

multi.stop();
```

## Interactive Manager [#interactive-manager]

Access the interactive manager directly for custom use:

```typescript
const logger = createPail({ interactive: true });
const manager = logger.getInteractiveManager();

if (manager) {
    manager.hook();
    manager.update("stdout", ["Custom output line 1", "Custom output line 2"]);
    manager.unhook();
}
```

## Migration from Previous Versions [#migration-from-previous-versions]

The `createSpinner()`, `createMultiSpinner()`, `createProgressBar()`, and `createMultiProgressBar()` methods have been removed from pail.

**Before (old API):**

```typescript
const logger = createPail({ interactive: true });
const spinner = logger.createSpinner({ name: "dots" });
spinner.start("Loading...");
```

**After (new API):**

```typescript
import { createPail } from "@visulima/pail";
import { Spinner } from "@visulima/spinner";

const logger = createPail({ interactive: true });
const spinner = new Spinner({ name: "dots" }, logger.getInteractiveManager());
spinner.start("Loading...");
```

## Related [#related]

* `@visulima/spinner` - Spinner package documentation
* `@visulima/progress-bar` - Progress bar package documentation
* `@visulima/interactive-manager` - Interactive manager documentation
* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations


# Object Tree Rendering (/docs/packages/pail/usage/object-tree)



# Object Tree Rendering [#object-tree-rendering]

The `renderObjectTree` utility function converts JavaScript objects into visually appealing ASCII tree structures. This is useful for debugging, documentation, or displaying hierarchical data.

## Installation [#installation]

`renderObjectTree` is exported as a separate module to reduce bundle size:

```typescript
import { renderObjectTree } from "@visulima/pail/object-tree";
```

## Basic Usage [#basic-usage]

```typescript
import { renderObjectTree } from "@visulima/pail/object-tree";

const user = {
    name: "Alice Johnson",
    age: 28,
    email: "alice@example.com",
    active: true,
};

console.log(renderObjectTree(user));
```

Output:

```
├─ name: Alice Johnson
├─ age: 28
├─ email: alice@example.com
└─ active: true
```

## Nested Objects [#nested-objects]

Works seamlessly with nested object structures:

```typescript
const config = {
    server: {
        host: "localhost",
        port: 3000,
        ssl: {
            enabled: true,
            cert: "/path/to/cert.pem",
        },
    },
    database: {
        type: "postgresql",
        connection: {
            host: "db.example.com",
            port: 5432,
        },
    },
};

console.log(renderObjectTree(config));
```

Output:

```
├─ server
│  ├─ host: localhost
│  ├─ port: 3000
│  └─ ssl
│     ├─ enabled: true
│     └─ cert: /path/to/cert.pem
└─ database
   ├─ type: postgresql
   └─ connection
      ├─ host: db.example.com
      └─ port: 5432
```

## Custom Styling [#custom-styling]

Customize the tree appearance:

```typescript
const data = {
    project: "MyApp",
    version: "2.1.0",
    contributors: 15,
};

console.log(
    renderObjectTree(data, {
        keyNeighbour: "├── ",
        keyNoNeighbour: "└── ",
        separator: " → ",
        spacerNeighbour: "│  ",
        spacerNoNeighbour: "   ",
    }),
);
```

## Custom Render Function [#custom-render-function]

Format values with a custom render function:

```typescript
const metrics = {
    responseTime: 145, // milliseconds
    errorRate: 0.02, // percentage
    uptime: 99.9, // percentage
    requestsPerSecond: 1250,
};

console.log(
    renderObjectTree(metrics, {
        renderFn: (node) => {
            if (typeof node === "number") {
                if (node < 1) {
                    return `${(node * 100).toFixed(2)}%`;
                }
                if (node > 1000) {
                    return `${(node / 1000).toFixed(1)}k`;
                }
                return node.toString();
            }
            return ["boolean", "string"].includes(typeof node) ? String(node) : undefined;
        },
    }),
);
```

Output:

```
├─ responseTime: 145
├─ errorRate: 2.00%
├─ uptime: 99.90%
└─ requestsPerSecond: 1.3k
```

## Sorting Keys [#sorting-keys]

Sort object keys alphabetically or with a custom function:

```typescript
const unsorted = {
    zebra: "animal",
    apple: "fruit",
    banana: "fruit",
    car: "vehicle",
};

console.log(
    renderObjectTree(unsorted, {
        sortFn: (a, b) => a.localeCompare(b),
    }),
);
```

## Circular Reference Handling [#circular-reference-handling]

Detects and handles circular references:

```typescript
const circularObj = {
    name: "Circular Example",
    data: [1, 2, 3],
};

// Create circular reference
circularObj.self = circularObj;

console.log(
    renderObjectTree(circularObj, {
        breakCircularWith: " [↻ CIRCULAR]",
    }),
);
```

Output:

```
├─ name: Circular Example
├─ data: [1,2,3]
└─ self:  [↻ CIRCULAR]
```

## Array Output [#array-output]

Get output as an array of lines instead of a single string:

```typescript
const obj = {
    method: "GET",
    status: 200,
    cached: false,
};

const lines = renderObjectTree(obj, { joined: false });
lines.forEach((line, index) => {
    console.log(`${index + 1}: ${line}`);
});
```

## Options [#options]

### `ObjectTreeOptions` [#objecttreeoptions]

```typescript
interface ObjectTreeOptions {
    /** Text to display for circular references (default: " (circular ref.)") */
    breakCircularWith?: string | null;
    /** Whether to return as single string or array of lines (default: true) */
    joined?: boolean;
    /** Connector for neighbor keys (default: "├─ ") */
    keyNeighbour?: string;
    /** Connector for non-neighbor keys (default: "└─ ") */
    keyNoNeighbour?: string;
    /** Function to render node values (default: renders primitives) */
    renderFn?: (node: unknown) => string | undefined;
    /** Separator between key and value (default: ": ") */
    separator?: string;
    /** Function to sort object keys (default: natural order) */
    sortFn?: (a: string, b: string) => number;
    /** Spacer for neighbor branches (default: "│  ") */
    spacerNeighbour?: string;
    /** Spacer for non-neighbor branches (default: "   ") */
    spacerNoNeighbour?: string;
}
```

## Use Cases [#use-cases]

* **Debugging**: Visualize complex nested objects
* **Documentation**: Display configuration structures
* **CLI Tools**: Show hierarchical data in terminal
* **Logging**: Format object metadata for logs

## Browser and Server Support [#browser-and-server-support]

`renderObjectTree` works in both **Node.js** and **Browser** environments. It's a pure utility function with no platform-specific dependencies.

## Related [#related]

* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations
* [Examples](/docs/packages/pail/examples) - Real-world examples


# Scoped Loggers (/docs/packages/pail/usage/scoped)



# Scoped Loggers [#scoped-loggers]

Scoped loggers allow you to organize logs by context, making it easier to track messages from specific modules, features, or components.

## Basic Scoping [#basic-scoping]

Create a scoped logger by calling `scope()`:

```typescript
import { pail } from "@visulima/pail";

const authLogger = pail.scope("auth");
authLogger.info("User logged in"); // Includes scope: ["auth"]
```

## Multiple Scope Levels [#multiple-scope-levels]

You can nest scopes for hierarchical organization:

```typescript
const apiLogger = pail.scope("api", "users");
apiLogger.info("Fetching user"); // Includes scope: ["api", "users"]
```

## Scoped Logger Instance [#scoped-logger-instance]

The `scope()` method returns a new logger instance with the scope applied:

```typescript
const logger = createPail();
const scopedLogger = logger.scope("database");

scopedLogger.info("Connected"); // Has scope
logger.info("General message"); // No scope (original logger unchanged)
```

## Removing Scope [#removing-scope]

Remove the current scope:

```typescript
const scopedLogger = logger.scope("auth");
scopedLogger.info("Has scope");

scopedLogger.unscope();
scopedLogger.info("No scope");
```

## Usage Patterns [#usage-patterns]

### Module-Level Scoping [#module-level-scoping]

```typescript
// auth.ts
import { pail } from "@visulima/pail";

const logger = pail.scope("auth");

export const login = (username: string) => {
    logger.info("Attempting login", { username });
    // ...
};
```

### Feature-Level Scoping [#feature-level-scoping]

```typescript
// payment.ts
import { pail } from "@visulima/pail";

const paymentLogger = pail.scope("payment", "processing");

export const processPayment = (amount: number) => {
    paymentLogger.info("Processing payment", { amount });
    // ...
};
```

### Request-Level Scoping [#request-level-scoping]

```typescript
// middleware.ts
import { createPail } from "@visulima/pail";

const logger = createPail();

export const requestLogger = (req: Request, res: Response, next: NextFunction) => {
    const requestId = req.headers["x-request-id"] || generateId();
    const scopedLogger = logger.scope("request", requestId);

    req.logger = scopedLogger; // Attach to request
    scopedLogger.info("Request received", { method: req.method, path: req.path });

    next();
};
```

### Component Scoping (React Example) [#component-scoping-react-example]

```typescript
// UserProfile.tsx
import { pail } from "@visulima/pail";

const logger = pail.scope("UserProfile");

const UserProfile = () => {
    useEffect(() => {
        logger.info("Component mounted");

        return () => {
            logger.info("Component unmounted");
        };
    }, []);

    // ...
};
```

## Scope Display [#scope-display]

Scopes are displayed differently depending on the reporter:

### PrettyReporter [#prettyreporter]

```
[api] [users] info Fetching user
```

### JsonReporter [#jsonreporter]

```json
{
    "scope": ["api", "users"],
    "type": { "name": "info", "level": "informational" },
    "message": "Fetching user"
}
```

## Best Practices [#best-practices]

1. **Use descriptive names** - Make scopes meaningful
2. **Keep scope hierarchy shallow** - Usually 1-3 levels is enough
3. **Scope at module boundaries** - Create scopes at module/feature level
4. **Consistent naming** - Use consistent scope naming across your app
5. **Don't over-scope** - Not every function needs its own scope

## Advanced: Dynamic Scoping [#advanced-dynamic-scoping]

You can create scopes dynamically:

```typescript
const createModuleLogger = (moduleName: string) => {
    return pail.scope("module", moduleName);
};

const authLogger = createModuleLogger("auth");
const userLogger = createModuleLogger("user");
```

## Related [#related]

* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations
* [Configuration](/docs/packages/pail/configuration) - Configure logger behavior


# Timers (/docs/packages/pail/usage/timers)



# Timers [#timers]

Pail provides built-in timing utilities to measure how long operations take.

## Basic Timer [#basic-timer]

Start and stop a timer:

```typescript
import { pail } from "@visulima/pail";

pail.time("operation");
// ... do work ...
pail.timeEnd("operation");
// Output: Timer run for: 123 ms
```

## Multiple Timers [#multiple-timers]

You can run multiple timers simultaneously:

```typescript
pail.time("database");
pail.time("api");

// ... database work ...
pail.timeEnd("database"); // Logs elapsed time for database

// ... api work ...
pail.timeEnd("api"); // Logs elapsed time for api
```

## Timer Labels [#timer-labels]

Use descriptive labels for your timers:

```typescript
pail.time("user-authentication");
// ... authentication logic ...
pail.timeEnd("user-authentication");
```

## Checking Elapsed Time [#checking-elapsed-time]

Log the current elapsed time without stopping the timer:

```typescript
pail.time("long-operation");

// ... some work ...
pail.timeLog("long-operation"); // Logs current elapsed time

// ... more work ...
pail.timeEnd("long-operation"); // Logs final time and stops
```

## Sequential Timers [#sequential-timers]

Timers can be sequential - start one after another:

```typescript
pail.time("step1");
// ... work ...
pail.timeEnd("step1");

pail.time("step2");
// ... work ...
pail.timeEnd("step2");
```

## Custom Timer Messages [#custom-timer-messages]

Configure timer messages:

```typescript
import { createPail } from "@visulima/pail";

const logger = createPail({
    messages: {
        timerStart: "Starting timer...",
        timerEnd: "Completed in:",
    },
});

logger.time("task");
// ... work ...
logger.timeEnd("task");
// Output: Completed in: 123 ms
```

## Real-World Examples [#real-world-examples]

### API Request Timing [#api-request-timing]

```typescript
import { pail } from "@visulima/pail";

export const handleRequest = async (req: Request, res: Response) => {
    pail.time("request");

    try {
        pail.time("database");
        const data = await db.query("SELECT * FROM users");
        pail.timeEnd("database");

        pail.time("serialization");
        const json = JSON.stringify(data);
        pail.timeEnd("serialization");

        res.json(json);
    } finally {
        pail.timeEnd("request");
    }
};
```

### Performance Benchmarking [#performance-benchmarking]

```typescript
import { pail } from "@visulima/pail";

const benchmark = (name: string, fn: () => void) => {
    pail.time(`benchmark-${name}`);
    fn();
    pail.timeEnd(`benchmark-${name}`);
};

benchmark("array-sort", () => {
    const arr = Array.from({ length: 1000000 }, () => Math.random());
    arr.sort();
});
```

### Scoped Timers [#scoped-timers]

Combine timers with scoped loggers:

```typescript
const apiLogger = pail.scope("api");

apiLogger.time("request");
// ... work ...
apiLogger.timeEnd("request");
// Output: [api] Timer run for: 123 ms
```

## Timer States [#timer-states]

### Starting a Timer [#starting-a-timer]

If you try to start a timer that already exists, you'll get a warning:

```typescript
pail.time("my-timer");
pail.time("my-timer"); // Warning: Timer 'my-timer' already exists
```

### Stopping Non-Existent Timer [#stopping-non-existent-timer]

If you try to stop a timer that doesn't exist:

```typescript
pail.timeEnd("non-existent"); // Warning: Timer not found
```

### Using Last Timer [#using-last-timer]

If you don't specify a label, the most recently started timer is used:

```typescript
pail.time("first");
pail.time("second");
pail.timeEnd(); // Stops "second"
pail.timeEnd(); // Stops "first"
```

## Best Practices [#best-practices]

1. **Use descriptive labels** - Make timer names meaningful
2. **Nest timers logically** - Group related timers
3. **Clean up timers** - Always call `timeEnd()` to avoid memory leaks
4. **Combine with scopes** - Use scoped loggers for context
5. **Use in production** - Timers have minimal overhead

## Related [#related]

* [Basic Usage](/docs/packages/pail/usage/basic) - Basic logging operations
* [Scoped Loggers](/docs/packages/pail/usage/scoped) - Organize logs by context


# Wide Events (/docs/packages/pail/usage/wide-events)



# Wide Events [#wide-events]

Wide events let you accumulate structured context throughout an operation and emit a single, comprehensive log event at the end — instead of scattering multiple log calls across your code.

This pattern is inspired by [Charity Majors' wide events](https://charity.wtf/2019/02/05/logs-vs-structured-events/) approach to observability: instead of many small log lines, you build up one rich event per request or operation.

## Why Wide Events? [#why-wide-events]

Traditional logging looks like this:

```typescript
logger.info("Request started", { method: "POST", path: "/api/checkout" });
logger.info("User validated", { userId: 1 });
logger.info("Cart fetched", { items: 3, total: 9999 });
logger.info("Payment processed", { provider: "stripe" });
logger.info("Request completed", { status: 200, duration: "127ms" });
```

That's 5 log lines for one request — hard to correlate, expensive to store, and easy to miss context. With wide events:

```typescript
const ev = createWideEvent({ pail: logger, name: "api.checkout" });

ev.set({ user: { id: 1 } });
ev.info("User validated");
ev.set({ cart: { items: 3, total: 9999 } });
ev.info("Payment processed", { provider: "stripe" });
ev.finish({ status: 200 });
// One log line with ALL the context
```

## Basic Usage [#basic-usage]

```typescript
import { createPail } from "@visulima/pail";
import { createWideEvent } from "@visulima/pail/wide-event";

const logger = createPail();

const ev = createWideEvent({ pail: logger, name: "api.checkout" });

ev.set({ user: { id: 1, plan: "pro" } });
ev.info("Validated cart", { itemCount: 3 });
ev.set({ cart: { id: 42, items: 3, total: 9999 } });
ev.info("Payment processed");
ev.finish({ status: 200 });
```

This emits a single structured log:

```json
{
    "event": "api.checkout",
    "timestamp": "2026-03-14T10:23:45.612Z",
    "duration": "127ms",
    "duration_ms": 127,
    "status": 200,
    "user": { "id": 1, "plan": "pro" },
    "cart": { "id": 42, "items": 3, "total": 9999 },
    "requestLogs": [
        { "level": "info", "message": "Validated cart", "context": { "itemCount": 3 }, "timestamp": "..." },
        { "level": "info", "message": "Payment processed", "timestamp": "..." }
    ]
}
```

## Accumulating Context with `set()` [#accumulating-context-with-set]

Call `set()` as many times as you like. Data is deep-merged:

```typescript
ev.set({ user: { id: 1 } });
ev.set({ user: { plan: "pro" } });
// data = { user: { id: 1, plan: "pro" } }
```

Arrays are replaced, not concatenated:

```typescript
ev.set({ tags: ["a", "b"] });
ev.set({ tags: ["c"] });
// data = { tags: ["c"] }
```

## Lifecycle Logging [#lifecycle-logging]

Record what happened during the operation with `info()`, `warn()`, `error()`, and `debug()`:

```typescript
ev.info("Cart validated", { itemCount: 3 });
ev.warn("Rate limit approaching", { remaining: 5 });
ev.error("Payment retry needed", new Error("timeout"));
ev.debug("Cache miss for user profile");
```

Each entry is recorded with a timestamp and included in the `requestLogs` array of the emitted event.

## Level Escalation [#level-escalation]

The event's severity level auto-escalates and never de-escalates:

```typescript
const ev = createWideEvent({ pail: logger, name: "api.checkout" });

ev.getLevel(); // "info" (default)
ev.info("Step 1"); // still "info"
ev.warn("Rate limit approaching"); // escalates to "warn"
ev.info("Step 3"); // stays "warn"
ev.error("Payment failed"); // escalates to "error"
ev.warn("Another warning"); // stays "error"
```

The final emission uses the escalated level to determine which pail log type to use.

## Error Handling [#error-handling]

Attach errors to be serialized in the emitted event:

```typescript
// Via error() lifecycle method
ev.error("Payment failed", new Error("connection timeout"));

// Via setError()
ev.setError(new Error("connection timeout"));

// Via finish()
ev.finish({ status: 500, error: new Error("connection timeout") });
```

Errors are serialized with `name`, `message`, `stack`, `status`/`statusCode`, `data`, and the full `cause` chain.

## Finishing and Emitting [#finishing-and-emitting]

### `finish()` — for HTTP contexts [#finish--for-http-contexts]

```typescript
ev.finish({ status: 200 });
ev.finish({ status: 500, error: new Error("DB timeout") });
ev.finish(); // emit without status or error
```

### `emit()` — direct emission [#emit--direct-emission]

```typescript
ev.emit(); // emit with auto-detected type
ev.emit("warn"); // override the log type
```

Both `finish()` and `emit()` are idempotent — only the first call emits.

## Auto-Emit with Explicit Resource Management [#auto-emit-with-explicit-resource-management]

Wide events implement `Disposable` for use with TC39 Explicit Resource Management:

```typescript
{
    using ev = createWideEvent({ pail: logger, name: "api.checkout" });
    ev.set({ user: { id: 1 } });
    // auto-emits when scope exits
}
```

Disable auto-emit if you want manual control:

```typescript
const ev = createWideEvent({ pail: logger, name: "api.checkout", autoEmit: false });
// won't emit on dispose — you must call finish() or emit()
```

## Typed Data Shape [#typed-data-shape]

For type-safe context accumulation, provide a type parameter:

```typescript
interface CheckoutData {
    user: { id: number; plan: string };
    cart: { items: number; total: number };
}

const ev = createWideEvent<CheckoutData>({ pail: logger, name: "api.checkout" });

ev.set({ user: { id: 1, plan: "pro" } }); // typed
ev.set({ cart: { items: 3 } }); // partial is fine
```

## Chaining [#chaining]

All mutating methods return `this` for chaining:

```typescript
createWideEvent({ pail: logger, name: "api.checkout" })
    .set({ user: { id: 1 } })
    .info("User validated")
    .set({ cart: { items: 3 } })
    .info("Cart validated", { total: 9999 })
    .setStatus(200)
    .emit();
```

## Service Name [#service-name]

Tag events with a service name for multi-service architectures:

```typescript
const ev = createWideEvent({
    pail: logger,
    name: "api.checkout",
    service: "checkout-service",
});
// emitted event includes { service: "checkout-service" }
```

## Options Reference [#options-reference]

| Option     | Type          | Default  | Description                                |
| ---------- | ------------- | -------- | ------------------------------------------ |
| `name`     | `string`      | required | Event name, e.g. `"api.checkout"`          |
| `pail`     | Pail instance | required | The pail logger to emit through            |
| `service`  | `string`      | —        | Service name included in the emitted event |
| `type`     | `string`      | `"info"` | Base log type (may be escalated)           |
| `autoEmit` | `boolean`     | `true`   | Auto-emit on `Symbol.dispose`              |

## Methods Reference [#methods-reference]

| Method                   | Returns    | Description                            |
| ------------------------ | ---------- | -------------------------------------- |
| `set(data)`              | `this`     | Deep-merge partial data into the event |
| `info(msg, ctx?)`        | `this`     | Record an info-level lifecycle entry   |
| `warn(msg, ctx?)`        | `this`     | Record a warn-level entry; escalates   |
| `error(msg, err?, ctx?)` | `this`     | Record an error-level entry; escalates |
| `debug(msg, ctx?)`       | `this`     | Record a debug-level entry             |
| `setError(error)`        | `this`     | Attach an error; escalates to "error"  |
| `setStatus(code)`        | `this`     | Set HTTP status code                   |
| `finish(opts?)`          | `void`     | Set status/error and emit (once)       |
| `emit(typeOverride?)`    | `void`     | Emit the event directly (once)         |
| `getData()`              | `Readonly` | Get snapshot of accumulated data       |
| `getLevel()`             | `string`   | Get current severity level             |
| `getRequestLogs()`       | `readonly` | Get lifecycle log entries              |

## Next Steps [#next-steps]

* [Express Middleware](/docs/packages/pail/middleware/express) — Use wide events in Express apps
* [Fastify Plugin](/docs/packages/pail/middleware/fastify) — Use wide events in Fastify apps
* [Hono Middleware](/docs/packages/pail/middleware/hono) — Use wide events in Hono apps
* [Elysia Plugin](/docs/packages/pail/middleware/elysia) — Use wide events in Elysia apps
* [SvelteKit Hooks](/docs/packages/pail/middleware/sveltekit) — Use wide events in SvelteKit apps
* [Next.js Integration](/docs/packages/pail/middleware/nextjs) — Use wide events in Next.js apps


# API Reference (/docs/packages/path/api)



# API Reference [#api-reference]

Complete API documentation for **@visulima/path**.

## Imports [#imports]

### Main Module [#main-module]

```typescript
// Default import
import path from "@visulima/path";

// Named imports
import {
    basename,
    delimiter,
    dirname,
    extname,
    format,
    isAbsolute,
    join,
    matchesGlob,
    normalize,
    normalizeString,
    parse,
    relative,
    resolve,
    sep,
    toNamespacedPath,
} from "@visulima/path";
```

### Utilities [#utilities]

```typescript
import { filename, normalizeAliases, resolveAlias, reverseResolveAlias, isRelative, isBinaryPath, toPath, isWindows } from "@visulima/path/utils";
```

## Standard Path Methods [#standard-path-methods]

### `basename(path: string, suffix?: string): string` [#basenamepath-string-suffix-string-string]

Get the last portion of a path.

**Parameters:**

* `path` (string): The file path
* `suffix` (string, optional): Extension to remove

**Returns:** The filename

**Example:**

```typescript
basename("/home/user/file.txt");
// Returns: 'file.txt'

basename("/home/user/file.txt", ".txt");
// Returns: 'file'
```

***

### `delimiter: string` [#delimiter-string]

The platform-specific path delimiter (always `:` for consistency).

**Example:**

```typescript
console.log(delimiter);
// Returns: ':'
```

***

### `dirname(path: string): string` [#dirnamepath-string-string]

Get the directory name of a path.

**Parameters:**

* `path` (string): The file path

**Returns:** The directory portion

**Example:**

```typescript
dirname("/home/user/documents/file.txt");
// Returns: '/home/user/documents'
```

***

### `extname(path: string): string` [#extnamepath-string-string]

Get the file extension.

**Parameters:**

* `path` (string): The file path

**Returns:** The extension (including the dot)

**Example:**

```typescript
extname("file.txt");
// Returns: '.txt'

extname("archive.tar.gz");
// Returns: '.gz'
```

***

### `format(pathObject: ParsedPath): string` [#formatpathobject-parsedpath-string]

Create a path string from an object.

**Parameters:**

* `pathObject` (ParsedPath): Path components

**ParsedPath Interface:**

```typescript
interface ParsedPath {
    root?: string;
    dir?: string;
    base?: string;
    ext?: string;
    name?: string;
}
```

**Returns:** The formatted path string

**Example:**

```typescript
format({
    dir: "/home/user",
    base: "file.txt",
});
// Returns: '/home/user/file.txt'

format({
    root: "/",
    dir: "/home/user",
    name: "file",
    ext: ".txt",
});
// Returns: '/home/user/file.txt'
```

***

### `isAbsolute(path: string): boolean` [#isabsolutepath-string-boolean]

Determine if a path is absolute.

**Parameters:**

* `path` (string): The path to check

**Returns:** `true` if absolute, `false` otherwise

**Example:**

```typescript
isAbsolute("/home/user");
// Returns: true

isAbsolute("src/index.ts");
// Returns: false
```

***

### `join(...paths: string[]): string` [#joinpaths-string-string]

Join path segments.

**Parameters:**

* `...paths` (string\[]): Path segments to join

**Returns:** The joined path

**Example:**

```typescript
join("src", "components", "Button.tsx");
// Returns: 'src/components/Button.tsx'

join("/home", "user", "documents");
// Returns: '/home/user/documents'
```

***

### `matchesGlob(path: string, pattern: string): boolean` [#matchesglobpath-string-pattern-string-boolean]

Check if a path matches a glob pattern.

**Parameters:**

* `path` (string): The path to test
* `pattern` (string): The glob pattern

**Returns:** `true` if matches, `false` otherwise

**Example:**

```typescript
matchesGlob("src/index.ts", "src/**/*.ts");
// Returns: true

matchesGlob("test.js", "**/*.test.js");
// Returns: false
```

***

### `normalize(path: string): string` [#normalizepath-string-string]

Normalize a path by resolving `.` and `..`.

**Parameters:**

* `path` (string): The path to normalize

**Returns:** The normalized path

**Example:**

```typescript
normalize("/foo/bar//baz/asdf/quux/..");
// Returns: '/foo/bar/baz/asdf'

normalize("src/../dist/./index.js");
// Returns: 'dist/index.js'
```

***

### `normalizeString(path: string): string` [#normalizestringpath-string-string]

Low-level path normalization (internal use).

**Parameters:**

* `path` (string): The path to normalize

**Returns:** The normalized path string

***

### `parse(path: string): ParsedPath` [#parsepath-string-parsedpath]

Parse a path into its components.

**Parameters:**

* `path` (string): The path to parse

**Returns:** ParsedPath object

**ParsedPath Type:**

```typescript
type ParsedPath = {
    root: string; // Root (e.g., '/', 'C:/')
    dir: string; // Directory path
    base: string; // Filename with extension
    ext: string; // Extension (including dot)
    name: string; // Filename without extension
};
```

**Example:**

```typescript
parse("/home/user/file.txt");
// Returns: {
//   root: '/',
//   dir: '/home/user',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }
```

***

### `relative(from: string, to: string): string` [#relativefrom-string-to-string-string]

Get the relative path from one location to another.

**Parameters:**

* `from` (string): The starting path
* `to` (string): The destination path

**Returns:** The relative path

**Example:**

```typescript
relative("/home/user/docs", "/home/user/pictures");
// Returns: '../pictures'

relative("/src", "/dist");
// Returns: '../dist'
```

***

### `resolve(...paths: string[]): string` [#resolvepaths-string-string]

Resolve path segments into an absolute path.

**Parameters:**

* `...paths` (string\[]): Path segments to resolve

**Returns:** The absolute path

**Example:**

```typescript
resolve("src", "index.ts");
// Returns: '/current/working/directory/src/index.ts'

resolve("/home", "user", "documents");
// Returns: '/home/user/documents'
```

***

### `sep: string` [#sep-string]

The platform-specific path segment separator (always `/` for consistency).

**Example:**

```typescript
console.log(sep);
// Returns: '/'

"src/components".split(sep);
// Returns: ['src', 'components']
```

***

### `toNamespacedPath(path: string): string` [#tonamespacedpathpath-string-string]

Convert path to namespaced path (Windows UNC path support).

**Parameters:**

* `path` (string): The path to convert

**Returns:** The namespaced path

**Example:**

```typescript
toNamespacedPath("C:/Users/file.txt");
// Returns: 'C:/Users/file.txt' (normalized)
```

***

## Extra Utilities [#extra-utilities]

### `filename(path: string): string` [#filenamepath-string-string]

Get filename without extension.

**Parameters:**

* `path` (string): The file path

**Returns:** Filename without extension

**Example:**

```typescript
filename("/home/user/document.pdf");
// Returns: 'document'

filename("archive.tar.gz");
// Returns: 'archive.tar'
```

***

### `normalizeAliases(aliases: Record<string, string>): Record<string, string>` [#normalizealiasesaliases-recordstring-string-recordstring-string]

Normalize alias mappings for resolution.

**Parameters:**

* `aliases` (Record\<string, string>): Alias mappings

**Returns:** Normalized aliases

**Example:**

```typescript
normalizeAliases({
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
});
// Returns: Sorted and resolved alias mappings
```

***

### `resolveAlias(path: string, aliases: Record<string, string>): string` [#resolvealiaspath-string-aliases-recordstring-string-string]

Resolve a path using alias mappings.

**Parameters:**

* `path` (string): The path to resolve
* `aliases` (Record\<string, string>): Alias mappings

**Returns:** The resolved path

**Example:**

```typescript
const aliases = { "@/*": "./src/*" };
resolveAlias("@/config/app", aliases);
// Returns: './src/config/app'
```

***

### `reverseResolveAlias(path: string, aliases: Record<string, string>): string` [#reverseresolvealiaspath-string-aliases-recordstring-string-string]

Convert absolute path back to alias format.

**Parameters:**

* `path` (string): The absolute path
* `aliases` (Record\<string, string>): Alias mappings

**Returns:** The aliased path or original if no match

**Example:**

```typescript
const aliases = { "@/*": "./src/*" };
reverseResolveAlias("./src/config/app", aliases);
// Returns: '@/config/app'
```

***

### `isRelative(path: string): boolean` [#isrelativepath-string-boolean]

Check if a path is relative.

**Parameters:**

* `path` (string): The path to check

**Returns:** `true` if relative, `false` otherwise

**Example:**

```typescript
isRelative("./src/index.ts");
// Returns: true

isRelative("/home/user/file.txt");
// Returns: false
```

***

### `isBinaryPath(path: string): boolean` [#isbinarypathpath-string-boolean]

Check if a file path points to a binary file.

**Parameters:**

* `path` (string): The file path

**Returns:** `true` if binary file, `false` otherwise

**Example:**

```typescript
isBinaryPath("image.png");
// Returns: true

isBinaryPath("document.json");
// Returns: false
```

***

### `toPath(urlOrPath: string): string` [#topathurlorpath-string-string]

Convert file URL to path or return path as-is.

**Parameters:**

* `urlOrPath` (string): File URL or path string

**Returns:** The path string

**Example:**

```typescript
toPath("file:///home/user/file.txt");
// Returns: '/home/user/file.txt'

toPath("/home/user/file.txt");
// Returns: '/home/user/file.txt'
```

***

### `isWindows(): boolean` [#iswindows-boolean]

Check if running on Windows platform.

**Returns:** `true` if Windows, `false` otherwise

**Example:**

```typescript
if (isWindows()) {
    console.log("Running on Windows");
}
```

***

## TypeScript Types [#typescript-types]

### `Path` [#path]

The main path module type:

```typescript
import type { Path } from "@visulima/path";

const path: Path = await import("@visulima/path");
```

### `ParsedPath` [#parsedpath]

Object returned by `parse()`:

```typescript
interface ParsedPath {
    root: string;
    dir: string;
    base: string;
    ext: string;
    name: string;
}
```

## Compatibility [#compatibility]

### vs. Node.js `path` [#vs-nodejs-path]

All methods are compatible with Node.js `path` API:

| Method               | @visulima/path | Node.js path |
| -------------------- | -------------- | ------------ |
| `basename()`         | ✅              | ✅            |
| `delimiter`          | ✅              | ✅            |
| `dirname()`          | ✅              | ✅            |
| `extname()`          | ✅              | ✅            |
| `format()`           | ✅              | ✅            |
| `isAbsolute()`       | ✅              | ✅            |
| `join()`             | ✅              | ✅            |
| `normalize()`        | ✅              | ✅            |
| `parse()`            | ✅              | ✅            |
| `relative()`         | ✅              | ✅            |
| `resolve()`          | ✅              | ✅            |
| `sep`                | ✅              | ✅            |
| `toNamespacedPath()` | ✅              | ✅            |
| `posix`              | ⚠️ (stub)      | ✅            |
| `win32`              | ⚠️ (stub)      | ✅            |

**Note:** `posix` and `win32` are exported but point to the same normalized implementation.

### Extra Methods [#extra-methods]

Methods not in Node.js `path`:

| Method                  | Description                |
| ----------------------- | -------------------------- |
| `matchesGlob()`         | Glob pattern matching      |
| `filename()`            | Get name without extension |
| `normalizeAliases()`    | Prepare alias mappings     |
| `resolveAlias()`        | Resolve path aliases       |
| `reverseResolveAlias()` | Convert back to alias      |
| `isRelative()`          | Check if path is relative  |
| `isBinaryPath()`        | Check if file is binary    |
| `toPath()`              | Convert file URL to path   |
| `isWindows()`           | Check if on Windows        |


# Introduction (/docs/packages/path)



# @visulima/path [#visulimapath]

Drop-in replacement for Node.js `path` module with consistent cross-platform behavior. No more path separator headaches between Windows and POSIX systems.

## Why @visulima/path? [#why-visulimapath]

### The Problem with Node.js `path` [#the-problem-with-nodejs-path]

Node.js's built-in `path` module behaves differently on Windows vs. macOS/Linux:

```javascript
// On Windows
const path = require("node:path");
path.join("C:", "Users", "John"); // 'C:\\Users\\John'

// On macOS/Linux
const path = require("node:path");
path.join("C:", "Users", "John"); // 'C:/Users/John'
```

This creates **inconsistent code behavior** across operating systems, leading to bugs that only appear on specific platforms.

### The Solution [#the-solution]

**@visulima/path** normalizes all path operations to use forward slashes (`/`) consistently across all platforms, while maintaining full compatibility with Node.js `path` API.

```javascript
import { join } from "@visulima/path";

// Works consistently on ALL platforms
join("C:", "Users", "John"); // 'C:/Users/John'
join("/home", "user", "docs"); // '/home/user/docs'
```

## Key Features [#key-features]

**Cross-Platform Consistency**

* **Normalized paths** - Always uses forward slashes (`/`) regardless of OS
* **Predictable behavior** - Same output on Windows, macOS, and Linux
* **No surprises** - Write once, works everywhere

**Drop-in Replacement**

* **100% compatible** with Node.js `path` API
* **No code changes** required for migration
* **Same function signatures** as Node.js path module

**Modern & Lightweight**

* **Written in TypeScript** with full type definitions
* **ESM and CommonJS** support
* **No Node.js dependency** - Works in any JavaScript runtime
* **Zero dependencies** (except for binary detection)

**Extra Utilities**

* **Alias resolution** - Resolve path aliases like TypeScript/Webpack
* **Binary detection** - Check if a path points to a binary file
* **Relative path checking** - Determine if a path is relative
* **File extension utilities** - Extract filename without extension

## Quick Start [#quick-start]

### Installation [#installation]

```bash npm2yarn
npm install @visulima/path
```

### Basic Usage [#basic-usage]

```typescript
import { resolve, join, basename, dirname } from "@visulima/path";

// Join paths
const configPath = join("src", "config", "app.json");
// Result: 'src/config/app.json' (on ALL platforms)

// Resolve absolute path
const absolutePath = resolve("docs", "guide.md");
// Result: '/current/working/dir/docs/guide.md'

// Get filename
const filename = basename("/home/user/document.pdf");
// Result: 'document.pdf'

// Get directory
const directory = dirname("/home/user/document.pdf");
// Result: '/home/user'
```

### With Extra Utilities [#with-extra-utilities]

```typescript
import { filename, resolveAlias, isBinaryPath } from "@visulima/path/utils";

// Get filename without extension
const name = filename("/home/user/document.pdf");
// Result: 'document'

// Resolve TypeScript-style aliases
const aliases = { "@/*": "./src/*" };
const resolved = resolveAlias("@/components/Button", aliases);
// Result: './src/components/Button'

// Check if path is binary
const isBinary = isBinaryPath("image.png");
// Result: true
```

## Use Cases [#use-cases]

### Build Tools & Bundlers [#build-tools--bundlers]

Ensure consistent path handling in build scripts across developer machines:

```typescript
import { join, resolve } from "@visulima/path";

const srcDir = resolve("src");
const distDir = resolve("dist");
const entryPoint = join(srcDir, "index.ts");

// Always produces forward slashes, regardless of OS
console.log(entryPoint); // '/project/src/index.ts'
```

### File System Operations [#file-system-operations]

Handle paths consistently when working with files:

```typescript
import { join, dirname, basename, extname } from "@visulima/path";
import { readFile } from "node:fs/promises";

async function processFile(filePath: string) {
    const dir = dirname(filePath);
    const name = basename(filePath, extname(filePath));
    const outputPath = join(dir, "processed", `${name}.out`);

    // Paths work consistently on all platforms
    const content = await readFile(filePath, "utf-8");
    // ... process content
}
```

### TypeScript Path Aliases [#typescript-path-aliases]

Resolve TypeScript path aliases at runtime:

```typescript
import { resolveAlias, normalizeAliases } from "@visulima/path/utils";

const tsConfig = {
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
    "@utils/*": "./src/utils/*",
};

const aliases = normalizeAliases(tsConfig);

// Resolve imports
const resolved = resolveAlias("@/config/app", aliases);
// Result: './src/config/app'
```

## Comparison with Alternatives [#comparison-with-alternatives]

### vs. Node.js `path` [#vs-nodejs-path]

| Feature                    | @visulima/path | Node.js path |
| -------------------------- | -------------- | ------------ |
| Cross-platform consistency | ✅              | ❌            |
| Forward slash everywhere   | ✅              | ❌            |
| Drop-in replacement        | ✅              | N/A          |
| TypeScript support         | ✅              | ✅            |
| Extra utilities            | ✅              | ❌            |
| No Node.js dependency      | ✅              | ❌            |

### vs. upath [#vs-upath]

| Feature             | @visulima/path | upath |
| ------------------- | -------------- | ----- |
| Modern ESM          | ✅              | ❌     |
| TypeScript          | ✅              | ⚠️    |
| Maintained          | ✅              | ⚠️    |
| Extra utilities     | ✅              | ✅     |
| Runtime independent | ✅              | ❌     |

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/path/installation">
    Learn how to install and import the package
  </Card>

  <Card title="Usage Guide" href="/docs/packages/path/usage">
    Explore all path methods and utilities
  </Card>

  <Card title="API Reference" href="/docs/packages/path/api">
    Complete API documentation
  </Card>
</Cards>

## Browser and Server Support [#browser-and-server-support]

### Node.js [#nodejs]

* ✅ Node.js 22.13 - 25.x
* ✅ ESM and CommonJS support

### Runtimes [#runtimes]

* ✅ Node.js
* ✅ Deno
* ✅ Bun
* ✅ Browser (with bundler)
* ✅ Edge runtimes (Cloudflare Workers, Vercel Edge)

### Operating Systems [#operating-systems]

* ✅ Windows
* ✅ macOS
* ✅ Linux
* ✅ Any POSIX-compliant OS


# Installation (/docs/packages/path/installation)



# Installation [#installation]

## Package Manager [#package-manager]

Install **@visulima/path** using your preferred package manager:

```bash npm2yarn
npm install @visulima/path
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher
* **TypeScript:** 5.0+ (optional, for TypeScript projects)

## Import Methods [#import-methods]

### Node.js (ESM) [#nodejs-esm]

```typescript
// Default import
import path from "@visulima/path";

// Named imports (recommended)
import { resolve, join, basename, dirname, extname } from "@visulima/path";

// Extra utilities
import { filename, resolveAlias, isBinaryPath } from "@visulima/path/utils";
```

### Node.js (CommonJS) [#nodejs-commonjs]

```javascript
// Default import
const path = require("@visulima/path");

// Named imports
const { resolve, join, basename, dirname } = require("@visulima/path");

// Extra utilities
const { filename, resolveAlias } = require("@visulima/path/utils");
```

### TypeScript [#typescript]

TypeScript definitions are included automatically:

```typescript
import type { Path } from "@visulima/path";
import path from "@visulima/path";

// Full type checking and autocomplete
const result: string = path.join("src", "index.ts");
```

## Migration from Node.js `path` [#migration-from-nodejs-path]

### Drop-in Replacement [#drop-in-replacement]

Simply replace your Node.js `path` imports:

```typescript
// Before
import path from "node:path";
// or
const path = require("node:path");

// After
import path from "@visulima/path";
// or
const path = require("@visulima/path");
```

**No other code changes needed!** All Node.js `path` methods work identically.

### Named Imports [#named-imports]

```typescript
// Before
import { resolve, join } from "node:path";

// After
import { resolve, join } from "@visulima/path";
```

### What Changes? [#what-changes]

**Output normalization** - All paths use forward slashes:

```typescript
// Node.js path (on Windows)
path.join("C:", "Users", "John"); // 'C:\\Users\\John'

// @visulima/path (on Windows)
path.join("C:", "Users", "John"); // 'C:/Users/John'
```

This ensures **consistent behavior** across all operating systems.

## Verification [#verification]

Verify your installation works correctly:

```typescript
import { resolve, join, basename } from "@visulima/path";

console.log(join("src", "config", "app.json"));
// Output: 'src/config/app.json'

console.log(resolve("docs", "guide.md"));
// Output: '/current/directory/docs/guide.md'

console.log(basename("/home/user/document.pdf"));
// Output: 'document.pdf'
```

If you see output similar to above, installation is successful!

## Subpath Exports [#subpath-exports]

The package provides subpath exports for extra utilities:

```typescript
// Main path module
import path from "@visulima/path";
import { join, resolve } from "@visulima/path";

// Extra utilities
import { filename, normalizeAliases, resolveAlias, reverseResolveAlias, isRelative, isBinaryPath, toPath, isWindows } from "@visulima/path/utils";
```

## Using with TypeScript [#using-with-typescript]

### Type Definitions [#type-definitions]

Full TypeScript support is included:

```typescript
import type { Path } from "@visulima/path";
import type { ParsedPath } from "@visulima/path";

const myPath: Path = await import("@visulima/path");
```

### Type Safety [#type-safety]

All methods are fully typed:

```typescript
import { parse, format } from "@visulima/path";

// parse() returns ParsedPath type
const parsed = parse("/home/user/file.txt");
// parsed.root: string
// parsed.dir: string
// parsed.base: string
// parsed.ext: string
// parsed.name: string

// format() accepts ParsedPath
const formatted = format({
    root: "/",
    dir: "/home/user",
    base: "file.txt",
});
```

## Runtime Support [#runtime-support]

**@visulima/path** works in multiple JavaScript runtimes:

### Node.js [#nodejs]

```typescript
import { join } from "@visulima/path";
const config = join("src", "config.json");
```

### Deno [#deno]

```typescript
import { join } from "npm:@visulima/path";
const config = join("src", "config.json");
```

### Bun [#bun]

```typescript
import { join } from "@visulima/path";
const config = join("src", "config.json");
```

### Browsers (with bundlers) [#browsers-with-bundlers]

```typescript
// Works with Vite, Webpack, Rollup, etc.
import { join } from "@visulima/path";
const assetPath = join("assets", "images", "logo.png");
```

## Common Setup Patterns [#common-setup-patterns]

### In a Build Tool [#in-a-build-tool]

```typescript
// vite.config.ts
import { resolve } from "@visulima/path";
import { defineConfig } from "vite";

export default defineConfig({
    resolve: {
        alias: {
            "@": resolve("src"),
        },
    },
});
```

### In a Node.js Script [#in-a-nodejs-script]

```typescript
#!/usr/bin/env node
import { join, resolve, dirname } from "@visulima/path";
import { fileURLToPath } from "node:url";

// Get current file directory
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Resolve paths relative to script
const configPath = join(__dirname, "config", "app.json");
```

### In a TypeScript Project [#in-a-typescript-project]

```typescript
// src/utils/paths.ts
import { join, resolve } from "@visulima/path";

export const ROOT_DIR = resolve(process.cwd());
export const SRC_DIR = join(ROOT_DIR, "src");
export const BUILD_DIR = join(ROOT_DIR, "dist");
export const CONFIG_FILE = join(ROOT_DIR, "config.json");
```

## Troubleshooting [#troubleshooting]

### Module Not Found [#module-not-found]

If you see `Cannot find module '@visulima/path'`:

```bash npm2yarn
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

### TypeScript Errors [#typescript-errors]

Ensure your `tsconfig.json` includes:

```json
{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true,
        "module": "ES2020"
    }
}
```

### Subpath Not Resolved [#subpath-not-resolved]

If `@visulima/path/utils` doesn't work, verify Node.js version:

```bash
node --version
# Should be 22.13 or higher
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/path/usage">
    Learn how to use all path methods
  </Card>

  <Card title="API Reference" href="/docs/packages/path/api">
    Complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/path/usage)



# Usage Guide [#usage-guide]

Complete guide to using **@visulima/path** for cross-platform path manipulation.

## Standard Path Methods [#standard-path-methods]

All standard Node.js `path` methods are available with consistent cross-platform behavior.

### Join Paths [#join-paths]

Combine path segments into a single path:

```typescript
import { join } from "@visulima/path";

join("src", "components", "Button.tsx");
// Result: 'src/components/Button.tsx'

join("/home", "user", "documents", "file.txt");
// Result: '/home/user/documents/file.txt'

join("C:", "Users", "John", "Desktop");
// Result: 'C:/Users/John/Desktop' (forward slashes on ALL platforms)

// Handles edge cases
join(""); // Result: '.'
join("/foo", "bar", "", "baz");
// Result: '/foo/bar/baz'
```

### Resolve Absolute Paths [#resolve-absolute-paths]

Convert relative paths to absolute paths:

```typescript
import { resolve } from "@visulima/path";

// Resolve from current directory
resolve("src", "index.ts");
// Result: '/current/working/directory/src/index.ts'

// With absolute path
resolve("/home/user", "documents", "file.txt");
// Result: '/home/user/documents/file.txt'

// Multiple relative segments
resolve("docs", "../src", "config.json");
// Result: '/current/working/directory/src/config.json'

// No arguments returns cwd
resolve();
// Result: '/current/working/directory'
```

### Get Directory Name [#get-directory-name]

Extract the directory portion of a path:

```typescript
import { dirname } from "@visulima/path";

dirname("/home/user/documents/file.txt");
// Result: '/home/user/documents'

dirname("src/components/Button.tsx");
// Result: 'src/components'

dirname("/foo/bar/");
// Result: '/foo/bar'

dirname("file.txt");
// Result: '.'

dirname("/");
// Result: '/'
```

### Get Base Name [#get-base-name]

Extract the last portion of a path:

```typescript
import { basename } from "@visulima/path";

basename("/home/user/documents/file.txt");
// Result: 'file.txt'

basename("/home/user/documents/");
// Result: 'documents'

// With extension removal
basename("/home/user/document.pdf", ".pdf");
// Result: 'document'

basename("src/components/Button.tsx", ".tsx");
// Result: 'Button'
```

### Get File Extension [#get-file-extension]

Extract the file extension:

```typescript
import { extname } from "@visulima/path";

extname("file.txt");
// Result: '.txt'

extname("document.pdf");
// Result: '.pdf'

extname("archive.tar.gz");
// Result: '.gz'

extname("README");
// Result: ''

extname(".gitignore");
// Result: ''
```

### Normalize Path [#normalize-path]

Clean up path by resolving `.` and `..`:

```typescript
import { normalize } from "@visulima/path";

normalize("/foo/bar//baz/asdf/quux/..");
// Result: '/foo/bar/baz/asdf'

normalize("src/../dist/./index.js");
// Result: 'dist/index.js'

normalize("C:\\Users\\..\\John");
// Result: 'C:/John' (normalized to forward slashes)

// Preserves trailing slash
normalize("/foo/bar/");
// Result: '/foo/bar/'
```

### Check Absolute Path [#check-absolute-path]

Determine if a path is absolute:

```typescript
import { isAbsolute } from "@visulima/path";

isAbsolute("/home/user");
// Result: true

isAbsolute("C:/Users/John");
// Result: true

isAbsolute("src/index.ts");
// Result: false

isAbsolute("../config.json");
// Result: false
```

### Get Relative Path [#get-relative-path]

Get the relative path from one location to another:

```typescript
import { relative } from "@visulima/path";

relative("/home/user/docs", "/home/user/docs/file.txt");
// Result: 'file.txt'

relative("/home/user/docs", "/home/user/pictures/image.png");
// Result: '../pictures/image.png'

relative("/src", "/dist");
// Result: '../dist'

// Same path
relative("/foo/bar", "/foo/bar");
// Result: ''
```

### Parse Path [#parse-path]

Parse a path into its components:

```typescript
import { parse } from "@visulima/path";

const parsed = parse("/home/user/documents/file.txt");
// Result: {
//   root: '/',
//   dir: '/home/user/documents',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }

const windowsParsed = parse("C:/Users/John/document.pdf");
// Result: {
//   root: 'C:/',
//   dir: 'C:/Users/John',
//   base: 'document.pdf',
//   ext: '.pdf',
//   name: 'document'
// }
```

### Format Path [#format-path]

Build a path from components:

```typescript
import { format } from "@visulima/path";

format({
    root: "/",
    dir: "/home/user",
    base: "file.txt",
});
// Result: '/home/user/file.txt'

format({
    dir: "/home/user/documents",
    name: "report",
    ext: ".pdf",
});
// Result: '/home/user/documents/report.pdf'

// base takes precedence over name + ext
format({
    dir: "/foo",
    base: "file.txt",
    name: "ignored",
    ext: ".ignored",
});
// Result: '/foo/file.txt'
```

### Match Glob Pattern [#match-glob-pattern]

Check if a path matches a glob pattern:

```typescript
import { matchesGlob } from "@visulima/path";

matchesGlob("src/index.ts", "src/**/*.ts");
// Result: true

matchesGlob("test/unit/user.test.js", "**/*.test.js");
// Result: true

matchesGlob("README.md", "*.txt");
// Result: false
```

### Constants [#constants]

Path separator constants:

```typescript
import { sep, delimiter } from "@visulima/path";

// Path segment separator (always '/')
console.log(sep);
// Result: '/'

// PATH environment variable delimiter
console.log(delimiter);
// Result: ':' (or ';' on original Windows, but normalized)
```

## Extra Utilities [#extra-utilities]

Import extra utilities from `@visulima/path/utils`:

### Get Filename Without Extension [#get-filename-without-extension]

```typescript
import { filename } from "@visulima/path/utils";

filename("/home/user/document.pdf");
// Result: 'document'

filename("src/components/Button.tsx");
// Result: 'Button'

filename("archive.tar.gz");
// Result: 'archive.tar'
```

### Normalize Path Aliases [#normalize-path-aliases]

Prepare alias mappings for resolution:

```typescript
import { normalizeAliases } from "@visulima/path/utils";

const aliases = normalizeAliases({
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
    "@utils/*": "./src/utils/*",
});

// Aliases are sorted from specific to general
// and resolved relative to each other
```

### Resolve Path Aliases [#resolve-path-aliases]

Resolve TypeScript/Webpack-style path aliases:

```typescript
import { resolveAlias, normalizeAliases } from "@visulima/path/utils";

const aliases = normalizeAliases({
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
});

resolveAlias("@/config/app", aliases);
// Result: './src/config/app'

resolveAlias("@components/Button", aliases);
// Result: './src/components/Button'

// Non-matching paths return unchanged
resolveAlias("./local/file", aliases);
// Result: './local/file'
```

### Reverse Resolve Aliases [#reverse-resolve-aliases]

Convert absolute paths back to alias format:

```typescript
import { reverseResolveAlias, normalizeAliases } from "@visulima/path/utils";

const aliases = normalizeAliases({
    "@/*": "./src/*",
});

reverseResolveAlias("./src/config/app", aliases);
// Result: '@/config/app'

reverseResolveAlias("./dist/bundle.js", aliases);
// Result: './dist/bundle.js' (no matching alias)
```

### Check if Path is Relative [#check-if-path-is-relative]

```typescript
import { isRelative } from "@visulima/path/utils";

isRelative("./src/index.ts");
// Result: true

isRelative("../config.json");
// Result: true

isRelative("/home/user/file.txt");
// Result: false

isRelative("C:/Users/file.txt");
// Result: false
```

### Check if Path is Binary [#check-if-path-is-binary]

Detect if a file path points to a binary file:

```typescript
import { isBinaryPath } from "@visulima/path/utils";

isBinaryPath("image.png");
// Result: true

isBinaryPath("document.pdf");
// Result: true

isBinaryPath("video.mp4");
// Result: true

isBinaryPath("script.js");
// Result: false

isBinaryPath("data.json");
// Result: false
```

### Convert File URL to Path [#convert-file-url-to-path]

```typescript
import { toPath } from "@visulima/path/utils";

toPath("file:///home/user/documents/file.txt");
// Result: '/home/user/documents/file.txt'

toPath("file:///C:/Users/John/document.pdf");
// Result: 'C:/Users/John/document.pdf'

// Regular paths pass through
toPath("/home/user/file.txt");
// Result: '/home/user/file.txt'
```

### Check if Running on Windows [#check-if-running-on-windows]

```typescript
import { isWindows } from "@visulima/path/utils";

if (isWindows()) {
    console.log("Running on Windows");
} else {
    console.log("Running on POSIX system");
}
```

## Common Patterns [#common-patterns]

### Build Configuration Paths [#build-configuration-paths]

```typescript
import { resolve, join, dirname } from "@visulima/path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export const paths = {
    root: resolve(__dirname, ".."),
    src: resolve(__dirname, "../src"),
    dist: resolve(__dirname, "../dist"),
    public: resolve(__dirname, "../public"),
    config: join(__dirname, "../config"),
};
```

### File Operations with Consistent Paths [#file-operations-with-consistent-paths]

```typescript
import { join, extname, basename } from "@visulima/path";
import { readdir } from "node:fs/promises";

async function findTypeScriptFiles(dir: string): Promise<string[]> {
    const entries = await readdir(dir, { withFileTypes: true });
    const files: string[] = [];

    for (const entry of entries) {
        const fullPath = join(dir, entry.name);

        if (entry.isDirectory()) {
            files.push(...(await findTypeScriptFiles(fullPath)));
        } else if (extname(entry.name) === ".ts") {
            files.push(fullPath);
        }
    }

    return files;
}
```

### Alias Resolution System [#alias-resolution-system]

```typescript
import { resolveAlias, normalizeAliases, join } from "@visulima/path";

class ModuleResolver {
    private aliases: Record<string, string>;

    constructor(aliasConfig: Record<string, string>) {
        this.aliases = normalizeAliases(aliasConfig);
    }

    resolve(importPath: string, fromFile: string): string {
        // Resolve alias
        const resolved = resolveAlias(importPath, this.aliases);

        // If relative, resolve from importing file
        if (resolved.startsWith(".")) {
            return join(dirname(fromFile), resolved);
        }

        return resolved;
    }
}

// Usage
const resolver = new ModuleResolver({
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
});

const modulePath = resolver.resolve("@/utils/helper", "src/index.ts");
// Result: './src/utils/helper'
```

### Cross-Platform Script Paths [#cross-platform-script-paths]

```typescript
import { join, resolve, normalize } from "@visulima/path";

// Always use forward slashes - works everywhere
const config = {
    entry: join("src", "index.ts"),
    output: join("dist", "bundle.js"),
    assets: join("public", "assets"),
};

// Resolve to absolute paths
const absolute = {
    entry: resolve(config.entry),
    output: resolve(config.output),
    assets: resolve(config.assets),
};

console.log(absolute);
// All paths use forward slashes regardless of OS
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/path/api">
    Complete API documentation with all method signatures
  </Card>
</Cards>


# Getting Started (/docs/packages/progress-bar/getting-started)



## Installation [#installation]

Install the package using your preferred package manager:



<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="pnpm">
    ```bash
    pnpm add @visulima/progress-bar
    ```
  </Tab>

  <Tab value="npm">
    `bash npm install @visulima/progress-bar `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/progress-bar `
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @visulima/progress-bar
    ```
  </Tab>
</Tabs>

## Basic Usage [#basic-usage]

### Simple Progress Bar [#simple-progress-bar]

```typescript
import { ProgressBar } from "@visulima/progress-bar";

const bar = new ProgressBar({ total: 100 });

bar.update(25);
console.log(bar.render());
// progress [██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 25% | ETA: 3s | 25/100

bar.update(100);
console.log(bar.render());
// progress [████████████████████████████████████████] 100% | ETA: 0s | 100/100
```

### Custom Format [#custom-format]

```typescript
const bar = new ProgressBar(
    {
        total: 200,
        format: "{task} [{bar}] {percentage}% | {value}/{total}",
    },
    undefined,
    { task: "Downloading" },
);

bar.update(100);
console.log(bar.render());
// Downloading [████████████████████░░░░░░░░░░░░░░░░░░░░] 50% | 100/200
```

### Different Styles [#different-styles]

```typescript
// ASCII style
const ascii = new ProgressBar({ total: 100, style: "ascii", format: "[{bar}]", width: 20 });
ascii.update(50);
console.log(ascii.render()); // [##########----------]

// Braille style with pill caps
const braille = new ProgressBar({ total: 100, style: "braille", format: "[{bar}]", width: 20 });
braille.update(50);
console.log(braille.render()); // [⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⠤⠤⠤⠤⠤⠤⠤⠤⠤⡷]
```

### With Interactive Manager [#with-interactive-manager]

For real-time terminal updates, use with `@visulima/interactive-manager`:

```bash
pnpm add @visulima/interactive-manager
```

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
import { ProgressBar } from "@visulima/progress-bar";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

const bar = new ProgressBar({ total: 100 }, manager);
bar.start();

// Progress updates render automatically
for (let i = 0; i <= 100; i++) {
    bar.update(i);
    await new Promise((r) => setTimeout(r, 50));
}

bar.stop();
```

## See Also [#see-also]

* [Usage Guide](/docs/packages/progress-bar/usage) - Complete API reference
* [Styles Reference](/docs/packages/progress-bar/styles) - All available bar styles


# Progress Bar (/docs/packages/progress-bar)



A terminal progress bar library with multiple styles, gradient support, composite multi-bar rendering, and peak markers.

## Features [#features]

* **7 Built-in Styles** - Classic, grey, rect, filled, solid, ASCII, braille
* **Multi-bar Support** - Display multiple progress bars simultaneously
* **Composite Mode** - Overlay multiple bars in a single visualization
* **Gradient Arrays** - Smooth sub-character progress transitions
* **Peak Markers** - Show peak values on the bar
* **Braille Pill Caps** - Rounded pill-shaped bars with braille characters
* **Custom Formatting** - Template-based output with payload placeholders
* **TypeScript** - Full type support out of the box

## Quick Example [#quick-example]

```typescript
import { ProgressBar } from "@visulima/progress-bar";

const bar = new ProgressBar({
    total: 100,
    style: "shades_classic",
});

console.log(bar.render()); // progress [░░░░░░░░░░░░░░░░░░░░] 0% | ETA: 0s | 0/100

bar.update(50);
console.log(bar.render()); // progress [██████████░░░░░░░░░░] 50% | ETA: ...

bar.update(100);
console.log(bar.render()); // progress [████████████████████] 100% | ETA: 0s | 100/100
```

## Next Steps [#next-steps]

* [Getting Started](/docs/packages/progress-bar/getting-started) - Install and set up
* [Usage Guide](/docs/packages/progress-bar/usage) - Complete API reference
* [Styles Reference](/docs/packages/progress-bar/styles) - All available bar styles


# Styles Reference (/docs/packages/progress-bar/styles)



## Built-in Styles [#built-in-styles]

All styles can be used via the `style` option:

```typescript
import { ProgressBar } from "@visulima/progress-bar";

const bar = new ProgressBar({
    total: 100,
    style: "shades_classic", // Any style name below
    format: "[{bar}]",
    width: 20,
});
```

### shades\_classic (default) [#shades_classic-default]

Classic block/shade characters.

```
[██████████░░░░░░░░░░] 50%
[████████████████████] 100%
```

Complete: `█` | Incomplete: `░`

### shades\_grey [#shades_grey]

Grey gradient shading.

```
[▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░] 50%
```

Complete: `▓` | Incomplete: `░`

### rect [#rect]

Rectangle block characters.

```
[▬▬▬▬▬▬▬▬▬▬▭▭▭▭▭▭▭▭▭▭] 50%
```

Complete: `▬` | Incomplete: `▭`

### filled [#filled]

Filled blocks with space background.

```
[██████████          ] 50%
```

Complete: `█` | Incomplete: ` ` (space)

### solid [#solid]

Same as filled — solid blocks with space.

```
[██████████          ] 50%
```

Complete: `█` | Incomplete: ` ` (space)

### ascii [#ascii]

Plain ASCII characters, works everywhere.

```
[##########----------] 50%
```

Complete: `#` | Incomplete: `-`

### braille [#braille]

Unicode braille dots with automatic pill-shaped caps.

```
[⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⠤⠤⠤⠤⠤⠤⠤⠤⠤⡷] 50%
```

Complete: `⣿` | Incomplete: `⠤` | Left cap: `⢾` | Right cap: `⡷`

The braille style automatically applies rounded caps unless `roundedCaps: false` is set.

## Custom Characters [#custom-characters]

Override any style's characters:

```typescript
// Custom complete/incomplete chars
const bar = new ProgressBar({
    total: 100,
    barCompleteChar: "=",
    barIncompleteChar: " ",
    format: "[{bar}]",
});

bar.update(50);
// [==========          ]
```

## Gradient Arrays [#gradient-arrays]

Pass arrays for smooth sub-character transitions:

```typescript
const bar = new ProgressBar({
    total: 100,
    barCompleteChar: ["░", "▒", "▓", "█"], // Light to heavy
    barIncompleteChar: " ",
    format: "[{bar}]",
    width: 20,
});
```

The gradient boundary shows intermediate characters at the fill edge, creating smoother progress visualization.

## Peak Markers [#peak-markers]

Show a peak value on the bar:

```typescript
const bar = new ProgressBar({
    total: 100,
    format: "[{bar}]",
    width: 20,
});

bar.setPeak(80);
bar.update(50);
// The peak marker appears at the 80% position
```

## Rounded Caps [#rounded-caps]

Pill-shaped bars using braille cap characters:

```typescript
// Automatic with braille style
const bar = new ProgressBar({ total: 100, style: "braille" });

// Manual with any style
const bar2 = new ProgressBar({
    total: 100,
    roundedCaps: true,
    style: "shades_classic",
});

// Disable for braille
const bar3 = new ProgressBar({
    total: 100,
    style: "braille",
    roundedCaps: false,
});
```


# Usage Guide (/docs/packages/progress-bar/usage)



## ProgressBar [#progressbar]

### Constructor [#constructor]

```typescript
import { ProgressBar } from '@visulima/progress-bar';

const bar = new ProgressBar(options, interactiveManager?, payload?);
```

#### Options [#options]

| Option              | Type                 | Default                                                              | Description                           |
| ------------------- | -------------------- | -------------------------------------------------------------------- | ------------------------------------- |
| `total`             | `number`             | **required**                                                         | Total value for 100%                  |
| `current`           | `number`             | `0`                                                                  | Starting value                        |
| `width`             | `number`             | `40`                                                                 | Bar width in characters               |
| `format`            | `string`             | `"progress [{bar}] {percentage}% \| ETA: {eta}s \| {value}/{total}"` | Output format template                |
| `style`             | `ProgressBarStyle`   | `"shades_classic"`                                                   | Bar character style                   |
| `barCompleteChar`   | `string \| string[]` | Style default                                                        | Complete portion character(s)         |
| `barIncompleteChar` | `string \| string[]` | Style default                                                        | Incomplete portion character(s)       |
| `barGlue`           | `string`             | `""`                                                                 | Separator between complete/incomplete |
| `fps`               | `number`             | `10`                                                                 | Max frames per second                 |
| `peak`              | `number`             | —                                                                    | Peak marker position                  |
| `peakChar`          | `string`             | Complete char                                                        | Character for peak marker             |
| `roundedCaps`       | `boolean`            | `true` for braille                                                   | Pill-shaped bar ends                  |

### Methods [#methods]

#### update(current, payload?) [#updatecurrent-payload]

Update the progress value.

```typescript
bar.update(50);
bar.update(75, { speed: "2.5 MB/s" });
```

#### increment(step?, payload?) [#incrementstep-payload]

Increment by a step value (default: 1).

```typescript
bar.increment(); // +1
bar.increment(10); // +10
bar.increment(5, { file: "data.json" });
```

#### render() [#render]

Render the progress bar as a string.

```typescript
const output = bar.render();
console.log(output);
```

#### start(total?, startValue?, payload?) [#starttotal-startvalue-payload]

Start the progress bar (hooks into interactive manager if provided).

```typescript
bar.start();
bar.start(200); // Override total
bar.start(200, 50); // Override total and start value
```

#### stop() [#stop]

Stop the progress bar and unhook from interactive manager.

```typescript
bar.stop();
```

#### setPeak(peak) [#setpeakpeak]

Set the peak marker position.

```typescript
bar.setPeak(75); // Show peak at 75%
```

### Format Placeholders [#format-placeholders]

| Placeholder    | Description                         |
| -------------- | ----------------------------------- |
| `{bar}`        | The progress bar characters         |
| `{percentage}` | Current percentage (0-100)          |
| `{value}`      | Current value                       |
| `{total}`      | Total value                         |
| `{eta}`        | Estimated time remaining in seconds |
| `{custom}`     | Any key from the payload object     |

```typescript
const bar = new ProgressBar(
    {
        total: 100,
        format: "{task} [{bar}] {percentage}% | {speed}",
    },
    undefined,
    { task: "Upload", speed: "0 KB/s" },
);

bar.update(50, { speed: "1.2 MB/s" });
```

## MultiProgressBar [#multiprogressbar]

Display multiple progress bars simultaneously.

### Constructor [#constructor-1]

```typescript
import { MultiProgressBar } from '@visulima/progress-bar';

const multi = new MultiProgressBar(options?, interactiveManager?);
```

#### Options [#options-1]

| Option              | Type                 | Default            | Description              |
| ------------------- | -------------------- | ------------------ | ------------------------ |
| `format`            | `string`             | Default format     | Format for all bars      |
| `style`             | `ProgressBarStyle`   | `"shades_classic"` | Style for all bars       |
| `barCompleteChar`   | `string \| string[]` | Style default      | Complete char            |
| `barIncompleteChar` | `string \| string[]` | Style default      | Incomplete char          |
| `barGlue`           | `string`             | `""`               | Bar separator            |
| `fps`               | `number`             | `10`               | Max FPS                  |
| `composite`         | `boolean`            | `false`            | Overlay bars in one line |

### Methods [#methods-1]

#### create(total, current?, payload?) [#createtotal-current-payload]

Create a new progress bar within the multi-bar manager.

```typescript
const bar1 = multi.create(100);
const bar2 = multi.create(200, 50);
const bar3 = multi.create(150, 0, { task: "Build" });
```

#### remove(bar) [#removebar]

Remove a progress bar from the manager.

```typescript
multi.remove(bar1);
```

#### stop() [#stop-1]

Stop all progress bars.

```typescript
multi.stop();
```

#### setBarColor(bar, color) [#setbarcolorbar-color]

Set a color function for a specific bar.

```typescript
multi.setBarColor(bar1, (text) => `\x1b[32m${text}\x1b[0m`);
```

### Composite Mode [#composite-mode]

Overlay multiple bars in a single line:

```typescript
const multi = new MultiProgressBar({ composite: true }, manager);

const download = multi.create(100);
const extract = multi.create(100);

download.update(80);
extract.update(40);
// Renders as a single composite bar showing both progress values
```

## Utility Functions [#utility-functions]

### getBarChar(char, style, complete?) [#getbarcharchar-style-complete]

Get the appropriate bar character for a style.

```typescript
import { getBarChar } from "@visulima/progress-bar";

getBarChar(undefined, "ascii", true); // '#'
getBarChar(undefined, "ascii", false); // '-'
getBarChar(undefined, "braille", true); // '⣿'
getBarChar("X", "ascii"); // 'X' (custom override)
```

### applyStyleToOptions(options) [#applystyletooptionsoptions]

Apply style defaults to options, allowing overrides.

```typescript
import { applyStyleToOptions } from "@visulima/progress-bar";

const opts = applyStyleToOptions({ total: 100, style: "braille" });
// opts.barCompleteChar === '⣿'
// opts.barIncompleteChar === '⠤'
```


# API Reference (/docs/packages/redact/api)



# API Reference [#api-reference]

## Functions [#functions]

### redact [#redact]

```typescript
function redact<T>(input: T, rules?: string[], options?: RedactOptions): T;
```

Redact sensitive properties from objects.

**Parameters:**

* `input` - Object to redact
* `rules` - Array of property paths to redact
* `options` - Redaction options

**Returns:** New object with redacted values

***

### stringAnonymize [#stringanonymize]

```typescript
function stringAnonymize(text: string, options?: AnonymizeOptions): string;
```

Anonymize sensitive information in text using NLP.

**Parameters:**

* `text` - Text to anonymize
* `options` - Anonymization options

**Returns:** Anonymized text

***

## Options [#options]

### RedactOptions [#redactoptions]

```typescript
interface RedactOptions {
    replacement?: string;
    caseSensitive?: boolean;
}
```

**Properties:**

* `replacement` - Custom replacement text. Default: `"<FIELD_NAME>"`
* `caseSensitive` - Case-sensitive matching. Default: `true`

***

### AnonymizeOptions [#anonymizeoptions]

```typescript
interface AnonymizeOptions {
    include?: string[];
    exclude?: string[];
    replacement?: string;
}
```

**Properties:**

* `include` - Entity types to anonymize
* `exclude` - Entity types to skip
* `replacement` - Custom replacement pattern

***

## Built-in Rules [#built-in-rules]

### Credentials [#credentials]

* `password` - Password fields
* `apikey` - API keys
* `token` - Auth tokens
* `bearer` - Bearer tokens
* `auth` - Auth headers
* `secret` - Secret values

### Financial [#financial]

* `creditcard` - Credit card numbers
* `cvv` / `cvd` - Card security codes
* `bankacc` - Bank account numbers
* `routing` - Routing numbers
* `PAN` - Primary account numbers
* `money` - Monetary values

### Personal [#personal]

* `email` - Email addresses
* `ssn` / `us_social_security` - Social Security Numbers
* `firstname` / `lastname` - Names
* `phonenumber` - Phone numbers
* `passport` - Passport numbers
* `dl` - Driver's license
* `uk_nin` - UK National Insurance

### Technical [#technical]

* `ip` - IP addresses
* `mac_address` - MAC addresses
* `url` - URLs
* `domain` - Domain names
* `crypto` - Cryptocurrency addresses

### Other [#other]

* `date` - Dates
* `time` - Times
* `zip_code` - Postal codes
* `isbn` - ISBN numbers
* `organization` - Organization names

***

## Text Anonymization Categories [#text-anonymization-categories]

### NLP-Detected Entities [#nlp-detected-entities]

* `Person` - People's names
* `Organization` - Company/org names
* `Place` - Locations
* `Date` - Date expressions
* `Money` - Monetary amounts
* `PhoneNumber` - Phone numbers
* `Email` - Email addresses

***

## Examples [#examples]

### All Options [#all-options]

```typescript
import { redact, stringAnonymize } from "@visulima/redact";

// Object redaction with options
const safe = redact(data, ["password", "ssn"], {
    replacement: "[REDACTED]",
    caseSensitive: false,
});

// Text anonymization with options
const anonymous = stringAnonymize(text, {
    include: ["Person", "Email"],
    exclude: ["Organization"],
    replacement: "<HIDDEN>",
});
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/redact/usage">
    Detailed usage examples
  </Card>

  <Card title="Back to Overview">
    Return to overview
  </Card>
</Cards>


# Introduction (/docs/packages/redact)



# @visulima/redact [#visulimaredact]

Powerful library for redacting and masking sensitive data. Protect user privacy with automatic detection of passwords, emails, credit cards, SSNs, and more—plus NLP-powered text anonymization for GDPR compliance.

## Key Features [#key-features]

**Smart Redaction**

* Deep object property masking
* Circular reference handling
* Path-based redaction rules
* Preserves object structure

**Built-in Detection**

* 40+ sensitive data patterns
* Passwords, tokens, API keys
* Credit cards, SSN, bank accounts
* Emails, phone numbers, IPs
* Personal names (NLP-powered)

**Text Anonymization**

* Natural Language Processing
* Detect people, organizations
* Money, dates, locations
* Customizable entity types

**Production-Ready**

* TypeScript support
* No input mutation
* GDPR compliant
* Fast performance

## Quick Start [#quick-start]

```bash
npm install @visulima/redact
```

Redact sensitive object properties:

```typescript
import { redact } from "@visulima/redact";

const user = {
    name: "Alice",
    email: "alice@example.com",
    password: "secret123",
    creditCard: "4532-1234-5678-9010",
};

const safe = redact(user, ["password", "creditCard"]);
console.log(safe);
// { name: "Alice", email: "alice@example.com", password: "<PASSWORD>", creditCard: "<CREDITCARD>" }
```

Anonymize text with NLP:

```typescript
import { stringAnonymize } from "@visulima/redact";

const text = "Contact John Doe at john@example.com or call (555) 123-4567";
const anonymized = stringAnonymize(text);
console.log(anonymized);
// "Contact <PERSON> at <EMAIL> or call <PHONENUMBER>"
```

## Use Cases [#use-cases]

### GDPR-Compliant Logging [#gdpr-compliant-logging]

```typescript
import { redact } from "@visulima/redact";

function logUserAction(user: User, action: string) {
    const safeUser = redact(user, ["password", "ssn", "creditCard", "apiKey"]);
    logger.info({ user: safeUser, action });
}
```

### Sanitize API Responses [#sanitize-api-responses]

```typescript
import { redact } from "@visulima/redact";

app.use((req, res, next) => {
    const originalJson = res.json;
    res.json = function (data) {
        const sanitized = redact(data, ["password", "token", "secret"]);
        return originalJson.call(this, sanitized);
    };
    next();
});
```

### Anonymize User Content [#anonymize-user-content]

```typescript
import { stringAnonymize } from "@visulima/redact";

function anonymizeUserReview(review: string) {
    return stringAnonymize(review, {
        include: ["Person", "Organization", "PhoneNumber", "Email"],
    });
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/redact/installation">
    Installation and setup guide
  </Card>

  <Card title="Usage Guide" href="/docs/packages/redact/usage">
    Complete usage examples
  </Card>

  <Card title="API Reference" href="/docs/packages/redact/api">
    Full API documentation
  </Card>
</Cards>


# Installation & Quick Start (/docs/packages/redact/installation)





# Installation & Quick Start [#installation--quick-start]

## Installation [#installation]

<Tabs items="[&#x22;npm&#x22;, &#x22;pnpm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="npm">
    `bash npm install @visulima/redact `
  </Tab>

  <Tab value="pnpm">
    `bash pnpm add @visulima/redact `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/redact `
  </Tab>

  <Tab value="bun">
    `bash bun add @visulima/redact `
  </Tab>
</Tabs>

## Import [#import]

```typescript
import { redact, stringAnonymize } from "@visulima/redact";
```

## Quick Examples [#quick-examples]

### Redact Object Properties [#redact-object-properties]

```typescript
import { redact } from "@visulima/redact";

const data = {
    username: "alice",
    password: "secret123",
    email: "alice@example.com",
};

const safe = redact(data, ["password"]);
// { username: "alice", password: "<PASSWORD>", email: "alice@example.com" }
```

### Anonymize Text [#anonymize-text]

```typescript
import { stringAnonymize } from "@visulima/redact";

const text = "My email is john@example.com";
const anonymous = stringAnonymize(text);
// "My email is <EMAIL>"
```

### Custom Replacement [#custom-replacement]

```typescript
import { redact } from "@visulima/redact";

const safe = redact(data, ["ssn"], {
    replacement: "[REDACTED]",
});
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Usage Guide" href="/docs/packages/redact/usage">
    Detailed usage examples
  </Card>

  <Card title="API Reference" href="/docs/packages/redact/api">
    Complete API documentation
  </Card>
</Cards>


# Usage Guide (/docs/packages/redact/usage)



# Usage Guide [#usage-guide]

## Object Redaction [#object-redaction]

### Basic Redaction [#basic-redaction]

```typescript
import { redact } from "@visulima/redact";

const user = {
    id: 123,
    name: "Alice",
    password: "secret123",
    apiKey: "sk_live_abc123",
};

const safe = redact(user, ["password", "apiKey"]);
console.log(safe);
// { id: 123, name: "Alice", password: "<PASSWORD>", apiKey: "<APIKEY>" }
```

### Nested Properties [#nested-properties]

```typescript
import { redact } from "@visulima/redact";

const data = {
    user: {
        profile: {
            email: "alice@example.com",
            ssn: "123-45-6789",
        },
        credentials: {
            password: "secret",
        },
    },
};

const safe = redact(data, ["user.profile.ssn", "user.credentials.password"]);
```

### Array Elements [#array-elements]

```typescript
import { redact } from "@visulima/redact";

const users = [
    { name: "Alice", password: "pass1" },
    { name: "Bob", password: "pass2" },
];

const safe = redact(users, ["*.password"]);
```

## Text Anonymization [#text-anonymization]

### Automatic Detection [#automatic-detection]

```typescript
import { stringAnonymize } from "@visulima/redact";

const text = "Contact John Doe at john@example.com or 555-1234";
const result = stringAnonymize(text);
// "Contact <PERSON> at <EMAIL> or <PHONENUMBER>"
```

### Select Categories [#select-categories]

```typescript
import { stringAnonymize } from "@visulima/redact";

const text = "John works at Acme Corp earning $50,000";

// Only anonymize people and money
const result = stringAnonymize(text, {
    include: ["Person", "Money"],
});
// "John works at Acme Corp earning <MONEY>"
```

### Exclude Categories [#exclude-categories]

```typescript
import { stringAnonymize } from "@visulima/redact";

const text = "Email john@example.com about the project";

// Anonymize everything except emails
const result = stringAnonymize(text, {
    exclude: ["Email"],
});
```

## Built-in Rules [#built-in-rules]

### Sensitive Data Patterns [#sensitive-data-patterns]

The library includes 40+ detection patterns:

```typescript
import { redact } from "@visulima/redact";

const data = {
    email: "user@example.com", // Detected
    password: "myPassword123", // Detected
    creditCard: "4532123456789010", // Detected
    ssn: "123-45-6789", // Detected
    apiKey: "sk_live_abc123", // Detected
    token: "Bearer eyJ...", // Detected
    ip: "192.168.1.1", // Detected
    phone: "+1-555-123-4567", // Detected
};

// Auto-detect all sensitive fields
const safe = redact(data);
```

### Financial Data [#financial-data]

```typescript
import { redact } from "@visulima/redact";

const payment = {
    cardNumber: "4532-1234-5678-9010",
    cvv: "123",
    routing: "021000021",
    account: "123456789",
};

const safe = redact(payment, ["cardNumber", "cvv", "routing", "account"]);
```

## Custom Options [#custom-options]

### Custom Replacement [#custom-replacement]

```typescript
import { redact } from "@visulima/redact";

const safe = redact(data, ["password"], {
    replacement: "[REDACTED]",
});
// password: "[REDACTED]"
```

### Case Sensitivity [#case-sensitivity]

```typescript
import { redact } from "@visulima/redact";

const safe = redact(data, ["Password"], {
    caseSensitive: false,
});
// Matches "password", "PASSWORD", "Password"
```

## Real-World Examples [#real-world-examples]

### Express Middleware [#express-middleware]

```typescript
import { redact } from "@visulima/redact";
import type { Request, Response, NextFunction } from "express";

function redactMiddleware(req: Request, res: Response, next: NextFunction) {
    // Redact request body
    if (req.body) {
        req.body = redact(req.body, ["password", "token", "apiKey"]);
    }

    // Redact response
    const originalJson = res.json.bind(res);
    res.json = (data: any) => {
        const safe = redact(data, ["password", "secret", "token"]);
        return originalJson(safe);
    };

    next();
}

app.use(redactMiddleware);
```

### Logger Integration [#logger-integration]

```typescript
import { redact } from "@visulima/redact";
import winston from "winston";

const logger = winston.createLogger({
    format: winston.format.combine(
        winston.format((info) => {
            return {
                ...info,
                ...redact(info, ["password", "token", "apiKey"]),
            };
        })(),
        winston.format.json(),
    ),
});
```

### Database Query Sanitization [#database-query-sanitization]

```typescript
import { redact } from "@visulima/redact";

class UserRepository {
    async findById(id: string) {
        const user = await this.db.users.findOne({ id });

        // Remove sensitive fields before returning
        return redact(user, ["password", "passwordHash", "resetToken", "twoFactorSecret"]);
    }

    async logQuery(query: any) {
        // Redact sensitive data in logs
        const safe = redact(query, ["password", "token", "secret"]);

        logger.debug("Query executed", safe);
    }
}
```

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/packages/redact/api">
    Complete API documentation
  </Card>

  <Card title="Back to Overview">
    Return to overview
  </Card>
</Cards>


# API Reference (/docs/packages/secret-scanner/api)



# API Reference [#api-reference]

## Scanning [#scanning]

### `scan(paths, options?)` [#scanpaths-options]

Recursively scan one or more paths for secrets. Runs the detector on a Rust thread pool.

```typescript
import { scan } from "@visulima/secret-scanner";

const findings = await scan([process.cwd()], {
    redact: true,
    walk: { gitignore: true, maxFileSize: 5 * 1024 * 1024 },
});
```

* Respects `.gitignore`, `.ignore` and global excludes by default.
* Walker-level exclusions come from `walk.excludePatterns` and `walk.excludeFromFiles`.
* Findings are sorted, deduped by identity and priority, and emitted with paths relative to the first scan root.

### `scanFiles(files, options?)` [#scanfilesfiles-options]

Scan a fixed list of files (for example, the output of `git diff --name-only`). Bypasses the walker entirely.

```typescript
import { scanFiles } from "@visulima/secret-scanner";

const findings = await scanFiles(["src/app.ts", "src/db.ts"], {
    walk: { excludePatterns: ["*.generated.ts"] },
});
```

`walk.excludePatterns` / `walk.excludeFromFiles` still apply — the JS wrapper runs them through the `ignore` npm package to match the walker's semantics.

### `scanString(content, file, options?)` [#scanstringcontent-file-options]

Scan an in-memory buffer as if it lived at `file`. Useful for editor integrations and LSPs.

```typescript
import { scanString } from "@visulima/secret-scanner";

const findings = await scanString('const token = "ghp_..."', "src/app.ts");
```

Runs synchronously on the calling thread (the binding exposes `scanTextSync`); the wrapper returns a Promise for API consistency.

## Introspection [#introspection]

### `listRules(options?)` [#listrulesoptions]

Return metadata for every rule compiled from the effective config. Useful for building UIs, validating user configs, or pretty-printing the active ruleset.

```typescript
import { listRules } from "@visulima/secret-scanner";

const rules = await listRules({ rules: { enable: ["tag:preset:weak-passwords"] } });

for (const rule of rules) {
    console.log(`${rule.id} (${String(rule.keywords.length)} keywords)`);
}
```

### `inspectRuleset(options?)` [#inspectrulesetoptions]

Return the rules that failed to compile (invalid regex, bad allowlist, etc.). Rules that compile are silently skipped otherwise, which makes this the canonical way to validate a config before scanning.

```typescript
import { inspectRuleset } from "@visulima/secret-scanner";

const skipped = await inspectRuleset({ config: { path: "./leaks.json" } });

if (skipped.length > 0) {
    console.warn(skipped.map((s) => `${s.ruleId}: ${s.reason}`).join("\n"));
}
```

### `listRequiredValidators(options?)` [#listrequiredvalidatorsoptions]

Return every **non-HTTP** validator type referenced by the current ruleset, plus the optional peer-dep needed to verify findings from rules of that type. Returns an empty array when the ruleset only uses built-in HTTP / JWT validators.

Ideal for a pre-flight check before enabling `config.validate: true`, or for wiring a `--list-validators`-style UI.

```typescript
import { listRequiredValidators } from "@visulima/secret-scanner";

const report = await listRequiredValidators();

for (const entry of report) {
    console.log(`${entry.displayName} (${entry.type}) — ${String(entry.ruleCount)} rule(s)`);
    if (entry.packageName) {
        console.log(`  install: npm add ${entry.packageName}`);
    }
}
```

## Fingerprints [#fingerprints]

### `fingerprint(finding)` [#fingerprintfinding]

Content-addressed stable key — SHA-256 over `(secret, ruleId, file)` truncated to 16 hex characters. Use it to build or merge baselines; the result survives line shifts inside the file and only changes when the secret, the rule, or the file path changes.

```typescript
import { fingerprint } from "@visulima/secret-scanner";

const key = fingerprint(finding);
// "a1b2c3d4e5f60718"
```

### `legacyFingerprint(finding)` [#legacyfingerprintfinding]

Gitleaks-compatible `file:ruleID:startLine` string. Retained for interop with existing gitleaks baselines and tooling — suppression loaders still accept this form on read, but new baselines should use `fingerprint()` so line edits don't churn the file.

```typescript
import { legacyFingerprint } from "@visulima/secret-scanner";

const key = legacyFingerprint(finding);
// "src/config.ts:aws-access-token:42"
```

## Transformers [#transformers]

### `transformYamlBlockScalars(content)` [#transformyamlblockscalarscontent]

Collapse YAML `|` (literal) and `>` (folded) block scalars into single-line `key: "value"` proxies so multi-line secrets become a contiguous match for the detector. Opt-in because it requires reading the file in JS rather than going through the Rust walker — use it via `scanString` on YAML inputs you specifically want to transform.

```typescript
import { readFile } from "node:fs/promises";
import { scanString, transformYamlBlockScalars } from "@visulima/secret-scanner";

const yaml = await readFile("config.yaml", "utf8");
const findings = await scanString(transformYamlBlockScalars(yaml), "config.yaml");
```

Scope: handles `key: |` / `key: >` at any indent level, including quoted keys. Sequence-element scalars (`- |`) and flow-style mappings are left alone — smaller hit rate, larger edge-case surface, and not worth carrying without real demand.

The transformer pads blank lines for every consumed block-scalar body line, so `finding.startLine` / `finding.endLine` still map back to the original source without a side-band source map.

## Heuristic helpers [#heuristic-helpers]

The same predicates the [heuristic filter suite](/docs/packages/secret-scanner/configuration#heuristics--post-detection-false-positive-filters) applies. Exported so custom pre-filters (editor plugins, CI gates, third-party wrappers) can reuse the logic without re-implementing the rules.

```typescript
import { isLockFile, isNotAlphanumericString, isPotentialUuid, isSequentialString } from "@visulima/secret-scanner";

isLockFile("packages/foo/pnpm-lock.yaml"); // true
isSequentialString("AAAAAAAA"); // true
isPotentialUuid("123e4567-e89b-12d3-a456-426614174000"); // true
isNotAlphanumericString("*****"); // true
```

Each returns `true` when the input **should be dropped** as a likely false positive. See the [configuration reference](/docs/packages/secret-scanner/configuration#heuristics--post-detection-false-positive-filters) for the full behaviour of each heuristic and the knobs to turn them off.

## Paths [#paths]

### `bundledConfigPath` [#bundledconfigpath]

Absolute path to the bundled gitleaks ruleset JSON. Exposed so downstream tools can re-run / diff the bundled defaults without re-implementing the loader.

## Types [#types]

### `Finding` [#finding]

```typescript
interface Finding {
    ruleId: string;
    description: string;
    file: string;
    startLine: number;
    endLine: number;
    startColumn: number;
    endColumn: number;
    match: string;
    secret: string;
    entropy: number;
    tags: string[];
    confidence: Confidence;
    alternateMatches: string[];
    source?: string;
    validation?: ValidationStatus;
}
```

* `file` is **relative** to the first scan root. When scanning with `scanFiles`, it is relative to the current working directory.
* Columns are **1-based and count Unicode code points**, not bytes — consumable by editor/LSP tooling.
* `confidence` resolves to `"low"` when the rule declares none (every bundled gitleaks rule). Use it alongside `config.minConfidence` to filter.
* `alternateMatches` lists other rule ids that matched the same byte span and were collapsed by the dedup pass.
* `source` tags the rule's provenance — `"gitleaks"`, `"kingfisher"`, `"visulima"`, or whatever the user declared.
* `validation` is set only when `config.validate: true`. See [`ValidationStatus`](#validationstatus) below.

### `RuleInfo` [#ruleinfo]

```typescript
interface RuleInfo {
    id: string;
    description: string;
    tags: string[];
    keywords: string[];
    entropy?: number;
    hasRegex: boolean;
    hasPathFilter: boolean;
    alwaysRuns: boolean;
    confidence: Confidence;
}
```

`alwaysRuns` is `true` when the rule declares no keywords — its regex runs against every file instead of being prefiltered by Aho-Corasick. Surface it in tooling that validates custom rulesets so users can spot accidental perf regressions.

### `SkippedRule` [#skippedrule]

```typescript
interface SkippedRule {
    ruleId: string;
    reason: string;
}
```

### `Confidence` [#confidence]

Author-declared rule quality. Rules that don't declare a value resolve to `"low"`.

```typescript
type Confidence = "low" | "medium" | "high";
```

### `ValidationStatus` [#validationstatus]

Populated on `Finding.validation` when `config.validate: true`.

```typescript
type ValidationStatus = "verified" | "rejected" | "skipped" | "error";
```

* `"verified"` / `"rejected"` — the provider returned a conclusive result.
* `"skipped"` — the validator ran but the rule uses an unsupported validation type (gRPC without deps, multi-step HTTP, checksum, …).
* `"error"` — the validator ran but failed (network, timeout, rate-limit).
* *absent* — validator was never invoked (`config.validate` was `false`).

### `ValidatorReport` [#validatorreport]

Returned by [`listRequiredValidators()`](#listrequiredvalidatorsoptions).

```typescript
interface ValidatorReport {
    displayName: string;
    implemented: boolean;
    packageName?: string;
    ruleCount: number;
    summary: string;
    type: string;
}
```

* `type` — the validator's discriminator in the rule schema (`"aws"`, `"mongodb"`, `"mysql"`, …).
* `implemented: false` means no transport is wired up yet — a bespoke implementation is required.
* `packageName` is the npm peer-dep to install; omitted when no driver is needed.

### `GitleaksConfig` [#gitleaksconfig]

Lightweight structural mirror of the gitleaks schema. The Rust side is the source of truth via `serde_json::from_value`; the TypeScript type only validates the shape for downstream tooling.

```typescript
interface GitleaksConfig {
    allowlist?: unknown;
    allowlists?: unknown[];
    description?: string;
    extend?: { disabledRules?: string[]; path?: string; useDefault?: boolean };
    rules?: unknown[];
    title?: string;
}
```

### `ScanOptions` [#scanoptions]

See the [Configuration](/docs/packages/secret-scanner/configuration) page.


# CLI (/docs/packages/secret-scanner/cli)



# CLI [#cli]

The scanner doesn't ship its own CLI. It's consumed by [`@visulima/vis`](/docs/packages/vis) as `vis secrets`, which adds workspace-aware flags (`--staged`, `--since`, `--affected`), baseline tooling, SARIF rendering, opt-in rule presets, live provider validation, and migrations from competing tools.

The full reference — modes, exit codes, workspace config, CI recipe — lives in [`vis secrets`](/docs/packages/vis/commands/secrets). This page focuses on the flags surfaced by the underlying scanner.

## Install [#install]

```bash
pnpm add -D @visulima/vis
```

## Common commands [#common-commands]

```bash
# Scan the workspace (grouped, colourised output)
vis secrets

# Pre-commit mode — scan only staged files
vis secrets --staged

# Scan files changed since a ref
vis secrets --since main

# Scan projects affected by the current branch
vis secrets --affected

# Scaffold an initial .secrets-baseline.json
vis secrets --init

# Print all bundled detection rules
vis secrets --list-rules

# Print non-HTTP validators referenced by the ruleset (install hints for peer-deps)
vis secrets --list-validators

# Enable opt-in rule groups additively — defaults still fire
vis secrets --enable-rule tag:preset:weak-passwords --enable-rule tag:preset:password-manager

# Restrict output to one opt-in group only (whitelist)
vis secrets --include-rule tag:preset:password-manager

# Rule filters
vis secrets --include-rule stripe-access-token
vis secrets --exclude-rule generic-api-key

# Raise the confidence floor — drop unlabeled + low-confidence rules
vis secrets --min-confidence high

# Live-verify findings against provider APIs, then fail CI on unverified matches
vis secrets --validate --only-verified

# Extra walker exclusions on top of .gitignore
vis secrets --exclude 'dist/**' --exclude-from .secretsignore

# Baseline suppression + diff
vis secrets --baseline .secrets-baseline.json

# Merge current findings into the baseline
vis secrets --update-baseline

# SARIF for GitHub / GitLab code scanning
vis secrets --format sarif > report.sarif
```

## Full flag list [#full-flag-list]

### Input selection [#input-selection]

| Flag                    | Type       | Default | Description                                                      |
| ----------------------- | ---------- | ------- | ---------------------------------------------------------------- |
| `--staged`              | boolean    | `false` | Scan only files staged for commit. Requires git.                 |
| `--since <ref>`         | string     | —       | Scan only files changed since a git ref (e.g. `main`).           |
| `--affected`            | boolean    | `false` | Scan only projects affected by the current branch (`$VIS_BASE`). |
| `--exclude <pattern>`   | `string[]` | —       | Gitignore-syntax pattern to exclude from the walk. Repeatable.   |
| `--exclude-from <path>` | `string[]` | —       | Gitignore-shaped file the walker should honor. Repeatable.       |
| `--include-hidden`      | boolean    | `false` | Visit dotfiles.                                                  |
| `--no-gitignore`        | boolean    | `false` | Do not respect `.gitignore`.                                     |
| `--max-size <bytes>`    | number     | 10 MiB  | Skip files larger than this.                                     |

### Rule selection [#rule-selection]

| Flag                     | Type       | Default | Description                                                                                         |
| ------------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------- |
| `--config <path>`        | string     | —       | Path to a JSON config (gitleaks-compatible shape).                                                  |
| `--no-extend-bundled`    | boolean    | `false` | With `--config`, replace the bundled ruleset instead of merging on top.                             |
| `--enable-rule <spec>`   | `string[]` | —       | Additive enablement for opt-in rules. Rule id or `tag:<name>`. Doesn't restrict output. Repeatable. |
| `--include-rule <spec>`  | `string[]` | —       | Whitelist — only emit matching findings. Rule id or `tag:<name>`. Implies enablement. Repeatable.   |
| `--exclude-rule <spec>`  | `string[]` | —       | Blacklist — drop matching findings. Rule id or `tag:<name>`. Repeatable.                            |
| `--min-confidence <lvl>` | string     | `low`   | Drop rules below this author-declared confidence: `low`, `medium`, `high`. See below.               |
| `--list-rules`           | boolean    | `false` | Print all bundled detection rules and exit.                                                         |
| `--list-validators`      | boolean    | `false` | Print non-HTTP validators referenced by the ruleset + peer-dep install hints.                       |

**Opt-in rule groups shipped today:** `tag:preset:weak-passwords` (low-entropy credentials complementing `generic-api-key`), `tag:preset:password-manager` (1Password / Bitwarden / LastPass / KeePass / browser-CSV export detection). Both are `defaultEnabled: false` inside every bundled ruleset.

### Validation [#validation]

| Flag                | Type    | Default | Description                                                                                 |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------- |
| `--validate`        | boolean | `false` | Live-verify each finding against its provider. Off by default — scans stay offline-safe.    |
| `--only-verified`   | boolean | `false` | With `--validate`, drop every finding whose validation is not `verified`.                   |
| `--list-validators` | boolean | `false` | Print non-HTTP validator types referenced by the ruleset, with install hints for peer-deps. |

### Output [#output]

| Flag                | Type    | Default | Description                                            |
| ------------------- | ------- | ------- | ------------------------------------------------------ |
| `--format <fmt>`    | string  | `text`  | Output format: `text`, `json`, `sarif`.                |
| `--redact`          | boolean | `false` | Mask secret values in output.                          |
| `--quiet`           | boolean | `false` | Suppress all progress output (only emit findings).     |
| `--verbose`         | boolean | `false` | Print diagnostic info to stderr (skipped rules, etc.). |
| `--concurrency <n>` | number  | auto    | Rayon worker threads (`0` / omit = auto).              |

### Baseline [#baseline]

| Flag                 | Type    | Default | Description                                                |
| -------------------- | ------- | ------- | ---------------------------------------------------------- |
| `--baseline <path>`  | string  | —       | Path to a baseline JSON of previously-triaged findings.    |
| `--init`             | boolean | `false` | Scaffold a baseline from current findings.                 |
| `--dry-run`          | boolean | `false` | With `--init`, preview the baseline without writing files. |
| `--update-baseline`  | boolean | `false` | Merge current findings into the baseline and exit `0`.     |
| `--replace-baseline` | boolean | `false` | With `--update-baseline`, replace rather than merge.       |

## `--min-confidence` [#--min-confidence]

Every rule may carry an author-declared `confidence` field (`low`, `medium`, `high`). `--min-confidence` drops rules below the supplied floor:

| Floor    | Drops                                                          |
| -------- | -------------------------------------------------------------- |
| `low`    | Nothing (the default).                                         |
| `medium` | Rules declared `low`, **plus** every rule with no declaration. |
| `high`   | Rules declared `low` or `medium`, plus every unlabeled rule.   |

Rules without an explicit label are treated as `low`. That's every bundled gitleaks rule today — the stock ruleset needs explicit labels before `--min-confidence high` is useful. Use it when you've curated a precision-tuned config of your own, or when you pull in an opt-in preset that ships labels (e.g. a future `weak-passwords-v2`).

## `--validate` and `--only-verified` [#--validate-and---only-verified]

`--validate` turns every finding into a live verification request against the provider's own API. Only [Kingfisher-style HTTP validators](https://github.com/mongodb/kingfisher/blob/main/docs/RULES) with `StatusMatch` / `WordMatch` response matchers are supported today; other kinds (gRPC, multi-step HTTP, checksum) mark the finding as `validation=skipped` and pass through unfiltered.

* One HTTP request per finding.
* Per-host concurrency capped at 4; global cap at 8.
* `--only-verified` drops any finding whose `validation` is not `verified` — ideal for CI gating.
* Non-HTTP validators may require optional peer-deps (e.g. AWS / GCP / MySQL drivers). Run `vis secrets --list-validators` to see which are referenced by the current ruleset.

> **Warning:** `--validate` sends the candidate secret to the provider. Some providers page their security team on failed auth attempts. Only enable on repos you own or have explicit authorisation to test.

## `--list-validators` [#--list-validators]

Prints every non-HTTP validator type referenced by the currently-loaded ruleset, together with the npm peer-dep users need to install before `--validate` can verify findings from those rules. Non-HTTP validators are optional — HTTP / JWT are built in — so skip this unless you opt in to validator-heavy presets.

Example output:

```text
2 non-HTTP validator type(s) referenced by the current ruleset:

AWS Secret Key (aws, 3 rules)
  STS GetCallerIdentity challenge.
  install: npm add @aws-sdk/client-sts

MongoDB Connection String (mongodb, 1 rule)
  Attempts an authenticated handshake against the cluster.
  install: npm add mongodb
```

An empty list means the ruleset only references HTTP / JWT validators and no extra dependencies are required.

## Workspace config — `vis.config.ts` [#workspace-config--visconfigts]

The same grouped `ScanOptions` shape is available under `secrets` in `vis.config.ts`, so teams can commit the defaults once:

```typescript
export default {
    secrets: {
        baseline: ".secrets-baseline.json",
        config: {
            extendBundled: true,
            minConfidence: "medium",
            onlyVerified: false,
            validate: false,
        },
        rules: {
            enable: ["tag:preset:weak-passwords"],
            exclude: ["generic-api-key"],
        },
        walk: {
            excludeFromFiles: [".secretsignore"],
            excludePatterns: ["dist/**", "coverage/**"],
        },
    },
};
```

CLI flags always take precedence over the config file. See the [configuration reference](/docs/packages/secret-scanner/configuration) for every field.

## SARIF output [#sarif-output]

`--format sarif` emits SARIF v2.1.0 with `file://` URIs, a `tool.driver.rules[]` cross-reference, and `result.level`. Compatible with GitHub code scanning and GitLab security dashboards.

```yaml
# .github/workflows/secrets.yml
name: Secrets
on: [push, pull_request]
jobs:
    scan:
        runs-on: ubuntu-latest
        permissions: { security-events: write, contents: read }
        steps:
            - uses: actions/checkout@v4
            - uses: pnpm/action-setup@v4
            - run: pnpm install
            - run: pnpm vis secrets --format sarif > report.sarif
              continue-on-error: true
            - uses: github/codeql-action/upload-sarif@v3
              with: { sarif_file: report.sarif }
```

## Exit codes [#exit-codes]

| Code | Meaning                                                          |
| ---- | ---------------------------------------------------------------- |
| `0`  | No findings after suppression, or `--update-baseline` succeeded. |
| `1`  | One or more findings emitted.                                    |
| `2`  | Usage / configuration error.                                     |

## Migrations [#migrations]

`vis migrate` can port existing tools to `vis secrets`:

```bash
vis migrate gitleaks     # keeps gitleaks.toml, rewrites scripts / hooks
vis migrate secretlint   # removes @secretlint/*, rewrites scripts / hooks
vis migrate verify       # sanity-check the migration
```

## Pre-commit hook [#pre-commit-hook]

```bash
vis hook add secrets
```

Appends a managed block to `.husky/pre-commit` (or creates one) that runs `vis secrets --staged --quiet`. Remove the block or delete the file to disable.


# Configuration (/docs/packages/secret-scanner/configuration)



# Configuration [#configuration]

Every entry point (`scan`, `scanFiles`, `scanString`, `listRules`, `inspectRuleset`) accepts the same grouped `ScanOptions` object. Keys are namespaced by concern — `config`, `walk`, `rules`, `baseline` — plus a few truly cross-cutting flags at the root.

## Shape [#shape]

```typescript
export interface ScanOptions {
    baseline?: string;
    concurrency?: number;

    config?: {
        extendBundled?: boolean;
        heuristics?: {
            lockFile?: boolean;
            notAlphanumericString?: boolean;
            potentialUuid?: boolean;
            sequentialString?: boolean;
        };
        inline?: GitleaksConfig;
        minConfidence?: "low" | "medium" | "high";
        onlyVerified?: boolean;
        path?: string;
        validate?: boolean;
    };

    redact?: boolean;

    rules?: {
        enable?: string[];
        exclude?: string[];
        include?: string[];
    };

    verbose?: boolean;

    walk?: {
        excludeFromFiles?: string[];
        excludePatterns?: string[];
        gitignore?: boolean;
        includeHidden?: boolean;
        maxFileSize?: number;
    };
}
```

## Root-level [#root-level]

| Option        | Type      | Default | Description                                                                       |
| ------------- | --------- | ------- | --------------------------------------------------------------------------------- |
| `baseline`    | `string`  | —       | Path to a JSON array of `Finding` objects. Matches are suppressed by fingerprint. |
| `concurrency` | `number`  | auto    | Rayon worker threads. `0` or `undefined` uses rayon's global pool.                |
| `redact`      | `boolean` | `false` | Mask the `match` and `secret` strings in every emitted finding.                   |
| `verbose`     | `boolean` | `false` | Print skipped-rule diagnostics to stderr on the first call.                       |

## `config` — rule source + validation [#config--rule-source--validation]

| Option          | Type                          | Default | Description                                                                                                               |
| --------------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `extendBundled` | `boolean`                     | `true`  | Layer the user ruleset on top of the bundled set. `false` replaces it entirely.                                           |
| `heuristics`    | `object`                      | all on  | Toggle post-detection false-positive filters. See [heuristics](#heuristics--post-detection-false-positive-filters) below. |
| `inline`        | `GitleaksConfig`              | —       | Pre-parsed config object. Fastest path, no file IO.                                                                       |
| `path`          | `string`                      | —       | Path to a JSON file (gitleaks-compatible shape). Parsed once and cached.                                                  |
| `minConfidence` | `"low" \| "medium" \| "high"` | —       | Drop rules below this author-declared confidence floor. See [Confidence](#minconfidence) below.                           |
| `validate`      | `boolean`                     | `false` | Live-verify each finding against its provider's API after detection.                                                      |
| `onlyVerified`  | `boolean`                     | `false` | With `validate: true`, drop every finding whose validation is not `"verified"`.                                           |

### Precedence [#precedence]

1. `config.inline` wins when both `inline` and `path` are set.
2. The resulting user config layers on top of the bundled ruleset unless `extendBundled: false`.
3. Opt-in rule bundles (e.g. `tag:preset:weak-passwords`) ship disabled-by-default inside every ruleset; `rules.include` is the only gate.

### `minConfidence` [#minconfidence]

Every rule may carry an optional `confidence` field (`"low"`, `"medium"`, `"high"`). Rules without an explicit label are treated as `"low"`. Setting `minConfidence` drops rules below the floor:

| Floor      | Drops                                                            |
| ---------- | ---------------------------------------------------------------- |
| unset      | Nothing — every loaded rule fires.                               |
| `"low"`    | Nothing (equivalent to unset).                                   |
| `"medium"` | Rules declared `"low"`, **plus** every rule with no declaration. |
| `"high"`   | Rules declared `"low"` or `"medium"`, plus every unlabeled rule. |

Every bundled gitleaks rule ships unlabeled, so `"medium"` or `"high"` drops the entire stock ruleset. Use this flag against a curated config of your own, or when you opt into a preset that ships labels.

### `heuristics` — post-detection false-positive filters [#heuristics--post-detection-false-positive-filters]

Four heuristics (ported from [detect-secrets](https://github.com/Yelp/detect-secrets)) run after rule detection and drop high-confidence placeholders before returning. All four default to **on**; set the individual key to `false` when you need the raw match set — typical only when scanning a curated fixture that legitimately contains UUID-shaped or all-dash values.

| Key                     | Default | Drops findings where …                                                                                                                                                                                                                                                                    |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lockFile`              | `true`  | file basename is a known lock file (28 entries: `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `go.sum`, `flake.lock`, `gradle.lockfile`, `.terraform.lock.hcl`, …). Lock files are regenerated from manifests and churn constantly; scanning them almost always produces noise, not leaks. |
| `sequentialString`      | `true`  | the secret is a substring of a standard character sequence (`abcdefgh`, `12345678`) or a single repeating character (`AAAAAAAA`, `00000000`). Short secrets (\<6 chars) are always allowed.                                                                                               |
| `potentialUuid`         | `true`  | the secret matches the canonical 8-4-4-4-12 UUID shape. In practice UUIDs are object identifiers (trace, request, user) rather than credentials.                                                                                                                                          |
| `notAlphanumericString` | `true`  | the secret contains zero ASCII alphanumerics (`*****`, `------`, `//////`) — almost always a masked-out placeholder captured by a greedy regex.                                                                                                                                           |

```typescript
// Keep UUID-shaped findings when auditing a system that uses UUIDs as API keys.
const findings = await scan([process.cwd()], {
    config: { heuristics: { potentialUuid: false } },
});
```

The filters are intentionally conservative: every entry has to be wrong in a very specific way before it drops. If you hit a false negative you suspect a heuristic caused, toggle the one you suspect off and compare.

For help detecting secrets that span multiple lines in YAML (where the raw scan never sees the full value), see the complementary [`transformYamlBlockScalars`](/docs/packages/secret-scanner/api#transformyamlblockscalarscontent) helper — it's opt-in because it requires reading files in JS rather than through the Rust walker.

### `validate` and `onlyVerified` [#validate-and-onlyverified]

`validate` turns on live verification — every finding whose rule declares an HTTP validator is checked against the provider's own API after detection. Cost: one HTTP request per finding (per-host concurrency capped at 4, global at 8). Default `false`, so scans stay offline-safe.

Supported today: Kingfisher-style HTTP validators with `StatusMatch` / `WordMatch` response matchers. Other kinds (gRPC, multi-step HTTP, checksum) surface as `validation: "skipped"` on the finding and pass through unfiltered. Non-HTTP validators (AWS STS, MongoDB, MySQL / Postgres, …) require optional peer-deps — call `listRequiredValidators()` (or `vis secrets --list-validators`) to see which the current ruleset references.

`onlyVerified: true` then filters the emitted set down to findings whose `validation === "verified"` — useful for CI gating where a suspect match that can't be verified is not a blocker.

> **Warning:** `validate: true` sends the candidate secret to the provider. Some providers page their security team on failed auth attempts. Only enable on repos you own or have explicit authorisation to test.

## `walk` — filesystem traversal [#walk--filesystem-traversal]

| Option             | Type       | Default | Description                                                                                                         |
| ------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `excludeFromFiles` | `string[]` | `[]`    | Paths to `.gitignore`-syntax files to honor in addition to `.gitignore` (for example `.secretsignore`).             |
| `excludePatterns`  | `string[]` | `[]`    | Inline gitignore-syntax lines layered on top of `.gitignore`. Supports negation, directory markers and leading `/`. |
| `gitignore`        | `boolean`  | `true`  | Respect `.gitignore`, `.ignore` and global excludes via the `ignore` crate.                                         |
| `includeHidden`    | `boolean`  | `false` | Visit dotfiles and hidden directory entries.                                                                        |
| `maxFileSize`      | `number`   | 10 MiB  | Skip files larger than this (in bytes). Files above the threshold never enter the detector.                         |

Only `scan()` runs the walker. `scanFiles()` takes a fixed list and bypasses it; there the JS wrapper applies `excludePatterns` / `excludeFromFiles` via the `ignore` npm package so the two code paths behave the same.

## `rules` — id + tag filters [#rules--id--tag-filters]

| Option    | Type       | Default | Description                                                                                                            |
| --------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `enable`  | `string[]` | —       | **Additive.** Turn on opt-in rules (e.g. `tag:preset:weak-passwords`) without restricting output. Defaults still fire. |
| `include` | `string[]` | —       | **Whitelist.** Only emit findings matching these ids/tags. Implies enablement for opt-in rules referenced here.        |
| `exclude` | `string[]` | —       | **Blacklist.** Drop findings matching these ids/tags. Doesn't enable anything.                                         |

`tag:<name>` entries expand to every rule carrying that tag at config-load time. An unknown tag throws with a list of known tags — catches typos at the boundary. Common tags: `tag:preset:weak-passwords`, `tag:preset:password-manager`.

**Pick the right knob:**

* "enable the weak-passwords rules alongside my normal scan" → `rules.enable: ["tag:preset:weak-passwords"]`
* "scan **only** for password-manager exports" → `rules.include: ["tag:preset:password-manager"]`
* "keep defaults but mute `generic-api-key`" → `rules.exclude: ["generic-api-key"]`

## `baseline` — fingerprint suppression [#baseline--fingerprint-suppression]

Set `baseline` to the path of a JSON array of `Finding` objects. Any finding whose content-hash fingerprint — SHA-256 over `(secret, ruleId, file)` truncated to 16 hex chars — already appears in the baseline is suppressed. Because the fingerprint hashes content rather than position, the entry survives line shifts inside the file; it only invalidates when the secret itself, the rule, or the file path changes.

Legacy gitleaks-style baselines using the `<file>:<ruleID>:<startLine>` form keep suppressing correctly on read, so migrating to the content-hash form can happen at your own pace via `vis secrets --update-baseline`.

A missing file is treated as an empty baseline; a malformed file is ignored with a stderr warning — scans never fail because of a broken baseline.

## Gitleaks-compatible schema extensions [#gitleaks-compatible-schema-extensions]

The config shape mirrors gitleaks' TOML schema. A few fields are ours (safe additions):

| Field             | Scope     | Description                                                                                                     |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `priority`        | Rule      | Integer (default `0`). When two rules match the same byte span, the higher priority wins (`#1997`).             |
| `preRegexReplace` | Rule      | Ordered `[{ from, to }, …]` regex replacements applied to the scan buffer before the rule's main regex runs.    |
| `targetRules`     | Allowlist | When non-empty, the allowlist only applies to findings whose rule id is in this list (gitleaks schema `#1919`). |


# Introduction (/docs/packages/secret-scanner)



# Secret Scanner [#secret-scanner]

**Fast secret and credential scanner for Node.js, built on a Rust port of the [gitleaks](https://github.com/gitleaks/gitleaks) detection engine and exposed through NAPI.**

`@visulima/secret-scanner` ships a combined default ruleset (1,047 rules active by default — 222 upstream gitleaks rules MIT + 825 MongoDB Kingfisher rules Apache-2.0, plus 11 opt-in `preset:*` rules disabled by default) together with a vetted set of false-positive reductions, native `.gitignore` support, and a handful of ergonomic extensions (opt-in tagged rule groups, per-rule priority, per-rule pre-processing, target-scoped allowlists). The detector is PCRE-compatible, parallelised with `rayon`, and mmap-aware for large files.

Use it as a library, through the [`vis secrets`](/docs/packages/vis) CLI, or as a drop-in replacement for `gitleaks` / `secretlint` in existing pipelines.

## Features [#features]

* **1,047 bundled rules** active by default — 222 from upstream gitleaks (MIT) + 825 from MongoDB Kingfisher (Apache-2.0) — plus 11 opt-in `preset:*` rules (`preset:weak-passwords` for low-entropy credentials, `preset:password-manager` for committed vault exports), disabled by default.
* **Fancy-regex engine** with lookaround support; delegates to `regex` internally when a pattern doesn't need PCRE features.
* **Aho-Corasick keyword prefilter** — candidate rules are shortlisted in a single DFA pass before any per-rule regex runs.
* **Parallel file scanning** via `rayon`, memory-mapped zero-copy reads above 1 MiB.
* **Respects `.gitignore` / `.ignore`** out of the box, plus scanner-specific `walk.excludePatterns` / `walk.excludeFromFiles` for `.secretsignore`-style files.
* **Baseline JSON** with content-hash fingerprints (SHA-256 over `secret + ruleId + file`, truncated to 16 hex) — survives line shifts. Legacy `file:rule:line` baselines still suppress on read.
* **Inline + block + next-line suppression** — `gitleaks:allow`, `gitleaks:allow-start` / `-end`, `secret-scanner:` equivalents, plus detect-secrets `pragma: allowlist secret` / `pragma: allowlist nextline secret` for YAML and PEM bodies.
* **Heuristic false-positive suite** — lock-file skip, UUID / sequential / non-alphanumeric drops. On by default, individually toggleable via `config.heuristics.*`.
* **YAML block-scalar transformer** — opt-in helper (`transformYamlBlockScalars`) that collapses multi-line `|` / `>` scalars into single-line proxies so secrets split across lines become detectable.
* **Deterministic output order** across runs — stable sort on file + line + column + rule id.
* **Findings deduplication** — identical findings collapse; rule priority resolves span overlaps (specific rules beat `generic-api-key`).
* **Targeted allowlists** via gitleaks' `targetRules` schema (#1919).
* **Per-rule text pre-processor** (`preRegexReplace`) for normalising escape sequences / templates before the main regex runs (#1182).
* **Codepoint-based column math** for editor / LSP consumers (#1962).
* **SARIF** output ready for GitHub / GitLab code scanning (polished URIs + rule cross-refs).
* **JSON-only config at runtime** — author in TOML if you prefer; convert once at build time. No c12 / TOML parser in the runtime dep graph.

## Quick Start [#quick-start]

```typescript
import { scan, scanFiles, scanString, listRules, inspectRuleset, fingerprint, transformYamlBlockScalars } from "@visulima/secret-scanner";

// Scan a directory (respects .gitignore)
const findings = await scan([process.cwd()], { redact: true });

// Scan a fixed list of files (e.g. `git diff --name-only`)
const staged = await scanFiles(["src/app.ts", "src/db.ts"]);

// Scan an in-memory buffer
const inline = await scanString('aws_secret = "AKIA..."', "config.env");

// Collapse YAML block scalars first so multi-line secrets are detectable
const yamlFindings = await scanString(transformYamlBlockScalars(yamlSource), "config.yaml");

// List every bundled rule
const rules = await listRules();

// Validate a custom config before scanning
const skipped = await inspectRuleset({ config: { path: "./leaks.json" } });

// Additively enable the bundled weak-passwords opt-in group (defaults still fire)
const weak = await scan([process.cwd()], { rules: { enable: ["tag:preset:weak-passwords"] } });

// Keep UUID-shaped findings (heuristic filters default to on; toggle individually)
const audit = await scan([process.cwd()], { config: { heuristics: { potentialUuid: false } } });

// Compute a content-hash fingerprint — stable across line shifts
for (const f of findings) console.log(fingerprint(f));
```

## Why Secret Scanner? [#why-secret-scanner]

* **Gitleaks-compatible without the Go runtime** — ships as an ESM module with prebuilt NAPI binaries for 8 platforms (darwin / linux / windows × x64 / arm64, plus linux musl variants).
* **Fewer false positives than stock gitleaks** — additive stopword patches cover common placeholder patterns (`${VAR}`, `{{ var }}`, `vault://`, `your-secret`, etc.) and empty-RHS matches are dropped by default.
* **Rule priority** — a specific rule always wins over a generic catch-all on the same byte span.
* **Deterministic, portable output** — relative paths, stable ordering, JSON-first — baselines are checked into the repo and survive cwd changes.
* **Works in vis** — `vis secrets`, `vis migrate gitleaks`, `vis migrate secretlint`, `vis hook add secrets`.

## Related [#related]

* [`@visulima/vis`](/docs/packages/vis) — ships `vis secrets` on top of this package with migrations and pre-commit hook helpers.
* [gitleaks](https://github.com/gitleaks/gitleaks) — upstream detection engine (MIT) we vendor the ruleset from.


# Installation (/docs/packages/secret-scanner/installation)



# Installation [#installation]

## Package Managers [#package-managers]

### npm [#npm]

```bash
npm install @visulima/secret-scanner
```

### yarn [#yarn]

```bash
yarn add @visulima/secret-scanner
```

### pnpm [#pnpm]

```bash
pnpm add @visulima/secret-scanner
```

The right prebuilt native binary is pulled in automatically via `optionalDependencies`.

## Supported platforms [#supported-platforms]

| OS      | Arch  | libc         |
| ------- | ----- | ------------ |
| macOS   | x64   | —            |
| macOS   | arm64 | —            |
| Linux   | x64   | glibc / musl |
| Linux   | arm64 | glibc / musl |
| Windows | x64   | MSVC         |
| Windows | arm64 | MSVC         |

## Requirements [#requirements]

* **Node.js**: 22.13 or higher.
* No Go / gitleaks / Rust toolchain required at install time — the platform-matched prebuilt binary is downloaded from npm.

## First scan [#first-scan]

```typescript
import { scan } from "@visulima/secret-scanner";

const findings = await scan([process.cwd()]);

if (findings.length > 0) {
    console.warn(`Found ${String(findings.length)} potential secret(s).`);
}
```

If you prefer a CLI, install [`@visulima/vis`](/docs/packages/vis) and run `vis secrets`.


# Opt-in rule groups & custom rules (/docs/packages/secret-scanner/presets)



# Opt-in rule groups & custom rules [#opt-in-rule-groups--custom-rules]

## Bundled opt-in rule groups [#bundled-opt-in-rule-groups]

Some rule groups are noisy by design and ship **disabled by default** inside every bundled ruleset. Each rule in a group is tagged `preset:<name>` and carries `defaultEnabled: false`; enable a whole group with a `tag:preset:<name>` entry in `rules.include`.

```typescript
import { scan } from "@visulima/secret-scanner";

// Additive: defaults still fire, plus weak-passwords findings on top
const findings = await scan([process.cwd()], {
    rules: { enable: ["tag:preset:weak-passwords"] },
});

// Whitelist: scan runs everything, output is restricted to password-manager findings
const onlyVaults = await scan([process.cwd()], {
    rules: { include: ["tag:preset:password-manager"] },
});
```

Via the CLI:

```bash
vis secrets --enable-rule tag:preset:weak-passwords         # additive
vis secrets --include-rule tag:preset:password-manager       # restrict output
```

Two groups ship today: `weak-passwords` and `password-manager`. Combine them by repeating the flag.

### `weak-passwords` [#weak-passwords]

Low-entropy credential patterns commonly missed by `generic-api-key` (which ships with a 3.0 entropy floor). Adds a companion `low-entropy-api-key` rule at 2.0 entropy with a curated stopword list for obvious placeholder values (`changeme`, `example`, `your-*`, etc.).

Use it when your codebase contains weakly-hashed DB credentials, short static tokens, or the like. Expect more noise than the defaults — pair with `--update-baseline` when first enabling it.

### `password-manager` [#password-manager]

Detects committed password-manager export files — the kind of blast-radius leak a baseline can't quietly absorb.

Covers:

* **1Password** — `1PUX` export bundle, `1PIF` legacy export, CLI `OP_SESSION_*` session tokens
* **Bitwarden** — unencrypted and encrypted JSON vault exports
* **LastPass** — CSV exports (canonical header row)
* **KeePass** — `.kdbx` binary databases (path filter) and XML exports
* **Browser-native** — Chrome / Edge / Firefox password-manager CSV exports
* **Path catch-all** — files like `passwords.csv`, `vault-export.json`, `credentials-backup.kdbx`

Every rule has `priority: 5`, so these win over `generic-api-key` on any overlapping span. Because they're tagged `preset:password-manager` and default-disabled, they only fire when `rules.enable` (or `rules.include`) references `tag:preset:password-manager` or one of the individual rule ids.

## Authoring a custom ruleset [#authoring-a-custom-ruleset]

The runtime accepts gitleaks-compatible JSON. Author in TOML if you prefer the format, then convert once:

```bash
node -e 'import("smol-toml").then(m => process.stdout.write(JSON.stringify(m.parse(require("fs").readFileSync(0, "utf8")))))' < my-rules.toml > my-rules.json
```

Then reference it:

```typescript
await scan([process.cwd()], {
    config: { path: "./my-rules.json" },
});
```

Or inline:

```typescript
await scan([process.cwd()], {
    config: {
        inline: {
            title: "internal",
            rules: [
                {
                    id: "internal-api-key",
                    description: "Internal API key format",
                    regex: "int_[A-Za-z0-9]{32}",
                    keywords: ["int_"],
                    entropy: 3.0,
                },
            ],
        },
    },
});
```

### Priority [#priority]

When two rules match the same byte span on the same line, the higher-priority wins. Default is `0`.

```json
{
    "id": "my-specific-stripe-key",
    "regex": "sk_live_[A-Za-z0-9]{24,34}",
    "keywords": ["sk_live_"],
    "priority": 10
}
```

With `generic-api-key` at the default priority, this rule wins on every overlap.

### Per-rule pre-processor [#per-rule-pre-processor]

Rules can rewrite the scan buffer before their regex runs — useful for normalising escape sequences or splitting tokens across template delimiters.

```json
{
    "id": "joined-github-pat",
    "regex": "ghp_[A-Za-z0-9]{36}",
    "keywords": ["ghp_"],
    "preRegexReplace": [{ "from": "\\\\\\n", "to": "" }]
}
```

The pre-processor runs only for that rule; other rules see the original content.

### Target-scoped allowlists [#target-scoped-allowlists]

The gitleaks `targetRules` schema field applies an allowlist to specific rules only:

```json
{
    "allowlists": [
        {
            "description": "Placeholders we intentionally write in docs",
            "targetRules": ["github-pat"],
            "regexTarget": "secret",
            "stopwords": ["ghp_example", "ghp_placeholder"]
        }
    ]
}
```

With an empty `targetRules`, the allowlist applies to every rule (gitleaks' default).

## False-positive patches [#false-positive-patches]

The gitleaks ruleset is fetched from upstream at build time (pinned in `scripts/gitleaks.ref`). Additive improvements live in `data/gitleaks.patches.json` and are merged into `data/ruleset.json` during `pnpm run build:rules`. This keeps upstream re-syncs a single-ref bump while letting us tighten false positives without maintaining a fork.

Current patches focus on `generic-api-key`:

* **Placeholder stopwords** — `your-secret`, `changeme`, `replace-me`, `dummy-secret`, `xxxxxx`, etc.
* **Template interpolation** — `${VAR}`, `{{ var }}`, `vault://`, `$env:`, `arn:aws:*`.
* **Empty / whitespace RHS** — dropped unconditionally by the detector.

See the [Configuration](/docs/packages/secret-scanner/configuration#gitleaks-compatible-schema-extensions) page for the full schema.


# Suppression (/docs/packages/secret-scanner/suppression)



# Suppression [#suppression]

Four marker families plus a baseline file. All markers match **case-insensitively** and work regardless of the host-language comment syntax (`#`, `//`, `/* */`, `--`, `<!-- -->`, …) — the scanner looks for the marker text itself, not the delimiters.

## 1. Inline comment — `gitleaks:allow` / `secret-scanner:allow` / `pragma: allowlist secret` [#1-inline-comment--gitleaksallow--secret-scannerallow--pragma-allowlist-secret]

Put the marker on the same line as the match.

```typescript
const token = "ghp_aB3dE4fG5hI6jK7lM8nO9pQ0rS1tU2vW3xY4zA5b"; // gitleaks:allow
const other = "ghp_zY9xW8vU7tS6rQ5pO4nM3lK2jI1hG0fE9dC8bA7a"; // secret-scanner:allow
const third = "ghp_bB4cC5dD6eE7fF8gG9hH0iI1jJ2kK3lL4mM5nN6o"; // pragma: allowlist secret
```

`pragma: allowlist secret` is the [detect-secrets](https://github.com/Yelp/detect-secrets) marker, accepted for smooth migrations. The other two are the historical gitleaks + Visulima forms.

## 2. Block region — `gitleaks:allow-start` / `-end` [#2-block-region--gitleaksallow-start---end]

Suppresses every finding between two markers. Use for fixture blocks, test data, migration scripts and the like.

```typescript
// gitleaks:allow-start
const fixtures = {
    aws: "AKIAEXAMPLEEXAMPLEEX",
    stripe: "sk_live_fakefakefakefakefakefakefake",
};
// gitleaks:allow-end
```

Unpaired start markers are ignored — a stray `allow-start` never silently swallows the rest of the file.

Both `gitleaks:...` and `secret-scanner:...` are accepted for every variant (inline, start, end). Case-insensitive.

## 3. Previous-line pragma — `pragma: allowlist nextline secret` [#3-previous-line-pragma--pragma-allowlist-nextline-secret]

Covers the cases where an inline comment on the secret line is awkward (YAML block scalars) or impossible (PEM bodies, multi-line base64 blobs). Place the marker on the line **immediately before** the finding:

```yaml
# pragma: allowlist nextline secret
token: |
    <multi-line secret body here>
```

```python
# pragma: allowlist nextline secret
STRIPE_KEY = "sk_live_fakefakefakefakefakefakefake"
```

Only the immediately preceding line is checked — markers two or more lines up have no effect. For larger regions, use the `allow-start` / `allow-end` block form instead.

## 4. Baseline JSON [#4-baseline-json]

The richest form — an array of previously-triaged `Finding` objects checked into the repository.

```json
[
    {
        "ruleId": "aws-access-token",
        "file": "docs/examples.md",
        "startLine": 42,
        "endLine": 42,
        "startColumn": 9,
        "endColumn": 29,
        "match": "AKIAEXAMPLEEXAMPLEEX",
        "secret": "AKIAEXAMPLEEXAMPLEEX",
        "description": "AWS access key",
        "entropy": 3.5,
        "tags": []
    }
]
```

Pass it with the `baseline` option:

```typescript
import { scan } from "@visulima/secret-scanner";

const findings = await scan([process.cwd()], { baseline: ".secrets-baseline.json" });
```

The fingerprint used for matching is a **content hash** — SHA-256 over `(secret, ruleId, file)` truncated to 16 hex chars. This means moving a secret up or down the file doesn't invalidate its baseline entry; edits only invalidate the entry if the secret itself, the rule that matched, or the file path changes. Legacy `<file>:<ruleID>:<startLine>` baselines are still accepted on read, so older gitleaks-style baselines keep suppressing correctly while you migrate.

Malformed baselines log a stderr warning and are treated as empty — scans never fail because of a broken file.

### Baseline workflow [#baseline-workflow]

1. Run the first scan, triage what's real vs. noise.
2. Store the noise as a baseline: `vis secrets --init` (generates `.secrets-baseline.json`) or write one by hand.
3. Commit the baseline.
4. CI and pre-commit hooks now only flag *new* findings; triaged ones are silent.
5. Update with `vis secrets --update-baseline` when more noise surfaces, or `--replace-baseline` to rewrite wholesale.

### Why not `.gitleaksignore`? [#why-not-gitleaksignore]

`.gitleaksignore` stores only fingerprints (`file:rule:line`). Baselines store full `Finding` objects — same suppression semantics but enough context to see *what* was triaged, by whom, and which rule. The runtime only supports baseline JSON; the `vis migrate gitleaks` command converts legacy `.gitleaksignore` entries into the richer format.

## What about path exclusion? [#what-about-path-exclusion]

Suppression hides **findings**. If you want to hide **whole paths** from the walker, that's a different concern — use `.gitignore`, `walk.excludePatterns` or `walk.excludeFromFiles`. See [Configuration](/docs/packages/secret-scanner/configuration#walk--filesystem-traversal).

## What about automatic false-positive filtering? [#what-about-automatic-false-positive-filtering]

The scanner ships four always-on heuristic filters that drop known-placeholder findings (lock files, UUID shapes, sequential strings, non-alphanumeric masks) before they reach you. They aren't user-driven markers like the ones on this page, so they live on the [Configuration](/docs/packages/secret-scanner/configuration#heuristics--post-detection-false-positive-filters) page — toggle each with `config.heuristics.<name>: false` when you need the raw match set.


# API (/docs/packages/source-map/api)



# API Reference [#api-reference]

## `SourceMapConsumer.fromSourceMap(map)` [#sourcemapconsumerfromsourcemapmap]

Create consumer from source map object.

## `consumer.originalPositionFor(position)` [#consumeroriginalpositionforposition]

Get original position from generated.

**Parameters:**

* `line` (number)
* `column` (number)

**Returns:** Original position object

## `consumer.generatedPositionFor(position)` [#consumergeneratedpositionforposition]

Get generated position from original.


# Introduction (/docs/packages/source-map)



# @visulima/source-map [#visulimasource-map]

Parse, generate, and manipulate source maps for debugging transpiled JavaScript and TypeScript.

## Key Features [#key-features]

* Parse source maps
* Generate source maps
* Map positions
* Support for inline maps

## Quick Start [#quick-start]

```typescript
import { SourceMapConsumer } from "@visulima/source-map";

const map = await SourceMapConsumer.fromSourceMap(sourceMap);
const original = map.originalPositionFor({ line: 1, column: 0 });
```

<Cards>
  <Card title="Installation" href="/docs/packages/source-map/installation">
    Install
  </Card>

  <Card title="Quick Start" href="/docs/packages/source-map/quick-start">
    Get started
  </Card>

  <Card title="Usage" href="/docs/packages/source-map/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/source-map/api">
    API docs
  </Card>
</Cards>


# Installation (/docs/packages/source-map/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/source-map
```

## Import [#import]

```typescript
import { SourceMapConsumer, SourceMapGenerator } from "@visulima/source-map";
```


# Quick Start (/docs/packages/source-map/quick-start)



# Quick Start [#quick-start]

## Read Source Map [#read-source-map]

```typescript
import { SourceMapConsumer } from "@visulima/source-map";

const consumer = await SourceMapConsumer.fromSourceMap(rawMap);

const original = consumer.originalPositionFor({
    line: 10,
    column: 5,
});

console.log(original);
// { source: 'original.ts', line: 8, column: 3 }
```


# Usage (/docs/packages/source-map/usage)



# Usage [#usage]

## Parse Source Map [#parse-source-map]

```typescript
import { SourceMapConsumer } from "@visulima/source-map";

const map = await SourceMapConsumer.fromSourceMap(sourceMapObject);
```

## Map Positions [#map-positions]

```typescript
const original = map.originalPositionFor({
    line: generatedLine,
    column: generatedColumn,
});

const generated = map.generatedPositionFor({
    source: "original.ts",
    line: originalLine,
    column: originalColumn,
});
```


# Getting Started (/docs/packages/spinner/getting-started)



## Installation [#installation]

Install the package using your preferred package manager:



<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;, &#x22;bun&#x22;]">
  <Tab value="pnpm">
    ```bash
    pnpm add @visulima/spinner
    ```
  </Tab>

  <Tab value="npm">
    `bash npm install @visulima/spinner `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/spinner `
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @visulima/spinner
    ```
  </Tab>
</Tabs>

`@visulima/interactive-manager` is included as a dependency and provides terminal output coordination.

## Basic Usage [#basic-usage]

### Simple Spinner [#simple-spinner]

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
import { Spinner } from "@visulima/spinner";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

const spinner = new Spinner({ name: "dots" }, manager);

spinner.start("Processing...");

await processData();

spinner.succeed("Completed!");
```

### With Error Handling [#with-error-handling]

```typescript
const spinner = new Spinner({ name: "line" }, manager);

spinner.start("Connecting to database...");

try {
    await connectDB();
    spinner.succeed("Connected!");
} catch (error) {
    spinner.failed(`Failed: ${error.message}`);
}
```

### With Styling [#with-styling]

```typescript
// Declarative style — uses Node.js util.styleText
const spinner = new Spinner(
    {
        name: "breathe",
        style: { bold: true, color: "cyan" },
    },
    manager,
);

// Function style — full control
const spinner = new Spinner(
    {
        name: "breathe",
        style: (text) => `\x1b[1m\x1b[36m${text}\x1b[0m`,
    },
    manager,
);
```

### Custom Icons [#custom-icons]

```typescript
const spinner = new Spinner(
    {
        name: "dots",
        icons: {
            success: "DONE",
            error: "FAIL",
            warning: "WARN",
            info: "NOTE",
        },
    },
    manager,
);

spinner.start("Loading...");
spinner.succeed(); // Shows "DONE" icon
```

## Available Spinners [#available-spinners]

Get all available spinner names:

```typescript
import { getSpinnerNames } from "@visulima/spinner";

const names = getSpinnerNames();
console.log(names); // ['aesthetic', 'arc', 'arrow', ...]
```

Check out the [Spinner Reference](/docs/packages/spinner/spinners) to see all 109 spinners with previews and details.

## Disabling Output [#disabling-output]

```typescript
// Disable spinner output (useful in CI/testing)
const spinner = new Spinner({ name: "dots", verbose: false }, manager);
```

## See Also [#see-also]

* [Usage Guide](/docs/packages/spinner/usage) - Complete API reference with patterns
* [Spinner Reference](/docs/packages/spinner/spinners) - Browse all 109 available spinners


# Spinner (/docs/packages/spinner)



A terminal spinner library with 109 animations, styling support, multi-spinner management, and interactive terminal integration via `@visulima/interactive-manager`.

## Features [#features]

* **109 Spinners** - Curated animations from cli-spinners, Rattles, and unicode-animations
* **Styling** - Declarative `SpinnerStyle` objects or custom `(text) => string` functions
* **MultiSpinner** - Display and manage multiple spinners concurrently
* **Interactive Terminal** - Coordinates with `@visulima/interactive-manager` for dynamic output
* **Pause/Resume** - Pause and resume spinner animation
* **Custom Icons** - Configure success, failure, warning, and info icons
* **TypeScript** - Full type support out of the box

## Quick Example [#quick-example]

```typescript
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
import { Spinner } from "@visulima/spinner";

const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);

const spinner = new Spinner({ name: "dots" }, manager);

spinner.start("Loading...");
await doSomething();
spinner.succeed("Done!");
```

## Next Steps [#next-steps]

* [Getting Started](/docs/packages/spinner/getting-started) - Install and use in 30 seconds
* [Usage Guide](/docs/packages/spinner/usage) - Learn the Spinner API
* [Spinner Reference](/docs/packages/spinner/spinners) - Explore all 109 spinners


# Spinner Reference (/docs/packages/spinner/spinners)



All 109 spinners with their names, frame counts, and animation speed. Use any name in the `spinner` option.

> **Note on Emoji Rendering:** Some spinners include emoji characters (🌍, 🕛, etc.). These may render differently depending on your terminal, font, and operating system. If emoji spinners don't display properly, use spinners like `dots`, `line`, `breathe`, or `helix` instead.

## Braille Animations [#braille-animations]

Fast-moving Unicode braille character animations, perfect for smooth visual feedback.

| Name           | Frames | Speed | Preview        |
| -------------- | ------ | ----- | -------------- |
| `breathe`      | 17     | 100ms | ⠀ ⠂ ⠌ ⡑ ⢕      |
| `cascade`      | 13     | 60ms  | ⠀⠀⠀⠀ ⠁⠀⠀⠀ ⠋⠀⠀⠀ |
| `checkerboard` | 4      | 250ms | ⢕⢕⢕ ⡪⡪⡪ ⢊⠔⡡    |
| `columns`      | 26     | 60ms  | ⡀⠀⠀ ⡄⠀⠀ ⡆⠀⠀    |
| `diagSwipe`    | 16     | 60ms  | ⠁⠀ ⠋⠀ ⠟⠁       |
| `dna`          | 12     | 80ms  | ⠋⠉⠙⠚ ⠉⠙⠚⠒      |
| `fillSweep`    | 11     | 100ms | ⣀⣀ ⣤⣤ ⣶⣶       |
| `helix`        | 16     | 80ms  | ⢌⣉⢎⣉ ⣉⡱⣉⡱      |
| `infinity`     | 32     | 60ms  | ⢎⡱⣉⠆ ⢎⡱⣈⠆      |
| `orbit`        | 8      | 100ms | ⠃ ⠉ ⠘ ⠰        |
| `pulse`        | 5      | 180ms | ⠀⠶⠀ ⠰⣿⠆        |
| `rain`         | 12     | 100ms | ⢁⠂⠔⠈ ⠂⠌⡠⠐      |
| `scan`         | 10     | 70ms  | ⠀⠀⠀⠀ ⡇⠀⠀⠀      |
| `scanline`     | 6      | 120ms | ⠉⠉⠉ ⠓⠓⠓        |
| `snake`        | 16     | 80ms  | ⣁⡀ ⣉⠀ ⡉⠁       |
| `sparkle`      | 6      | 150ms | ⡡⠊⢔⠡ ⠊⡰⡡⡘      |
| `wave`         | 8      | 100ms | ⠁⠂⠄⡀ ⠂⠄⡀⢀      |
| `waveRows`     | 16     | 90ms  | ⠖⠉⠉⠑ ⡠⠖⠉⠉      |

## Dots & Lines [#dots--lines]

Classic dot sequences and simple line animations.

\| Name                  | Frames | Speed | Preview  |
\| --------------------- | ------ | ----- | -------- | --- |
\| `dots`                | 10     | 80ms  | ⠋ ⠙ ⠹ ⠸  |
\| `dots2`               | 8      | 80ms  | ⣾ ⣽ ⣻ ⣟  |
\| `dots3`               | 10     | 80ms  | ⠋ ⠙ ⠚ ⠞  |
\| `dots4`               | 14     | 80ms  | ⠄ ⠆ ⠇ ⠋  |
\| `dots5`               | 17     | 80ms  | ⠋ ⠙ ⠚ ⠞  |
\| `dots6`               | 24     | 80ms  | ⠁ ⠉ ⠙ ⠚  |
\| `dots7`               | 24     | 80ms  | ⠈ ⠉ ⠋ ⠓  |
\| `dots8`               | 29     | 80ms  | ⠁ ⠁ ⠉ ⠙  |
\| `dots8Bit`            | 256    | 80ms  | ⠀ ⠁ ⠂ ⠃  |
\| `dots9`               | 8      | 80ms  | ⢹ ⢺ ⢼ ⣸  |
\| `dots10`              | 7      | 80ms  | ⢄ ⢂ ⢁ ⡁  |
\| `dots11`              | 8      | 100ms | ⠁ ⠂ ⠄ ⡀  |
\| `dots12`              | 56     | 80ms  | ⢀⠀ ⡀⠀ ⠄⠀ |
\| `dots13`              | 8      | 80ms  | ⣼ ⣹ ⢻ ⠿  |
\| `dots14`              | 12     | 80ms  | ⠉⠉ ⠈⠙ ⠀⠹ |
\| `dotsCircle`          | 8      | 80ms  | ⢎ ⠎⠁ ⠊⠑  |
\| `line`                | 4      | 130ms | - \      | /   |
\| `line2`               | 6      | 100ms | ⠂ - –    |
\| `simpleDots`          | 4      | 400ms | . .. ... |
\| `simpleDotsScrolling` | 6      | 200ms | . .. ... |

## Arrows & Directions [#arrows--directions]

Animations showing direction and movement.

| Name          | Frames | Speed | Preview     |
| ------------- | ------ | ----- | ----------- |
| `arrow`       | 8      | 100ms | ← ↖ ↑ ↗     |
| `arrow2`      | 8      | 80ms  | ⬆️ ↗️ ➡️ ↘️ |
| `arrow3`      | 6      | 120ms | ▹▹▹▹▹ ▸▹▹▹▹ |
| `doubleArrow` | 8      | 100ms | ⇐ ⇖ ⇑ ⇗     |

## Shapes & Boxes [#shapes--boxes]

Box and circle animations.

| Name                        | Frames | Speed | Preview           |
| --------------------------- | ------ | ----- | ----------------- |
| `arc`                       | 6      | 100ms | ◜ ◠ ◝ ◞           |
| `bouncingBar`               | 16     | 80ms  | \[ ] \[= ] \[== ] |
| `bouncingBall`              | 10     | 80ms  | ( ● ) ( ● )       |
| `boxBounce`                 | 4      | 120ms | ▖ ▘ ▝ ▗           |
| `boxBounce2`                | 4      | 100ms | ▌ ▀ ▐ ▄           |
| `bounce`                    | 4      | 120ms | ⠁ ⠂ ⠄ ⠂           |
| `circle`                    | 3      | 120ms | ◡ ⊙ ◠             |
| `circleHalves`              | 4      | 50ms  | ◐ ◓ ◑ ◒           |
| `circleQuarters`            | 4      | 120ms | ◴ ◷ ◶ ◵           |
| `circleQuartersNegative`    | 4      | 120ms | ◵ ◶ ◷ ◴           |
| `circleQuartersNegativeAlt` | 4      | 120ms | ◶ ◷ ◴ ◵           |
| `growHorizontal`            | 12     | 120ms | ▏ ▎ ▍ ▌           |
| `growVertical`              | 10     | 120ms | ▁ ▃ ▄ ▅           |
| `hamburger`                 | 3      | 100ms | ☱ ☲ ☴             |
| `point`                     | 5      | 125ms | ∙∙∙ ●∙∙ ∙●∙       |
| `squareCorners`             | 4      | 180ms | ◰ ◳ ◲ ◱           |
| `triangle`                  | 4      | 50ms  | ◢ ◣ ◤ ◥           |

## Toggles & Effects [#toggles--effects]

Simple toggle switches and visual effects.

| Name       | Frames | Speed | Preview |
| ---------- | ------ | ----- | ------- |
| `toggle`   | 2      | 250ms | ⊶ ⊷     |
| `toggle2`  | 2      | 80ms  | ▫ ▪     |
| `toggle3`  | 2      | 120ms | □ ■     |
| `toggle4`  | 4      | 100ms | ■ □ ▪ ▫ |
| `toggle5`  | 2      | 100ms | ▮ ▯     |
| `toggle6`  | 2      | 300ms | ဝ ၀     |
| `toggle7`  | 2      | 80ms  | ⦾ ⦿     |
| `toggle8`  | 2      | 100ms | ◍ ◌     |
| `toggle9`  | 2      | 100ms | ◉ ◎     |
| `toggle10` | 3      | 100ms | ㊂ ㊀ ㊁   |
| `toggle11` | 2      | 50ms  | ⧇ ⧆     |
| `toggle12` | 2      | 120ms | ☗ ☖     |
| `toggle13` | 3      | 80ms  | = \* -  |

## Creative & Complex [#creative--complex]

Complex animations and special effects.

\| Name              | Frames | Speed | Preview           |
\| ----------------- | ------ | ----- | ----------------- | --- |
\| `aesthetic`       | 8      | 80ms  | ▰▱▱▱▱▱▱ ▰▰▱▱▱▱▱   |
\| `balloon`         | 7      | 140ms | (space) . o       |
\| `bluePulse`       | 5      | 100ms | 🔹 🔷 🔵          |
\| `balloon2`        | 7      | 120ms | . o O °           |
\| `betaWave`        | 7      | 80ms  | ρββββββ βρβββββ   |
\| `binary`          | 10     | 80ms  | 010010 001100     |
\| `christmas`       | 2      | 400ms | 🌲 🎄             |
\| `dqpb`            | 4      | 100ms | d q p b           |
\| `dwarfFortress`   | 133    | 80ms  | Complex ASCII     |
\| `fillSweep`       | 11     | 100ms | ⣀⣀ ⣤⣤ ⣶⣶          |
\| `fish`            | 27     | 80ms  | ASCII fish        |
\| `flip`            | 12     | 70ms  | \_ / ‾            |
\| `hearts`          | 5      | 100ms | 💛 💙 💜          |
\| `layer`           | 3      | 150ms | - = ≡             |
\| `material`        | 92     | 17ms  | ███ progress bars |
\| `mindblown`       | 14     | 160ms | 😐 😮 💥          |
\| `noise`           | 3      | 100ms | ▓ ▒ ░             |
\| `orangeBluePulse` | 10     | 100ms | 🔸 🔶 🟠          |
\| `orangePulse`     | 5      | 100ms | 🔸 🔶 🟠          |
\| `pipe`            | 8      | 100ms | ┤ ┘ ┴ └           |
\| `pong`            | 30     | 80ms  | Pong game         |
\| `rollingLine`     | 8      | 80ms  | / - \             |     |
\| `sand`            | 35     | 80ms  | ⠁ ⠂ ⠄ ⡀           |
\| `shark`           | 26     | 120ms | ASCII shark       |
\| `smiley`          | 2      | 200ms | 😄 😝             |
\| `soccerHeader`    | 12     | 80ms  | ⚽ 🧑             |
\| `speaker`         | 4      | 160ms | 🔈 🔉 🔊          |
\| `squish`          | 2      | 100ms | ╫ ╪               |
\| `star`            | 6      | 70ms  | ✶ ✸ ✹ ✺           |
\| `star2`           | 3      | 80ms  | + x \*            |
\| `timeTravel`      | 12     | 100ms | 🕛 🕧 🕐          |
\| `weather`         | 23     | 100ms | ☀️ ⛅ ☁️ 🌧       |

## Earth & Space [#earth--space]

Earth and space-themed animations.

| Name    | Frames | Speed | Preview  |
| ------- | ------ | ----- | -------- |
| `clock` | 12     | 100ms | 🕛 🕐 🕑 |
| `earth` | 3      | 180ms | 🌍 🌎 🌏 |
| `moon`  | 8      | 80ms  | 🌑 🌒 🌓 |

## Interaction [#interaction]

Special interaction animations.

| Name          | Frames | Speed | Preview  |
| ------------- | ------ | ----- | -------- |
| `fingerDance` | 6      | 160ms | 🤘 🤟 🖖 |
| `fistBump`    | 7      | 80ms  | 🤜 👊 🤛 |
| `grenade`     | 14     | 80ms  | ، ′ ´    |
| `monkey`      | 4      | 300ms | 🙈 🙈 🙉 |
| `runner`      | 2      | 140ms | 🚶 🏃    |

## Usage [#usage]

Use any spinner name with the Spinner class:

```typescript
import { Spinner } from "@visulima/spinner";

const spinner = new Spinner({
    spinner: "breathe", // Use any name from above
    text: "Loading...",
});

spinner.start();
```

Get a random spinner:

```typescript
import { getRandomSpinner } from "@visulima/spinner";

const spinner = getRandomSpinner();
```

For more examples and patterns, see the [Usage Guide](/docs/packages/spinner/usage).

## Sources [#sources]

The spinners are sourced from three excellent open-source projects (all MIT licensed):

* **cli-spinners** by [Sindre Sorhus](https://github.com/sindresorhus/cli-spinners)
* **Rattles** by [vyfor](https://github.com/vyfor/rattles)
* **unicode-animations** by [gunnar gray](https://github.com/gunnargray-dev/unicode-animations)


# Usage Guide (/docs/packages/spinner/usage)



## Constructor [#constructor]

```typescript
import { Spinner } from "@visulima/spinner";

const spinner = new Spinner(options?, interactiveManager?);
```

### Options [#options]

| Option       | Type                                       | Default       | Description                |
| ------------ | ------------------------------------------ | ------------- | -------------------------- |
| `name`       | `SpinnerName`                              | `"dots"`      | Spinner animation name     |
| `prefixText` | `string`                                   | `""`          | Text before the spinner    |
| `style`      | `SpinnerStyle \| (text: string) => string` | —             | Style for frames and icons |
| `icons`      | `SpinnerIcons`                             | Default icons | Custom completion icons    |
| `verbose`    | `boolean`                                  | `true`        | Whether to output spinner  |

### SpinnerStyle Object [#spinnerstyle-object]

When passing a `SpinnerStyle` object, Node.js `util.styleText` is used:

```typescript
const spinner = new Spinner(
    {
        name: "dots",
        style: {
            bold: true,
            dim: false,
            italic: false,
            underline: false,
            strikethrough: false,
            color: "blue", // e.g., "red", "green", "cyan"
            bgColor: "bgWhite", // e.g., "bgRed", "bgBlue"
        },
    },
    manager,
);
```

### Style Function [#style-function]

For full control, pass a function:

```typescript
import colorize from "@visulima/colorize";

const spinner = new Spinner(
    {
        name: "dots",
        style: (text) => colorize.bold.blue(text),
    },
    manager,
);
```

### SpinnerIcons [#spinnericons]

```typescript
const spinner = new Spinner(
    {
        icons: {
            success: "✓", // default
            error: "✖", // default
            warning: "⚠", // default
            info: "ℹ", // default
        },
    },
    manager,
);
```

## Properties [#properties]

### text (get/set) [#text-getset]

Get or set the spinner text. Setting text while spinning triggers a re-render.

```typescript
spinner.text = "New message";
console.log(spinner.getText); // "New message"
```

### prefixText (get/set) [#prefixtext-getset]

Get or set the prefix text.

```typescript
spinner.prefixText = "[STEP 2]";
console.log(spinner.getPrefixText); // "[STEP 2]"
```

### isRunning (get) [#isrunning-get]

Whether the spinner is currently active.

```typescript
if (spinner.isRunning) {
    // spinner is animating
}
```

### elapsedTime (get) [#elapsedtime-get]

Milliseconds since the spinner was started.

```typescript
console.log(spinner.elapsedTime); // 1234
```

## Methods [#methods]

### start(text?, options?) [#starttext-options]

Start the spinner. Returns `this` for chaining.

```typescript
spinner.start();
spinner.start("Loading...");
spinner.start("Loading...", { prefixText: "[INFO]" });
```

### succeed(text?) [#succeedtext]

Stop with success icon and optional message.

```typescript
spinner.succeed();
spinner.succeed("Operation completed!");
```

### failed(text?) [#failedtext]

Stop with error icon and optional message.

```typescript
spinner.failed();
spinner.failed("Something went wrong");
```

### warn(text?) [#warntext]

Stop with warning icon and optional message.

```typescript
spinner.warn();
spinner.warn("Proceed with caution");
```

### info(text?) [#infotext]

Stop with info icon and optional message.

```typescript
spinner.info();
spinner.info("FYI: 42 items processed");
```

### pause() [#pause]

Pause the animation without stopping the spinner. The spinner remains in "running" state.

```typescript
spinner.pause();
```

### resume() [#resume]

Resume a paused spinner.

```typescript
spinner.resume();
```

## MultiSpinner [#multispinner]

Manage multiple spinners concurrently with coordinated rendering.

### Constructor [#constructor-1]

```typescript
import { MultiSpinner } from "@visulima/spinner";

const multi = new MultiSpinner(options?, interactiveManager?);
```

Options are the same as `SpinnerOptions` — they serve as defaults for all created spinners.

### create(text?, options?) [#createtext-options]

Create a new spinner within the multi-spinner manager. Options override the defaults.

```typescript
const spinner1 = multi.create("Task 1");
const spinner2 = multi.create("Task 2", { name: "line" });
```

### remove(spinner) [#removespinner]

Remove a spinner from the manager.

```typescript
multi.remove(spinner1); // returns true if found
```

### stop() [#stop]

Stop all spinners (calls `succeed()` on each) and unhook the interactive manager.

```typescript
multi.stop();
```

### clear() [#clear]

Succeed all spinners and clear the internal map, but don't unhook.

```typescript
multi.clear();
```

## Patterns [#patterns]

### Sequential Tasks [#sequential-tasks]

```typescript
const spinner = new Spinner({ name: "dots" }, manager);

spinner.start("Task 1...");
await task1();
spinner.succeed("Task 1 done");

spinner.start("Task 2...");
await task2();
spinner.succeed("Task 2 done");
```

### Parallel Tasks with MultiSpinner [#parallel-tasks-with-multispinner]

```typescript
const multi = new MultiSpinner({ name: "dots" }, manager);

const s1 = multi.create("Downloading...");
const s2 = multi.create("Compiling...");
const s3 = multi.create("Testing...");

s1.start();
s2.start();
s3.start();

await Promise.all([download().then(() => s1.succeed("Downloaded")), compile().then(() => s2.succeed("Compiled")), test().then(() => s3.succeed("Tested"))]);

multi.stop();
```

### Helper Function [#helper-function]

```typescript
async function withSpinner<T>(text: string, fn: () => Promise<T>, manager: InteractiveManager, name: SpinnerName = "dots"): Promise<T> {
    const spinner = new Spinner({ name }, manager);

    spinner.start(text);
    try {
        const result = await fn();
        spinner.succeed();
        return result;
    } catch (error) {
        spinner.failed(error instanceof Error ? error.message : "Failed");
        throw error;
    }
}

await withSpinner("Building...", build, manager, "line");
```

## Utility Functions [#utility-functions]

### getSpinner(name) [#getspinnername]

Get spinner definition by name.

```typescript
import { getSpinner } from "@visulima/spinner";

const spinner = getSpinner("dots");
// Returns: { frames: [...], interval: 80 }
```

### getSpinnerNames() [#getspinnernames]

Get array of all available spinner names.

```typescript
import { getSpinnerNames } from "@visulima/spinner";

const names = getSpinnerNames();
console.log(names.length); // 109
```

### getRandomSpinner() [#getrandomspinner]

Get a random spinner definition.

```typescript
import { getRandomSpinner } from "@visulima/spinner";

const randomSpinner = getRandomSpinner();
```


# Authenticated File Uploads (/docs/packages/storage/authenticated-file-uploads)



# Authenticated File Uploads [#authenticated-file-uploads]

## Overview [#overview]

This guide shows you how to implement authenticated file uploads with Visulima Storage. We'll use [Better Auth](https://www.better-auth.com) as the authentication solution, but the patterns shown here can be adapted to other authentication libraries. Instead of creating a Better Auth plugin, we'll use Better Auth for authentication middleware and the storage handlers directly with your web framework (Express, Hono, Fastify, etc.).

This approach provides:

* **Better separation of concerns**: Auth handles authentication, storage handles file operations
* **More flexibility**: Use any web framework with existing, well-tested handlers
* **Easier maintenance**: Leverage existing storage handler APIs
* **Framework agnostic**: Works with Express, Hono, Fastify, and any framework supporting middleware

## Installation [#installation]

First, install Better Auth, Visulima Storage, and your chosen framework:

```bash
npm install better-auth @visulima/storage express
# or
npm install better-auth @visulima/storage hono
# or
npm install better-auth @visulima/storage fastify
```

For cloud storage backends, install the corresponding peer dependencies:

```bash
# For AWS S3
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types

# For Google Cloud Storage
npm install @google-cloud/storage node-fetch gaxios

# For Azure Blob Storage
npm install @azure/storage-blob
```

## Basic Setup [#basic-setup]

### 1. Configure Better Auth [#1-configure-better-auth]

Create an `auth.ts` file to configure Better Auth:

```typescript
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@/db";

export const auth = betterAuth({
    database: drizzleAdapter(db, {
        provider: "pg", // or "mysql", "sqlite"
    }),
    emailAndPassword: {
        enabled: true,
    },
});
```

### 2. Create Type Definitions (Recommended) [#2-create-type-definitions-recommended]

Create proper TypeScript types for better type safety:

```typescript
// types/express.d.ts
import type { User } from "better-auth/types";

declare global {
    namespace Express {
        interface Request {
            user?: User;
        }
    }
}
```

### 3. Create Authentication Middleware [#3-create-authentication-middleware]

Create middleware to protect your file upload routes:

> **Note**: The Better Auth API may vary by version. The following example uses `auth.api.getSession()`. Please refer to the [Better Auth documentation](https://www.better-auth.com/docs) for the exact API in your version.

```typescript
// middleware/auth.ts
import type { Request, Response, NextFunction } from "express";
import { auth } from "@/lib/auth";

export const requireAuth = async (req: Request, res: Response, next: NextFunction) => {
    try {
        // Get session from Better Auth
        // Note: API may vary - check Better Auth docs for your version
        const session = await auth.api.getSession({
            headers: req.headers as any,
        });

        if (!session) {
            return res.status(401).json({ error: "Unauthorized" });
        }

        // Attach user to request (now properly typed with the type definition above)
        req.user = session.user;
        next();
    } catch (error) {
        return res.status(401).json({ error: "Unauthorized" });
    }
};
```

## Express Integration [#express-integration]

### Basic Example with Multipart Handler [#basic-example-with-multipart-handler]

```typescript
import express from "express";
import { DiskStorage, Multipart } from "@visulima/storage";
import { auth } from "@/lib/auth";
import { requireAuth } from "@/middleware/auth";

const app = express();

// Mount Better Auth routes first (before file routes)
app.all("/api/auth/*", (req, res) => {
    return auth.handler(req, res);
});

// Initialize storage with OWASP-compliant validation
// See: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
const storage = new DiskStorage({
    directory: "./uploads", // Store outside webroot in production
    maxUploadSize: "50MB", // Prevent DoS attacks
    // Use allowlist approach - only allow business-critical extensions
    allowMIME: [
        "image/jpeg", // Explicitly list allowed types
        "image/png",
        "image/webp",
        "application/pdf", // Avoid wildcards when possible
    ],
    // Storage automatically generates UUID-based filenames (OWASP recommended)
    filename: (file) => file.id, // UUID prevents path traversal and overwrite attacks
});

const multipart = new Multipart({ storage });

// Protected upload endpoint
app.post("/api/files", requireAuth, multipart.handle, async (req, res) => {
    try {
        const file = req.body; // File object from storage handler
        const user = req.user; // User from Better Auth (properly typed)

        // Store file-user association in database (recommended)
        await db.file.create({
            data: {
                storageId: file.id,
                userId: user.id,
                name: file.originalName,
                size: file.size,
                contentType: file.contentType,
            },
        });

        res.json({
            id: file.id,
            url: `/api/files/${file.id}`,
            size: file.size,
            contentType: file.contentType,
        });
    } catch (error) {
        console.error("Upload error:", error);
        // If database save fails, clean up storage file
        if (req.body?.id) {
            await storage.delete({ id: req.body.id }).catch(() => {});
        }
        res.status(500).json({ error: "Failed to save file" });
    }
});

// Protected file retrieval
app.get(
    "/api/files/:id",
    requireAuth,
    multipart.handle, // Handles GET requests to stream files
    (req, res) => {
        // File is automatically streamed by the handler
    },
);

// Protected file deletion
app.delete("/api/files/:id", requireAuth, async (req, res) => {
    try {
        const { id } = req.params;
        const user = req.user; // Properly typed with Express type definition

        // Always verify ownership before deletion
        const fileRecord = await db.file.findFirst({
            where: { storageId: id, userId: user.id },
        });

        if (!fileRecord) {
            return res.status(403).json({ error: "Forbidden" });
        }

        // Use transaction to ensure both operations succeed or fail together
        await db.$transaction(async (tx) => {
            await storage.delete({ id });
            await tx.file.delete({ where: { id: fileRecord.id } });
        });

        res.status(204).send();
    } catch (error) {
        console.error("Delete error:", error);
        res.status(500).json({ error: "Failed to delete file" });
    }
});
```

### Advanced Example with User-Scoped Storage [#advanced-example-with-user-scoped-storage]

```typescript
import express from "express";
import { DiskStorage, Multipart } from "@visulima/storage";
import { requireAuth } from "@/middleware/auth";

const app = express();

// Create storage with user-specific file naming
// Note: filename function runs during file creation, before user metadata is available
// For user-scoped paths, store user association in database and use it for organization
const storage = new DiskStorage({
    directory: "./uploads",
    filename: (file) => {
        // Files are organized by ID. User association stored in database
        return file.id;
    },
});

const multipart = new Multipart({ storage });

// Upload with user metadata
// Configure storage onCreate hook to inject user metadata
const originalOnCreate = storage.onCreate;
storage.onCreate = async (file) => {
    // Note: This runs for all uploads. For per-request user data,
    // consider using storage options or storing user association after upload
    if (originalOnCreate) {
        await originalOnCreate(file);
    }
};

app.post("/api/files", requireAuth, multipart.handle, async (req, res) => {
    const file = req.body;
    const user = req.user; // Properly typed

    // Store file-user association in database
    // await db.file.create({
    //     data: {
    //         storageId: file.id,
    //         userId: user.id,
    //         name: file.originalName,
    //     },
    // });

    res.json({
        id: file.id,
        url: `/api/files/${file.id}`,
        size: file.size,
    });
});

// List user's files
app.get("/api/files", requireAuth, async (req, res) => {
    const user = (req as any).user;

    // Get user's files from database (recommended approach)
    // const files = await db.file.findMany({
    //     where: { userId: user.id },
    // });
    // res.json({ files });

    // Alternative: Filter from storage metadata (if you set it)
    const allFiles = await storage.list(1000);
    const userFiles = allFiles.filter((file) => file.metadata?.userId === user.id);

    res.json({ files: userFiles });
});
```

## Hono Integration [#hono-integration]

Hono works seamlessly with Better Auth and the storage handlers:

```typescript
import { Hono } from "hono";
import { DiskStorage, Multipart } from "@visulima/storage";
import { auth } from "@/lib/auth";

const app = new Hono();
const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// Authentication middleware for Hono
const requireAuth = async (c: any, next: () => Promise<void>) => {
    try {
        const session = await auth.api.getSession({
            headers: c.req.raw.headers as any,
        });

        if (!session) {
            return c.json({ error: "Unauthorized" }, 401);
        }

        // Store user in Hono context
        c.set("user", session.user);
        await next();
    } catch {
        return c.json({ error: "Unauthorized" }, 401);
    }
};

// Protected upload endpoint
app.post("/api/files", requireAuth, async (c) => {
    const user = c.get("user");

    // Use multipart.fetch for Web API Request/Response
    const response = await multipart.fetch(c.req.raw);

    if (response.ok) {
        const file = await response.json();

        // Optionally store file-user association
        // await db.file.create({
        //     data: {
        //         storageId: file.id,
        //         userId: user.id,
        //     },
        // });

        return c.json({
            id: file.id,
            url: `/api/files/${file.id}`,
            size: file.size,
        });
    }

    return response;
});

// Protected file retrieval
app.get("/api/files/:id", requireAuth, async (c) => {
    return await multipart.fetch(c.req.raw);
});

// Protected file deletion
app.delete("/api/files/:id", requireAuth, async (c) => {
    const { id } = c.req.param("id");
    await storage.delete({ id });
    return c.body(null, 204);
});
```

## Fastify Integration [#fastify-integration]

```typescript
import Fastify from "fastify";
import { DiskStorage, Multipart } from "@visulima/storage";
import { auth } from "@/lib/auth";

const fastify = Fastify();
const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// Authentication decorator
fastify.decorate("requireAuth", async (request: any, reply: any) => {
    try {
        const session = await auth.api.getSession({
            headers: request.headers as any,
        });

        if (!session) {
            return reply.code(401).send({ error: "Unauthorized" });
        }

        request.user = session.user;
    } catch {
        return reply.code(401).send({ error: "Unauthorized" });
    }
});

// Protected upload endpoint
fastify.post("/api/files", { preHandler: fastify.requireAuth }, async (request, reply) => {
    // Convert Fastify request to Web API Request
    const webRequest = new Request(`http://localhost${request.url}`, {
        method: request.method,
        headers: request.headers as any,
        body: request.raw,
    });

    const response = await multipart.fetch(webRequest);
    const file = await response.json();

    return reply.send({
        id: file.id,
        url: `/api/files/${file.id}`,
        size: file.size,
    });
});
```

## REST Handler Example [#rest-handler-example]

For direct binary uploads or API-first applications:

```typescript
import express from "express";
import { DiskStorage, Rest } from "@visulima/storage";
import { requireAuth } from "@/middleware/auth";

const app = express();
const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Upload binary data
app.post("/api/files", requireAuth, rest.handle, (req, res) => {
    const file = req.body;
    res.json({
        id: file.id,
        url: `/api/files/${file.id}`,
    });
});

// Update file (PUT)
app.put("/api/files/:id", requireAuth, rest.handle, (req, res) => {
    const file = req.body;
    res.json({ id: file.id });
});

// Batch delete
app.delete("/api/files", requireAuth, rest.handle, (req, res) => {
    // Handler processes ?ids=id1,id2,id3 or JSON body
    res.status(204).send();
});
```

## TUS Handler for Resumable Uploads [#tus-handler-for-resumable-uploads]

For large files or unreliable networks:

```typescript
import express from "express";
import { DiskStorage, Tus } from "@visulima/storage";
import { requireAuth } from "@/middleware/auth";

const app = express();
const storage = new DiskStorage({ directory: "./uploads" });
const tus = new Tus({ storage });

// TUS endpoints (all protected)
app.post("/api/files/tus", requireAuth, tus.handle);
app.patch("/api/files/tus/:id", requireAuth, tus.handle);
app.head("/api/files/tus/:id", requireAuth, tus.handle);
app.delete("/api/files/tus/:id", requireAuth, tus.handle);
```

## Cloud Storage Examples [#cloud-storage-examples]

### AWS S3 with Better Auth [#aws-s3-with-better-auth]

```typescript
import express from "express";
import { S3Storage, Multipart } from "@visulima/storage/provider/aws";
import { requireAuth } from "@/middleware/auth";

const app = express();
const storage = new S3Storage({
    bucket: process.env.S3_BUCKET,
    region: process.env.S3_REGION,
    credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    },
    filename: (file) => {
        // Files organized by ID. User association stored separately in database
        return file.id;
    },
});

const multipart = new Multipart({ storage });

app.post("/api/files", requireAuth, multipart.handle, (req, res) => {
    res.json({ id: req.body.id, url: req.body.url });
});
```

### Google Cloud Storage [#google-cloud-storage]

```typescript
import { GCStorage, Multipart } from "@visulima/storage/provider/gcs";
import { requireAuth } from "@/middleware/auth";

const storage = new GCStorage({
    bucket: process.env.GCS_BUCKET,
    projectId: process.env.GCS_PROJECT_ID,
});

const multipart = new Multipart({ storage });

app.post("/api/files", requireAuth, multipart.handle, (req, res) => {
    res.json({ id: req.body.id });
});
```

## Client-Side Usage [#client-side-usage]

### Upload with Authentication [#upload-with-authentication]

```typescript
import { createAuthClient } from "better-auth/react";

const authClient = createAuthClient({
    baseURL: "http://localhost:3000",
});

// Upload file
const uploadFile = async (file: File) => {
    const session = await authClient.getSession();
    if (!session) {
        throw new Error("Not authenticated");
    }

    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/files", {
        method: "POST",
        headers: {
            // Better Auth automatically includes auth headers
            Cookie: document.cookie,
        },
        body: formData,
    });

    if (!response.ok) {
        throw new Error("Upload failed");
    }

    return response.json();
};
```

## Best Practices [#best-practices]

### Authentication & Authorization [#authentication--authorization]

1. **Always validate authentication** before file operations - Use middleware on all file endpoints
2. **Verify file ownership** before allowing access, update, or deletion
3. **Store file-user associations** in your database for reliable ownership tracking
4. **Use database transactions** when creating file records to ensure consistency
5. **Implement role-based access control** if you need different permissions for different user roles

### File Management (OWASP Compliant) [#file-management-owasp-compliant]

6. **Use separate upload endpoints for different file types** - Create dedicated endpoints for avatars, documents, images, etc. This allows different validation rules, storage locations, and access controls per file type
7. **Use allowlist for file extensions** - Only allow business-critical extensions. Never rely on blocklist alone ([OWASP](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html))
8. **Validate file signatures (magic bytes)** - Don't trust Content-Type header. Validate actual file content against expected signatures
9. **Validate file types and sizes** using storage validation options (`allowMIME`, `maxUploadSize`)
10. **Filename safety** - Storage automatically generates UUID-based filenames, preventing path traversal and overwrite attacks
11. **Implement per-user storage quotas** to prevent abuse
12. **Use database for file metadata** - Don't rely solely on storage metadata for user associations
13. **Implement cleanup jobs** for orphaned files when users are deleted
14. **Use signed URLs** for private file access (S3, GCS, Azure) instead of public URLs
15. **File content validation** - For images, use image rewriting/transformation. For documents, consider CDR (Content Disarm & Reconstruct)
16. **Antivirus/Sandbox scanning** - Run files through antivirus or sandbox in production environments

### Security (OWASP Compliant) [#security-owasp-compliant]

17. **Implement rate limiting** for upload endpoints to prevent abuse and DoS attacks
18. **Sanitize file names** - Storage handlers automatically generate UUID-based filenames, preventing path traversal
19. **Set appropriate permissions** on storage backends (private buckets/containers) - Use least privilege principle
20. **Use HTTPS** for all file transfers
21. **Validate file content** - Always validate actual file content, not just MIME types
22. **Don't expose internal errors** - Return generic error messages to clients
23. **Protect from CSRF attacks** - Ensure CSRF protection is enabled (Better Auth handles this)
24. **Keep libraries updated** - Regularly update Better Auth, storage package, and all dependencies
25. **File storage location** - Prefer storing files on different host or outside webroot ([OWASP](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html))
26. **Use handler mapping** - Access files via application handler instead of direct paths to prevent file enumeration

### Performance & Reliability [#performance--reliability]

27. **Use database indexes** on `userId` and `storageId` columns for fast lookups
28. **Implement proper error handling** with try-catch blocks
29. **Add logging** for file operations (upload, delete, access) for auditing
30. **Use connection pooling** for database operations
31. **Monitor storage usage** per user to detect anomalies

### Code Quality [#code-quality]

32. **Use TypeScript types** - Avoid `any` types, create proper interfaces for request extensions
33. **Validate environment variables** at startup
34. **Mount Better Auth routes** separately from file routes for clarity
35. **Handle session expiration** gracefully with proper error messages

## Security Considerations [#security-considerations]

### Authentication & Session Management [#authentication--session-management]

* **Always use `requireAuth` middleware** on file endpoints - Never skip authentication
* **Handle session expiration** - Return clear error messages when sessions expire
* **Validate session freshness** - Consider checking session age for sensitive operations
* **Mount Better Auth routes** - Ensure Better Auth handles its own routes (`/api/auth/*`)

### Authorization & Access Control [#authorization--access-control]

* **Verify file ownership** before allowing access, update, or deletion
* **Use database lookups** for ownership verification - Don't trust client-provided data
* **Implement role-based access** if needed - Check user roles before allowing operations
* **Return 403 Forbidden** (not 404) when user lacks permission - Prevents information leakage

### File Validation (OWASP Compliant) [#file-validation-owasp-compliant]

Following [OWASP File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) recommendations:

* **Use allowlist for extensions** - Only allow business-critical extensions (e.g., `.jpg`, `.png`, `.pdf`). Never use blocklist approach alone
* **Configure `allowMIME`** in storage options to restrict file types - This is a quick check but not sufficient alone
* **Validate file signatures (magic bytes)** - Don't trust Content-Type header as it can be spoofed. Validate actual file content against expected file signatures
* **Set `maxUploadSize`** to prevent oversized uploads and DoS attacks
* **Validate file content** - MIME type can be spoofed, always validate actual file content
* **Filename safety** - Storage automatically generates UUID-based filenames, which prevents path traversal and overwrite attacks
* **Consider virus scanning** - Run files through antivirus or sandbox in production
* **Content Disarm & Reconstruct (CDR)** - For documents (PDF, DOCX, etc.), consider CDR to remove potentially malicious content
* **Sanitize file names** - Storage handlers automatically sanitize file paths and generate safe filenames

### Infrastructure Security (OWASP Compliant) [#infrastructure-security-owasp-compliant]

Following [OWASP File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) recommendations:

* **File Storage Location** (in priority order):
  1. **Store files on a different host** - Complete segregation between application and file storage
  2. **Store files outside webroot** - Only administrative access allowed
  3. **Store inside webroot with write-only permissions** - If read access needed, use proper controls (internal IP, authorized users)
* **Path Traversal**: Storage handlers automatically sanitize file paths and generate UUID-based filenames
* **Use handler mapping** - Access files via application handler (`/api/files/:id`) instead of direct file paths. Storage uses ID-based access which prevents direct file enumeration
* **CORS**: Configure CORS appropriately - Only allow trusted origins
* **Rate Limiting**: Implement rate limiting to prevent abuse and DoS attacks
* **Use private storage buckets** - Don't make storage buckets/containers publicly accessible
* **Use signed URLs** for temporary access instead of public URLs (S3, GCS, Azure)
* **Filesystem permissions** - Set files with least privilege principle (read/write for required users only)
* **Encrypt sensitive files** at rest if required by compliance
* **Protect from CSRF** - Ensure Better Auth and your framework handle CSRF protection

### Error Handling [#error-handling]

* **Don't expose internal errors** - Return generic messages to clients
* **Log errors server-side** - Include user ID, file ID, and operation type
* **Handle storage failures gracefully** - Implement retry logic for transient failures
* **Validate all inputs** - Check file IDs, user IDs, and other parameters

## Separate Upload Endpoints for Different File Types [#separate-upload-endpoints-for-different-file-types]

Using separate upload endpoints for different file types (avatars, documents, images, etc.) is a security best practice that provides:

* **Different validation rules** per file type (size limits, allowed MIME types)
* **Different storage locations** for better organization
* **Different access controls** and permissions
* **Easier monitoring and auditing** of file operations
* **Better error handling** with type-specific error messages

### Example: Separate Endpoints for Avatars and Documents [#example-separate-endpoints-for-avatars-and-documents]

```typescript
import express from "express";
import { DiskStorage, Multipart } from "@visulima/storage";
import { requireAuth } from "@/middleware/auth";
import { db } from "@/db";

const app = express();

// Avatar storage - optimized for small images
const avatarStorage = new DiskStorage({
    directory: "./uploads/avatars",
    maxUploadSize: "5MB", // Smaller limit for avatars
    allowMIME: ["image/jpeg", "image/png", "image/webp"], // Only image types
    filename: (file) => file.id, // UUID-based filename
});

const avatarHandler = new Multipart({ storage: avatarStorage });

// Document storage - for PDFs, DOCX, etc.
const documentStorage = new DiskStorage({
    directory: "./uploads/documents",
    maxUploadSize: "50MB", // Larger limit for documents
    allowMIME: ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
    filename: (file) => file.id,
});

const documentHandler = new Multipart({ storage: documentStorage });

// Avatar upload endpoint
app.post("/api/avatars", requireAuth, avatarHandler.handle, async (req, res) => {
    try {
        const file = req.body;
        const user = req.user;

        // Additional validation for avatars (e.g., image dimensions)
        // You can use ImageTransformer to validate/transform images

        await db.file.create({
            data: {
                storageId: file.id,
                userId: user.id,
                name: file.originalName,
                size: file.size,
                contentType: file.contentType,
                category: "avatar", // Track file category
            },
        });

        res.json({
            id: file.id,
            url: `/api/avatars/${file.id}`,
            size: file.size,
        });
    } catch (error) {
        console.error("Avatar upload error:", error);
        if (req.body?.id) {
            await avatarStorage.delete({ id: req.body.id }).catch(() => {});
        }
        res.status(500).json({ error: "Failed to upload avatar" });
    }
});

// Document upload endpoint
app.post("/api/documents", requireAuth, documentHandler.handle, async (req, res) => {
    try {
        const file = req.body;
        const user = req.user;

        // Additional validation for documents (e.g., file signature validation)
        // Consider CDR (Content Disarm & Reconstruct) for documents

        await db.file.create({
            data: {
                storageId: file.id,
                userId: user.id,
                name: file.originalName,
                size: file.size,
                contentType: file.contentType,
                category: "document", // Track file category
            },
        });

        res.json({
            id: file.id,
            url: `/api/documents/${file.id}`,
            size: file.size,
        });
    } catch (error) {
        console.error("Document upload error:", error);
        if (req.body?.id) {
            await documentStorage.delete({ id: req.body.id }).catch(() => {});
        }
        res.status(500).json({ error: "Failed to upload document" });
    }
});

// Separate retrieval endpoints
app.get("/api/avatars/:id", requireAuth, avatarHandler.handle);
app.get("/api/documents/:id", requireAuth, documentHandler.handle);

// Separate deletion endpoints with category-specific logic
app.delete("/api/avatars/:id", requireAuth, async (req, res) => {
    const { id } = req.params;
    const user = req.user;

    const fileRecord = await db.file.findFirst({
        where: { storageId: id, userId: user.id, category: "avatar" },
    });

    if (!fileRecord) {
        return res.status(403).json({ error: "Forbidden" });
    }

    await db.$transaction(async (tx) => {
        await avatarStorage.delete({ id });
        await tx.file.delete({ where: { id: fileRecord.id } });
    });

    res.status(204).send();
});
```

### Benefits of Separate Endpoints [#benefits-of-separate-endpoints]

1. **Type-specific validation** - Different file size limits and MIME types per endpoint
2. **Better organization** - Files stored in separate directories/buckets
3. **Easier monitoring** - Track uploads by category (avatar, document, etc.)
4. **Flexible access control** - Different permissions per file type
5. **Simpler error handling** - Type-specific error messages
6. **Better performance** - Optimize storage configuration per file type

## Complete Example: Express + Better Auth + S3 [#complete-example-express--better-auth--s3]

```typescript
import express from "express";
import { S3Storage, Multipart } from "@visulima/storage/provider/aws";
import { auth } from "@/lib/auth";
import { requireAuth } from "@/middleware/auth";
import { db } from "@/db";

const app = express();
app.use(express.json());

const storage = new S3Storage({
    bucket: process.env.S3_BUCKET,
    region: process.env.S3_REGION,
    credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    },
    maxUploadSize: "50MB",
    allowMIME: ["image/*", "application/pdf"],
    filename: (file) => {
        // Files organized by ID. User association stored separately in database
        return file.id;
    },
});

const multipart = new Multipart({ storage });

// Upload endpoint
app.post("/api/files", requireAuth, multipart.handle, async (req, res) => {
    const file = req.body;
    const user = req.user; // Properly typed

    // Store file record in database with user association
    await db.file.create({
        data: {
            storageId: file.id,
            userId: user.id,
            name: file.originalName,
            size: file.size,
            contentType: file.contentType,
        },
    });

    res.json({
        id: file.id,
        url: `/api/files/${file.id}`,
        size: file.size,
    });
});

// List user's files
app.get("/api/files", requireAuth, async (req, res) => {
    const user = (req as any).user;
    const files = await db.file.findMany({
        where: { userId: user.id },
    });
    res.json({ files });
});

// Get file
app.get(
    "/api/files/:id",
    requireAuth,
    async (req, res, next) => {
        const { id } = req.params;
        const user = (req as any).user;

        // Verify ownership
        const fileRecord = await db.file.findFirst({
            where: { storageId: id, userId: user.id },
        });

        if (!fileRecord) {
            return res.status(403).json({ error: "Forbidden" });
        }

        next();
    },
    multipart.handle,
);

// Delete file
app.delete("/api/files/:id", requireAuth, async (req, res) => {
    const { id } = req.params;
    const user = (req as any).user;

    // Verify ownership
    const fileRecord = await db.file.findFirst({
        where: { storageId: id, userId: user.id },
    });

    if (!fileRecord) {
        return res.status(403).json({ error: "Forbidden" });
    }

    await storage.delete({ id });
    await db.file.delete({ where: { id: fileRecord.id } });

    res.status(204).send();
});

app.listen(3000, () => {
    console.log("Server running on port 3000");
});
```

## OWASP File Upload Security [#owasp-file-upload-security]

This guide follows security best practices from the [OWASP File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html). Key security measures implemented:

* ✅ **Allowlist-based extension validation** - Only business-critical extensions allowed
* ✅ **UUID-based filename generation** - Prevents path traversal and file overwrite attacks
* ✅ **File size limits** - Prevents DoS attacks via large files
* ✅ **MIME type validation** - Quick check (not sufficient alone)
* ✅ **Handler-based file access** - Files accessed via application handler (`/api/files/:id`) instead of direct paths
* ✅ **Authentication & Authorization** - Only authorized users can upload/access files
* ✅ **Private storage** - Files stored in private buckets/containers with signed URLs
* ✅ **CSRF protection** - Handled by Better Auth and framework

### Additional Security Recommendations [#additional-security-recommendations]

For production environments, consider implementing:

1. **File signature validation (Magic Bytes)** - Validate magic bytes to ensure file type matches extension. This is critical as Content-Type headers can be spoofed. Example:

```typescript
// File signature validation (OWASP recommended)
// Validates magic bytes to ensure file type matches declared Content-Type
// See: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
const validateFileSignature = (fileBuffer: Buffer, expectedType: string): boolean => {
    const signatures: Record<string, number[][]> = {
        "image/jpeg": [[0xff, 0xd8, 0xff]],
        "image/png": [[0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]],
        "image/webp": [
            [0x52, 0x49, 0x46, 0x46],
            [0x57, 0x45, 0x42, 0x50],
        ], // RIFF...WEBP
        "application/pdf": [[0x25, 0x50, 0x44, 0x46]], // %PDF
    };

    const expectedSignatures = signatures[expectedType];
    if (!expectedSignatures) return false;

    // Check if file buffer starts with any of the expected signatures
    return expectedSignatures.some((sig) => sig.every((byte, index) => fileBuffer[index] === byte));
};

// Use in upload handler with file signature validation
// Note: This example reads the file after upload for validation. For better performance,
// consider validating the file signature from the upload stream before storage.
app.post("/api/files", requireAuth, multipart.handle, async (req, res) => {
    try {
        const file = req.body;

        // Validate file signature matches declared Content-Type (OWASP best practice)
        // Note: storage.get() loads entire file into memory. For large files, consider
        // using storage.getStream() and reading only the first few bytes for signature validation.
        const fileData = await storage.get({ id: file.id });
        if (!validateFileSignature(fileData.content, file.contentType)) {
            // Delete the file if signature doesn't match
            await storage.delete({ id: file.id });
            return res.status(400).json({ error: "Invalid file type" });
        }

        // File signature validated, continue with processing
        const user = req.user;
        await db.file.create({
            data: {
                storageId: file.id,
                userId: user.id,
                name: file.originalName,
                size: file.size,
                contentType: file.contentType,
            },
        });

        res.json({
            id: file.id,
            url: `/api/files/${file.id}`,
            size: file.size,
        });
    } catch (error) {
        console.error("Upload error:", error);
        if (req.body?.id) {
            await storage.delete({ id: req.body.id }).catch(() => {});
        }
        res.status(500).json({ error: "Failed to save file" });
    }
});
```

2. **Antivirus scanning** - Integrate with services like VirusTotal API or ClamAV
3. **Content Disarm & Reconstruct (CDR)** - For documents (PDF, DOCX), use CDR to remove potentially malicious content
4. **Sandboxing** - Process files in isolated environments before making them available
5. **Image rewriting** - For images, use image transformation to remove embedded malicious content (already supported via ImageTransformer)
6. **Separate storage host** - Store files on a different server/host for complete segregation

## Next Steps [#next-steps]

* Explore [Better Auth documentation](https://www.better-auth.com/docs) for authentication features
* Check out [Storage documentation](/docs/packages/storage) for advanced storage features
* Review [Framework integrations](/docs/packages/storage/framework/express) for framework-specific examples
* See [Image Transformers](/docs/packages/storage/transformers) for media processing
* Learn about [Error Handling](/docs/packages/storage/error-handling) for robust error management
* Read [OWASP File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) for comprehensive security guidance


# Batch Operations (/docs/packages/storage/batch-operations)



# Batch Operations [#batch-operations]

Perform multiple file operations in a single request for improved efficiency and reduced API calls. The package offers three layers, each fit for a different surface:

* **`Files` facade bulk overloads** — pass an array to `upload` / `download` / `head` / `exists` / `delete` / `move`, get back a structured `{ …, errors? }` result with bounded concurrency.
* **Cross-provider migration** — `transfer(source, destination, opts?)` streams every object from one `Files` instance to another.
* **Adapter-level batch primitives** — `deleteBatch` / `copyBatch` / `moveBatch` on the underlying `BaseStorage`.
* **HTTP handler batch endpoints** — `DELETE /files?ids=…` for browser clients.

## `Files` facade bulk overloads [#files-facade-bulk-overloads]

Each single-key method has a bulk-array overload. The bulk form runs the operations with bounded concurrency (default `8`), never throws on partial failure, and returns per-item failures in `errors`.

```typescript
import { Files } from "@visulima/storage";

const files = new Files({ adapter });

const { uploaded, errors } = await files.upload(
    [
        { key: "a.txt", body: "A" },
        { key: "b.txt", body: "B" },
        { key: "c.txt", body: "C" },
    ],
    { concurrency: 4 },
);

const { downloaded } = await files.download(["a.txt", "b.txt"]);
const { existing, missing } = await files.exists(["a.txt", "missing.txt"]);
const { deleted } = await files.delete(["a.txt", "b.txt"]);

const { moved } = await files.move(
    [
        { from: "tmp/a.txt", to: "final/a.txt" },
        { from: "tmp/b.txt", to: "final/b.txt" },
    ],
    { stopOnError: false },
);
```

`stopOnError: true` switches the call to short-circuit on the first failure (in-flight operations still complete). `delete` prefers the adapter's native bulk primitive (S3 `DeleteObjects`, Supabase `remove`, UploadThing `deleteFiles`) when one exists and `stopOnError` is not set; otherwise the keys are fanned out with bounded concurrency.

## Cross-provider migration: `transfer` [#cross-provider-migration-transfer]

`transfer(source, destination, opts?)` is built on top of the facade's public surface — no adapter implements anything new — and streams every object from one `Files` instance to another with bounded concurrency. Pull keys directly from `source.listAll()` so very large buckets transfer in constant memory.

```typescript
import { Files, transfer } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";
import { BunnyStorage } from "@visulima/storage/provider/bunny";

const from = new Files({ adapter: new S3Storage({ bucket: "old", region: "us-east-1" }) });
const to = new Files({ adapter: new BunnyStorage({ zone, accessKey, region: "de" }) });

const { transferred, skipped, errors } = await transfer(from, to, {
    prefix: "uploads/",
    concurrency: 8,
    onProgress: ({ done, key, status }) => log.info(done, key, status),
    transformKey: (key) => `archive/${key}`,
});
```

By default missing destination keys are uploaded and existing keys are skipped — pass `overwrite: true` to force re-upload. `stopOnError` switches to sequential execution and aborts on the first failure; `signal` aborts mid-walk.

## HTTP Batch Delete [#http-batch-delete]

Delete multiple files in a single request using the REST handler. For programmatic batch deletes from server code, prefer `files.delete(keys)` — the HTTP form is for browser clients hitting your upload server.

### Query Parameter Method [#query-parameter-method]

```typescript
// DELETE /files?ids=id1,id2,id3
const response = await fetch("/files?ids=id1,id2,id3", {
    method: "DELETE",
});

// Response includes:
// - X-Delete-Successful: Number of successful deletions
// - X-Delete-Failed: Number of failed deletions
// - X-Delete-Errors: JSON array of errors (if any)
```

### JSON Body Method [#json-body-method]

```typescript
// DELETE /files
// Body: { "ids": ["id1", "id2", "id3"] }
const response = await fetch("/files", {
    method: "DELETE",
    headers: {
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        ids: ["id1", "id2", "id3"],
    }),
});
```

### Array Body Method [#array-body-method]

```typescript
// DELETE /files
// Body: ["id1", "id2", "id3"]
const response = await fetch("/files", {
    method: "DELETE",
    headers: {
        "Content-Type": "application/json",
    },
    body: JSON.stringify(["id1", "id2", "id3"]),
});
```

## Response Format [#response-format]

Batch delete returns a multi-status response:

```typescript
// Status: 204 (No Content) - All deletions successful
// Status: 207 (Multi-Status) - Partial success

// Headers:
// X-Delete-Successful: 2
// X-Delete-Failed: 1
// X-Delete-Errors: [{"error":"File not found","id":"id3"}]

// Body: Array of successfully deleted files
[
    { id: "id1", status: "deleted", ... },
    { id: "id2", status: "deleted", ... },
]
```

## Error Handling [#error-handling]

```typescript
const response = await fetch("/files?ids=id1,id2,id3", {
    method: "DELETE",
});

const successful = parseInt(response.headers.get("X-Delete-Successful") || "0");
const failed = parseInt(response.headers.get("X-Delete-Failed") || "0");

if (failed > 0) {
    const errors = JSON.parse(response.headers.get("X-Delete-Errors") || "[]");
    console.error("Failed deletions:", errors);
}

if (successful > 0) {
    const deletedFiles = await response.json();
    console.log("Successfully deleted:", deletedFiles.length);
}
```

## Express Example [#express-example]

```typescript
import express from "express";
import { DiskStorage } from "@visulima/storage";

const app = express();
const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Batch delete endpoint
app.delete("/files", rest.handle, (req, res) => {
    // Response is automatically handled by the handler
    // Check headers for deletion status
    const successful = res.getHeader("X-Delete-Successful");
    const failed = res.getHeader("X-Delete-Failed");

    console.log(`Deleted: ${successful}, Failed: ${failed}`);
});
```

## Storage-Level Batch Operations [#storage-level-batch-operations]

All storage backends support batch operations at the storage level. These methods are available directly on storage instances:

### Batch Delete [#batch-delete]

```typescript
import { DiskStorage } from "@visulima/storage";

const storage = new DiskStorage({ directory: "./uploads" });

// Delete multiple files
const result = await storage.deleteBatch(["id1", "id2", "id3"]);

console.log(`Successful: ${result.successfulCount}, Failed: ${result.failedCount}`);
console.log("Successful files:", result.successful);
console.log("Failed operations:", result.failed);
```

### Batch Copy [#batch-copy]

```typescript
// Copy multiple files
const result = await storage.copyBatch([
    { source: "file1.jpg", destination: "backup/file1.jpg" },
    { source: "file2.jpg", destination: "backup/file2.jpg", options: { storageClass: "STANDARD_IA" } },
    { source: "file3.jpg", destination: "backup/file3.jpg" },
]);

console.log(`Copied: ${result.successfulCount}, Failed: ${result.failedCount}`);
```

### Batch Move [#batch-move]

```typescript
// Move multiple files
const result = await storage.moveBatch([
    { source: "temp/file1.jpg", destination: "permanent/file1.jpg" },
    { source: "temp/file2.jpg", destination: "permanent/file2.jpg" },
]);

console.log(`Moved: ${result.successfulCount}, Failed: ${result.failedCount}`);
```

## Batch Operation Response [#batch-operation-response]

All batch operations return a consistent response format:

```typescript
interface BatchOperationResponse<T extends File> {
    /** Successfully processed files */
    successful: T[];
    /** Failed operations with error details */
    failed: Array<{ error: string; id: string }>;
    /** Total number of successful operations */
    successfulCount: number;
    /** Total number of failed operations */
    failedCount: number;
}
```

## Error Handling [#error-handling-1]

```typescript
try {
    const result = await storage.deleteBatch(["id1", "id2", "id3"]);

    if (result.failedCount > 0) {
        console.warn(`${result.failedCount} operations failed:`, result.failed);
    }

    if (result.successfulCount > 0) {
        console.log(`Successfully processed ${result.successfulCount} files`);
    }
} catch (error) {
    console.error("Batch operation error:", error);
}
```

## Programmatic Batch Operations [#programmatic-batch-operations]

For operations not yet available as batch methods, you can implement them programmatically:

```typescript
// Batch update metadata
async function batchUpdateMetadata(files: Array<{ id: string; metadata: Record<string, any> }>) {
    const results = await Promise.allSettled(files.map(({ id, metadata }) => storage.update({ id }, metadata)));

    return results;
}
```

## Provider-Specific Batch Limits [#provider-specific-batch-limits]

Different storage providers have varying limits and considerations for batch operations:

### Azure Blob Storage [#azure-blob-storage]

Azure Blob Storage has a native batch API with specific limits:

* **Maximum subrequests per batch**: 256 operations
* **Maximum batch request size**: 4 MB
* **Supported operations**: Delete Blob and Set Blob Tier

> **Note**: Our implementation processes operations in parallel rather than using Azure's native batch API. For optimal performance with Azure, consider limiting batches to 256 operations or less to align with Azure's native batch limits.

### AWS S3 and S3-Compatible Services [#aws-s3-and-s3-compatible-services]

AWS S3 and S3-compatible services (DigitalOcean Spaces, Cloudflare R2, MinIO, Backblaze B2, Wasabi, Tigris):

* **No hard limit** on parallel operations in our implementation
* **Rate limiting**: Subject to provider-specific rate limits and quotas
  * AWS S3: Rate limits vary by operation type and are subject to account-level and bucket-level quotas
  * S3-compatible services: Each provider has their own rate limits (check provider documentation)
* **Recommendation**: Keep batches under 100-200 operations to avoid rate limit throttling
* **Note**: For very large batch operations, consider using AWS S3 Batch Operations (a managed service) for processing billions of objects

### Google Cloud Storage (GCS) [#google-cloud-storage-gcs]

* **No hard limit** on parallel operations in our implementation
* **Rate limiting**: Subject to GCS quotas and rate limits
  * Quotas vary by operation type (read, write, list)
  * Default quotas can be increased by requesting quota increases
  * Rate limits are enforced per bucket and per project
* **Recommendation**: Keep batches under 100 operations to avoid quota limits

### Vercel Blob [#vercel-blob]

* **No specific batch limits** documented
* **Rate limiting**: Subject to Vercel's API rate limits
* **Recommendation**: Keep batches under 100 operations to avoid timeouts and rate limits

### Netlify Blob [#netlify-blob]

* **No specific batch limits** documented
* **Rate limiting**: Subject to Netlify's API rate limits
* **Recommendation**: Keep batches under 100 operations to avoid timeouts and rate limits

### Local Disk Storage [#local-disk-storage]

* **No hard limits** - Limited only by system resources
* **Recommendation**: Can handle larger batches (500+ files), but consider memory usage for very large batches

## Best Practices [#best-practices]

1. **Limit batch size** - Don't exceed 100 files per batch to avoid timeouts (Azure: 256 max for optimal performance)
2. **Handle partial failures** - Always check `X-Delete-Failed` header or `failedCount` in response
3. **Use appropriate status codes** - 204 for full success, 207 for partial success
4. **Log errors** - Track failed operations for debugging
5. **Consider rate limits** - Batch operations may be rate-limited by storage providers
6. **Monitor provider quotas** - Be aware of your provider's rate limits and quotas
7. **Implement retry logic** - Use the built-in retry mechanism for transient failures


# Caching (/docs/packages/storage/caching)



# Caching [#caching]

The storage package supports caching to improve performance and reduce API calls. You provide your own cache implementation that follows the simple `Cache` interface.

## LRU Cache [#lru-cache]

Use the built-in LRU cache for simple in-memory caching:

```typescript
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";

const cache = new LRUCache({
    max: 1000, // Maximum number of items
    ttl: 3600000, // 1 hour in milliseconds
});

const storage = new DiskStorage({
    directory: "/uploads",
    cache,
});
```

## Custom Cache Implementation [#custom-cache-implementation]

Implement the `Cache` interface for any cache provider:

```typescript
import { DiskStorage, type Cache } from "@visulima/storage";
import { Redis } from "ioredis";

// Custom Redis cache implementation
class RedisCache implements Cache<string, any> {
    constructor(private redis: Redis) {}

    async get(key: string): Promise<any | undefined> {
        const value = await this.redis.get(key);
        return value ? JSON.parse(value) : undefined;
    }

    async set(key: string, value: any): Promise<boolean> {
        await this.redis.set(key, JSON.stringify(value));
        return true;
    }

    async delete(key: string): Promise<boolean> {
        await this.redis.del(key);
        return true;
    }

    async clear(): Promise<void> {
        await this.redis.flushall();
    }

    async has(key: string): Promise<boolean> {
        const exists = await this.redis.exists(key);
        return exists === 1;
    }
}

const redis = new Redis();
const cache = new RedisCache(redis);

const storage = new DiskStorage({
    directory: "/uploads",
    cache,
});
```

## BentoCache Integration [#bentocache-integration]

For advanced multi-tier caching, use BentoCache with the adapter:

```typescript
import { BentoCache, bentostore } from "bentocache";
import { memoryDriver } from "bentocache/drivers/memory";
import { redisDriver } from "bentocache/drivers/redis";
import { BentoCacheAdapter } from "@visulima/storage/utils/cache";

const bento = new BentoCache({
    default: "storage",
    stores: {
        storage: bentostore()
            .useL1Layer(memoryDriver({ maxSize: "10mb" }))
            .useL2Layer(
                redisDriver({
                    connection: { host: "127.0.0.1", port: 6379 },
                }),
            ),
    },
});

const cache = new BentoCacheAdapter({
    bento,
    namespace: "storage",
    defaultTtl: 3600000, // 1 hour
});

const storage = new DiskStorage({
    directory: "/uploads",
    cache,
});
```

## Transformer Caching [#transformer-caching]

Cache transformed media files to avoid reprocessing:

```typescript
import { MediaTransformer } from "@visulima/storage/transformer";
import ImageTransformer from "@visulima/storage/transformer/image";
import VideoTransformer from "@visulima/storage/transformer/video";
import { LRUCache } from "lru-cache";

const transformer = new MediaTransformer(storage, {
    cache: new LRUCache({ max: 100, ttl: 3600000 }),
    ImageTransformer: ImageTransformer,
    VideoTransformer: VideoTransformer,
});
```

## Cache Interface [#cache-interface]

Any cache implementation must implement this interface:

```typescript
interface Cache<K = string, V = any> {
    get(key: K): V | undefined | Promise<V | undefined>;
    set(key: K, value: V, options?: { ttl?: number }): boolean | Promise<boolean>;
    delete(key: K): boolean | Promise<boolean>;
    clear(): void | Promise<void>;
    has(key: K): boolean | Promise<boolean>;
}
```

## Cache Strategies [#cache-strategies]

### File Metadata Caching [#file-metadata-caching]

Storage backends automatically cache file metadata to reduce API calls:

```typescript
const storage = new S3Storage({
    bucket: "my-bucket",
    cache: new LRUCache({
        max: 1000,
        ttl: 3600000, // Cache metadata for 1 hour
    }),
});
```

### Transformed Media Caching [#transformed-media-caching]

Cache transformed images, videos, and audio to avoid reprocessing:

```typescript
const imageTransformer = new ImageTransformer(storage, {
    cache: new LRUCache({
        max: 500, // Cache up to 500 transformed images
        ttl: 86400000, // 24 hours
    }),
    cacheTtl: 86400, // Cache TTL in seconds
});
```

### Multi-Tier Caching [#multi-tier-caching]

Use a multi-tier cache for optimal performance:

```typescript
// L1: Fast in-memory cache (small, fast)
// L2: Redis cache (larger, slower)
// L3: Storage backend (largest, slowest)

const cache = new BentoCacheAdapter({
    bento: new BentoCache({
        stores: {
            storage: bentostore()
                .useL1Layer(memoryDriver({ maxSize: "10mb" }))
                .useL2Layer(redisDriver({ connection: { host: "localhost" } })),
        },
    }),
});
```

## Cache Invalidation [#cache-invalidation]

Manually invalidate cache entries when needed:

```typescript
// Delete specific cache entry
await cache.delete(fileId);

// Clear all cache entries
await cache.clear();

// Check if entry exists
const exists = await cache.has(fileId);
```

## Best Practices [#best-practices]

1. **Set appropriate TTLs** - Balance freshness with performance
2. **Monitor cache hit rates** - Optimize cache size based on usage
3. **Use multi-tier caching** - Combine fast and slow cache layers
4. **Invalidate on updates** - Clear cache when files are modified
5. **Consider cache size limits** - Prevent memory issues with large caches

For more information, see the [BentoCache documentation](https://bentocache.dev/docs/introduction).


# Chunked Uploads (/docs/packages/storage/chunked-uploads)



# Chunked Uploads [#chunked-uploads]

The REST handler supports client-side chunked uploads for large files. This allows you to upload files in smaller pieces, reducing memory usage and enabling resumable uploads.

## Overview [#overview]

Chunked uploads are ideal for:

* Large files that exceed memory limits
* Unreliable network connections
* Resumable uploads after interruptions
* Parallel chunk uploads for better performance

## Initializing a Chunked Upload [#initializing-a-chunked-upload]

```typescript
import { DiskStorage } from "@visulima/storage";
import { Rest } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Initialize chunked upload
const initResponse = await fetch("/files", {
    method: "POST",
    headers: {
        "X-Chunked-Upload": "true",
        "X-Total-Size": "10485760", // Total file size in bytes
        "Content-Length": "0",
        "Content-Type": "application/octet-stream",
    },
});

const { id } = await initResponse.json();
// id is the upload session ID
```

## Uploading Chunks [#uploading-chunks]

```typescript
// Upload chunk 1 (bytes 0-524288)
await fetch(`/files/${id}`, {
    method: "PATCH",
    headers: {
        "X-Chunk-Offset": "0",
        "Content-Length": "524288",
        "Content-Type": "application/octet-stream",
    },
    body: chunk1,
});

// Upload chunk 2 (bytes 524288-1048576) - can be out of order
await fetch(`/files/${id}`, {
    method: "PATCH",
    headers: {
        "X-Chunk-Offset": "524288",
        "Content-Length": "524288",
        "Content-Type": "application/octet-stream",
    },
    body: chunk2,
});
```

## Checking Upload Progress [#checking-upload-progress]

```typescript
// Check upload status
const statusResponse = await fetch(`/files/${id}`, {
    method: "HEAD",
});

const offset = statusResponse.headers.get("X-Upload-Offset");
const complete = statusResponse.headers.get("X-Upload-Complete");
const chunks = JSON.parse(statusResponse.headers.get("X-Received-Chunks") || "[]");

console.log(`Uploaded: ${offset} bytes, Complete: ${complete}`);
```

## Features [#features]

* **Out-of-Order Chunks**: Chunks can be uploaded in any order
* **Idempotency**: Duplicate chunks are safely ignored
* **Resumable**: Check progress and resume from last uploaded chunk
* **Progress Tracking**: Real-time upload progress via HEAD requests
* **Chunk Size Limits**: Maximum 100MB per chunk (configurable)

## Response Headers [#response-headers]

* `X-Upload-ID`: Upload session ID (returned on initialization)
* `X-Chunked-Upload`: Indicates chunked upload mode
* `X-Upload-Offset`: Current upload offset in bytes
* `X-Upload-Complete`: "true" when upload is complete, "false" otherwise
* `X-Received-Chunks`: JSON array of received chunks `[{ offset, length }]`

## Complete Example [#complete-example]

```typescript
import { DiskStorage } from "@visulima/storage";
import { Rest } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Client-side chunked upload implementation
async function uploadFileInChunks(file: File, chunkSize = 524288) {
    const totalSize = file.size;

    // Initialize chunked upload
    const initResponse = await fetch("/files", {
        method: "POST",
        headers: {
            "X-Chunked-Upload": "true",
            "X-Total-Size": String(totalSize),
            "Content-Length": "0",
            "Content-Type": file.type,
        },
    });

    const { id } = await initResponse.json();

    // Upload chunks
    const chunks = Math.ceil(totalSize / chunkSize);
    const uploadPromises = [];

    for (let i = 0; i < chunks; i++) {
        const start = i * chunkSize;
        const end = Math.min(start + chunkSize, totalSize);
        const chunk = file.slice(start, end);

        uploadPromises.push(
            fetch(`/files/${id}`, {
                method: "PATCH",
                headers: {
                    "X-Chunk-Offset": String(start),
                    "Content-Length": String(end - start),
                    "Content-Type": "application/octet-stream",
                },
                body: chunk,
            }),
        );
    }

    // Wait for all chunks to upload
    await Promise.all(uploadPromises);

    // Verify completion
    const statusResponse = await fetch(`/files/${id}`, {
        method: "HEAD",
    });

    const complete = statusResponse.headers.get("X-Upload-Complete");

    if (complete === "true") {
        console.log("Upload complete!");
        return id;
    } else {
        throw new Error("Upload incomplete");
    }
}
```

## Resuming Interrupted Uploads [#resuming-interrupted-uploads]

```typescript
async function resumeUpload(uploadId: string, file: File, chunkSize = 524288) {
    // Check current progress
    const statusResponse = await fetch(`/files/${uploadId}`, {
        method: "HEAD",
    });

    const offset = parseInt(statusResponse.headers.get("X-Upload-Offset") || "0");
    const receivedChunks = JSON.parse(statusResponse.headers.get("X-Received-Chunks") || "[]");

    // Upload remaining chunks
    const totalSize = file.size;
    const chunks = Math.ceil(totalSize / chunkSize);

    for (let i = 0; i < chunks; i++) {
        const start = i * chunkSize;
        const end = Math.min(start + chunkSize, totalSize);

        // Skip already uploaded chunks
        const chunkUploaded = receivedChunks.some((chunk: { offset: number; length: number }) => chunk.offset === start && chunk.length === end - start);

        if (chunkUploaded) {
            continue;
        }

        const chunk = file.slice(start, end);

        await fetch(`/files/${uploadId}`, {
            method: "PATCH",
            headers: {
                "X-Chunk-Offset": String(start),
                "Content-Length": String(end - start),
                "Content-Type": "application/octet-stream",
            },
            body: chunk,
        });
    }
}
```

## Best Practices [#best-practices]

1. **Choose appropriate chunk size** - Balance between network efficiency and memory usage (typically 512KB - 5MB)
2. **Upload chunks in parallel** - Use `Promise.all()` for better performance
3. **Handle errors gracefully** - Retry failed chunks individually
4. **Monitor progress** - Use HEAD requests to track upload status
5. **Verify completion** - Always check `X-Upload-Complete` header before considering upload done


# Custom Storage (/docs/packages/storage/custom-storage)



# Custom Storage Backends [#custom-storage-backends]

Create custom storage backends by extending `AbstractBaseStorage` (exported as `BaseStorage`) or implementing custom `MetaStorage` for advanced use cases.

## Overview [#overview]

Visulima Storage provides two base classes for customization:

* **`AbstractBaseStorage`** - Base class for creating custom storage backends
* **`MetaStorage`** - Base class for custom metadata storage implementations

## Creating a Custom Storage Backend [#creating-a-custom-storage-backend]

### Extending AbstractBaseStorage [#extending-abstractbasestorage]

Create a custom storage backend by extending `AbstractBaseStorage`:

```typescript
import { AbstractBaseStorage } from "@visulima/storage";
import type { File, FileInit, FilePart, FileQuery, FileReturn } from "@visulima/storage";

interface MyStorageOptions {
    apiKey: string;
    endpoint: string;
}

class MyCustomStorage extends AbstractBaseStorage<File, FileReturn> {
    public static override readonly name: string = "my-custom-storage";

    private readonly apiKey: string;
    private readonly endpoint: string;

    public constructor(config: MyStorageOptions) {
        super({
            maxUploadSize: "100MB",
            allowMIME: ["*/*"],
            // ... other BaseStorageOptions
        });

        this.apiKey = config.apiKey;
        this.endpoint = config.endpoint;
    }

    // Implement required abstract methods
    public override async create(config: FileInit): Promise<File> {
        // Create file in your storage system
        const file = await this.createFile(config);

        // Save metadata
        await this.meta.save(file.id, file);

        // Call onCreate hook
        await this.onCreate(file);

        return file;
    }

    public override async write(part: FilePart | FileQuery): Promise<File> {
        // Write file data to your storage system
        const file = await this.writeFile(part);

        // Update metadata
        await this.meta.save(file.id, file);

        // Call onUpdate hook
        await this.onUpdate(file);

        return file;
    }

    public override async get(query: FileQuery): Promise<FileReturn> {
        // Retrieve file from your storage system
        const file = await this.getFile(query.id);

        return {
            ...file,
            stream: await this.getFileStream(query.id),
        };
    }

    public override async delete(query: FileQuery): Promise<File> {
        // Delete file from your storage system
        await this.deleteFile(query.id);

        // Delete metadata
        await this.meta.delete(query.id);

        // Call onDelete hook
        const file = await this.meta.get(query.id);
        await this.onDelete(file);

        return file;
    }

    // Implement other required methods...
    // - list()
    // - update()
    // - copy()
    // - move()
    // - exists()
    // - normalizeError()
}
```

### Required Methods [#required-methods]

When extending `AbstractBaseStorage`, you must implement:

#### Core Operations [#core-operations]

* **`create(config: FileInit): Promise<File>`** - Create a new file upload
* **`write(part: FilePart | FileQuery): Promise<File>`** - Write file data
* **`get(query: FileQuery): Promise<FileReturn>`** - Retrieve file and metadata
* **`delete(query: FileQuery): Promise<File>`** - Delete a file
* **`list(limit?: number): Promise<File[]>`** - List files
* **`update(query: FileQuery, metadata: Partial<File>): Promise<File>`** - Update file metadata

#### Optional Operations [#optional-operations]

* **`copy(source: string, destination: string, options?: { storageClass?: string }): Promise<File>`** - Copy a file
* **`move(source: string, destination: string): Promise<File>`** - Move a file
* **`exists(query: FileQuery): Promise<boolean>`** - Check if file exists
* **`getStream(query: FileQuery): Promise<{ stream: Readable; headers?: Record<string, string>; size?: number }>`** - Get file as stream
* **`getUrl(query: FileQuery, expiresIn?: number): Promise<string>`** - Get public URL
* **`getUploadUrl(query: FileQuery, expiresIn?: number): Promise<string>`** - Get presigned upload URL

#### Error Handling [#error-handling]

* **`normalizeError(error: unknown): HttpError`** - Normalize errors to HttpError format

### Using Instrumentation [#using-instrumentation]

The base class provides `instrumentOperation()` for automatic metrics collection:

```typescript
public override async create(config: FileInit): Promise<File> {
    return this.instrumentOperation(
        "create",
        async () => {
            // Your implementation
            const file = await this.createFile(config);
            await this.meta.save(file.id, file);
            await this.onCreate(file);
            return file;
        },
        {
            custom_attribute: "value",
        },
    );
}
```

### Batch Operations [#batch-operations]

Batch operations are automatically implemented by the base class, but you can override them:

```typescript
public override async deleteBatch(ids: string[]): Promise<BatchOperationResponse<File>> {
    // Custom batch delete implementation
    const results = await Promise.allSettled(
        ids.map((id) => this.delete({ id })),
    );

    const successful: File[] = [];
    const failed: Array<{ error: string; id: string }> = [];

    results.forEach((result, index) => {
        if (result.status === "fulfilled") {
            successful.push(result.value);
        } else {
            failed.push({
                id: ids[index],
                error: result.reason.message,
            });
        }
    });

    return {
        successful,
        failed,
        successfulCount: successful.length,
        failedCount: failed.length,
    };
}
```

## Creating Custom MetaStorage [#creating-custom-metastorage]

Create custom metadata storage by extending `MetaStorage`:

```typescript
import { MetaStorage } from "@visulima/storage";
import type { File } from "@visulima/storage";

interface DatabaseMetaStorageOptions {
    connectionString: string;
    tableName?: string;
}

class DatabaseMetaStorage<T extends File = File> extends MetaStorage<T> {
    private readonly connectionString: string;
    private readonly tableName: string;

    public constructor(config: DatabaseMetaStorageOptions) {
        super({
            prefix: config.tableName ? `${config.tableName}_` : "",
            suffix: "",
        });

        this.connectionString = config.connectionString;
        this.tableName = config.tableName || "file_metadata";
    }

    public override async save(id: string, file: T): Promise<T> {
        // Save metadata to database
        await this.db.query(
            `INSERT INTO ${this.tableName} (id, metadata) VALUES ($1, $2) 
             ON CONFLICT (id) DO UPDATE SET metadata = $2`,
            [id, JSON.stringify(file)],
        );

        return file;
    }

    public override async get(id: string): Promise<T> {
        // Retrieve metadata from database
        const result = await this.db.query(`SELECT metadata FROM ${this.tableName} WHERE id = $1`, [id]);

        if (result.rows.length === 0) {
            throw new Error("File not found");
        }

        return JSON.parse(result.rows[0].metadata) as T;
    }

    public override async delete(id: string): Promise<void> {
        // Delete metadata from database
        await this.db.query(`DELETE FROM ${this.tableName} WHERE id = $1`, [id]);
    }

    public override async touch(id: string, file: T): Promise<T> {
        // Update last accessed timestamp
        await this.db.query(`UPDATE ${this.tableName} SET last_accessed = NOW() WHERE id = $1`, [id]);

        return file;
    }
}
```

### MetaStorage Methods [#metastorage-methods]

Implement these methods in your custom `MetaStorage`:

* **`save(id: string, file: T): Promise<T>`** - Save file metadata
* **`get(id: string): Promise<T>`** - Retrieve file metadata
* **`delete(id: string): Promise<void>`** - Delete file metadata
* **`touch(id: string, file: T): Promise<T>`** - Update last accessed timestamp

### Using Custom MetaStorage [#using-custom-metastorage]

Use your custom `MetaStorage` with any storage backend:

```typescript
import { DiskStorage } from "@visulima/storage";
import { DatabaseMetaStorage } from "./database-meta-storage";

const metaStorage = new DatabaseMetaStorage({
    connectionString: process.env.DATABASE_URL,
    tableName: "file_metadata",
});

const storage = new DiskStorage({
    directory: "./uploads",
    metaStorage, // Use custom metadata storage
});
```

## Complete Example: Redis Storage Backend [#complete-example-redis-storage-backend]

Here's a complete example of a Redis-based storage backend:

```typescript
import { Readable } from "node:stream";
import { AbstractBaseStorage } from "@visulima/storage";
import { ERRORS, throwErrorCode } from "@visulima/storage";
import type { File, FileInit, FilePart, FileQuery, FileReturn } from "@visulima/storage";
import Redis from "ioredis";

interface RedisStorageOptions {
    redis: Redis;
    prefix?: string;
}

class RedisStorage extends AbstractBaseStorage<File, FileReturn> {
    public static override readonly name: string = "redis";

    private readonly redis: Redis;
    private readonly prefix: string;

    public constructor(config: RedisStorageOptions) {
        super({
            maxUploadSize: "100MB",
            allowMIME: ["*/*"],
        });

        this.redis = config.redis;
        this.prefix = config.prefix || "visulima:";
    }

    private getKey(id: string): string {
        return `${this.prefix}file:${id}`;
    }

    private getMetaKey(id: string): string {
        return `${this.prefix}meta:${id}`;
    }

    public override async create(config: FileInit): Promise<File> {
        const file: File = {
            id: config.id || this.generateId(),
            name: config.name || "",
            originalName: config.originalName || "",
            size: config.size || 0,
            contentType: config.contentType || "application/octet-stream",
            status: "created",
            createdAt: new Date(),
            updatedAt: new Date(),
            metadata: config.metadata || {},
        };

        // Save metadata to Redis
        await this.redis.set(this.getMetaKey(file.id), JSON.stringify(file));

        // Call onCreate hook
        await this.onCreate(file);

        return file;
    }

    public override async write(part: FilePart | FileQuery): Promise<File> {
        const id = "id" in part ? part.id : part.id;
        const file = await this.get({ id });

        if (!("body" in part) || !part.body) {
            throw throwErrorCode(ERRORS.BAD_REQUEST, "Body is required");
        }

        // Convert stream to buffer
        const chunks: Buffer[] = [];
        for await (const chunk of part.body) {
            chunks.push(chunk);
        }
        const buffer = Buffer.concat(chunks);

        // Store file data in Redis
        await this.redis.set(this.getKey(id), buffer);

        // Update file metadata
        const updatedFile: File = {
            ...file,
            size: file.size + buffer.length,
            status: "completed",
            updatedAt: new Date(),
        };

        await this.redis.set(this.getMetaKey(id), JSON.stringify(updatedFile));

        // Call onUpdate hook
        await this.onUpdate(updatedFile);

        return updatedFile;
    }

    public override async get(query: FileQuery): Promise<FileReturn> {
        const metaData = await this.redis.get(this.getMetaKey(query.id));

        if (!metaData) {
            throw throwErrorCode(ERRORS.FILE_NOT_FOUND);
        }

        const file = JSON.parse(metaData) as File;
        const fileData = await this.redis.getBuffer(this.getKey(query.id));

        if (!fileData) {
            throw throwErrorCode(ERRORS.FILE_NOT_FOUND);
        }

        // Create readable stream from buffer
        const stream = Readable.from(fileData);

        return {
            ...file,
            stream,
        };
    }

    public override async delete(query: FileQuery): Promise<File> {
        const metaData = await this.redis.get(this.getMetaKey(query.id));

        if (!metaData) {
            throw throwErrorCode(ERRORS.FILE_NOT_FOUND);
        }

        const file = JSON.parse(metaData) as File;

        // Delete file data and metadata
        await Promise.all([this.redis.del(this.getKey(query.id)), this.redis.del(this.getMetaKey(query.id))]);

        // Call onDelete hook
        await this.onDelete(file);

        return file;
    }

    public override async list(limit = 100): Promise<File[]> {
        const keys = await this.redis.keys(this.getMetaKey("*"));
        const files: File[] = [];

        for (const key of keys.slice(0, limit)) {
            const metaData = await this.redis.get(key);

            if (metaData) {
                files.push(JSON.parse(metaData) as File);
            }
        }

        return files;
    }

    public override async update(query: FileQuery, metadata: Partial<File>): Promise<File> {
        const file = await this.get({ id: query.id });
        const updatedFile: File = {
            ...file,
            ...metadata,
            updatedAt: new Date(),
        };

        await this.redis.set(this.getMetaKey(query.id), JSON.stringify(updatedFile));
        await this.onUpdate(updatedFile);

        return updatedFile;
    }

    public override normalizeError(error: unknown): HttpError {
        if (error instanceof Error && error.message.includes("not found")) {
            return {
                code: ERRORS.FILE_NOT_FOUND,
                message: "File not found",
                statusCode: 404,
            };
        }

        return {
            code: ERRORS.STORAGE_ERROR,
            message: error instanceof Error ? error.message : "Storage error",
            statusCode: 500,
        };
    }

    private generateId(): string {
        return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
    }
}

// Usage
const redis = new Redis(process.env.REDIS_URL);
const storage = new RedisStorage({
    redis,
    prefix: "myapp:",
});
```

## Best Practices [#best-practices]

1. **Implement Error Normalization** - Always implement `normalizeError()` to provide consistent error responses
2. **Use Instrumentation** - Wrap operations with `instrumentOperation()` for automatic metrics
3. **Handle Metadata** - Properly save and retrieve metadata using the `meta` property
4. **Call Hooks** - Call lifecycle hooks (`onCreate`, `onUpdate`, `onDelete`, `onComplete`) at appropriate times
5. **Handle Streams** - Properly handle Readable streams for file data
6. **Validate Inputs** - Validate file sizes, MIME types, and other constraints
7. **Handle Concurrency** - Use file locking for concurrent access (base class provides `locker`)
8. **Support Batch Operations** - Implement batch operations for better performance
9. **Test Thoroughly** - Test all operations including error cases
10. **Document Your Storage** - Document any limitations or special behavior

## Integration with Handlers [#integration-with-handlers]

Your custom storage backend works seamlessly with all handlers:

```typescript
import { Multipart } from "@visulima/storage/handler/http/fetch";
import { RedisStorage } from "./redis-storage";

const storage = new RedisStorage({
    redis: new Redis(process.env.REDIS_URL),
});

const multipart = new Multipart({ storage });

// Use with any framework
app.post("/upload", async (request) => {
    return await multipart.fetch(request);
});
```

## Next Steps [#next-steps]

* Review existing storage implementations for reference
* Test your custom storage with all handler types
* Add metrics and logging for observability
* Consider implementing optional operations for better compatibility


# Error Handling (/docs/packages/storage/error-handling)



# Error Handling [#error-handling]

Visulima storage provides consistent error handling across all storage backends with standardized error codes and messages.

## Error Types [#error-types]

### Upload Errors [#upload-errors]

```typescript
import { ERRORS, isUploadError, throwErrorCode } from "@visulima/storage";

try {
    await storage.get({ id: "nonexistent" });
} catch (error) {
    if (isUploadError(error)) {
        console.log("Error code:", error.UploadErrorCode);
        console.log("Status:", error.statusCode);
        console.log("Message:", error.message);
    }
}
```

### Standard Error Codes [#standard-error-codes]

```typescript
enum ERRORS {
    BAD_REQUEST = "BadRequest",
    CHECKSUM_MISMATCH = "ChecksumMismatch",
    FILE_CONFLICT = "FileConflict",
    FILE_ERROR = "FileError",
    FILE_LOCKED = "FileLocked",
    FILE_NOT_ALLOWED = "FileNotAllowed",
    FILE_NOT_FOUND = "FileNotFound",
    FORBIDDEN = "Forbidden",
    GONE = "Gone",
    INVALID_FILE_NAME = "InvalidFileName",
    INVALID_FILE_SIZE = "InvalidFileSize",
    INVALID_RANGE = "InvalidRange",
    INVALID_TYPE = "Invalidtype",
    METHOD_NOT_ALLOWED = "MethodNotAllowed",
    REQUEST_ABORTED = "RequestAborted",
    REQUEST_ENTITY_TOO_LARGE = "RequestEntityTooLarge",
    STORAGE_BUSY = "StorageBusy",
    STORAGE_ERROR = "StorageError",
    TOO_MANY_REQUESTS = "TooManyRequests",
    UNKNOWN_ERROR = "UnknownError",
    UNPROCESSABLE_ENTITY = "UnprocessableEntity",
    UNSUPPORTED_CHECKSUM_ALGORITHM = "UnsupportedChecksumAlgorithm",
    UNSUPPORTED_MEDIA_TYPE = "UnsupportedMediaType",
}
```

## Error Response Format [#error-response-format]

All errors follow a consistent format:

```typescript
interface HttpError {
    code: string; // Error code (e.g., "FileNotFound")
    message: string; // Human-readable message
    statusCode: number; // HTTP status code
    name?: string; // Error name
    body?: any; // Additional error details
}
```

## Handling Common Errors [#handling-common-errors]

### File Not Found [#file-not-found]

```typescript
try {
    await storage.get({ id: "nonexistent" });
} catch (error) {
    if (isUploadError(error) && error.UploadErrorCode === ERRORS.FILE_NOT_FOUND) {
        return res.status(404).json({ error: "File not found" });
    }
    throw error;
}
```

### File Too Large [#file-too-large]

```typescript
try {
    await storage.create({
        contentType: "image/jpeg",
        size: 100 * 1024 * 1024, // 100MB
    });
} catch (error) {
    if (isUploadError(error) && error.UploadErrorCode === ERRORS.REQUEST_ENTITY_TOO_LARGE) {
        return res.status(413).json({ error: "File too large" });
    }
    throw error;
}
```

### Unsupported Media Type [#unsupported-media-type]

```typescript
try {
    await storage.create({
        contentType: "application/x-executable",
        size: 1024,
    });
} catch (error) {
    if (isUploadError(error) && error.UploadErrorCode === ERRORS.UNSUPPORTED_MEDIA_TYPE) {
        return res.status(415).json({ error: "Unsupported file type" });
    }
    throw error;
}
```

### Checksum Mismatch [#checksum-mismatch]

```typescript
try {
    await storage.write({
        id: "file-id",
        body: stream,
        checksum: "invalid-checksum",
        checksumAlgorithm: "md5",
    });
} catch (error) {
    if (isUploadError(error) && error.UploadErrorCode === ERRORS.CHECKSUM_MISMATCH) {
        return res.status(460).json({ error: "Checksum mismatch" });
    }
    throw error;
}
```

## Custom Error Handling [#custom-error-handling]

### Custom Error Responses [#custom-error-responses]

```typescript
const storage = new DiskStorage({
    directory: "./uploads",
    onError: (error: HttpError) => {
        // Customize error response
        return {
            body: {
                error: {
                    code: error.code,
                    message: error.message,
                    timestamp: new Date().toISOString(),
                },
            },
            headers: {
                "X-Error-Code": error.code,
            },
            statusCode: error.statusCode,
        };
    },
});
```

### Error Logging [#error-logging]

```typescript
const storage = new DiskStorage({
    directory: "./uploads",
    logger: {
        error: (message, ...args) => {
            console.error(`[Storage Error] ${message}`, ...args);
            // Send to error tracking service
            errorTracker.captureException(new Error(message));
        },
        debug: (message, ...args) => {
            console.debug(`[Storage Debug] ${message}`, ...args);
        },
        info: (message, ...args) => {
            console.info(`[Storage Info] ${message}`, ...args);
        },
    },
});
```

## Storage-Specific Errors [#storage-specific-errors]

### AWS S3 Errors [#aws-s3-errors]

```typescript
try {
    await s3Storage.get({ id: "file-id" });
} catch (error) {
    // AWS SDK errors are normalized
    if (error.$metadata) {
        console.log("AWS Status:", error.$metadata.httpStatusCode);
        console.log("AWS Code:", error.Code);
    }
}
```

### Azure Storage Errors [#azure-storage-errors]

```typescript
try {
    await azureStorage.get({ id: "file-id" });
} catch (error) {
    // Azure errors include statusCode
    if (error.statusCode) {
        console.log("Azure Status:", error.statusCode);
    }
}
```

## Error Middleware [#error-middleware]

### Express Error Middleware [#express-error-middleware]

```typescript
app.use((error: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
    if (isUploadError(error)) {
        const statusCode = error.statusCode || 500;
        return res.status(statusCode).json({
            error: {
                code: error.UploadErrorCode,
                message: error.message,
            },
        });
    }

    // Handle other errors
    res.status(500).json({ error: "Internal server error" });
});
```

### Hono Error Handler [#hono-error-handler]

```typescript
app.onError((error, c) => {
    if (isUploadError(error)) {
        return c.json(
            {
                error: {
                    code: error.UploadErrorCode,
                    message: error.message,
                },
            },
            error.statusCode || 500,
        );
    }

    return c.json({ error: "Internal server error" }, 500);
});
```

## Best Practices [#best-practices]

1. **Always check error types** - Use `isUploadError()` to identify upload errors
2. **Handle specific error codes** - Provide user-friendly messages for common errors
3. **Log errors appropriately** - Include context for debugging
4. **Return appropriate status codes** - Use standard HTTP status codes
5. **Don't expose internal details** - Sanitize error messages for production


# Files Facade (/docs/packages/storage/files-facade)



# `Files` facade [#files-facade]

Files-SDK–style unified facade over any `BaseStorage` adapter. One small surface (`upload`, `download`, `head`, `exists`, `delete`, `copy`, `move`, `list`, `listAll`, `url`, `signedUploadUrl`) plus a `.raw` escape hatch — works against every adapter the package ships, including the in-memory adapter for tests.

```ts
import { Files } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

const files = new Files({
    adapter: new S3Storage({ bucket: "uploads", region: "us-east-1" }),
});
```

The user-supplied `key` is both the storage path and the metadata id — subsequent operations look up the object by the same key used to upload it.

## When to use it [#when-to-use-it]

* One-shot puts and gets (uploading a `Blob`, fetching a `Buffer`).
* Provider-portable code — swap `S3Storage` for `BunnyStorage` without changing call sites.
* Bulk operations and cross-provider migrations (`upload([...])`, `delete([...])`, `transfer(from, to)`).
* AI-agent and LLM tool integrations (the `@visulima/storage/ai/*` subpaths build on top of `Files`).
* Quick scripts, serverless functions, and small services that don't need TUS / multipart / lifecycle hooks.

For client-driven uploads (browser forms, large resumable files, chunked transfers), skip the facade and use the adapter directly with an [HTTP handler](/docs/packages/storage/tus-handler).

## Method surface [#method-surface]

| Method            | Single-key signature                                 | Bulk-array signature                            | Notes                                                             |
| ----------------- | ---------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
| `upload`          | `(key, body, opts?) → Promise<FileObject>`           | `(items: BulkUploadItem[], opts?) → Promise<…>` | Accepts any [supported body type](#body-types).                   |
| `download`        | `(key, opts?) → Promise<DownloadResult>`             | `(keys: string[], opts?) → Promise<…>`          | Optional `range` for byte slices.                                 |
| `head`            | `(key, opts?) → Promise<FileObject>`                 | `(keys: string[], opts?) → Promise<…>`          | Metadata only.                                                    |
| `exists`          | `(key, opts?) → Promise<boolean>`                    | `(keys: string[], opts?) → Promise<…>`          | Never throws for a missing object.                                |
| `delete`          | `(key, opts?) → Promise<void>`                       | `(keys: string[], opts?) → Promise<…>`          | Uses the adapter's native bulk primitive when present.            |
| `copy`            | `(source, destination, opts?) → Promise<FileObject>` | —                                               | Server-side where supported; download + re-upload otherwise.      |
| `move`            | `(from, to, opts?) → Promise<FileObject>`            | `(items: BulkMoveItem[], opts?) → Promise<…>`   | Uses native rename where one exists, otherwise `copy` + `delete`. |
| `list`            | `(opts?) → Promise<FileObject[]>`                    | —                                               | Optional `prefix` filter and `limit`. Single page.                |
| `listAll`         | `(opts?) → AsyncGenerator<FileObject>`               | —                                               | Pages internally; yields one at a time.                           |
| `url`             | `(key, opts?) → Promise<string>`                     | —                                               | Signed-read URL when the provider supports it.                    |
| `signedUploadUrl` | `(key, opts?) → Promise<string>`                     | —                                               | Presigned-PUT URL for direct-from-browser uploads.                |
| `raw` (getter)    | `→ unknown`                                          | —                                               | The adapter's native client (`S3Client`, `BlobServiceClient`, …). |

## Per-call `OperationOptions` [#per-call-operationoptions]

Every method accepts `signal`, `timeout`, and `retries` per call. Defaults set on the constructor are merged in, per-call wins; the signal is combined with any constructor signal via `AbortSignal.any` so either one aborts the operation.

```ts
const files = new Files({
    adapter,
    defaults: { timeout: 30_000, retries: { maxRetries: 5 } },
});

const ac = new AbortController();
await files.download("k", { signal: ac.signal, timeout: 5_000 });
```

See the [Retry mechanism](/docs/packages/storage/retry-mechanism) page for the full `RetryConfig` shape and how `onRetry` integrates with the facade hooks.

## Constructor `prefix` [#constructor-prefix]

Namespace every key under a prefix. Reads, writes, copies, listings, URLs, and signed uploads all resolve keys as `${prefix}/${key}`; returned keys (including from `list()` / `listAll()`) have the prefix stripped back off. Leading/trailing slashes are normalized so `"/users/"` and `"users"` behave identically.

```ts
const files = new Files({ adapter, prefix: "tenant-x" });

await files.upload("docs/report.pdf", buffer); // → tenant-x/docs/report.pdf
const objects = await files.list({ prefix: "docs/" }); // result keys are un-prefixed
```

`list()` and `listAll()` scope results on a path boundary, so `prefix: "users"` never matches the sibling `users-archive/`.

## Lifecycle hooks [#lifecycle-hooks]

Pass `hooks: { onAction, onError, onRetry }` to observe activity. Hooks are fire-and-forget — called, not awaited — and exceptions are swallowed so a hook can never fail the operation it observes.

```ts
const files = new Files({
    adapter,
    hooks: {
        onAction: (event) => log.info(event.type, event.key, event.durationMs),
        onError: (event) => log.error(event.type, event.key, event.error.message),
        onRetry: (event) => log.warn(event.type, event.key, "retry attempt", event.attempt),
    },
});
```

Every event carries `type` (one of `upload`, `download`, `head`, `exists`, `delete`, `copy`, `move`, `list`, `listAll`, `url`, `signedUploadUrl`, `transfer`) plus the relevant `key` / `keys` / `from` / `to` fields. `onAction` / `onError` include `durationMs`; `onRetry` adds `attempt` (1-based) and `error`. The `listAll` terminal event fires even when the consumer breaks out of the `for await` early.

## Body types [#body-types]

`Files.upload(key, body, opts?)` accepts:

| Type                                             | Size hint                                      | Notes                                          |
| ------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------- |
| `string`                                         | derived                                        | UTF-8 encoded.                                 |
| `Buffer`                                         | derived                                        |                                                |
| `Uint8Array` / `ArrayBuffer` / `ArrayBufferView` | derived                                        |                                                |
| `Blob`                                           | derived                                        | Web `Blob` (Node 18+ and all modern runtimes). |
| `ReadableStream<Uint8Array>`                     | **required via `opts.size`** for some adapters | Web stream, not Node `Readable`.               |
| `NodeJS.ReadableStream`                          | **required via `opts.size`** for some adapters | Node `Readable`.                               |

Stream inputs don't carry a length; pass `opts.size` when the underlying adapter or upload protocol needs to know it up front (multipart, content-length headers, presigned-PUT bodies).

## Return shape: `FileObject` [#return-shape-fileobject]

Every method that returns object data returns the same provider-agnostic shape:

```ts
interface FileObject {
    contentType: string;
    etag?: string;
    key: string;
    lastModified?: Date | number | string;
    metadata?: Record<string, unknown>;
    size?: number;
}

interface DownloadResult extends FileObject {
    body: Buffer;
}
```

No S3-style `ETag` capitalization quirks, no Azure-specific fields leaking through — adapter-side mapping is the facade's job.

## Typed `.raw` escape hatch [#typed-raw-escape-hatch]

`Files` is generic over the adapter type, so `files.raw` is typed to the adapter's native client when you pin it:

```ts
import { Files, S3Storage } from "@visulima/storage";
import type { S3Client } from "@aws-sdk/client-s3";

const files = new Files({ adapter: new S3Storage({ bucket: "u", region: "us-east-1" }) });

// `files.raw` is `S3Client` (not `unknown`).
const s3: S3Client = files.raw;
await s3.send(/* …adapter-specific call… */);
```

Adapters without a native client (e.g. `DiskStorage`) return `undefined` from `raw`. The in-memory adapter exposes its backing `Map` via `raw`.

## Examples [#examples]

### Save a `Blob` from a form [#save-a-blob-from-a-form]

```ts
const file = formData.get("avatar") as Blob;

await files.upload(`avatars/${userId}.png`, file, {
    contentType: file.type,
    metadata: { userId },
});
```

### Read into a `Buffer` [#read-into-a-buffer]

```ts
const { body, contentType, size } = await files.download(`avatars/${userId}.png`);

response.setHeader("Content-Type", contentType);
response.setHeader("Content-Length", String(size));
response.end(body);
```

### Download a byte range [#download-a-byte-range]

```ts
// Fetch only the first 1 KiB to inspect a magic-number header without pulling the whole object.
const { body } = await files.download("video.mp4", { range: { start: 0, end: 1023 } });

// Resume from a saved offset — omit `end` to read to EOF.
const { body: tail } = await files.download("video.mp4", { range: { start: 8 * 1024 * 1024 } });
```

`range` is the HTTP `bytes=start-end` semantics: both bounds 0-based, `end` inclusive. The facade checks `adapter.supportsRange` and throws synchronously for adapters that don't opt in, so the bandwidth saving is never silently lost client-side.

### Upload with progress [#upload-with-progress]

```ts
import { createReadStream } from "node:fs";
import { stat } from "node:fs/promises";

const { size } = await stat(path);

await files.upload(key, createReadStream(path), {
    contentType: "video/mp4",
    size,
    onProgress: ({ loaded, total }) => {
        const percent = total ? Math.round((loaded / total) * 100) : "?";

        log.info(`uploaded ${loaded} / ${total ?? "?"} bytes (${percent}%)`);
    },
});
```

For buffered bodies a coarse start/done pair is emitted. For streaming bodies each chunk reports `loaded` cumulatively. A throwing callback can never fail the upload — exceptions are swallowed. Adapters that report progress natively (`reportsUploadProgress = true`) supersede the facade's PassThrough wrap with byte-accurate events.

### Multipart upload for large objects [#multipart-upload-for-large-objects]

```ts
await files.upload("backups/db-2026-05.tar.gz", stream, {
    size,
    multipart: { partSize: 16 * 1024 * 1024, concurrency: 4 },
});
```

`multipart: true` uses the adapter's defaults; pass an object to tune the per-part size and the number of parts uploaded in parallel. Adapters that don't have a multipart primitive ignore the option.

### Mint a signed URL for a private object [#mint-a-signed-url-for-a-private-object]

```ts
const url = await files.url(`docs/${docId}.pdf`, {
    expiresIn: 900,
    responseContentDisposition: `attachment; filename="${docId}.pdf"`,
});
```

`responseContentDisposition` and `responseContentType` are honored where the provider supports them; otherwise the call throws `UploadError(METHOD_NOT_ALLOWED)` so the caller knows the feature is unsupported.

### Presigned upload for a browser client [#presigned-upload-for-a-browser-client]

```ts
const uploadUrl = await files.signedUploadUrl(`raw/${id}.bin`, {
    contentType: "application/octet-stream",
    contentLength: bytes,
    expiresIn: 600,
});

return Response.json({ uploadUrl });
```

Not every adapter supports presigned PUT. Adapters without a primitive (UploadThing, Bunny) throw `UploadError(METHOD_NOT_ALLOWED)` with a message pointing to the supported alternative.

### List a single page [#list-a-single-page]

```ts
const userFiles = await files.list({ prefix: `users/${userId}/`, limit: 100 });
```

`list()` is intentionally simple: one page from the adapter, then filter by `prefix` in memory. Use `listAll` for full-bucket walks.

### Walk every object (paginated async iterable) [#walk-every-object-paginated-async-iterable]

```ts
for await (const file of files.listAll({ prefix: "avatars/" })) {
    if (file.size && file.size > 5 * 1024 * 1024) {
        log.warn("oversized avatar", file.key);
    }
}
```

`listAll` pages internally so callers don't have to thread a cursor. Returned keys have any constructor prefix stripped off; out-of-namespace keys are filtered out, mirroring `list()`. Breaking out of the `for await` early still emits the terminal `onAction` / `onError` hook event.

### Copy and rename [#copy-and-rename]

```ts
await files.copy(`tmp/${id}`, `final/${id}`);
await files.move(`tmp/${id}`, `final/${id}`); // copy + delete, or native rename
```

For providers without server-side copy (Bunny, UploadThing), `copy` is a download + re-upload roundtrip and `move = copy + delete` is non-atomic — a failed delete leaves the source behind. Moving a key onto itself (`move("k", "k")`) is a no-op and returns the existing metadata without emitting a second hook event.

### Bulk operations [#bulk-operations]

Every single-key method has a bulk-array overload that runs the keys with bounded concurrency and returns a structured result instead of throwing on partial failure.

```ts
const { uploaded, errors } = await files.upload([
    { key: "a.txt", body: "A" },
    { key: "b.txt", body: "B" },
    { key: "c.txt", body: "C" },
]);

const { downloaded, errors: dErr } = await files.download(["a.txt", "b.txt", "c.txt"], {
    concurrency: 4,
});

const { deleted } = await files.delete(["a.txt", "b.txt"]);

const { moved } = await files.move([
    { from: "tmp/a.txt", to: "final/a.txt" },
    { from: "tmp/b.txt", to: "final/b.txt" },
]);

const { existing, missing } = await files.exists(["a.txt", "b.txt", "missing.txt"]);
```

Each bulk call accepts `concurrency` (default `8`) and `stopOnError` (default `false`). When `false`, every key is attempted and per-key failures land in `errors`; when `true`, dispatching stops on the first failure (in-flight operations still complete). `delete` prefers the adapter's native bulk primitive (S3 `DeleteObjects`, Supabase `remove`, UploadThing `deleteFiles`) when one exists and `stopOnError` isn't set.

## Cross-provider migration: `transfer(source, destination, opts?)` [#cross-provider-migration-transfersource-destination-opts]

Stream every object from one `Files` instance to another. Built entirely on the public surface — no adapter implements anything new.

```ts
import { Files, transfer } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";
import { BunnyStorage } from "@visulima/storage/provider/bunny";

const from = new Files({ adapter: new S3Storage({ bucket: "old", region: "us-east-1" }) });
const to = new Files({ adapter: new BunnyStorage({ zone, accessKey, region: "de" }) });

const { transferred, skipped, errors } = await transfer(from, to, {
    prefix: "uploads/",
    concurrency: 8,
    onProgress: ({ done, key, status }) => log.info(done, key, status),
});
```

Each object is downloaded and re-uploaded with bounded concurrency. By default keys that already exist at the destination are skipped — pass `overwrite: true` to force re-upload. `transformKey` rewrites the destination key, `stopOnError` switches to sequential execution and aborts on the first failure, `signal` aborts mid-walk. Body, content type, and user metadata travel; `etag`/`lastModified` are destination-assigned.

The walk pulls from `source.listAll()` directly via N concurrent workers — no eager buffering of keys, so very large buckets transfer in constant memory.

## In-memory adapter for tests [#in-memory-adapter-for-tests]

`MemoryStorage` is a `BaseStorage` adapter backed by a `Map<string, MemoryEntry>`. It implements the full surface (including ranged reads) without touching disk or any external service — useful for tests, ephemeral environments, and as a reference implementation.

```ts
import { Files } from "@visulima/storage";
import MemoryStorage from "@visulima/storage/provider/memory";

const files = new Files({
    adapter: new MemoryStorage({
        initial: {
            "users/1.json": '{"id":1}',
            "users/2.json": '{"id":2}',
        },
    }),
});

await files.upload("docs/x.txt", "x");
// `raw` exposes the backing Map for direct inspection / reset:
files.raw.clear();
```

`supportsRange` is `true`, so `download({ range })` works against the in-memory store.

## Errors [#errors]

Every method that hits the network throws an `UploadError` from `@visulima/storage` on failure, with a stable `UploadErrorCode` from the `ERRORS` enum:

```ts
import { ERRORS, isUploadError } from "@visulima/storage";

try {
    await files.download("missing.bin");
} catch (error) {
    if (isUploadError(error) && error.UploadErrorCode === ERRORS.FILE_NOT_FOUND) {
        // …
    }
    throw error;
}
```

Adapters normalize provider-specific error shapes into the same enum: `FILE_NOT_FOUND` (404), `FORBIDDEN` (401/403), `BAD_REQUEST` (400), `METHOD_NOT_ALLOWED` (unsupported primitive), `STORAGE_ERROR` (everything else). The original error is preserved on `UploadError.detail`.

→ See [Error handling](/docs/packages/storage/error-handling) for the full enum and how to wrap your own adapter errors.

## When to drop down to the adapter [#when-to-drop-down-to-the-adapter]

The facade is intentionally narrow. Reach for the adapter (`files.adapter`) when you need:

* **Resumable uploads** — `BaseStorage.write(part)` takes a `FilePart` with `start` offsets; `Files.upload` is one-shot only.
* **Lifecycle hooks** — `onCreate`, `onUpdate`, `onComplete`, `onDelete`, `onError` are configured on the adapter (distinct from the facade `onAction` / `onError` / `onRetry` hooks).
* **Validators / locking** — file-type, size, and MIME validation; lock tokens for concurrent writers.
* **Expiration / purge** — the adapter's `expiration` config.
* **OpenAPI export** — schema generation against the adapter, not the facade.
* **Transformers** — `ImageTransformer`, `VideoTransformer`, `AudioTransformer`, `MediaTransformer` all take an adapter.

The facade and the adapter are not exclusive — `files.adapter` always returns the underlying `BaseStorage`, so you can mix both styles in the same codebase.


# Express (/docs/packages/storage/framework/express)



# Express Integration [#express-integration]

Use Visulima upload with Express.js for file uploads and on-demand image transformations. For modern frameworks like Hono, Deno, or Bun, see the Modern (Fetch API) guide.

## Installation [#installation]

```sh
npm install @visulima/storage express
```

```sh
yarn add @visulima/storage express
```

```sh
pnpm add @visulima/storage express
```

## Basic File Upload [#basic-file-upload]

### Multipart Handler (Form-based Uploads) [#multipart-handler-form-based-uploads]

````ts
import express from "express";
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/node";

const app = express();
const PORT = 3000;

// Create upload directory if it doesn't exist
const uploadDirectory = "./uploads";

// Initialize storage and multipart handler
const storage = new DiskStorage({ directory: uploadDirectory });
const multipart = new Multipart({ storage });

app.use("/files", multipart.handle, (req, res) => {
  const file = req.body;
  res.json(file);
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

## Fetch Method Alternative

For environments that support Web API Request/Response objects, you can also use the `fetch` method directly:

```ts
import express from "express";
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/node";

const app = express();
const PORT = 3000;

const storage = new DiskStorage({ directory: uploadDirectory });
const multipart = new Multipart({ storage });

// Using fetch method with a custom handler
app.use("/upload", express.raw({ type: "multipart/form-data" }), async (req, res) => {
  try {
    // Convert Node.js request to Web API Request
    const webRequest = new Request(`http://localhost:${PORT}/upload`, {
      method: req.method,
      headers: req.headers as any,
      body: req.body,
    });

    const response = await multipart.fetch(webRequest);

    // Convert back to Express response
    res.status(response.status);
    for (const [key, value] of response.headers.entries()) {
      res.setHeader(key, value);
    }

    const body = await response.text();
    res.send(body);
  } catch (error) {
    res.status(500).json({ error: "Upload failed" });
  }
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
````

### REST Handler (Direct Binary Uploads) [#rest-handler-direct-binary-uploads]

```ts
import express from "express";
import { DiskStorage } from "@visulima/storage";
import { Rest } from "@visulima/storage/handler/http/node";

const app = express();
const PORT = 3000;

const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Upload file with raw binary data
app.post("/files", rest.handle, (req, res) => {
    const file = req.body;
    res.json(file);
});

// Create or update file (requires ID in URL)
app.put("/files/:id", rest.handle, (req, res) => {
    const file = req.body;
    res.json(file);
});

// Delete single file
app.delete("/files/:id", rest.handle, (req, res) => {
    res.status(204).send();
});

// Batch delete multiple files via query parameter
// DELETE /files?ids=id1,id2,id3
app.delete("/files", rest.handle, (req, res) => {
    res.status(204).send();
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});
```

### Choosing Between Handlers [#choosing-between-handlers]

* **Multipart**: Use for traditional web form uploads (`multipart/form-data`)
* **REST**: Use for direct binary uploads, API-first applications, or when you need PUT support
* **TUS**: Use for large files or when you need resumable uploads

Note: The `handle` middleware attaches the completed `UploadFile` to `req.body` for POST/PUT uploads and streams/serves files for GET.

## Image Transformations [#image-transformations]

Add on-demand image transformations with URL query parameters:

```ts
import express from "express";
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/node";
import ImageTransformer from "@visulima/storage/transformer/image";

const app = express();
const PORT = 3000;

const uploadDirectory = "./uploads";

// Initialize storage
const storage = new DiskStorage({ directory: uploadDirectory });

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

// Initialize image transformer
const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});

// Initialize multipart handler
const multipart = new Multipart({ storage });

// File upload endpoint
app.use("/files", multipart.handle, (req, res) => {
    const file = req.body;
    res.json(file);
});

// Image transformation endpoint with query parameters
// Example URLs:
// GET /files/image123?width=300&height=200&fit=cover&quality=80
// GET /files/photo456?width=800&format=webp&lossless=true
// GET /files/anim.gif?width=400&height=300&loop=0&delay=100
app.get("/files/:id", async (req, res) => {
    try {
        const { id } = req.params;
        const { width, height, fit, position, quality, lossless, effort, alphaQuality, loop, delay } = req.query;

        // Check if any transformation parameters are provided
        const hasTransformParams = width || height || fit || position || quality || lossless || effort || alphaQuality || loop || delay;

        if (!hasTransformParams) {
            // No transformation requested, serve original file
            // Delegate GET to handler to stream efficiently (incl. range)
            return multipart.upload(req as any, res as any);
        }

        // Parse transformation options
        const transformOptions: any = {};

        if (width) transformOptions.width = Number(width);
        if (height) transformOptions.height = Number(height);
        if (fit) transformOptions.fit = fit;
        if (position) transformOptions.position = position;
        if (quality) transformOptions.quality = Number(quality);
        if (lossless !== undefined) transformOptions.lossless = lossless === "true";
        if (effort) transformOptions.effort = Number(effort);
        if (alphaQuality) transformOptions.alphaQuality = Number(alphaQuality);
        if (loop !== undefined) transformOptions.loop = Number(loop);
        if (delay) transformOptions.delay = Number(delay);

        // Apply transformation
        // Use high-level convenience methods when possible
        const result = await imageTransformer.resize(id, transformOptions);

        // Set appropriate headers
        res.set({
            "Content-Type": `image/${result.format}`,
            "Content-Length": result.buffer.length,
            "Cache-Control": "public, max-age=3600", // Cache for 1 hour
            "X-Transformed": "true",
        });

        res.send(result.buffer);
    } catch (error) {
        console.error("Error transforming image:", error);
        res.status(500).json({ error: "Image transformation failed" });
    }
});

// Programmatic transformation example
app.post("/transform/:id", async (req, res) => {
    try {
        const { id } = req.params;
        const { width, height, fit = "cover", quality = 80, format = "jpeg" } = req.body;

        const result = await imageTransformer.resize(id, {
            width: Number(width),
            height: Number(height),
            fit: fit as "cover" | "contain" | "fill" | "inside" | "outside",
            quality: Number(quality),
            format: format as "jpeg" | "png" | "webp" | "avif" | "tiff",
        });

        res.json({
            originalSize: result.originalSize,
            transformedSize: result.buffer.length,
            format: result.format,
            url: `/files/${id}?width=${width}&height=${height}&fit=${fit}&quality=${quality}`,
        });
    } catch (error) {
        console.error("Error in programmatic transformation:", error);
        res.status(500).json({ error: "Transformation failed" });
    }
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
    console.log(`Upload files to: http://localhost:${PORT}/files`);
    console.log(`Transform images: http://localhost:${PORT}/files/{id}?width=300&height=200`);
});
```

## Configuration Options [#configuration-options]

### ImageTransformer Configuration [#imagetransformer-configuration]

```ts
const imageTransformer = new ImageTransformer(storage, {
    maxImageSize: 10 * 1024 * 1024, // Maximum image size in bytes (default: 50MB)
    cacheTtl: 3600, // Cache TTL in seconds (default: 3600)
    supportedFormats: ["jpeg", "png"], // Supported input formats (default: all)
    logger: console, // Logger instance (default: console)
});
```

### Storage Configuration [#storage-configuration]

```ts
const storage = new DiskStorage({
    directory: "./uploads", // Upload directory
    expiration: { maxAge: "1h" }, // File expiration
    logger: console, // Logger instance
});
```

## Error Handling [#error-handling]

Handle common errors when working with image transformations:

```ts
app.get("/files/:id", async (req, res) => {
    try {
        // ... transformation logic ...
    } catch (error) {
        if (error.message?.includes("not found")) {
            return res.status(404).json({ error: "File not found" });
        }

        if (error.message?.includes("exceeds maximum")) {
            return res.status(413).json({ error: "File too large" });
        }

        if (error.message?.includes("Unsupported image format")) {
            return res.status(415).json({ error: "Unsupported image format" });
        }

        console.error("Transformation error:", error);
        res.status(500).json({ error: "Internal server error" });
    }
});
```

## Performance Tips [#performance-tips]

1. **Enable Caching**: Provide a proper cache instance (e.g., LRUCache) to cache transformed images
2. **Use Appropriate Quality**: Lower quality values reduce file size but may affect visual quality
3. **Choose Efficient Formats**: WebP and AVIF often provide better compression than JPEG
4. **Set Reasonable Limits**: Configure `maxImageSize` to prevent memory issues
5. **Use Content-Length**: Always set the Content-Length header for better performance


# Modern (/docs/packages/storage/framework/modern)



# Modern Frameworks (Fetch API) [#modern-frameworks-fetch-api]

Use Visulima upload with modern frameworks that support the Web Fetch API, including Hono, Cloudflare Workers, Deno, Bun, and other Web API environments.

## Installation [#installation]

```sh
npm install @visulima/storage
```

```sh
yarn add @visulima/storage
```

```sh
pnpm add @visulima/storage
```

## Overview [#overview]

Modern frameworks that use the Web Fetch API can take advantage of the `fetch()` method, which provides native Web API Request/Response support without conversion layers.

## Handler Import Paths [#handler-import-paths]

Visulima Storage provides framework-specific import paths for convenience:

* **`@visulima/storage/handler/http/fetch`** - Generic Web API (works everywhere)
* **`@visulima/storage/handler/http/hono`** - Hono framework (includes `createStorageHandler` helper)
* **`@visulima/storage/handler/http/bun`** - Bun runtime (alias for fetch)
* **`@visulima/storage/handler/http/cloudflare`** - Cloudflare Workers (alias for fetch)
* **`@visulima/storage/handler/http/deno`** - Deno runtime (alias for fetch)
* **`@visulima/storage/handler/http/edge`** - Edge runtimes (Vercel, Netlify) (alias for fetch)

> **Note**: Most framework-specific paths are aliases to `./handler/http/fetch`. The Hono path (`/handler/http/hono`) provides an additional `createStorageHandler` function that automatically registers routes. Use the framework-specific path for clarity, or use the generic `fetch` path - both work identically.

## Choosing the Right Handler [#choosing-the-right-handler]

* **Multipart**: Use for traditional web form uploads (`multipart/form-data`)
* **REST**: Use for direct binary uploads, API-first applications, or when you need PUT support
* **TUS**: Use for large files, unreliable networks, or when you need resumable uploads

## Hono [#hono]

Hono is a fast, lightweight web framework for Node runtimes and Web API environments.

### Recommended: Using `createStorageHandler` (Automatic Route Registration) [#recommended-using-createstoragehandler-automatic-route-registration]

The easiest way to use Visulima Storage with Hono is to use the `createStorageHandler` function, which automatically registers all required routes for you:

```ts
import { Hono } from "hono";
import { DiskStorage } from "@visulima/storage";
import { createStorageHandler } from "@visulima/storage/handler/http/hono";

const app = new Hono();
const storage = new DiskStorage({ directory: "./uploads" });

// Register handlers - routes are automatically registered!
createStorageHandler(app, {
    path: "/files",
    storage,
    type: "multipart",
});

createStorageHandler(app, {
    path: "/files-rest",
    storage,
    type: "rest",
});

createStorageHandler(app, {
    path: "/files-tus",
    storage,
    type: "tus",
});
```

This automatically registers:

* **Multipart**: `POST /files`, `GET /files/:id?/:metadata?`, `DELETE /files/:id`, `OPTIONS /files`
* **REST**: `POST /files-rest`, `PUT /files-rest/:id`, `PATCH /files-rest/:id`, `GET /files-rest/:id?`, `HEAD /files-rest/:id`, `DELETE /files-rest/:id?`, `OPTIONS /files-rest`
* **TUS**: All methods on `/files-tus` and `/files-tus/:id` (POST, PATCH, HEAD, GET, DELETE, OPTIONS)

### With Media Transformers [#with-media-transformers]

You can also pass media transformers to enable image/video/audio transformations:

```ts
import { Hono } from "hono";
import { DiskStorage } from "@visulima/storage";
import { createStorageHandler } from "@visulima/storage/handler/http/hono";
import { MediaTransformer } from "@visulima/storage/transformer";
import ImageTransformer from "@visulima/storage/transformer/image";

const app = new Hono();
const storage = new DiskStorage({ directory: "./uploads" });

const mediaTransformer = new MediaTransformer(storage, {
    ImageTransformer,
    maxImageSize: 10 * 1024 * 1024, // 10MB
});

createStorageHandler(app, {
    path: "/files",
    storage,
    mediaTransformer,
    type: "multipart",
});
```

### Manual Route Registration (Advanced) [#manual-route-registration-advanced]

If you need more control over route registration, you can manually register routes:

```ts
import { Hono } from "hono";
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/fetch";

const app = new Hono();
const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// File upload endpoint
app.post("/upload", async (c) => {
    try {
        return await multipart.fetch(c.req.raw);
    } catch (error) {
        return c.json({ error: "Upload failed" }, 500);
    }
});

// File listing endpoint
app.get("/files", async (c) => {
    try {
        return await multipart.fetch(c.req.raw);
    } catch (error) {
        return c.json({ error: "Failed to list files" }, 500);
    }
});

// File download endpoint
app.get("/files/:id", async (c) => {
    try {
        return await multipart.fetch(c.req.raw);
    } catch (error) {
        return c.json({ error: "File not found" }, 404);
    }
});

export default app;
```

## Cloudflare Workers [#cloudflare-workers]

Cloudflare Workers do not provide a writable filesystem. `DiskStorage` is not supported. Use a remote/object storage adapter suitable for Workers (e.g., R2) or proxy uploads to a Node server using supported adapters (S3, GCS, Azure, local disk). When running Hono on Workers, prefer storage backends that operate over HTTP APIs instead of local disk.

### Using Framework-Specific Import [#using-framework-specific-import]

```ts
import { S3Storage } from "@visulima/storage/provider/aws";
import { Multipart } from "@visulima/storage/handler/http/cloudflare";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
});

const multipart = new Multipart({ storage });

export default {
    async fetch(request: Request): Promise<Response> {
        return await multipart.fetch(request);
    },
};
```

### Using Generic Fetch Import [#using-generic-fetch-import]

```ts
import { S3Storage } from "@visulima/storage/provider/aws";
import { Multipart } from "@visulima/storage/handler/http/fetch";
```

## Deno [#deno]

Deno provides native TypeScript support and Web API compatibility.

### Using Framework-Specific Import [#using-framework-specific-import-1]

```ts
import { DiskStorage } from "npm:@visulima/storage";
import { Multipart } from "npm:@visulima/storage/handler/http/deno";
```

### Using Generic Fetch Import [#using-generic-fetch-import-1]

```ts
import { DiskStorage } from "npm:@visulima/storage";
import { Multipart } from "npm:@visulima/storage/handler/http/fetch";

// Initialize storage and handler
const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// HTTP server
Deno.serve(async (request: Request) => {
    const url = new URL(request.url);

    try {
        // Route requests
        if (url.pathname === "/upload" && request.method === "POST") {
            return await multipart.fetch(request);
        }

        if (url.pathname === "/files" && request.method === "GET") {
            return await multipart.fetch(request);
        }

        if (url.pathname.startsWith("/files/") && request.method === "GET") {
            return await multipart.fetch(request);
        }

        return new Response("Not found", { status: 404 });
    } catch (error) {
        console.error("Request error:", error);
        return Response.json({ error: "Internal server error" }, { status: 500 });
    }
});
```

## Bun [#bun]

Bun is a fast JavaScript runtime with Web API support.

### Using Framework-Specific Import [#using-framework-specific-import-2]

```ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/bun";
```

### Using Generic Fetch Import [#using-generic-fetch-import-2]

```ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/fetch";

// Initialize storage and handler
const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// HTTP server
const server = Bun.serve({
    port: 3000,
    async fetch(request: Request): Promise<Response> {
        const url = new URL(request.url);

        try {
            // Route requests
            if (url.pathname === "/upload" && request.method === "POST") {
                return await multipart.fetch(request);
            }

            if (url.pathname === "/files" && request.method === "GET") {
                return await multipart.fetch(request);
            }

            if (url.pathname.startsWith("/files/") && request.method === "GET") {
                return await multipart.fetch(request);
            }

            return new Response("Not found", { status: 404 });
        } catch (error) {
            console.error("Request error:", error);
            return Response.json({ error: "Internal server error" }, { status: 500 });
        }
    },
});

console.log(`Server running on port ${server.port}`);
```

## REST Handler (Direct Binary Uploads) [#rest-handler-direct-binary-uploads]

The REST handler provides a clean REST API for direct binary file uploads:

```ts
import { DiskStorage } from "@visulima/storage";
import { Rest } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

// Upload file with raw binary data
app.post("/files", async (c) => {
    return await rest.fetch(c.req.raw);
});

// Create or update file (requires ID in URL)
app.put("/files/:id", async (c) => {
    return await rest.fetch(c.req.raw);
});

// Delete single file
app.delete("/files/:id", async (c) => {
    return await rest.fetch(c.req.raw);
});

// Batch delete multiple files
app.delete("/files", async (c) => {
    const url = new URL(c.req.url);
    // Delete via query parameter: ?ids=id1,id2,id3
    // Or via JSON body: { "ids": ["id1", "id2"] }
    return await rest.fetch(c.req.raw);
});

// Get file metadata
app.head("/files/:id", async (c) => {
    return await rest.fetch(c.req.raw);
});
```

### REST Handler Features [#rest-handler-features]

* **Direct binary uploads**: Upload raw binary data without multipart encoding
* **PUT support**: Create or update files with PUT method
* **Batch delete**: Delete multiple files in one request
* **RESTful API**: Clean REST interface for file operations

## TUS Protocol Support [#tus-protocol-support]

The `fetch` method also supports TUS resumable uploads:

```ts
import { DiskStorage } from "@visulima/storage";
import { Tus } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const tus = new Tus({ storage });

// TUS endpoints
app.post("/upload/tus", async (c) => {
    return await tus.fetch(c.req.raw);
});

app.patch("/upload/tus/:id", async (c) => {
    return await tus.fetch(c.req.raw);
});

app.head("/upload/tus/:id", async (c) => {
    return await tus.fetch(c.req.raw);
});
```

## Image Transformations [#image-transformations]

Combine with image transformations for on-demand processing:

```ts
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/fetch";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
});

// Upload endpoint
app.post("/upload", async (c) => {
    return await multipart.fetch(c.req.raw);
});

// Image transformation endpoint (resize + optional format)
app.get("/images/:id", async (c) => {
    const { id } = c.req.param();
    const url = new URL(c.req.url);

    // Get transformation parameters
    const width = url.searchParams.get("width");
    const height = url.searchParams.get("height");
    const fit = url.searchParams.get("fit") || "cover";
    const quality = url.searchParams.get("quality") || "80";
    const format = url.searchParams.get("format") || undefined;

    try {
        let result;

        if (width || height) {
            result = await imageTransformer.resize(id, {
                width: width ? Number(width) : undefined,
                height: height ? Number(height) : undefined,
                fit: fit as "cover" | "contain" | "fill" | "inside" | "outside",
                quality: quality ? Number(quality) : undefined,
            });
        } else {
            // No resize options provided; fall back to format conversion if requested
            result = await imageTransformer.convertFormat(id, (format || "jpeg") as any, {
                quality: quality ? Number(quality) : undefined,
            });
        }

        return new Response(result.buffer, {
            headers: {
                "Content-Type": `image/${result.format}`,
                "Cache-Control": "public, max-age=3600",
            },
        });
    } catch (error) {
        return c.json({ error: "Image transformation failed" }, 500);
    }
});
```

## Error Handling [#error-handling]

Handle errors consistently across frameworks:

```ts
app.use("*", async (c) => {
    try {
        // Your route handlers here
        return await multipart.fetch(c.req.raw);
    } catch (error) {
        console.error("Request error:", error);

        // Return appropriate error response
        return c.json(
            {
                error: "Request failed",
                message: error instanceof Error ? error.message : "Unknown error",
            },
            500,
        );
    }
});
```

## Configuration [#configuration]

Configure storage and upload options:

```ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({
    directory: "./uploads",
    expiration: { maxAge: "7d" }, // Files expire in 7 days
});

const multipart = new Multipart({
    storage,
    // Additional multipart options can be configured here
});
```

## OpenAPI (Swagger) [#openapi-swagger]

If you expose HTTP endpoints, you can generate OpenAPI specs for both multipart (XHR) and TUS routes and serve Swagger UI. See the Hono example for combining `xhrOpenApiSpec` and `tusOpenApiSpec` and mounting `/openapi.json`.

## Performance Tips [#performance-tips]

1. **Initialize once**: Create storage and handler instances outside request handlers
2. **Use appropriate storage**: Choose storage backends based on your deployment environment
3. **Enable caching**: For image transformations, enable caching for better performance
4. **Handle large files**: Configure appropriate limits for your use case
5. **Monitor errors**: Log and monitor upload errors for debugging

## Edge Functions [#edge-functions]

For Vercel Edge Functions and Netlify Edge Functions, use the edge-specific import path:

```ts
import { S3Storage } from "@visulima/storage/provider/aws";
import { Multipart } from "@visulima/storage/handler/http/edge";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
});

const multipart = new Multipart({ storage });

export const config = {
    runtime: "edge",
};

export default async function handler(request: Request) {
    return await multipart.fetch(request);
}
```

## Supported Frameworks [#supported-frameworks]

The `fetch` method works with any framework or runtime that supports the Web Fetch API:

* **Hono** - Lightweight web framework (use `/handler/http/hono`)
* **Cloudflare Workers** - Serverless functions (use `/handler/http/cloudflare`)
* **Deno** - Secure runtime (use `/handler/http/deno`)
* **Bun** - Fast JavaScript runtime (use `/handler/http/bun`)
* **Next.js 15+** - With Web API support (use `/handler/http/fetch` or `/handler/http/edge`)
* **Vercel Edge Functions** - Serverless edge functions (use `/handler/http/edge`)
* **Netlify Edge Functions** - Serverless edge functions (use `/handler/http/edge`)
* **Any Web API compatible environment** (use `/handler/http/fetch`)

> **Tip**: While all framework-specific paths work identically, using the appropriate path makes your code more self-documenting and helps with IDE autocomplete and type checking.


# Nextjs (/docs/packages/storage/framework/nextjs)



# Next.js Integration [#nextjs-integration]

Use Visulima Storage with Next.js for file uploads and on-demand image transformations. The `createNextjsHandler` function provides the easiest way to set up upload endpoints with automatic route handling.

## Installation [#installation]

```sh
npm install @visulima/storage next
```

```sh
yarn add @visulima/storage next
```

```sh
pnpm add @visulima/storage next
```

## Recommended: Using `createNextjsHandler` [#recommended-using-createnextjshandler]

The easiest way to use Visulima Storage with Next.js is to use the `createNextjsHandler` function, which automatically handles all HTTP methods for each handler type:

### Multipart Handler [#multipart-handler]

```ts
// app/api/upload/multipart/route.ts
import { DiskStorage } from "@visulima/storage";
import { createNextjsHandler } from "@visulima/storage/handler/http/nextjs";

const storage = new DiskStorage({ directory: "./uploads" });
const handler = createNextjsHandler({ storage, type: "multipart" });

export const POST = handler;
export const GET = handler;
export const DELETE = handler;
export const OPTIONS = handler;
```

### REST Handler [#rest-handler]

```ts
// app/api/upload/rest/route.ts
import { DiskStorage } from "@visulima/storage";
import { createNextjsHandler } from "@visulima/storage/handler/http/nextjs";

const storage = new DiskStorage({ directory: "./uploads" });
const handler = createNextjsHandler({ storage, type: "rest" });

export const POST = handler;
export const PUT = handler;
export const PATCH = handler;
export const GET = handler;
export const HEAD = handler;
export const DELETE = handler;
export const OPTIONS = handler;
```

### TUS Handler [#tus-handler]

```ts
// app/api/upload/tus/route.ts
import { DiskStorage } from "@visulima/storage";
import { createNextjsHandler } from "@visulima/storage/handler/http/nextjs";

const storage = new DiskStorage({ directory: "./uploads" });
const handler = createNextjsHandler({ storage, type: "tus" });

export const POST = handler;
export const PATCH = handler;
export const HEAD = handler;
export const GET = handler;
export const DELETE = handler;
export const OPTIONS = handler;
```

### With Media Transformers [#with-media-transformers]

You can also pass media transformers to enable image/video/audio transformations:

```ts
// app/api/upload/multipart/route.ts
import { DiskStorage } from "@visulima/storage";
import { createNextjsHandler } from "@visulima/storage/handler/http/nextjs";
import { MediaTransformer } from "@visulima/storage/transformer";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new DiskStorage({ directory: "./uploads" });

const mediaTransformer = new MediaTransformer(storage, {
    ImageTransformer,
    maxImageSize: 10 * 1024 * 1024, // 10MB
});

const handler = createNextjsHandler({
    storage,
    mediaTransformer,
    type: "multipart",
});

export const POST = handler;
export const GET = handler;
export const DELETE = handler;
export const OPTIONS = handler;
```

## Manual Route Registration (Advanced) [#manual-route-registration-advanced]

If you need more control, you can manually register routes using the fetch method:

```ts
// app/api/upload/route.ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

export async function POST(request: Request) {
    try {
        return await multipart.fetch(request);
    } catch (error) {
        console.error("Upload error:", error);
        return Response.json({ error: "Upload failed" }, { status: 500 });
    }
}
```

## Image Transformation API Route [#image-transformation-api-route]

```ts
// app/api/files/[id]/route.ts
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";
import ImageTransformer from "@visulima/storage/transformer/image";
import { NextRequest, NextResponse } from "next/server";

const uploadDirectory = "./uploads";

// Initialize storage
const storage = new DiskStorage({ directory: uploadDirectory });

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

// Initialize image transformer
const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});

export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
    try {
        const { id } = params;
        const { searchParams } = new URL(request.url);

        // Get transformation parameters
        const width = searchParams.get("width");
        const height = searchParams.get("height");
        const fit = searchParams.get("fit");
        const position = searchParams.get("position");
        const quality = searchParams.get("quality");
        const lossless = searchParams.get("lossless");
        const effort = searchParams.get("effort");
        const alphaQuality = searchParams.get("alphaQuality");
        const loop = searchParams.get("loop");
        const delay = searchParams.get("delay");

        // Check if any transformation parameters are provided
        const hasTransformParams = width || height || fit || position || quality || lossless || effort || alphaQuality || loop || delay;

        if (!hasTransformParams) {
            // No transformation requested, serve original file
            try {
                const file = await storage.get({ id });

                const response = new NextResponse(file.content, {
                    status: 200,
                    headers: {
                        "Content-Type": file.contentType,
                        "Content-Length": file.size.toString(),
                        ETag: file.ETag,
                        "Cache-Control": "public, max-age=31536000", // Cache for 1 year
                        ...(file.expiredAt && { "X-Upload-Expires": file.expiredAt.toString() }),
                        ...(file.modifiedAt && { "Last-Modified": file.modifiedAt.toString() }),
                    },
                });

                return response;
            } catch (error) {
                console.error("Error serving original file:", error);
                return NextResponse.json({ error: "File not found" }, { status: 404 });
            }
        }

        // Parse transformation options
        const transformOptions: any = {};

        if (width) transformOptions.width = Number(width);
        if (height) transformOptions.height = Number(height);
        if (fit) transformOptions.fit = fit;
        if (position) transformOptions.position = position;
        if (quality) transformOptions.quality = Number(quality);
        if (lossless !== null) transformOptions.lossless = lossless === "true";
        if (effort) transformOptions.effort = Number(effort);
        if (alphaQuality) transformOptions.alphaQuality = Number(alphaQuality);
        if (loop !== null) transformOptions.loop = Number(loop);
        if (delay) transformOptions.delay = Number(delay);

        // Apply transformation
        const result = await imageTransformer.transform(id, transformOptions);

        // Return transformed image
        const response = new NextResponse(result.buffer, {
            status: 200,
            headers: {
                "Content-Type": `image/${result.format}`,
                "Content-Length": result.buffer.length.toString(),
                "Cache-Control": "public, max-age=3600", // Cache for 1 hour
                "X-Transformed": "true",
            },
        });

        return response;
    } catch (error) {
        console.error("Error transforming image:", error);
        return NextResponse.json({ error: "Image transformation failed" }, { status: 500 });
    }
}
```

## Client-side Usage [#client-side-usage]

Create a React component for uploading and displaying images:

```tsx
// components/ImageUpload.tsx
"use client";

import { useState } from "react";

export default function ImageUpload() {
    const [uploadedFile, setUploadedFile] = useState<{ id: string; filename: string } | null>(null);
    const [uploading, setUploading] = useState(false);

    const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
        const file = event.target.files?.[0];
        if (!file) return;

        setUploading(true);

        try {
            const formData = new FormData();
            formData.append("file", file);

            const response = await fetch("/api/upload", {
                method: "POST",
                body: formData,
            });

            const result = await response.json();

            if (response.ok) {
                setUploadedFile(result);
            } else {
                console.error("Upload failed:", result.error);
            }
        } catch (error) {
            console.error("Upload error:", error);
        } finally {
            setUploading(false);
        }
    };

    return (
        <div>
            <input type="file" accept="image/*" onChange={handleFileUpload} disabled={uploading} />

            {uploading && <p>Uploading...</p>}

            {uploadedFile && (
                <div>
                    <h3>Uploaded: {uploadedFile.filename}</h3>

                    {/* Original image */}
                    <img src={`/api/files/${uploadedFile.id}`} alt="Original" style={{ maxWidth: "300px", margin: "10px" }} />

                    {/* Transformed images */}
                    <div style={{ display: "flex", gap: "10px", flexWrap: "wrap" }}>
                        <div>
                            <h4>Thumbnail (300x200)</h4>
                            <img src={`/api/files/${uploadedFile.id}?width=300&height=200&fit=cover&quality=80`} alt="Thumbnail" />
                        </div>

                        <div>
                            <h4>WebP (800px wide)</h4>
                            <img src={`/api/files/${uploadedFile.id}?width=800&format=webp&quality=85`} alt="WebP version" />
                        </div>

                        <div>
                            <h4>Grayscale</h4>
                            <img src={`/api/files/${uploadedFile.id}?width=400&height=300&grayscale=true`} alt="Grayscale" />
                        </div>
                    </div>
                </div>
            )}
        </div>
    );
}
```

## Next.js Image Component Integration [#nextjs-image-component-integration]

Use Next.js Image component with transformed URLs:

```tsx
// components/OptimizedImage.tsx
import Image from "next/image";

interface OptimizedImageProps {
    fileId: string;
    width: number;
    height: number;
    alt: string;
    quality?: number;
    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
}

export default function OptimizedImage({ fileId, width, height, alt, quality = 80, fit = "cover" }: OptimizedImageProps) {
    const transformUrl = `/api/files/${fileId}?width=${width}&height=${height}&fit=${fit}&quality=${quality}&format=webp`;

    return (
        <Image
            src={transformUrl}
            alt={alt}
            width={width}
            height={height}
            priority={false}
            placeholder="blur"
            blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAAIAAoDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAhEAACAQMDBQAAAAAAAAAAAAABAgMABAUGIWGRkqGx0f/EABUBAQEAAAAAAAAAAAAAAAAAAAMF/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAECEgMRkf/aAAwDAQACEQMRAD8AltJagyeH0AthI5xdrLcNM91BF5pX2HaH9bcfaSXWGaRmknyJckliyjqTzSlT54b6bk+h0R+IRjWjBqO6O2mhP//Z"
        />
    );
}
```

## Programmatic Transformations [#programmatic-transformations]

Create server-side transformations for pre-processing:

```ts
// app/api/transform/route.ts
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";
import ImageTransformer from "@visulima/storage/transformer/image";
import { NextRequest, NextResponse } from "next/server";

const storage = new DiskStorage({ directory: "./uploads" });

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024,
});

export async function POST(request: NextRequest) {
    try {
        const { fileId, transformations } = await request.json();

        const results = [];

        for (const transform of transformations) {
            const result = await imageTransformer.transform(fileId, transform);
            results.push({
                ...transform,
                size: result.buffer.length,
                format: result.format,
                url: `/api/files/${fileId}?${new URLSearchParams(transform as any).toString()}`,
            });
        }

        return NextResponse.json({ results });
    } catch (error) {
        console.error("Batch transformation error:", error);
        return NextResponse.json({ error: "Transformation failed" }, { status: 500 });
    }
}
```

## Configuration [#configuration]

Add environment variables for configuration:

```bash
# .env.local
UPLOAD_DIR=./uploads
MAX_IMAGE_SIZE=10485760  # 10MB
CACHE_TTL=3600          # 1 hour
```

```ts
// lib/upload-config.ts
import { DiskStorage } from "@visulima/storage";
import ImageTransformer from "@visulima/storage/transformer/image";

export const storage = new DiskStorage({
    directory: process.env.UPLOAD_DIR || "./uploads",
    logger: console,
});

export const imageTransformer = new ImageTransformer(storage, {
    maxImageSize: parseInt(process.env.MAX_IMAGE_SIZE || "10485760"),
    cacheTtl: parseInt(process.env.CACHE_TTL || "3600"),
    logger: console,
});
```

## Error Handling [#error-handling]

Handle transformation errors gracefully:

```ts
// app/api/files/[id]/route.ts
export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
    try {
        // ... transformation logic ...
    } catch (error: any) {
        console.error("Image transformation error:", error);

        // Handle specific error types
        if (error.message?.includes("not found")) {
            return NextResponse.json({ error: "File not found" }, { status: 404 });
        }

        if (error.message?.includes("exceeds maximum")) {
            return NextResponse.json({ error: "File too large" }, { status: 413 });
        }

        if (error.message?.includes("Unsupported image format")) {
            return NextResponse.json({ error: "Unsupported image format" }, { status: 415 });
        }

        return NextResponse.json({ error: "Internal server error" }, { status: 500 });
    }
}
```

## Performance Optimization [#performance-optimization]

1. **Enable Response Caching**: Use Next.js caching for transformed images
2. **Optimize Bundle Size**: Import only needed transformation functions
3. **Use WebP/AVIF**: Serve modern formats for better compression
4. **Implement Image Preloading**: Generate common sizes during upload
5. **Monitor Performance**: Track transformation times and cache hit rates


# Nuxt (/docs/packages/storage/framework/nuxt)



# Nuxt Integration [#nuxt-integration]

Use Visulima Storage with Nuxt 3+ for file uploads and on-demand image transformations. The Nuxt module automatically registers upload endpoints without requiring manual API route files.

## Installation [#installation]

```sh
npm install @visulima/storage nuxt
```

```sh
yarn add @visulima/storage nuxt
```

```sh
pnpm add @visulima/storage nuxt
```

## Quick Start [#quick-start]

The Nuxt module automatically sets up upload endpoints. Simply configure it in your `nuxt.config.ts`:

```ts
// nuxt.config.ts
import { DiskStorage } from "@visulima/storage";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [
        [
            storageModule,
            {
                storage: new DiskStorage({
                    directory: "./uploads",
                }),
            },
        ],
    ],
});
```

This automatically registers three upload endpoints:

* `/api/upload/multipart` - Multipart/form-data uploads
* `/api/upload/rest` - REST API for direct binary uploads
* `/api/upload/tus` - TUS resumable uploads

## Configuration Options [#configuration-options]

The Nuxt module accepts the following configuration options:

```ts
interface ModuleOptions {
    /** Storage instance to use for file uploads (required) */
    storage: BaseStorage;
    /** Base path for upload routes (default: '/api/upload') */
    basePath?: string;
    /** CORS configuration */
    cors?: {
        headers?: string[];
        methods?: string[];
        origin?: string | string[];
    };
    /** Enable multipart upload endpoint (default: true) */
    multipart?: boolean;
    /** Additional options for multipart handler */
    multipartOptions?: UploadOptions;
    /** Enable REST API endpoint (default: true) */
    rest?: boolean;
    /** Additional options for REST handler */
    restOptions?: UploadOptions;
    /** Enable TUS resumable upload endpoint (default: true) */
    tus?: boolean;
    /** Additional options for TUS handler */
    tusOptions?: UploadOptions;
}
```

## Complete Example [#complete-example]

```ts
// nuxt.config.ts
import { DiskStorage } from "@visulima/storage";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new DiskStorage({
            directory: "./uploads",
            maxUploadSize: "100MB",
        }),
        basePath: "/api/upload",
        cors: {
            origin: ["http://localhost:3000", "https://example.com"],
            methods: ["GET", "POST", "PATCH", "PUT", "HEAD", "DELETE", "OPTIONS"],
            headers: ["Content-Type", "Upload-Offset", "Upload-Length", "Tus-Resumable"],
        },
        multipart: true,
        rest: true,
        tus: true,
    },
});
```

## Customizing Handler Options [#customizing-handler-options]

You can pass additional options to each handler type:

```ts
// nuxt.config.ts
import { DiskStorage } from "@visulima/storage";
import { MediaTransformer } from "@visulima/storage/transformer";
import ImageTransformer from "@visulima/storage/transformer/image";
import storageModule from "@visulima/storage/adapter/nuxt";

const storage = new DiskStorage({ directory: "./uploads" });

const mediaTransformer = new MediaTransformer(storage, {
    ImageTransformer,
    maxImageSize: 10 * 1024 * 1024, // 10MB
});

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage,
        basePath: "/api/upload",
        multipartOptions: {
            mediaTransformer,
        },
        restOptions: {
            mediaTransformer,
        },
        tusOptions: {
            mediaTransformer,
        },
    },
});
```

## Enabling/Disabling Specific Handlers [#enablingdisabling-specific-handlers]

You can enable or disable specific handlers:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new DiskStorage({ directory: "./uploads" }),
        // Only enable multipart and REST, disable TUS
        multipart: true,
        rest: true,
        tus: false,
    },
});
```

## Custom Base Path [#custom-base-path]

Change the base path for upload endpoints:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new DiskStorage({ directory: "./uploads" }),
        basePath: "/api/files", // Changes to /api/files/multipart, /api/files/rest, /api/files/tus
    },
});
```

## CORS Configuration [#cors-configuration]

Configure CORS settings for upload endpoints:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new DiskStorage({ directory: "./uploads" }),
        cors: {
            origin: ["https://example.com", "https://app.example.com"],
            methods: ["GET", "POST", "PATCH", "PUT", "HEAD", "DELETE", "OPTIONS"],
            headers: ["Content-Type", "Upload-Offset", "Upload-Length", "Tus-Resumable", "Authorization"],
        },
    },
});
```

## Using Different Storage Backends [#using-different-storage-backends]

### AWS S3 [#aws-s3]

```ts
// nuxt.config.ts
import { S3Storage } from "@visulima/storage/provider/aws";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new S3Storage({
            bucket: process.env.S3_BUCKET!,
            region: process.env.S3_REGION || "us-east-1",
        }),
    },
});
```

### Azure Blob Storage [#azure-blob-storage]

```ts
// nuxt.config.ts
import { AzureStorage } from "@visulima/storage/provider/azure";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new AzureStorage({
            containerName: process.env.AZURE_CONTAINER!,
            accountName: process.env.AZURE_ACCOUNT_NAME!,
            accountKey: process.env.AZURE_ACCOUNT_KEY!,
        }),
    },
});
```

### Google Cloud Storage [#google-cloud-storage]

```ts
// nuxt.config.ts
import { GCStorage } from "@visulima/storage/provider/gcs";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new GCStorage({
            bucket: process.env.GCS_BUCKET!,
        }),
    },
});
```

## Client-Side Usage [#client-side-usage]

Use the `@visulima/storage-client` package with Vue composables for client-side uploads:

```vue
<!-- pages/upload.vue -->
<template>
    <div>
        <input type="file" @change="handleFileChange" />
        <button @click="handleUpload" :disabled="isUploading">
            {{ isUploading ? "Uploading..." : "Upload" }}
        </button>
        <div v-if="progress > 0">Progress: {{ progress }}%</div>
        <div v-if="error">Error: {{ error.message }}</div>
        <div v-if="result">Upload complete! File ID: {{ result.id }}</div>
    </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useUpload } from "@visulima/storage-client/vue";

const file = ref<File | null>(null);
const { upload, progress, isUploading, error, result } = useUpload({
    endpointMultipart: "/api/upload/multipart",
    endpointTus: "/api/upload/tus",
});

const handleFileChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    file.value = target.files?.[0] || null;
};

const handleUpload = async () => {
    if (file.value) {
        await upload(file.value);
    }
};
</script>
```

## Manual API Routes (Advanced) [#manual-api-routes-advanced]

If you need more control, you can create manual API routes instead of using the module:

```ts
// server/api/upload/multipart.post.ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/node";

const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

export default defineEventHandler(async (event) => {
    event.node.res.setHeader("Access-Control-Allow-Origin", "*");
    await multipart.handle(event.node.req, event.node.res);
});
```

```ts
// server/api/upload/rest.post.ts
import { DiskStorage } from "@visulima/storage";
import { Rest } from "@visulima/storage/handler/http/node";

const storage = new DiskStorage({ directory: "./uploads" });
const rest = new Rest({ storage });

export default defineEventHandler(async (event) => {
    event.node.res.setHeader("Access-Control-Allow-Origin", "*");
    await rest.handle(event.node.req, event.node.res);
});
```

## Environment Variables [#environment-variables]

Use environment variables for configuration:

```bash
# .env
UPLOAD_DIR=./uploads
S3_BUCKET=my-bucket
S3_REGION=us-east-1
```

```ts
// nuxt.config.ts
import { S3Storage } from "@visulima/storage/provider/aws";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [storageModule],
    storage: {
        storage: new S3Storage({
            bucket: process.env.S3_BUCKET!,
            region: process.env.S3_REGION || "us-east-1",
        }),
    },
});
```

## Error Handling [#error-handling]

The module automatically handles errors and returns appropriate HTTP responses. Errors are logged to the console in development mode.

## Performance Tips [#performance-tips]

1. **Use appropriate storage**: Choose storage backends based on your deployment environment
2. **Enable caching**: For image transformations, configure caching in handler options
3. **Configure limits**: Set appropriate `maxUploadSize` limits for your use case
4. **Monitor errors**: Check server logs for upload errors in production

## Supported Nuxt Versions [#supported-nuxt-versions]

The Nuxt module requires Nuxt 4.0.0 or higher.

## Next Steps [#next-steps]

* Learn about [Media Transformers](/docs/packages/storage/transformers) for image/video/audio processing
* Explore [Batch Operations](/docs/packages/storage/batch-operations) for deleting multiple files
* Check out [Error Handling](/docs/packages/storage/error-handling) for advanced error management
* See [OpenAPI Documentation](/docs/packages/storage/openapi) for API documentation generation


# Introduction (/docs/packages/storage)



# @visulima/storage [#visulimastorage]

Unified file storage for Node.js, edge runtimes, and modern web frameworks. One library, two surfaces:

* **`Files`** — one-liner API for ad-hoc storage operations. Web-standard body types (`Blob`, `Uint8Array`, `ReadableStream`), a compact set of provider-agnostic methods, bulk-array overloads, lifecycle hooks (`onAction` / `onError` / `onRetry`), ranged downloads, upload progress, async-iterable listings, and a cross-provider `transfer()` for migrations. Use this when you just need to put files somewhere.
* **`BaseStorage` adapters** (`S3Storage`, `DiskStorage`, `BunnyStorage`, …) — the full upload-server framework. TUS / multipart / REST handlers, lifecycle hooks, validators, image / video / audio transformers, OpenAPI export. Use this when you're hosting an upload service.

Both surfaces wrap the same adapters — swap providers without touching call sites.

## Install [#install]

```sh
npm install @visulima/storage
# or yarn add / pnpm add
```

## Quick start with `Files` [#quick-start-with-files]

```ts
import { Files } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

const files = new Files({
    adapter: new S3Storage({ bucket: "uploads", region: "us-east-1" }),
    defaults: { timeout: 30_000, retries: { maxRetries: 5 } },
    hooks: {
        onAction: ({ type, key, durationMs }) => log.info(type, key, durationMs),
        onRetry: ({ type, key, attempt }) => log.warn(type, key, "retry", attempt),
    },
});

await files.upload("avatars/abc.png", buffer, { contentType: "image/png" });

const url = await files.url("avatars/abc.png", { expiresIn: 900 });
const { body } = await files.download("avatars/abc.png", { range: { start: 0, end: 1023 } });

// Bulk: upload / download / delete / move accept an array and return a structured result.
const { uploaded, errors } = await files.upload([
    { key: "a.txt", body: "A" },
    { key: "b.txt", body: "B" },
]);

// Walk every object as an async iterable — pages internally.
for await (const file of files.listAll({ prefix: "avatars/" })) {
    log.info(file.key, file.size);
}
```

For ephemeral environments and tests, an in-memory adapter ships out of the box:

```ts
import MemoryStorage from "@visulima/storage/provider/memory";

const files = new Files({ adapter: new MemoryStorage({ initial: { "k.txt": "x" } }) });
```

Swap the adapter to change provider — everything else stays the same:

```ts
import { Files, DiskStorage } from "@visulima/storage";
import { BunnyStorage } from "@visulima/storage/provider/bunny";

new Files({ adapter: new DiskStorage({ directory: "./uploads" }) });
new Files({ adapter: new BunnyStorage({ zone, accessKey, region: "de" }) });
```

The `Files` facade accepts any web-standard body (`string`, `Buffer`, `Uint8Array`, `ArrayBuffer`, `Blob`, `ReadableStream`, or a Node `Readable`) and returns provider-agnostic `FileObject` results.

→ See the [Files facade reference](/docs/packages/storage/files-facade) for the full method surface.

## Building an upload server? [#building-an-upload-server]

If you're handling client uploads from a browser — large files, resumable transfers, form posts — use the adapter directly with one of the HTTP handlers. The `Files` facade is a one-shot put; upload servers need streaming, locking, and partial-write protocols.

### Node.js / Express [#nodejs--express]

```ts
import { DiskStorage } from "@visulima/storage";
import { Multipart, Rest } from "@visulima/storage/handler/http/node";

const storage = new DiskStorage({ directory: "./uploads" });

const multipart = new Multipart({ storage });
app.use("/upload", multipart.handle, (req, res) => {
    res.json(req.body); // handler writes the stored file metadata to req.body
});

const rest = new Rest({ storage });
app.use("/files", rest.handle);
```

### Hono / Cloudflare Workers / Bun / Deno [#hono--cloudflare-workers--bun--deno]

```ts
import { Hono } from "hono";
import { DiskStorage } from "@visulima/storage";
import { createStorageHandler } from "@visulima/storage/handler/http/hono";

const app = new Hono();
const storage = new DiskStorage({ directory: "./uploads" });

createStorageHandler(app, { path: "/files", storage, type: "multipart" });
createStorageHandler(app, { path: "/files-tus", storage, type: "tus" });
```

Three handlers cover the common upload patterns:

* **Multipart** — `multipart/form-data` from HTML forms.
* **REST** — direct binary `POST` / `PUT`. Optional client-side chunking for large files.
* **TUS** — resumable uploads ([tus.io](https://tus.io)) for unreliable networks and very large files.

→ See [TUS handler](/docs/packages/storage/tus-handler), [Chunked uploads](/docs/packages/storage/chunked-uploads), [Authenticated uploads](/docs/packages/storage/authenticated-file-uploads).

## Choosing your surface [#choosing-your-surface]

| You want to…                                                 | Use                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Save a `Blob` / `Buffer` to S3 and get a signed URL          | `Files`                                                      |
| Bulk-upload / bulk-delete a list of keys                     | `Files` (array overload on every method)                     |
| Migrate every object from one provider to another            | `transfer(source, dest)` on `Files`                          |
| Walk every object in a bucket as an async iterable           | `files.listAll({ prefix })`                                  |
| Observe operation counts, durations, retries from the facade | `Files` with `hooks: { onAction, onRetry }`                  |
| Drop in a file picker / "import from cloud" flow             | `Files` with a consumer provider adapter                     |
| Expose ad-hoc storage to an AI agent or LLM tool             | `Files` + `@visulima/storage/ai/*` subpaths                  |
| Build a TUS / multipart / chunked upload endpoint            | adapter + handler                                            |
| Transform images / video / audio on the fly                  | adapter + [transformer](/docs/packages/storage/transformers) |
| Hook adapter-level `onCreate` / `onComplete` / `onDelete`    | adapter                                                      |
| Export OpenAPI for an upload endpoint                        | adapter + [OpenAPI export](/docs/packages/storage/openapi)   |

## Providers [#providers]

Object storage (service credentials, presigned URLs, S3-style):

* AWS S3 (`S3Storage`, `AWSLightStorage`)
* Azure Blob (`AzureStorage`)
* Google Cloud Storage (`GcsStorage`)
* Vercel Blob (`VercelBlobStorage`)
* Netlify Blobs (`NetlifyBlobStorage`)
* Local filesystem (`DiskStorage`, `DiskStorageWithChecksum`)
* In-memory (`MemoryStorage`) — for tests and ephemeral environments

S3-compatible (branded client configs under `provider/aws/s3/clients`): Cloudflare R2, DigitalOcean Spaces, MinIO, Hetzner, Storj, Backblaze B2, Tigris, Wasabi, Akamai.

Consumer providers (user OAuth or service-credential, all peer-dep gated):

* Dropbox, Google Drive, Microsoft OneDrive, Box
* Supabase Storage, UploadThing, Bunny Storage

→ See [Storage services](/docs/packages/storage/services/capabilities) for the full capability matrix per provider.

## What you get beyond `Files` [#what-you-get-beyond-files]

The `Files` facade is intentionally small. Features below live on the adapter and the framework around it:

* **Upload protocols** — multipart-form, raw REST, chunked REST, TUS resumable.
* **HTTP handlers** — Node, Fetch, Hono, Next.js, SolidStart, Nuxt, Bun, Deno, Cloudflare, Edge.
* **Image / video / audio transformers** — Sharp + Mediabunny, URL-query or programmatic, with caching.
* **Retry + backoff** — exponential retry baked into every adapter, plus custom `shouldRetry`.
* **Observability** — built-in metrics and OpenTelemetry spans.
* **Lifecycle hooks** — `onCreate`, `onUpdate`, `onComplete`, `onDelete`, `onError`.
* **Batch operations** — `deleteBatch`, `copyBatch`, `moveBatch` with per-item error capture.
* **Validators, locking, expiration, checksums** — content / size / MIME limits, lock tokens, automatic purge, MD5/SHA1/SHA256.
* **OpenAPI export** — generate a schema for your upload endpoint.
* **`@visulima/storage-client`** — React / Vue / Solid / Svelte hooks with progress, drag-drop, paste, and abort.
* **AI-tool wrappers** — Vercel AI SDK, OpenAI Responses / Agents, Claude Agent SDK, TanStack AI.

## Next steps [#next-steps]

* [Files facade reference](/docs/packages/storage/files-facade) — full surface (single + bulk, hooks, ranges, progress, `transfer`).
* [Storage services](/docs/packages/storage/services/capabilities) — per-provider configuration and capability matrix.
* [Custom storage](/docs/packages/storage/custom-storage) — write your own adapter against `BaseStorage`.
* [Retry mechanism](/docs/packages/storage/retry-mechanism) — backoff, custom `shouldRetry`, `onRetry` hook.
* [Error handling](/docs/packages/storage/error-handling) — `UploadError`, `ERRORS` enum, and `wrapStorageError`.
* [Observability](/docs/packages/storage/observability) — metrics, OpenTelemetry, structured logs.


# Observability (/docs/packages/storage/observability)



# Observability & Metrics [#observability--metrics]

The storage package provides two complementary observability layers:

* **Adapter-level metrics** — structured counts, durations, and gauges emitted from every `BaseStorage` operation, with built-in OpenTelemetry support.
* **Facade-level hooks** — fire-and-forget `onAction` / `onError` / `onRetry` callbacks on the `Files` facade, carrying per-operation context (`type`, `key`, `from`/`to`, `durationMs`, `attempt`, `error`).

Pick the layer that matches what you need: metrics for aggregation and dashboards; hooks for structured logs and tracing at the application boundary.

## Overview [#overview]

Metrics are collected for all storage operations including:

* **Operation counts** - Track how many operations are performed
* **Operation durations** - Measure latency (p50, p95, p99)
* **Error rates** - Monitor failures by operation type
* **File sizes** - Track file size distributions
* **Batch operation metrics** - Monitor batch operation performance

## `Files` facade hooks [#files-facade-hooks]

The `Files` facade exposes three fire-and-forget hooks. Hooks are called, not awaited; exceptions thrown by a hook are swallowed so a hook can never fail the operation it observes.

```typescript
import { Files } from "@visulima/storage";

const files = new Files({
    adapter,
    hooks: {
        onAction: ({ type, key, durationMs }) => log.info(type, key, durationMs),
        onError: ({ type, key, error, durationMs }) => log.error(type, key, error.message, durationMs),
        onRetry: ({ type, key, attempt, error }) => log.warn(type, key, "retry", attempt, error.message),
    },
});
```

Each event carries:

| Field         | Present on             | Description                                                                                                                                      |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | every event            | `upload` \| `download` \| `head` \| `exists` \| `delete` \| `copy` \| `move` \| `list` \| `listAll` \| `url` \| `signedUploadUrl` \| `transfer`. |
| `key`         | single-key operations  | Caller-facing key (constructor prefix stripped off).                                                                                             |
| `keys`        | bulk-delete            | All caller-facing keys included in the batch.                                                                                                    |
| `from` / `to` | `copy` / `move`        | Source / destination keys.                                                                                                                       |
| `durationMs`  | `onAction` / `onError` | Wall-clock time from the start of the operation to completion or failure.                                                                        |
| `attempt`     | `onRetry`              | 1-based retry attempt number (1 = first retry).                                                                                                  |
| `error`       | `onError`, `onRetry`   | Normalized `Error`.                                                                                                                              |

The `listAll` terminal event fires once at the end of the async-iterable walk — including the case where the consumer breaks out of the `for await` early.

When to use hooks vs. adapter metrics:

* Use **hooks** when you want per-call structured logs with the caller's key, or a tracing span keyed by `type` + `key`.
* Use **adapter metrics** when you want aggregate counters and histograms for dashboards and alerts.

Both layers can be enabled at once — they observe different concerns.

## Metrics Interface [#metrics-interface]

The storage package uses a simple `Metrics` interface that can be implemented by any metrics backend:

```typescript
interface Metrics {
    increment(name: string, value?: number, attributes?: Record<string, string | number>): void;
    timing(name: string, duration: number, attributes?: Record<string, string | number>): void;
    gauge(name: string, value: number, attributes?: Record<string, string | number>): void;
}
```

## OpenTelemetry Integration [#opentelemetry-integration]

The package includes built-in support for OpenTelemetry, the industry-standard observability framework. This allows integration with any OpenTelemetry-compatible backend (Prometheus, Datadog, New Relic, Grafana Cloud, etc.).

### Installation [#installation]

First, install the OpenTelemetry API:

```bash
pnpm add @opentelemetry/api
```

### Basic Usage [#basic-usage]

```typescript
import { metrics } from "@opentelemetry/api";
import { OpenTelemetryMetrics } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

// Initialize OpenTelemetry (typically done once in your app)
const meter = metrics.getMeter("@visulima/storage", "1.0.0");

// Create metrics instance
const storageMetrics = new OpenTelemetryMetrics(meter);

// Use with storage
const storage = new S3Storage({
    bucket: "my-bucket",
    metrics: storageMetrics,
});
```

### Custom Meter [#custom-meter]

You can also provide a custom meter instance:

```typescript
import { metrics } from "@opentelemetry/api";
import { OpenTelemetryMetrics } from "@visulima/storage";

// Create a meter with custom configuration
const meter = metrics.getMeter("my-app", "1.0.0", {
    // Custom meter options
});

const storageMetrics = new OpenTelemetryMetrics(meter);
```

## Collected Metrics [#collected-metrics]

The storage package automatically collects the following metrics:

### Operation Metrics [#operation-metrics]

* `storage.operations.{operation}.count` - Counter for operation invocations
* `storage.operations.{operation}.duration` - Histogram of operation durations (ms)
* `storage.operations.{operation}.error.count` - Counter for operation errors

**Operations tracked:**

* `create` - File creation
* `write` - File write operations
* `get` - File retrieval
* `delete` - File deletion
* `copy` - File copy operations
* `move` - File move operations
* `update` - Metadata updates

### Batch Operation Metrics [#batch-operation-metrics]

* `storage.operations.batch.{operation}.count` - Counter for batch operations
* `storage.operations.batch.{operation}.duration` - Histogram of batch operation durations (ms)
* `storage.operations.batch.{operation}.success_count` - Gauge of successful operations
* `storage.operations.batch.{operation}.failed_count` - Gauge of failed operations

**Batch operations tracked:**

* `delete` - Batch deletions
* `copy` - Batch copies
* `move` - Batch moves

### File Metrics [#file-metrics]

* `storage.files.size` - Gauge of file sizes (bytes)

### Metric Attributes [#metric-attributes]

All metrics include the following attributes:

* `storage` - Storage backend type (e.g., "s3", "azure", "disk")
* `operation` - Operation name (for file size metrics)
* `error` - Error message (for error metrics)
* `batch_size` - Number of items in batch (for batch operations)

## Custom Metrics Implementation [#custom-metrics-implementation]

You can implement your own metrics backend by implementing the `Metrics` interface:

```typescript
import type { Metrics } from "@visulima/storage";
import { DiskStorage } from "@visulima/storage";

class CustomMetrics implements Metrics {
    increment(name: string, value = 1, attributes?: Record<string, string | number>): void {
        // Send to your metrics backend
        console.log(`Counter: ${name} = ${value}`, attributes);
    }

    timing(name: string, duration: number, attributes?: Record<string, string | number>): void {
        // Send to your metrics backend
        console.log(`Timing: ${name} = ${duration}ms`, attributes);
    }

    gauge(name: string, value: number, attributes?: Record<string, string | number>): void {
        // Send to your metrics backend
        console.log(`Gauge: ${name} = ${value}`, attributes);
    }
}

const storage = new DiskStorage({
    directory: "./uploads",
    metrics: new CustomMetrics(),
});
```

## Examples [#examples]

### Prometheus Integration [#prometheus-integration]

```typescript
import { metrics } from "@opentelemetry/api";
import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
import { OpenTelemetryMetrics } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

// Setup Prometheus exporter
const exporter = new PrometheusExporter({ port: 9464 });

const meterProvider = new MeterProvider({
    readers: [new PeriodicExportingMetricReader({ exporter })],
});

metrics.setGlobalMeterProvider(meterProvider);

const meter = metrics.getMeter("@visulima/storage");
const storageMetrics = new OpenTelemetryMetrics(meter);

const storage = new S3Storage({
    bucket: "my-bucket",
    metrics: storageMetrics,
});
```

### Datadog Integration [#datadog-integration]

```typescript
import { metrics } from "@opentelemetry/api";
import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { OpenTelemetryMetrics } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

const exporter = new OTLPMetricExporter({
    url: "https://api.datadoghq.com/api/v2/otlp/v1/metrics",
    headers: {
        "DD-API-KEY": process.env.DATADOG_API_KEY!,
    },
});

const meterProvider = new MeterProvider({
    readers: [new PeriodicExportingMetricReader({ exporter })],
});

metrics.setGlobalMeterProvider(meterProvider);

const meter = metrics.getMeter("@visulima/storage");
const storageMetrics = new OpenTelemetryMetrics(meter);

const storage = new S3Storage({
    bucket: "my-bucket",
    metrics: storageMetrics,
});
```

### Using with Instrumentation Helper [#using-with-instrumentation-helper]

For custom storage implementations, you can use the `instrumentOperation` helper method:

```typescript
import { AbstractBaseStorage } from "@visulima/storage";

class MyStorage extends AbstractBaseStorage {
    public async create(config: FileInit): Promise<File> {
        return this.instrumentOperation(
            "create",
            async () => {
                // Your implementation
                const file = await this.doCreate(config);
                return file;
            },
            {
                custom_attribute: "value",
            },
        );
    }
}
```

## Best Practices [#best-practices]

1. **Use OpenTelemetry for Production** - OpenTelemetry is the industry standard and integrates with all major observability platforms.

2. **Monitor Key Metrics** - Focus on:
   * Operation latencies (p95, p99)
   * Error rates
   * Batch operation success rates
   * File size distributions

3. **Set Up Alerts** - Configure alerts for:
   * High error rates (> 1%)
   * Slow operations (p95 > 1s)
   * Batch operation failures

4. **Use Attributes Wisely** - Attributes are automatically added but you can add custom ones for filtering and grouping.

5. **No Metrics Overhead** - If no metrics instance is provided, a no-op implementation is used, ensuring zero overhead when metrics are disabled.

## Metric Naming Convention [#metric-naming-convention]

All metrics follow this naming pattern:

* `storage.operations.{operation}.{type}` - Operation-level metrics
* `storage.operations.batch.{operation}.{type}` - Batch operation metrics
* `storage.files.{property}` - File-level metrics

Where:

* `{operation}` is the operation name (create, write, delete, etc.)
* `{type}` is the metric type (count, duration, error.count)
* `{property}` is the file property (size)

This consistent naming makes it easy to query and aggregate metrics across all storage operations.


# Openapi (/docs/packages/storage/openapi)



# OpenAPI Documentation [#openapi-documentation]

Visulima Storage provides OpenAPI (Swagger) specifications for all upload handlers, allowing you to automatically generate API documentation for your file upload endpoints.

## Overview [#overview]

The package exports four OpenAPI specifications:

* **`xhrOpenApiSpec`** - Multipart/form-data uploads (XHR)
* **`tusOpenApiSpec`** - TUS resumable upload protocol
* **`restOpenApiSpec`** - REST API for direct binary uploads
* **`transformOpenApiSpec`** - Media transformation endpoints

## Installation [#installation]

OpenAPI specs are included in the main package - no additional installation required.

```bash
npm install @visulima/storage
```

## Basic Usage [#basic-usage]

### Import OpenAPI Specs [#import-openapi-specs]

```typescript
import { xhrOpenApiSpec, tusOpenApiSpec, restOpenApiSpec, transformOpenApiSpec } from "@visulima/storage/openapi";
```

## XHR OpenAPI Spec (Multipart Uploads) [#xhr-openapi-spec-multipart-uploads]

Generate OpenAPI documentation for multipart/form-data upload endpoints.

### Basic Example [#basic-example]

```typescript
import { xhrOpenApiSpec } from "@visulima/storage/openapi";

const spec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp", "avif"],
});
```

### With Custom Tags [#with-custom-tags]

```typescript
const spec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
    tags: ["File Upload", "Multipart"],
});
```

### Options [#options]

```typescript
interface XhrOpenApiSpecOptions {
    /** Transformer type (e.g., "image", "video", "audio") */
    transformer?: string;
    /** Supported transformation formats */
    supportedTransformerFormat?: string[];
    /** Custom OpenAPI tags */
    tags?: string[];
}
```

## TUS OpenAPI Spec (Resumable Uploads) [#tus-openapi-spec-resumable-uploads]

Generate OpenAPI documentation for TUS resumable upload protocol endpoints.

### Basic Example [#basic-example-1]

```typescript
import { tusOpenApiSpec } from "@visulima/storage/openapi";

const spec = tusOpenApiSpec("/files-tus", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
});
```

### Options [#options-1]

```typescript
interface TusOpenApiSpecOptions {
    /** Transformer type */
    transformer?: string;
    /** Supported transformation formats */
    supportedTransformerFormat?: string[];
    /** Custom OpenAPI tags */
    tags?: string[];
}
```

## REST OpenAPI Spec (Direct Binary Uploads) [#rest-openapi-spec-direct-binary-uploads]

Generate OpenAPI documentation for REST API endpoints supporting direct binary uploads and chunked uploads.

### Basic Example [#basic-example-2]

```typescript
import { restOpenApiSpec } from "@visulima/storage/openapi";

const spec = restOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
});
```

### Features Documented [#features-documented]

* POST - Upload file or initialize chunked upload
* PUT - Create or update file
* PATCH - Upload chunks for chunked uploads
* GET - Retrieve file or list files
* DELETE - Delete single file or batch delete
* HEAD - Get file metadata and upload progress

## Transform OpenAPI Spec (Media Transformations) [#transform-openapi-spec-media-transformations]

Generate OpenAPI documentation for media transformation endpoints.

### Basic Example [#basic-example-3]

```typescript
import { transformOpenApiSpec } from "@visulima/storage/openapi";

const spec = transformOpenApiSpec("/files", ["Transform"]);
```

### Options [#options-2]

```typescript
interface TransformOpenApiSpecOptions {
    /** Custom OpenAPI tags */
    tags?: string[];
}
```

## Combining Multiple Specs [#combining-multiple-specs]

Combine multiple OpenAPI specs into a single document for comprehensive API documentation.

### Express Example [#express-example]

```typescript
import express from "express";
import swaggerUi from "swagger-ui-express";
import { xhrOpenApiSpec, transformOpenApiSpec } from "@visulima/storage/openapi";

const app = express();

// Generate OpenAPI specs
const xhrSpec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp", "avif"],
});

const transformSpec = transformOpenApiSpec("/files", ["Transform"]);

// Combine specs
const swaggerSpec = {
    openapi: "3.0.0",
    info: {
        title: "Visulima Storage API",
        version: "1.0.0",
        description: "File upload and transformation API",
    },
    servers: [
        {
            url: "http://localhost:3000",
            description: "Development server",
        },
    ],
    components: {
        schemas: {
            ...xhrSpec.components?.schemas,
            ...transformSpec.components?.schemas,
        },
        examples: {
            ...xhrSpec.components?.examples,
            ...transformSpec.components?.examples,
        },
        responses: {
            ...xhrSpec.components?.responses,
            ...transformSpec.components?.responses,
        },
        parameters: {
            ...xhrSpec.components?.parameters,
            ...transformSpec.components?.parameters,
        },
    },
    paths: {
        ...xhrSpec.paths,
        ...transformSpec.paths,
    },
};

// Serve Swagger UI
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(3000);
```

### Hono Example [#hono-example]

```typescript
import { Hono } from "hono";
import { swaggerUI } from "@hono/swagger-ui";
import { xhrOpenApiSpec, tusOpenApiSpec } from "@visulima/storage/openapi";

const app = new Hono();

// Generate OpenAPI specs
const xhrSpec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
});

const tusSpec = tusOpenApiSpec("/files-tus", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
});

// OpenAPI JSON endpoint
app.get("/openapi.json", (c) => {
    return c.json({
        openapi: "3.0.0",
        info: {
            title: "Visulima Storage API",
            version: "1.0.0",
            description: "File upload API (Multipart & TUS)",
        },
        servers: [
            {
                url: "http://localhost:3000",
                description: "Development server",
            },
        ],
        components: {
            schemas: {
                ...xhrSpec.components?.schemas,
                ...tusSpec.components?.schemas,
            },
            examples: {
                ...xhrSpec.components?.examples,
                ...tusSpec.components?.examples,
            },
            responses: {
                ...xhrSpec.components?.responses,
                ...tusSpec.components?.responses,
            },
            parameters: {
                ...xhrSpec.components?.parameters,
                ...tusSpec.components?.parameters,
            },
        },
        paths: {
            ...xhrSpec.paths,
            ...tusSpec.paths,
        },
    });
});

// Swagger UI
app.get("/", swaggerUI({ url: "/openapi.json" }));

export default app;
```

## Shared Components [#shared-components]

The OpenAPI specs include shared components that can be reused:

```typescript
import { sharedErrorSchemaObject, sharedFileMetaExampleObject, sharedFileMetaSchemaObject, sharedGet, sharedGetList } from "@visulima/storage/openapi";
```

### Available Shared Components [#available-shared-components]

* **`sharedErrorSchemaObject`** - Standard error response schema
* **`sharedFileMetaExampleObject`** - Example file metadata
* **`sharedFileMetaSchemaObject`** - File metadata schema
* **`sharedGet`** - Standard GET operation definition
* **`sharedGetList`** - Standard GET list operation definition

### Using Shared Components [#using-shared-components]

```typescript
import { sharedGet, sharedFileMetaSchemaObject } from "@visulima/storage/openapi";

const customSpec = {
    openapi: "3.0.0",
    paths: {
        "/custom-endpoint": {
            get: sharedGet("CustomGet", ["Custom"]),
        },
    },
    components: {
        schemas: {
            FileMeta: sharedFileMetaSchemaObject,
        },
    },
};
```

## Customization [#customization]

### Custom Tags [#custom-tags]

Add custom tags to organize your API documentation:

```typescript
const spec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
    tags: ["File Management", "Upload"],
});
```

### Multiple Transformers [#multiple-transformers]

Document support for multiple transformer types:

```typescript
const xhrSpec = xhrOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp", "avif", "tiff", "gif"],
});

const restSpec = restOpenApiSpec("http://localhost:3000", "/files", {
    transformer: "video",
    supportedTransformerFormat: ["mp4", "webm", "mkv"],
});
```

## Integration with Swagger UI [#integration-with-swagger-ui]

### Express [#express]

```typescript
import swaggerUi from "swagger-ui-express";
import { xhrOpenApiSpec } from "@visulima/storage/openapi";

const spec = xhrOpenApiSpec("http://localhost:3000", "/files");

app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));
```

### Hono [#hono]

```typescript
import { swaggerUI } from "@hono/swagger-ui";
import { xhrOpenApiSpec } from "@visulima/storage/openapi";

const spec = xhrOpenApiSpec("http://localhost:3000", "/files");

app.get("/docs", swaggerUI({ url: "/openapi.json" }));
app.get("/openapi.json", (c) => c.json(spec));
```

### Fastify [#fastify]

```typescript
import fastifySwagger from "@fastify/swagger";
import { xhrOpenApiSpec } from "@visulima/storage/openapi";

const spec = xhrOpenApiSpec("http://localhost:3000", "/files");

await fastify.register(fastifySwagger, {
    openapi: spec,
});
```

## Best Practices [#best-practices]

1. **Combine Related Specs** - Merge multipart, TUS, and REST specs for comprehensive documentation
2. **Use Consistent Tags** - Organize endpoints with meaningful tags
3. **Document Transformers** - Include transformer information for media transformation endpoints
4. **Version Your API** - Include version information in the OpenAPI info section
5. **Add Examples** - The specs include examples, but you can add custom ones for your use case
6. **Serve from Production URLs** - Update server URLs for production environments

## Complete Example [#complete-example]

```typescript
import express from "express";
import swaggerUi from "swagger-ui-express";
import { xhrOpenApiSpec, tusOpenApiSpec, restOpenApiSpec, transformOpenApiSpec } from "@visulima/storage/openapi";

const app = express();
const PORT = process.env.PORT || 3000;
const BASE_URL = `http://localhost:${PORT}`;

// Generate all OpenAPI specs
const xhrSpec = xhrOpenApiSpec(BASE_URL, "/files", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp", "avif"],
    tags: ["Multipart Upload"],
});

const tusSpec = tusOpenApiSpec("/files-tus", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
    tags: ["TUS Upload"],
});

const restSpec = restOpenApiSpec(BASE_URL, "/files-rest", {
    transformer: "image",
    supportedTransformerFormat: ["jpeg", "png", "webp"],
    tags: ["REST Upload"],
});

const transformSpec = transformOpenApiSpec("/files", ["Transform"]);

// Combine all specs
const combinedSpec = {
    openapi: "3.0.0",
    info: {
        title: "Visulima Storage API",
        version: "1.0.0",
        description: "Complete file upload and transformation API",
        contact: {
            name: "Visulima",
            url: "https://github.com/visulima/visulima",
        },
    },
    servers: [
        {
            url: BASE_URL,
            description: "Development server",
        },
    ],
    components: {
        schemas: {
            ...xhrSpec.components?.schemas,
            ...tusSpec.components?.schemas,
            ...restSpec.components?.schemas,
            ...transformSpec.components?.schemas,
        },
        examples: {
            ...xhrSpec.components?.examples,
            ...tusSpec.components?.examples,
            ...restSpec.components?.examples,
            ...transformSpec.components?.examples,
        },
        responses: {
            ...xhrSpec.components?.responses,
            ...tusSpec.components?.responses,
            ...restSpec.components?.responses,
            ...transformSpec.components?.responses,
        },
        parameters: {
            ...xhrSpec.components?.parameters,
            ...tusSpec.components?.parameters,
            ...restSpec.components?.parameters,
            ...transformSpec.components?.parameters,
        },
    },
    paths: {
        ...xhrSpec.paths,
        ...tusSpec.paths,
        ...restSpec.paths,
        ...transformSpec.paths,
    },
};

// Serve Swagger UI
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(combinedSpec));

app.listen(PORT, () => {
    console.log(`Server running on ${BASE_URL}`);
    console.log(`API docs available at ${BASE_URL}/api-docs`);
});
```

## Next Steps [#next-steps]

* Visit `/api-docs` to view interactive API documentation
* Test endpoints directly from Swagger UI
* Export OpenAPI spec for API clients
* Integrate with API testing tools
* Generate client SDKs from OpenAPI spec


# Retry Mechanism (/docs/packages/storage/retry-mechanism)



# Retry Mechanism [#retry-mechanism]

All storage backends (AWS S3, Azure, GCS, Vercel Blob, Netlify Blob) include automatic retry logic for transient failures. This ensures your uploads and file operations are resilient to network issues, rate limits, and temporary service unavailability.

## Default Behavior [#default-behavior]

By default, storage operations will retry up to 3 times with exponential backoff:

* Initial delay: 1 second
* Backoff multiplier: 2x (delays double each retry: 1s → 2s → 4s)
* Maximum delay: 30 seconds
* Retryable status codes: 408, 429, 500, 502, 503, 504

## Basic Configuration [#basic-configuration]

Configure retry behavior when creating your storage instance:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
    retryConfig: {
        maxRetries: 5,
        initialDelay: 2000,
        backoffMultiplier: 1.5,
        maxDelay: 60_000,
    },
});
```

## Advanced Configuration [#advanced-configuration]

Customize retry logic with backend-specific error detection:

```typescript
import { AzureStorage } from "@visulima/storage/provider/azure";

const storage = new AzureStorage({
    containerName: "uploads",
    accountName: "myaccount",
    accountKey: "mykey",
    retryConfig: {
        maxRetries: 3,
        initialDelay: 1000,
        backoffMultiplier: 2,
        maxDelay: 30_000,
        retryableStatusCodes: [408, 429, 500, 502, 503, 504],
        shouldRetry: (error: unknown) => {
            // Custom retry logic
            if (error instanceof Error) {
                const errorCode = (error as any).code;

                // Retry on network errors
                if (errorCode === "ECONNRESET" || errorCode === "ETIMEDOUT") {
                    return true;
                }
            }

            // Retry on specific HTTP status codes
            if ((error as any).statusCode && [429, 503].includes((error as any).statusCode)) {
                return true;
            }

            return false;
        },
    },
});
```

## Retry Configuration Options [#retry-configuration-options]

```typescript
interface RetryConfig {
    /** Maximum number of retry attempts (default: 3) */
    maxRetries?: number;

    /** Initial delay in milliseconds before first retry (default: 1000) */
    initialDelay?: number;

    /** Multiplier for exponential backoff (default: 2) */
    backoffMultiplier?: number;

    /** Maximum delay in milliseconds between retries (default: 30000) */
    maxDelay?: number;

    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
    retryableStatusCodes?: number[];

    /** Custom function to determine if an error should be retried */
    shouldRetry?: (error: unknown) => boolean;

    /** Custom function to calculate delay for a specific retry attempt */
    calculateDelay?: (attempt: number, error: unknown) => number | undefined;

    /**
     * Fire-and-forget hook invoked before each retry attempt's backoff sleep. `attempt` is 1-based
     * (1 = first retry, after the initial call failed). Exceptions thrown by this callback are
     * swallowed so an observability hook can never fail the underlying operation.
     */
    onRetry?: (attempt: number, error: unknown) => void;
}
```

## Per-call retries via the `Files` facade [#per-call-retries-via-the-files-facade]

Every `Files` method accepts `retries` per call via `OperationOptions`. Facade-wide defaults set on the constructor are merged in; per-call wins.

```typescript
import { Files } from "@visulima/storage";

const files = new Files({
    adapter,
    defaults: { retries: { maxRetries: 5, initialDelay: 500 } },
});

// Use the facade defaults.
await files.download("k.txt");

// Override for a single call — accepts either a plain number or a full RetryConfig.
await files.download("flaky.txt", { retries: 1 });
await files.download("critical.txt", {
    retries: {
        maxRetries: 10,
        shouldRetry: (error) => isMyCustomTransient(error),
    },
});
```

## Observing retries with the `onRetry` hook [#observing-retries-with-the-onretry-hook]

The `Files` facade wires its `hooks.onRetry` through `RetryConfig.onRetry` so retry events surface with facade-level operation context (`type`, `key`, `from`/`to`):

```typescript
const files = new Files({
    adapter,
    defaults: { retries: { maxRetries: 5 } },
    hooks: {
        onRetry: ({ type, key, attempt, error }) => {
            log.warn(`${type} ${key} retry ${attempt}: ${error.message}`);
        },
    },
});
```

If the caller also passes a custom `retries.onRetry`, both callbacks fire — user-provided first, facade hook second — and both are wrapped in try/catch.

## Using Retry Utilities Directly [#using-retry-utilities-directly]

You can also use the retry utilities for custom operations:

```typescript
import { retry, createRetryWrapper, isRetryableError } from "@visulima/storage";

// One-off retry
const result = await retry(
    async () => {
        // Your operation here
        return await someOperation();
    },
    {
        maxRetries: 3,
        initialDelay: 1000,
    },
);

// Create a reusable retry wrapper
const retryWrapper = createRetryWrapper({
    maxRetries: 5,
    initialDelay: 2000,
});

const result = await retryWrapper(async () => {
    return await someOperation();
});

// Check if an error is retryable
if (isRetryableError(error)) {
    // Handle retryable error
}
```

## Supported Error Types [#supported-error-types]

The retry mechanism automatically handles:

* **Network errors**: `ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`, `ECONNREFUSED`, `EAI_AGAIN`
* **AWS SDK errors**: Server faults, retryable status codes, SDK v2/v3 error formats
* **Azure Storage errors**: HTTP status codes, network connection issues
* **HTTP errors**: 408 (Request Timeout), 429 (Too Many Requests), 5xx (Server Errors)

## Examples by Storage Backend [#examples-by-storage-backend]

### AWS S3 [#aws-s3]

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
    retryConfig: {
        maxRetries: 3,
        // AWS SDK errors are automatically detected
    },
});
```

### Azure Blob Storage [#azure-blob-storage]

```typescript
import { AzureStorage } from "@visulima/storage/provider/azure";

const storage = new AzureStorage({
    containerName: "uploads",
    accountName: "myaccount",
    accountKey: "mykey",
    retryConfig: {
        maxRetries: 5,
        initialDelay: 2000,
    },
});
```

### Google Cloud Storage [#google-cloud-storage]

GCS already has built-in retry support via `gaxios`. The retry mechanism works alongside GCS's native retry logic:

```typescript
import { GCStorage } from "@visulima/storage/provider/gcs";

const storage = new GCStorage({
    bucket: "my-bucket",
    projectId: "my-project",
    retryConfig: {
        maxRetries: 3,
        // Works with GCS's existing retryOptions
    },
});
```

### Vercel Blob [#vercel-blob]

```typescript
import { VercelBlobStorage } from "@visulima/storage/provider/vercel";

const storage = new VercelBlobStorage({
    token: process.env.BLOB_READ_WRITE_TOKEN,
    retryConfig: {
        maxRetries: 3,
        retryableStatusCodes: [408, 429, 500, 502, 503, 504],
    },
});
```

### Netlify Blob [#netlify-blob]

```typescript
import { NetlifyBlobStorage } from "@visulima/storage/provider/netlify";

const storage = new NetlifyBlobStorage({
    storeName: "uploads",
    retryConfig: {
        maxRetries: 3,
    },
});
```

## Best Practices [#best-practices]

1. **Configure appropriate retry limits** - Too many retries can cause unnecessary delays
2. **Use exponential backoff** - Prevents overwhelming the service during outages
3. **Monitor retry patterns** - Log retry attempts to identify persistent issues
4. **Customize per operation** - Some operations may need different retry strategies
5. **Handle non-retryable errors** - Distinguish between transient and permanent failures


# Alibaba Oss (/docs/packages/storage/services/alibaba-oss)



# Alibaba Cloud OSS [#alibaba-cloud-oss]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Alibaba Cloud Object Storage Service (OSS) is an S3-compatible object storage service. It is accessed through the S3-compatible endpoint, so it works with `S3Storage` plus the bundled `alibaba` client preset, which derives the endpoint from the region code.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Alibaba OSS is S3-compatible, so use `S3Storage` with the `alibaba` client preset:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { alibaba } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = alibaba({
    accessKeyId: process.env.ALIBABA_ACCESS_KEY_ID!,
    secretAccessKey: process.env.ALIBABA_ACCESS_KEY_SECRET!,
    region: process.env.ALIBABA_REGION || "cn-hangzhou",
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

The endpoint defaults to `https://s3.oss-${region}.aliyuncs.com` with virtual-hosted-style addressing. Pass `endpoint` (or set `ALIBABA_ENDPOINT`) to override it — for example, when using an internal or accelerated endpoint.

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.ALIBABA_ACCESS_KEY_ID = "your-access-key";
process.env.ALIBABA_ACCESS_KEY_SECRET = "your-secret-key";
process.env.ALIBABA_REGION = "cn-hangzhou";

const clientConfig = alibaba(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

The `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` variables are also accepted as fallbacks. The region is **not** read from `AWS_REGION` — it is part of the endpoint hostname, and `AWS_REGION` is commonly set to an AWS region in dev/CI, which would silently produce a broken endpoint. Use `ALIBABA_REGION` (or pass `region`).

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = alibaba({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    region: "cn-hangzhou",
});
```

## Regions [#regions]

Common Alibaba OSS regions:

* `cn-hangzhou` - China (Hangzhou)
* `cn-shanghai` - China (Shanghai)
* `cn-beijing` - China (Beijing)
* `ap-southeast-1` - Asia Pacific SE (Singapore)
* `us-east-1` - US East (Virginia)
* `eu-central-1` - EU Central (Frankfurt)

## Features [#features]

* **S3-Compatible**: Works through the S3-compatible OSS endpoint
* **Global Regions**: Data centers across China and worldwide
* **Lifecycle Management**: Automatic tiering and expiration policies
* **Presigned URLs**: Direct browser uploads and downloads

## Best Practices [#best-practices]

1. **Set `ALIBABA_REGION` explicitly** - it drives the endpoint hostname; never rely on `AWS_REGION`
2. **Choose the closest region** - reduce latency for your users
3. **Use lifecycle policies** - automatically transition or expire objects
4. **Configure CORS** - set up CORS for browser-based uploads
5. **Use a separate metafiles bucket** - keep upload metadata isolated for resumable uploads


# Amazon S3 (/docs/packages/storage/services/amazon-s3)



# Amazon S3 [#amazon-s3]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server (TUS / multipart / REST handlers, lifecycle hooks, transformers).

## Overview [#overview]

Amazon S3 is a web service interface that you can use to store and retrieve any amount of data, at any time, from anywhere on the web. You can accomplish these tasks using the simple web services interface that Amazon S3 provides. Amazon S3 is designed to make web-scale computing easier for developers and works seamlessly with Visulima upload's image transformation features.

## When to Use AWS S3 vs AWS Light Storage [#when-to-use-aws-s3-vs-aws-light-storage]

### Use AWS S3 Storage When: [#use-aws-s3-storage-when]

* ✅ **Node.js Environment**: Running in traditional Node.js servers or applications
* ✅ **Full AWS SDK Features**: Need advanced AWS SDK features and integrations
* ✅ **Better Presigned URL Support**: Require robust presigned URL generation
* ✅ **AWS Ecosystem Integration**: Need to integrate with other AWS services
* ✅ **Production Node.js Apps**: Standard Node.js backend applications

### Use AWS Light Storage When: [#use-aws-light-storage-when]

* ✅ **Worker Environments**: Cloudflare Workers, Web Workers, or edge runtimes
* ✅ **Bundle Size Matters**: Need a lightweight solution (\~6.4 KB vs \~2MB)
* ✅ **No Node.js Available**: Running in browser or edge environments without Node.js
* ✅ **Simple S3 Operations**: Basic upload, download, delete operations are sufficient

> **Note**: If you're unsure, start with AWS Light Storage for worker/edge environments, or AWS S3 Storage for Node.js environments. Both provide the same core S3 functionality.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

```sh
yarn add @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

```sh
pnpm add @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

```ts
import { LRUCache } from "lru-cache";
import { S3Storage } from "@visulima/storage/provider/aws";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new S3Storage({
    bucket: "upload",
    region: "us-east-1",
    credentials: {
        accessKeyId: "test",
        secretAccessKey: "test",
    },
    expiration: { maxAge: "1h", purgeInterval: "15min" },
    logger: console,
});

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

// Initialize image transformer for on-demand transformations
const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});

// Upload a file
const file = await storage.put(fileBuffer, { filename: "image.jpg" });

// Transform the uploaded image
const thumbnail = await imageTransformer.resize(file.id, {
    width: 300,
    height: 200,
    fit: "cover",
    quality: 80,
});
```

## Image Transformations [#image-transformations]

Amazon S3 integrates seamlessly with Visulima upload's image transformation capabilities:

```ts
// Resize images on-demand
const resized = await imageTransformer.resize("file-id", {
    width: 800,
    height: 600,
    fit: "cover",
});

// Convert formats for better compression
const webp = await imageTransformer.transform("file-id", {
    format: "webp",
    quality: 85,
    lossless: false,
});

// Crop images
const cropped = await imageTransformer.crop("file-id", {
    width: 400,
    height: 300,
    left: 100,
    top: 50,
});
```

## Configuration [#configuration]

| Name        | Type   | Description                                  | Default |
| :---------- | :----- | :------------------------------------------- | :------ |
| bucket      | string | The name of the bucket to use.               |         |
| region      | string | The region of the bucket.                    |         |
| credentials | object | The credentials to use to access the bucket. |         |
| expiration  | object | The expiration configuration.                |         |
| logger      | Logger | The logger to use                            |         |

## Performance Considerations [#performance-considerations]

1. **CloudFront Integration**: Use Amazon CloudFront as a CDN for faster global delivery
2. **Caching**: Enable transformation caching to reduce processing costs
3. **Storage Classes**: Use appropriate S3 storage classes for transformed images
4. **Presigned URLs**: Generate presigned URLs for secure temporary access

## CloudFront Integration [#cloudfront-integration]

For optimal performance, integrate with Amazon CloudFront:

```ts
// Use CloudFront distribution for transformed images
const cloudFrontUrl = `https://your-distribution.cloudfront.net/files/${fileId}?width=500&height=500&fit=cover&quality=80`;

// Or generate presigned URLs for private buckets
const presignedUrl = await storage.getPresignedUrl(fileId, {
    expires: Date.now() + 3600000, // 1 hour
    transform: {
        width: 500,
        height: 500,
        fit: "cover",
        format: "webp",
    },
});
```

## Cost Optimization [#cost-optimization]

1. **Intelligent Tiering**: Use S3 Intelligent Tiering for automatic cost optimization
2. **Lifecycle Policies**: Automatically move old transformations to cheaper storage
3. **Request Optimization**: Cache transformations to reduce compute costs
4. **Compression**: Use efficient formats like WebP/AVIF to reduce storage costs


# Aws Light (/docs/packages/storage/services/aws-light)



# AWS Light Storage [#aws-light-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

AWS Light Storage is a lightweight S3-compatible storage implementation optimized for worker environments. It uses `aws4fetch` instead of the full AWS SDK, making it perfect for Cloudflare Workers, Web Workers, and other edge runtime environments where the AWS SDK cannot run.

## Key Features [#key-features]

* **Worker Compatible**: Works in Cloudflare Workers, Web Workers, and edge runtimes
* **Lightweight**: Uses `aws4fetch` (\~6.4 KB) instead of the full AWS SDK
* **S3-Compatible**: Full S3 API compatibility for multipart uploads, presigned URLs, and more
* **No Node.js Dependencies**: Uses standard Web APIs (`fetch`, `SubtleCrypto`)

## Installation [#installation]

```sh
npm install aws4fetch
```

```sh
yarn add aws4fetch
```

```sh
pnpm add aws4fetch
```

## Usage [#usage]

### Basic Usage [#basic-usage]

```typescript
import { AwsLightStorage } from "@visulima/storage/provider/aws-light";

const storage = new AwsLightStorage({
    bucket: "my-bucket",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
});
```

### Cloudflare Workers [#cloudflare-workers]

AWS Light Storage is perfect for Cloudflare Workers:

```typescript
export default {
    async fetch(request: Request, env: any): Promise<Response> {
        const storage = new AwsLightStorage({
            bucket: env.S3_BUCKET,
            region: env.AWS_REGION,
            accessKeyId: env.AWS_ACCESS_KEY_ID,
            secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
        });

        // Use storage...
        const file = await storage.create({
            contentType: "image/jpeg",
            size: 1024,
        });

        return new Response(JSON.stringify(file));
    },
};
```

### Web Workers [#web-workers]

```typescript
// worker.ts
import { AwsLightStorage } from "@visulima/storage/provider/aws-light";

self.onmessage = async (event) => {
    const storage = new AwsLightStorage({
        bucket: "my-bucket",
        region: "us-east-1",
        accessKeyId: event.data.accessKeyId,
        secretAccessKey: event.data.secretAccessKey,
    });

    const file = await storage.create(event.data.fileConfig);
    self.postMessage({ file });
};
```

### Custom Endpoint (S3-Compatible Services) [#custom-endpoint-s3-compatible-services]

AWS Light Storage works with any S3-compatible service:

```typescript
import { AwsLightStorage } from "@visulima/storage/provider/aws-light";

// Cloudflare R2
const r2Storage = new AwsLightStorage({
    bucket: "my-r2-bucket",
    region: "auto",
    endpoint: "https://my-account-id.r2.cloudflarestorage.com",
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
});

// DigitalOcean Spaces
const spacesStorage = new AwsLightStorage({
    bucket: "my-space",
    region: "nyc3",
    endpoint: "https://nyc3.digitaloceanspaces.com",
    accessKeyId: process.env.DO_SPACES_KEY!,
    secretAccessKey: process.env.DO_SPACES_SECRET!,
});

// MinIO
const minioStorage = new AwsLightStorage({
    bucket: "my-bucket",
    region: "us-east-1",
    endpoint: "https://minio.example.com",
    accessKeyId: process.env.MINIO_ACCESS_KEY!,
    secretAccessKey: process.env.MINIO_SECRET_KEY!,
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.S3_BUCKET = "my-bucket";
process.env.S3_REGION = "us-east-1";
process.env.AWS_ACCESS_KEY_ID = "your-access-key";
process.env.AWS_SECRET_ACCESS_KEY = "your-secret-key";

const storage = new AwsLightStorage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION!,
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
});
```

### Configuration Options [#configuration-options]

| Name               | Type           | Description                                             | Default |
| :----------------- | :------------- | :------------------------------------------------------ | :------ |
| bucket             | string         | The name of the S3 bucket to use.                       |         |
| region             | string         | The AWS region of the bucket.                           |         |
| accessKeyId        | string         | AWS access key ID.                                      |         |
| secretAccessKey    | string         | AWS secret access key.                                  |         |
| sessionToken       | string         | Optional AWS session token (for temporary credentials). |         |
| endpoint           | string         | Custom S3 endpoint (for S3-compatible services).        | Auto    |
| service            | string         | AWS service name (usually "s3").                        | "s3"    |
| clientDirectUpload | boolean        | Enable client-side direct upload with presigned URLs.   | false   |
| partSize           | number\|string | Part size for multipart uploads.                        | "16MB"  |
| expiration         | object         | File expiration configuration.                          |         |
| logger             | Logger         | Logger instance for debugging.                          |         |

## When to Use AWS Light vs AWS S3 Storage [#when-to-use-aws-light-vs-aws-s3-storage]

### Use AWS Light Storage When: [#use-aws-light-storage-when]

* ✅ **Running in Worker Environments**: Cloudflare Workers, Web Workers, or edge runtimes
* ✅ **Bundle Size Matters**: Need a lightweight solution (\~6.4 KB vs \~2MB)
* ✅ **No Node.js Available**: Running in browser or edge environments without Node.js
* ✅ **Simple S3 Operations**: Basic upload, download, delete operations are sufficient
* ✅ **S3-Compatible Services**: Using R2, DigitalOcean Spaces, MinIO, or other S3-compatible services

### Use AWS S3 Storage When: [#use-aws-s3-storage-when]

* ✅ **Node.js Environment**: Running in traditional Node.js servers or applications
* ✅ **Full AWS SDK Features**: Need advanced AWS SDK features and integrations
* ✅ **Better Presigned URL Support**: Require robust presigned URL generation
* ✅ **AWS Ecosystem Integration**: Need to integrate with other AWS services
* ✅ **Production Node.js Apps**: Standard Node.js backend applications

### Quick Decision Guide [#quick-decision-guide]

```
┌─────────────────────────────────────────────────────────┐
│ Are you running in a worker/edge environment?           │
│   ├─ YES → Use AWS Light Storage                        │
│   └─ NO → Continue...                                    │
│                                                          │
│ Is bundle size critical?                                │
│   ├─ YES → Use AWS Light Storage                        │
│   └─ NO → Continue...                                   │
│                                                          │
│ Do you need full AWS SDK features?                      │
│   ├─ YES → Use AWS S3 Storage                           │
│   └─ NO → Use AWS Light Storage                         │
└─────────────────────────────────────────────────────────┘
```

## Comparison with S3Storage [#comparison-with-s3storage]

| Feature              | S3Storage       | AwsLightStorage      |
| :------------------- | :-------------- | :------------------- |
| Worker Support       | ❌ No            | ✅ Yes                |
| Bundle Size          | \~2MB (AWS SDK) | \~6.4 KB (aws4fetch) |
| Node.js Required     | ✅ Yes           | ❌ No                 |
| Presigned URLs       | ✅ Full Support  | ⚠️ Limited           |
| All S3 Features      | ✅ Yes           | ✅ Yes                |
| Edge Runtime Support | ❌ No            | ✅ Yes                |

## Limitations [#limitations]

1. **Presigned URLs**: Full presigned URL generation requires implementing AWS Signature Version 4 query string authentication. Currently, URLs are constructed but signing happens on-demand.

2. **File Type Detection**: File type detection from streams may not work in all worker environments due to Node.js stream dependencies.

## Best Practices [#best-practices]

1. **Use in Workers**: Perfect for Cloudflare Workers, Web Workers, and edge runtimes
2. **Environment Variables**: Store credentials securely using environment variables
3. **Error Handling**: Implement proper error handling for network failures
4. **Retry Logic**: Configure retry logic for transient failures
5. **Monitor Usage**: Track storage usage and costs in your AWS/S3 dashboard

## Examples [#examples]

### Upload a File [#upload-a-file]

```typescript
const file = await storage.create({
    contentType: "image/jpeg",
    size: 1024 * 1024, // 1MB
    metadata: {
        userId: "123",
        category: "profile",
    },
});

await storage.write({
    id: file.id,
    body: imageBuffer,
    contentLength: imageBuffer.length,
    start: 0,
});
```

### Download a File [#download-a-file]

```typescript
const fileData = await storage.get({ id: "file-id" });
console.log(fileData.content); // Buffer
console.log(fileData.contentType); // "image/jpeg"
```

### Stream a File [#stream-a-file]

```typescript
const { stream, size, headers } = await storage.getStream({ id: "file-id" });
// stream is a Node.js Readable stream
```

### Delete a File [#delete-a-file]

```typescript
await storage.delete({ id: "file-id" });
```

## Migration from S3Storage [#migration-from-s3storage]

If you're migrating from `S3Storage` to `AwsLightStorage`:

1. Install `aws4fetch` instead of `@aws-sdk/client-s3`
2. Update imports: `S3Storage` → `AwsLightStorage`
3. Update configuration: Remove `credentials` object, use `accessKeyId` and `secretAccessKey` directly
4. Test presigned URL functionality if using `clientDirectUpload`

```typescript
// Before (S3Storage)
import { S3Storage } from "@visulima/storage/provider/aws";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
    credentials: {
        accessKeyId: "...",
        secretAccessKey: "...",
    },
});

// After (AwsLightStorage)
import { AwsLightStorage } from "@visulima/storage/provider/aws-light";

const storage = new AwsLightStorage({
    bucket: "my-bucket",
    region: "us-east-1",
    accessKeyId: "...",
    secretAccessKey: "...",
});
```


# Azure (/docs/packages/storage/services/azure)



# Azure Blob Storage [#azure-blob-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Azure Blob Storage is Microsoft's object storage solution for the cloud. Blob Storage is optimized for storing massive amounts of unstructured data, such as text or binary data. Blob Storage is ideal for serving images with on-demand transformations and works seamlessly with Visulima upload's image processing capabilities.

## Installation [#installation]

```sh
npm install @azure/storage-blob
```

```sh
yarn add @azure/storage-blob
```

```sh
pnpm add @azure/storage-blob
```

## Usage [#usage]

```ts
import { LRUCache } from "lru-cache";
import { AzureStorage } from "@visulima/storage/provider/azure";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new AzureStorage({
    containerName: "upload",
    connectionString: "your config",
    maxUploadSize: "1GB",
    logger: console,
});

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

// Initialize image transformer for on-demand transformations
const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});

// Upload a file
const file = await storage.put(fileBuffer, { filename: "image.jpg" });

// Transform the uploaded image
const thumbnail = await imageTransformer.resize(file.id, {
    width: 300,
    height: 200,
    fit: "cover",
    quality: 80,
});
```

## Image Transformations [#image-transformations]

Azure Blob Storage integrates seamlessly with Visulima upload's image transformation features:

```ts
// Resize images on-demand
const resized = await imageTransformer.resize("file-id", {
    width: 800,
    height: 600,
    fit: "cover",
});

// Convert formats for better performance
const webp = await imageTransformer.transform("file-id", {
    format: "webp",
    quality: 85,
});

// Crop images
const cropped = await imageTransformer.crop("file-id", {
    width: 400,
    height: 300,
    left: 100,
    top: 50,
});
```

## Configuration [#configuration]

| Name             | Type   | Description                                              | Default |
| :--------------- | :----- | :------------------------------------------------------- | :------ |
| containerName    | string | The name of the container to use                         |         |
| connectionString | string | The connection string to use to connect to Azure Storage |         |
| maxUploadSize    | string | The maximum size of the file to upload                   |         |
| logger           | Logger | The logger to use                                        |         |

## Performance Considerations [#performance-considerations]

1. **CDN Integration**: Use Azure CDN for global content delivery
2. **Caching**: Enable transformation caching to reduce compute costs
3. **Access Tiers**: Choose appropriate access tiers (Hot, Cool, Archive)
4. **Shared Access Signatures**: Use SAS tokens for secure temporary access

## CDN Integration [#cdn-integration]

For optimal performance, integrate with Azure CDN:

```ts
// Use Azure CDN for transformed images
const cdnUrl = `https://your-cdn.azureedge.net/upload/${fileId}?width=500&height=500&fit=cover&quality=80`;

// Or generate SAS URLs for private containers
const sasUrl = await storage.getSasUrl(fileId, {
    expires: Date.now() + 3600000, // 1 hour
    permissions: "r", // read-only
    transform: {
        width: 500,
        height: 500,
        fit: "cover",
        format: "webp",
    },
});
```

## Cost Optimization [#cost-optimization]

1. **Lifecycle Management**: Automatically move old transformations to cooler tiers
2. **Access Patterns**: Use appropriate access tiers based on transformation frequency
3. **Caching Strategy**: Cache frequently requested transformations
4. **Compression**: Use efficient formats to reduce storage and bandwidth costs


# Backblaze B2 (/docs/packages/storage/services/backblaze-b2)



# Backblaze B2 [#backblaze-b2]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Backblaze B2 is an S3-compatible cloud storage service with competitive pricing. It provides reliable, cost-effective storage for applications.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Backblaze B2 is S3-compatible, so use the S3Storage with B2 endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { backblaze } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = backblaze({
    applicationKeyId: process.env.B2_APP_KEY_ID!,
    applicationKey: process.env.B2_APP_KEY!,
    region: process.env.B2_REGION || "us-west-000",
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.B2_APP_KEY_ID = "your-application-key-id";
process.env.B2_APP_KEY = "your-application-key";
process.env.B2_REGION = "us-west-000";

const clientConfig = backblaze(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = backblaze({
    applicationKeyId: "your-application-key-id",
    applicationKey: "your-application-key",
    region: "us-west-000",
});
```

## Regions [#regions]

Backblaze B2 regions:

* `us-west-000` - US West
* `us-west-001` - US West (alternate)
* `us-west-002` - US West (alternate)
* `eu-central-003` - EU Central

## Features [#features]

* **Cost-Effective**: Competitive pricing for storage and egress
* **S3-Compatible**: Full S3 API compatibility
* **Reliable**: High durability and availability
* **Scalable**: Unlimited storage capacity

## Best Practices [#best-practices]

1. **Choose appropriate region** - Select region closest to your users
2. **Monitor costs** - Track storage and egress costs
3. **Use lifecycle policies** - Automatically manage file lifecycle
4. **Configure CORS** - Set up CORS for web applications
5. **Enable versioning** - Use B2 versioning for important files


# Box (/docs/packages/storage/services/box)



# Box [#box]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage, OAuth wiring, and Box-specific key-to-fileId resolution.

## Overview [#overview]

The Box adapter wraps `box-typescript-sdk-gen`'s `BoxClient` with the `BaseStorage` contract. It supports developer tokens, OAuth refresh tokens (handled natively by the SDK's `BoxOAuth`), or a pre-built client. Operations are rooted at a configurable `rootFolderId`, and the adapter resolves virtual keys to Box file ids on every read.

## Installation [#installation]

```sh
npm install box-typescript-sdk-gen
```

```sh
yarn add box-typescript-sdk-gen
```

```sh
pnpm add box-typescript-sdk-gen
```

## Usage [#usage]

```ts
import BoxStorage from "@visulima/storage/provider/box";

const storage = new BoxStorage({
    developerToken: process.env.BOX_DEVELOPER_TOKEN!,
    rootFolderId: "0", // "0" is the All Files root
});
```

## Configuration [#configuration]

### Auth precedence [#auth-precedence]

1. `client` — pre-built `BoxClient`.
2. `developerToken` — single-token dev/test auth.
3. `oauth` — `{ clientId, clientSecret, refreshToken }` for OAuth refresh-token flow (handled by `BoxOAuth`).
4. Env fallback: `BOX_DEVELOPER_TOKEN`.

```ts
const storage = new BoxStorage({
    oauth: {
        clientId: process.env.BOX_CLIENT_ID!,
        clientSecret: process.env.BOX_CLIENT_SECRET!,
        refreshToken: process.env.BOX_REFRESH_TOKEN!,
    },
});
```

### Root folder [#root-folder]

```ts
new BoxStorage({
    developerToken: process.env.BOX_DEVELOPER_TOKEN!,
    rootFolderId: "1234567890", // pre-existing Box folder id
});
```

All uploads land in this folder; sub-paths in virtual keys are flattened into the file name. To preserve hierarchy, drop to `storage.raw` and use the Box folders API directly.

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

Creates (or returns the existing) shared link via `createSharedLinkForFile` / `getSharedLinkForFile`. Recovers from "shared link already exists" by reading back the current one. `responseContentDisposition` is not supported.

```ts
const url = await storage.getReadUrl("avatar.png");
// → https://app.box.com/s/<token>
```

### `getUploadUrl(key)` [#getuploadurlkey]

Throws `METHOD_NOT_ALLOWED`. Box doesn't expose presigned PUT URLs — uploads go through the SDK or the `POST /files/content` REST endpoint with `Authorization: Bearer …`.

## Features [#features]

* **Three auth strategies** — developer token, OAuth (BoxOAuth), or bring-your-own client.
* **Shared-link conflict recovery** — re-uses the existing public link when create fails with "already exists".
* **404 / not-found tolerance** — `delete()` is idempotent against Box's standard not-found responses.
* **Native token refresh** — OAuth flow delegates token caching/refresh to the Box SDK, no per-request plumbing.

## Limitations [#limitations]

* Single-shot writes only — for files larger than 50 MB use `storage.raw.uploads.startCreateFileUploadSessionForExistingFile`.
* No native presigned upload URLs.
* Sub-paths in keys are not converted to folder hierarchy — all files land in `rootFolderId`.


# Bun S3 (/docs/packages/storage/services/bun-s3)



# Bun S3 [#bun-s3]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage and Bun-specific limitations (no resumable multipart, client-side copy).

## Overview [#overview]

The Bun S3 adapter is backed by the native [`Bun.S3Client`](https://bun.sh/docs/api/s3) instead of the AWS SDK. Use it when you are already running on Bun and want to skip the AWS SDK dependency — the runtime ships its own zero-dependency S3 client.

It works against any S3-compatible backend (AWS S3, Cloudflare R2, MinIO, Tigris, Wasabi, Backblaze B2, …) by pointing `endpoint` at the provider. For Node or edge runtimes use the [`aws`](/docs/packages/storage/services/amazon-s3) or [`aws-light`](/docs/packages/storage/services/aws-light) provider instead — this adapter requires the Bun runtime (or an injected client).

## Usage [#usage]

```ts
import { BunS3Storage } from "@visulima/storage/provider/bun-s3";

const storage = new BunS3Storage({
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION,
    // endpoint: "https://<account>.r2.cloudflarestorage.com", // for R2/MinIO/etc.
});
```

Omitted credential fields fall back to Bun's own environment resolution: `S3_ACCESS_KEY_ID` then `AWS_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` then `AWS_SECRET_ACCESS_KEY`, `S3_REGION` then `AWS_REGION`, `S3_BUCKET` then `AWS_BUCKET`, `S3_ENDPOINT` then `AWS_ENDPOINT`.

## Configuration [#configuration]

### Credentials [#credentials]

| Option            | Env (Bun resolution)                             |
| ----------------- | ------------------------------------------------ |
| `accessKeyId`     | `S3_ACCESS_KEY_ID` → `AWS_ACCESS_KEY_ID`         |
| `secretAccessKey` | `S3_SECRET_ACCESS_KEY` → `AWS_SECRET_ACCESS_KEY` |
| `region`          | `S3_REGION` → `AWS_REGION`                       |
| `bucket`          | `S3_BUCKET` → `AWS_BUCKET`                       |
| `endpoint`        | `S3_ENDPOINT` → `AWS_ENDPOINT`                   |
| `sessionToken`    | —                                                |

Additional options: `acl` (canned ACL applied to uploads, e.g. `"public-read"`), `virtualHostedStyle` (use `https://<bucket>.<host>/…` addressing), and `metaStorageConfig` (local metafile bookkeeping for the upload lifecycle).

### Pre-built client [#pre-built-client]

```ts
import { S3Client } from "bun";
import { BunS3Storage } from "@visulima/storage/provider/bun-s3";

const client = new S3Client({
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
    bucket: process.env.S3_BUCKET!,
});

const storage = new BunS3Storage({ client });
```

When `client` is passed, the inline credential options (`accessKeyId`, `secretAccessKey`, `region`, `bucket`, `endpoint`, `sessionToken`, `acl`, `virtualHostedStyle`) are ignored. You can also pass the `Bun.s3` singleton. Outside Bun, the constructor throws unless `client` is supplied.

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

Returns a presigned `GET` URL via `Bun.S3Client`. Supports `expiresIn`, `responseContentType` (mapped to Bun's `type`), and `responseContentDisposition` (mapped to `contentDisposition`).

### `getUploadUrl(key, options?)` [#getuploadurlkey-options]

Returns a presigned `PUT` URL. Supports `expiresIn` and `contentType`. A `contentLength` cap **cannot** be enforced — Bun's presign has no max-size policy — and is ignored by design.

## Features [#features]

* **Native single-shot writes** — `write()` uploads the part body in one call; Bun handles large-object chunking internally, so no AWS SDK and no manual multipart wiring.
* **Streaming reads** — `getStream()` returns the object via `S3File.stream()`, bridged to a Node `Readable`.
* **Presigned GET/PUT** — both read and upload URLs are minted directly by the runtime client.
* **Idempotent delete** — `delete()` resolves even when the key (or its metadata) is absent, returning a synthetic deleted file.
* **`raw` escape hatch** — `storage.raw` exposes the underlying `Bun.S3Client` for advanced calls (`list`, `stat`, `presign`, …).

## Limitations [#limitations]

* **No resumable / TUS multipart protocol.** Each `write` uploads the supplied body in one shot. `Bun.S3Client` exposes no low-level multipart primitives (create/upload-part/complete/abort), so resumable uploads are not available — use the [`aws`](/docs/packages/storage/services/amazon-s3) or [`aws-light`](/docs/packages/storage/services/aws-light) provider for those.
* **Client-side `copy()` / `move()`** — implemented as read-then-write; Bun has no server-side `CopyObject`.
* **`getUploadUrl()` cannot enforce `contentLength`** — Bun presign has no max-size policy; the option is ignored.
* **Checksums are not verified** — `Bun.S3Client.write` has no checksum parameter, so a supplied `checksum`/`checksumAlgorithm` is accepted but not forwarded or enforced server-side (an *unsupported* algorithm is still rejected up front).
* **`list()` is single-page** — capped at the requested limit; deep prefix pagination is not surfaced.
* Requires the **Bun runtime** (or an injected `client`). Not usable on Node or edge runtimes.


# Bunny (/docs/packages/storage/services/bunny)



# Bunny Storage [#bunny-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage and Bunny-specific limitations (no presigned PUT, no signed-read URL).

## Overview [#overview]

The Bunny Storage adapter wraps `@bunny.net/storage-sdk`. Writes go through the Storage API with an `AccessKey` header; reads go through `BunnyStorageSDK.file.get(...).data()` for server-side fetches or, when a Pull Zone hostname is configured via `publicBaseUrl`, through that public origin.

Bunny Storage does not expose presigned upload URLs or signed-read URL primitives, so this adapter follows the same pattern as UploadThing: public reads via a configured CDN base URL, server-side writes via the SDK.

## Installation [#installation]

```sh
npm install @bunny.net/storage-sdk
```

```sh
yarn add @bunny.net/storage-sdk
```

```sh
pnpm add @bunny.net/storage-sdk
```

## Usage [#usage]

```ts
import { BunnyStorage } from "@visulima/storage/provider/bunny";

const storage = new BunnyStorage({
    zone: process.env.BUNNY_STORAGE_ZONE!,
    accessKey: process.env.BUNNY_STORAGE_ACCESS_KEY!,
    region: "de", // BunnyStorageSDK.regions.StorageRegion.*
    publicBaseUrl: "https://cdn.example.com",
});
```

## Configuration [#configuration]

### Credentials [#credentials]

| Option      | Env (visulima)             | Env (SDK alias)      |
| ----------- | -------------------------- | -------------------- |
| `zone`      | `BUNNY_STORAGE_ZONE`       | `STORAGE_ZONE`       |
| `accessKey` | `BUNNY_STORAGE_ACCESS_KEY` | `STORAGE_ACCESS_KEY` |
| `region`    | `BUNNY_STORAGE_REGION`     | `STORAGE_REGION`     |

`BUNNY_ACCESS_KEY` is also accepted as an alias for `accessKey`. Region must be one of the values in `BunnyStorageSDK.regions.StorageRegion` (e.g. `"de"`, `"uk"`, `"ny"`, `"la"`, `"sg"`, `"se"`, `"br"`, `"jh"`, `"syd"`).

### Pre-built client [#pre-built-client]

```ts
import * as BunnyStorageSDK from "@bunny.net/storage-sdk";
import { BunnyStorage } from "@visulima/storage/provider/bunny";

const client = BunnyStorageSDK.zone.connect_with_accesskey(
    BunnyStorageSDK.regions.StorageRegion.Falkenstein,
    process.env.BUNNY_STORAGE_ZONE!,
    process.env.BUNNY_STORAGE_ACCESS_KEY!,
);

const storage = new BunnyStorage({
    client,
    publicBaseUrl: "https://cdn.example.com",
});
```

When `client` is passed, `zone`, `accessKey`, and `region` are ignored.

### `publicBaseUrl` [#publicbaseurl]

`getReadUrl()` joins `publicBaseUrl` with the object key. Without `publicBaseUrl`, the adapter throws `METHOD_NOT_ALLOWED` from `getReadUrl()` — the raw Storage API URL requires an `AccessKey` header and cannot be handed out to clients.

Configure a Bunny Pull Zone (or any CDN/proxy fronting the Storage Zone) and pass its hostname:

```ts
new BunnyStorage({
    /* … */
    publicBaseUrl: "https://my-pull-zone.b-cdn.net",
});
```

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

* Returns `${publicBaseUrl}/${key}` when `publicBaseUrl` is set.
* Throws `METHOD_NOT_ALLOWED` when `publicBaseUrl` is unset.
* Throws `METHOD_NOT_ALLOWED` when `responseContentDisposition` is supplied — Bunny Storage and Pull Zone URLs have no equivalent override.
* `expiresIn` is accepted but not consumed by the adapter; downstream Pull-Zone token-signing (if any) is the caller's responsibility.

### `getUploadUrl(key)` [#getuploadurlkey]

Throws `METHOD_NOT_ALLOWED`. Bunny Storage has no presigned PUT primitive — writes must go through the Storage API with an `AccessKey` header. Upload server-side via `storage.write()` or proxy through your application.

## Features [#features]

* **SHA256 checksum hint** — when `part.checksum` is provided with `checksumAlgorithm: "sha256"`, it is forwarded as `sha256Checksum` to the Bunny SDK so the server can verify the upload.
* **Soft delete** — `delete()` swallows `FILE_NOT_FOUND` errors so removing a missing key is idempotent.
* **Public-URL minting** — `getReadUrl()` joins `publicBaseUrl + key` synchronously when a Pull Zone is configured.
* **`raw` escape hatch** — `storage.raw` exposes the connected `StorageZone` for advanced SDK calls (`BunnyStorageSDK.file.list`, etc.).

## Limitations [#limitations]

* No native server-side `copy()` — implemented as download + re-upload.
* No presigned upload URLs (`getUploadUrl()` throws `METHOD_NOT_ALLOWED`).
* No signed-read URLs — `getReadUrl()` requires `publicBaseUrl` and ignores `expiresIn`.
* No `responseContentDisposition` override — Bunny Storage / Pull Zone URLs cannot bind a Content-Disposition response header.
* `list()` paginates client-side over a flat directory listing — large prefixes round-trip the full directory.
* Custom `metadata` and `cacheControl` upload options are not supported (configure cache behavior on the Pull Zone instead).


# Capabilities (/docs/packages/storage/services/capabilities)



# Adapter Capabilities [#adapter-capabilities]

Different storage backends expose different primitives. This page enumerates which features each adapter implements natively, simulates, or rejects — so you can choose the right adapter for your use case without reading source.

Legend:

* ✅ **native** — the underlying SDK / API provides this directly
* 🟡 **partial** — supported with caveats (documented in the adapter's page)
* ❌ **not supported** — the adapter throws `METHOD_NOT_ALLOWED` or `STORAGE_ERROR`
* 🔁 **simulated** — implemented via `download` + reupload or similar fallback

## Read & write URLs [#read--write-urls]

| Adapter        | `getReadUrl()`                                          | `getUploadUrl()`                      |
| -------------- | ------------------------------------------------------- | ------------------------------------- |
| S3 / R2 / etc. | ✅ presigned `GET`                                       | ✅ presigned `PUT`                     |
| S3 (light)     | 🟡 limited (aws4fetch signing)                          | 🟡 limited (aws4fetch signing)        |
| Azure Blob     | ✅ SAS                                                   | ❌                                     |
| GCS            | ✅ V4 signed URL                                         | ❌ (resumable URLs handled internally) |
| Vercel Blob    | ✅ public URL                                            | ❌ (use Vercel client tokens)          |
| Netlify Blobs  | ✅ signed URL                                            | ❌                                     |
| Local (disk)   | 🟡 path-based URL                                       | ❌                                     |
| Dropbox        | ✅ temporary link (≤ 4 h) or public shared link          | ❌                                     |
| Google Drive   | 🟡 only when `publicByDefault: true`                    | ✅ resumable session URL               |
| OneDrive       | ✅ `@microsoft.graph.downloadUrl` or `createLink`        | ✅ `createUploadSession`               |
| Box            | ✅ shared download link                                  | ❌                                     |
| Supabase       | ✅ `createSignedUrl` (≤ 7 d)                             | ✅ `createSignedUploadUrl`             |
| UploadThing    | ✅ CDN URL (public ACL) or `generateSignedURL` (private) | ❌                                     |
| Bunny Storage  | 🟡 via `publicBaseUrl` (Pull Zone)                      | ❌                                     |
| Memory         | 🟡 synthetic `memory://${key}`                          | 🟡 synthetic `memory://${key}`        |

## URL options [#url-options]

| Adapter        | `expiresIn` cap | `responseContentDisposition`                                                |
| -------------- | --------------- | --------------------------------------------------------------------------- |
| S3 / R2 / etc. | 7 d (SigV4 max) | ✅ forwarded as `ResponseContentDisposition`                                 |
| Azure Blob     | none (SAS)      | ✅ via SAS query                                                             |
| GCS            | 7 d             | ✅ `response-content-disposition`                                            |
| Vercel Blob    | n/a (public)    | ❌                                                                           |
| Netlify Blobs  | varies          | ❌                                                                           |
| Local (disk)   | n/a             | ❌                                                                           |
| Dropbox        | 4 h             | ❌ — temporary links have no override                                        |
| Google Drive   | n/a             | ❌ — `webContentLink` has no override                                        |
| OneDrive       | n/a             | ❌ — Graph download URLs have no overrides                                   |
| Box            | n/a             | ❌ — shared-link URLs have no overrides                                      |
| Supabase       | 7 d             | 🟡 mapped to Supabase `download` option (filename round-trips when present) |
| UploadThing    | 7 d             | ❌ — no override on UFS/CDN URLs                                             |
| Bunny Storage  | n/a (public)    | ❌ — no override on Storage / Pull Zone URLs                                 |
| Memory         | n/a             | ❌                                                                           |

## Server-side operations [#server-side-operations]

| Adapter        | `copy()`               | `move()`            | `list()` prefix filter         |
| -------------- | ---------------------- | ------------------- | ------------------------------ |
| S3 / R2 / etc. | ✅ CopyObject           | 🔁 copy + delete    | ✅ `Prefix`                     |
| Azure Blob     | ✅ Copy Blob            | 🔁 copy + delete    | ✅ `prefix`                     |
| GCS            | ✅ copy                 | 🔁 copy + delete    | ✅ `prefix`                     |
| Vercel Blob    | ✅ copy                 | 🔁 copy + delete    | ✅ `prefix`                     |
| Netlify Blobs  | 🔁 copy + delete       | 🔁 copy + delete    | ✅ `prefix`                     |
| Local (disk)   | ✅ fs.copyFile          | ✅ fs.rename         | ✅ recursive scan               |
| Dropbox        | ✅ filesCopyV2          | ✅ filesMoveV2       | 🟡 recursive listing of root   |
| Google Drive   | ✅ files.copy           | 🔁 copy + delete    | 🟡 virtual-key + appProperties |
| OneDrive       | ✅ async copy           | ✅ patch parent      | 🟡 folder root, paginated      |
| Box            | ✅ copyFile             | ✅ updateFile parent | 🟡 folder root, cached IDs     |
| Supabase       | ✅ bucket.copy          | ✅ bucket.move       | ❌ root only (per page limit)   |
| UploadThing    | 🔁 download + reupload | 🔁 copy + delete    | 🟡 client-side prefix filter   |
| Bunny Storage  | 🔁 download + reupload | 🔁 copy + delete    | 🟡 root listing, client-side   |
| Memory         | ✅ Map clone            | ✅ copy + delete     | ✅ in-memory prefix scan        |

## Auth model [#auth-model]

| Adapter        | Auth shapes                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| S3 / R2 / etc. | static / SSO / EC2 / env (AWS SDK credential chain)                                                  |
| Azure Blob     | connection string, account key, SAS token, AAD                                                       |
| GCS            | service-account JSON, ADC, key file, OAuth                                                           |
| Vercel Blob    | OIDC (`VERCEL_OIDC_TOKEN` + `BLOB_STORE_ID`, recommended on Vercel), `BLOB_READ_WRITE_TOKEN`         |
| Netlify Blobs  | env-injected on Netlify, explicit token otherwise                                                    |
| Local (disk)   | filesystem permissions                                                                               |
| Dropbox        | access token, refresh token + app key (+ secret), pre-built `Dropbox`                                |
| Google Drive   | service-account JSON, key file, OAuth (refresh token), JWT, env (`GOOGLE_APPLICATION_CREDENTIALS`)   |
| OneDrive       | static access token, client-credentials (app-only), refresh token + redirect, pre-built Graph client |
| Box            | developer token, OAuth, CCG (enterprise / user), JWT, env                                            |
| Supabase       | service-role key (env or explicit), pre-built `StorageClient`                                        |
| UploadThing    | dashboard token (base64 JSON with `apiKey` + `appId`)                                                |
| Bunny Storage  | zone + access key + region (env or explicit), pre-built `StorageZone`                                |
| Memory         | none (in-process only)                                                                               |

## Error normalization [#error-normalization]

All consumer adapters propagate adapter-native errors today, but the package ships `wrapStorageError` (in `@visulima/storage` → `utils/errors`) to normalize them into a canonical `UploadError` with a stable `ERRORS` code. Wired into HTTP-fetch throws on Google Drive (resumable session) and OneDrive (copy, createUploadSession, monitor, upload-session chunks).

Mapping rule of thumb:

| HTTP status | `ERRORS` code              |
| ----------- | -------------------------- |
| 400         | `BAD_REQUEST`              |
| 401 / 403   | `FORBIDDEN`                |
| 404         | `FILE_NOT_FOUND`           |
| 405         | `METHOD_NOT_ALLOWED`       |
| 409         | `FILE_CONFLICT`            |
| 410         | `GONE`                     |
| 413         | `REQUEST_ENTITY_TOO_LARGE` |
| 415         | `UNSUPPORTED_MEDIA_TYPE`   |
| 422         | `UNPROCESSABLE_ENTITY`     |
| 423         | `FILE_LOCKED`              |
| 429         | `TOO_MANY_REQUESTS`        |
| 503         | `STORAGE_BUSY`             |
| other 5xx   | `STORAGE_ERROR`            |
| other 4xx   | `BAD_REQUEST`              |

The native error is preserved on `UploadError.detail` for callers that need provider-specific shapes.

## When in doubt [#when-in-doubt]

Drop down to the native client via `storage.raw` — every adapter exposes the underlying SDK instance there, so you can bypass the unified contract when a feature isn't in the table above.


# Cloudflare R2 (/docs/packages/storage/services/cloudflare-r2)



# Cloudflare R2 [#cloudflare-r2]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Cloudflare R2 is an S3-compatible object storage service with zero egress fees. It's optimized for edge deployments and works seamlessly with Cloudflare Workers.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Cloudflare R2 is S3-compatible, so use the S3Storage with R2 endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { cloudflare } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = cloudflare({
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    accessKeyId: process.env.CLOUDFLARE_ACCESS_KEY_ID!,
    secretAccessKey: process.env.CLOUDFLARE_SECRET_ACCESS_KEY!,
    jurisdiction: process.env.CLOUDFLARE_JURISDICTION, // Optional
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.CLOUDFLARE_ACCOUNT_ID = "your-account-id";
process.env.CLOUDFLARE_ACCESS_KEY_ID = "your-access-key";
process.env.CLOUDFLARE_SECRET_ACCESS_KEY = "your-secret-key";
process.env.CLOUDFLARE_JURISDICTION = "eu"; // Optional

const clientConfig = cloudflare(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = cloudflare({
    accountId: "your-account-id",
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    jurisdiction: "eu", // Optional: eu, us, etc.
});
```

## Cloudflare Workers [#cloudflare-workers]

R2 works seamlessly with Cloudflare Workers:

```typescript
export default {
    async fetch(request: Request, env: any): Promise<Response> {
        const clientConfig = cloudflare({
            accountId: env.CLOUDFLARE_ACCOUNT_ID,
            accessKeyId: env.CLOUDFLARE_ACCESS_KEY_ID,
            secretAccessKey: env.CLOUDFLARE_SECRET_ACCESS_KEY,
        });

        const storage = new S3Storage({
            bucket: "my-bucket",
            ...clientConfig,
        });

        // Use storage...
        return new Response("OK");
    },
};
```

## Features [#features]

* **Zero Egress Fees**: No charges for data transfer out
* **S3-Compatible**: Full S3 API compatibility
* **Edge Integration**: Works with Cloudflare Workers
* **Global Distribution**: Automatic global CDN

## Best Practices [#best-practices]

1. **Use environment variables** - Store credentials securely
2. **Leverage Workers** - Use R2 with Cloudflare Workers for edge computing
3. **Configure CORS** - Set up CORS for web applications
4. **Monitor usage** - Track storage usage in Cloudflare dashboard
5. **Use custom domains** - Configure custom domains for R2 buckets


# Digital Ocean Spaces (/docs/packages/storage/services/digital-ocean-spaces)



# DigitalOcean Spaces [#digitalocean-spaces]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

DigitalOcean Spaces is an S3-compatible object storage service. It provides a simple, scalable solution for storing and serving files with global CDN integration.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

DigitalOcean Spaces is S3-compatible, so use the S3Storage with Spaces endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { digitalOcean } from "@visulima/storage/provider/aws/s3/clients";

const storage = new S3Storage({
    bucket: "my-space",
    region: "nyc3", // DigitalOcean region
    endpoint: "https://nyc3.digitaloceanspaces.com",
    credentials: {
        accessKeyId: process.env.SPACES_ACCESS_KEY_ID!,
        secretAccessKey: process.env.SPACES_SECRET_ACCESS_KEY!,
    },
});
```

## Configuration [#configuration]

### Using Client Helper [#using-client-helper]

```typescript
import { digitalOcean } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = digitalOcean({
    key: process.env.SPACES_ACCESS_KEY_ID!,
    secret: process.env.SPACES_SECRET_ACCESS_KEY!,
    region: "nyc3",
});

const storage = new S3Storage({
    bucket: "my-space",
    ...clientConfig,
});
```

### Environment Variables [#environment-variables]

```typescript
process.env.SPACES_ACCESS_KEY_ID = "your-access-key";
process.env.SPACES_SECRET_ACCESS_KEY = "your-secret-key";

const storage = new S3Storage({
    bucket: process.env.SPACES_BUCKET,
    region: process.env.SPACES_REGION || "nyc3",
    endpoint: `https://${process.env.SPACES_REGION || "nyc3"}.digitaloceanspaces.com`,
});
```

## Regions [#regions]

Available DigitalOcean Spaces regions:

* `nyc3` - New York 3
* `sfo3` - San Francisco 3
* `ams3` - Amsterdam 3
* `sgp1` - Singapore 1
* `fra1` - Frankfurt 1

## CDN Integration [#cdn-integration]

DigitalOcean Spaces includes built-in CDN:

```typescript
// Files are automatically served via CDN
const file = await storage.get({ id: "file-id" });
// file.uri includes CDN URL
```

## Best Practices [#best-practices]

1. **Choose appropriate region** - Select region closest to your users
2. **Use CDN** - Leverage built-in CDN for global distribution
3. **Configure CORS** - Set up CORS for web applications
4. **Enable versioning** - Use Spaces versioning for important files
5. **Monitor usage** - Track storage and bandwidth in DigitalOcean dashboard


# Dropbox (/docs/packages/storage/services/dropbox)



# Dropbox [#dropbox]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage, OAuth wiring, and Dropbox-specific URL minting.

## Overview [#overview]

The Dropbox adapter wraps the official `dropbox` SDK in the `BaseStorage` contract. It supports static access tokens, refresh-token auth (with built-in caching and 60 s renewal leeway), or a pre-built client for callers that already wire auth themselves. Read URLs are minted from `filesGetTemporaryLink` (4 h cap) or, when `publicByDefault: true`, from a sharing-link with automatic `?dl=0 → ?dl=1` rewriting so the URL serves raw bytes.

## Installation [#installation]

```sh
npm install dropbox
```

```sh
yarn add dropbox
```

```sh
pnpm add dropbox
```

## Usage [#usage]

```ts
import DropboxStorage from "@visulima/storage/provider/dropbox";

const storage = new DropboxStorage({
    refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
    appKey: process.env.DROPBOX_APP_KEY!,
    appSecret: process.env.DROPBOX_APP_SECRET,
    rootFolderPath: "uploads",
});
```

## Configuration [#configuration]

### Static access token [#static-access-token]

Short-lived tokens (the SDK does no refresh on its own):

```ts
const storage = new DropboxStorage({
    accessToken: process.env.DROPBOX_ACCESS_TOKEN!,
});
```

Falls back to `DROPBOX_ACCESS_TOKEN` when no auth option is configured.

### Refresh-token auth [#refresh-token-auth]

Recommended for long-running apps — the adapter caches the access token and refreshes it inside a 60 s leeway window:

```ts
const storage = new DropboxStorage({
    refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
    appKey: process.env.DROPBOX_APP_KEY!,
    appSecret: process.env.DROPBOX_APP_SECRET, // optional for PKCE clients
});
```

### Pre-built client [#pre-built-client]

For callers that have wired their own auth:

```ts
import { Dropbox } from "dropbox";

const storage = new DropboxStorage({
    client: new Dropbox({ accessToken: customToken }),
});
```

### Public links [#public-links]

```ts
const storage = new DropboxStorage({
    refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
    appKey: process.env.DROPBOX_APP_KEY!,
    publicByDefault: true,
});

const url = await storage.getReadUrl("avatar.png");
// → https://www.dropbox.com/s/abc?dl=1 (already rewritten for direct download)
```

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

* Without `publicByDefault`: returns a temporary link via `filesGetTemporaryLink` (max 4 h / 14 400 s).
* With `publicByDefault`: creates a sharing link (recovers from `shared_link_already_exists` by reusing the existing one).
* `responseContentDisposition` is not supported — Dropbox has no content-disposition override.

### `getUploadUrl(key)` [#getuploadurlkey]

Throws `METHOD_NOT_ALLOWED`. Dropbox doesn't expose presigned PUT URLs; uploads happen against the SDK or `https://content.dropboxapi.com/2/files/upload` with `Authorization: Bearer …`.

## Features [#features]

* **Multiple auth strategies** — static, refresh-token, or bring-your-own client.
* **Refresh-token caching** — built-in 60 s leeway, no double-refresh storms.
* **404 / not-found tolerance** — `delete()` is idempotent across both HTTP 404 and Dropbox's tagged `path_lookup/not_found` errors.
* **Shared-link conflict recovery** — re-uses the existing public link when `sharingCreateSharedLinkWithSettings` fails with `shared_link_already_exists`.

## Limitations [#limitations]

* Single-shot uploads only: the adapter buffers the part stream and POSTs in one request. For chunked transfers, drop to `storage.raw` and use the SDK's `filesUploadSession*` methods.
* No native presigned upload URLs.
* Read URLs are capped at the Dropbox 4 h maximum.


# Google Cloud Storage (/docs/packages/storage/services/google-cloud-storage)



# Google Cloud Storage [#google-cloud-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Google Cloud Storage is a unified object storage for developers and enterprises, from live data serving to data analytics/ML to data archiving. It integrates seamlessly with Visulima upload's image transformation capabilities.

## Installation [#installation]

> Note: If you hit this error: "TypeError: Expected signal to be an instanceof AbortSignal" [#784](https://github.com/node-fetch/node-fetch/issues/784).

```sh
npm install @google-cloud/storage gaxios
```

```sh
yarn add @google-cloud/storage gaxios
```

```sh
pnpm add @google-cloud/storage gaxios
```

## Usage [#usage]

```ts
import { LRUCache } from "lru-cache";
import { GCStorage } from "@visulima/storage/provider/gcs";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new GCStorage({
    bucket: "upload",
    projectId: "test",
    maxUploadSize: "1GB",
    logger: console,
    expiration: { maxAge: "1h", purgeInterval: "15min" },
});

// Initialize cache for transformed images
const cache = new LRUCache({
    max: 1000, // Maximum number of cached items
    ttl: 3600000, // 1 hour in milliseconds
});

// Initialize image transformer for on-demand transformations
const imageTransformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});

// Upload a file
const file = await storage.put(fileBuffer, { filename: "image.jpg" });

// Transform the uploaded image
const thumbnail = await imageTransformer.resize(file.id, {
    width: 300,
    height: 200,
    fit: "cover",
    quality: 80,
});
```

## Image Transformations [#image-transformations]

Google Cloud Storage works seamlessly with Visulima upload's image transformation features:

```ts
// Resize images
const resized = await imageTransformer.resize("file-id", {
    width: 800,
    height: 600,
    fit: "cover",
});

// Convert formats
const webp = await imageTransformer.transform("file-id", {
    format: "webp",
    quality: 85,
});

// Crop images
const cropped = await imageTransformer.crop("file-id", {
    width: 400,
    height: 300,
    left: 100,
    top: 50,
});
```

## Configuration [#configuration]

| Name          | Type   | Description                               | Default |
| :------------ | :----- | :---------------------------------------- | :------ |
| bucket        | string | The name of the bucket to use             |         |
| projectId     | string | Google Cloud project ID                   |         |
| maxUploadSize | string | Maximum upload size (e.g., "1GB", "10MB") |         |
| expiration    | object | File expiration configuration             |         |
| logger        | Logger | Logger instance                           |         |

## Performance Considerations [#performance-considerations]

1. **Global CDN**: GCS automatically serves files through Google's global CDN
2. **Caching**: Enable transformation caching to reduce processing overhead
3. **Signed URLs**: Use signed URLs for private files with transformations
4. **Lifecycle Policies**: Configure automatic cleanup of temporary transformations

## Signed URLs with Transformations [#signed-urls-with-transformations]

For private files, combine signed URLs with transformations:

```ts
// Generate a signed URL for a transformed image
const signedUrl = await storage.getSignedUrl(fileId, {
    expires: Date.now() + 3600000, // 1 hour
    transform: {
        width: 500,
        height: 500,
        fit: "cover",
        format: "webp",
    },
});
```


# Google Drive (/docs/packages/storage/services/google-drive)



# Google Drive [#google-drive]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage, OAuth wiring, and Drive-specific key resolution.

## Overview [#overview]

The Google Drive adapter routes virtual keys onto `fileId`s by stamping every upload with an `appProperties.fsdkKey` marker. An LRU cache amortizes the resolve cost. Drive isn't a key-value store, so a virtual key like `"docs/report.pdf"` can technically map to multiple Drive files — the adapter throws if `files.list` returns more than one match, and call sites can drop to `storage.raw` to disambiguate.

## Installation [#installation]

```sh
npm install @googleapis/drive google-auth-library
```

```sh
yarn add @googleapis/drive google-auth-library
```

```sh
pnpm add @googleapis/drive google-auth-library
```

## Usage [#usage]

```ts
import GoogleDriveStorage from "@visulima/storage/provider/google-drive";

const storage = new GoogleDriveStorage({
    credentials: {
        client_email: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
        private_key: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
    },
    driveId: process.env.GOOGLE_DRIVE_ID, // Shared Drive id
    rootFolderId: process.env.GOOGLE_DRIVE_ROOT_FOLDER_ID,
});
```

## Configuration [#configuration]

### Auth precedence [#auth-precedence]

1. `client` — pre-built `drive_v3.Drive` instance.
2. `credentials` — inline service-account credentials (`client_email` + `private_key`).
3. `keyFilename` — path to a service-account JSON file.
4. `oauth` — 3-legged refresh token (`clientId` + `clientSecret` + `refreshToken`).
5. Env fallbacks: `GOOGLE_DRIVE_CLIENT_EMAIL` + `GOOGLE_DRIVE_PRIVATE_KEY`, or `GOOGLE_DRIVE_KEY_FILE`.

`GOOGLE_DRIVE_SUBJECT` enables domain-wide delegation for service-account auth shapes.

### Shared Drive [#shared-drive]

Service accounts have a 15 GB personal quota. Production workloads should target a Shared Drive with the service account added as a member:

```ts
const storage = new GoogleDriveStorage({
    keyFilename: "/etc/secrets/sa.json",
    driveId: "0AAbCdEfG...",
    rootFolderId: "0AAbCdEfG...", // typically the same as driveId
});
```

### OAuth (end-user Drive) [#oauth-end-user-drive]

```ts
const storage = new GoogleDriveStorage({
    oauth: {
        clientId: process.env.GOOGLE_OAUTH_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_OAUTH_CLIENT_SECRET!,
        refreshToken: process.env.GOOGLE_DRIVE_REFRESH_TOKEN!,
    },
});
```

The `google-auth-library` `OAuth2Client` handles refresh natively — no per-request token plumbing in the adapter.

### Public reads [#public-reads]

```ts
const storage = new GoogleDriveStorage({
    credentials: {
        /* … */
    },
    publicByDefault: true,
});

const url = await storage.getReadUrl("file.mp4");
// → https://drive.google.com/uc?export=download&id=<fileId>
```

When `publicByDefault` is set, every `write()` also creates an "anyone with link, reader" permission.

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

Requires `publicByDefault: true` — Drive has no signed-URL primitive. Returns the canonical `https://drive.google.com/uc?export=download&id=<fileId>` URL. `responseContentDisposition` is not supported.

### `getUploadUrl(key, options?)` [#getuploadurlkey-options]

Returns a resumable-upload session URL (`https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable`). Requires `credentials`, `keyFilename`, or `oauth` — the pre-built `client` escape hatch throws because the adapter can't recover the underlying auth handle to mint tokens.

## Features [#features]

* **Virtual-key routing** — uploads stamp `appProperties.fsdkKey`; reads resolve via `files.list`, cached in an LRU.
* **Shared-Drive aware** — sets `supportsAllDrives` / `includeItemsFromAllDrives` on every request.
* **Domain-wide delegation** — pass `subject` (or `GOOGLE_DRIVE_SUBJECT`) to impersonate a workspace user.
* **Resumable uploads** — `getUploadUrl` initiates a session that the caller can drive directly from a browser.

## Limitations [#limitations]

* `getReadUrl()` throws `METHOD_NOT_ALLOWED` without `publicByDefault: true`. Use `get()` for private files.
* Single-shot writes via `write()`; for large files use `getUploadUrl()` and stream against the session URL.
* Duplicate virtual keys (same `fsdkKey` on multiple Drive files) cause `resolve` to throw — surface via `storage.raw` and reconcile manually.


# Hetzner (/docs/packages/storage/services/hetzner)



# Hetzner Object Storage [#hetzner-object-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Hetzner Object Storage is an S3-compatible object storage service hosted in Hetzner data centers (Falkenstein, Nuremberg, Helsinki). It's priced per TB and well-suited for European workloads with data-residency requirements.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Hetzner Object Storage is S3-compatible, so use the S3Storage with the Hetzner endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { hetzner } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = hetzner({
    accessKeyId: process.env.HETZNER_ACCESS_KEY_ID!,
    secretAccessKey: process.env.HETZNER_SECRET_ACCESS_KEY!,
    location: "fsn1", // fsn1 | nbg1 | hel1
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Locations [#locations]

| Code   | Site            |
| ------ | --------------- |
| `fsn1` | Falkenstein, DE |
| `nbg1` | Nuremberg, DE   |
| `hel1` | Helsinki, FI    |

The `location` is used as both the AWS region and the endpoint subdomain (`https://<location>.your-objectstorage.com`).

### Environment Variables [#environment-variables]

```typescript
process.env.HETZNER_ACCESS_KEY_ID = "your-access-key";
process.env.HETZNER_SECRET_ACCESS_KEY = "your-secret-key";
process.env.HETZNER_LOCATION = "fsn1";

const clientConfig = hetzner(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = hetzner({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    location: "nbg1",
});
```

## Features [#features]

* **EU data residency**: All locations are in the EU (Germany, Finland)
* **S3-Compatible**: Works with the AWS S3 SDK and any S3-compatible tooling
* **Flat pricing**: Transparent per-TB pricing with no surprise egress fees on most plans

## Best Practices [#best-practices]

1. **Pin your location** — keep buckets close to your compute to minimize latency
2. **Use environment variables** — never hard-code keys
3. **Configure CORS** in the Hetzner console for browser uploads
4. **Generate scoped keys** per environment / service via the Hetzner console


# Local Disk (/docs/packages/storage/services/local-disk)



# Local Disk Storage [#local-disk-storage]

> **Just need ad-hoc reads / writes?** Wrap `DiskStorage` in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage, with the resumable / multipart / lifecycle features that are unique to the framework surface.

## Overview [#overview]

Local disk storage provides file storage on the local filesystem. It's ideal for development, single-server deployments, and scenarios where cloud storage isn't needed.

## Installation [#installation]

No additional dependencies required - uses Node.js built-in `fs` module.

## Usage [#usage]

```typescript
import { DiskStorage } from "@visulima/storage";

const storage = new DiskStorage({
    directory: "./uploads",
});
```

## Basic Configuration [#basic-configuration]

```typescript
const storage = new DiskStorage({
    directory: "/var/uploads", // Upload directory
});
```

## With Checksum Validation [#with-checksum-validation]

```typescript
import { DiskStorageWithChecksum } from "@visulima/storage/provider/local";

const storage = new DiskStorageWithChecksum({
    checksum: "md5", // Enable MD5 checksum validation (md5 or sha1)
    directory: "/var/uploads",
});
```

## Advanced Configuration [#advanced-configuration]

```typescript
const storage = new DiskStorage({
    assetFolder: "assets",
    directory: "/var/uploads",
    filename: (file, request) => `${Date.now()}-${file.originalName}`,
    expiration: {
        maxAge: "7d",
        purgeInterval: "1h",
    },
    retryConfig: {
        maxRetries: 3,
    },
    cache: new LRUCache({
        max: 1000,
        ttl: 3600000,
    }),
});
```

## Features [#features]

* **Filesystem Storage**: Direct disk I/O operations
* **Checksum Support**: MD5 and SHA1 validation
* **Resumable Uploads**: Continue interrupted uploads
* **Metadata Storage**: JSON-based metadata files
* **Directory Management**: Automatic directory creation
* **File Locking**: Concurrent access protection
* **Cross-platform**: Works on Windows, macOS, Linux

## TTL (Time-to-Live) [#ttl-time-to-live]

Set expiration times for files:

```typescript
const storage = new DiskStorage({
    directory: "./uploads",
    expiration: {
        maxAge: "30d", // Files expire in 30 days
        purgeInterval: "1h", // Check for expired files every hour
        rolling: true, // Extend expiration on access
    },
});
```

## File Naming [#file-naming]

Customize file naming strategy:

```typescript
const storage = new DiskStorage({
    directory: "/var/uploads",
    filename: (file, request) => {
        const timestamp = Date.now();
        const random = Math.random().toString(36).slice(2);
        return `${timestamp}-${random}-${file.originalName}`;
    },
});
```

## Filename Validation [#filename-validation]

DiskStorage automatically applies filesystem-safe filename validation by default, blocking characters that are incompatible with local filesystems (`"`, `*`, `:`, `<`, `>`, `?`, `\`, `|`, `../`, `\0`).

### Default Validation [#default-validation]

```typescript
// DiskStorage uses strict filesystem validation by default
const storage = new DiskStorage({
    directory: "/var/uploads",
    // Automatically validates filenames for filesystem compatibility
});
```

### Custom Validation [#custom-validation]

Override the default validation with your own rules:

```typescript
import { defaultFilesystemFileNameValidation } from "@visulima/storage";

const storage = new DiskStorage({
    directory: "/var/uploads",
    fileNameValidation: (name: string) => {
        // Custom validation logic
        // Return true if valid, false otherwise
        if (name.length < 3 || name.length > 255) {
            return false;
        }

        // Block specific patterns
        if (name.includes("../") || name.includes("\0")) {
            return false;
        }

        // Your custom rules here
        return !name.includes("forbidden");
    },
});
```

### Cloud Storage Validation [#cloud-storage-validation]

Cloud storage platforms (S3, Azure, GCS) use more permissive validation by default, only blocking dangerous patterns like path traversal (`../`) and null bytes (`\0`). They accept most special characters since cloud storage handles URL encoding automatically.

```typescript
import { defaultCloudStorageFileNameValidation } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

const storage = new S3Storage({
    bucket: "my-bucket",
    // Uses permissive validation by default
    // Or explicitly set:
    fileNameValidation: defaultCloudStorageFileNameValidation,
});
```

## Directory Structure [#directory-structure]

```typescript
const storage = new DiskStorage({
    assetFolder: "files", // Subfolder for uploaded files
    directory: "/var/uploads",
});

// Files stored in: /var/uploads/files/
// Metadata in: /var/uploads/.meta/
```

## Concurrent Access [#concurrent-access]

File locking prevents corruption during concurrent access:

```typescript
// Automatic locking during write operations
await storage.write({
    body: data,
    contentLength: data.length,
    id: file.id,
    start: 0,
});
// File is locked during the operation
```

## Error Handling [#error-handling]

Local storage provides clear error messages:

```typescript
try {
    await storage.get({ id: "nonexistent" });
} catch (error) {
    console.log(error.code); // 'ENOENT'
    console.log(error.statusCode); // 404
    console.log(error.message); // 'File not found'
}
```

Common errors:

* `ENOENT` (404): File not found
* `EACCES` (403): Permission denied
* `ENOSPC` (507): Disk full
* `EMFILE` (503): Too many open files

## Performance Optimization [#performance-optimization]

### Large File Handling [#large-file-handling]

```typescript
const storage = new DiskStorage({
    directory: "/var/uploads",
    // Optimize for large files
    highWaterMark: 64 * 1024, // 64KB buffer size
});
```

### Directory Structure [#directory-structure-1]

```typescript
// Use prefixes to avoid too many files per directory
const storage = new DiskStorage({
    directory: "/var/uploads",
    filename: (file) => {
        // Distribute files across subdirectories
        const hash = file.id.slice(0, 2);
        return `${hash}/${file.id}`;
    },
});
```

## Best Practices [#best-practices]

1. **Set appropriate permissions** - Ensure directory is writable
2. **Monitor disk space** - Implement disk space monitoring
3. **Use checksums** - Enable checksum validation for critical files
4. **Configure expiration** - Automatically clean up old files
5. **Backup regularly** - Local storage requires manual backups


# Memory (/docs/packages/storage/services/memory)



# In-Memory Storage [#in-memory-storage]

> **Just need a quick in-memory store for tests?** Wrap `MemoryStorage` in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The adapter implements the full `BaseStorage` surface, so any framework that takes a `BaseStorage` works with it unchanged.

## Overview [#overview]

`MemoryStorage` is a `BaseStorage` adapter backed by an in-process `Map<string, MemoryEntry>`. Nothing is persisted; everything lives in the Node.js heap for the lifetime of the process. It implements the full surface — `create`, `write`, `get`, `getStream`, `head`, `exists`, `delete`, `copy`, `move`, `list`, `getReadUrl`, `getUploadUrl` — and supports ranged reads (`supportsRange: true`).

Use it for:

* **Unit and integration tests** — no temp directories, no cleanup, deterministic state.
* **Ephemeral environments** — preview deployments, smoke tests, ad-hoc scripts.
* **Reference implementation** — the simplest possible adapter to read when authoring your own.

## Installation [#installation]

No additional dependencies — the adapter ships with `@visulima/storage`.

## Usage [#usage]

```typescript
import { Files } from "@visulima/storage";
import MemoryStorage from "@visulima/storage/provider/memory";

const files = new Files({ adapter: new MemoryStorage() });

await files.upload("k.txt", "hello");
const { body } = await files.download("k.txt");
```

## Seed the store [#seed-the-store]

Pass `initial` to pre-populate the backing map with `key → bytes` entries. Each entry creates a `File` metadata record so subsequent `head`, `download`, `delete` look up by the same key.

```typescript
const adapter = new MemoryStorage({
    initial: {
        "users/1.json": '{"id":1}',
        "users/2.json": Buffer.from([0x01, 0x02, 0x03]),
    },
});

const files = new Files({ adapter });

await files.head("users/1.json"); // → FileObject for the seeded entry
```

`initial` values can be `Buffer`, `Uint8Array`, or `string` (UTF-8 encoded).

## Inspecting and resetting [#inspecting-and-resetting]

The adapter exposes its backing `Map` via `raw`, so tests can assert on internal state directly:

```typescript
const adapter = new MemoryStorage();
const files = new Files({ adapter });

await files.upload("k.txt", "x");

expect(adapter.raw.size).toBe(1);
expect(adapter.raw.has("k.txt")).toBe(true);

adapter.raw.clear(); // wipe everything between tests
```

The `Files` facade also forwards `raw`:

```typescript
files.raw.clear();
```

## Sharing metadata between facades [#sharing-metadata-between-facades]

Pass a shared `metaStorage` to point a second `MemoryStorage` instance at the same `MemoryMetaStorage`. Rarely needed, but useful for testing meta-only flows.

```typescript
import MemoryMetaStorage from "@visulima/storage/provider/memory/meta-storage";

const meta = new MemoryMetaStorage();
const a = new MemoryStorage({ metaStorage: meta });
const b = new MemoryStorage({ metaStorage: meta });
```

## Returned URLs [#returned-urls]

`getReadUrl(key)` and `getUploadUrl(key)` return a synthetic `memory://${key}` URL. There's no network behind the scheme — it's a marker that the object is in-process. Consumers that distinguish "private" vs. "public" stores can detect memory by the protocol.

## Caveats [#caveats]

* **Process-local** — the store dies when the process exits. Use `DiskStorage` if you need durability between runs.
* **Unbounded growth** — there is no eviction. Track your test sizes or call `raw.clear()` between cases.
* **Single-process** — fan-out across workers won't see each other's writes. Use `DiskStorage` or a real provider for multi-process tests.

## When in doubt [#when-in-doubt]

The adapter is small (\~370 lines) and a useful reference. Skim `packages/storage/storage/src/storage/memory/memory-storage.ts` to see the minimum surface every adapter must implement.


# Minio (/docs/packages/storage/services/minio)



# MinIO [#minio]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

MinIO is a high-performance, S3-compatible object storage service. It can be self-hosted or used as a managed service, providing S3-compatible APIs.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

MinIO is S3-compatible, so use the S3Storage with MinIO endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { minio } from "@visulima/storage/provider/aws/s3/clients";

const storage = new S3Storage({
    bucket: "my-bucket",
    region: "us-east-1",
    endpoint: "http://localhost:9000", // MinIO endpoint
    credentials: {
        accessKeyId: process.env.MINIO_ACCESS_KEY!,
        secretAccessKey: process.env.MINIO_SECRET_KEY!,
    },
    forcePathStyle: true, // Required for MinIO
});
```

## Configuration [#configuration]

### Using Client Helper [#using-client-helper]

```typescript
import { minio } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = minio({
    accessKeyId: process.env.MINIO_ACCESS_KEY!,
    secretAccessKey: process.env.MINIO_SECRET_KEY!,
    endpoint: "http://localhost:9000",
    region: "us-east-1",
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### Self-Hosted MinIO [#self-hosted-minio]

```typescript
const storage = new S3Storage({
    bucket: "my-bucket",
    endpoint: "http://minio.example.com:9000",
    region: "us-east-1",
    credentials: {
        accessKeyId: "minioadmin",
        secretAccessKey: "minioadmin",
    },
    forcePathStyle: true, // Required for self-hosted MinIO
});
```

### Managed MinIO (MinIO Object Storage) [#managed-minio-minio-object-storage]

```typescript
const storage = new S3Storage({
    bucket: "my-bucket",
    endpoint: "https://s3.your-minio-instance.com",
    region: "us-east-1",
    credentials: {
        accessKeyId: process.env.MINIO_ACCESS_KEY!,
        secretAccessKey: process.env.MINIO_SECRET_KEY!,
    },
});
```

## Features [#features]

* **S3-Compatible**: Full S3 API compatibility
* **Self-Hosted**: Deploy on your own infrastructure
* **High Performance**: Optimized for performance
* **Distributed**: Support for distributed deployments

## Best Practices [#best-practices]

1. **Use forcePathStyle** - Required for self-hosted MinIO
2. **Configure TLS** - Use HTTPS for production
3. **Set up access policies** - Configure bucket policies
4. **Monitor performance** - Track MinIO metrics
5. **Backup regularly** - Implement backup strategy for self-hosted deployments


# Netlify Blob (/docs/packages/storage/services/netlify-blob)



# Netlify Blob Storage [#netlify-blob-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Netlify Blob Storage is a serverless object storage service for Netlify deployments. It provides persistent storage for edge functions and serverless applications.

## Installation [#installation]

```sh
npm install @netlify/blobs
```

```sh
yarn add @netlify/blobs
```

```sh
pnpm add @netlify/blobs
```

## Usage [#usage]

```typescript
import { NetlifyBlobStorage } from "@visulima/storage/provider/netlify";

const storage = new NetlifyBlobStorage({
    storeName: "uploads",
    siteID: process.env.NETLIFY_SITE_ID,
    token: process.env.NETLIFY_TOKEN,
    metaStorageConfig: { directory: "/tmp/upload-metafiles" },
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
// Set NETLIFY_SITE_ID and NETLIFY_TOKEN
process.env.NETLIFY_SITE_ID = "your-site-id";
process.env.NETLIFY_TOKEN = "your-token";

const storage = new NetlifyBlobStorage({
    storeName: "uploads",
    // Site ID and token are automatically read from environment
});
```

### With Credentials [#with-credentials]

```typescript
const storage = new NetlifyBlobStorage({
    storeName: "uploads",
    siteID: "your-site-id",
    token: "your-token",
});
```

### Advanced Configuration [#advanced-configuration]

```typescript
const storage = new NetlifyBlobStorage({
    storeName: "uploads",
    siteID: process.env.NETLIFY_SITE_ID,
    token: process.env.NETLIFY_TOKEN,
    retryConfig: {
        maxRetries: 3,
        initialDelay: 1000,
    },
    expiration: {
        maxAge: "7d",
        purgeInterval: "1h",
    },
});
```

## Features [#features]

* **Serverless**: Optimized for Netlify Edge Functions
* **Persistent Storage**: Reliable storage for serverless applications
* **Automatic Retry**: Built-in retry mechanism for transient failures
* **Metadata Support**: Rich metadata for file organization

## Basic Operations [#basic-operations]

```typescript
// Create a file
const file = await storage.create({
    contentType: "image/jpeg",
    metadata: { filename: "photo.jpg" },
});

// Write data
await storage.write({
    id: file.id,
    body: imageStream,
    contentLength: imageSize,
});

// Get file
const fileData = await storage.get({ id: file.id });

// Delete file
await storage.delete({ id: file.id });
```

## URL Generation [#url-generation]

Netlify Blob generates URLs based on your deployment:

```typescript
const file = await storage.get({ id: "file-id" });

// file.url - Generated URL (typically via Netlify Function)
// file.pathname - File pathname
```

## Netlify Edge Functions [#netlify-edge-functions]

Use with Netlify Edge Functions:

```typescript
import { NetlifyBlobStorage } from "@visulima/storage/provider/netlify";

export default async (request: Request, context: any) => {
    const storage = new NetlifyBlobStorage({
        storeName: "uploads",
        // Credentials are automatically available in Netlify context
    });

    // Use storage...
    return new Response("OK");
};
```

## Best Practices [#best-practices]

1. **Use environment variables** - Store credentials securely
2. **Configure retry** - Handle transient failures
3. **Use appropriate store names** - Organize files by store
4. **Monitor usage** - Track storage usage in Netlify dashboard
5. **Handle errors gracefully** - Netlify Blob may have rate limits


# Onedrive (/docs/packages/storage/services/onedrive)



# Microsoft OneDrive [#microsoft-onedrive]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage, OAuth wiring, and Graph-specific behavior.

## Overview [#overview]

The OneDrive adapter targets Microsoft Graph (`/me/drive` or `/users/{id}/drive`) via the official `@microsoft/microsoft-graph-client`. It supports app-only (client-credentials) auth for service deployments, refresh-token auth for end-user flows, or a pre-built Graph client. Refresh-token caching uses a shared OAuth helper with 60 s leeway.

## Installation [#installation]

```sh
npm install @microsoft/microsoft-graph-client
```

```sh
yarn add @microsoft/microsoft-graph-client
```

```sh
pnpm add @microsoft/microsoft-graph-client
```

## Usage [#usage]

### App-only (client-credentials) [#app-only-client-credentials]

```ts
import OneDriveStorage from "@visulima/storage/provider/onedrive";

const storage = new OneDriveStorage({
    clientId: process.env.ONEDRIVE_CLIENT_ID!,
    clientSecret: process.env.ONEDRIVE_CLIENT_SECRET!,
    tenantId: process.env.ONEDRIVE_TENANT_ID!,
    driveUserId: process.env.ONEDRIVE_USER_ID, // target a specific user's drive
    basePath: "uploads",
});
```

### Refresh-token (delegated end-user auth) [#refresh-token-delegated-end-user-auth]

```ts
const storage = new OneDriveStorage({
    clientId: process.env.ONEDRIVE_CLIENT_ID!,
    clientSecret: process.env.ONEDRIVE_CLIENT_SECRET,
    tenantId: process.env.ONEDRIVE_TENANT_ID, // optional; defaults to `common`
    refreshToken: process.env.ONEDRIVE_REFRESH_TOKEN!,
});
```

### Pre-built client [#pre-built-client]

```ts
import { Client } from "@microsoft/microsoft-graph-client";

const storage = new OneDriveStorage({
    client: Client.init({ authProvider: async (done) => done(null, await getToken()) }),
});
```

Pre-built clients bypass the adapter's auth bookkeeping entirely.

## Configuration [#configuration]

### `basePath` [#basepath]

All operations are rooted under `basePath` so the same Microsoft tenant can host multiple logical "buckets":

```ts
new OneDriveStorage({
    /* …auth… */
    basePath: "uploads/avatars",
});
```

Keys are then joined as `uploads/avatars/<key>` inside `/drive/root:`.

### Drive selection [#drive-selection]

* Default: `/me/drive` (the authenticated user).
* `driveUserId`: targets `/users/{id}/drive` — useful for app-only auth where there's no "me".
* Pre-built client: target whatever the client is wired for.

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

* Default: returns the `@microsoft.graph.downloadUrl` from the item metadata (pre-authenticated, short-lived, \~1 h).
* `publicByDefault: true`: calls `createLink` (`type: "view", scope: "anonymous"`) to mint an anonymous sharing link.
* `responseContentDisposition` is not supported.

### `getUploadUrl(key, options?)` [#getuploadurlkey-options]

Returns an upload-session URL from `POST /drive/root:/{path}:/createUploadSession`. The caller drives the session with `PUT` requests carrying `Content-Range` headers — see Microsoft's [resumable upload docs](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession).

## Features [#features]

* **Two server-side auth flows** — client-credentials for app deployments, refresh-token for delegated end-user access.
* **Shared OAuth helper** — refresh-token mode reuses the same caching/leeway logic as the Dropbox adapter.
* **Upload sessions** — `getUploadUrl()` initiates a Microsoft Graph resumable upload session.
* **Sharing-link minting** — `publicByDefault` swaps the read-URL strategy without changing the call site.

## Limitations [#limitations]

* Single-shot writes via `write()` buffer the part stream — use `getUploadUrl()` for large transfers.
* `parentReference.path` requires the literal `/drive/root:` prefix; the adapter handles this for you but `storage.raw` callers should be aware.
* Read URLs (`@microsoft.graph.downloadUrl`) are short-lived (\~1 h) — re-call `getReadUrl()` for each request rather than caching.


# Storj (/docs/packages/storage/services/storj)



# Storj [#storj]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Storj is a decentralized, S3-compatible object storage service. Data is encrypted client-side and erasure-coded across thousands of independent storage nodes worldwide. The `storj` client targets the public Storj S3 Gateway (`gateway.storjshare.io`) by default; self-hosted gateways can override the endpoint.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Storj is S3-compatible via its S3 Gateway:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { storj } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = storj({
    accessKeyId: process.env.STORJ_ACCESS_KEY_ID!,
    secretAccessKey: process.env.STORJ_SECRET_ACCESS_KEY!,
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Generating credentials [#generating-credentials]

The `accessKeyId` / `secretAccessKey` pair is derived from a Storj **access grant**, using either the [Storj web console](https://www.storj.io/) or the `uplink share --register` CLI. Each grant scopes the resulting S3 credentials to a set of buckets and operations.

### Environment Variables [#environment-variables]

```typescript
process.env.STORJ_ACCESS_KEY_ID = "your-access-key";
process.env.STORJ_SECRET_ACCESS_KEY = "your-secret-key";
process.env.STORJ_ENDPOINT = "https://gateway.storjshare.io"; // Optional

const clientConfig = storj(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = storj({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    endpoint: "https://gateway.eu1.storjshare.io", // Optional region-specific gateway
});
```

## Features [#features]

* **End-to-end encryption**: Data is encrypted client-side before upload
* **Decentralized**: Erasure-coded across thousands of independent nodes
* **S3-Compatible**: Works with the AWS S3 SDK via the Storj S3 Gateway
* **Pay-as-you-go**: Per-GB storage and egress pricing

## Best Practices [#best-practices]

1. **Scope your access grants** — generate per-environment grants restricted to specific buckets / prefixes
2. **Rotate grants** instead of long-lived root credentials
3. **Self-host the gateway** for sensitive workloads to keep the encryption boundary in your trust zone
4. **Pick a regional gateway** (e.g. `gateway.eu1.storjshare.io`) closer to your compute


# Supabase (/docs/packages/storage/services/supabase)



# Supabase Storage [#supabase-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

The Supabase adapter wraps `@supabase/storage-js`'s `StorageClient` with the `BaseStorage` contract. Each adapter instance is bound to a single bucket — for multi-bucket apps, instantiate one adapter per bucket. Both `getReadUrl()` (signed URLs) and `getUploadUrl()` (signed upload URLs) are natively supported.

## Installation [#installation]

```sh
npm install @supabase/storage-js
```

```sh
yarn add @supabase/storage-js
```

```sh
pnpm add @supabase/storage-js
```

## Usage [#usage]

```ts
import SupabaseStorage from "@visulima/storage/provider/supabase";

const storage = new SupabaseStorage({
    url: process.env.SUPABASE_URL!,
    serviceKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
    bucket: "avatars",
});
```

## Configuration [#configuration]

### Environment variables [#environment-variables]

```ts
// Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_KEY)
process.env.SUPABASE_URL = "https://xyz.supabase.co";
process.env.SUPABASE_SERVICE_ROLE_KEY = "eyJ...";

const storage = new SupabaseStorage({ bucket: "avatars" });
```

The adapter normalizes the URL: pass either `https://xyz.supabase.co` or `https://xyz.supabase.co/storage/v1`.

### Pre-built client [#pre-built-client]

```ts
import { StorageClient } from "@supabase/storage-js";

const storageClient = new StorageClient(/* … */);
const storage = new SupabaseStorage({ client: storageClient, bucket: "avatars" });
```

### Custom fetch [#custom-fetch]

For environments without a global `fetch` or with custom transport requirements:

```ts
const storage = new SupabaseStorage({
    url: process.env.SUPABASE_URL!,
    serviceKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
    bucket: "avatars",
    fetch: customFetch,
});
```

### Default URL lifetime [#default-url-lifetime]

```ts
new SupabaseStorage({
    /* … */
    defaultUrlExpiresIn: 3600, // seconds; capped at 7 days (604_800)
});
```

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

Calls `bucket.createSignedUrl(key, expiresIn, { download })`. `expiresIn` is clamped to the Supabase 7-day max. `responseContentDisposition` translates to Supabase's `download` option:

* `attachment; filename=report.pdf` (or quoted, or RFC 5987 `filename*=UTF-8''…`) → `download: "report.pdf"` (filename round-trips to the browser)
* `attachment` (no filename) → `download: true` (browser saves under the bucket key)
* `inline` or omitted → `download: undefined` (browser renders inline)

```ts
const url = await storage.getReadUrl("avatar.png", { expiresIn: 600 });
const downloadUrl = await storage.getReadUrl("doc.pdf", {
    responseContentDisposition: 'attachment; filename="Q1 Report.pdf"',
});
```

### `getUploadUrl(key)` [#getuploadurlkey]

Calls `bucket.createSignedUploadUrl(key)`. The returned URL accepts a `PUT` from the browser with the file body — no Authorization header needed.

```ts
const url = await storage.getUploadUrl("avatar.png");
// PUT this URL from the browser
```

## Features [#features]

* **Native signed URLs** — both read and write, no extra plumbing.
* **Service-role auth** — set the key once; the adapter wires it into every request as `Authorization: Bearer …` and `apikey: …`.
* **Bucket-scoped** — each adapter instance targets a single bucket; multi-bucket apps run multiple adapters.
* **Auto upsert** — `write()` calls Supabase's `upload` with `upsert: true`, so re-writing a key replaces the object.

## Limitations [#limitations]

* Single-shot uploads — Supabase's TUS endpoint exists but the JS SDK uses `POST` with the full body. For large files use `getUploadUrl()` and stream the `PUT` from the client.
* Signed URLs cap at 7 days.
* `list()` always lists the bucket root with the configured page limit (default 1000). For deep prefixes or pagination, drop to `storage.raw`.


# Tencent Cos (/docs/packages/storage/services/tencent-cos)



# Tencent Cloud COS [#tencent-cloud-cos]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Tencent Cloud Object Storage (COS) is an S3-compatible object storage service. It is accessed through the S3-compatible endpoint, so it works with `S3Storage` plus the bundled `tencent` client preset, which derives the endpoint from the region code.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Tencent COS is S3-compatible, so use `S3Storage` with the `tencent` client preset:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { tencent } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = tencent({
    accessKeyId: process.env.TENCENT_SECRET_ID!,
    secretAccessKey: process.env.TENCENT_SECRET_KEY!,
    region: process.env.TENCENT_REGION || "ap-guangzhou",
});

const storage = new S3Storage({
    bucket: "uploads-1250000000",
    ...clientConfig,
});
```

> **Bucket naming:** the bucket name must include the APPID suffix (e.g. `uploads-1250000000`). The S3-compatible API expects the full form — a bare bucket name will not resolve.

The endpoint defaults to `https://cos.${region}.myqcloud.com` with virtual-hosted-style addressing. Pass `endpoint` (or set `TENCENT_ENDPOINT`) to override it.

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.TENCENT_SECRET_ID = "your-secret-id";
process.env.TENCENT_SECRET_KEY = "your-secret-key";
process.env.TENCENT_REGION = "ap-guangzhou";

const clientConfig = tencent(); // Uses environment variables
const storage = new S3Storage({
    bucket: "uploads-1250000000",
    ...clientConfig,
});
```

The `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` variables are also accepted as fallbacks. The region is **not** read from `AWS_REGION` — it is part of the endpoint hostname, and `AWS_REGION` is commonly set to an AWS region in dev/CI, which would silently produce a broken endpoint. Use `TENCENT_REGION` (or pass `region`).

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = tencent({
    accessKeyId: "your-secret-id",
    secretAccessKey: "your-secret-key",
    region: "ap-guangzhou",
});
```

## Regions [#regions]

Common Tencent COS regions:

* `ap-guangzhou` - China (Guangzhou)
* `ap-shanghai` - China (Shanghai)
* `ap-beijing` - China (Beijing)
* `ap-singapore` - Asia Pacific (Singapore)
* `na-siliconvalley` - North America (Silicon Valley)
* `eu-frankfurt` - Europe (Frankfurt)

## Features [#features]

* **S3-Compatible**: Works through the S3-compatible COS endpoint
* **Global Regions**: Data centers across China and worldwide
* **Lifecycle Management**: Automatic tiering and expiration policies
* **Presigned URLs**: Direct browser uploads and downloads

## Best Practices [#best-practices]

1. **Always include the APPID suffix** in the bucket name
2. **Set `TENCENT_REGION` explicitly** - it drives the endpoint hostname; never rely on `AWS_REGION`
3. **Choose the closest region** - reduce latency for your users
4. **Use lifecycle policies** - automatically transition or expire objects
5. **Configure CORS** - set up CORS for browser-based uploads


# Tigris (/docs/packages/storage/services/tigris)



# Tigris [#tigris]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Tigris is an S3-compatible object storage service with a focus on developer experience and simplicity.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Tigris is S3-compatible, so use the S3Storage with Tigris endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { tigris } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = tigris({
    accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY!,
    endpoint: process.env.TIGRIS_ENDPOINT || "https://t3.storage.dev",
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.TIGRIS_ACCESS_KEY_ID = "your-access-key";
process.env.TIGRIS_SECRET_ACCESS_KEY = "your-secret-key";
process.env.TIGRIS_ENDPOINT = "https://t3.storage.dev";

const clientConfig = tigris(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = tigris({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    endpoint: "https://t3.storage.dev",
});
```

## Features [#features]

* **S3-Compatible**: Full S3 API compatibility
* **Developer-Friendly**: Simple setup and configuration
* **Reliable**: High availability and durability

## Best Practices [#best-practices]

1. **Use environment variables** - Store credentials securely
2. **Configure endpoint** - Use appropriate Tigris endpoint
3. **Monitor usage** - Track storage usage
4. **Handle errors** - Implement proper error handling
5. **Use retry mechanism** - Configure retry for transient failures


# Uploadthing (/docs/packages/storage/services/uploadthing)



# UploadThing [#uploadthing]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage and UploadThing-specific key handling.

## Overview [#overview]

The UploadThing adapter wraps `UTApi` from `uploadthing/server`. Uploads are keyed by user-supplied `customId` so subsequent operations (`delete`, `signed URL`, `list`) round-trip on the user's key rather than UploadThing's internal `fileKey`. Read URLs are minted as public CDN URLs (`<appId>.ufs.sh/f/<customId>`) when the ACL is `public-read`, or as signed URLs via `generateSignedURL()` when the ACL is `private`.

## Installation [#installation]

```sh
npm install uploadthing
```

```sh
yarn add uploadthing
```

```sh
pnpm add uploadthing
```

## Usage [#usage]

```ts
import UploadThingStorage from "@visulima/storage/provider/uploadthing";

const storage = new UploadThingStorage({
    token: process.env.UPLOADTHING_TOKEN!,
    acl: "public-read",
});
```

The `token` is the base64-encoded JSON from your UploadThing dashboard — it embeds both `apiKey` and `appId`. The adapter decodes it once at construction to extract `appId` for CDN URL minting.

## Configuration [#configuration]

### Pre-built client [#pre-built-client]

```ts
import { UTApi } from "uploadthing/server";

const storage = new UploadThingStorage({
    client: new UTApi({ defaultKeyType: "customId", token: process.env.UPLOADTHING_TOKEN! }),
    token: process.env.UPLOADTHING_TOKEN!, // still required — used to derive appId
});
```

Even with a pre-built client, `token` is required so the adapter can extract `appId` for CDN URLs.

### ACL [#acl]

```ts
new UploadThingStorage({
    token: process.env.UPLOADTHING_TOKEN!,
    acl: "private", // or "public-read" (default)
});
```

* `public-read`: every upload is publicly readable; `getReadUrl()` returns the CDN URL synchronously without a round-trip.
* `private`: `getReadUrl()` calls `utapi.generateSignedURL()` for each request.

### Default signed URL lifetime [#default-signed-url-lifetime]

```ts
new UploadThingStorage({
    /* … */
    defaultUrlExpiresIn: 3600, // seconds; capped at 7 days (604_800)
});
```

## URL Generation [#url-generation]

### `getReadUrl(key, options?)` [#getreadurlkey-options]

* `public-read` ACL: returns `https://<appId>.ufs.sh/f/<encoded-customId>` synchronously.
* `private` ACL: returns a signed URL via `generateSignedURL(key, { expiresIn, keyType: "customId" })`. `expiresIn` is clamped to 7 days.
* `responseContentDisposition` is not supported.

### `getUploadUrl(key)` [#getuploadurlkey]

Throws `METHOD_NOT_ALLOWED`. UploadThing's signed PUT URLs require HMAC signing against a UFS ingest endpoint — out of scope for this adapter. Callers that need direct-from-browser uploads should use UploadThing's [file-router pattern](https://docs.uploadthing.com/) via `storage.raw`.

## Features [#features]

* **customId keying** — operations are addressed by your virtual key, not UploadThing's internal fileKey.
* **ACL-aware reads** — public files use the CDN directly; private files use signed URLs only when needed.
* **Token-derived `appId`** — no separate config field; the dashboard token already contains everything.
* **Native `listFiles`** — `storage.list()` round-trips a single `utapi.listFiles({ limit })`.

## Limitations [#limitations]

* No native presigned upload URLs — use the file-router pattern via `storage.raw` for direct-from-browser uploads.
* `copy()` is download-then-reupload (UploadThing has no server-side copy).
* `list()` has no server-side prefix filter — prefix filtering happens client-side per page.
* Signed URLs cap at 7 days.


# Vercel Blob (/docs/packages/storage/services/vercel-blob)



# Vercel Blob Storage [#vercel-blob-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Vercel Blob Storage is a serverless object storage service optimized for edge deployments. It provides fast, global access to files with automatic CDN distribution.

## Installation [#installation]

```sh
npm install @vercel/blob
```

```sh
yarn add @vercel/blob
```

```sh
pnpm add @vercel/blob
```

## Usage [#usage]

### On Vercel (recommended): OIDC [#on-vercel-recommended-oidc]

When a Blob store is connected to a Vercel project, `VERCEL_OIDC_TOKEN` and `BLOB_STORE_ID` are auto-injected. OIDC tokens are short-lived and auto-rotated, so there's no long-lived secret to leak.

```typescript
import { VercelBlobStorage } from "@visulima/storage/provider/vercel";

// Zero config — picks up VERCEL_OIDC_TOKEN + BLOB_STORE_ID from process.env.
const storage = new VercelBlobStorage({
    metaStorageConfig: { directory: "/tmp/upload-metafiles" },
});
```

For runtimes that don't expose `process.env` (Vite, some edge sandboxes), pass the OIDC pair explicitly:

```typescript
const storage = new VercelBlobStorage({
    oidcToken: loadOidcToken(),
    storeId: loadStoreId(), // accepts "store_<id>" or "<id>"
});
```

See [Vercel's OIDC docs](https://vercel.com/docs/vercel-blob/using-blob-sdk#oidc-tokens-recommended) for the full background.

### Off Vercel: read-write token [#off-vercel-read-write-token]

For CI, local dev, or anything not running on Vercel, use a long-lived `BLOB_READ_WRITE_TOKEN`:

```typescript
const storage = new VercelBlobStorage({
    token: process.env.BLOB_READ_WRITE_TOKEN,
    metaStorageConfig: { directory: "/tmp/upload-metafiles" },
});
```

## Configuration [#configuration]

### Credential precedence [#credential-precedence]

The adapter resolves auth credentials in this order — first match wins:

1. Explicit `token` option (RW or client token).
2. OIDC pair: `oidcToken` + `storeId` (option or `VERCEL_OIDC_TOKEN` + `BLOB_STORE_ID` env).
3. `BLOB_READ_WRITE_TOKEN` / `VERCEL_BLOB_TOKEN` env.

If no credentials are found, the constructor throws. Partial OIDC config (only one of `oidcToken`/`storeId` set) also throws, so misconfiguration fails loudly instead of silently falling through to anonymous calls.

### Environment Variables [#environment-variables]

| Variable                | Purpose                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `VERCEL_OIDC_TOKEN`     | Short-lived OIDC token, auto-injected on Vercel. Must be paired with `BLOB_STORE_ID`.         |
| `BLOB_STORE_ID`         | Blob store ID, auto-injected on Vercel. Accepted as `store_<id>` or `<id>` (prefix stripped). |
| `BLOB_READ_WRITE_TOKEN` | Long-lived read-write token. Used as a fallback when no OIDC pair is configured.              |
| `VERCEL_BLOB_TOKEN`     | Alias for `BLOB_READ_WRITE_TOKEN`, checked second.                                            |

### Advanced Configuration [#advanced-configuration]

```typescript
const storage = new VercelBlobStorage({
    // Auth (pick one of token / oidcToken+storeId; otherwise env vars are used)
    token: process.env.BLOB_READ_WRITE_TOKEN,

    multipart: true, // Enable multipart uploads for large files
    multipart: 10 * 1024 * 1024, // Or: enable multipart for files > 10MB

    retryConfig: {
        maxRetries: 3,
        initialDelay: 1000,
    },
    expiration: {
        maxAge: "7d",
        purgeInterval: "1h",
    },
});
```

### Peer dependency [#peer-dependency]

OIDC support requires `@vercel/blob >= 2.4.0` (the first release with `oidcToken` and `storeId` on `BlobCommandOptions`).

## Features [#features]

* **Global CDN**: Automatic CDN distribution for fast access
* **Serverless**: Optimized for edge deployments
* **Multipart Uploads**: Support for large files
* **Automatic Retry**: Built-in retry mechanism for transient failures

## Basic Operations [#basic-operations]

```typescript
// Create a file
const file = await storage.create({
    contentType: "image/jpeg",
    metadata: { filename: "photo.jpg" },
});

// Write data
await storage.write({
    id: file.id,
    body: imageStream,
    contentLength: imageSize,
});

// Get file
const fileData = await storage.get({ id: file.id });

// Delete file
await storage.delete({ id: file.id });
```

## URL Generation [#url-generation]

Vercel Blob automatically generates public URLs:

```typescript
const file = await storage.get({ id: "file-id" });

// file.url - Public URL
// file.downloadUrl - Download URL
// file.pathname - File pathname
```

## Best Practices [#best-practices]

1. **Prefer OIDC on Vercel** - Use `VERCEL_OIDC_TOKEN` + `BLOB_STORE_ID` over long-lived `BLOB_READ_WRITE_TOKEN`. OIDC tokens auto-rotate and can't leak from a checked-in env file.
2. **Use environment variables** - Store tokens securely off Vercel.
3. **Enable multipart for large files** - Better performance for files > 10MB.
4. **Configure retry** - Handle transient failures.
5. **Use CDN URLs** - Leverage Vercel's global CDN.
6. **Monitor usage** - Track storage and bandwidth usage.


# Wasabi (/docs/packages/storage/services/wasabi)



# Wasabi [#wasabi]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Wasabi is an S3-compatible cloud storage service with predictable pricing and no egress fees. It provides high-performance storage for applications.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Wasabi is S3-compatible, so use the S3Storage with Wasabi endpoint:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { wasabi } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = wasabi({
    accessKeyId: process.env.WASABI_ACCESS_KEY_ID!,
    secretAccessKey: process.env.WASABI_SECRET_ACCESS_KEY!,
    region: process.env.WASABI_REGION || "us-east-1",
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.WASABI_ACCESS_KEY_ID = "your-access-key";
process.env.WASABI_SECRET_ACCESS_KEY = "your-secret-key";
process.env.WASABI_REGION = "us-east-1";

const clientConfig = wasabi(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = wasabi({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    region: "us-east-1",
});
```

## Regions [#regions]

Wasabi regions:

* `us-east-1` - US East (N. Virginia)
* `us-west-1` - US West (Oregon)
* `eu-central-1` - EU Central (Amsterdam)
* `eu-west-1` - EU West (London)
* `ap-northeast-1` - Asia Pacific (Tokyo)

## Features [#features]

* **Predictable Pricing**: No egress fees, simple pricing model
* **S3-Compatible**: Full S3 API compatibility
* **High Performance**: Fast upload and download speeds
* **Global Regions**: Multiple regions worldwide

## Best Practices [#best-practices]

1. **Choose appropriate region** - Select region closest to your users
2. **Monitor usage** - Track storage usage in Wasabi dashboard
3. **Use lifecycle policies** - Automatically manage file lifecycle
4. **Configure CORS** - Set up CORS for web applications
5. **Enable versioning** - Use Wasabi versioning for important files


# Yandex Object Storage (/docs/packages/storage/services/yandex-object-storage)



# Yandex Object Storage [#yandex-object-storage]

> **Just need ad-hoc uploads?** Wrap this adapter in the [`Files` facade](/docs/packages/storage/files-facade) for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

## Overview [#overview]

Yandex Object Storage is an S3-compatible object storage service. It serves a single global endpoint (`https://storage.yandexcloud.net`) and routes internally, so it works with `S3Storage` plus the bundled `yandex` client preset.

## Installation [#installation]

```sh
npm install @aws-sdk/client-s3 @aws-sdk/credential-providers @aws-sdk/s3-request-presigner @aws-sdk/signature-v4-crt aws-crt @aws-sdk/types
```

## Usage [#usage]

Yandex Object Storage is S3-compatible, so use `S3Storage` with the `yandex` client preset:

```typescript
import { S3Storage } from "@visulima/storage/provider/aws";
import { yandex } from "@visulima/storage/provider/aws/s3/clients";

const clientConfig = yandex({
    accessKeyId: process.env.YANDEX_ACCESS_KEY_ID!,
    secretAccessKey: process.env.YANDEX_SECRET_ACCESS_KEY!,
});

const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

Yandex serves a single global endpoint, so the region is only the SigV4 signing scope and defaults to `ru-central1`. Pass `endpoint` (or set `YANDEX_ENDPOINT`) to override the endpoint.

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```typescript
process.env.YANDEX_ACCESS_KEY_ID = "your-access-key";
process.env.YANDEX_SECRET_ACCESS_KEY = "your-secret-key";
// Optional — defaults to "ru-central1"
process.env.YANDEX_REGION = "ru-central1";

const clientConfig = yandex(); // Uses environment variables
const storage = new S3Storage({
    bucket: "my-bucket",
    ...clientConfig,
});
```

The `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` variables are also accepted as fallbacks. Because the region does not drive the endpoint here, falling back to `AWS_REGION` is safe.

### With Explicit Parameters [#with-explicit-parameters]

```typescript
const clientConfig = yandex({
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key",
    region: "ru-central1",
});
```

## Regions [#regions]

Yandex Object Storage uses a single global endpoint; `region` only sets the SigV4 signing scope:

* `ru-central1` - Russia (Central) — default

## Features [#features]

* **S3-Compatible**: Works through the S3-compatible endpoint
* **Single Global Endpoint**: No per-region endpoint to configure
* **Lifecycle Management**: Automatic tiering and expiration policies
* **Presigned URLs**: Direct browser uploads and downloads

## Best Practices [#best-practices]

1. **Leave region as default** unless you have a specific signing requirement
2. **Use lifecycle policies** - automatically transition or expire objects
3. **Configure CORS** - set up CORS for browser-based uploads
4. **Use a separate metafiles bucket** - keep upload metadata isolated for resumable uploads


# Transformers (/docs/packages/storage/transformers)



# Media Transformers [#media-transformers]

Visulima storage provides transformers for images, videos, and audio files. Transformers support both URL-based query parameters and programmatic APIs.

## Overview [#overview]

Three transformer types are available:

* **ImageTransformer**: Image processing with Sharp
* **VideoTransformer**: Video processing with Mediabunny
* **AudioTransformer**: Audio processing with Mediabunny
* **MediaTransformer**: Unified transformer that automatically detects media type

## Image Transformer [#image-transformer]

Transform images with resizing, cropping, format conversion, and more.

### Basic Usage [#basic-usage]

```typescript
import { LRUCache } from "lru-cache";
import { DiskStorage } from "@visulima/storage";
import ImageTransformer from "@visulima/storage/transformer/image";

const storage = new DiskStorage({ directory: "./uploads" });
const cache = new LRUCache({ max: 1000, ttl: 3600000 });

const transformer = new ImageTransformer(storage, {
    cache,
    maxImageSize: 10 * 1024 * 1024, // 10MB
    cacheTtl: 3600, // 1 hour
});
```

### Resize Images [#resize-images]

```typescript
// Resize with fit mode
const result = await transformer.resize("image-id", {
    width: 800,
    height: 600,
    fit: "cover", // cover, contain, fill, inside, outside
    quality: 85,
    format: "jpeg",
});

// URL-based: GET /files/image-id?width=800&height=600&fit=cover&quality=85
```

### Crop Images [#crop-images]

```typescript
const cropped = await transformer.crop("image-id", {
    width: 400,
    height: 300,
    left: 100,
    top: 50,
});
```

### Convert Formats [#convert-formats]

```typescript
// Convert to WebP
const webp = await transformer.convertFormat("image-id", "webp", {
    quality: 85,
    lossless: false,
});

// Convert to AVIF
const avif = await transformer.convertFormat("image-id", "avif", {
    quality: 80,
    effort: 4,
});
```

### Advanced Transformations [#advanced-transformations]

```typescript
// Rotate
const rotated = await transformer.rotate("image-id", {
    angle: 90,
    background: { r: 255, g: 255, b: 255 },
});

// Apply effects
const processed = await transformer.transform("image-id", {
    blur: true,
    sharpen: true,
    greyscale: true,
    gamma: 2.2,
});
```

## Video Transformer [#video-transformer]

Transform videos with resizing, format conversion, and codec changes.

### Basic Usage [#basic-usage-1]

```typescript
import { DiskStorage } from "@visulima/storage";
import VideoTransformer from "@visulima/storage/transformer/video";

const storage = new DiskStorage({ directory: "./uploads" });

const transformer = new VideoTransformer(storage, {
    maxVideoSize: 100 * 1024 * 1024, // 100MB
    defaultCodec: "avc",
    defaultBitrate: 2_000_000, // 2 Mbps
});
```

### Resize Videos [#resize-videos]

```typescript
const result = await transformer.resize("video-id", {
    width: 1920,
    height: 1080,
    fit: "contain",
    codec: "avc",
    bitrate: 2_000_000,
});

// URL-based: GET /files/video-id?width=1920&height=1080&codec=avc&bitrate=2000000
```

### Convert Formats [#convert-formats-1]

```typescript
const webm = await transformer.transform("video-id", {
    format: "webm",
    codec: "vp9",
    bitrate: 1_500_000,
});
```

### Video Codecs [#video-codecs]

Supported codecs:

* `avc` - H.264/AVC
* `hevc` - H.265/HEVC
* `vp8` - VP8
* `vp9` - VP9
* `av1` - AV1

## Audio Transformer [#audio-transformer]

Transform audio with resampling, format conversion, and codec changes.

### Basic Usage [#basic-usage-2]

```typescript
import { DiskStorage } from "@visulima/storage";
import AudioTransformer from "@visulima/storage/transformer/audio";

const storage = new DiskStorage({ directory: "./uploads" });

const transformer = new AudioTransformer(storage, {
    maxAudioSize: 50 * 1024 * 1024, // 50MB
    defaultCodec: "aac",
    defaultBitrate: 128_000, // 128 kbps
});
```

### Resample Audio [#resample-audio]

```typescript
const result = await transformer.resample("audio-id", {
    sampleRate: 44100,
    numberOfChannels: 2,
});

// URL-based: GET /files/audio-id?sampleRate=44100&numberOfChannels=2
```

### Convert Formats [#convert-formats-2]

```typescript
const mp3 = await transformer.transform("audio-id", {
    format: "mp3",
    codec: "mp3",
    bitrate: 192_000,
});
```

### Audio Codecs [#audio-codecs]

Supported codecs:

* `aac` - AAC
* `opus` - Opus
* `mp3` - MP3
* `vorbis` - Vorbis
* `flac` - FLAC

## Media Transformer [#media-transformer]

Unified transformer that automatically detects and processes any media type.

### Basic Usage [#basic-usage-3]

```typescript
import { DiskStorage } from "@visulima/storage";
import { MediaTransformer } from "@visulima/storage/transformer";
import ImageTransformer from "@visulima/storage/transformer/image";
import VideoTransformer from "@visulima/storage/transformer/video";
import AudioTransformer from "@visulima/storage/transformer/audio";

const storage = new DiskStorage({ directory: "./uploads" });

const transformer = new MediaTransformer(storage, {
    ImageTransformer: ImageTransformer,
    VideoTransformer: VideoTransformer,
    AudioTransformer: AudioTransformer,
    cache: new LRUCache({ max: 1000, ttl: 3600000 }),
    saveTransformedFiles: true, // Persist transformed files
});
```

### Automatic Detection [#automatic-detection]

```typescript
// Automatically detects media type and routes to appropriate transformer
const result = await transformer.handle("file-id", {
    width: 800,
    height: 600,
    format: "webp",
    quality: 85,
});

// Or use URL query string
const result = await transformer.fetch("file-id", "width=800&height=600&format=webp&quality=85");
```

### URL-Based Transformations [#url-based-transformations]

```typescript
// Image: GET /files/image-id?width=800&height=600&fit=cover&quality=85
// Video: GET /files/video-id?width=1920&height=1080&codec=avc&bitrate=2000000
// Audio: GET /files/audio-id?sampleRate=44100&codec=aac&bitrate=128000
```

## Query Parameters [#query-parameters]

### Common Parameters [#common-parameters]

| Parameter | Type   | Description     | Example                                |
| --------- | ------ | --------------- | -------------------------------------- |
| `format`  | string | Output format   | `jpeg`, `webp`, `mp4`, `mp3`           |
| `quality` | number | Quality/bitrate | `80` (images), `2000000` (video/audio) |

### Image Parameters [#image-parameters]

| Parameter  | Type    | Description                 | Values                                          |
| ---------- | ------- | --------------------------- | ----------------------------------------------- |
| `width`    | number  | Width in pixels             | 1-10000                                         |
| `height`   | number  | Height in pixels            | 1-10000                                         |
| `fit`      | string  | Resize fit mode             | `cover`, `contain`, `fill`, `inside`, `outside` |
| `position` | string  | Position for cover/contain  | `centre`, `top`, `right`, `bottom`, `left`      |
| `lossless` | boolean | Lossless compression (WebP) | `true`, `false`                                 |
| `effort`   | number  | CPU effort (AVIF)           | 0-10                                            |

### Video Parameters [#video-parameters]

| Parameter   | Type   | Description      | Values                             |
| ----------- | ------ | ---------------- | ---------------------------------- |
| `width`     | number | Width in pixels  | 1-10000                            |
| `height`    | number | Height in pixels | 1-10000                            |
| `codec`     | string | Video codec      | `avc`, `hevc`, `vp8`, `vp9`, `av1` |
| `bitrate`   | number | Bitrate in bps   | 1000000+                           |
| `frameRate` | number | Frame rate in Hz | 24, 30, 60                         |

### Audio Parameters [#audio-parameters]

| Parameter          | Type   | Description        | Values                                 |
| ------------------ | ------ | ------------------ | -------------------------------------- |
| `sampleRate`       | number | Sample rate in Hz  | 8000, 16000, 44100, 48000              |
| `numberOfChannels` | number | Number of channels | 1, 2                                   |
| `codec`            | string | Audio codec        | `aac`, `opus`, `mp3`, `vorbis`, `flac` |
| `bitrate`          | number | Bitrate in bps     | 64000+                                 |

## Caching Transformed Files [#caching-transformed-files]

Enable persistent caching of transformed files:

```typescript
const transformer = new MediaTransformer(storage, {
    ImageTransformer: ImageTransformer,
    saveTransformedFiles: true, // Save to storage
    cache: new LRUCache({ max: 1000, ttl: 3600000 }), // In-memory cache
});
```

## Best Practices [#best-practices]

1. **Use caching** - Cache transformed files to avoid reprocessing
2. **Choose appropriate formats** - WebP/AVIF for images, VP9/AV1 for videos
3. **Set quality/bitrate** - Balance file size and quality
4. **Monitor processing time** - Large files take longer to process
5. **Handle errors** - Transformations can fail for invalid files


# Tus Handler (/docs/packages/storage/tus-handler)



# TUS Handler [#tus-handler]

The TUS (Tus Resumable Upload Protocol) handler provides resumable uploads for large files, unreliable networks, and scenarios where uploads may be interrupted.

## Overview [#overview]

TUS is an open protocol for resumable file uploads. It allows clients to:

* Resume interrupted uploads
* Upload large files efficiently
* Track upload progress
* Handle network failures gracefully

## Installation [#installation]

TUS handler is included in the main package - no additional installation required.

## Basic Usage [#basic-usage]

### Express [#express]

```typescript
import express from "express";
import { DiskStorage } from "@visulima/storage";
import { Tus } from "@visulima/storage/handler/http/node";

const app = express();
const storage = new DiskStorage({ directory: "./uploads" });
const tus = new Tus({ storage });

// TUS endpoints
app.post("/upload/tus", tus.handle);
app.patch("/upload/tus/:id", tus.handle);
app.head("/upload/tus/:id", tus.handle);
app.delete("/upload/tus/:id", tus.handle);
```

### Modern Frameworks (Fetch API) [#modern-frameworks-fetch-api]

```typescript
import { DiskStorage } from "@visulima/storage";
import { Tus } from "@visulima/storage/handler/http/fetch";

const storage = new DiskStorage({ directory: "./uploads" });
const tus = new Tus({ storage });

// TUS endpoints
app.post("/upload/tus", async (c) => {
    return await tus.fetch(c.req.raw);
});

app.patch("/upload/tus/:id", async (c) => {
    return await tus.fetch(c.req.raw);
});

app.head("/upload/tus/:id", async (c) => {
    return await tus.fetch(c.req.raw);
});

app.delete("/upload/tus/:id", async (c) => {
    return await tus.fetch(c.req.raw);
});
```

## Client-Side Usage [#client-side-usage]

### JavaScript/TypeScript [#javascripttypescript]

```typescript
import * as tus from "tus-js-client";

const file = document.getElementById("file-input").files[0];

const upload = new tus.Upload(file, {
    endpoint: "http://localhost:3000/upload/tus",
    retryDelays: [0, 3000, 5000, 10000, 20000],
    metadata: {
        filename: file.name,
        filetype: file.type,
    },
    onError: (error) => {
        console.error("Upload failed:", error);
    },
    onProgress: (bytesUploaded, bytesTotal) => {
        const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
        console.log(`Upload progress: ${percentage}%`);
    },
    onSuccess: () => {
        console.log("Upload finished:", upload.url);
    },
});

// Start the upload
upload.start();

// Pause the upload
upload.abort();

// Resume the upload
upload.start();
```

## TUS Extensions [#tus-extensions]

The TUS handler supports several extensions:

### Creation Extension [#creation-extension]

Create uploads with metadata:

```typescript
// POST /upload/tus
// Headers:
//   Upload-Length: 10485760
//   Upload-Metadata: filename dGVzdC5qcGc=,filetype aW1hZ2UvanBlZw==
```

### Creation-with-Upload Extension [#creation-with-upload-extension]

Create and upload in a single request:

```typescript
// POST /upload/tus
// Headers:
//   Upload-Length: 10485760
//   Content-Type: application/offset+octet-stream
// Body: [file data]
```

### Termination Extension [#termination-extension]

Delete incomplete uploads:

```typescript
// DELETE /upload/tus/:id
```

### Checksum Extension [#checksum-extension]

Verify upload integrity:

```typescript
// PATCH /upload/tus/:id
// Headers:
//   Upload-Offset: 0
//   Upload-Checksum: sha1 3f4f5f6f7f8f9f0f1f2f3f4f5f6f7f8f9f0f1f2
//   Content-Type: application/offset+octet-stream
// Body: [chunk data]
```

### Expiration Extension [#expiration-extension]

Automatic cleanup of expired uploads:

```typescript
const storage = new DiskStorage({
    directory: "./uploads",
    expiration: {
        maxAge: "24h",
        purgeInterval: "1h",
    },
});
```

## Response Headers [#response-headers]

TUS responses include standard TUS headers:

* `Tus-Resumable`: TUS protocol version (e.g., "1.0.0")
* `Tus-Version`: Supported TUS versions
* `Tus-Extension`: Supported TUS extensions
* `Tus-Max-Size`: Maximum upload size
* `Location`: Upload URL for created uploads
* `Upload-Offset`: Current upload offset
* `Upload-Expires`: Upload expiration timestamp

## Configuration [#configuration]

```typescript
const tus = new Tus({
    storage,
    // Customize TUS behavior
    onUploadComplete: (file) => {
        console.log("Upload complete:", file.id);
    },
    onUploadError: (error) => {
        console.error("Upload error:", error);
    },
});
```

## Resuming Uploads [#resuming-uploads]

TUS automatically handles resumable uploads:

```typescript
// Client checks upload status
const response = await fetch("http://localhost:3000/upload/tus/upload-id", {
    method: "HEAD",
});

const offset = response.headers.get("Upload-Offset");
const length = response.headers.get("Upload-Length");

// Resume from offset
const upload = new tus.Upload(file, {
    endpoint: "http://localhost:3000/upload/tus",
    uploadUrl: "http://localhost:3000/upload/tus/upload-id",
    // Upload will automatically resume from offset
});
```

## Best Practices [#best-practices]

1. **Use appropriate chunk sizes** - Balance between efficiency and memory usage
2. **Handle network errors** - Implement retry logic on the client side
3. **Monitor progress** - Use HEAD requests to track upload status
4. **Clean up incomplete uploads** - Use expiration extension for automatic cleanup
5. **Verify integrity** - Use checksum extension for large files

## Comparison with REST Handler [#comparison-with-rest-handler]

| Feature           | TUS Handler   | REST Handler    |
| ----------------- | ------------- | --------------- |
| Resumable         | ✅ Yes         | ✅ Yes (chunked) |
| Protocol          | TUS Protocol  | HTTP REST       |
| Client Library    | tus-js-client | Native fetch    |
| Progress Tracking | Built-in      | Custom headers  |
| Checksum Support  | ✅ Yes         | ✅ Yes           |
| Batch Operations  | ❌ No          | ✅ Yes           |

Choose TUS for:

* Standard resumable upload protocol
* Large files with unreliable networks
* Client libraries that support TUS

Choose REST for:

* Simple HTTP-based uploads
* Batch operations
* Custom upload workflows


# API Reference (/docs/packages/storage-client/api)



# API Reference [#api-reference]

Complete API reference for the `@visulima/storage-client` package. This page documents every exported hook, primitive, type, and utility across all framework integrations.

## Core Exports [#core-exports]

The core module is available via the root import path `@visulima/storage-client` and provides framework-agnostic utilities, adapters, and types.

### `createUploader` [#createuploader]

Creates a low-level event-driven file uploader instance using `XMLHttpRequest` with multipart/form-data.

```ts
import { createUploader } from "@visulima/storage-client";

const uploader = createUploader({
    endpoint: "/api/upload/multipart",
    metadata: { category: "photos" },
});
```

**Options: `UploaderOptions`**

| Property     | Type                     | Required | Description                                    |
| ------------ | ------------------------ | -------- | ---------------------------------------------- |
| `endpoint`   | `string`                 | Yes      | Upload endpoint URL                            |
| `metadata`   | `Record<string, string>` | No       | Additional metadata to include with the upload |
| `retry`      | `boolean`                | No       | Enable automatic retry on failure              |
| `maxRetries` | `number`                 | No       | Maximum number of retry attempts               |

**Returns: `Uploader`**

| Method          | Signature                                                           | Description                                       |
| --------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `add`           | `(file: File, batchId?: string) => string`                          | Adds a file to the upload queue. Returns item ID. |
| `addBatch`      | `(files: File[]) => string[]`                                       | Adds multiple files as a batch. Returns item IDs. |
| `getItem`       | `(id: string) => UploadItem \| undefined`                           | Gets an item by ID                                |
| `getItems`      | `() => UploadItem[]`                                                | Gets all items                                    |
| `getBatch`      | `(batchId: string) => BatchState \| undefined`                      | Gets batch state by batch ID                      |
| `getBatches`    | `() => BatchState[]`                                                | Gets all batches                                  |
| `getBatchItems` | `(batchId: string) => UploadItem[]`                                 | Gets all items in a batch                         |
| `abortItem`     | `(id: string) => void`                                              | Aborts a specific upload                          |
| `abortBatch`    | `(batchId: string) => void`                                         | Aborts all uploads in a batch                     |
| `abort`         | `() => void`                                                        | Aborts all uploads                                |
| `clear`         | `() => void`                                                        | Clears all items and aborts active uploads        |
| `retryItem`     | `(id: string) => void`                                              | Retries a failed upload item                      |
| `retryBatch`    | `(batchId: string) => void`                                         | Retries all failed items in a batch               |
| `on`            | `(event: UploaderEventType, handler: UploaderEventHandler) => void` | Subscribes to uploader events                     |
| `off`           | `(event: UploaderEventType, handler: UploaderEventHandler) => void` | Unsubscribes from uploader events                 |

### `createMultipartAdapter` [#createmultipartadapter]

Creates a multipart upload adapter wrapping the `Uploader` with a Promise-based API.

```ts
import { createMultipartAdapter } from "@visulima/storage-client";

const adapter = createMultipartAdapter({
    endpoint: "/api/upload/multipart",
});

const result = await adapter.upload(file);
```

**Options: `MultipartAdapterOptions`**

| Property     | Type                     | Required | Description            |
| ------------ | ------------------------ | -------- | ---------------------- |
| `endpoint`   | `string`                 | Yes      | Upload endpoint URL    |
| `metadata`   | `Record<string, string>` | No       | Additional metadata    |
| `retry`      | `boolean`                | No       | Enable automatic retry |
| `maxRetries` | `number`                 | No       | Maximum retry attempts |

**Returns: `MultipartAdapter`**

| Method        | Signature                               | Description                                         |
| ------------- | --------------------------------------- | --------------------------------------------------- |
| `upload`      | `(file: File) => Promise<UploadResult>` | Uploads a file and returns the result               |
| `uploadBatch` | `(files: File[]) => string[]`           | Uploads multiple files as a batch, returns item IDs |
| `abort`       | `() => void`                            | Aborts all uploads                                  |
| `abortBatch`  | `(batchId: string) => void`             | Aborts a batch of uploads                           |
| `abortItem`   | `(id: string) => void`                  | Aborts a specific upload item                       |
| `clear`       | `() => void`                            | Clears all uploads                                  |
| `uploader`    | `Uploader`                              | The underlying uploader instance                    |

### `createTusAdapter` [#createtusadapter]

Creates a TUS (resumable upload) adapter with pause/resume and chunked upload support.

```ts
import { createTusAdapter } from "@visulima/storage-client";

const adapter = createTusAdapter({
    endpoint: "/api/upload/tus",
    chunkSize: 1024 * 1024, // 1MB
});

const result = await adapter.upload(file);
```

**Options: `TusAdapterOptions`**

| Property      | Type                     | Required | Default              | Description                                                                          |
| ------------- | ------------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------ |
| `endpoint`    | `string`                 | Yes      | -                    | TUS upload endpoint URL                                                              |
| `chunkSize`   | `number`                 | No       | `1048576` (1MB)      | Chunk size for TUS uploads                                                           |
| `metadata`    | `Record<string, string>` | No       | `{}`                 | Additional metadata                                                                  |
| `retry`       | `boolean`                | No       | `true`               | Enable automatic retry                                                               |
| `maxRetries`  | `number`                 | No       | `3`                  | Maximum retry attempts                                                               |
| `control`     | `UploadControl`          | No       | -                    | Unified pause/resume/abort handle, see [Cross-process resume](#cross-process-resume) |
| `fingerprint` | `FingerprintFn`          | No       | `defaultFingerprint` | Override the per-file resume key                                                     |
| `urlStorage`  | `UrlStorage`             | No       | -                    | Persistent storage for resume URLs; opt in via `defaultUrlStorage()`                 |

**Returns: `TusAdapter`**

| Method          | Signature                               | Description                                 |
| --------------- | --------------------------------------- | ------------------------------------------- |
| `upload`        | `(file: File) => Promise<UploadResult>` | Uploads a file using TUS protocol           |
| `pause`         | `() => void`                            | Pauses the current upload                   |
| `resume`        | `() => Promise<void>`                   | Resumes a paused upload                     |
| `abort`         | `() => void`                            | Aborts the current upload                   |
| `clear`         | `() => void`                            | Clears all uploads                          |
| `getOffset`     | `() => number`                          | Gets current upload offset                  |
| `isPaused`      | `() => boolean`                         | Whether upload is paused                    |
| `setOnStart`    | `(callback?) => void`                   | Sets start callback                         |
| `setOnProgress` | `(callback?) => void`                   | Sets progress callback `(progress, offset)` |
| `setOnFinish`   | `(callback?) => void`                   | Sets finish callback                        |
| `setOnError`    | `(callback?) => void`                   | Sets error callback                         |

### `createChunkedRestAdapter` [#createchunkedrestadapter]

Creates a chunked REST upload adapter that uploads files in chunks using PATCH requests with pause/resume support.

```ts
import { createChunkedRestAdapter } from "@visulima/storage-client";

const adapter = createChunkedRestAdapter({
    endpoint: "/api/upload/chunked-rest",
    chunkSize: 5 * 1024 * 1024, // 5MB
});

const result = await adapter.upload(file);
```

**Options: `ChunkedRestAdapterOptions`**

| Property      | Type                     | Required | Default              | Description                                                                          |
| ------------- | ------------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------ |
| `endpoint`    | `string`                 | Yes      | -                    | Chunked REST upload endpoint URL                                                     |
| `chunkSize`   | `number`                 | No       | `5242880` (5MB)      | Chunk size in bytes                                                                  |
| `metadata`    | `Record<string, string>` | No       | `{}`                 | Additional metadata                                                                  |
| `retry`       | `boolean`                | No       | `true`               | Enable automatic retry                                                               |
| `maxRetries`  | `number`                 | No       | `3`                  | Maximum retry attempts                                                               |
| `control`     | `UploadControl`          | No       | -                    | Unified pause/resume/abort handle, see [Cross-process resume](#cross-process-resume) |
| `fingerprint` | `FingerprintFn`          | No       | `defaultFingerprint` | Override the per-file resume key                                                     |
| `urlStorage`  | `UrlStorage`             | No       | -                    | Persistent storage for resume identifiers; opt in via `defaultUrlStorage()`          |

**Returns: `ChunkedRestAdapter`**

| Method          | Signature                               | Description                                 |
| --------------- | --------------------------------------- | ------------------------------------------- |
| `upload`        | `(file: File) => Promise<UploadResult>` | Uploads a file in chunks                    |
| `pause`         | `() => void`                            | Pauses the upload                           |
| `resume`        | `() => Promise<void>`                   | Resumes a paused upload                     |
| `abort`         | `() => void`                            | Aborts current upload                       |
| `clear`         | `() => void`                            | Clears upload state                         |
| `getOffset`     | `() => Promise<number>`                 | Gets current upload offset                  |
| `isPaused`      | `() => boolean`                         | Whether upload is paused                    |
| `setOnStart`    | `(callback?) => void`                   | Sets start callback                         |
| `setOnProgress` | `(callback?) => void`                   | Sets progress callback `(progress, offset)` |
| `setOnFinish`   | `(callback?) => void`                   | Sets finish callback                        |
| `setOnError`    | `(callback?) => void`                   | Sets error callback                         |

### Cross-process resume [#cross-process-resume]

The TUS and chunked-REST adapters can resume an interrupted upload after a page refresh,
process restart, or another tab takes over. The flow has two opt-in pieces:

* **`urlStorage`** — persists the per-file resume identifier so the next call to `adapter.upload(file)`
  with the same file recognises it and resumes instead of starting over. Pass `defaultUrlStorage()`
  (browser → `localStorage`, elsewhere → in-memory) or implement the `UrlStorage` interface yourself.
* **`UploadControl`** — a serializable handle. `toJSON()` returns a snapshot you can stash anywhere
  (URL query param, server, IndexedDB); `UploadControl.from(token)` rehydrates it in another process,
  and passing that control into `adapter.upload(file)` resumes the prior session.

```ts
import { createTusAdapter, defaultUrlStorage, UploadControl } from "@visulima/storage-client";

// First process — persistent storage takes care of resume across reloads.
const adapter = createTusAdapter({
    endpoint: "/api/upload/tus",
    urlStorage: defaultUrlStorage(),
});

await adapter.upload(file); // crashes? a later upload(file) resumes automatically

// Or hand off a snapshot to another process.
const control = new UploadControl();

void createTusAdapter({ endpoint: "/api/upload/tus", control }).upload(file);

// Later, in another tab/process:
const token = JSON.stringify(control); // or control.toJSON()
const restored = UploadControl.from(token);

await createTusAdapter({ endpoint: "/api/upload/tus", control: restored }).upload(file);
```

Both pieces are independent. Use `urlStorage` alone for transparent same-machine resume.
Use `UploadControl` alone (or together with `urlStorage`) when you need to drive pause/abort/serialize
the upload from outside the adapter.

**Types**

| Type                     | Description                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `UploadControl`          | Class with `pause()`, `resume()`, `abort()`, `toJSON()`, and `UploadControl.from(token)`                    |
| `UploadControlSnapshot`  | Serializable shape — `{ v, protocol, endpoint, fingerprint, uploadUrl, offset? }`                           |
| `UrlStorage`             | Interface — `addEntry / findEntry / listEntries / removeEntry` (all async)                                  |
| `MemoryUrlStorage`       | In-process implementation (no persistence)                                                                  |
| `LocalStorageUrlStorage` | Browser-localStorage implementation. Constructor throws if no `localStorage` is available                   |
| `defaultUrlStorage()`    | Returns `LocalStorageUrlStorage` if available, otherwise falls back to `MemoryUrlStorage`                   |
| `FingerprintFn`          | `(input: { endpoint, file, protocol }) => string \| Promise<string>` — override to customise the resume key |

### Utility Functions [#utility-functions]

```ts
import {
    buildUrl,
    fetchFile,
    fetchJson,
    fetchHead,
    deleteRequest,
    putFile,
    patchChunk,
    parseApiError,
    extractFileMetaFromHeaders,
} from "@visulima/storage-client";
```

| Function                     | Signature                                           | Description                                  |
| ---------------------------- | --------------------------------------------------- | -------------------------------------------- |
| `buildUrl`                   | `(baseUrl, path, params?) => string`                | Builds URL with query parameters             |
| `fetchFile`                  | `(url) => Promise<Blob>`                            | Fetches a file as Blob with error handling   |
| `fetchJson`                  | `<T>(url) => Promise<T>`                            | Fetches JSON with error handling             |
| `fetchHead`                  | `(url) => Promise<Headers>`                         | Fetches metadata via HEAD request            |
| `deleteRequest`              | `(url) => Promise<void>`                            | Sends DELETE request with error handling     |
| `putFile`                    | `(url, file, onProgress?) => Promise<{...}>`        | PUT request with progress tracking           |
| `patchChunk`                 | `(url, chunk, offset, checksum?) => Promise<{...}>` | PATCH request for chunk uploads              |
| `parseApiError`              | `(response) => Promise<Error>`                      | Parses error response from API               |
| `extractFileMetaFromHeaders` | `(id, headers) => FileMeta`                         | Extracts file metadata from response headers |

### `storageQueryKeys` [#storagequerykeys]

Query key factory for TanStack Query integration. Provides consistent cache key generation across all hooks.

```ts
import { storageQueryKeys } from "@visulima/storage-client";

// Base key
storageQueryKeys.all; // ["storage"]

// File keys
storageQueryKeys.files.all(endpoint);
storageQueryKeys.files.detail(endpoint, id, transformParams?);
storageQueryKeys.files.list(endpoint, { limit?, page? });
storageQueryKeys.files.meta(endpoint, id);
storageQueryKeys.files.head(endpoint, id);

// Transform keys
storageQueryKeys.transform.all(endpoint);
storageQueryKeys.transform.file(endpoint, id, transformParams);
storageQueryKeys.transform.metadata(endpoint);
```

***

## Types [#types]

### `FileMeta` [#filemeta]

File metadata returned from the server.

```ts
interface FileMeta {
    id: string;
    name?: string;
    originalName?: string;
    contentType?: string;
    size?: number;
    bytesWritten?: number;
    createdAt?: string;
    metadata?: Record<string, unknown>;
    status?: "completed" | "part" | "deleted" | "created";
}
```

### `UploadResult` [#uploadresult]

Result returned after a successful file upload. Extends `FileMeta`.

```ts
interface UploadResult extends FileMeta {
    filename?: string;
    offset?: number;
    url?: string;
}
```

### `UploadMethod` [#uploadmethod]

```ts
type UploadMethod = "auto" | "multipart" | "tus" | "chunked-rest";
```

### `UploadItem` [#uploaditem]

State of an individual upload item tracked by the uploader.

```ts
interface UploadItem {
    id: string;
    file: File;
    status: "pending" | "uploading" | "completed" | "error" | "aborted";
    completed: number; // Progress percentage (0-100)
    loaded: number; // Bytes uploaded so far
    size: number; // Total file size in bytes
    error?: string;
    batchId?: string;
    retryCount?: number;
    url?: string;
    uploadResponse?: { data?: unknown; response?: string };
}
```

### `BatchState` [#batchstate]

State of a batch upload.

```ts
interface BatchState {
    id: string;
    itemIds: string[];
    status: "pending" | "uploading" | "completed" | "error" | "cancelled";
    progress: number; // Aggregate progress (0-100)
    totalCount: number;
    completedCount: number;
    errorCount: number;
}
```

### `UploaderEventType` [#uploadereventtype]

```ts
type UploaderEventType =
    | "ITEM_START"
    | "ITEM_PROGRESS"
    | "ITEM_FINISH"
    | "ITEM_ERROR"
    | "ITEM_ABORT"
    | "BATCH_START"
    | "BATCH_PROGRESS"
    | "BATCH_FINISH"
    | "BATCH_ERROR"
    | "BATCH_CANCELLED"
    | "BATCH_FINALIZE"
    | "BATCH_COMPLETE";
```

### `ApiError` [#apierror]

```ts
interface ApiError {
    error: {
        code: string;
        message: string;
        name?: string;
    };
}
```

### `FileHeadMetadata` [#fileheadmetadata]

Metadata returned from HEAD requests.

```ts
interface FileHeadMetadata {
    contentLength?: number;
    contentType?: string;
    etag?: string;
    lastModified?: string;
    uploadOffset?: number;
    uploadComplete?: boolean;
    uploadExpires?: string;
    chunkedUpload?: boolean;
    receivedChunks?: number[];
}
```

### `FileListResponse` [#filelistresponse]

Response from file list queries.

```ts
interface FileListResponse {
    data: FileMeta[];
    meta?: {
        page?: number;
        perPage?: number;
        total?: number;
        firstPage?: number;
        lastPage?: number;
        firstPageUrl?: string;
        lastPageUrl?: string;
        nextPageUrl?: string | undefined;
        previousPageUrl?: string | undefined;
    };
}
```

### `TransformOptions` [#transformoptions]

Options for file transformation (images, etc.).

```ts
interface TransformOptions {
    width?: number;
    height?: number;
    quality?: number; // 0-100
    format?: string; // "jpeg", "png", "webp", etc.
    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
    [key: string]: string | number | boolean | undefined;
}
```

### `TransformMetadata` [#transformmetadata]

Available transformation capabilities.

```ts
interface TransformMetadata {
    formats?: string[];
    parameters?: string[];
}
```

### `BatchDeleteResult` [#batchdeleteresult]

```ts
interface BatchDeleteResult {
    successful?: number;
    failed?: number;
}
```

***

## React Hooks [#react-hooks]

All React hooks are imported from `@visulima/storage-client/react`. They require `@tanstack/react-query` and a `QueryClientProvider` to be set up in your component tree.

### Upload Hooks [#upload-hooks]

#### `useUpload` [#useupload]

Unified upload hook with automatic method selection based on provided endpoints and file size.

```ts
const {
    upload, // (file: File) => Promise<UploadResult>
    abort, // () => void
    reset, // () => void
    progress, // number (0-100)
    isUploading, // boolean
    isPaused, // boolean | undefined
    error, // Error | undefined
    result, // UploadResult | undefined
    currentMethod, // UploadMethod
    offset, // number | undefined
    pause, // (() => void) | undefined
    resume, // (() => Promise<void>) | undefined
} = useUpload(options);
```

**Options: `UseUploadOptions`**

| Property              | Type                           | Default                   | Description                                |
| --------------------- | ------------------------------ | ------------------------- | ------------------------------------------ |
| `endpointMultipart`   | `string`                       | -                         | Multipart upload endpoint URL              |
| `endpointTus`         | `string`                       | -                         | TUS upload endpoint URL                    |
| `endpointChunkedRest` | `string`                       | -                         | Chunked REST upload endpoint URL           |
| `method`              | `UploadMethod`                 | auto-detected             | Upload method to use                       |
| `chunkSize`           | `number`                       | 1MB (TUS) / 5MB (chunked) | Chunk size                                 |
| `tusThreshold`        | `number`                       | `10485760` (10MB)         | File size threshold for auto-selecting TUS |
| `metadata`            | `Record<string, string>`       | -                         | Additional metadata                        |
| `retry`               | `boolean`                      | -                         | Enable automatic retry (TUS/chunked only)  |
| `maxRetries`          | `number`                       | -                         | Maximum retry attempts (TUS/chunked only)  |
| `onStart`             | `() => void`                   | -                         | Called when upload starts                  |
| `onProgress`          | `(progress: number) => void`   | -                         | Called when progress updates               |
| `onSuccess`           | `(file: UploadResult) => void` | -                         | Called on success                          |
| `onError`             | `(error: Error) => void`       | -                         | Called on failure                          |
| `onPause`             | `() => void`                   | -                         | Called when paused (TUS/chunked only)      |
| `onResume`            | `() => void`                   | -                         | Called when resumed (TUS/chunked only)     |

#### `useMultipartUpload` [#usemultipartupload]

Hook for traditional multipart/form-data uploads.

```ts
const { upload, progress, isUploading, error, result, reset } = useMultipartUpload({
    endpoint: "/api/upload/multipart",
});
```

**Options: `UseMultipartUploadOptions`**

| Property     | Type                           | Required | Description                  |
| ------------ | ------------------------------ | -------- | ---------------------------- |
| `endpoint`   | `string`                       | Yes      | Upload endpoint URL          |
| `metadata`   | `Record<string, string>`       | No       | Additional metadata          |
| `onStart`    | `() => void`                   | No       | Called when upload starts    |
| `onProgress` | `(progress: number) => void`   | No       | Called when progress updates |
| `onSuccess`  | `(file: UploadResult) => void` | No       | Called on success            |
| `onError`    | `(error: Error) => void`       | No       | Called on failure            |

#### `useTusUpload` [#usetusupload]

Hook for TUS resumable uploads with pause/resume support.

```ts
const { upload, pause, resume, abort, progress, isUploading, isPaused, offset, error, result, reset } = useTusUpload({
    endpoint: "/api/upload/tus",
});
```

**Options: `UseTusUploadOptions`**

| Property      | Type                           | Required | Default              | Description                                                                          |
| ------------- | ------------------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------ |
| `endpoint`    | `string`                       | Yes      | -                    | TUS upload endpoint URL                                                              |
| `chunkSize`   | `number`                       | No       | `1048576` (1MB)      | Chunk size                                                                           |
| `metadata`    | `Record<string, string>`       | No       | -                    | Additional metadata                                                                  |
| `retry`       | `boolean`                      | No       | -                    | Enable automatic retry                                                               |
| `maxRetries`  | `number`                       | No       | -                    | Maximum retry attempts                                                               |
| `control`     | `UploadControl`                | No       | -                    | Unified pause/resume/abort handle, see [Cross-process resume](#cross-process-resume) |
| `fingerprint` | `FingerprintFn`                | No       | `defaultFingerprint` | Override the per-file resume key                                                     |
| `urlStorage`  | `UrlStorage`                   | No       | -                    | Persistent storage for resume URLs; opt in via `defaultUrlStorage()`                 |
| `onStart`     | `() => void`                   | No       | -                    | Called when upload starts                                                            |
| `onProgress`  | `(progress: number) => void`   | No       | -                    | Called when progress updates                                                         |
| `onSuccess`   | `(file: UploadResult) => void` | No       | -                    | Called on success                                                                    |
| `onError`     | `(error: Error) => void`       | No       | -                    | Called on failure                                                                    |
| `onPause`     | `() => void`                   | No       | -                    | Called when paused                                                                   |
| `onResume`    | `() => void`                   | No       | -                    | Called when resumed                                                                  |

#### `useChunkedRestUpload` [#usechunkedrestupload]

Hook for client-side chunked REST uploads with pause/resume support.

```ts
const { upload, pause, resume, abort, progress, isUploading, isPaused, offset, error, result, reset } = useChunkedRestUpload({
    endpoint: "/api/upload/chunked-rest",
    chunkSize: 5 * 1024 * 1024,
});
```

**Options: `UseChunkedRestUploadOptions`**

| Property      | Type                                         | Required | Default              | Description                                                                          |
| ------------- | -------------------------------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------ |
| `endpoint`    | `string`                                     | Yes      | -                    | Chunked REST upload endpoint URL                                                     |
| `chunkSize`   | `number`                                     | No       | `5242880` (5MB)      | Chunk size                                                                           |
| `metadata`    | `Record<string, string>`                     | No       | -                    | Additional metadata                                                                  |
| `retry`       | `boolean`                                    | No       | -                    | Enable automatic retry                                                               |
| `maxRetries`  | `number`                                     | No       | -                    | Maximum retry attempts                                                               |
| `control`     | `UploadControl`                              | No       | -                    | Unified pause/resume/abort handle, see [Cross-process resume](#cross-process-resume) |
| `fingerprint` | `FingerprintFn`                              | No       | `defaultFingerprint` | Override the per-file resume key                                                     |
| `urlStorage`  | `UrlStorage`                                 | No       | -                    | Persistent storage for resume identifiers; opt in via `defaultUrlStorage()`          |
| `onStart`     | `() => void`                                 | No       | -                    | Called when upload starts                                                            |
| `onProgress`  | `(progress: number, offset: number) => void` | No       | -                    | Called when progress updates                                                         |
| `onSuccess`   | `(file: UploadResult) => void`               | No       | -                    | Called on success                                                                    |
| `onError`     | `(error: Error) => void`                     | No       | -                    | Called on failure                                                                    |
| `onPause`     | `() => void`                                 | No       | -                    | Called when paused                                                                   |
| `onResume`    | `() => void`                                 | No       | -                    | Called when resumed                                                                  |

#### `useBatchUpload` [#usebatchupload]

Hook for uploading multiple files simultaneously as a batch.

```ts
const { uploadBatch, abortBatch, progress, isUploading, items, completedCount, errorCount, error, reset } = useBatchUpload({
    endpoint: "/api/upload/multipart",
});
```

**Options: `UseBatchUploadOptions`**

| Property     | Type                                                 | Required | Description                  |
| ------------ | ---------------------------------------------------- | -------- | ---------------------------- |
| `endpoint`   | `string`                                             | Yes      | Upload endpoint URL          |
| `metadata`   | `Record<string, string>`                             | No       | Additional metadata          |
| `onStart`    | `(batchId: string) => void`                          | No       | Called when batch starts     |
| `onProgress` | `(progress: number, batchId: string) => void`        | No       | Called when progress updates |
| `onSuccess`  | `(results: UploadResult[], batchId: string) => void` | No       | Called on success            |
| `onError`    | `(error: Error, batchId: string) => void`            | No       | Called on failure            |

**Returns: `UseBatchUploadReturn`**

| Property         | Type                          | Description                                |
| ---------------- | ----------------------------- | ------------------------------------------ |
| `uploadBatch`    | `(files: File[]) => string[]` | Uploads files as a batch, returns item IDs |
| `abortBatch`     | `(batchId: string) => void`   | Aborts a specific batch                    |
| `items`          | `UploadItem[]`                | All upload items in current batch          |
| `progress`       | `number`                      | Current batch progress (0-100)             |
| `isUploading`    | `boolean`                     | Whether a batch is uploading               |
| `completedCount` | `number`                      | Number of completed items                  |
| `errorCount`     | `number`                      | Number of failed items                     |
| `error`          | `Error \| undefined`          | Last batch error                           |
| `reset`          | `() => void`                  | Reset batch state                          |

### File Input Hooks [#file-input-hooks]

#### `useFileInput` [#usefileinput]

Hook for file input handling with drag and drop support.

```ts
const { files, inputRef, handleFileChange, handleDrop, handleDragOver, handleDragLeave, openFileDialog, reset } = useFileInput({
    multiple: true,
    accept: "image/*",
});
```

**Options: `UseFileInputOptions`**

| Property          | Type                      | Description                                     |
| ----------------- | ------------------------- | ----------------------------------------------- |
| `accept`          | `string`                  | Accept file types (e.g., `"image/*"`, `".pdf"`) |
| `multiple`        | `boolean`                 | Whether to allow multiple file selection        |
| `onFilesSelected` | `(files: File[]) => void` | Callback when files are selected                |

**Returns: `UseFileInputReturn`**

| Property           | Type                                | Description                        |
| ------------------ | ----------------------------------- | ---------------------------------- |
| `files`            | `File[]`                            | Currently selected files           |
| `inputRef`         | `React.RefObject<HTMLInputElement>` | Ref for the file input element     |
| `handleFileChange` | `(event) => void`                   | Handler for input change events    |
| `handleDrop`       | `(event) => void`                   | Handler for drop events            |
| `handleDragOver`   | `(event) => void`                   | Handler for drag over events       |
| `handleDragLeave`  | `(event) => void`                   | Handler for drag leave events      |
| `openFileDialog`   | `() => void`                        | Opens file dialog programmatically |
| `reset`            | `() => void`                        | Resets selected files              |

#### `usePasteUpload` [#usepasteupload]

Hook for handling clipboard paste uploads.

```ts
const { handlePaste, pastedFiles, reset } = usePasteUpload({
    filter: (file) => file.type.startsWith("image/"),
    onFilesPasted: (files) => console.log("Pasted:", files),
});
```

**Options: `UsePasteUploadOptions`**

| Property        | Type                      | Description                            |
| --------------- | ------------------------- | -------------------------------------- |
| `filter`        | `(file: File) => boolean` | Filter function to accept/reject files |
| `onFilesPasted` | `(files: File[]) => void` | Callback when files are pasted         |

**Returns: `UsePasteUploadReturn`**

| Property      | Type              | Description              |
| ------------- | ----------------- | ------------------------ |
| `handlePaste` | `(event) => void` | Handler for paste events |
| `pastedFiles` | `File[]`          | Files that were pasted   |
| `reset`       | `() => void`      | Resets pasted files      |

### File Operation Hooks (Queries) [#file-operation-hooks-queries]

#### `useGetFile` [#usegetfile]

Fetches/downloads a file by ID using TanStack Query. Supports optional transformation parameters.

```ts
const { data, isLoading, error, meta, refetch } = useGetFile({
    endpoint: "/api/files",
    id: "file-123",
});
```

**Options: `UseGetFileOptions`**

| Property    | Type                                          | Required | Description                                   |
| ----------- | --------------------------------------------- | -------- | --------------------------------------------- |
| `endpoint`  | `string`                                      | Yes      | Base endpoint URL                             |
| `id`        | `string`                                      | Yes      | File ID to fetch                              |
| `enabled`   | `boolean`                                     | No       | Whether to enable the query (default: `true`) |
| `transform` | `Record<string, string \| number \| boolean>` | No       | Transformation parameters                     |
| `onSuccess` | `(data: Blob, meta?) => void`                 | No       | Success callback                              |
| `onError`   | `(error: Error) => void`                      | No       | Error callback                                |

**Returns: `UseGetFileReturn`**

| Property    | Type                    | Description                         |
| ----------- | ----------------------- | ----------------------------------- |
| `data`      | `Blob \| undefined`     | File data as Blob                   |
| `meta`      | `FileMeta \| undefined` | File metadata from response headers |
| `isLoading` | `boolean`               | Whether request is in progress      |
| `error`     | `Error \| undefined`    | Last request error                  |
| `refetch`   | `() => void`            | Refetch the file                    |

#### `useGetFileList` [#usegetfilelist]

Fetches a paginated list of files.

```ts
const { data, isLoading, error, refetch } = useGetFileList({
    endpoint: "/api/files",
    page: 1,
    limit: 20,
});
```

**Options: `UseGetFileListOptions`**

| Property    | Type                               | Required | Description                                   |
| ----------- | ---------------------------------- | -------- | --------------------------------------------- |
| `endpoint`  | `string`                           | Yes      | Base endpoint URL                             |
| `page`      | `number`                           | No       | Page number                                   |
| `limit`     | `number`                           | No       | Maximum elements to retrieve                  |
| `enabled`   | `boolean`                          | No       | Whether to enable the query (default: `true`) |
| `onSuccess` | `(data: FileListResponse) => void` | No       | Success callback                              |
| `onError`   | `(error: Error) => void`           | No       | Error callback                                |

#### `useGetFileMeta` [#usegetfilemeta]

Fetches file metadata by ID.

```ts
const { data, isLoading, error, refetch } = useGetFileMeta({
    endpoint: "/api/files",
    id: "file-123",
});
```

**Options: `UseGetFileMetaOptions`**

| Property    | Type                       | Required | Description                                   |
| ----------- | -------------------------- | -------- | --------------------------------------------- |
| `endpoint`  | `string`                   | Yes      | Base endpoint URL                             |
| `id`        | `string`                   | Yes      | File ID                                       |
| `enabled`   | `boolean`                  | No       | Whether to enable the query (default: `true`) |
| `onSuccess` | `(meta: FileMeta) => void` | No       | Success callback                              |
| `onError`   | `(error: Error) => void`   | No       | Error callback                                |

#### `useHeadFile` [#useheadfile]

Fetches file metadata via HEAD request. Useful for checking upload status without downloading.

```ts
const { data, isLoading, error, refetch } = useHeadFile({
    endpoint: "/api/files",
    id: "file-123",
});
```

**Options: `UseHeadFileOptions`**

| Property    | Type                               | Required | Description                                   |
| ----------- | ---------------------------------- | -------- | --------------------------------------------- |
| `endpoint`  | `string`                           | Yes      | Base endpoint URL                             |
| `id`        | `string`                           | Yes      | File ID                                       |
| `enabled`   | `boolean`                          | No       | Whether to enable the query (default: `true`) |
| `onSuccess` | `(meta: FileHeadMetadata) => void` | No       | Success callback                              |
| `onError`   | `(error: Error) => void`           | No       | Error callback                                |

### File Operation Hooks (Mutations) [#file-operation-hooks-mutations]

#### `useDeleteFile` [#usedeletefile]

Deletes a file by ID. Automatically invalidates related TanStack Query caches.

```ts
const { deleteFile, isLoading, error, reset } = useDeleteFile({
    endpoint: "/api/files",
});

await deleteFile("file-123");
```

**Options: `UseDeleteFileOptions`**

| Property    | Type                     | Required | Description       |
| ----------- | ------------------------ | -------- | ----------------- |
| `endpoint`  | `string`                 | Yes      | Base endpoint URL |
| `onSuccess` | `() => void`             | No       | Success callback  |
| `onError`   | `(error: Error) => void` | No       | Error callback    |

#### `useBatchDeleteFiles` [#usebatchdeletefiles]

Deletes multiple files by IDs. Automatically invalidates caches.

```ts
const { batchDeleteFiles, isLoading, error, reset } = useBatchDeleteFiles({
    endpoint: "/api/files",
});

const result = await batchDeleteFiles(["file-1", "file-2"]);
// result: { successful?: number, failed?: number }
```

**Options: `UseBatchDeleteFilesOptions`**

| Property    | Type                                  | Required | Description       |
| ----------- | ------------------------------------- | -------- | ----------------- |
| `endpoint`  | `string`                              | Yes      | Base endpoint URL |
| `onSuccess` | `(result: BatchDeleteResult) => void` | No       | Success callback  |
| `onError`   | `(error: Error) => void`              | No       | Error callback    |

#### `usePutFile` [#useputfile]

Creates or updates a file via PUT request with progress tracking.

```ts
const { putFile, progress, isLoading, error, data, reset } = usePutFile({
    endpoint: "/api/files",
});

await putFile("file-123", file);
```

**Options: `UsePutFileOptions`**

| Property     | Type                             | Required | Description       |
| ------------ | -------------------------------- | -------- | ----------------- |
| `endpoint`   | `string`                         | Yes      | Base endpoint URL |
| `onProgress` | `(progress: number) => void`     | No       | Progress callback |
| `onSuccess`  | `(result: UploadResult) => void` | No       | Success callback  |
| `onError`    | `(error: Error) => void`         | No       | Error callback    |

#### `usePatchChunk` [#usepatchchunk]

Uploads individual chunks for chunked uploads via PATCH request.

```ts
const { patchChunk, isLoading, error, data, reset } = usePatchChunk({
    endpoint: "/api/upload/chunked-rest",
});

await patchChunk("file-123", chunkBlob, offset, checksum);
```

**Options: `UsePatchChunkOptions`**

| Property    | Type                             | Required | Description       |
| ----------- | -------------------------------- | -------- | ----------------- |
| `endpoint`  | `string`                         | Yes      | Base endpoint URL |
| `onSuccess` | `(result: UploadResult) => void` | No       | Success callback  |
| `onError`   | `(error: Error) => void`         | No       | Error callback    |

### Transform Hooks [#transform-hooks]

#### `useTransformFile` [#usetransformfile]

Fetches a transformed file (e.g., resized image) using TanStack Query.

```ts
const { data, isLoading, error, meta, refetch } = useTransformFile({
    endpoint: "/api/files",
    id: "file-123",
    transform: { width: 800, height: 600, quality: 85 },
});
```

**Options: `UseTransformFileOptions`**

| Property    | Type                          | Required | Description                 |
| ----------- | ----------------------------- | -------- | --------------------------- |
| `endpoint`  | `string`                      | Yes      | Base endpoint URL           |
| `id`        | `string`                      | Yes      | File ID                     |
| `transform` | `TransformOptions`            | Yes      | Transformation parameters   |
| `enabled`   | `boolean`                     | No       | Whether to enable the query |
| `onSuccess` | `(data: Blob, meta?) => void` | No       | Success callback            |
| `onError`   | `(error: Error) => void`      | No       | Error callback              |

#### `useTransformMetadata` [#usetransformmetadata]

Fetches available transformation options from the server.

```ts
const { data, isLoading, error, refetch } = useTransformMetadata({
    endpoint: "/api/files",
});
// data: { formats?: string[], parameters?: string[] }
```

### Abort Hooks [#abort-hooks]

#### `useAbortAll` [#useabortall]

```ts
const { abortAll } = useAbortAll({ endpoint: "/api/upload/multipart" });
```

#### `useAbortBatch` [#useabortbatch]

```ts
const { abortBatch } = useAbortBatch({ endpoint: "/api/upload/multipart" });
abortBatch("batch-123");
```

#### `useAbortItem` [#useabortitem]

```ts
const { abortItem } = useAbortItem({ endpoint: "/api/upload/multipart" });
abortItem("item-123");
```

### Retry Hooks [#retry-hooks]

#### `useRetry` [#useretry]

```ts
const { retryItem } = useRetry({ endpoint: "/api/upload/multipart" });
retryItem("item-123");
```

#### `useBatchRetry` [#usebatchretry]

```ts
const { retryBatch } = useBatchRetry({ endpoint: "/api/upload/multipart" });
retryBatch("batch-123");
```

### Event Listener Hooks [#event-listener-hooks]

All listener hooks accept `endpoint` and `metadata` options, plus an event-specific callback.

| Hook                        | Callback           | Callback Signature            |
| --------------------------- | ------------------ | ----------------------------- |
| `useBatchStartListener`     | `onBatchStart`     | `(batch: BatchState) => void` |
| `useBatchProgressListener`  | `onBatchProgress`  | `(batch: BatchState) => void` |
| `useBatchFinishListener`    | `onBatchFinish`    | `(batch: BatchState) => void` |
| `useBatchErrorListener`     | `onBatchError`     | `(batch: BatchState) => void` |
| `useBatchCancelledListener` | `onBatchCancelled` | `(batch: BatchState) => void` |
| `useBatchFinalizeListener`  | `onBatchFinalize`  | `(batch: BatchState) => void` |
| `useRetryListener`          | `onRetry`          | `(item: UploadItem) => void`  |
| `useAllAbortListener`       | `onAbortAll`       | `() => void`                  |

***

## Solid Primitives [#solid-primitives]

All Solid.js primitives are imported from `@visulima/storage-client/solid`. They require `@tanstack/solid-query` and a `QueryClientProvider` in your component tree.

Solid primitives follow the same API patterns as React hooks but use Solid's reactive primitives (`Accessor`, `createSignal`, `createMemo`) instead of React state. Return values that are reactive are wrapped as `Accessor<T>` (called as functions, e.g., `progress()` instead of `progress`).

### Upload Primitives [#upload-primitives]

| Primitive                 | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `createUpload`            | Unified upload with automatic method selection |
| `createMultipartUpload`   | Multipart/form-data uploads                    |
| `createTusUpload`         | TUS resumable uploads with pause/resume        |
| `createChunkedRestUpload` | Chunked REST uploads with pause/resume         |
| `createBatchUpload`       | Batch upload for multiple files                |

### File Input Primitives [#file-input-primitives]

| Primitive           | Description                           |
| ------------------- | ------------------------------------- |
| `createFileInput`   | File input with drag and drop support |
| `createPasteUpload` | Clipboard paste upload handling       |

### File Operation Primitives [#file-operation-primitives]

| Primitive                | Description                  |
| ------------------------ | ---------------------------- |
| `createGetFile`          | Fetch/download a file by ID  |
| `createGetFileList`      | Fetch paginated file list    |
| `createGetFileMeta`      | Fetch file metadata          |
| `createHeadFile`         | HEAD request for file status |
| `createDeleteFile`       | Delete a file                |
| `createBatchDeleteFiles` | Batch delete files           |
| `createPutFile`          | Create/update a file via PUT |
| `createPatchChunk`       | Upload individual chunks     |

### Transform Primitives [#transform-primitives]

| Primitive                 | Description                       |
| ------------------------- | --------------------------------- |
| `createTransformFile`     | Fetch transformed file            |
| `createTransformMetadata` | Fetch transformation capabilities |

### Abort Primitives [#abort-primitives]

| Primitive          | Description           |
| ------------------ | --------------------- |
| `createAbortAll`   | Abort all uploads     |
| `createAbortBatch` | Abort a batch         |
| `createAbortItem`  | Abort a specific item |

### Retry Primitives [#retry-primitives]

| Primitive          | Description                   |
| ------------------ | ----------------------------- |
| `createRetry`      | Retry a failed item           |
| `createBatchRetry` | Retry failed items in a batch |

### Event Listener Primitives [#event-listener-primitives]

| Primitive                      | Description                      |
| ------------------------------ | -------------------------------- |
| `createBatchStartListener`     | Listen to batch start events     |
| `createBatchProgressListener`  | Listen to batch progress events  |
| `createBatchFinishListener`    | Listen to batch finish events    |
| `createBatchErrorListener`     | Listen to batch error events     |
| `createBatchCancelledListener` | Listen to batch cancelled events |
| `createBatchFinalizeListener`  | Listen to batch finalize events  |
| `createRetryListener`          | Listen to retry events           |
| `createAllAbortListener`       | Listen to abort all events       |

***

## Vue Composables [#vue-composables]

All Vue composables are imported from `@visulima/storage-client/vue`. They require `@tanstack/vue-query` and `VueQueryPlugin` to be installed. The API mirrors the React hooks using the same naming convention (`useUpload`, `useTusUpload`, etc.) with Vue's reactivity system (`Ref` instead of React state).

***

## Svelte Stores [#svelte-stores]

All Svelte stores are imported from `@visulima/storage-client/svelte`. They require `@tanstack/svelte-query` and follow Svelte store conventions. Function names use the `create*` prefix (e.g., `createUpload`, `createTusUpload`). Return values are Svelte stores accessed with the `$` prefix in templates (e.g., `$progress`, `$isUploading`).


# Introduction (/docs/packages/storage-client)



# Storage Client [#storage-client]

**Simple and easy file uploads for React | Vue | Solid | Svelte**

The Visulima Storage Client is a powerful, framework-agnostic library for handling file uploads in modern web applications. It provides a unified API across React, Vue, Nuxt, Solid, and Svelte with support for multiple upload methods, progress tracking, retry mechanisms, and batch operations.

## Features [#features]

* **Framework Support** - First-class support for React, Vue/Nuxt, Solid, and Svelte
* **Multiple Upload Methods** - Multipart (form-based), TUS (resumable), and chunked REST uploads
* **Auto-detection** - Automatically selects the best upload method based on file size and available endpoints
* **Progress Tracking** - Real-time upload progress with percentage and byte-level tracking
* **Batch Operations** - Upload multiple files simultaneously with batch progress tracking
* **Retry Mechanism** - Built-in retry with exponential backoff for failed uploads
* **File Management** - Get, list, delete files with full metadata support
* **TypeScript Ready** - Full TypeScript support with comprehensive type definitions
* **TanStack Query Integration** - Built on TanStack Query for powerful caching and state management
* **Drag & Drop Support** - Built-in file input hooks with drag & drop functionality
* **Paste Upload** - Support for pasting images from clipboard
* **Transform Support** - Transform files and metadata on upload
* **Abort Control** - Cancel uploads at any time with abort functionality

## Upload Methods [#upload-methods]

### Multipart Upload [#multipart-upload]

Traditional `multipart/form-data` uploads, perfect for small to medium files and web forms.

```tsx
import { useUpload } from "@visulima/storage-client/react";

const { upload, progress, isUploading } = useUpload({
    endpointMultipart: "/api/upload/multipart",
});

await upload(file);
```

### TUS Upload [#tus-upload]

Resumable uploads using the TUS protocol, ideal for large files and unreliable networks.

```tsx
import { useTusUpload } from "@visulima/storage-client/react";

const { upload, pause, resume, progress } = useTusUpload({
    endpointTus: "/api/upload/tus",
});

await upload(file);
// Can pause and resume later
pause();
resume();
```

### Chunked REST Upload [#chunked-rest-upload]

Client-side chunked uploads for large files without requiring TUS server support.

```tsx
import { useChunkedRestUpload } from "@visulima/storage-client/react";

const { upload, progress } = useChunkedRestUpload({
    endpointChunkedRest: "/api/upload/chunked-rest",
    chunkSize: 5 * 1024 * 1024, // 5MB chunks
});

await upload(file);
```

## Quick Start [#quick-start]

### React [#react]

```tsx
import { useUpload } from "@visulima/storage-client/react";

function UploadComponent() {
    const { upload, progress, isUploading, error, result } = useUpload({
        endpointMultipart: "/api/upload/multipart",
        onProgress: (progress) => console.log(`Upload: ${progress}%`),
        onSuccess: (file) => console.log("Upload complete:", file.id),
    });

    const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
        const file = e.target.files?.[0];
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            {isUploading && <div>Progress: {progress}%</div>}
            {error && <div>Error: {error.message}</div>}
            {result && <div>File ID: {result.id}</div>}
        </div>
    );
}
```

### Vue / Nuxt [#vue--nuxt]

```vue
<template>
    <div>
        <input type="file" @change="handleFileChange" />
        <div v-if="isUploading">Progress: {{ progress }}%</div>
        <div v-if="error">Error: {{ error.message }}</div>
        <div v-if="result">File ID: {{ result.id }}</div>
    </div>
</template>

<script setup lang="ts">
import { useUpload } from "@visulima/storage-client/vue";

const { upload, progress, isUploading, error, result } = useUpload({
    endpointMultipart: "/api/upload/multipart",
});

const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
        await upload(file);
    }
};
</script>
```

### Solid [#solid]

```tsx
import { createUpload } from "@visulima/storage-client/solid";

function UploadComponent() {
    const { upload, progress, isUploading, error, result } = createUpload({
        endpointMultipart: "/api/upload/multipart",
    });

    const handleFileChange = async (e: Event) => {
        const target = e.target as HTMLInputElement;
        const file = target.files?.[0];
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            {isUploading() && <div>Progress: {progress()}%</div>}
            {error() && <div>Error: {error()?.message}</div>}
            {result() && <div>File ID: {result()?.id}</div>}
        </div>
    );
}
```

### Svelte [#svelte]

```svelte
<script lang="ts">
  import { createUpload } from "@visulima/storage-client/svelte";

  const { upload, progress, isUploading, error, result } = createUpload({
    endpointMultipart: "/api/upload/multipart",
  });

  async function handleFileChange(e: Event) {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
      await upload(file);
    }
  }
</script>

<div>
  <input type="file" on:change={handleFileChange} />
  {#if $isUploading}
    <div>Progress: {$progress}%</div>
  {/if}
  {#if $error}
    <div>Error: {$error.message}</div>
  {/if}
  {#if $result}
    <div>File ID: {$result.id}</div>
  {/if}
</div>
```

## What's Next? [#whats-next]

* [Installation Guide](/docs/packages/storage-client/installation) - Learn how to install and set up the storage client
* [React Guide](/docs/packages/storage-client/react) - Complete React usage guide
* [Vue / Nuxt Guide](/docs/packages/storage-client/vue) - Complete Vue and Nuxt usage guide
* [Solid Guide](/docs/packages/storage-client/solid) - Complete Solid usage guide
* [Svelte Guide](/docs/packages/storage-client/svelte) - Complete Svelte usage guide


# Installation (/docs/packages/storage-client/installation)



# Installation [#installation]

Install the storage client package and the required framework dependencies.

## Prerequisites [#prerequisites]

The storage client requires TanStack Query (formerly React Query) for state management. You'll need to install the appropriate version for your framework:

* **React**: `@tanstack/react-query` >= 5.90.10
* **Vue**: `@tanstack/vue-query` >= 5.91.2
* **Solid**: `@tanstack/solid-query` >= 5.90.13
* **Svelte**: `@tanstack/svelte-query` >= 6.0.8

## React [#react]

```bash
npm install @visulima/storage-client @tanstack/react-query react
```

```bash
yarn add @visulima/storage-client @tanstack/react-query react
```

```bash
pnpm add @visulima/storage-client @tanstack/react-query react
```

### Setup QueryClient [#setup-queryclient]

Wrap your app with `QueryClientProvider`:

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactNode } from "react";

const queryClient = new QueryClient();

function App({ children }: { children: ReactNode }) {
    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}
```

## Vue / Nuxt [#vue--nuxt]

```bash
npm install @visulima/storage-client @tanstack/vue-query vue
```

```bash
yarn add @visulima/storage-client @tanstack/vue-query vue
```

```bash
pnpm add @visulima/storage-client @tanstack/vue-query vue
```

### Setup QueryClient [#setup-queryclient-1]

For Vue 3:

```ts
import { createApp } from "vue";
import { VueQueryPlugin } from "@tanstack/vue-query";

const app = createApp(App);
app.use(VueQueryPlugin);
app.mount("#app");
```

### Nuxt 3 Setup [#nuxt-3-setup]

Create a plugin file:

```ts
// plugins/vue-query.client.ts
import { VueQueryPlugin } from "@tanstack/vue-query";

export default defineNuxtPlugin((nuxtApp) => {
    nuxtApp.vueApp.use(VueQueryPlugin);
});
```

## Solid [#solid]

```bash
npm install @visulima/storage-client @tanstack/solid-query solid-js
```

```bash
yarn add @visulima/storage-client @tanstack/solid-query solid-js
```

```bash
pnpm add @visulima/storage-client @tanstack/solid-query solid-js
```

### Setup QueryClient [#setup-queryclient-2]

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";

const queryClient = new QueryClient();

function App() {
    return <QueryClientProvider client={queryClient}>{/* Your app */}</QueryClientProvider>;
}
```

## Svelte [#svelte]

```bash
npm install @visulima/storage-client @tanstack/svelte-query svelte
```

```bash
yarn add @visulima/storage-client @tanstack/svelte-query svelte
```

```bash
pnpm add @visulima/storage-client @tanstack/svelte-query svelte
```

### Setup QueryClient [#setup-queryclient-3]

```svelte
<script lang="ts">
  import { QueryClient, QueryClientProvider } from "@tanstack/svelte-query";

  const queryClient = new QueryClient();
</script>

<QueryClientProvider client={queryClient}>
  <!-- Your app -->
</QueryClientProvider>
```

## Import Paths [#import-paths]

Import hooks/composables from framework-specific paths:

```ts
// React
import { useUpload } from "@visulima/storage-client/react";

// Vue
import { useUpload } from "@visulima/storage-client/vue";

// Solid
import { createUpload } from "@visulima/storage-client/solid";

// Svelte
import { createUpload } from "@visulima/storage-client/svelte";
```

## TypeScript Support [#typescript-support]

The package includes full TypeScript definitions. No additional `@types` packages are required.

## Next Steps [#next-steps]

* [React Guide](/docs/packages/storage-client/react) - Learn how to use the storage client with React
* [Vue / Nuxt Guide](/docs/packages/storage-client/vue) - Learn how to use the storage client with Vue and Nuxt
* [Solid Guide](/docs/packages/storage-client/solid) - Learn how to use the storage client with Solid
* [Svelte Guide](/docs/packages/storage-client/svelte) - Learn how to use the storage client with Svelte


# Next.js (/docs/packages/storage-client/nextjs)



# Next.js [#nextjs]

Use `@visulima/storage-client` with Next.js App Router for file uploads with server-side rendering support.

## Installation [#installation]

```bash
npm install @visulima/storage-client @tanstack/react-query react next
```

## Setup QueryClient Provider [#setup-queryclient-provider]

Create a providers component:

```tsx
// app/providers.tsx
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactNode, useState } from "react";

export function Providers({ children }: { children: ReactNode }) {
    const [queryClient] = useState(() => new QueryClient());

    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}
```

Use it in your root layout:

```tsx
// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <body>
                <Providers>{children}</Providers>
            </body>
        </html>
    );
}
```

## Client Component Example [#client-component-example]

Create a client component for uploads:

```tsx
// app/page.tsx
"use client";

import { useUpload } from "@visulima/storage-client/react";
import { useRef, useState } from "react";

export default function Home() {
    const [file, setFile] = useState<File | null>(null);
    const fileInputRef = useRef<HTMLInputElement>(null);
    const { error, isUploading, progress, result, upload } = useUpload({
        endpointMultipart: "/api/upload/multipart",
        endpointTus: "/api/upload/tus",
        onSuccess: (result) => {
            console.log("Upload successful:", result);
            setFile(null);
            if (fileInputRef.current) {
                fileInputRef.current.value = "";
            }
        },
        onError: (error) => {
            console.error("Upload error:", error);
        },
    });

    const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const selectedFile = e.target.files?.[0];
        setFile(selectedFile || null);
    };

    const handleUpload = async () => {
        if (file) {
            try {
                await upload(file);
            } catch (error_) {
                console.error("Upload failed:", error_);
            }
        }
    };

    return (
        <main>
            <h1>Storage Client - Next.js Example</h1>
            <div style={{ marginTop: "2rem" }}>
                <input disabled={isUploading} onChange={handleFileChange} ref={fileInputRef} type="file" />
                <button disabled={!file || isUploading} onClick={handleUpload} style={{ marginLeft: "1rem" }}>
                    {isUploading ? "Uploading..." : "Upload"}
                </button>
            </div>
            {isUploading && (
                <div style={{ marginTop: "1rem" }}>
                    <div>
                        Progress:
                        {progress}%
                    </div>
                    <progress max={100} value={progress} />
                </div>
            )}
            {error && (
                <div style={{ color: "red", marginTop: "1rem" }}>
                    Error:
                    {error.message}
                </div>
            )}
            {result && (
                <div style={{ color: "green", marginTop: "1rem" }}>
                    Upload complete! File:
                    {result.filename}
                </div>
            )}
        </main>
    );
}
```

## API Routes Setup [#api-routes-setup]

Set up upload endpoints using `@visulima/storage`:

```tsx
// app/api/upload/multipart/route.ts
import { createHandler } from "@visulima/storage/handler/http/nextjs";
import { storage } from "@/lib/storage";

const handler = createHandler({ storage, type: "multipart" });

export const POST = handler;
export const DELETE = handler;
export const GET = handler;
export const OPTIONS = handler;
```

```tsx
// app/api/upload/tus/route.ts
import { createHandler } from "@visulima/storage/handler/http/nextjs";
import { storage } from "@/lib/storage";

const handler = createHandler({ storage, type: "tus" });

export const POST = handler;
export const PATCH = handler;
export const HEAD = handler;
export const OPTIONS = handler;
```

```tsx
// app/api/upload/tus/[id]/route.ts
import { createHandler } from "@visulima/storage/handler/http/nextjs";
import { storage } from "@/lib/storage";

const handler = createHandler({ storage, type: "tus" });

export const PATCH = handler;
export const HEAD = handler;
export const DELETE = handler;
export const OPTIONS = handler;
```

```tsx
// app/api/upload/rest/route.ts
import { createHandler } from "@visulima/storage/handler/http/nextjs";
import { storage } from "@/lib/storage";

const handler = createHandler({ storage, type: "rest" });

export const POST = handler;
export const OPTIONS = handler;
```

```tsx
// app/api/upload/rest/[id]/route.ts
import { createHandler } from "@visulima/storage/handler/http/nextjs";
import { storage } from "@/lib/storage";

const handler = createHandler({ storage, type: "rest" });

export const PUT = handler;
export const OPTIONS = handler;
```

## Storage Configuration [#storage-configuration]

Create a storage instance:

```tsx
// lib/storage.ts
import { DiskStorage } from "@visulima/storage";

export const storage = new DiskStorage({
    directory: "./uploads",
});
```

## Server Actions (Alternative) [#server-actions-alternative]

You can also use Server Actions for uploads:

```tsx
// app/actions.ts
"use server";

import { storage } from "@/lib/storage";

export async function uploadFile(formData: FormData) {
    const file = formData.get("file") as File;
    if (!file) {
        throw new Error("No file provided");
    }

    const buffer = await file.arrayBuffer();
    const id = await storage.put(file.name, Buffer.from(buffer), {
        contentType: file.type,
    });

    return { id, filename: file.name };
}
```

## Environment Variables [#environment-variables]

Configure storage backend via environment variables:

```bash
# .env.local
UPLOAD_DIR=./uploads
S3_BUCKET=my-bucket
S3_REGION=us-east-1
```

## TypeScript Configuration [#typescript-configuration]

Ensure your `tsconfig.json` includes the necessary paths:

```json
{
    "compilerOptions": {
        "paths": {
            "@/*": ["./*"]
        }
    }
}
```

## Next Steps [#next-steps]

* [React Guide](/docs/packages/storage-client/react) - Learn React-specific features
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# React (/docs/packages/storage-client/react)



# React [#react]

Use `@visulima/storage-client` with React to handle file uploads with hooks and TanStack Query integration.

## Installation [#installation]

```bash
npm install @visulima/storage-client @tanstack/react-query react
```

## Setup QueryClient [#setup-queryclient]

Wrap your app with `QueryClientProvider`:

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactNode } from "react";

const queryClient = new QueryClient();

function App({ children }: { children: ReactNode }) {
    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}
```

## Basic Upload [#basic-upload]

Use the `useUpload` hook for automatic method selection:

```tsx
import { useUpload } from "@visulima/storage-client/react";
import { useState } from "react";

function UploadComponent() {
    const [file, setFile] = useState<File | null>(null);
    const { upload, progress, isUploading, error, result } = useUpload({
        endpointMultipart: "/api/upload/multipart",
        endpointTus: "/api/upload/tus",
        onSuccess: (result) => {
            console.log("Upload successful:", result);
        },
        onError: (error) => {
            console.error("Upload error:", error);
        },
    });

    const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        setFile(e.target.files?.[0] || null);
    };

    const handleUpload = async () => {
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} disabled={isUploading} />
            <button onClick={handleUpload} disabled={!file || isUploading}>
                {isUploading ? "Uploading..." : "Upload"}
            </button>
            {isUploading && <div>Progress: {progress}%</div>}
            {error && <div>Error: {error.message}</div>}
            {result && <div>Upload complete! File: {result.filename}</div>}
        </div>
    );
}
```

## Multipart Upload [#multipart-upload]

For traditional form-based uploads:

```tsx
import { useMultipartUpload } from "@visulima/storage-client/react";

function MultipartUpload() {
    const { upload, progress, isUploading } = useMultipartUpload({
        endpoint: "/api/upload/multipart",
    });

    const handleUpload = async (file: File) => {
        await upload(file);
    };

    return (
        <div>
            <input
                type="file"
                onChange={(e) => {
                    const file = e.target.files?.[0];
                    if (file) handleUpload(file);
                }}
            />
            {isUploading && <progress value={progress} max={100} />}
        </div>
    );
}
```

## TUS Resumable Upload [#tus-resumable-upload]

For large files with pause/resume support:

```tsx
import { useTusUpload } from "@visulima/storage-client/react";

function TusUpload() {
    const { upload, pause, resume, progress, isUploading, isPaused } = useTusUpload({
        endpoint: "/api/upload/tus",
    });

    const handleUpload = async (file: File) => {
        await upload(file);
    };

    return (
        <div>
            <input
                type="file"
                onChange={(e) => {
                    const file = e.target.files?.[0];
                    if (file) handleUpload(file);
                }}
            />
            {isUploading && (
                <div>
                    <progress value={progress} max={100} />
                    {isPaused ? <button onClick={resume}>Resume</button> : <button onClick={pause}>Pause</button>}
                </div>
            )}
        </div>
    );
}
```

## Chunked REST Upload [#chunked-rest-upload]

For client-side chunked uploads:

```tsx
import { useChunkedRestUpload } from "@visulima/storage-client/react";

function ChunkedUpload() {
    const { upload, progress, isUploading } = useChunkedRestUpload({
        endpoint: "/api/upload/chunked-rest",
        chunkSize: 5 * 1024 * 1024, // 5MB chunks
    });

    const handleUpload = async (file: File) => {
        await upload(file);
    };

    return (
        <div>
            <input
                type="file"
                onChange={(e) => {
                    const file = e.target.files?.[0];
                    if (file) handleUpload(file);
                }}
            />
            {isUploading && <progress value={progress} max={100} />}
        </div>
    );
}
```

## Batch Upload [#batch-upload]

Upload multiple files simultaneously:

```tsx
import { useBatchUpload } from "@visulima/storage-client/react";

function BatchUpload() {
    const { uploadBatch, progress, isUploading, items, completedCount, errorCount } = useBatchUpload({
        endpoint: "/api/upload/multipart",
        onSuccess: (results) => {
            console.log("Batch upload complete:", results);
        },
    });

    const handleFilesChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const files = Array.from(e.target.files || []);
        if (files.length > 0) {
            uploadBatch(files);
        }
    };

    return (
        <div>
            <input type="file" multiple onChange={handleFilesChange} />
            {isUploading && (
                <div>
                    <div>Progress: {progress}%</div>
                    <div>
                        Completed: {completedCount} / {items.length}
                    </div>
                    <div>Errors: {errorCount}</div>
                </div>
            )}
        </div>
    );
}
```

## File Input Hook [#file-input-hook]

Use the `useFileInput` hook for drag & drop support:

```tsx
import { useFileInput } from "@visulima/storage-client/react";
import { useUpload } from "@visulima/storage-client/react";

function DragDropUpload() {
    const { files, inputRef, handleFileChange, handleDrop, handleDragOver, openFileDialog } = useFileInput({
        multiple: true,
        onFilesSelected: (files) => {
            console.log("Files selected:", files);
        },
    });

    const { uploadBatch } = useBatchUpload({
        endpoint: "/api/upload/multipart",
    });

    const handleUpload = () => {
        if (files.length > 0) {
            uploadBatch(files);
        }
    };

    return (
        <div onDrop={handleDrop} onDragOver={handleDragOver} style={{ border: "2px dashed #ccc", padding: "2rem", textAlign: "center" }}>
            <input ref={inputRef} type="file" multiple onChange={handleFileChange} style={{ display: "none" }} />
            <p>Drag and drop files here or</p>
            <button onClick={openFileDialog}>Select Files</button>
            {files.length > 0 && (
                <div>
                    <p>Selected: {files.length} files</p>
                    <button onClick={handleUpload}>Upload</button>
                </div>
            )}
        </div>
    );
}
```

## Paste Upload [#paste-upload]

Handle clipboard paste events:

```tsx
import { usePasteUpload } from "@visulima/storage-client/react";
import { useUpload } from "@visulima/storage-client/react";

function PasteUpload() {
    const { pastedFiles, handlePaste } = usePasteUpload({
        onFilesPasted: (files) => {
            console.log("Files pasted:", files);
        },
    });

    const { upload, isUploading } = useUpload({
        endpointMultipart: "/api/upload/multipart",
    });

    const handlePasteAndUpload = (e: React.ClipboardEvent) => {
        handlePaste(e);
        // Upload the first pasted file
        if (pastedFiles.length > 0) {
            upload(pastedFiles[0]);
        }
    };

    return (
        <div onPaste={handlePasteAndUpload} style={{ padding: "2rem", border: "1px solid #ccc" }}>
            <p>Paste an image here</p>
            {isUploading && <p>Uploading...</p>}
            {pastedFiles.length > 0 && <p>{pastedFiles.length} file(s) pasted</p>}
        </div>
    );
}
```

## File Operations [#file-operations]

### Get File [#get-file]

```tsx
import { useGetFile } from "@visulima/storage-client/react";

function FileViewer({ fileId }: { fileId: string }) {
    const { data, isLoading, error, meta } = useGetFile({
        endpoint: "/api/files",
        id: fileId,
    });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!data) return null;

    // Create object URL from blob
    const url = URL.createObjectURL(data);

    return (
        <div>
            <img src={url} alt={meta?.filename || "File"} />
            {meta && <p>Filename: {meta.filename}</p>}
        </div>
    );
}
```

### Delete File [#delete-file]

```tsx
import { useDeleteFile } from "@visulima/storage-client/react";

function DeleteButton({ fileId }: { fileId: string }) {
    const { deleteFile, isLoading } = useDeleteFile({
        endpoint: "/api/files",
    });

    return (
        <button onClick={() => deleteFile(fileId)} disabled={isLoading}>
            {isLoading ? "Deleting..." : "Delete"}
        </button>
    );
}
```

### List Files [#list-files]

```tsx
import { useGetFileList } from "@visulima/storage-client/react";

function FileList() {
    const { data, isLoading } = useGetFileList({
        endpoint: "/api/files",
    });

    if (isLoading) return <div>Loading...</div>;

    return (
        <ul>
            {data?.data.map((file) => (
                <li key={file.id}>{file.filename}</li>
            ))}
        </ul>
    );
}
```

### Get File Metadata [#get-file-metadata]

```tsx
import { useGetFileMeta } from "@visulima/storage-client/react";

function FileMetadata({ fileId }: { fileId: string }) {
    const {
        data: meta,
        isLoading,
        error,
    } = useGetFileMeta({
        endpoint: "/api/files",
        id: fileId,
    });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!meta) return null;

    return (
        <div>
            <p>Filename: {meta.filename}</p>
            <p>Size: {meta.size} bytes</p>
            <p>Content Type: {meta.contentType}</p>
            {meta.url && <p>URL: {meta.url}</p>}
        </div>
    );
}
```

### Head File (Check Upload Status) [#head-file-check-upload-status]

```tsx
import { useHeadFile } from "@visulima/storage-client/react";

function UploadStatus({ fileId }: { fileId: string }) {
    const { data, isLoading } = useHeadFile({
        endpoint: "/api/files",
        id: fileId,
    });

    if (isLoading) return <div>Checking status...</div>;
    if (!data) return null;

    return (
        <div>
            {data.uploadComplete ? (
                <p>Upload complete</p>
            ) : (
                <p>
                    Upload in progress: {data.uploadOffset} / {data.contentLength} bytes
                </p>
            )}
            {data.receivedChunks && <p>Received chunks: {data.receivedChunks.length}</p>}
        </div>
    );
}
```

### Put File (Create/Update) [#put-file-createupdate]

```tsx
import { usePutFile } from "@visulima/storage-client/react";
import { useState } from "react";

function PutFileComponent({ fileId }: { fileId: string }) {
    const [file, setFile] = useState<File | null>(null);
    const { putFile, progress, isLoading, error, data } = usePutFile({
        endpoint: "/api/files",
        onSuccess: (result) => {
            console.log("File uploaded:", result);
        },
    });

    const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        setFile(e.target.files?.[0] || null);
    };

    const handleUpload = async () => {
        if (file) {
            await putFile(fileId, file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            <button onClick={handleUpload} disabled={!file || isLoading}>
                {isLoading ? `Uploading... ${progress}%` : "Upload"}
            </button>
            {error && <div>Error: {error.message}</div>}
            {data && <div>Upload complete! ID: {data.id}</div>}
        </div>
    );
}
```

### Batch Delete Files [#batch-delete-files]

```tsx
import { useBatchDeleteFiles } from "@visulima/storage-client/react";

function BatchDeleteComponent() {
    const { batchDeleteFiles, isLoading } = useBatchDeleteFiles({
        endpoint: "/api/files",
        onSuccess: (result) => {
            console.log(`Deleted ${result.successful} files`);
            if (result.failed) {
                console.log(`${result.failed} files failed to delete`);
            }
        },
    });

    const handleDelete = async () => {
        const fileIds = ["file1", "file2", "file3"];
        await batchDeleteFiles(fileIds);
    };

    return (
        <button onClick={handleDelete} disabled={isLoading}>
            {isLoading ? "Deleting..." : "Delete Selected Files"}
        </button>
    );
}
```

## Transform Operations [#transform-operations]

### Transform File [#transform-file]

Transform files (images, videos, etc.) with query parameters:

```tsx
import { useTransformFile } from "@visulima/storage-client/react";
import { useState } from "react";

function TransformImage({ fileId }: { fileId: string }) {
    const [transform, setTransform] = useState({ width: 800, height: 600, quality: 85 });
    const { data, isLoading, error, meta } = useTransformFile({
        endpoint: "/api/files",
        id: fileId,
        transform,
    });

    const [url, setUrl] = useState<string | null>(null);

    // Create object URL from blob
    if (data && !url) {
        setUrl(URL.createObjectURL(data));
    }

    if (isLoading) return <div>Transforming...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!data || !url) return null;

    return (
        <div>
            <img src={url} alt="Transformed" />
            <div>
                <label>
                    Width:
                    <input type="number" value={transform.width} onChange={(e) => setTransform({ ...transform, width: Number(e.target.value) })} />
                </label>
                <label>
                    Height:
                    <input type="number" value={transform.height} onChange={(e) => setTransform({ ...transform, height: Number(e.target.value) })} />
                </label>
                <label>
                    Quality:
                    <input
                        type="number"
                        min="1"
                        max="100"
                        value={transform.quality}
                        onChange={(e) => setTransform({ ...transform, quality: Number(e.target.value) })}
                    />
                </label>
            </div>
        </div>
    );
}
```

### Get Transform Metadata [#get-transform-metadata]

Get available transformation options:

```tsx
import { useTransformMetadata } from "@visulima/storage-client/react";

function TransformOptions() {
    const { data, isLoading, error } = useTransformMetadata({
        endpoint: "/api/files",
    });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!data) return null;

    return (
        <div>
            <h3>Available Formats</h3>
            <ul>
                {data.formats?.map((format) => (
                    <li key={format}>{format}</li>
                ))}
            </ul>
            <h3>Available Parameters</h3>
            <ul>
                {data.parameters?.map((param) => (
                    <li key={param}>{param}</li>
                ))}
            </ul>
        </div>
    );
}
```

### Patch Chunk (Chunked Uploads) [#patch-chunk-chunked-uploads]

Upload individual chunks for chunked uploads:

```tsx
import { usePatchChunk } from "@visulima/storage-client/react";

function ChunkUploader({ fileId }: { fileId: string }) {
    const { patchChunk, isLoading, error, data } = usePatchChunk({
        endpoint: "/api/upload/chunked-rest",
        onSuccess: (result) => {
            console.log("Chunk uploaded:", result);
        },
    });

    const uploadChunk = async (chunk: Blob, offset: number) => {
        await patchChunk(fileId, chunk, offset);
    };

    return (
        <div>
            {isLoading && <div>Uploading chunk...</div>}
            {error && <div>Error: {error.message}</div>}
            {data && <div>Chunk uploaded. Offset: {data.offset}</div>}
        </div>
    );
}
```

## Abort Operations [#abort-operations]

### Abort All Uploads [#abort-all-uploads]

```tsx
import { useAbortAll } from "@visulima/storage-client/react";

function AbortAllButton() {
    const { abortAll } = useAbortAll({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={abortAll}>Abort All Uploads</button>;
}
```

### Abort Batch [#abort-batch]

```tsx
import { useAbortBatch } from "@visulima/storage-client/react";

function AbortBatchButton({ batchId }: { batchId: string }) {
    const { abortBatch } = useAbortBatch({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => abortBatch(batchId)}>Abort Batch</button>;
}
```

### Abort Item [#abort-item]

```tsx
import { useAbortItem } from "@visulima/storage-client/react";

function AbortItemButton({ itemId }: { itemId: string }) {
    const { abortItem } = useAbortItem({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => abortItem(itemId)}>Abort Upload</button>;
}
```

## Retry Operations [#retry-operations]

### Retry Failed Upload [#retry-failed-upload]

```tsx
import { useRetry } from "@visulima/storage-client/react";

function RetryButton({ itemId }: { itemId: string }) {
    const { retryItem } = useRetry({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => retryItem(itemId)}>Retry Upload</button>;
}
```

### Batch Retry [#batch-retry]

```tsx
import { useBatchRetry } from "@visulima/storage-client/react";

function BatchRetryButton({ batchId }: { batchId: string }) {
    const { retryBatch } = useBatchRetry({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => retryBatch(batchId)}>Retry Failed Items in Batch</button>;
}
```

## Event Listeners [#event-listeners]

### Batch Event Listeners [#batch-event-listeners]

Listen to batch upload events:

```tsx
import { useBatchStartListener, useBatchProgressListener, useBatchFinishListener, useBatchErrorListener } from "@visulima/storage-client/react";
import { useEffect } from "react";

function BatchUploadWithListeners() {
    useBatchStartListener({
        endpoint: "/api/upload/multipart",
        onBatchStart: (batchId) => {
            console.log("Batch started:", batchId);
        },
    });

    useBatchProgressListener({
        endpoint: "/api/upload/multipart",
        onBatchProgress: (progress, batchId) => {
            console.log(`Batch ${batchId} progress: ${progress}%`);
        },
    });

    useBatchFinishListener({
        endpoint: "/api/upload/multipart",
        onBatchFinish: (results, batchId) => {
            console.log(`Batch ${batchId} finished:`, results);
        },
    });

    useBatchErrorListener({
        endpoint: "/api/upload/multipart",
        onBatchError: (error, batchId) => {
            console.error(`Batch ${batchId} error:`, error);
        },
    });

    // Your upload component...
    return <div>Upload component with listeners</div>;
}
```

### Retry Listener [#retry-listener]

```tsx
import { useRetryListener } from "@visulima/storage-client/react";

function RetryListener() {
    useRetryListener({
        endpoint: "/api/upload/multipart",
        onRetry: (itemId) => {
            console.log("Retrying item:", itemId);
        },
    });

    return null; // This is just a listener
}
```

### All Abort Listener [#all-abort-listener]

```tsx
import { useAllAbortListener } from "@visulima/storage-client/react";

function AbortListener() {
    useAllAbortListener({
        endpoint: "/api/upload/multipart",
        onAbortAll: () => {
            console.log("All uploads aborted");
        },
    });

    return null; // This is just a listener
}
```

## Next Steps [#next-steps]

* [Next.js Guide](/docs/packages/storage-client/nextjs) - Learn how to use with Next.js
* [TanStack Start Guide](/docs/packages/storage-client/tanstack-start) - Learn how to use with TanStack Start
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# Solid Start (/docs/packages/storage-client/solid-start)



# Solid Start [#solid-start]

Use `@visulima/storage-client` with Solid Start for full-stack SolidJS applications with server-side file handling and client-side uploads.

## Installation [#installation]

```bash
npm install @visulima/storage-client @tanstack/solid-query solid-js @solidjs/start
```

## Setup QueryClient Provider [#setup-queryclient-provider]

Configure the TanStack Solid Query provider in your root layout:

```tsx
// src/app.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";

const queryClient = new QueryClient();

export default function App() {
    return (
        <QueryClientProvider client={queryClient}>
            <Router root={(props) => <>{props.children}</>}>
                <FileRoutes />
            </Router>
        </QueryClientProvider>
    );
}
```

## Upload Component [#upload-component]

Create a page with file upload functionality:

```tsx
// src/routes/index.tsx
import { createUpload } from "@visulima/storage-client/solid";
import { createSignal } from "solid-js";

export default function Home() {
    const [file, setFile] = createSignal<File | null>(null);
    let fileInputRef: HTMLInputElement | undefined;

    const { error, isUploading, progress, result, upload, reset } = createUpload({
        endpointMultipart: "/api/upload/multipart",
        endpointTus: "/api/upload/tus",
        onSuccess: (result) => {
            console.log("Upload successful:", result);
            setFile(null);
            if (fileInputRef) {
                fileInputRef.value = "";
            }
        },
        onError: (error_) => {
            console.error("Upload error:", error_);
        },
    });

    const handleFileChange = (e: Event) => {
        const target = e.target as HTMLInputElement;
        const selectedFile = target.files?.[0];
        setFile(selectedFile || null);
    };

    const handleUpload = async () => {
        const currentFile = file();
        if (currentFile) {
            try {
                await upload(currentFile);
            } catch (error_) {
                console.error("Upload failed:", error_);
            }
        }
    };

    const handleReset = () => {
        reset();
        setFile(null);
        if (fileInputRef) {
            fileInputRef.value = "";
        }
    };

    return (
        <main style={{ margin: "0 auto", "max-width": "800px", padding: "2rem" }}>
            <h1>Storage Client - Solid Start Example</h1>
            <p>Upload files using @visulima/storage-client with Solid Start</p>

            <div style={{ "margin-top": "2rem" }}>
                <input disabled={isUploading()} onChange={handleFileChange} ref={fileInputRef} type="file" />
                <button disabled={!file() || isUploading()} onClick={handleUpload} style={{ "margin-left": "1rem" }}>
                    {isUploading() ? `Uploading... ${progress()}%` : "Upload"}
                </button>
                <button disabled={isUploading()} onClick={handleReset} style={{ "margin-left": "0.5rem" }}>
                    Reset
                </button>
            </div>

            {isUploading() && (
                <div style={{ "margin-top": "1rem" }}>
                    <div>Progress: {progress()}%</div>
                    <progress max={100} value={progress()} style={{ width: "100%", "max-width": "400px" }} />
                </div>
            )}

            {error() && <div style={{ color: "red", "margin-top": "1rem" }}>Error: {error()?.message}</div>}

            {result() && (
                <div style={{ color: "green", "margin-top": "1rem" }}>
                    <div>Upload complete!</div>
                    <div>File ID: {result()?.id}</div>
                    {result()?.filename && <div>Filename: {result()?.filename}</div>}
                    {result()?.url && (
                        <div>
                            URL:{" "}
                            <a href={result()?.url} target="_blank" rel="noopener noreferrer">
                                {result()?.url}
                            </a>
                        </div>
                    )}
                </div>
            )}
        </main>
    );
}
```

## Server API Routes [#server-api-routes]

### Multipart Upload Endpoint [#multipart-upload-endpoint]

```tsx
// src/routes/api/upload/multipart.ts
import type { APIEvent } from "@solidjs/start/server";
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "~/lib/storage";

const handler = createHandler({ storage, type: "multipart" });

export async function POST(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function DELETE(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function GET(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function OPTIONS(event: APIEvent) {
    return handler.fetch(event.request);
}
```

### TUS Upload Endpoint [#tus-upload-endpoint]

```tsx
// src/routes/api/upload/tus.ts
import type { APIEvent } from "@solidjs/start/server";
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "~/lib/storage";

const handler = createHandler({ storage, type: "tus" });

export async function POST(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function PATCH(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function HEAD(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function OPTIONS(event: APIEvent) {
    return handler.fetch(event.request);
}
```

### TUS Upload by ID Endpoint [#tus-upload-by-id-endpoint]

```tsx
// src/routes/api/upload/tus/[id].ts
import type { APIEvent } from "@solidjs/start/server";
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "~/lib/storage";

const handler = createHandler({ storage, type: "tus" });

export async function PATCH(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function HEAD(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function DELETE(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function OPTIONS(event: APIEvent) {
    return handler.fetch(event.request);
}
```

### Chunked REST Upload Endpoint [#chunked-rest-upload-endpoint]

```tsx
// src/routes/api/upload/chunked-rest.ts
import type { APIEvent } from "@solidjs/start/server";
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "~/lib/storage";

const handler = createHandler({ storage, type: "rest" });

export async function POST(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function OPTIONS(event: APIEvent) {
    return handler.fetch(event.request);
}
```

```tsx
// src/routes/api/upload/chunked-rest/[id].ts
import type { APIEvent } from "@solidjs/start/server";
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "~/lib/storage";

const handler = createHandler({ storage, type: "rest" });

export async function PUT(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function PATCH(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function HEAD(event: APIEvent) {
    return handler.fetch(event.request);
}

export async function OPTIONS(event: APIEvent) {
    return handler.fetch(event.request);
}
```

## Storage Configuration [#storage-configuration]

Create a shared storage instance:

```tsx
// src/lib/storage.ts
import { DiskStorage } from "@visulima/storage";

export const storage = new DiskStorage({
    directory: "./uploads",
});
```

## TUS Resumable Upload Example [#tus-resumable-upload-example]

For large file uploads with pause/resume support:

```tsx
// src/routes/upload-large.tsx
import { createTusUpload } from "@visulima/storage-client/solid";
import { createSignal } from "solid-js";

export default function LargeFileUpload() {
    const [file, setFile] = createSignal<File | null>(null);

    const { upload, pause, resume, progress, isUploading, isPaused, offset, error, result, reset } = createTusUpload({
        endpoint: "/api/upload/tus",
        chunkSize: 1024 * 1024, // 1MB chunks
        onSuccess: (result) => {
            console.log("Upload complete:", result);
        },
    });

    const handleFileChange = (e: Event) => {
        const target = e.target as HTMLInputElement;
        setFile(target.files?.[0] || null);
    };

    const handleUpload = async () => {
        const currentFile = file();
        if (currentFile) {
            await upload(currentFile);
        }
    };

    return (
        <main style={{ padding: "2rem" }}>
            <h1>Large File Upload (TUS)</h1>
            <input type="file" onChange={handleFileChange} disabled={isUploading()} />
            <button onClick={handleUpload} disabled={!file() || isUploading()}>
                Upload
            </button>

            {isUploading() && (
                <div style={{ "margin-top": "1rem" }}>
                    <progress max={100} value={progress()} style={{ width: "100%" }} />
                    <div>
                        Progress: {progress()}% ({offset()} bytes uploaded)
                    </div>
                    {isPaused() ? <button onClick={resume}>Resume</button> : <button onClick={pause}>Pause</button>}
                </div>
            )}

            {error() && <div style={{ color: "red" }}>Error: {error()?.message}</div>}
            {result() && <div style={{ color: "green" }}>Upload complete! ID: {result()?.id}</div>}
        </main>
    );
}
```

## Batch Upload with Drag and Drop [#batch-upload-with-drag-and-drop]

```tsx
// src/routes/batch-upload.tsx
import { createBatchUpload, createFileInput } from "@visulima/storage-client/solid";

export default function BatchUploadPage() {
    const {
        files,
        inputRef,
        handleFileChange,
        handleDrop,
        handleDragOver,
        openFileDialog,
        reset: resetFiles,
    } = createFileInput({
        multiple: true,
    });

    const {
        uploadBatch,
        progress,
        isUploading,
        completedCount,
        errorCount,
        items,
        reset: resetUpload,
    } = createBatchUpload({
        endpoint: "/api/upload/multipart",
        onSuccess: (results) => {
            console.log("Batch complete:", results);
        },
    });

    const handleUpload = () => {
        const currentFiles = files();
        if (currentFiles.length > 0) {
            uploadBatch(currentFiles);
        }
    };

    return (
        <main style={{ padding: "2rem" }}>
            <h1>Batch Upload</h1>

            <div
                onDrop={handleDrop}
                onDragOver={handleDragOver}
                style={{
                    border: "2px dashed #ccc",
                    padding: "2rem",
                    "text-align": "center",
                    "border-radius": "8px",
                }}
            >
                <input ref={inputRef} type="file" multiple onChange={handleFileChange} style={{ display: "none" }} />
                <p>Drag and drop files here or</p>
                <button onClick={openFileDialog}>Select Files</button>
            </div>

            {files().length > 0 && (
                <div style={{ "margin-top": "1rem" }}>
                    <p>Selected: {files().length} files</p>
                    <button onClick={handleUpload} disabled={isUploading()}>
                        {isUploading() ? "Uploading..." : "Upload All"}
                    </button>
                </div>
            )}

            {isUploading() && (
                <div style={{ "margin-top": "1rem" }}>
                    <progress max={100} value={progress()} style={{ width: "100%" }} />
                    <div>Progress: {progress()}%</div>
                    <div>
                        Completed: {completedCount()} / {items().length}
                    </div>
                    <div>Errors: {errorCount()}</div>
                </div>
            )}
        </main>
    );
}
```

## File Management [#file-management]

### Listing and Deleting Files [#listing-and-deleting-files]

```tsx
// src/routes/files.tsx
import { createGetFileList, createDeleteFile, createBatchDeleteFiles } from "@visulima/storage-client/solid";
import { createSignal, For } from "solid-js";

export default function FilesPage() {
    const [selectedIds, setSelectedIds] = createSignal<string[]>([]);

    const { data, isLoading, refetch } = createGetFileList({
        endpoint: "/api/files",
    });

    const { deleteFile, isLoading: isDeleting } = createDeleteFile({
        endpoint: "/api/files",
    });

    const { batchDeleteFiles, isLoading: isBatchDeleting } = createBatchDeleteFiles({
        endpoint: "/api/files",
    });

    const handleDelete = async (id: string) => {
        await deleteFile(id);
        refetch();
    };

    const handleBatchDelete = async () => {
        await batchDeleteFiles(selectedIds());
        setSelectedIds([]);
        refetch();
    };

    const toggleSelect = (id: string) => {
        setSelectedIds((prev) => (prev.includes(id) ? prev.filter((i) => i !== id) : [...prev, id]));
    };

    return (
        <main style={{ padding: "2rem" }}>
            <h1>Files</h1>

            {selectedIds().length > 0 && (
                <button onClick={() => handleBatchDelete()} disabled={isBatchDeleting()}>
                    {isBatchDeleting() ? "Deleting..." : `Delete Selected (${selectedIds().length})`}
                </button>
            )}

            {isLoading() && <div>Loading...</div>}

            <ul>
                <For each={data()?.data}>
                    {(file) => (
                        <li>
                            <input type="checkbox" checked={selectedIds().includes(file.id)} onChange={() => toggleSelect(file.id)} />
                            {file.originalName || file.name || file.id} ({file.size} bytes)
                            <button onClick={() => handleDelete(file.id)} disabled={isDeleting()}>
                                Delete
                            </button>
                        </li>
                    )}
                </For>
            </ul>
        </main>
    );
}
```

## Environment Variables [#environment-variables]

Configure storage backend via environment variables:

```bash
# .env
UPLOAD_DIR=./uploads
```

## Next Steps [#next-steps]

* [Solid Guide](/docs/packages/storage-client/solid) - Learn all Solid primitives in detail
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# Solid (/docs/packages/storage-client/solid)



# Solid [#solid]

Use `@visulima/storage-client` with SolidJS and Solid Start for reactive file uploads with primitives and TanStack Solid Query integration.

## Installation [#installation]

### SolidJS [#solidjs]

```bash
npm install @visulima/storage-client @tanstack/solid-query solid-js
```

### Solid Start [#solid-start]

```bash
npm install @visulima/storage-client @tanstack/solid-query solid-start
```

## Setup QueryClient [#setup-queryclient]

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";

const queryClient = new QueryClient();

function App() {
    return <QueryClientProvider client={queryClient}>{/* Your app */}</QueryClientProvider>;
}
```

## Basic Upload [#basic-upload]

Use the `createUpload` primitive for automatic method selection:

```tsx
import { createUpload } from "@visulima/storage-client/solid";
import { createSignal } from "solid-js";

function UploadComponent() {
    const [file, setFile] = createSignal<File | null>(null);
    let fileInputRef: HTMLInputElement | undefined;
    const { error, isUploading, progress, result, upload } = createUpload({
        endpointMultipart: "/api/upload/multipart",
        endpointTus: "/api/upload/tus",
        onError: (error_) => {
            console.error("Upload error:", error_);
        },
        onSuccess: (result) => {
            console.log("Upload successful:", result);
            setFile(null);
            if (fileInputRef) {
                fileInputRef.value = "";
            }
        },
    });

    const handleFileChange = (e: Event) => {
        const target = e.target as HTMLInputElement;
        const selectedFile = target.files?.[0];
        setFile(selectedFile || null);
    };

    const handleUpload = async () => {
        const currentFile = file();
        if (currentFile) {
            try {
                await upload(currentFile);
            } catch (error_) {
                console.error("Upload failed:", error_);
            }
        }
    };

    return (
        <main>
            <h1>Storage Client - Solid Example</h1>
            <div style={{ "margin-top": "2rem" }}>
                <input disabled={isUploading()} onChange={handleFileChange} ref={fileInputRef} type="file" />
                <button disabled={!file() || isUploading()} onClick={handleUpload} style={{ "margin-left": "1rem" }}>
                    {isUploading() ? "Uploading..." : "Upload"}
                </button>
            </div>
            {isUploading() && (
                <div style={{ "margin-top": "1rem" }}>
                    <div>
                        Progress:
                        {progress()}%
                    </div>
                    <progress max={100} value={progress()} />
                </div>
            )}
            {error() && (
                <div style={{ color: "red", "margin-top": "1rem" }}>
                    Error:
                    {error()?.message}
                </div>
            )}
            {result() && (
                <div style={{ color: "green", "margin-top": "1rem" }}>
                    Upload complete! File:
                    {result()?.filename}
                </div>
            )}
        </main>
    );
}
```

## Multipart Upload [#multipart-upload]

For traditional form-based uploads:

```tsx
import { createMultipartUpload } from "@visulima/storage-client/solid";

function MultipartUpload() {
    const { upload, progress, isUploading } = createMultipartUpload({
        endpoint: "/api/upload/multipart",
    });

    const handleFileChange = async (e: Event) => {
        const target = e.target as HTMLInputElement;
        const file = target.files?.[0];
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            {isUploading() && <progress value={progress()} max={100} />}
        </div>
    );
}
```

## TUS Resumable Upload [#tus-resumable-upload]

For large files with pause/resume support:

```tsx
import { createTusUpload } from "@visulima/storage-client/solid";

function TusUpload() {
    const { upload, pause, resume, progress, isUploading, isPaused } = createTusUpload({
        endpoint: "/api/upload/tus",
    });

    const handleFileChange = async (e: Event) => {
        const target = e.target as HTMLInputElement;
        const file = target.files?.[0];
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            {isUploading() && (
                <div>
                    <progress value={progress()} max={100} />
                    {isPaused() ? <button onClick={resume}>Resume</button> : <button onClick={pause}>Pause</button>}
                </div>
            )}
        </div>
    );
}
```

## Chunked REST Upload [#chunked-rest-upload]

For client-side chunked uploads:

```tsx
import { createChunkedRestUpload } from "@visulima/storage-client/solid";

function ChunkedUpload() {
    const { upload, progress, isUploading } = createChunkedRestUpload({
        endpoint: "/api/upload/chunked-rest",
        chunkSize: 5 * 1024 * 1024, // 5MB chunks
    });

    const handleFileChange = async (e: Event) => {
        const target = e.target as HTMLInputElement;
        const file = target.files?.[0];
        if (file) {
            await upload(file);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            {isUploading() && <progress value={progress()} max={100} />}
        </div>
    );
}
```

## Batch Upload [#batch-upload]

Upload multiple files simultaneously:

```tsx
import { createBatchUpload } from "@visulima/storage-client/solid";

function BatchUpload() {
    const { uploadBatch, progress, isUploading, items, completedCount, errorCount } = createBatchUpload({
        endpoint: "/api/upload/multipart",
        onSuccess: (results) => {
            console.log("Batch upload complete:", results);
        },
    });

    const handleFilesChange = (e: Event) => {
        const target = e.target as HTMLInputElement;
        const files = Array.from(target.files || []);
        if (files.length > 0) {
            uploadBatch(files);
        }
    };

    return (
        <div>
            <input type="file" multiple onChange={handleFilesChange} />
            {isUploading() && (
                <div>
                    <div>
                        Progress:
                        {progress()}%
                    </div>
                    <div>
                        Completed:
                        {completedCount()} / {items().length}
                    </div>
                    <div>
                        Errors:
                        {errorCount()}
                    </div>
                </div>
            )}
        </div>
    );
}
```

## File Input Primitive [#file-input-primitive]

Use the `createFileInput` primitive for drag & drop support:

```tsx
import { createFileInput } from "@visulima/storage-client/solid";
import { createBatchUpload } from "@visulima/storage-client/solid";

function DragDropUpload() {
    const { files, inputRef, handleFileChange, handleDrop, handleDragOver, openFileDialog } = createFileInput({
        multiple: true,
    });

    const { uploadBatch } = createBatchUpload({
        endpoint: "/api/upload/multipart",
    });

    const handleUpload = () => {
        const currentFiles = files();
        if (currentFiles.length > 0) {
            uploadBatch(currentFiles);
        }
    };

    return (
        <div onDrop={handleDrop} onDragOver={handleDragOver} style={{ border: "2px dashed #ccc", padding: "2rem", "text-align": "center" }}>
            <input ref={inputRef} type="file" multiple onChange={handleFileChange} style={{ display: "none" }} />
            <p>Drag and drop files here or</p>
            <button onClick={openFileDialog}>Select Files</button>
            {files().length > 0 && (
                <div>
                    <p>
                        Selected:
                        {files().length} files
                    </p>
                    <button onClick={handleUpload}>Upload</button>
                </div>
            )}
        </div>
    );
}
```

## File Operations [#file-operations]

### Get File [#get-file]

```tsx
import { createEffect, createSignal, onCleanup } from "solid-js";
import { createGetFile } from "@visulima/storage-client/solid";

function FileViewer({ fileId }: { fileId: string }) {
    const { data, isLoading, error, meta } = createGetFile({
        endpoint: "/api/files",
        id: () => fileId,
    });

    const [url, setUrl] = createSignal<string | null>(null);

    // Create object URL from blob
    createEffect(() => {
        const blob = data();
        if (!blob) return;

        const objectUrl = URL.createObjectURL(blob);
        setUrl(objectUrl);
        onCleanup(() => URL.revokeObjectURL(objectUrl));
    });

    return (
        <>
            {isLoading() && <div>Loading...</div>}
            {error() && <div>Error: {error()?.message}</div>}
            {data() && url() && (
                <div>
                    <img src={url()!} alt={meta()?.filename || "File"} />
                    {meta() && <p>Filename: {meta()?.filename}</p>}
                </div>
            )}
        </>
    );
}
```

### Delete File [#delete-file]

```tsx
import { createDeleteFile } from "@visulima/storage-client/solid";

function DeleteButton({ fileId }: { fileId: string }) {
    const { deleteFile, isLoading } = createDeleteFile({
        endpoint: "/api/files",
    });

    return (
        <button onClick={() => deleteFile(fileId)} disabled={isLoading()}>
            {isLoading() ? "Deleting..." : "Delete"}
        </button>
    );
}
```

## Solid Start Integration [#solid-start-integration]

### Server Routes [#server-routes]

Set up upload endpoints in Solid Start:

```tsx
// src/routes/api/upload/multipart.ts
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "@/lib/storage";

const multipart = createHandler({ storage, type: "multipart" });

export async function POST({ request }: { request: Request }) {
    return multipart.fetch(request);
}
```

### Storage Configuration [#storage-configuration]

```tsx
// src/lib/storage.ts
import { DiskStorage } from "@visulima/storage";

export const storage = new DiskStorage({
    directory: "./uploads",
});
```

## File Operations [#file-operations-1]

### Get File Metadata [#get-file-metadata]

```tsx
import { createGetFileMeta } from "@visulima/storage-client/solid";

function FileMetadata({ fileId }: { fileId: string }) {
    const {
        data: meta,
        isLoading,
        error,
    } = createGetFileMeta({
        endpoint: "/api/files",
        id: () => fileId,
    });

    return (
        <>
            {isLoading() && <div>Loading...</div>}
            {error() && <div>Error: {error()?.message}</div>}
            {meta() && (
                <div>
                    <p>Filename: {meta()?.filename}</p>
                    <p>Size: {meta()?.size} bytes</p>
                    <p>Content Type: {meta()?.contentType}</p>
                    {meta()?.url && <p>URL: {meta()?.url}</p>}
                </div>
            )}
        </>
    );
}
```

### Head File (Check Upload Status) [#head-file-check-upload-status]

```tsx
import { createHeadFile } from "@visulima/storage-client/solid";

function UploadStatus({ fileId }: { fileId: string }) {
    const { data, isLoading } = createHeadFile({
        endpoint: "/api/files",
        id: () => fileId,
    });

    return (
        <>
            {isLoading() && <div>Checking status...</div>}
            {data() && (
                <div>
                    {data()?.uploadComplete ? (
                        <p>Upload complete</p>
                    ) : (
                        <p>
                            Upload in progress: {data()?.uploadOffset} / {data()?.contentLength} bytes
                        </p>
                    )}
                    {data()?.receivedChunks && <p>Received chunks: {data()?.receivedChunks.length}</p>}
                </div>
            )}
        </>
    );
}
```

### Put File (Create/Update) [#put-file-createupdate]

```tsx
import { createSignal } from "solid-js";
import { createPutFile } from "@visulima/storage-client/solid";

function PutFileComponent({ fileId }: { fileId: string }) {
    const [file, setFile] = createSignal<File | null>(null);
    const { putFile, progress, isLoading, error, data } = createPutFile({
        endpoint: "/api/files",
        onSuccess: (result) => {
            console.log("File uploaded:", result);
        },
    });

    const handleFileChange = (e: Event) => {
        const target = e.target as HTMLInputElement;
        setFile(target.files?.[0] || null);
    };

    const handleUpload = async () => {
        const currentFile = file();
        if (currentFile) {
            await putFile(fileId, currentFile);
        }
    };

    return (
        <div>
            <input type="file" onChange={handleFileChange} />
            <button onClick={handleUpload} disabled={!file() || isLoading()}>
                {isLoading() ? `Uploading... ${progress()}%` : "Upload"}
            </button>
            {error() && <div>Error: {error()?.message}</div>}
            {data() && <div>Upload complete! ID: {data()?.id}</div>}
        </div>
    );
}
```

### Batch Delete Files [#batch-delete-files]

```tsx
import { createBatchDeleteFiles } from "@visulima/storage-client/solid";

function BatchDeleteComponent() {
    const { batchDeleteFiles, isLoading } = createBatchDeleteFiles({
        endpoint: "/api/files",
        onSuccess: (result) => {
            console.log(`Deleted ${result.successful} files`);
            if (result.failed) {
                console.log(`${result.failed} files failed to delete`);
            }
        },
    });

    const handleDelete = async () => {
        const fileIds = ["file1", "file2", "file3"];
        await batchDeleteFiles(fileIds);
    };

    return (
        <button onClick={handleDelete} disabled={isLoading()}>
            {isLoading() ? "Deleting..." : "Delete Selected Files"}
        </button>
    );
}
```

## Transform Operations [#transform-operations]

### Transform File [#transform-file]

```tsx
import { createEffect, createSignal, onCleanup } from "solid-js";
import { createTransformFile } from "@visulima/storage-client/solid";

function TransformImage({ fileId }: { fileId: string }) {
    const [transform, setTransform] = createSignal({ width: 800, height: 600, quality: 85 });
    const { data, isLoading, error, meta } = createTransformFile({
        endpoint: "/api/files",
        id: () => fileId,
        transform: () => transform(),
    });

    const [url, setUrl] = createSignal<string | null>(null);

    // Create object URL from blob
    createEffect(() => {
        const blob = data();
        if (!blob) return;

        const objectUrl = URL.createObjectURL(blob);
        setUrl(objectUrl);
        onCleanup(() => URL.revokeObjectURL(objectUrl));
    });

    return (
        <>
            {isLoading() && <div>Transforming...</div>}
            {error() && <div>Error: {error()?.message}</div>}
            {data() && url() && (
                <div>
                    <img src={url()!} alt="Transformed" />
                    <div>
                        <label>
                            Width:
                            <input
                                type="number"
                                value={transform().width}
                                onInput={(e) => setTransform({ ...transform(), width: Number(e.currentTarget.value) })}
                            />
                        </label>
                        <label>
                            Height:
                            <input
                                type="number"
                                value={transform().height}
                                onInput={(e) => setTransform({ ...transform(), height: Number(e.currentTarget.value) })}
                            />
                        </label>
                        <label>
                            Quality:
                            <input
                                type="number"
                                min="1"
                                max="100"
                                value={transform().quality}
                                onInput={(e) => setTransform({ ...transform(), quality: Number(e.currentTarget.value) })}
                            />
                        </label>
                    </div>
                </div>
            )}
        </>
    );
}
```

### Get Transform Metadata [#get-transform-metadata]

```tsx
import { createTransformMetadata } from "@visulima/storage-client/solid";

function TransformOptions() {
    const { data, isLoading, error } = createTransformMetadata({
        endpoint: "/api/files",
    });

    return (
        <>
            {isLoading() && <div>Loading...</div>}
            {error() && <div>Error: {error()?.message}</div>}
            {data() && (
                <div>
                    <h3>Available Formats</h3>
                    <ul>
                        {data()?.formats?.map((format) => (
                            <li key={format}>{format}</li>
                        ))}
                    </ul>
                    <h3>Available Parameters</h3>
                    <ul>
                        {data()?.parameters?.map((param) => (
                            <li key={param}>{param}</li>
                        ))}
                    </ul>
                </div>
            )}
        </>
    );
}
```

## Abort Operations [#abort-operations]

### Abort All Uploads [#abort-all-uploads]

```tsx
import { createAbortAll } from "@visulima/storage-client/solid";

function AbortAllButton() {
    const { abortAll } = createAbortAll({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={abortAll}>Abort All Uploads</button>;
}
```

### Abort Batch [#abort-batch]

```tsx
import { createAbortBatch } from "@visulima/storage-client/solid";

function AbortBatchButton({ batchId }: { batchId: string }) {
    const { abortBatch } = createAbortBatch({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => abortBatch(batchId)}>Abort Batch</button>;
}
```

### Abort Item [#abort-item]

```tsx
import { createAbortItem } from "@visulima/storage-client/solid";

function AbortItemButton({ itemId }: { itemId: string }) {
    const { abortItem } = createAbortItem({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => abortItem(itemId)}>Abort Upload</button>;
}
```

## Retry Operations [#retry-operations]

### Retry Failed Upload [#retry-failed-upload]

```tsx
import { createRetry } from "@visulima/storage-client/solid";

function RetryButton({ itemId }: { itemId: string }) {
    const { retryItem } = createRetry({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => retryItem(itemId)}>Retry Upload</button>;
}
```

### Batch Retry [#batch-retry]

```tsx
import { createBatchRetry } from "@visulima/storage-client/solid";

function BatchRetryButton({ batchId }: { batchId: string }) {
    const { retryBatch } = createBatchRetry({
        endpoint: "/api/upload/multipart",
    });

    return <button onClick={() => retryBatch(batchId)}>Retry Failed Items in Batch</button>;
}
```

## Event Listeners [#event-listeners]

### Batch Event Listeners [#batch-event-listeners]

```tsx
import { createBatchStartListener, createBatchProgressListener, createBatchFinishListener, createBatchErrorListener } from "@visulima/storage-client/solid";

function BatchUploadWithListeners() {
    createBatchStartListener({
        endpoint: "/api/upload/multipart",
        onBatchStart: (batchId) => {
            console.log("Batch started:", batchId);
        },
    });

    createBatchProgressListener({
        endpoint: "/api/upload/multipart",
        onBatchProgress: (progress, batchId) => {
            console.log(`Batch ${batchId} progress: ${progress}%`);
        },
    });

    createBatchFinishListener({
        endpoint: "/api/upload/multipart",
        onBatchFinish: (results, batchId) => {
            console.log(`Batch ${batchId} finished:`, results);
        },
    });

    createBatchErrorListener({
        endpoint: "/api/upload/multipart",
        onBatchError: (error, batchId) => {
            console.error(`Batch ${batchId} error:`, error);
        },
    });

    return <div>Upload component with listeners</div>;
}
```

## Next Steps [#next-steps]

* [Solid Start Guide](/docs/packages/storage-client/solid-start) - Learn Solid Start-specific features
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# Svelte (/docs/packages/storage-client/svelte)



# Svelte [#svelte]

Use `@visulima/storage-client` with Svelte and SvelteKit for reactive file uploads with stores and TanStack Svelte Query integration.

## Installation [#installation]

### Svelte [#svelte-1]

```bash
npm install @visulima/storage-client @tanstack/svelte-query svelte
```

### SvelteKit [#sveltekit]

```bash
npm install @visulima/storage-client @tanstack/svelte-query sveltekit
```

## Setup QueryClient [#setup-queryclient]

```svelte
<script lang="ts">
  import { QueryClient, QueryClientProvider } from "@tanstack/svelte-query";

  const queryClient = new QueryClient();
</script>

<QueryClientProvider client={queryClient}>
  <!-- Your app -->
</QueryClientProvider>
```

## Basic Upload [#basic-upload]

Use the `createUpload` store for automatic method selection:

```svelte
<script lang="ts">
  import { createUpload } from "@visulima/storage-client/svelte";

  let file: File | null = null;
  const { upload, progress, isUploading, error, result, reset } = createUpload({
    endpointMultipart: "/api/upload/multipart",
    endpointTus: "/api/upload/tus",
    onSuccess: (result) => {
      console.log("Upload successful:", result);
      file = null;
      const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
      if (fileInput) {
        fileInput.value = "";
      }
    },
    onError: (error_) => {
      console.error("Upload error:", error_);
    },
  });

  const handleFileChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    const selectedFile = target.files?.[0];
    file = selectedFile || null;
  };

  const handleUpload = async () => {
    if (file) {
      try {
        await upload(file);
      } catch (error_) {
        console.error("Upload failed:", error_);
      }
    }
  };

  const handleReset = () => {
    reset();
    file = null;
    const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
    if (fileInput) {
      fileInput.value = "";
    }
  };
</script>

<div class="app">
  <h1>Storage Client - Svelte Example</h1>
  <div class="upload-section">
    <input type="file" on:change={handleFileChange} disabled={$isUploading} />
    <button on:click={handleUpload} disabled={!file || $isUploading}>
      {$isUploading ? "Uploading..." : "Upload"}
    </button>
    <button on:click={handleReset} disabled={$isUploading}>
      Reset
    </button>
  </div>
  {#if $isUploading}
    <div class="progress-section">
      <div>Progress: {$progress}%</div>
      <progress value={$progress} max={100} />
    </div>
  {/if}
  {#if $error}
    <div class="error">Error: {$error.message}</div>
  {/if}
  {#if $result}
    <div class="success">
      Upload complete! File: {$result.filename}
    </div>
  {/if}
</div>

<style>
  .app {
    max-width: 800px;
    margin: 0 auto;
    padding: 2rem;
    text-align: center;
  }

  .upload-section {
    margin: 2rem 0;
    display: flex;
    gap: 1rem;
    justify-content: center;
    align-items: center;
  }

  .upload-section input[type="file"] {
    padding: 0.5rem;
  }

  .upload-section button {
    padding: 0.5rem 1rem;
    background-color: #ff3e00;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  }

  .upload-section button:disabled {
    background-color: #ccc;
    cursor: not-allowed;
  }

  .progress-section {
    margin: 2rem 0;
  }

  .progress-section progress {
    width: 100%;
    max-width: 400px;
    height: 20px;
  }

  .error {
    margin: 1rem 0;
    padding: 1rem;
    background-color: #fee;
    color: #c33;
    border-radius: 4px;
  }

  .success {
    margin: 1rem 0;
    padding: 1rem;
    background-color: #efe;
    color: #3c3;
    border-radius: 4px;
  }
</style>
```

## Multipart Upload [#multipart-upload]

For traditional form-based uploads:

```svelte
<script lang="ts">
  import { createMultipartUpload } from "@visulima/storage-client/svelte";

  const { upload, progress, isUploading } = createMultipartUpload({
    endpoint: "/api/upload/multipart",
  });

  const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
      await upload(file);
    }
  };
</script>

<div>
  <input type="file" on:change={handleFileChange} />
  {#if $isUploading}
    <progress value={$progress} max={100} />
  {/if}
</div>
```

## TUS Resumable Upload [#tus-resumable-upload]

For large files with pause/resume support:

```svelte
<script lang="ts">
  import { createTusUpload } from "@visulima/storage-client/svelte";

  const { upload, pause, resume, progress, isUploading, isPaused } = createTusUpload({
    endpoint: "/api/upload/tus",
  });

  const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
      await upload(file);
    }
  };
</script>

<div>
  <input type="file" on:change={handleFileChange} />
  {#if $isUploading}
    <progress value={$progress} max={100} />
    {#if $isPaused}
      <button on:click={resume}>Resume</button>
    {:else}
      <button on:click={pause}>Pause</button>
    {/if}
  {/if}
</div>
```

## Chunked REST Upload [#chunked-rest-upload]

For client-side chunked uploads:

```svelte
<script lang="ts">
  import { createChunkedRestUpload } from "@visulima/storage-client/svelte";

  const { upload, progress, isUploading } = createChunkedRestUpload({
    endpoint: "/api/upload/chunked-rest",
    chunkSize: 5 * 1024 * 1024, // 5MB chunks
  });

  const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
      await upload(file);
    }
  };
</script>

<div>
  <input type="file" on:change={handleFileChange} />
  {#if $isUploading}
    <progress value={$progress} max={100} />
  {/if}
</div>
```

## Batch Upload [#batch-upload]

Upload multiple files simultaneously:

```svelte
<script lang="ts">
  import { createBatchUpload } from "@visulima/storage-client/svelte";

  const { uploadBatch, progress, isUploading, items, completedCount, errorCount } = createBatchUpload({
    endpoint: "/api/upload/multipart",
    onSuccess: (results) => {
      console.log("Batch upload complete:", results);
    },
  });

  const handleFilesChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    const files = Array.from(target.files || []);
    if (files.length > 0) {
      uploadBatch(files);
    }
  };
</script>

<div>
  <input type="file" multiple on:change={handleFilesChange} />
  {#if $isUploading}
    <div>
      <div>Progress: {$progress}%</div>
      <div>Completed: {$completedCount} / {$items.length}</div>
      <div>Errors: {$errorCount}</div>
    </div>
  {/if}
</div>
```

## File Input Store [#file-input-store]

Use the `createFileInput` store for drag & drop support:

```svelte
<script lang="ts">
  import { createFileInput } from "@visulima/storage-client/svelte";
  import { createBatchUpload } from "@visulima/storage-client/svelte";

  const { files, inputRef, handleFileChange, handleDrop, handleDragOver, openFileDialog } = createFileInput({
    multiple: true,
  });

  const { uploadBatch } = createBatchUpload({
    endpoint: "/api/upload/multipart",
  });

  const handleUpload = () => {
    if ($files.length > 0) {
      uploadBatch($files);
    }
  };
</script>

<div
  on:drop={handleDrop}
  on:dragover={handleDragOver}
  style="border: 2px dashed #ccc; padding: 2rem; text-align: center"
>
  <input
    bind:this={inputRef}
    type="file"
    multiple
    on:change={handleFileChange}
    style="display: none"
  />
  <p>Drag and drop files here or</p>
  <button on:click={openFileDialog}>Select Files</button>
  {#if $files.length > 0}
    <div>
      <p>Selected: {$files.length} files</p>
      <button on:click={handleUpload}>Upload</button>
    </div>
  {/if}
</div>
```

## File Operations [#file-operations]

### Get File [#get-file]

```svelte
<script lang="ts">
  import { onMount, onDestroy } from "svelte";
  import { createGetFile } from "@visulima/storage-client/svelte";

  export let fileId: string;

  const { data, isLoading, error, meta } = createGetFile({
    endpoint: "/api/files",
    id: () => fileId,
  });

  let url: string | null = null;

  $: {
    if ($data) {
      url = URL.createObjectURL($data);
    }
  }

  onDestroy(() => {
    if (url) {
      URL.revokeObjectURL(url);
    }
  });
</script>

{#if $isLoading}
  <div>Loading...</div>
{:else if $error}
  <div>Error: {$error.message}</div>
{:else if $data && url}
  <div>
    <img src={url} alt={$meta?.filename || "File"} />
    {#if $meta}
      <p>Filename: {$meta.filename}</p>
    {/if}
  </div>
{/if}
```

### Delete File [#delete-file]

```svelte
<script lang="ts">
  import { createDeleteFile } from "@visulima/storage-client/svelte";

  export let fileId: string;

  const { deleteFile, isLoading } = createDeleteFile({
    endpoint: "/api/files",
  });
</script>

<button on:click={() => deleteFile(fileId)} disabled={$isLoading}>
  {$isLoading ? "Deleting..." : "Delete"}
</button>
```

## SvelteKit Integration [#sveltekit-integration]

### Server Routes [#server-routes]

Set up upload endpoints in SvelteKit:

```ts
// src/routes/api/upload/multipart/+server.ts
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "$lib/storage";
import type { RequestHandler } from "./$types";

const multipart = createHandler({ storage, type: "multipart" });

export const POST: RequestHandler = async ({ request }) => {
    return multipart.fetch(request);
};
```

### Storage Configuration [#storage-configuration]

```ts
// src/lib/storage.ts
import { DiskStorage } from "@visulima/storage";

export const storage = new DiskStorage({
    directory: "./uploads",
});
```

## File Operations [#file-operations-1]

### Get File Metadata [#get-file-metadata]

```svelte
<script lang="ts">
  import { createGetFileMeta } from "@visulima/storage-client/svelte";

  export let fileId: string;

  const { data: meta, isLoading, error } = createGetFileMeta({
    endpoint: "/api/files",
    id: () => fileId,
  });
</script>

{#if $isLoading}
  <div>Loading...</div>
{:else if $error}
  <div>Error: {$error.message}</div>
{:else if $meta}
  <div>
    <p>Filename: {$meta.filename}</p>
    <p>Size: {$meta.size} bytes</p>
    <p>Content Type: {$meta.contentType}</p>
    {#if $meta.url}
      <p>URL: {$meta.url}</p>
    {/if}
  </div>
{/if}
```

### Head File (Check Upload Status) [#head-file-check-upload-status]

```svelte
<script lang="ts">
  import { createHeadFile } from "@visulima/storage-client/svelte";

  export let fileId: string;

  const { data, isLoading } = createHeadFile({
    endpoint: "/api/files",
    id: () => fileId,
  });
</script>

{#if $isLoading}
  <div>Checking status...</div>
{:else if $data}
  <div>
    {#if $data.uploadComplete}
      <p>Upload complete</p>
    {:else}
      <p>Upload in progress: {$data.uploadOffset} / {$data.contentLength} bytes</p>
    {/if}
    {#if $data.receivedChunks}
      <p>Received chunks: {$data.receivedChunks.length}</p>
    {/if}
  </div>
{/if}
```

### Put File (Create/Update) [#put-file-createupdate]

```svelte
<script lang="ts">
  import { createPutFile } from "@visulima/storage-client/svelte";

  export let fileId: string;

  let file: File | null = null;
  const { putFile, progress, isLoading, error, data } = createPutFile({
    endpoint: "/api/files",
    onSuccess: (result) => {
      console.log("File uploaded:", result);
    },
  });

  const handleFileChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    file = target.files?.[0] || null;
  };

  const handleUpload = async () => {
    if (file) {
      await putFile(fileId, file);
    }
  };
</script>

<div>
  <input type="file" on:change={handleFileChange} />
  <button on:click={handleUpload} disabled={!file || $isLoading}>
    {$isLoading ? `Uploading... ${$progress}%` : "Upload"}
  </button>
  {#if $error}
    <div>Error: {$error.message}</div>
  {/if}
  {#if $data}
    <div>Upload complete! ID: {$data.id}</div>
  {/if}
</div>
```

### Batch Delete Files [#batch-delete-files]

```svelte
<script lang="ts">
  import { createBatchDeleteFiles } from "@visulima/storage-client/svelte";

  const { batchDeleteFiles, isLoading } = createBatchDeleteFiles({
    endpoint: "/api/files",
    onSuccess: (result) => {
      console.log(`Deleted ${result.successful} files`);
      if (result.failed) {
        console.log(`${result.failed} files failed to delete`);
      }
    },
  });

  const handleDelete = async () => {
    const fileIds = ["file1", "file2", "file3"];
    await batchDeleteFiles(fileIds);
  };
</script>

<button on:click={handleDelete} disabled={$isLoading}>
  {$isLoading ? "Deleting..." : "Delete Selected Files"}
</button>
```

## Transform Operations [#transform-operations]

### Transform File [#transform-file]

```svelte
<script lang="ts">
  import { createTransformFile } from "@visulima/storage-client/svelte";

  export let fileId: string;

  let transform = { width: 800, height: 600, quality: 85 };
  const { data, isLoading, error, meta } = createTransformFile({
    endpoint: "/api/files",
    id: () => fileId,
    transform: () => transform,
  });

  let url: string | null = null;

  $: {
    if ($data) {
      url = URL.createObjectURL($data);
    }
  }
</script>

{#if $isLoading}
  <div>Transforming...</div>
{:else if $error}
  <div>Error: {$error.message}</div>
{:else if $data && url}
  <div>
    <img src={url} alt="Transformed" />
    <div>
      <label>
        Width:
        <input
          type="number"
          bind:value={transform.width}
        />
      </label>
      <label>
        Height:
        <input
          type="number"
          bind:value={transform.height}
        />
      </label>
      <label>
        Quality:
        <input
          type="number"
          min="1"
          max="100"
          bind:value={transform.quality}
        />
      </label>
    </div>
  </div>
{/if}
```

### Get Transform Metadata [#get-transform-metadata]

```svelte
<script lang="ts">
  import { createTransformMetadata } from "@visulima/storage-client/svelte";

  const { data, isLoading, error } = createTransformMetadata({
    endpoint: "/api/files",
  });
</script>

{#if $isLoading}
  <div>Loading...</div>
{:else if $error}
  <div>Error: {$error.message}</div>
{:else if $data}
  <div>
    <h3>Available Formats</h3>
    <ul>
      {#each $data.formats || [] as format}
        <li>{format}</li>
      {/each}
    </ul>
    <h3>Available Parameters</h3>
    <ul>
      {#each $data.parameters || [] as param}
        <li>{param}</li>
      {/each}
    </ul>
  </div>
{/if}
```

## Abort Operations [#abort-operations]

### Abort All Uploads [#abort-all-uploads]

```svelte
<script lang="ts">
  import { createAbortAll } from "@visulima/storage-client/svelte";

  const { abortAll } = createAbortAll({
    endpoint: "/api/upload/multipart",
  });
</script>

<button on:click={abortAll}>Abort All Uploads</button>
```

### Abort Batch [#abort-batch]

```svelte
<script lang="ts">
  import { createAbortBatch } from "@visulima/storage-client/svelte";

  export let batchId: string;

  const { abortBatch } = createAbortBatch({
    endpoint: "/api/upload/multipart",
  });
</script>

<button on:click={() => abortBatch(batchId)}>Abort Batch</button>
```

### Abort Item [#abort-item]

```svelte
<script lang="ts">
  import { createAbortItem } from "@visulima/storage-client/svelte";

  export let itemId: string;

  const { abortItem } = createAbortItem({
    endpoint: "/api/upload/multipart",
  });
</script>

<button on:click={() => abortItem(itemId)}>Abort Upload</button>
```

## Retry Operations [#retry-operations]

### Retry Failed Upload [#retry-failed-upload]

```svelte
<script lang="ts">
  import { createRetry } from "@visulima/storage-client/svelte";

  export let itemId: string;

  const { retryItem } = createRetry({
    endpoint: "/api/upload/multipart",
  });
</script>

<button on:click={() => retryItem(itemId)}>Retry Upload</button>
```

### Batch Retry [#batch-retry]

```svelte
<script lang="ts">
  import { createBatchRetry } from "@visulima/storage-client/svelte";

  export let batchId: string;

  const { retryBatch } = createBatchRetry({
    endpoint: "/api/upload/multipart",
  });
</script>

<button on:click={() => retryBatch(batchId)}>Retry Failed Items in Batch</button>
```

## Event Listeners [#event-listeners]

### Batch Event Listeners [#batch-event-listeners]

```svelte
<script lang="ts">
  import {
    createBatchStartListener,
    createBatchProgressListener,
    createBatchFinishListener,
    createBatchErrorListener,
  } from "@visulima/storage-client/svelte";

  createBatchStartListener({
    endpoint: "/api/upload/multipart",
    onBatchStart: (batchId) => {
      console.log("Batch started:", batchId);
    },
  });

  createBatchProgressListener({
    endpoint: "/api/upload/multipart",
    onBatchProgress: (progress, batchId) => {
      console.log(`Batch ${batchId} progress: ${progress}%`);
    },
  });

  createBatchFinishListener({
    endpoint: "/api/upload/multipart",
    onBatchFinish: (results, batchId) => {
      console.log(`Batch ${batchId} finished:`, results);
    },
  });

  createBatchErrorListener({
    endpoint: "/api/upload/multipart",
    onBatchError: (error, batchId) => {
      console.error(`Batch ${batchId} error:`, error);
    },
  });
</script>

<div>Upload component with listeners</div>
```

## Next Steps [#next-steps]

* [API Reference](/docs/packages/storage-client/api) - Complete API documentation
* Examples - See working examples in the examples folder


# TanStack Start (/docs/packages/storage-client/tanstack-start)



# TanStack Start [#tanstack-start]

Use `@visulima/storage-client` with TanStack Start for full-stack React applications with file uploads.

## Installation [#installation]

```bash
npm install @visulima/storage-client @tanstack/react-query @tanstack/react-router
```

## Setup QueryClient [#setup-queryclient]

TanStack Start includes QueryClient setup. Ensure it's configured in your root route:

```tsx
// src/routes/__root.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createRootRoute, Outlet } from "@tanstack/react-router";

const queryClient = new QueryClient();

export const Route = createRootRoute({
    component: () => (
        <QueryClientProvider client={queryClient}>
            <Outlet />
        </QueryClientProvider>
    ),
});
```

## Upload Component [#upload-component]

Create an upload page using React Router:

```tsx
// src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import type { UploadResult } from "@visulima/storage-client/react";
import { useUpload } from "@visulima/storage-client/react";
import { useRef, useState } from "react";

const Home = () => {
    const [file, setFile] = useState<File | null>(null);
    const fileInputRef = useRef<HTMLInputElement>(null);
    const { error, isUploading, progress, reset, result, upload } = useUpload({
        endpointMultipart: "/api/upload/multipart",
        endpointTus: "/api/upload/tus",
        onError: (error_: Error) => console.error("Upload error:", error_),
        onProgress: (p: number) => console.log("Upload progress:", p),
        onSuccess: (res: UploadResult) => {
            console.log("Upload successful:", res);
            setFile(null);
            if (fileInputRef.current) {
                fileInputRef.current.value = "";
            }
        },
    });

    const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const selectedFile = e.target.files?.[0];
        setFile(selectedFile || null);
    };

    const handleUpload = async () => {
        if (file) {
            try {
                await upload(file);
            } catch (error_) {
                console.error("Upload failed:", error_);
            }
        }
    };

    const handleReset = () => {
        reset();
        setFile(null);
        if (fileInputRef.current) {
            fileInputRef.current.value = "";
        }
    };

    return (
        <div style={{ margin: "0 auto", maxWidth: "800px", padding: "2rem" }}>
            <h1>File Upload Example</h1>
            <p>Upload files using @visulima/storage-client with TanStack Start</p>

            <div style={{ marginTop: "2rem" }}>
                <input disabled={isUploading} onChange={handleFileChange} ref={fileInputRef} type="file" />
                <button disabled={!file || isUploading} onClick={handleUpload} style={{ marginLeft: "1rem", padding: "0.5rem 1rem" }}>
                    {isUploading ? `Uploading... ${progress}%` : "Upload"}
                </button>
                <button disabled={isUploading} onClick={handleReset} style={{ marginLeft: "0.5rem", padding: "0.5rem 1rem" }}>
                    Reset
                </button>
            </div>

            {isUploading && (
                <div style={{ marginTop: "1rem" }}>
                    <div>
                        Progress:
                        {progress}%
                    </div>
                    <progress max={100} style={{ maxWidth: "400px", width: "100%" }} value={progress} />
                </div>
            )}

            {error && (
                <div
                    style={{
                        backgroundColor: "#fee",
                        borderRadius: "4px",
                        color: "#c33",
                        marginTop: "1rem",
                        padding: "1rem",
                    }}
                >
                    Error:
                    {error.message}
                </div>
            )}

            {result && (
                <div
                    style={{
                        backgroundColor: "#efe",
                        borderRadius: "4px",
                        color: "#3c3",
                        marginTop: "1rem",
                        padding: "1rem",
                    }}
                >
                    <div>Upload complete!</div>
                    <div>
                        File ID:
                        {result.id}
                    </div>
                    {result.filename && (
                        <div>
                            Filename:
                            {result.filename}
                        </div>
                    )}
                    {result.url && (
                        <div>
                            URL:{" "}
                            <a href={result.url} rel="noopener noreferrer" target="_blank">
                                {result.url}
                            </a>
                        </div>
                    )}
                </div>
            )}
        </div>
    );
};

export const Route = createFileRoute("/")({
    component: Home,
});
```

## API Routes [#api-routes]

Set up upload API routes:

```tsx
// src/routes/api.upload.multipart.ts
import { createHandler } from "@visulima/storage/handler/http/fetch";
import { storage } from "@/lib/storage";

const multipart = createHandler({ storage, type: "multipart" });

export async function POST(request: Request) {
    return multipart.fetch(request);
}

export async function DELETE(request: Request) {
    return multipart.fetch(request);
}

export async function GET(request: Request) {
    return multipart.fetch(request);
}

export async function OPTIONS(request: Request) {
    return multipart.fetch(request);
}
```

## Storage Configuration [#storage-configuration]

```tsx
// src/lib/storage.ts
import { DiskStorage } from "@visulima/storage";

export const storage = new DiskStorage({
    directory: "./uploads",
});
```

## TypeScript Configuration [#typescript-configuration]

Ensure your routes are properly typed:

```tsx
// src/routes/__root.tsx
import { createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
    component: () => <Outlet />,
});
```

## Next Steps [#next-steps]

* [React Guide](/docs/packages/storage-client/react) - Learn React-specific features
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# Vue / Nuxt (/docs/packages/storage-client/vue)



# Vue / Nuxt [#vue--nuxt]

Use `@visulima/storage-client` with Vue 3 and Nuxt 3 for file uploads with composables and TanStack Vue Query integration.

## Installation [#installation]

### Vue 3 [#vue-3]

```bash
npm install @visulima/storage-client @tanstack/vue-query vue
```

### Nuxt 3 [#nuxt-3]

```bash
npm install @visulima/storage-client @tanstack/vue-query
```

## Setup QueryClient [#setup-queryclient]

### Vue 3 [#vue-3-1]

```ts
import { createApp } from "vue";
import { VueQueryPlugin } from "@tanstack/vue-query";
import App from "./App.vue";

const app = createApp(App);
app.use(VueQueryPlugin);
app.mount("#app");
```

### Nuxt 3 [#nuxt-3-1]

Create a plugin file:

```ts
// plugins/vue-query.client.ts
import { VueQueryPlugin } from "@tanstack/vue-query";

export default defineNuxtPlugin((nuxtApp) => {
    nuxtApp.vueApp.use(VueQueryPlugin);
});
```

## Basic Upload [#basic-upload]

Use the `useUpload` composable for automatic method selection:

```vue
<template>
    <div class="app">
        <h1>Storage Client - Vue Example</h1>
        <div class="upload-section">
            <input type="file" @change="handleFileChange" :disabled="isUploading" ref="fileInputRef" />
            <button @click="handleUpload" :disabled="!file || isUploading">
                {{ isUploading ? "Uploading..." : "Upload" }}
            </button>
        </div>
        <div v-if="isUploading" class="progress-section">
            <div>Progress: {{ progress }}%</div>
            <progress :value="progress" max="100" />
        </div>
        <div v-if="error" class="error">Error: {{ error.message }}</div>
        <div v-if="result" class="success">Upload complete! File: {{ result.filename }}</div>
    </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useUpload } from "@visulima/storage-client/vue";

const file = ref<File | null>(null);
const fileInputRef = ref<HTMLInputElement | null>(null);
const { upload, progress, isUploading, error, result } = useUpload({
    endpointMultipart: "/api/upload/multipart",
    endpointTus: "/api/upload/tus",
    onSuccess: (result) => {
        console.log("Upload successful:", result);
        file.value = null;
        if (fileInputRef.value) {
            fileInputRef.value.value = "";
        }
    },
    onError: (error_) => {
        console.error("Upload error:", error_);
    },
});

const handleFileChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    const selectedFile = target.files?.[0];
    file.value = selectedFile || null;
};

const handleUpload = async () => {
    if (file.value) {
        try {
            await upload(file.value);
        } catch (error_) {
            console.error("Upload failed:", error_);
        }
    }
};
</script>
```

## Multipart Upload [#multipart-upload]

For traditional form-based uploads:

```vue
<script setup lang="ts">
import { useMultipartUpload } from "@visulima/storage-client/vue";

const { upload, progress, isUploading } = useMultipartUpload({
    endpoint: "/api/upload/multipart",
});

const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
        await upload(file);
    }
};
</script>

<template>
    <div>
        <input type="file" @change="handleFileChange" />
        <div v-if="isUploading">
            <progress :value="progress" max="100" />
        </div>
    </div>
</template>
```

## TUS Resumable Upload [#tus-resumable-upload]

For large files with pause/resume support:

```vue
<script setup lang="ts">
import { useTusUpload } from "@visulima/storage-client/vue";

const { upload, pause, resume, progress, isUploading, isPaused } = useTusUpload({
    endpoint: "/api/upload/tus",
});

const handleFileChange = async (e: Event) => {
    const target = e.target as HTMLInputElement;
    const file = target.files?.[0];
    if (file) {
        await upload(file);
    }
};
</script>

<template>
    <div>
        <input type="file" @change="handleFileChange" />
        <div v-if="isUploading">
            <progress :value="progress" max="100" />
            <button v-if="isPaused" @click="resume">Resume</button>
            <button v-else @click="pause">Pause</button>
        </div>
    </div>
</template>
```

## Batch Upload [#batch-upload]

Upload multiple files simultaneously:

```vue
<script setup lang="ts">
import { useBatchUpload } from "@visulima/storage-client/vue";

const { uploadBatch, progress, isUploading, items, completedCount, errorCount } = useBatchUpload({
    endpoint: "/api/upload/multipart",
    onSuccess: (results) => {
        console.log("Batch upload complete:", results);
    },
});

const handleFilesChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    const files = Array.from(target.files || []);
    if (files.length > 0) {
        uploadBatch(files);
    }
};
</script>

<template>
    <div>
        <input type="file" multiple @change="handleFilesChange" />
        <div v-if="isUploading">
            <div>Progress: {{ progress }}%</div>
            <div>Completed: {{ completedCount }} / {{ items.length }}</div>
            <div>Errors: {{ errorCount }}</div>
        </div>
    </div>
</template>
```

## File Input Composable [#file-input-composable]

Use the `useFileInput` composable for drag & drop support:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useFileInput } from "@visulima/storage-client/vue";
import { useBatchUpload } from "@visulima/storage-client/vue";

const { files, inputRef, handleFileChange, handleDrop, handleDragOver, openFileDialog } = useFileInput({
    multiple: true,
});

const { uploadBatch } = useBatchUpload({
    endpoint: "/api/upload/multipart",
});

const handleUpload = () => {
    if (files.value.length > 0) {
        uploadBatch(files.value);
    }
};
</script>

<template>
    <div @drop="handleDrop" @dragover="handleDragOver" style="border: 2px dashed #ccc; padding: 2rem; text-align: center">
        <input ref="inputRef" type="file" multiple @change="handleFileChange" style="display: none" />
        <p>Drag and drop files here or</p>
        <button @click="openFileDialog">Select Files</button>
        <div v-if="files.length > 0">
            <p>Selected: {{ files.length }} files</p>
            <button @click="handleUpload">Upload</button>
        </div>
    </div>
</template>
```

## File Operations [#file-operations]

### Get File [#get-file]

```vue
<script setup lang="ts">
import { ref, watch } from "vue";
import { useGetFile } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const { data, isLoading, error, meta } = useGetFile({
    endpoint: "/api/files",
    id: () => props.fileId,
});

const url = ref<string | null>(null);

watch(data, (blob) => {
    if (blob) {
        url.value = URL.createObjectURL(blob);
    }
});
</script>

<template>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <div v-else-if="data && url">
        <img :src="url" :alt="meta?.filename || 'File'" />
        <p v-if="meta">Filename: {{ meta.filename }}</p>
    </div>
</template>
```

### Delete File [#delete-file]

```vue
<script setup lang="ts">
import { useDeleteFile } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const { deleteFile, isLoading } = useDeleteFile({
    endpoint: "/api/files",
});
</script>

<template>
    <button @click="() => deleteFile(props.fileId)" :disabled="isLoading">
        {{ isLoading ? "Deleting..." : "Delete" }}
    </button>
</template>
```

### Get File Metadata [#get-file-metadata]

```vue
<script setup lang="ts">
import { useGetFileMeta } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const {
    data: meta,
    isLoading,
    error,
} = useGetFileMeta({
    endpoint: "/api/files",
    id: () => props.fileId,
});
</script>

<template>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <div v-else-if="meta">
        <p>Filename: {{ meta.filename }}</p>
        <p>Size: {{ meta.size }} bytes</p>
        <p>Content Type: {{ meta.contentType }}</p>
        <p v-if="meta.url">URL: {{ meta.url }}</p>
    </div>
</template>
```

### Head File (Check Upload Status) [#head-file-check-upload-status]

```vue
<script setup lang="ts">
import { useHeadFile } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const { data, isLoading } = useHeadFile({
    endpoint: "/api/files",
    id: () => props.fileId,
});
</script>

<template>
    <div v-if="isLoading">Checking status...</div>
    <div v-else-if="data">
        <p v-if="data.uploadComplete">Upload complete</p>
        <p v-else>Upload in progress: {{ data.uploadOffset }} / {{ data.contentLength }} bytes</p>
        <p v-if="data.receivedChunks">Received chunks: {{ data.receivedChunks.length }}</p>
    </div>
</template>
```

### Put File (Create/Update) [#put-file-createupdate]

```vue
<script setup lang="ts">
import { ref } from "vue";
import { usePutFile } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const file = ref<File | null>(null);
const { putFile, progress, isLoading, error, data } = usePutFile({
    endpoint: "/api/files",
    onSuccess: (result) => {
        console.log("File uploaded:", result);
    },
});

const handleFileChange = (e: Event) => {
    const target = e.target as HTMLInputElement;
    file.value = target.files?.[0] || null;
};

const handleUpload = async () => {
    if (file.value) {
        await putFile(props.fileId, file.value);
    }
};
</script>

<template>
    <div>
        <input type="file" @change="handleFileChange" />
        <button @click="handleUpload" :disabled="!file || isLoading">
            {{ isLoading ? `Uploading... ${progress}%` : "Upload" }}
        </button>
        <div v-if="error">Error: {{ error.message }}</div>
        <div v-if="data">Upload complete! ID: {{ data.id }}</div>
    </div>
</template>
```

### Batch Delete Files [#batch-delete-files]

```vue
<script setup lang="ts">
import { useBatchDeleteFiles } from "@visulima/storage-client/vue";

const { batchDeleteFiles, isLoading } = useBatchDeleteFiles({
    endpoint: "/api/files",
    onSuccess: (result) => {
        console.log(`Deleted ${result.successful} files`);
        if (result.failed) {
            console.log(`${result.failed} files failed to delete`);
        }
    },
});

const handleDelete = async () => {
    const fileIds = ["file1", "file2", "file3"];
    await batchDeleteFiles(fileIds);
};
</script>

<template>
    <button @click="handleDelete" :disabled="isLoading">
        {{ isLoading ? "Deleting..." : "Delete Selected Files" }}
    </button>
</template>
```

## Transform Operations [#transform-operations]

### Transform File [#transform-file]

```vue
<script setup lang="ts">
import { ref, watch } from "vue";
import { useTransformFile } from "@visulima/storage-client/vue";

const props = defineProps<{ fileId: string }>();

const transform = ref({ width: 800, height: 600, quality: 85 });
const { data, isLoading, error, meta } = useTransformFile({
    endpoint: "/api/files",
    id: () => props.fileId,
    transform: () => transform.value,
});

const url = ref<string | null>(null);

watch(data, (blob) => {
    if (blob) {
        url.value = URL.createObjectURL(blob);
    }
});
</script>

<template>
    <div v-if="isLoading">Transforming...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <div v-else-if="data && url">
        <img :src="url" alt="Transformed" />
        <div>
            <label>
                Width:
                <input type="number" :value="transform.width" @input="transform.width = Number(($event.target as HTMLInputElement).value)" />
            </label>
            <label>
                Height:
                <input type="number" :value="transform.height" @input="transform.height = Number(($event.target as HTMLInputElement).value)" />
            </label>
            <label>
                Quality:
                <input
                    type="number"
                    min="1"
                    max="100"
                    :value="transform.quality"
                    @input="transform.quality = Number(($event.target as HTMLInputElement).value)"
                />
            </label>
        </div>
    </div>
</template>
```

### Get Transform Metadata [#get-transform-metadata]

```vue
<script setup lang="ts">
import { useTransformMetadata } from "@visulima/storage-client/vue";

const { data, isLoading, error } = useTransformMetadata({
    endpoint: "/api/files",
});
</script>

<template>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <div v-else-if="data">
        <h3>Available Formats</h3>
        <ul>
            <li v-for="format in data.formats" :key="format">{{ format }}</li>
        </ul>
        <h3>Available Parameters</h3>
        <ul>
            <li v-for="param in data.parameters" :key="param">{{ param }}</li>
        </ul>
    </div>
</template>
```

## Abort Operations [#abort-operations]

### Abort All Uploads [#abort-all-uploads]

```vue
<script setup lang="ts">
import { useAbortAll } from "@visulima/storage-client/vue";

const { abortAll } = useAbortAll({
    endpoint: "/api/upload/multipart",
});
</script>

<template>
    <button @click="abortAll">Abort All Uploads</button>
</template>
```

### Abort Batch [#abort-batch]

```vue
<script setup lang="ts">
import { useAbortBatch } from "@visulima/storage-client/vue";

const props = defineProps<{ batchId: string }>();

const { abortBatch } = useAbortBatch({
    endpoint: "/api/upload/multipart",
});
</script>

<template>
    <button @click="() => abortBatch(props.batchId)">Abort Batch</button>
</template>
```

### Abort Item [#abort-item]

```vue
<script setup lang="ts">
import { useAbortItem } from "@visulima/storage-client/vue";

const props = defineProps<{ itemId: string }>();

const { abortItem } = useAbortItem({
    endpoint: "/api/upload/multipart",
});
</script>

<template>
    <button @click="() => abortItem(props.itemId)">Abort Upload</button>
</template>
```

## Retry Operations [#retry-operations]

### Retry Failed Upload [#retry-failed-upload]

```vue
<script setup lang="ts">
import { useRetry } from "@visulima/storage-client/vue";

const props = defineProps<{ itemId: string }>();

const { retryItem } = useRetry({
    endpoint: "/api/upload/multipart",
});
</script>

<template>
    <button @click="() => retryItem(props.itemId)">Retry Upload</button>
</template>
```

### Batch Retry [#batch-retry]

```vue
<script setup lang="ts">
import { useBatchRetry } from "@visulima/storage-client/vue";

const props = defineProps<{ batchId: string }>();

const { retryBatch } = useBatchRetry({
    endpoint: "/api/upload/multipart",
});
</script>

<template>
    <button @click="() => retryBatch(props.batchId)">Retry Failed Items in Batch</button>
</template>
```

## Nuxt-Specific Features [#nuxt-specific-features]

### Server-Side Setup [#server-side-setup]

In Nuxt, you can set up upload endpoints using server routes:

```ts
// server/api/upload/multipart.post.ts
import { DiskStorage } from "@visulima/storage";
import { Multipart } from "@visulima/storage/handler/http/node";

const storage = new DiskStorage({ directory: "./uploads" });
const multipart = new Multipart({ storage });

export default defineEventHandler(async (event) => {
    event.node.res.setHeader("Access-Control-Allow-Origin", "*");
    await multipart.handle(event.node.req, event.node.res);
});
```

### Using with Nuxt Module [#using-with-nuxt-module]

If you're using the `@visulima/storage` Nuxt module, endpoints are automatically registered:

```ts
// nuxt.config.ts
import { DiskStorage } from "@visulima/storage";
import storageModule from "@visulima/storage/adapter/nuxt";

export default defineNuxtConfig({
    modules: [
        [
            storageModule,
            {
                storage: new DiskStorage({
                    directory: "./uploads",
                }),
            },
        ],
    ],
});
```

Then use the client in your components:

```vue
<script setup lang="ts">
import { useUpload } from "@visulima/storage-client/vue";

const { upload, progress, isUploading } = useUpload({
    endpointMultipart: "/api/upload/multipart",
    endpointTus: "/api/upload/tus",
});
</script>
```

## Event Listeners [#event-listeners]

### Batch Event Listeners [#batch-event-listeners]

Listen to batch upload events:

```vue
<script setup lang="ts">
import { useBatchStartListener, useBatchProgressListener, useBatchFinishListener, useBatchErrorListener } from "@visulima/storage-client/vue";

useBatchStartListener({
    endpoint: "/api/upload/multipart",
    onBatchStart: (batchId) => {
        console.log("Batch started:", batchId);
    },
});

useBatchProgressListener({
    endpoint: "/api/upload/multipart",
    onBatchProgress: (progress, batchId) => {
        console.log(`Batch ${batchId} progress: ${progress}%`);
    },
});

useBatchFinishListener({
    endpoint: "/api/upload/multipart",
    onBatchFinish: (results, batchId) => {
        console.log(`Batch ${batchId} finished:`, results);
    },
});

useBatchErrorListener({
    endpoint: "/api/upload/multipart",
    onBatchError: (error, batchId) => {
        console.error(`Batch ${batchId} error:`, error);
    },
});
</script>

<template>
    <div>Upload component with listeners</div>
</template>
```

### Retry Listener [#retry-listener]

```vue
<script setup lang="ts">
import { useRetryListener } from "@visulima/storage-client/vue";

useRetryListener({
    endpoint: "/api/upload/multipart",
    onRetry: (itemId) => {
        console.log("Retrying item:", itemId);
    },
});
</script>

<template>
    <!-- This is just a listener -->
</template>
```

### All Abort Listener [#all-abort-listener]

```vue
<script setup lang="ts">
import { useAllAbortListener } from "@visulima/storage-client/vue";

useAllAbortListener({
    endpoint: "/api/upload/multipart",
    onAbortAll: () => {
        console.log("All uploads aborted");
    },
});
</script>

<template>
    <!-- This is just a listener -->
</template>
```

## Next Steps [#next-steps]

* [React Guide](/docs/packages/storage-client/react) - Compare with React implementation
* [API Reference](/docs/packages/storage-client/api) - Complete API documentation


# Case Conversion API (/docs/packages/string/api/case)



# Case Conversion API [#case-conversion-api]

Detailed API reference for all case conversion functions, their signatures, options, and return types.

## camelCase [#camelcase]

Converts a string to camelCase format.

```typescript
function camelCase<T extends string = string>(value?: T, options?: CaseOptions): CamelCase<T>;
```

**Import:**

```typescript
import { camelCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import camelCase from "@visulima/string/case/camel-case";
```

**Parameters:**

| Parameter | Type               | Description                                                         |
| --------- | ------------------ | ------------------------------------------------------------------- |
| `value`   | `T extends string` | The string to convert. Returns `""` if `undefined` or not a string. |
| `options` | `CaseOptions`      | Optional configuration for case conversion.                         |

**Returns:** `CamelCase<T>` -- The string converted to camelCase.

**Examples:**

```typescript
camelCase("foo bar"); // 'fooBar'
camelCase("foo-bar"); // 'fooBar'
camelCase("foo_bar"); // 'fooBar'
camelCase("XMLHttpRequest"); // 'xmlHttpRequest'
camelCase("AJAXRequest"); // 'ajaxRequest'
camelCase("QueryXML123String"); // 'queryXml123String'
camelCase(undefined); // ''
```

***

## pascalCase [#pascalcase]

Converts a string to PascalCase format.

```typescript
function pascalCase<T extends string = string>(value?: T, options?: CaseOptions): PascalCase<T>;
```

**Import:**

```typescript
import { pascalCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import pascalCase from "@visulima/string/case/pascal-case";
```

**Parameters:**

| Parameter | Type               | Description             |
| --------- | ------------------ | ----------------------- |
| `value`   | `T extends string` | The string to convert.  |
| `options` | `CaseOptions`      | Optional configuration. |

**Returns:** `PascalCase<T>` -- The string converted to PascalCase.

**Examples:**

```typescript
pascalCase("foo bar"); // 'FooBar'
pascalCase("foo-bar"); // 'FooBar'
pascalCase("foo_bar"); // 'FooBar'
pascalCase("XMLHttpRequest"); // 'XmlHttpRequest'
```

***

## snakeCase [#snakecase]

Converts a string to snake\_case format.

```typescript
function snakeCase<T extends string = string>(value?: T, options?: CaseOptions): SnakeCase<T>;
```

**Import:**

```typescript
import { snakeCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import snakeCase from "@visulima/string/case/snake-case";
```

**Parameters:**

| Parameter | Type               | Description             |
| --------- | ------------------ | ----------------------- |
| `value`   | `T extends string` | The string to convert.  |
| `options` | `CaseOptions`      | Optional configuration. |

**Returns:** `SnakeCase<T>` -- The string converted to snake\_case.

**Examples:**

```typescript
snakeCase("fooBar"); // 'foo_bar'
snakeCase("foo bar"); // 'foo_bar'
snakeCase("foo-bar"); // 'foo_bar'
snakeCase("XMLHttpRequest"); // 'xml_http_request'
```

***

## kebabCase [#kebabcase]

Converts a string to kebab-case format.

```typescript
function kebabCase<T extends string = string>(value?: T, options?: KebabCaseOptions): KebabCase<T>;
```

**Import:**

```typescript
import { kebabCase } from "@visulima/string/case";
// or (named export from per-file subpath)
import { kebabCase } from "@visulima/string/case/kebab-case";
```

**Parameters:**

| Parameter | Type               | Description             |
| --------- | ------------------ | ----------------------- |
| `value`   | `T extends string` | The string to convert.  |
| `options` | `KebabCaseOptions` | Optional configuration. |

**Returns:** `KebabCase<T>` -- The string converted to kebab-case.

**Examples:**

```typescript
kebabCase("fooBar"); // 'foo-bar'
kebabCase("foo bar"); // 'foo-bar'
kebabCase("foo_bar"); // 'foo-bar'
kebabCase("XMLHttpRequest"); // 'xml-http-request'
```

### KebabCaseOptions [#kebabcaseoptions]

Extends `CaseOptions` with additional options:

```typescript
interface KebabCaseOptions extends CaseOptions {
    /** String used to join words. @default "-" */
    joiner?: string;

    /** Whether to convert the result to uppercase. @default false */
    toUpperCase?: boolean;
}
```

***

## constantCase [#constantcase]

Converts a string to CONSTANT\_CASE format.

```typescript
function constantCase<T extends string = string>(value?: T, options?: CaseOptions): ConstantCase<T>;
```

**Import:**

```typescript
import { constantCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import constantCase from "@visulima/string/case/constant-case";
```

**Parameters:**

| Parameter | Type               | Description             |
| --------- | ------------------ | ----------------------- |
| `value`   | `T extends string` | The string to convert.  |
| `options` | `CaseOptions`      | Optional configuration. |

**Returns:** `ConstantCase<T>` -- The string converted to CONSTANT\_CASE.

**Examples:**

```typescript
constantCase("foo bar"); // 'FOO_BAR'
constantCase("foo-bar"); // 'FOO_BAR'
constantCase("XMLHttpRequest"); // 'XML_HTTP_REQUEST'
```

***

## dotCase [#dotcase]

Converts a string to dot.case format.

```typescript
function dotCase<T extends string = string>(value?: T, options?: CaseOptions): DotCase<T>;
```

**Import:**

```typescript
import { dotCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import dotCase from "@visulima/string/case/dot-case";
```

**Examples:**

```typescript
dotCase("foo bar"); // 'foo.bar'
dotCase("XMLHttpRequest"); // 'xml.http.request'
```

***

## pathCase [#pathcase]

Converts a string to path/case format.

```typescript
function pathCase<T extends string = string>(value?: T, options?: CaseOptions): PathCase<T>;
```

**Import:**

```typescript
import { pathCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import pathCase from "@visulima/string/case/path-case";
```

**Examples:**

```typescript
pathCase("foo bar"); // 'foo/bar'
pathCase("XMLHttpRequest"); // 'xml/http/request'
```

***

## titleCase [#titlecase]

Converts a string to Title Case format.

```typescript
function titleCase<T extends string = string>(value?: T, options?: CaseOptions): TitleCase<T>;
```

**Import:**

```typescript
import { titleCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import titleCase from "@visulima/string/case/title-case";
```

**Examples:**

```typescript
titleCase("this-IS-aTitle"); // 'This Is A Title'
titleCase("XMLHttpRequest"); // 'Xml Http Request'
```

***

## sentenceCase [#sentencecase]

Converts a string to Sentence case format.

```typescript
function sentenceCase<T extends string = string>(value?: T, options?: CaseOptions): SentenceCase<T>;
```

**Import:**

```typescript
import { sentenceCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import sentenceCase from "@visulima/string/case/sentence-case";
```

**Examples:**

```typescript
sentenceCase("foo bar"); // 'Foo bar'
sentenceCase("XMLHttpRequest"); // 'Xml http request'
```

***

## capitalCase [#capitalcase]

Converts a string to Capital Case format (each word capitalized, separated by spaces).

```typescript
function capitalCase<T extends string = string>(value?: T, options?: CaseOptions): CapitalCase<T>;
```

**Import:**

```typescript
import { capitalCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import capitalCase from "@visulima/string/case/capital-case";
```

**Examples:**

```typescript
capitalCase("foo bar"); // 'Foo Bar'
capitalCase("foo-bar"); // 'Foo Bar'
```

***

## flatCase [#flatcase]

Converts a string to flatcase format (no separators, all lowercase).

```typescript
function flatCase<T extends string = string>(value?: T, options?: CaseOptions): FlatCase<T>;
```

**Import:**

```typescript
import { flatCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import flatCase from "@visulima/string/case/flat-case";
```

**Examples:**

```typescript
flatCase("foo bar"); // 'foobar'
flatCase("foo-bar"); // 'foobar'
```

***

## trainCase [#traincase]

Converts a string to Train-Case format (each word capitalized, hyphen-separated).

```typescript
function trainCase<T extends string = string>(value?: T, options?: CaseOptions): TrainCase<T>;
```

**Import:**

```typescript
import { trainCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import trainCase from "@visulima/string/case/train-case";
```

**Examples:**

```typescript
trainCase("foo bar"); // 'Foo-Bar'
trainCase("XMLHttpRequest"); // 'Xml-Http-Request'
```

***

## pascalSnakeCase [#pascalsnakecase]

Converts a string to Pascal\_Snake\_Case format (each word capitalized, underscore-separated).

```typescript
function pascalSnakeCase<T extends string = string>(value?: T, options?: CaseOptions): PascalSnakeCase<T>;
```

**Import:**

```typescript
import { pascalSnakeCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import pascalSnakeCase from "@visulima/string/case/pascal-snake-case";
```

**Examples:**

```typescript
pascalSnakeCase("foo bar"); // 'Foo_Bar'
pascalSnakeCase("XMLHttpRequest"); // 'Xml_Http_Request'
```

***

## noCase [#nocase]

Removes all case styling, converting to lowercase with spaces.

```typescript
function noCase<T extends string = string>(value?: T, options?: CaseOptions): NoCase<T>;
```

**Import:**

```typescript
import { noCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import noCase from "@visulima/string/case/no-case";
```

**Examples:**

```typescript
noCase("camelCase"); // 'camel case'
noCase("PascalCase"); // 'pascal case'
noCase("snake_case"); // 'snake case'
```

***

## flipCase [#flipcase]

Inverts the case of each character in a string.

```typescript
function flipCase<T extends string = string>(value?: T, options?: FlipOptions): FlipCase<T>;
```

**Import:**

```typescript
import { flipCase } from "@visulima/string/case";
// or (named export from per-file subpath)
import { flipCase } from "@visulima/string/case/flip-case";
```

**Parameters:**

| Parameter | Type               | Description                                                                                                            |
| --------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `value`   | `T extends string` | The string to flip case. Returns `""` if undefined or empty.                                                           |
| `options` | `FlipOptions`      | Optional configuration. Same as `CaseOptions` except `handleEmoji` is not available (emojis are preserved by default). |

**Returns:** `FlipCase<T>` -- The string with inverted character cases.

**Examples:**

```typescript
flipCase("FooBar"); // 'fOObAR'
flipCase("foobar"); // 'FOOBAR'
flipCase("FOOBAR"); // 'foobar'
flipCase("Hello World"); // 'hELLO wORLD'
flipCase("XMLHttpRequest"); // 'xmlhTTPrEQUEST'
```

### FlipOptions [#flipoptions]

```typescript
type FlipOptions = Omit<CaseOptions, "handleEmoji">;
```

***

## upperFirst [#upperfirst]

Converts the first character of a string to uppercase.

```typescript
function upperFirst<T extends string = string>(value?: T, options?: LocaleOptions): UpperFirst<T>;
```

**Import:**

```typescript
import { upperFirst } from "@visulima/string/case";
// or (default export from per-file subpath)
import upperFirst from "@visulima/string/case/upper-first";
```

**Examples:**

```typescript
upperFirst("hello"); // 'Hello'
upperFirst("hello world"); // 'Hello world'
```

***

## lowerFirst [#lowerfirst]

Converts the first character of a string to lowercase.

```typescript
function lowerFirst<T extends string = string>(value?: T, options?: LocaleOptions): LowerFirst<T>;
```

**Import:**

```typescript
import { lowerFirst } from "@visulima/string/case";
// or (default export from per-file subpath)
import lowerFirst from "@visulima/string/case/lower-first";
```

**Examples:**

```typescript
lowerFirst("Hello"); // 'hello'
lowerFirst("HELLO"); // 'hELLO'
```

***

## identifyCase [#identifycase]

Identifies the case style of a string.

```typescript
function identifyCase<T extends string = string>(value?: T): IdentifyCase<T>;
```

**Import:**

```typescript
import { identifyCase } from "@visulima/string/case";
// or (default export from per-file subpath)
import identifyCase from "@visulima/string/case/identify-case";
```

**Parameters:**

| Parameter | Type               | Description                                                 |
| --------- | ------------------ | ----------------------------------------------------------- |
| `value`   | `T extends string` | The string to identify. Throws `TypeError` if not a string. |

**Returns:** One of: `'camel'`, `'pascal'`, `'snake'`, `'kebab'`, `'upper_snake'`, `'lower'`, `'upper'`, `'title'`, `'sentence'`, `'mixed'`, or `'unknown'`.

**Examples:**

```typescript
identifyCase("helloWorld"); // 'camel'
identifyCase("HelloWorld"); // 'pascal'
identifyCase("hello_world"); // 'snake'
identifyCase("HELLO_WORLD"); // 'upper_snake'
identifyCase("hello-world"); // 'kebab'
identifyCase("foo"); // 'lower'
identifyCase("FOO"); // 'upper'
identifyCase("Hello World"); // 'title'
identifyCase("Hello world"); // 'sentence'
identifyCase("FooBAR"); // 'mixed'
identifyCase("123"); // 'unknown'
identifyCase(""); // 'unknown'
```

**Throws:** `TypeError` if input is not a string.

***

## splitByCase [#splitbycase]

Splits a string into segments based on case transitions, separators, Unicode scripts, ANSI codes, and emojis.

```typescript
function splitByCase<T extends string = string>(input: T, options?: SplitOptions): SplitByCase<T>;
```

**Import:**

```typescript
import { splitByCase } from "@visulima/string/case";
// or (named export from per-file subpath)
import { splitByCase } from "@visulima/string/case/split-by-case";
```

**Parameters:**

| Parameter | Type               | Description                                    |
| --------- | ------------------ | ---------------------------------------------- |
| `input`   | `T extends string` | The string to split.                           |
| `options` | `SplitOptions`     | Optional configuration for splitting behavior. |

**Returns:** `SplitByCase<T>` -- An array of string segments.

**Examples:**

```typescript
splitByCase("fooBarBaz"); // ['foo', 'Bar', 'Baz']
splitByCase("foo_bar-baz"); // ['foo', 'bar', 'baz']
splitByCase("HTMLElement"); // ['HTML', 'Element']
splitByCase("XMLHttpRequest"); // ['XML', 'Http', 'Request']

// With locale
splitByCase("ひらがなカタカナABC", { locale: "ja" });
// ['ひらがな', 'カタカナ', 'ABC']

// With emoji handling
splitByCase("hello🌍world", { handleEmoji: true });
// ['hello', '🌍', 'world']
```

### SplitOptions [#splitoptions]

```typescript
interface SplitOptions extends LocaleOptions {
    /** Whether to handle ANSI escape sequences. @default false */
    handleAnsi?: boolean;

    /** Whether to handle emoji sequences. @default false */
    handleEmoji?: boolean;

    /** A list of known acronyms to preserve casing for. */
    knownAcronyms?: ReadonlyArray<string>;

    /** Whether to normalize case. @default false */
    normalize?: boolean;

    /** List of additional separators to split on. */
    separators?: ReadonlyArray<string> | RegExp;

    /** Whether to strip ANSI escape sequences. @default false */
    stripAnsi?: boolean;

    /** Whether to strip emoji sequences. @default false */
    stripEmoji?: boolean;
}
```

***

## CaseOptions [#caseoptions]

Common options shared by all case conversion functions.

```typescript
interface CaseOptions extends LocaleOptions {
    /** Uses a shared LRU cache with a fixed size. @default false */
    cache?: boolean;

    /** A custom cache store for this specific case function. */
    cacheStore?: LRUCache<string, string>;

    /** Whether to handle ANSI escape sequences. @default false */
    handleAnsi?: boolean;

    /** Whether to handle emoji sequences. @default false */
    handleEmoji?: boolean;

    /** A list of known acronyms to preserve casing for. */
    knownAcronyms?: ReadonlyArray<string>;

    /** Whether to normalize case. */
    normalize?: boolean;

    /** Whether to strip ANSI escape sequences. @default false */
    stripAnsi?: boolean;

    /** Whether to strip emoji sequences. @default false */
    stripEmoji?: boolean;
}
```

### LocaleOptions [#localeoptions]

```typescript
interface LocaleOptions {
    /** The locale to use for case conversion (e.g. 'en', 'de', 'tr', 'ja'). */
    locale?: NodeLocale;
}
```

The `NodeLocale` type covers standard locale codes including `'en'`, `'de'`, `'fr'`, `'ja'`, `'ko'`, `'zh'`, `'tr'`, `'el'`, `'ru'`, `'ar'`, `'he'`, and many more.

***

## Notes [#notes]

* All case conversion functions return `""` when the input is `undefined` or not a string.
* Caching uses an internal LRU cache with a default capacity of 1000 entries. Provide your own `cacheStore` to control cache size per function.
* Acronym handling via `knownAcronyms` preserves the original casing of known acronyms during splitting. Acronyms are matched longest-first.
* Locale support enables script-aware splitting for CJK, Cyrillic, Greek, Arabic, Hebrew, Indic, and other scripts.


# String Similarity API (/docs/packages/string/api/similarity)



# String Similarity API [#string-similarity-api]

Detailed API reference for Levenshtein distance, closest string matching, similarity comparison, and sorting functions.

## distance [#distance]

Calculates the Levenshtein distance between two strings -- the minimum number of single-character edits (insertions, deletions, substitutions) required to change one string into the other.

This is a re-export from the `fastest-levenshtein` package for optimal performance.

```typescript
function distance(a: string, b: string): number;
```

**Import:**

```typescript
import { distance } from "@visulima/string";
```

**Parameters:**

| Parameter | Type     | Description        |
| --------- | -------- | ------------------ |
| `a`       | `string` | The first string.  |
| `b`       | `string` | The second string. |

**Returns:** `number` -- The edit distance between the two strings.

**Examples:**

```typescript
distance("hello", "hello"); // 0
distance("hello", "hallo"); // 1
distance("kitten", "sitting"); // 3
distance("", "hello"); // 5
```

***

## closest [#closest]

Finds the closest matching string from an array using Levenshtein distance.

This is a re-export from the `fastest-levenshtein` package.

```typescript
function closest(target: string, candidates: ReadonlyArray<string>): string;
```

**Import:**

```typescript
import { closest } from "@visulima/string";
```

**Parameters:**

| Parameter    | Type                    | Description                         |
| ------------ | ----------------------- | ----------------------------------- |
| `target`     | `string`                | The target string to match against. |
| `candidates` | `ReadonlyArray<string>` | Array of candidate strings.         |

**Returns:** `string` -- The closest matching string from the candidates array.

**Examples:**

```typescript
closest("aple", ["apple", "banana"]); // 'apple'
closest("ornge", ["apple", "orange"]); // 'orange'
```

***

## closestN [#closestn]

Finds the N closest matches from an array using Levenshtein distance.

```typescript
function closestN(target: string, candidates: ReadonlyArray<string>, n: number): (string | undefined)[];
```

**Import:**

```typescript
import { closestN } from "@visulima/string";
```

**Parameters:**

| Parameter    | Type                    | Description                          |
| ------------ | ----------------------- | ------------------------------------ |
| `target`     | `string`                | The target string to match against.  |
| `candidates` | `ReadonlyArray<string>` | Array of candidate strings.          |
| `n`          | `number`                | Number of closest matches to return. |

**Returns:** `(string | undefined)[]` -- Array of the N closest matches, sorted by distance. Entries may be `undefined` if `n` is larger than the candidates array.

**Examples:**

```typescript
const options = ["apple", "apricot", "application", "apply"];

closestN("app", options, 2);
// ['apple', 'apply']

closestN("appl", options, 3);
// ['apple', 'apply', 'application']
```

***

## closestString [#closeststring]

Finds the most similar string from an array of strings. Unlike `closest`, this function supports case-insensitive matching and custom comparison functions.

```typescript
function closestString(givenWord: string, possibleWords: ReadonlyArray<string>, options?: ClosestStringOptions): string | undefined;
```

**Import:**

```typescript
import { closestString } from "@visulima/string/closest-string";
```

**Parameters:**

| Parameter       | Type                    | Description                                                                       |
| --------------- | ----------------------- | --------------------------------------------------------------------------------- |
| `givenWord`     | `string`                | The string to measure distance against.                                           |
| `possibleWords` | `ReadonlyArray<string>` | The string array to pick the closest string from. Must contain at least one word. |
| `options`       | `ClosestStringOptions`  | Optional configuration.                                                           |

**Returns:** `string | undefined` -- The closest string from `possibleWords`.

**Throws:** `TypeError` if `possibleWords` is an empty array.

**Examples:**

```typescript
const words = ["length", "size", "blah", "help"];

closestString("hep", words);
// 'help'

// Case-insensitive (default)
closestString("HELP", words);
// 'help'

// Case-sensitive
closestString("HELP", words, { caseSensitive: true });
// result varies based on distance

// Custom comparison function
closestString("hep", words, {
    compareFn: (a, b) => customDistance(a, b),
});
```

### ClosestStringOptions [#closeststringoptions]

```typescript
interface ClosestStringOptions {
    /**
     * Whether the distance should include case.
     * When false (default), both strings are lowercased before comparison.
     * @default false
     */
    caseSensitive?: boolean;

    /**
     * A custom comparison function to use for comparing strings.
     * Must return a numeric distance (lower = more similar).
     * @default levenshteinDistance
     */
    compareFn?: (a: string, b: string) => number;
}
```

***

## compareSimilarity [#comparesimilarity]

Takes a string and generates a comparator function to determine which of two strings is more similar to the given one. The returned function is designed to be used with `Array.prototype.sort()` or `Array.prototype.toSorted()`.

```typescript
function compareSimilarity(givenWord: string, options?: CompareSimilarityOptions): (a: string, b: string) => number;
```

**Import:**

```typescript
import { compareSimilarity } from "@visulima/string/compare-similarity";
```

**Parameters:**

| Parameter   | Type                       | Description                             |
| ----------- | -------------------------- | --------------------------------------- |
| `givenWord` | `string`                   | The string to measure distance against. |
| `options`   | `CompareSimilarityOptions` | Optional configuration.                 |

**Returns:** `(a: string, b: string) => number` -- A comparator function that returns:

* A negative number if `a` is more similar to `givenWord` than `b`
* A positive number if `b` is more similar
* `0` if they are equally similar

**Examples:**

```typescript
const words = ["hi", "hello", "help"];
const sortedWords = words.toSorted(compareSimilarity("hep"));
// ['help', 'hi', 'hello']

// Case-sensitive
const sorted = words.toSorted(
    compareSimilarity("HEP", {
        caseSensitive: true,
    }),
);
```

### CompareSimilarityOptions [#comparesimilarityoptions]

```typescript
interface CompareSimilarityOptions {
    /**
     * Whether the distance should include case.
     * @default false
     */
    caseSensitive?: boolean;

    /**
     * A custom comparison function to use for comparing strings.
     * @default levenshteinDistance
     */
    compareFn?: (a: string, b: string) => number;
}
```

***

## wordSimilaritySort [#wordsimilaritysort]

Sorts a string array by similarity to a given string. Returns a new sorted copy -- the original array is not mutated.

```typescript
function wordSimilaritySort(givenWord: string, possibleWords: ReadonlyArray<string>, options?: WordSimilaritySortOptions): string[];
```

**Import:**

```typescript
import { wordSimilaritySort } from "@visulima/string/word-similarity-sort";
```

**Parameters:**

| Parameter       | Type                        | Description                                          |
| --------------- | --------------------------- | ---------------------------------------------------- |
| `givenWord`     | `string`                    | The string to measure distance against.              |
| `possibleWords` | `ReadonlyArray<string>`     | The string array to sort. This array is not mutated. |
| `options`       | `WordSimilaritySortOptions` | Optional configuration.                              |

**Returns:** `string[]` -- A sorted copy of `possibleWords`, with the most similar words first.

**Examples:**

```typescript
const words = ["length", "size", "blah", "help"];

wordSimilaritySort("hep", words);
// ['help', 'size', 'blah', 'length']

// Case-sensitive
wordSimilaritySort("hep", ["Size", "blah", "HELP", "length"], {
    caseSensitive: true,
});
// ['Size', 'blah', 'HELP', 'length']
```

**Tie-breaking:** When two words have the same distance, they are sorted alphabetically by their original value using `localeCompare`.

### WordSimilaritySortOptions [#wordsimilaritysortoptions]

```typescript
interface WordSimilaritySortOptions {
    /**
     * Whether the comparison should be case-sensitive.
     * @default false
     */
    caseSensitive?: boolean;

    /**
     * A custom comparison function for distance calculation.
     * @default levenshteinDistance
     */
    compareFunction?: (a: string, b: string) => number;
}
```

***

## Notes [#notes]

* All similarity functions use Levenshtein distance by default, but accept a custom `compareFn`/`compareFunction` to use alternative distance algorithms.
* Case-insensitive mode (the default for `closestString`, `compareSimilarity`, and `wordSimilaritySort`) lowercases both strings before comparison but returns the original-cased string from the candidates.
* The `distance` and `closest` functions are re-exports from `fastest-levenshtein`, which uses an optimized implementation for best performance.
* `closestN` internally tracks the top N candidates in a single pass over the array, so it is more efficient than sorting the entire array when N is small.


# Slugification API (/docs/packages/string/api/slugify)



# Slugification API [#slugification-api]

Detailed API reference for the `slugify` and `transliterate` functions.

## slugify [#slugify]

Converts a string into a URL-friendly slug. It transliterates non-ASCII characters, optionally converts case, removes disallowed characters (replacing with separator), and collapses separators.

```typescript
function slugify(input: string, options?: SlugifyOptions): string;
```

**Import:**

```typescript
import slugify from "@visulima/string/slugify";
// or from the barrel export:
// import { slugify } from "@visulima/string";
```

**Parameters:**

| Parameter | Type             | Description                        |
| --------- | ---------------- | ---------------------------------- |
| `input`   | `string`         | The string to convert into a slug. |
| `options` | `SlugifyOptions` | Optional configuration options.    |

**Returns:** `string` -- The generated URL-friendly slug.

**Examples:**

```typescript
slugify("Hello World!"); // 'hello-world'
slugify("Creme Brulee"); // 'creme-brulee'
slugify("foo & bar * baz"); // 'foo-bar-baz'

// Chinese support
slugify("你好 World!"); // 'ni-hao-world'

// Custom separator
slugify("foo bar baz", { separator: "_" }); // 'foo_bar_baz'

// Uppercase
slugify("foo bar", { lowercase: false, uppercase: true }); // 'FOO-BAR'

// Preserve case
slugify("Foo Bar", { lowercase: false }); // 'Foo-Bar'
```

**Edge cases:**

* If both `lowercase` and `uppercase` are `true`, a console warning is emitted and the function defaults to lowercase.
* Leading and trailing separator characters are always trimmed from the result.
* Consecutive separators are collapsed into a single separator.

***

## SlugifyOptions [#slugifyoptions]

```typescript
interface SlugifyOptions extends OptionsTransliterate {
    /**
     * Allowed characters. Other characters will be converted to `separator`.
     * Uses regex character class syntax (e.g. "a-zA-Z0-9").
     * @default "a-zA-Z0-9-_.~"
     */
    allowedChars?: string;

    /**
     * Fix Chinese spacing passed to transliterate.
     * If you don't need to transliterate Chinese characters, set to false to improve performance.
     * @default true
     */
    fixChineseSpacing?: boolean;

    /**
     * Characters/strings to ignore during transliteration.
     * @default []
     */
    ignore?: string[];

    /**
     * Whether the result should be converted into lowercase.
     * Cannot be true if `uppercase` is true.
     * @default true
     */
    lowercase?: boolean;

    /**
     * Search/replace pairs applied after transliteration.
     * Can be an object `{ search: replacement }` or an array of `[search, replacement]` tuples.
     * Searches can be strings or RegExp.
     * @default []
     */
    replaceAfter?: OptionReplaceCombined;

    /**
     * Search/replace pairs applied before transliteration.
     * @default []
     */
    replaceBefore?: OptionReplaceCombined;

    /**
     * Custom separator string used to join words in the slug.
     * @default "-"
     */
    separator?: string;

    /**
     * Whether to transliterate the input string.
     * @default true
     */
    transliterate?: boolean;

    /**
     * Trim leading/trailing whitespace before processing.
     * @default false
     */
    trim?: boolean;

    /**
     * Character to use for unknown characters.
     * @default ""
     */
    unknown?: string;

    /**
     * Whether the result should be converted into uppercase.
     * Cannot be true if `lowercase` is true.
     * @default false
     */
    uppercase?: boolean;
}
```

***

## transliterate [#transliterate]

Transliterates Unicode characters to ASCII equivalents using a comprehensive character map. Supports Chinese Pinyin, Thai romanization, Cyrillic, Greek, Arabic, Hebrew, Japanese, Korean, and many other scripts.

```typescript
function transliterate(source: string, options?: OptionsTransliterate): string;
```

**Import:**

```typescript
import { transliterate } from "@visulima/string";
```

**Parameters:**

| Parameter | Type                   | Description                  |
| --------- | ---------------------- | ---------------------------- |
| `source`  | `string`               | The string to transliterate. |
| `options` | `OptionsTransliterate` | Optional configuration.      |

**Returns:** `string` -- The transliterated ASCII string.

**Examples:**

```typescript
// European
transliterate("Creme brulee"); // 'Creme brulee'
transliterate("Dusseldorf"); // 'Dusseldorf'

// Cyrillic
transliterate("Москва"); // 'Moskva'

// Chinese (with spacing)
transliterate("你好世界"); // 'Ni Hao Shi Jie'

// Chinese (without spacing)
transliterate("你好世界", { fixChineseSpacing: false });
// 'NiHaoShiJie'

// Custom replacements
transliterate("Replace C++ before map", {
    replaceBefore: { "C++": "cpp" },
}); // 'Replace cpp before map'

// Ignore segments
transliterate("Don't change THIS", {
    ignore: ["THIS"],
}); // "Dont change THIS"

// Unknown characters
transliterate("a🚀b", { unknown: "[?]" }); // 'a[?]b'
```

***

## OptionsTransliterate [#optionstransliterate]

```typescript
interface OptionsTransliterate {
    /**
     * Add space between Chinese Pinyin syllables.
     * @default true
     */
    fixChineseSpacing?: boolean;

    /**
     * Characters/strings to ignore during transliteration.
     * These are preserved as-is in the output.
     * @default []
     */
    ignore?: string[];

    /**
     * Search/replace pairs applied after the character map.
     * Can be an object or array of `[RegExp | string, string]` tuples.
     * @default []
     */
    replaceAfter?: OptionReplaceCombined;

    /**
     * Search/replace pairs applied before the character map.
     * @default []
     */
    replaceBefore?: OptionReplaceCombined;

    /**
     * Trim leading/trailing whitespace from the result.
     * @default false
     */
    trim?: boolean;

    /**
     * Character to use for unknown (untransliterable) characters.
     * @default ""
     */
    unknown?: string;
}
```

***

## OptionReplaceCombined [#optionreplacecombined]

The replacement configuration can be either an object or an array:

```typescript
/** Object form: keys are search strings, values are replacements */
type OptionReplaceObject = Record<string, string>;

/** Array form: tuples of [search, replacement] where search can be a RegExp */
type OptionReplaceArray = [RegExp | string, string | undefined][];

/** Combined type */
type OptionReplaceCombined = OptionReplaceArray | OptionReplaceObject;
```

**Object form:**

```typescript
slugify("C# and C++", {
    replaceBefore: {
        "C#": "csharp",
        "C++": "cpp",
    },
}); // 'csharp-and-cpp'
```

**Array form (with RegExp):**

```typescript
transliterate("test123", {
    replaceAfter: [[/\d+/g, "NUM"]],
}); // 'testNUM'
```

***

## Notes [#notes]

* The `slugify` function internally calls `transliterate` when the `transliterate` option is `true` (the default).
* The character map covers thousands of Unicode code points across many writing systems.
* When `transliterate` is set to `false`, the input is normalized with NFC but non-ASCII characters that are not in `allowedChars` will be removed.
* The `fixChineseSpacing` option inserts spaces between Chinese Pinyin syllables for more readable output. Set to `false` for compact slugs.


# Testing Utilities API (/docs/packages/string/api/testing)



# Testing Utilities API [#testing-utilities-api]

Detailed API reference for the ANSI string testing and comparison utilities.

## toEqualAnsi [#toequalansi]

A Vitest custom matcher for comparing ANSI-encoded strings. Provides detailed error output when strings do not match, showing both the visible content and the underlying escape codes.

```typescript
function toEqualAnsi(actual: string, expected: string): ExpectationResult;
```

**Import:**

```typescript
import { toEqualAnsi } from "@visulima/string/test/vitest";
```

**Parameters:**

| Parameter  | Type     | Description                      |
| ---------- | -------- | -------------------------------- |
| `actual`   | `string` | The actual ANSI string received. |
| `expected` | `string` | The expected ANSI string.        |

**Returns:** `ExpectationResult` -- An object with `pass` (boolean) and `message` (function returning a string).

**Setup:**

```typescript
import { expect } from "vitest";
import { toEqualAnsi } from "@visulima/string/test/vitest";

expect.extend({ toEqualAnsi });
```

**Usage in tests:**

```typescript
it("should match colored output", () => {
    const actual = "\x1b[31mError\x1b[39m";
    const expected = "\x1b[31mError\x1b[39m";

    expect(actual).toEqualAnsi(expected);
});
```

**Error output:** When the assertion fails, the message includes:

* Visible content of both strings (with ANSI codes stripped)
* Escape codes shown as visible characters
* JSON-encoded representation
* Visual width of each string
* Whether the visible content is identical (indicating only escape codes differ)

### ExpectationResult [#expectationresult]

```typescript
interface ExpectationResult {
    /** Whether the assertion passed. */
    pass: boolean;

    /** Function returning the error message for display. */
    message: () => string;

    /** The actual value (optional, for diff display). */
    actual?: unknown;

    /** The expected value (optional, for diff display). */
    expected?: unknown;
}
```

### CustomMatchers [#custommatchers]

TypeScript interface for extending Vitest's `expect`:

```typescript
interface CustomMatchers {
    toEqualAnsi: (expected: string) => ExpectationResult;
}
```

***

## formatAnsiString [#formatansistring]

Formats an ANSI string into multiple representations for debugging and test output.

```typescript
function formatAnsiString(ansiString: string): {
    ansi: string;
    json: string;
    lengthDifference: number;
    stripped: string;
    visible: string;
};
```

**Import:**

```typescript
import { formatAnsiString } from "@visulima/string/test/utils";
```

**Parameters:**

| Parameter    | Type     | Description                |
| ------------ | -------- | -------------------------- |
| `ansiString` | `string` | The ANSI string to format. |

**Returns:** An object with the following properties:

| Property           | Type     | Description                                                                                                          |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `ansi`             | `string` | The original ANSI string, unchanged.                                                                                 |
| `stripped`         | `string` | The string with all ANSI/VT control characters removed (using `node:util.stripVTControlCharacters`).                 |
| `visible`          | `string` | The string with escape characters replaced by the literal text `\u001B` so they are visible.                         |
| `json`             | `string` | The `JSON.stringify` output, showing all escape codes as `\u001b` sequences.                                         |
| `lengthDifference` | `number` | The difference in `.length` between the original and stripped string, indicating how many characters are ANSI codes. |

**Examples:**

```typescript
const colored = "\x1b[31mError\x1b[39m";
const formatted = formatAnsiString(colored);

formatted.ansi; // '\x1b[31mError\x1b[39m'
formatted.stripped; // 'Error'
formatted.visible; // '\\u001B[31mError\\u001B[39m'
formatted.json; // '"\\u001b[31mError\\u001b[39m"'
formatted.lengthDifference; // 9
```

***

## expectAnsiStrings [#expectansistrings]

Creates a detailed comparison result for two ANSI strings. This is the underlying implementation used by `toEqualAnsi`.

```typescript
function expectAnsiStrings(actual: string, expected: string): ExpectationResult;
```

**Import:**

```typescript
import { expectAnsiStrings } from "@visulima/string/test/utils";
```

**Parameters:**

| Parameter  | Type     | Description               |
| ---------- | -------- | ------------------------- |
| `actual`   | `string` | The actual ANSI string.   |
| `expected` | `string` | The expected ANSI string. |

**Returns:** `ExpectationResult` -- The same result type as `toEqualAnsi`.

**Examples:**

```typescript
const result = expectAnsiStrings("\x1b[31mError\x1b[39m", "\x1b[32mError\x1b[39m");

result.pass; // false (different color codes)
result.message(); // Detailed diff message
```

***

## compareAnsiStrings [#compareansistrings]

Performs a detailed comparison between two ANSI strings, returning structured data about the differences.

```typescript
function compareAnsiStrings(
    actual: string,
    expected: string,
): {
    actual: ReturnType<typeof formatAnsiString>;
    ansiEqual: boolean;
    expected: ReturnType<typeof formatAnsiString>;
    strippedEqual: boolean;
    summary: {
        actualLength: number;
        actualStrippedLength: number;
        ansiEqual: boolean;
        expectedLength: number;
        expectedStrippedLength: number;
        strippedEqual: boolean;
    };
};
```

**Import:**

```typescript
import { compareAnsiStrings } from "@visulima/string/test/utils";
```

**Parameters:**

| Parameter  | Type     | Description               |
| ---------- | -------- | ------------------------- |
| `actual`   | `string` | The actual ANSI string.   |
| `expected` | `string` | The expected ANSI string. |

**Returns:** An object with:

| Property        | Type      | Description                                                     |
| --------------- | --------- | --------------------------------------------------------------- |
| `actual`        | `object`  | The `formatAnsiString` result for the actual string.            |
| `expected`      | `object`  | The `formatAnsiString` result for the expected string.          |
| `ansiEqual`     | `boolean` | Whether the full strings (including ANSI codes) are identical.  |
| `strippedEqual` | `boolean` | Whether the visible content (ANSI codes stripped) is identical. |
| `summary`       | `object`  | Aggregate comparison data including lengths and equality flags. |

**Examples:**

```typescript
const result = compareAnsiStrings("\x1b[31mError\x1b[39m", "\x1b[32mError\x1b[39m");

result.ansiEqual; // false
result.strippedEqual; // true (both say "Error")
result.summary.actualLength; // 14
result.summary.actualStrippedLength; // 5
result.summary.expectedLength; // 14
result.summary.expectedStrippedLength; // 5
```

**Use case:** Useful when you need programmatic access to the comparison data rather than just a pass/fail assertion:

```typescript
it("should use correct colors", () => {
    const output = generateOutput();
    const expected = generateExpected();

    const comparison = compareAnsiStrings(output, expected);

    if (!comparison.ansiEqual && comparison.strippedEqual) {
        console.log("Content matches but ANSI codes differ");
        console.log("Actual JSON:", comparison.actual.json);
        console.log("Expected JSON:", comparison.expected.json);
    }

    expect(comparison.ansiEqual).toBe(true);
});
```

***

## Notes [#notes]

* All ANSI stripping uses Node.js built-in `stripVTControlCharacters` from `node:util`.
* The `toEqualAnsi` matcher uses `getStringWidth` from `@visulima/string` to calculate the visual width shown in error messages.
* These utilities work with any ANSI escape codes, including SGR (colors, bold, underline), OSC (hyperlinks), and other VT control sequences.
* The `test/vitest` export provides the matcher function directly; the `test/utils` export provides the lower-level utilities for custom testing setups.


# String Width API (/docs/packages/string/api/width)



# String Width API [#string-width-api]

Detailed API reference for visual string width calculation and truncation functions.

## getStringWidth [#getstringwidth]

Calculate the visual width of a string, taking into account Unicode characters, emojis, ANSI escape codes, combining marks, and East Asian width properties.

```typescript
function getStringWidth(input: string, options?: StringWidthOptions): number;
```

**Import:**

```typescript
import { getStringWidth } from "@visulima/string/get-string-width";
```

**Parameters:**

| Parameter | Type                 | Description                                   |
| --------- | -------------------- | --------------------------------------------- |
| `input`   | `string`             | The string to calculate the width for.        |
| `options` | `StringWidthOptions` | Optional configuration for width calculation. |

**Returns:** `number` -- The calculated visual width of the string.

**Examples:**

```typescript
// Basic ASCII
getStringWidth("hello"); // 5

// CJK characters (width 2 each)
getStringWidth("你好"); // 4
getStringWidth("あいう"); // 6

// Emojis (width 2 each)
getStringWidth("👋"); // 2
getStringWidth("👨‍👩‍👧‍👦"); // 2 (ZWJ family emoji)

// ANSI escape codes (ignored by default)
getStringWidth("\x1b[31mRed\x1b[39m"); // 3

// Combining characters
getStringWidth("e\u0301"); // 1 (e with combining acute accent)
getStringWidth("\u0e01\u0e31"); // 1 (Thai character with vowel mark)

// Mixed content
getStringWidth("Hello 世界"); // 9

// Custom widths
getStringWidth("hello", { regularWidth: 2 }); // 10
getStringWidth("👋👋", { emojiWidth: 1 }); // 2
```

**How it works:** Internally, `getStringWidth` delegates to `getStringTruncatedWidth` with `limit: Infinity` and no ellipsis, returning only the `width` field from the result.

***

## StringWidthOptions [#stringwidthoptions]

Configuration options for string width calculation. This type excludes truncation-related options.

```typescript
type StringWidthOptions = Omit<StringTruncatedWidthOptions, "ellipsis" | "ellipsisWidth" | "limit">;
```

Effective properties:

| Property               | Type      | Default | Description                                                                                                                        |
| ---------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `ambiguousIsNarrow`    | `boolean` | `false` | Treat [ambiguous width characters](https://www.unicode.org/reports/tr11/#Ambiguous) as narrow (width 1) instead of wide (width 2). |
| `ansiWidth`            | `number`  | `0`     | Width assigned to ANSI escape sequences.                                                                                           |
| `controlWidth`         | `number`  | `0`     | Width assigned to control characters.                                                                                              |
| `countAnsiEscapeCodes` | `boolean` | `false` | Whether to count ANSI escape code characters in width calculation.                                                                 |
| `emojiWidth`           | `number`  | `2`     | Width assigned to emoji characters.                                                                                                |
| `fullWidth`            | `number`  | `2`     | Width assigned to full-width characters.                                                                                           |
| `halfWidth`            | `number`  | `1`     | Width assigned to half-width characters.                                                                                           |
| `regularWidth`         | `number`  | `1`     | Width assigned to regular ASCII characters.                                                                                        |
| `tabWidth`             | `number`  | `8`     | Width assigned to tab characters.                                                                                                  |
| `wideWidth`            | `number`  | `2`     | Width assigned to wide characters (CJK).                                                                                           |

***

## getStringTruncatedWidth [#getstringtruncatedwidth]

Calculate the visual width of a string with optional truncation support. Handles various Unicode character types including combining marks, emoji sequences, ANSI escape codes, and East Asian characters.

```typescript
function getStringTruncatedWidth(input: string, options?: StringTruncatedWidthOptions): StringTruncatedWidthResult;
```

**Import:**

```typescript
import { getStringTruncatedWidth } from "@visulima/string/get-string-truncated-width";
```

**Parameters:**

| Parameter | Type                          | Description                                                  |
| --------- | ----------------------------- | ------------------------------------------------------------ |
| `input`   | `string`                      | The string to calculate the width for.                       |
| `options` | `StringTruncatedWidthOptions` | Optional configuration for width calculation and truncation. |

**Returns:** `StringTruncatedWidthResult` -- An object containing width, truncation status, and index information.

**Examples:**

```typescript
// Basic width calculation
getStringTruncatedWidth("hello");
// { width: 5, truncated: false, ellipsed: false, index: 5 }

// With truncation limit
getStringTruncatedWidth("hello world", { limit: 8 });
// { width: 8, truncated: true, ellipsed: false, index: 8 }

// With truncation and ellipsis
getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "...",
});
// { width: 8, truncated: true, ellipsed: true, index: 5 }

// CJK with truncation
getStringTruncatedWidth("あいうえお", {
    limit: 6,
    ellipsis: "...",
});
// { width: 6, truncated: true, ellipsed: true, index: ... }

// Empty string
getStringTruncatedWidth("");
// { width: 0, truncated: false, ellipsed: false, index: 0 }
```

***

## StringTruncatedWidthOptions [#stringtruncatedwidthoptions]

Full configuration options for width calculation and truncation.

```typescript
interface StringTruncatedWidthOptions {
    /** Treat ambiguous width characters as narrow. @default false */
    ambiguousIsNarrow?: boolean;

    /** Width of ANSI escape sequences. @default 0 */
    ansiWidth?: number;

    /** Width of control characters. @default 0 */
    controlWidth?: number;

    /** Whether to count ANSI escape codes in width. @default false */
    countAnsiEscapeCodes?: boolean;

    /** Text appended to the string when it is truncated. @default '' */
    ellipsis?: string;

    /** Width of the ellipsis string. Auto-calculated if not provided. */
    ellipsisWidth?: number;

    /** Width of emoji characters. @default 2 */
    emojiWidth?: number;

    /** Width of full-width characters. @default 2 */
    fullWidth?: number;

    /** Width of half-width characters. @default 1 */
    halfWidth?: number;

    /** Maximum width limit for the string. @default Infinity */
    limit?: number;

    /** Width of regular characters. @default 1 */
    regularWidth?: number;

    /** Width of tab characters. @default 8 */
    tabWidth?: number;

    /** Width of wide characters. @default 2 */
    wideWidth?: number;
}
```

***

## StringTruncatedWidthResult [#stringtruncatedwidthresult]

Result object returned by `getStringTruncatedWidth`.

```typescript
interface StringTruncatedWidthResult {
    /** The calculated visual width of the string. */
    width: number;

    /** Whether the string was truncated. */
    truncated: boolean;

    /** Whether an ellipsis was added. */
    ellipsed: boolean;

    /** The index at which truncation occurred, or the full string length if not truncated. */
    index: number;
}
```

**Interpreting the result:**

* When `truncated` is `false`: `width` is the full visual width and `index` equals the string length.
* When `truncated` is `true` and `ellipsed` is `true`: `width` equals the `limit` value, and `index` is the position in the original string where truncation occurred (before the ellipsis).
* When `truncated` is `true` and `ellipsed` is `false`: the string exceeded the limit but no ellipsis was configured.

***

## Character Width Rules [#character-width-rules]

The width calculation uses these rules in order of priority:

1. **ANSI escape sequences**: Width `0` by default (or character count if `countAnsiEscapeCodes` is `true`).
2. **OSC 8 hyperlinks**: Only the display text within the hyperlink contributes to width.
3. **Zero-width characters**: Zero-width space (U+200B), zero-width non-joiner (U+200C), zero-width joiner (U+200D), and word joiner (U+2060) have width `0`.
4. **Tab characters**: Width of `tabWidth` (default 8).
5. **Latin characters** (U+0020-U+007E, U+00A0-U+00FF): Width of `regularWidth` (default 1).
6. **Control characters**: Width of `controlWidth` (default 0).
7. **Emoji sequences**: Width of `emojiWidth` (default 2), including complex ZWJ sequences.
8. **Combining characters**: Width `0` (combining diacritical marks, variation selectors, Indic vowel signs, etc.).
9. **CJK/wide characters**: Width of `wideWidth` (default 2). Includes Hangul, Hiragana, Katakana, CJK ideographs, and full-width forms.
10. **Ambiguous characters**: Width of `wideWidth` or `regularWidth` depending on the `ambiguousIsNarrow` option.
11. **All other characters**: Width of `regularWidth` (default 1).

***

## Notes [#notes]

* For strings longer than 10,000 characters, the implementation uses a character width cache for improved performance.
* The Box Drawing block (U+2500-U+257F) is treated as width 1, not as wide characters.
* The horizontal ellipsis (U+2026) is treated as width 1.
* When `ellipsisWidth` is not provided but `ellipsis` is, the ellipsis width is auto-calculated by recursively calling `getStringTruncatedWidth` on the ellipsis string.


# API Reference (/docs/packages/string/api)



# API Reference [#api-reference]

Complete reference for all functions, types, and utilities provided by @visulima/string.

## Case Conversion [#case-conversion]

### camelCase [#camelcase]

Converts string to camelCase.

```typescript
function camelCase(input: string, options?: CaseOptions): string;
```

**Parameters:**

* `input`: String to convert
* `options`: Optional configuration

**Returns:** String in camelCase format

**Example:**

```typescript
camelCase("hello-world"); // 'helloWorld'
```

***

### pascalCase [#pascalcase]

Converts string to PascalCase.

```typescript
function pascalCase(input: string, options?: CaseOptions): string;
```

***

### snakeCase [#snakecase]

Converts string to snake\_case.

```typescript
function snakeCase(input: string, options?: CaseOptions): string;
```

***

### kebabCase [#kebabcase]

Converts string to kebab-case.

```typescript
function kebabCase(input: string, options?: KebabCaseOptions): string;
```

***

### constantCase [#constantcase]

Converts string to CONSTANT\_CASE.

```typescript
function constantCase(input: string, options?: CaseOptions): string;
```

***

### dotCase [#dotcase]

Converts string to dot.case.

```typescript
function dotCase(input: string, options?: CaseOptions): string;
```

***

### pathCase [#pathcase]

Converts string to path/case.

```typescript
function pathCase(input: string, options?: CaseOptions): string;
```

***

### titleCase [#titlecase]

Converts string to Title Case.

```typescript
function titleCase(input: string, options?: CaseOptions): string;
```

***

### sentenceCase [#sentencecase]

Converts string to Sentence case.

```typescript
function sentenceCase(input: string, options?: CaseOptions): string;
```

***

### splitByCase [#splitbycase]

Splits string by case transitions.

```typescript
function splitByCase(input: string, options?: SplitOptions): string[];
```

**Parameters:**

* `input`: String to split
* `options`: Optional configuration

**Returns:** Array of string segments

**Example:**

```typescript
splitByCase("camelCase"); // ['camel', 'Case']
```

***

### flipCase [#flipcase]

Inverts case of each character in a string.

```typescript
function flipCase(input: string, options?: FlipOptions): string;
```

**Parameters:**

* `input`: String to flip case
* `options`: Optional configuration (same as CaseOptions except handleEmoji)

**Returns:** String with inverted case

**Example:**

```typescript
flipCase("Hello World"); // 'hELLO wORLD'
flipCase("XMLHttpRequest"); // 'xmlhTTPrEQUEST'
```

***

### identifyCase [#identifycase]

Identifies the case style of a string.

```typescript
function identifyCase(input: string): IdentifyCase;
```

**Parameters:**

* `input`: String to identify

**Returns:** Case style identifier: `'camel'`, `'pascal'`, `'snake'`, `'kebab'`, `'upper_snake'`, `'lower'`, `'upper'`, `'title'`, `'sentence'`, `'mixed'`, or `'unknown'`

**Example:**

```typescript
identifyCase("helloWorld"); // 'camel'
identifyCase("HELLO_WORLD"); // 'upper_snake'
identifyCase("Hello World"); // 'title'
```

***

### lowerFirst [#lowerfirst]

Converts first character to lowercase.

```typescript
function lowerFirst(input: string): string;
```

**Example:**

```typescript
lowerFirst("Hello"); // 'hello'
lowerFirst("HELLO"); // 'hELLO'
```

***

### upperFirst [#upperfirst]

Converts first character to uppercase.

```typescript
function upperFirst(input: string): string;
```

**Example:**

```typescript
upperFirst("hello"); // 'Hello'
upperFirst("hello world"); // 'Hello world'
```

***

### noCase [#nocase]

Removes all case styling, converting to lowercase with spaces.

```typescript
function noCase(input: string, options?: CaseOptions): string;
```

**Example:**

```typescript
noCase("camelCase"); // 'camel case'
noCase("PascalCase"); // 'pascal case'
noCase("snake_case"); // 'snake case'
```

***

### flatCase [#flatcase]

Converts string to flatcase (no separators, all lowercase).

```typescript
function flatCase(input: string, options?: CaseOptions): string;
```

**Example:**

```typescript
flatCase("foo bar"); // 'foobar'
flatCase("foo-bar"); // 'foobar'
```

***

### capitalCase [#capitalcase]

Converts string to Capital Case (each word capitalized).

```typescript
function capitalCase(input: string, options?: CaseOptions): string;
```

**Example:**

```typescript
capitalCase("foo bar"); // 'Foo Bar'
capitalCase("foo-bar"); // 'Foo Bar'
```

***

### trainCase [#traincase]

Converts string to Train-Case (each word capitalized, hyphen-separated).

```typescript
function trainCase(input: string, options?: CaseOptions): string;
```

**Example:**

```typescript
trainCase("foo bar"); // 'Foo-Bar'
trainCase("XMLHttpRequest"); // 'Xml-Http-Request'
```

***

### pascalSnakeCase [#pascalsnakecase]

Converts string to Pascal\_Snake\_Case.

```typescript
function pascalSnakeCase(input: string, options?: CaseOptions): string;
```

**Example:**

```typescript
pascalSnakeCase("foo bar"); // 'Foo_Bar'
pascalSnakeCase("XMLHttpRequest"); // 'Xml_Http_Request'
```

***

## String Manipulation [#string-manipulation]

### truncate [#truncate]

Truncates string to specified length.

```typescript
function truncate(input: string, length: number, options?: TruncateOptions): string;
```

**Parameters:**

* `input`: String to truncate
* `length`: Maximum length
* `options`: Optional configuration

**Returns:** Truncated string

**Example:**

```typescript
truncate("hello world", 8); // 'hello...'
```

***

### wordWrap [#wordwrap]

Wraps text to specified width.

```typescript
function wordWrap(text: string, options?: WordWrapOptions): string;
```

**Parameters:**

* `text`: Text to wrap
* `options`: Optional configuration

**Returns:** Wrapped text

**Example:**

```typescript
wordWrap("Long text...", { width: 40 });
```

***

### alignText [#aligntext]

Aligns text to left, center, or right.

```typescript
function alignText(text: string | string[], options?: AlignTextOptions): string | string[];
```

**Parameters:**

* `text`: Text to align (string or array of strings)
* `options`: Optional configuration

**Returns:** Aligned text in same format as input

**Example:**

```typescript
alignText("Hello", { align: "center" });
```

***

### outdent [#outdent]

Removes leading indentation.

```typescript
function outdent(strings: TemplateStringsArray, ...values: any[]): string;

function outdent(options: OutdentOptions): typeof outdent;

namespace outdent {
    function string(input: string): string;
}
```

**Usage:**

```typescript
// Template literal
outdent`
  Hello
  World
`;

// String input
outdent.string("  Hello\n  World");

// With options
const custom = outdent({ trimLeadingNewline: false });
custom`Hello`;
```

***

### slice [#slice]

Unicode-aware string slicing.

```typescript
function slice(input: string, start: number, end?: number, options?: SliceOptions): string;
```

**Parameters:**

* `input`: String to slice
* `start`: Start index
* `end`: End index (optional)
* `options`: Optional configuration

**Returns:** Sliced string

**Example:**

```typescript
slice("hello world", 0, 5); // 'hello'
```

***

### replaceString [#replacestring]

Advanced string replacement with ignore ranges.

```typescript
function replaceString(source: string, searches: OptionReplaceArray, ignoreRanges?: IntervalArray): string;
```

**Parameters:**

* `source`: Source string
* `searches`: Array of \[search, replace] tuples
* `ignoreRanges`: Optional ranges to ignore

**Returns:** String with replacements applied

**Example:**

```typescript
replaceString("hello", [["h", "H"]], []); // 'Hello'
```

***

### excerpt [#excerpt]

Strips HTML tags and truncates text to a specified limit.

```typescript
function excerpt(html: string, limit: number, options?: ExcerptOptions): string;
```

**Parameters:**

* `html`: HTML string to process
* `limit`: Maximum character limit
* `options`: Optional configuration

**Returns:** Plain text string with HTML removed and truncated

**Example:**

```typescript
excerpt("<p>Hello <strong>world</strong>!</p>", 10);
// 'Hello wor…'

excerpt("<div>Content</div>", 7);
// 'Content'
```

***

### countOccurrences [#countoccurrences]

Counts occurrences of a substring in a string.

```typescript
function countOccurrences(value: string, substring: string): number;
```

**Parameters:**

* `value`: Content to search in
* `substring`: Substring to look for (must be non-empty)

**Returns:** Count of `substring`s in `value`

**Throws:** `TypeError` when substring is not a string or is empty

**Example:**

```typescript
countOccurrences("foo", "o"); // 2
countOccurrences("fo fooo fo", "o"); // 5
countOccurrences("a🤔b🤔c", "🤔"); // 2
```

***

### direction [#direction]

Detects the direction of text: left-to-right, right-to-left, or neutral.

```typescript
function direction(value: string): "rtl" | "ltr" | "neutral";
```

**Parameters:**

* `value`: The string to analyze

**Returns:** The text direction: `'rtl'` for right-to-left, `'ltr'` for left-to-right, or `'neutral'` for neutral

**Example:**

```typescript
direction("english"); // 'ltr'
direction("الجملة"); // 'rtl'
direction("123"); // 'neutral'
direction(""); // 'neutral'
```

***

## String Width [#string-width]

### getStringWidth [#getstringwidth]

Calculates visual width of string.

```typescript
function getStringWidth(input: string, options?: StringWidthOptions): number;
```

**Parameters:**

* `input`: String to measure
* `options`: Optional configuration

**Returns:** Visual width in columns

**Example:**

```typescript
getStringWidth("hello"); // 5
getStringWidth("你好"); // 4
```

***

### getStringTruncatedWidth [#getstringtruncatedwidth]

Calculates width with truncation support.

```typescript
function getStringTruncatedWidth(input: string, options?: StringTruncatedWidthOptions): StringTruncatedWidthResult;
```

**Parameters:**

* `input`: String to measure
* `options`: Optional configuration

**Returns:** Object with width, truncation info, and index

**Example:**

```typescript
getStringTruncatedWidth("hello", { limit: 3 });
// { width: 3, truncated: true, ellipsed: false, index: 3 }
```

***

## Slugification [#slugification]

### slugify [#slugify]

Creates URL-friendly slug.

```typescript
function slugify(input: string, options?: SlugifyOptions): string;
```

**Parameters:**

* `input`: String to slugify
* `options`: Optional configuration

**Returns:** URL-friendly slug

**Example:**

```typescript
slugify("Hello World!"); // 'hello-world'
```

***

### transliterate [#transliterate]

Transliterates Unicode to ASCII.

```typescript
function transliterate(source: string, options?: OptionsTransliterate): string;
```

**Parameters:**

* `source`: String to transliterate
* `options`: Optional configuration

**Returns:** Transliterated string

**Example:**

```typescript
transliterate("Café"); // 'Cafe'
```

***

## String Similarity [#string-similarity]

### distance [#distance]

Calculates Levenshtein distance.

```typescript
function distance(a: string, b: string): number;
```

**Parameters:**

* `a`: First string
* `b`: Second string

**Returns:** Edit distance

**Example:**

```typescript
distance("hello", "hallo"); // 1
```

***

### closest [#closest]

Finds closest matching string.

```typescript
function closest(target: string, options: string[]): string | null;
```

**Parameters:**

* `target`: Target string
* `options`: Array of candidate strings

**Returns:** Closest match or null

**Example:**

```typescript
closest("aple", ["apple", "banana"]); // 'apple'
```

***

### closestN [#closestn]

Finds N closest matches.

```typescript
function closestN(target: string, options: string[], count: number): string[];
```

**Parameters:**

* `target`: Target string
* `options`: Array of candidate strings
* `count`: Number of matches to return

**Returns:** Array of closest matches

***

### closestString [#closeststring]

Finds closest string with options.

```typescript
function closestString(target: string, options: string[], config?: ClosestStringOptions): ClosestStringResult | null;
```

**Returns:** Object with value, distance, and similarity

***

### compareSimilarity [#comparesimilarity]

Compares two strings.

```typescript
function compareSimilarity(
    a: string,
    b: string,
    options?: CompareSimilarityOptions,
): {
    distance: number;
    similarity: number;
    equal: boolean;
};
```

***

### wordSimilaritySort [#wordsimilaritysort]

Sorts strings by similarity.

```typescript
function wordSimilaritySort(target: string, words: string[], options?: WordSimilaritySortOptions): string[];
```

***

## Utilities [#utilities]

### escapeRegExp [#escaperegexp]

Escapes special regex characters for safe use in regular expressions.

```typescript
function escapeRegExp(string: string): string;
```

**Parameters:**

* `string`: String to escape

**Returns:** Escaped string safe for use in regex

**Example:**

```typescript
escapeRegExp("hello.world"); // 'hello\\.world'
escapeRegExp("(test)"); // '\\(test\\)'
```

***

### inRange [#inrange]

Checks if a number falls within any of the specified intervals.

```typescript
function inRange(value: number, ranges: IntervalArray): boolean;
```

**Parameters:**

* `value`: Number to check
* `ranges`: Array of \[start, end] intervals

**Returns:** True if number is within any interval

**Example:**

```typescript
inRange(5, [
    [0, 10],
    [20, 30],
]); // true
inRange(15, [
    [0, 10],
    [20, 30],
]); // false
```

***

### hasChinese [#haschinese]

Checks if string contains Chinese characters (Han script).

```typescript
function hasChinese(text: string): boolean;
```

**Parameters:**

* `text`: String to check

**Returns:** True if string contains Chinese characters

**Example:**

```typescript
hasChinese("你好"); // true
hasChinese("hello"); // false
hasChinese("hello 世界"); // true
```

***

### hasPunctuationOrSpace [#haspunctuationorspace]

Checks if string contains punctuation or space characters.

```typescript
function hasPunctuationOrSpace(text: string): boolean;
```

**Parameters:**

* `text`: String to check

**Returns:** True if string contains punctuation or space

**Example:**

```typescript
hasPunctuationOrSpace("hello world"); // true
hasPunctuationOrSpace("hello,world"); // true
hasPunctuationOrSpace("helloworld"); // false
```

***

### findStringOccurrences [#findstringoccurrences]

Finds all occurrences of multiple substrings and returns their positions.

```typescript
function findStringOccurrences(source: string, targets: string[]): IntervalArray;
```

**Parameters:**

* `source`: String to search within
* `targets`: Array of strings to search for

**Returns:** Array of \[start, end] intervals for each occurrence

**Example:**

```typescript
findStringOccurrences("hello world hello", ["hello", "world"]);
// [[0, 4], [6, 10], [12, 16]]

findStringOccurrences("abc def abc", ["abc"]);
// [[0, 2], [8, 10]]
```

***

## Testing [#testing]

### toEqualAnsi [#toequalansi]

Vitest matcher for ANSI strings.

```typescript
function toEqualAnsi(received: string, expected: string): { pass: boolean; message: () => string };
```

**Usage:**

```typescript
expect.extend({ toEqualAnsi });
expect(actual).toEqualAnsi(expected);
```

***

### formatAnsiString [#formatansistring]

Formats ANSI string for display.

```typescript
function formatAnsiString(input: string): {
    ansi: string;
    stripped: string;
    visible: string;
    json: string;
    lengthDifference: number;
};
```

***

### compareAnsiStrings [#compareansistrings]

Compares two ANSI strings.

```typescript
function compareAnsiStrings(
    actual: string,
    expected: string,
): {
    ansiEqual: boolean;
    strippedEqual: boolean;
    summary: string;
    actual: FormattedAnsiString;
    expected: FormattedAnsiString;
};
```

***

## Type Definitions [#type-definitions]

### CaseOptions [#caseoptions]

```typescript
interface CaseOptions {
    cache?: boolean;
    cacheMaxSize?: number;
    cacheStore?: Map<string, string>;
    knownAcronyms?: ReadonlyArray<string>;
    locale?: string;
}
```

### TruncateOptions [#truncateoptions]

```typescript
interface TruncateOptions {
    ellipsis?: string;
    ellipsisWidth?: number;
    position?: "end" | "middle" | "start";
    preferTruncationOnSpace?: boolean;
    width?: StringWidthOptions;
}
```

### StringWidthOptions [#stringwidthoptions]

```typescript
interface StringWidthOptions {
    ambiguousIsNarrow?: boolean;
    ansiWidth?: number;
    controlWidth?: number;
    countAnsiEscapeCodes?: boolean;
    emojiWidth?: number;
    fullWidth?: number;
    regularWidth?: number;
    tabWidth?: number;
    wideWidth?: number;
}
```

### SlugifyOptions [#slugifyoptions]

```typescript
interface SlugifyOptions {
    allowedChars?: string;
    fixChineseSpacing?: boolean;
    ignore?: string[];
    lowercase?: boolean;
    replaceAfter?: OptionReplaceCombined;
    replaceBefore?: OptionReplaceCombined;
    separator?: string;
    transliterate?: boolean;
    trim?: boolean;
    unknown?: string;
    uppercase?: boolean;
}
```

### ExcerptOptions [#excerptoptions]

```typescript
interface ExcerptOptions {
    // String to append when truncation occurs
    ellipsis?: string; // default: '…'

    // All other TruncateOptions except 'position' (always 'end')
    // See TruncateOptions for full details
}
```

### FlipOptions [#flipoptions]

```typescript
interface FlipOptions extends Omit<CaseOptions, "handleEmoji"> {
    // Same as CaseOptions but handleEmoji is not available
    // (emojis are preserved by default in flipCase)
}
```

### IdentifyCase [#identifycase-1]

```typescript
type IdentifyCase = "camel" | "pascal" | "snake" | "kebab" | "upper_snake" | "lower" | "upper" | "title" | "sentence" | "mixed" | "unknown";
```

***

## Next Steps [#next-steps]

* [Case Conversion](/docs/packages/string/case-conversion) - Case conversion guide
* [String Manipulation](/docs/packages/string/string-manipulation) - String manipulation guide
* [TypeScript](/docs/packages/string/typescript) - TypeScript support


# Case Conversion (/docs/packages/string/case-conversion)



# Case Conversion [#case-conversion]

@visulima/string provides comprehensive case conversion utilities with intelligent handling of acronyms, multi-language support, and type-safe operations.

## Available Case Styles [#available-case-styles]

### camelCase [#camelcase]

Converts strings to camelCase format.

```typescript
import { camelCase } from "@visulima/string";

camelCase("foo bar"); // 'fooBar'
camelCase("foo-bar"); // 'fooBar'
camelCase("foo_bar"); // 'fooBar'
camelCase("XMLHttpRequest"); // 'xmlHttpRequest'
camelCase("AJAXRequest"); // 'ajaxRequest'
camelCase("QueryXML123String"); // 'queryXml123String'
```

### PascalCase [#pascalcase]

Converts strings to PascalCase format.

```typescript
import { pascalCase } from "@visulima/string";

pascalCase("foo bar"); // 'FooBar'
pascalCase("foo-bar"); // 'FooBar'
pascalCase("foo_bar"); // 'FooBar'
pascalCase("XMLHttpRequest"); // 'XmlHttpRequest'
pascalCase("AJAXRequest"); // 'AjaxRequest'
pascalCase("QueryXML123String"); // 'QueryXml123String'
```

### snake\_case [#snake_case]

Converts strings to snake\_case format.

```typescript
import { snakeCase } from "@visulima/string";

snakeCase("fooBar"); // 'foo_bar'
snakeCase("foo bar"); // 'foo_bar'
snakeCase("foo-bar"); // 'foo_bar'
snakeCase("XMLHttpRequest"); // 'xml_http_request'
snakeCase("AJAXRequest"); // 'ajax_request'
snakeCase("QueryXML123String"); // 'query_xml_123_string'
```

### kebab-case [#kebab-case]

Converts strings to kebab-case format.

```typescript
import { kebabCase } from "@visulima/string";

kebabCase("fooBar"); // 'foo-bar'
kebabCase("foo bar"); // 'foo-bar'
kebabCase("foo_bar"); // 'foo-bar'
kebabCase("XMLHttpRequest"); // 'xml-http-request'
kebabCase("AJAXRequest"); // 'ajax-request'
kebabCase("QueryXML123String"); // 'query-xml-123-string'
```

### CONSTANT\_CASE [#constant_case]

Converts strings to CONSTANT\_CASE format.

```typescript
import { constantCase } from "@visulima/string";

constantCase("foo bar"); // 'FOO_BAR'
constantCase("foo-bar"); // 'FOO_BAR'
constantCase("foo_bar"); // 'FOO_BAR'
constantCase("XMLHttpRequest"); // 'XML_HTTP_REQUEST'
constantCase("AJAXRequest"); // 'AJAX_REQUEST'
constantCase("QueryXML123String"); // 'QUERY_XML_123_STRING'
```

### Other Case Styles [#other-case-styles]

#### dot.case [#dotcase]

```typescript
import { dotCase } from "@visulima/string";

dotCase("foo bar"); // 'foo.bar'
dotCase("XMLHttpRequest"); // 'xml.http.request'
```

#### path/case [#pathcase]

```typescript
import { pathCase } from "@visulima/string";

pathCase("foo bar"); // 'foo/bar'
pathCase("XMLHttpRequest"); // 'xml/http/request'
```

#### Title Case [#title-case]

```typescript
import { titleCase } from "@visulima/string";

titleCase("this-IS-aTitle"); // 'This is a Title'
titleCase("XMLHttpRequest"); // 'XML Http Request'
```

#### Sentence case [#sentence-case]

```typescript
import { sentenceCase } from "@visulima/string";

sentenceCase("foo bar"); // 'Foo bar'
sentenceCase("XMLHttpRequest"); // 'Xml http request'
```

#### flatcase [#flatcase]

```typescript
import { flatCase } from "@visulima/string";

flatCase("foo bar"); // 'foobar'
flatCase("foo-bar"); // 'foobar'
```

#### Capital Case [#capital-case]

```typescript
import { capitalCase } from "@visulima/string";

capitalCase("foo bar"); // 'Foo Bar'
capitalCase("foo-bar"); // 'Foo Bar'
```

#### Train-Case [#train-case]

```typescript
import { trainCase } from "@visulima/string";

trainCase("foo bar"); // 'Foo-Bar'
trainCase("XMLHttpRequest"); // 'Xml-Http-Request'
```

#### Pascal\_Snake\_Case [#pascal_snake_case]

```typescript
import { pascalSnakeCase } from "@visulima/string";

pascalSnakeCase("foo bar"); // 'Foo_Bar'
pascalSnakeCase("XMLHttpRequest"); // 'Xml_Http_Request'
```

## Configuration Options [#configuration-options]

All case conversion functions accept common configuration options:

```typescript
import type { CaseOptions } from "@visulima/string";

interface CaseOptions {
    // Enable caching for better performance
    cache?: boolean;

    // Maximum size of the cache (default: 1000)
    cacheMaxSize?: number;

    // Custom cache store
    cacheStore?: Map<string, string>;

    // Known acronyms to preserve
    knownAcronyms?: ReadonlyArray<string>;

    // Locale for script-aware case conversion
    locale?: string;
}
```

### Example with Options [#example-with-options]

```typescript
import { camelCase } from "@visulima/string";

const result = camelCase("API_RESPONSE_XML", {
    knownAcronyms: ["API", "XML"],
    cache: true,
    locale: "en",
});
// Result: 'apiResponseXml'
```

## String Splitting [#string-splitting]

The `splitByCase` function intelligently splits strings by case transitions:

```typescript
import { splitByCase } from "@visulima/string";

// Basic case transitions
splitByCase("camelCase"); // ['camel', 'Case']
splitByCase("PascalCase"); // ['Pascal', 'Case']
splitByCase("snake_case"); // ['snake', 'case']
splitByCase("kebab-case"); // ['kebab', 'case']

// Numbers and acronyms
splitByCase("XMLHttpRequest"); // ['XML', 'Http', 'Request']
splitByCase("iOS8"); // ['i', 'OS', '8']
splitByCase("IPv6Address"); // ['IP', 'v6', 'Address']
```

### Multi-Language Support [#multi-language-support]

```typescript
// Japanese
splitByCase("ひらがなカタカナABC", { locale: "ja" });
// ['ひらがな', 'カタカナ', 'ABC']

// Korean
splitByCase("한글Text", { locale: "ko" });
// ['한글', 'Text']

// Chinese
splitByCase("中文Text", { locale: "zh" });
// ['中文', 'Text']

// Cyrillic
splitByCase("русскийText", { locale: "ru" });
// ['русский', 'Text']

// Greek
splitByCase("ελληνικάText", { locale: "el" });
// ['ελληνικά', 'Text']
```

### Split Options [#split-options]

```typescript
import type { SplitOptions } from "@visulima/string";

interface SplitOptions {
    // Locale for script-aware splitting
    locale?: string;

    // Known acronyms to preserve
    knownAcronyms?: ReadonlyArray<string>;

    // Handle ANSI escape sequences
    handleAnsi?: boolean;

    // Handle emoji sequences
    handleEmoji?: boolean;

    // Normalize case (convert all-upper tokens to title case)
    normalize?: boolean;

    // Custom separators
    separators?: ReadonlyArray<string> | RegExp;

    // Strip ANSI sequences
    stripAnsi?: boolean;

    // Strip emoji sequences
    stripEmoji?: boolean;
}
```

### Advanced Split Examples [#advanced-split-examples]

```typescript
import { splitByCase } from "@visulima/string";

// With known acronyms
splitByCase("MyXMLParser", {
    knownAcronyms: ["XML"],
    normalize: true,
    locale: "en",
});
// ['My', 'XML', 'Parser']

// With emoji handling
splitByCase("🎉HappyBirthday🎂", {
    handleEmoji: true,
});
// ['🎉', 'Happy', 'Birthday', '🎂']

// With ANSI codes
const coloredText = "\x1b[31mRedText\x1b[0m";
splitByCase(coloredText, {
    handleAnsi: true,
});
// Preserves ANSI codes while splitting
```

## Helper Functions [#helper-functions]

### lowerFirst [#lowerfirst]

Converts the first character to lowercase:

```typescript
import { lowerFirst } from "@visulima/string";

lowerFirst("Hello"); // 'hello'
lowerFirst("HELLO"); // 'hELLO'
```

### upperFirst [#upperfirst]

Converts the first character to uppercase:

```typescript
import { upperFirst } from "@visulima/string";

upperFirst("hello"); // 'Hello'
upperFirst("hello world"); // 'Hello world'
```

### noCase [#nocase]

Removes all case styling:

```typescript
import { noCase } from "@visulima/string";

noCase("camelCase"); // 'camel case'
noCase("PascalCase"); // 'pascal case'
noCase("snake_case"); // 'snake case'
```

### flipCase [#flipcase]

Inverts the case of each character:

```typescript
import { flipCase } from "@visulima/string";

flipCase("Hello World"); // 'hELLO wORLD'
flipCase("XMLHttpRequest"); // 'xmlhTTPrEQUEST'
flipCase("FooBar"); // 'fOObAR'
flipCase("foobar"); // 'FOOBAR'
flipCase("FOOBAR"); // 'foobar'
```

#### With Options [#with-options]

```typescript
// With locale support
flipCase("İstanbul", { locale: "tr" });
// Uses Turkish locale for case conversion

// Strip ANSI codes before flipping
flipCase("\x1b[31mRed\x1b[0m", { stripAnsi: true });
// 'RED'

// Strip emojis before flipping
flipCase("Hello 👋", { stripEmoji: true });
// 'HELLO '

// Handle ANSI codes (preserve them)
flipCase("\x1b[31mRed\x1b[0m", { handleAnsi: true });
// Preserves ANSI codes while flipping case
```

### identifyCase [#identifycase]

Identifies the case style of a string. Returns one of: `'camel'`, `'pascal'`, `'snake'`, `'kebab'`, `'upper_snake'`, `'lower'`, `'upper'`, `'title'`, `'sentence'`, `'mixed'`, or `'unknown'`.

```typescript
import { identifyCase } from "@visulima/string";

// Common case styles
identifyCase("helloWorld"); // 'camel'
identifyCase("HelloWorld"); // 'pascal'
identifyCase("hello_world"); // 'snake'
identifyCase("HELLO_WORLD"); // 'upper_snake'
identifyCase("hello-world"); // 'kebab'

// Simple cases
identifyCase("foo"); // 'lower'
identifyCase("FOO"); // 'upper'

// Title and sentence case
identifyCase("Hello World"); // 'title'
identifyCase("Hello world"); // 'sentence'

// Mixed or unknown
identifyCase("FooBAR"); // 'mixed'
identifyCase("123"); // 'unknown'
identifyCase(""); // 'unknown'
```

## Performance Optimization [#performance-optimization]

### Caching [#caching]

Enable caching for frequently converted strings:

```typescript
import { camelCase } from "@visulima/string";

// With caching enabled (default)
const convert = (str: string) => camelCase(str, { cache: true });

// Multiple calls use cached results
convert("hello-world"); // Computed
convert("hello-world"); // From cache
```

### Custom Cache Store [#custom-cache-store]

Provide your own cache implementation:

```typescript
const cache = new Map<string, string>();

camelCase("hello-world", {
    cache: true,
    cacheStore: cache,
    cacheMaxSize: 500,
});
```

## TypeScript Support [#typescript-support]

Full TypeScript support with type inference:

```typescript
import type { CamelCase, PascalCase, SnakeCase, KebabCase, ConstantCase } from "@visulima/string";

// Type-level case conversion
type Input = "hello-world";
type Result = CamelCase<Input>; // 'helloWorld'

// Usage in functions
function convertToCamel<T extends string>(input: T): CamelCase<T> {
    return camelCase(input) as CamelCase<T>;
}
```

## Best Practices [#best-practices]

1. Use specific case functions instead of generic conversion when possible
2. Enable caching for frequently converted strings
3. Specify known acronyms for consistent handling
4. Use locale options for international text
5. Leverage TypeScript types for compile-time safety

## Next Steps [#next-steps]

* [String Manipulation](/docs/packages/string/string-manipulation) - Learn about text formatting
* [Slugification](/docs/packages/string/slugification) - Create URL-friendly slugs
* [API Reference](/docs/packages/string/api/case) - Detailed API documentation


# Examples (/docs/packages/string/examples)



# Examples [#examples]

Practical, real-world examples demonstrating how to use @visulima/string in common scenarios.

## API Key Naming Conventions [#api-key-naming-conventions]

Convert between naming conventions when working with APIs that use different styles.

```typescript
import { camelCase, snakeCase, kebabCase } from "@visulima/string/case";

// Convert API response keys from snake_case to camelCase
const apiResponse = {
    user_name: "John",
    email_address: "john@example.com",
    phone_number: "555-1234",
};

const camelCaseKeys = Object.fromEntries(Object.entries(apiResponse).map(([key, value]) => [camelCase(key), value]));
// { userName: 'John', emailAddress: 'john@example.com', phoneNumber: '555-1234' }

// Convert camelCase to snake_case for API requests
const requestBody = {
    userName: "Jane",
    emailAddress: "jane@example.com",
};

const snakeCaseKeys = Object.fromEntries(Object.entries(requestBody).map(([key, value]) => [snakeCase(key), value]));
// { user_name: 'Jane', email_address: 'jane@example.com' }
```

## CSS Class Name Generation [#css-class-name-generation]

Generate CSS class names from component props.

```typescript
import { kebabCase } from "@visulima/string/case";

function generateClassName(component: string, modifiers: Record<string, boolean>): string {
    const base = kebabCase(component);
    const activeModifiers = Object.entries(modifiers)
        .filter(([, active]) => active)
        .map(([name]) => `${base}--${kebabCase(name)}`);

    return [base, ...activeModifiers].join(" ");
}

generateClassName("UserProfile", {
    isActive: true,
    hasAvatar: true,
    isDisabled: false,
});
// 'user-profile user-profile--is-active user-profile--has-avatar'
```

## Environment Variable Mapping [#environment-variable-mapping]

Map configuration objects to environment variable names.

```typescript
import { constantCase } from "@visulima/string/case";

function configToEnvVars(config: Record<string, string>, prefix: string = "APP"): Record<string, string> {
    return Object.fromEntries(Object.entries(config).map(([key, value]) => [`${prefix}_${constantCase(key)}`, value]));
}

configToEnvVars({
    databaseUrl: "postgres://localhost",
    redisHost: "127.0.0.1",
    apiSecret: "my-secret",
});
// {
//   APP_DATABASE_URL: 'postgres://localhost',
//   APP_REDIS_HOST: '127.0.0.1',
//   APP_API_SECRET: 'my-secret',
// }
```

## Blog Post URL Generation [#blog-post-url-generation]

Generate SEO-friendly URLs from article titles.

```typescript
import { slugify } from "@visulima/string/slugify";

function generatePostUrl(title: string, date: Date): string {
    const slug = slugify(title);
    const year = date.getFullYear();
    const month = String(date.getMonth() + 1).padStart(2, "0");

    return `/blog/${year}/${month}/${slug}`;
}

generatePostUrl("My First Blog Post!", new Date("2024-03-15"));
// '/blog/2024/03/my-first-blog-post'

generatePostUrl("Internationalization: 国际化 and i18n", new Date("2024-06-01"));
// '/blog/2024/06/internationalization-guo-ji-hua-and-i18n'

// With custom options for a filename
function generateFilename(title: string): string {
    return slugify(title, {
        separator: "_",
        allowedChars: "a-zA-Z0-9_.",
    });
}

generateFilename("My Document (Final) v2.pdf");
// 'my_document_final_v2.pdf'
```

## CLI Command Suggestions [#cli-command-suggestions]

Suggest the correct command when users make typos.

```typescript
import { closestString } from "@visulima/string/closest-string";
import { wordSimilaritySort } from "@visulima/string/word-similarity-sort";

const commands = ["init", "build", "dev", "start", "test", "lint", "format", "deploy", "publish"];

function suggestCommand(input: string): string {
    const match = closestString(input, commands);

    if (!match) {
        return `Unknown command: ${input}. Run --help to see available commands.`;
    }

    return `Did you mean: ${match}?`;
}

suggestCommand("biuld"); // 'Did you mean: build?'
suggestCommand("tset"); // 'Did you mean: test?'
suggestCommand("publsh"); // 'Did you mean: publish?'

// Show multiple suggestions
function suggestCommands(input: string, count: number = 3): string[] {
    return wordSimilaritySort(input, commands).slice(0, count);
}

suggestCommands("sta");
// ['start', 'init', 'test']
```

## Terminal Table Formatting [#terminal-table-formatting]

Build aligned columns in terminal output using string width.

```typescript
import { getStringWidth } from "@visulima/string/get-string-width";

function formatTable(headers: string[], rows: string[][], padding: number = 2): string {
    // Calculate column widths
    const colWidths = headers.map((header, colIndex) => {
        const cellWidths = rows.map((row) => getStringWidth(row[colIndex] ?? ""));
        return Math.max(getStringWidth(header), ...cellWidths);
    });

    // Format a row
    const formatRow = (cells: string[]): string =>
        cells
            .map((cell, i) => {
                const width = getStringWidth(cell);
                const pad = " ".repeat((colWidths[i] ?? 0) - width + padding);
                return cell + pad;
            })
            .join("");

    // Build table
    const headerLine = formatRow(headers);
    const separator = colWidths.map((w) => "-".repeat(w + padding)).join("");
    const bodyLines = rows.map((row) => formatRow(row));

    return [headerLine, separator, ...bodyLines].join("\n");
}

const table = formatTable(
    ["Name", "Country", "City"],
    [
        ["John", "USA", "New York"],
        ["Tanaka", "Japan", "Tokyo"],
        ["Ahmed", "Egypt", "Cairo"],
    ],
);

console.log(table);
// Name      Country   City
// --------------------------------
// John      USA       New York
// Tanaka    Japan     Tokyo
// Ahmed     Egypt     Cairo
```

## Search Autocomplete [#search-autocomplete]

Build a fuzzy search with ranked results.

```typescript
import { wordSimilaritySort } from "@visulima/string/word-similarity-sort";
import { distance } from "@visulima/string";

const products = ["iPhone 15 Pro", "iPhone 15 Pro Max", "Samsung Galaxy S24", "Samsung Galaxy S24 Ultra", "Google Pixel 8", "Google Pixel 8 Pro", "OnePlus 12"];

function searchProducts(query: string, maxResults: number = 5): string[] {
    if (query.length < 2) return [];

    // Sort by similarity, then filter out poor matches
    const sorted = wordSimilaritySort(query, products, {
        caseSensitive: false,
    });

    // Only return results with reasonable distance
    return sorted
        .filter((product) => {
            const d = distance(query.toLowerCase(), product.toLowerCase());
            // Allow distance up to half the query length
            return d <= Math.max(query.length * 0.6, 3);
        })
        .slice(0, maxResults);
}

searchProducts("iphone");
// ['iPhone 15 Pro', 'iPhone 15 Pro Max']

searchProducts("pixel");
// ['Google Pixel 8', 'Google Pixel 8 Pro']
```

## Truncating Terminal Output [#truncating-terminal-output]

Truncate strings to fit terminal width while preserving Unicode and ANSI codes.

```typescript
import { getStringTruncatedWidth } from "@visulima/string/get-string-truncated-width";
import { getStringWidth } from "@visulima/string/get-string-width";

function truncateForTerminal(text: string, maxWidth: number, ellipsis: string = "..."): string {
    const width = getStringWidth(text);

    if (width <= maxWidth) {
        return text;
    }

    const result = getStringTruncatedWidth(text, {
        limit: maxWidth,
        ellipsis,
    });

    return text.slice(0, result.index) + (result.ellipsed ? ellipsis : "");
}

truncateForTerminal("Hello, World!", 10);
// 'Hello, ...'

truncateForTerminal("你好世界 - Hello World", 12);
// '你好世界 ...'

// Preserve ANSI colors
truncateForTerminal("\x1b[31mError: Something went wrong\x1b[0m", 15);
// Truncates the visible text, not the escape codes
```

## Detecting Text Direction [#detecting-text-direction]

Handle bidirectional text in your application.

```typescript
import { direction } from "@visulima/string";

function wrapWithDirection(text: string): string {
    const dir = direction(text);

    if (dir === "rtl") {
        return `<span dir="rtl">${text}</span>`;
    }

    return text;
}

wrapWithDirection("Hello"); // 'Hello'
wrapWithDirection("مرحبا"); // '<span dir="rtl">مرحبا</span>'
```

## Testing Colored CLI Output [#testing-colored-cli-output]

Test that your CLI produces correctly colored output.

```typescript
import { expect, describe, it } from "vitest";
import { toEqualAnsi } from "@visulima/string/test/vitest";
import { formatAnsiString, compareAnsiStrings } from "@visulima/string/test/utils";

expect.extend({ toEqualAnsi });

describe("CLI formatter", () => {
    it("should format errors in red", () => {
        const output = formatError("File not found");

        // Exact ANSI comparison
        expect(output).toEqualAnsi("\x1b[31mError: File not found\x1b[39m");
    });

    it("should format warnings with yellow text", () => {
        const output = formatWarning("Deprecated API");
        const formatted = formatAnsiString(output);

        // Test visible content
        expect(formatted.stripped).toBe("Warning: Deprecated API");

        // Verify ANSI codes are present
        expect(formatted.lengthDifference).toBeGreaterThan(0);
    });

    it("should compare two formatted strings", () => {
        const v1Output = formatV1("message");
        const v2Output = formatV2("message");

        const comparison = compareAnsiStrings(v1Output, v2Output);

        // They should display the same text
        expect(comparison.strippedEqual).toBe(true);
    });
});
```

## Case Identification for Input Validation [#case-identification-for-input-validation]

Validate that user input follows expected naming conventions.

```typescript
import { identifyCase } from "@visulima/string/case";

function validateVariableName(name: string): {
    valid: boolean;
    caseStyle: string;
    suggestion?: string;
} {
    const caseStyle = identifyCase(name);

    if (caseStyle === "camel") {
        return { valid: true, caseStyle };
    }

    return {
        valid: false,
        caseStyle,
        suggestion: `Expected camelCase but got ${caseStyle}`,
    };
}

validateVariableName("myVariable");
// { valid: true, caseStyle: 'camel' }

validateVariableName("my_variable");
// { valid: false, caseStyle: 'snake', suggestion: 'Expected camelCase but got snake' }

validateVariableName("MyVariable");
// { valid: false, caseStyle: 'pascal', suggestion: 'Expected camelCase but got pascal' }
```

## Multi-Language Content Processing [#multi-language-content-processing]

Process content in multiple languages using locale-aware splitting.

```typescript
import { splitByCase, camelCase } from "@visulima/string/case";

// Split mixed-script content
const japaneseMixed = "ひらがなカタカナABC";
splitByCase(japaneseMixed, { locale: "ja" });
// ['ひらがな', 'カタカナ', 'ABC']

// Case conversion with locale support
camelCase("Straße nach Berlin", { locale: "de" });
// Handles German eszett correctly

// Korean mixed text
splitByCase("한글Text", { locale: "ko" });
// ['한글', 'Text']
```

## Building a Spell Checker [#building-a-spell-checker]

Use string similarity to suggest corrections for misspelled words.

```typescript
import { closestString } from "@visulima/string/closest-string";
import { closestN } from "@visulima/string";

const dictionary = [
    "hello",
    "world",
    "computer",
    "program",
    "algorithm",
    "function",
    "variable",
    "constant",
    "interface",
    "abstract",
    "implement",
    "typescript",
];

function spellCheck(word: string): {
    correct: boolean;
    suggestions: (string | undefined)[];
} {
    const lowerWord = word.toLowerCase();

    if (dictionary.includes(lowerWord)) {
        return { correct: true, suggestions: [] };
    }

    return {
        correct: false,
        suggestions: closestN(lowerWord, dictionary, 3),
    };
}

spellCheck("algorythm");
// { correct: false, suggestions: ['algorithm', ...] }

spellCheck("typscript");
// { correct: false, suggestions: ['typescript', ...] }

spellCheck("function");
// { correct: true, suggestions: [] }
```

## Next Steps [#next-steps]

* [Case Conversion](/docs/packages/string/case-conversion) -- Guide to case conversion
* [Slugification](/docs/packages/string/slugification) -- Guide to slugification and transliteration
* [String Width](/docs/packages/string/string-width) -- Guide to string width calculation
* [String Similarity](/docs/packages/string/string-similarity) -- Guide to string similarity
* [API Reference](/docs/packages/string/api) -- Complete API documentation


# Getting Started (/docs/packages/string)



# Getting Started [#getting-started]

@visulima/string is a comprehensive TypeScript library for string manipulation, providing utilities for case conversion, text formatting, internationalization, and advanced string operations.

## Key Features [#key-features]

### Case Conversion [#case-conversion]

Transform strings between multiple case styles with intelligent handling of acronyms and multi-language support:

* camelCase, PascalCase, snake\_case, kebab-case
* CONSTANT\_CASE, dot.case, path/case
* Title Case with smart minor word handling
* Sentence case, Train-Case, and more

### Unicode and Multi-Language Support [#unicode-and-multi-language-support]

Full support for international text processing:

* CJK Scripts (Japanese, Korean, Chinese)
* European Scripts (Cyrillic, Greek, Latin)
* RTL Scripts (Arabic, Hebrew)
* Indic Scripts (Devanagari, Bengali, Tamil)
* Southeast Asian (Thai, Lao, Khmer)

### String Width and Truncation [#string-width-and-truncation]

Accurate visual width calculation and intelligent truncation:

* Unicode-aware width calculation
* ANSI escape code handling
* Smart truncation with ellipsis support
* Emoji and zero-width character support

### Text Formatting [#text-formatting]

Advanced text formatting utilities:

* Word wrapping with multiple modes
* Text alignment (left, center, right)
* Indentation removal (outdent)
* ANSI color code preservation

### Additional Features [#additional-features]

* String analysis: count occurrences and detect text direction
* Slugification with transliteration
* Levenshtein distance calculation
* String similarity comparison
* Advanced string replacement with ignore ranges
* Type-safe native string extensions

## Quick Start [#quick-start]

### Installation [#installation]

```bash
npm install @visulima/string
```

```bash
yarn add @visulima/string
```

```bash
pnpm add @visulima/string
```

### Basic Usage [#basic-usage]

```typescript
import { camelCase, slugify, truncate, wordWrap } from "@visulima/string";

// Case conversion
camelCase("hello-world"); // 'helloWorld'

// Slugification
slugify("Hello World!"); // 'hello-world'

// Truncation
truncate("A very long string", 10); // 'A very lo…'

// Word wrapping
wordWrap("This is a long text that needs wrapping", { width: 20 });
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/string/installation">
    Learn how to install and configure @visulima/string
  </Card>

  <Card title="Case Conversion" href="/docs/packages/string/case-conversion">
    Transform strings between different case styles
  </Card>

  <Card title="String Manipulation" href="/docs/packages/string/string-manipulation">
    Format and manipulate strings
  </Card>

  <Card title="API Reference" href="/docs/packages/string/api">
    Explore the complete API documentation
  </Card>
</Cards>

## TypeScript Support [#typescript-support]

The library is written in TypeScript and provides comprehensive type definitions:

```typescript
import type { CaseOptions, TruncateOptions } from "@visulima/string";

const options: CaseOptions = {
    locale: "en",
    knownAcronyms: ["API", "URL"],
    cache: true,
};
```

## Performance [#performance]

The library is optimized for performance with:

* Precompiled regex patterns
* Smart caching mechanisms
* Efficient string processing
* Minimal memory allocations

## Browser and Node.js Support [#browser-and-nodejs-support]

Works seamlessly in both environments:

* Node.js >= 18.0.0
* All modern browsers
* TypeScript >= 5.0


# Installation (/docs/packages/string/installation)





# Installation [#installation]

## Package Manager [#package-manager]

Install @visulima/string using your preferred package manager:

<Tabs items="[&#x22;pnpm&#x22;, &#x22;npm&#x22;, &#x22;yarn&#x22;]">
  <Tab value="pnpm">
    `bash pnpm add @visulima/string `
  </Tab>

  <Tab value="npm">
    `bash npm install @visulima/string `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @visulima/string `
  </Tab>
</Tabs>

## Requirements [#requirements]

* Node.js >= 22.13.0 \<= 25.x
* TypeScript >= 5.0 (for TypeScript projects)

## TypeScript Configuration [#typescript-configuration]

### Basic Setup [#basic-setup]

The library works out of the box with TypeScript. Import functions as needed:

```typescript
import { camelCase, slugify } from "@visulima/string";
```

### Enhanced Native String Types [#enhanced-native-string-types]

For enhanced type-safe native string operations, configure your `tsconfig.json`:

```json title="tsconfig.json"
{
    "compilerOptions": {
        "types": ["@visulima/string/native-string-types"]
    }
}
```

Alternatively, add a triple-slash reference in your TypeScript files:

```typescript
/// <reference types="@visulima/string/native-string-types" />
```

This enables advanced type inference for native string methods:

```typescript
const str = "Hello, World!";

// Type-safe operations with literal type inference
str.charAt<typeof str, 0>(); // type: 'H'
str.slice<typeof str, 0, 5>(); // type: 'Hello'
str.split<typeof str, ", ">(); // type: ['Hello', 'World!']
```

## Module Imports [#module-imports]

### Full Import [#full-import]

Import all functions from the main entry point:

```typescript
import { camelCase, slugify, truncate, wordWrap } from "@visulima/string";
```

### Subpath Imports [#subpath-imports]

Import specific modules for better tree-shaking:

```typescript
// Case conversion (most per-file modules use default exports)
import camelCase from "@visulima/string/case/camel-case";
import pascalCase from "@visulima/string/case/pascal-case";
// A few use named exports (kebab-case, flip-case, split-by-case)
import { kebabCase } from "@visulima/string/case/kebab-case";

// String utilities
import { slugify } from "@visulima/string/slugify";
import { truncate } from "@visulima/string/truncate";
import { wordWrap } from "@visulima/string/word-wrap";

// String width
import { getStringWidth } from "@visulima/string/get-string-width";

// Text alignment
import { alignText } from "@visulima/string/align-text";

// Outdent
import { outdent } from "@visulima/string/outdent";
```

### Case Conversion Bundle [#case-conversion-bundle]

Import all case conversion functions:

```typescript
import {
    camelCase,
    pascalCase,
    snakeCase,
    kebabCase,
    constantCase,
    dotCase,
    pathCase,
    titleCase,
    sentenceCase,
    // ... and more
} from "@visulima/string/case";
```

## ESM and CommonJS [#esm-and-commonjs]

The package supports both ESM and CommonJS:

### ESM (Recommended) [#esm-recommended]

```typescript
import { camelCase } from "@visulima/string";
```

### CommonJS [#commonjs]

```javascript
const { camelCase } = require("@visulima/string");
```

## Testing Utilities [#testing-utilities]

For Vitest integration, import the custom matchers:

```typescript
import { expect, describe, it } from "vitest";
import { toEqualAnsi } from "@visulima/string/test/vitest";
import { formatAnsiString, compareAnsiStrings } from "@visulima/string/test/utils";

// Extend Vitest with custom matchers
expect.extend({ toEqualAnsi });

describe("ANSI string tests", () => {
    it("should match colored strings", () => {
        expect(actual).toEqualAnsi(expected);
    });
});
```

## Bundle Size [#bundle-size]

The library is designed for optimal bundle size:

* Tree-shakeable exports
* Minimal dependencies
* Efficient implementations
* Subpath imports for targeted usage

Use subpath imports to include only what you need:

```typescript
// Only imports camelCase function and its dependencies
import camelCase from "@visulima/string/case/camel-case";
```

## Browser Compatibility [#browser-compatibility]

Works in all modern browsers that support:

* ES2020 features
* Unicode property escapes in regex
* BigInt (for some advanced features)

## Verification [#verification]

Verify the installation by running a simple test:

```typescript
import { camelCase } from "@visulima/string";

console.log(camelCase("hello-world")); // Output: 'helloWorld'
```

## Next Steps [#next-steps]

* [Case Conversion](/docs/packages/string/case-conversion) - Learn about case conversion functions
* [String Manipulation](/docs/packages/string/string-manipulation) - Explore string manipulation utilities
* [API Reference](/docs/packages/string/api) - Browse the complete API documentation


# Slugification & Transliteration (/docs/packages/string/slugification)



# Slugification & Transliteration [#slugification--transliteration]

Convert strings into URL-friendly slugs and transliterate Unicode characters to ASCII with comprehensive language support.

## Slugification [#slugification]

The `slugify` function converts strings into URL-friendly slugs with automatic transliteration.

### Basic Usage [#basic-usage]

```typescript
import { slugify } from "@visulima/string";

slugify("Hello World!"); // 'hello-world'
slugify("Crème Brûlée"); // 'creme-brulee'
slugify("foo & bar * baz"); // 'foo-bar-baz'
```

### Chinese and CJK Support [#chinese-and-cjk-support]

```typescript
// Chinese with spacing (default)
slugify("你好 World!"); // 'ni-hao-world'

// Chinese without spacing
slugify("你好World!", {
    fixChineseSpacing: false,
}); // 'nihaoworld'

// Japanese
slugify("こんにちは世界"); // 'konnichiha-shi-jie'

// Korean
slugify("안녕하세요"); // 'annyeonghaseyo'
```

### Custom Separators [#custom-separators]

```typescript
slugify("foo bar baz", {
    separator: "_",
}); // 'foo_bar_baz'

slugify("Hello World", {
    separator: ".",
}); // 'hello.world'

// Empty separator
slugify("hello world", {
    separator: "",
}); // 'helloworld'
```

### Case Control [#case-control]

```typescript
// Lowercase (default)
slugify("FOO BAR"); // 'foo-bar'

// Uppercase
slugify("foo bar", {
    lowercase: false,
    uppercase: true,
}); // 'FOO-BAR'

// Preserve case
slugify("Foo Bar", {
    lowercase: false,
}); // 'Foo-Bar'
```

### Custom Allowed Characters [#custom-allowed-characters]

```typescript
// Default allows: a-zA-Z0-9-_.~
slugify("foo@bar.com"); // 'foobar-com'

// Custom allowed characters
slugify("foo@bar.com", {
    allowedChars: "a-z@.",
}); // 'foo@bar.com'

// Keep special characters
slugify("Keep !@#$", {
    allowedChars: "a-z!@$",
}); // 'keep!@$'
```

### Custom Replacements [#custom-replacements]

```typescript
// Replace before transliteration
slugify("Keep C++", {
    replaceBefore: { "C++": "cpp" },
}); // 'keep-cpp'

// Replace after transliteration
slugify("foo bar", {
    replaceAfter: { foo: "baz" },
}); // 'baz-bar'

// Multiple replacements
slugify("C# and C++", {
    replaceBefore: {
        "C#": "csharp",
        "C++": "cpp",
    },
}); // 'csharp-and-cpp'
```

### Ignore Segments [#ignore-segments]

```typescript
slugify("Keep THIS but change that", {
    ignore: ["THIS"],
}); // 'keep-this-but-change-that'
```

### Without Transliteration [#without-transliteration]

```typescript
// Skip transliteration entirely
slugify("café", {
    transliterate: false,
}); // 'caf'
// (é is removed because it's not in allowedChars)
```

### Complete Options [#complete-options]

```typescript
import type { SlugifyOptions } from "@visulima/string";

interface SlugifyOptions {
    // Allowed characters (default: 'a-zA-Z0-9-_.~')
    allowedChars?: string;

    // Add space between Chinese characters (default: true)
    fixChineseSpacing?: boolean;

    // Characters/strings to ignore during transliteration
    ignore?: string[];

    // Convert to lowercase (default: true)
    lowercase?: boolean;

    // Replacements after transliteration
    replaceAfter?: OptionReplaceCombined;

    // Replacements before transliteration
    replaceBefore?: OptionReplaceCombined;

    // Separator character (default: '-')
    separator?: string;

    // Enable transliteration (default: true)
    transliterate?: boolean;

    // Trim whitespace (default: false)
    trim?: boolean;

    // Character for unknown characters (default: '')
    unknown?: string;

    // Convert to uppercase (default: false)
    uppercase?: boolean;
}
```

## Transliteration [#transliteration]

The `transliterate` function converts Unicode characters to ASCII equivalents.

### Basic Transliteration [#basic-transliteration]

```typescript
import { transliterate } from "@visulima/string";

// European languages
transliterate("Crème brûlée"); // 'Creme brulee'
transliterate("Düsseldorf"); // 'Dusseldorf'
transliterate("Zürich"); // 'Zurich'

// Cyrillic
transliterate("Москва"); // 'Moskva'
transliterate("Привет"); // 'Privet'

// Greek
transliterate("Αθήνα"); // 'Athena'
transliterate("Ελληνικά"); // 'Ellenika'
```

### Chinese Transliteration [#chinese-transliteration]

```typescript
// With spacing (default)
transliterate("你好世界"); // 'Ni Hao Shi Jie'

// Without spacing
transliterate("你好世界", {
    fixChineseSpacing: false,
}); // 'NiHaoShiJie'

// Mixed Chinese and English
transliterate("你好World"); // 'Ni Hao World'
```

### Thai Romanization [#thai-romanization]

```typescript
// Automatic Thai romanization
transliterate("สวัสดี"); // 'sawatdi'
transliterate("ประเทศไทย"); // 'prathet thai'
```

### Custom Replacements [#custom-replacements-1]

```typescript
// Replace before transliteration
transliterate("Replace C++ before map", {
    replaceBefore: { "C++": "cpp" },
}); // 'Replace cpp before map'

// Replace after transliteration
transliterate("café", {
    replaceAfter: { e: "E" },
}); // 'cafE'

// Array format
transliterate("hello world", {
    replaceAfter: [
        ["hello", "hi"],
        ["world", "earth"],
    ],
}); // 'hi earth'

// Regular expressions
transliterate("test123", {
    replaceAfter: [[/\d+/g, "NUM"]],
}); // 'testNUM'
```

### Ignore Segments [#ignore-segments-1]

```typescript
// Keep specific strings unchanged
transliterate("Don't change THIS, but change that", {
    ignore: ["THIS"],
}); // "Dont change THIS, but change that"

// Multiple ignore segments
transliterate("Keep @username and #hashtag", {
    ignore: ["@username", "#hashtag"],
}); // 'Keep @username and #hashtag'
```

### Unknown Characters [#unknown-characters]

```typescript
// Default: remove unknown characters
transliterate("Hello 🚀 World"); // 'Hello  World'

// Custom replacement for unknown characters
transliterate("a🚀b", {
    unknown: "[?]",
}); // 'a[?]b'

transliterate("test�ing", {
    unknown: "",
}); // 'testing'
```

### Trim Output [#trim-output]

```typescript
transliterate("  hello world  ", {
    trim: true,
}); // 'hello world'

transliterate("  你好  ", {
    trim: true,
}); // 'Ni Hao'
```

### Complete Options [#complete-options-1]

```typescript
import type { OptionsTransliterate } from "@visulima/string";

interface OptionsTransliterate {
    // Add space between Chinese Pinyin syllables (default: true)
    fixChineseSpacing?: boolean;

    // Strings to ignore during transliteration (default: [])
    ignore?: string[];

    // Replacements before character map (default: [])
    replaceBefore?: OptionReplaceCombined;

    // Replacements after character map (default: [])
    replaceAfter?: OptionReplaceCombined;

    // Trim whitespace from result (default: false)
    trim?: boolean;

    // Character for unknown characters (default: '')
    unknown?: string;
}
```

## Language Support [#language-support]

### European Languages [#european-languages]

```typescript
// French
transliterate("Français"); // 'Francais'
transliterate("Côte d'Azur"); // 'Cote d\'Azur'

// German
transliterate("Größe"); // 'Grosse'
transliterate("Straße"); // 'Strasse'

// Spanish
transliterate("España"); // 'Espana'
transliterate("Niño"); // 'Nino'

// Italian
transliterate("Città"); // 'Citta'
transliterate("Perché"); // 'Perche'

// Portuguese
transliterate("Português"); // 'Portugues'
transliterate("São Paulo"); // 'Sao Paulo'
```

### Slavic Languages [#slavic-languages]

```typescript
// Russian
transliterate("Россия"); // 'Rossiia'
transliterate("Привет мир"); // 'Privet mir'

// Polish
transliterate("Łódź"); // 'Lodz'
transliterate("Kraków"); // 'Krakow'

// Czech
transliterate("Česká republika"); // 'Ceska republika'

// Croatian
transliterate("Zagreb"); // 'Zagreb'
```

### Middle Eastern Languages [#middle-eastern-languages]

```typescript
// Arabic
transliterate("مرحبا"); // 'mrhb'
transliterate("العربية"); // 'l'rby'

// Hebrew
transliterate("שלום"); // 'shlwm'
transliterate("ישראל"); // 'ysr'l'
```

### Asian Languages [#asian-languages]

```typescript
// Japanese (Hiragana)
transliterate("ひらがな"); // 'hiragana'

// Japanese (Katakana)
transliterate("カタカナ"); // 'katakana'

// Korean
transliterate("한글"); // 'hangeul'
transliterate("대한민국"); // 'daehanmingug'

// Chinese (Simplified)
transliterate("简体中文"); // 'Jian Ti Zhong Wen'

// Chinese (Traditional)
transliterate("繁體中文"); // 'Fan Ti Zhong Wen'

// Thai
transliterate("ภาษาไทย"); // 'phasa thai'
```

### Indic Scripts [#indic-scripts]

```typescript
// Hindi (Devanagari)
transliterate("नमस्ते"); // 'nmste'

// Bengali
transliterate("বাংলা"); // 'bamla'

// Tamil
transliterate("தமிழ்"); // 'tmil'
```

## Best Practices [#best-practices]

1. Use `slugify` for URL generation - it handles everything automatically
2. Use `transliterate` when you need more control over the conversion
3. Specify `fixChineseSpacing: false` for more compact Chinese output
4. Use `ignore` option to preserve brand names or special terms
5. Leverage `replaceBefore` for handling special cases before transliteration
6. Use `replaceAfter` for post-processing the transliterated output

## Common Use Cases [#common-use-cases]

### URL Slugs [#url-slugs]

```typescript
const title = "My Blog Post - 2024!";
const slug = slugify(title);
// 'my-blog-post-2024'

const url = `https://example.com/blog/${slug}`;
```

### Filename Sanitization [#filename-sanitization]

```typescript
const filename = "My File (Final) v2.txt";
const safe = slugify(filename, {
    separator: "_",
    allowedChars: "a-zA-Z0-9_.",
});
// 'my_file_final_v2.txt'
```

### Search Indexing [#search-indexing]

```typescript
const searchTerm = "Café Münchën";
const normalized = transliterate(searchTerm).toLowerCase();
// 'cafe munchen'
```

### Tag Generation [#tag-generation]

```typescript
const text = "Node.js & JavaScript Development";
const tag = slugify(text, {
    separator: "-",
    replaceBefore: {
        "Node.js": "nodejs",
        JavaScript: "javascript",
    },
});
// 'nodejs-javascript-development'
```

## Next Steps [#next-steps]

* [String Width](/docs/packages/string/string-width) - Calculate visual string width
* [Testing](/docs/packages/string/testing) - Test utilities for ANSI strings
* [API Reference](/docs/packages/string/api/slugify) - Complete API documentation


# String Manipulation (/docs/packages/string/string-manipulation)



# String Manipulation [#string-manipulation]

Comprehensive utilities for formatting and manipulating strings with full Unicode and ANSI escape code support.

## Text Truncation [#text-truncation]

The `truncate` function provides intelligent string truncation with configurable positions and Unicode support.

### Basic Truncation [#basic-truncation]

```typescript
import { truncate } from "@visulima/string";

// Truncate from the end (default)
truncate("unicorn", 4); // 'un…'
truncate("unicorn", 4, { position: "end" }); // 'un…'

// Truncate from the start
truncate("unicorn", 5, { position: "start" }); // '…orn'

// Truncate from the middle
truncate("unicorn", 5, { position: "middle" }); // 'un…n'
```

### Custom Ellipsis [#custom-ellipsis]

```typescript
truncate("unicorns", 5, { ellipsis: "." }); // 'unic.'
truncate("unicorns", 5, { ellipsis: " ." }); // 'uni .'
truncate("unicorns", 8, { ellipsis: "..." }); // 'unico...'
```

### Smart Truncation on Spaces [#smart-truncation-on-spaces]

```typescript
// Prefer truncation at word boundaries
truncate("dragons are awesome", 15, {
    position: "end",
    preferTruncationOnSpace: true,
});
// 'dragons are…'

truncate("unicorns rainbow dragons", 20, {
    position: "middle",
    preferTruncationOnSpace: true,
});
// 'unicorns…dragons'
```

### With ANSI Escape Codes [#with-ansi-escape-codes]

```typescript
const colored = "\x1b[31municorn\x1b[39m";
truncate(colored, 4);
// '\x1b[31mun\x1b[39m…' (preserves color codes)
```

### With Unicode Characters [#with-unicode-characters]

```typescript
// CJK characters (width 2)
truncate("안녕하세요", 3, {
    width: { fullWidth: 2 },
});
// '안…'

// Emojis
truncate("Hello 👋 World", 8, {
    width: { emojiWidth: 2 },
});
// 'Hello 👋…'
```

### Truncation Options [#truncation-options]

```typescript
import type { TruncateOptions } from "@visulima/string";

interface TruncateOptions {
    // String to append when truncation occurs
    ellipsis?: string; // default: ''

    // Width of the ellipsis (auto-calculated if not provided)
    ellipsisWidth?: number;

    // Position to truncate
    position?: "end" | "middle" | "start"; // default: 'end'

    // Truncate at whitespace if within 3 characters
    preferTruncationOnSpace?: boolean; // default: false

    // Width calculation options
    width?: StringWidthOptions;
}
```

## Word Wrapping [#word-wrapping]

The `wordWrap` function provides flexible text wrapping with multiple modes and Unicode support.

### Basic Wrapping [#basic-wrapping]

```typescript
import { wordWrap, WrapMode } from "@visulima/string";

// Default: 80 character width, preserve words
const wrapped = wordWrap("This is a long text that will be wrapped to fit within the specified width limit.");

// Custom width
wordWrap("Long text here...", { width: 40 });
```

### Wrapping Modes [#wrapping-modes]

```typescript
// Preserve words (default) - keeps words intact
wordWrap("Long words will stay intact but may exceed width", {
    width: 20,
    wrapMode: WrapMode.PRESERVE_WORDS,
});

// Break at characters - breaks words to fit width exactly
wordWrap("Words will be broken at character boundaries", {
    width: 20,
    wrapMode: WrapMode.BREAK_AT_CHARACTERS,
});

// Strict width - forces strict adherence to width
wordWrap("Text will be broken exactly at width limit", {
    width: 20,
    wrapMode: WrapMode.STRICT_WIDTH,
});
```

### With ANSI Color Codes [#with-ansi-color-codes]

```typescript
const coloredText = "\x1b[31mThis red text\x1b[0m will be wrapped";
const wrapped = wordWrap(coloredText, { width: 20 });
// Color codes preserved across line breaks
```

### Additional Options [#additional-options]

```typescript
wordWrap("Text with zero-width characters", {
    width: 30,
    trim: false, // Don't trim whitespace (default: true)
    removeZeroWidthCharacters: false, // Keep zero-width chars (default: true)
});
```

## Text Alignment [#text-alignment]

The `alignText` function aligns text with support for multi-line strings and ANSI codes.

### Basic Alignment [#basic-alignment]

```typescript
import { alignText } from "@visulima/string";

const text = "First line\nSecond, much longer line";

// Right alignment
alignText(text, { align: "right" });
// "          First line\nSecond, much longer line"

// Center alignment
alignText(text, { align: "center" });
// "     First line     \nSecond, much longer line"

// Left alignment (default)
alignText(text, { align: "left" });
```

### Array of Strings [#array-of-strings]

```typescript
const lines = ["Short", "Medium length", "A very long line"];

const aligned = alignText(lines, { align: "center" });
// Returns array with each line centered based on longest line
```

### Custom Options [#custom-options]

```typescript
alignText("Line1*Line2*Line3", {
    align: "center",
    split: "*", // Custom line separator
    pad: "-", // Custom padding character
    stringWidthOptions: {
        emojiWidth: 2, // Handle emoji width correctly
    },
});
```

### Alignment Options [#alignment-options]

```typescript
import type { AlignTextOptions } from "@visulima/string";

interface AlignTextOptions {
    // Alignment direction
    align?: "center" | "left" | "right"; // default: 'center'

    // Padding character
    pad?: string; // default: ' '

    // Line separator
    split?: string; // default: '\n'

    // String width calculation options
    stringWidthOptions?: StringWidthOptions;
}
```

## Text Indentation [#text-indentation]

Utilities for adding, removing, and normalizing indentation in strings.

### Indent [#indent]

Add indentation to each line in a string.

```typescript
import { indent } from "@visulima/string";

// Default: 1 space
indent("Unicorns\nRainbows"); // ' Unicorns\n Rainbows'

// 4 spaces
indent("Unicorns\nRainbows", 4); // '    Unicorns\n    Rainbows'

// Custom character
indent("Unicorns\nRainbows", 1, { indent: "♥" }); // '♥Unicorns\n♥Rainbows'

// Include empty lines
indent("Unicorns\n\nRainbows", 1, { includeEmptyLines: true });
// ' Unicorns\n \n Rainbows'
```

### Strip Indent [#strip-indent]

Remove common leading whitespace from all lines.

```typescript
import { stripIndent } from "@visulima/string";

stripIndent("\n\tunicorn\n\t\tdog\n");
// '\nunicorn\n\tdog\n'

stripIndent("\n  unicorn\n    dog\n");
// '\nunicorn\n  dog\n'
```

### Dedent [#dedent]

Strip common indentation and trim leading/trailing blank lines.

```typescript
import { dedent } from "@visulima/string";

dedent("\n\tunicorn\n\t\tdog\n");
// 'unicorn\n\tdog'

dedent("\n  unicorn\n    dog\n");
// 'unicorn\n  dog'
```

### Redent [#redent]

Strip redundant indentation and re-indent with a given count.

```typescript
import { redent } from "@visulima/string";

redent("\n  foo\n    bar\n", 1);
// '\n foo\n   bar\n'

redent("\n foo\n  bar\n", 5, { indent: "-" });
// '\n-----foo\n------bar\n'
```

## Indentation Removal (Outdent) [#indentation-removal-outdent]

The `outdent` function removes leading indentation while preserving relative indentation.

### Basic Usage [#basic-usage]

```typescript
import { outdent } from "@visulima/string";

// Template literal
const text = outdent`
  This text will have indentation removed
  while preserving relative indentation.
    This line stays indented.
`;
// Output:
// This text will have indentation removed
// while preserving relative indentation.
//   This line stays indented.

// String input
const result = outdent.string(`
  Hello
  World
`);
// "Hello\nWorld"
```

### With Interpolation [#with-interpolation]

```typescript
const name = "World";
const greeting = outdent`
  Hello ${name}!
  Welcome to outdent.
`;
// "Hello World!\nWelcome to outdent."
```

### Custom Options [#custom-options-1]

```typescript
const customOutdent = outdent({
    trimLeadingNewline: false, // Keep leading newline
    trimTrailingNewline: false, // Keep trailing newline
    newline: "\r\n", // Normalize to CRLF
    cache: true, // Enable caching (default)
});

customOutdent`
  Indented text
`;
```

### Performance with Caching [#performance-with-caching]

```typescript
// Default behavior - caching enabled
const dedent = outdent();

// Disable caching if memory is a concern
const noCacheDedent = outdent({ cache: false });

// Custom cache store
const customCache = new WeakMap();
const customCacheDedent = outdent({ cacheStore: customCache });
```

## HTML Excerpt [#html-excerpt]

The `excerpt` function strips HTML tags and truncates text to a specified character limit. It's perfect for creating preview text from HTML content.

### Basic Usage [#basic-usage-1]

```typescript
import { excerpt } from "@visulima/string";

// Strip HTML and truncate
excerpt("<p>Hello <strong>world</strong>!</p>", 10);
// 'Hello wor…'

excerpt("<div>This is a <em>long</em> text</div>", 20);
// 'This is a long text'
```

### With Custom Ellipsis [#with-custom-ellipsis]

```typescript
excerpt("<p>Hello world</p>", 5, { ellipsis: "..." });
// 'He...'

excerpt("<div>Long text here</div>", 10, { ellipsis: " →" });
// 'Long te →'
```

### Handling HTML Entities [#handling-html-entities]

```typescript
// HTML entities are decoded
excerpt("Hello&nbsp;world", 11);
// 'Hello\u00A0world' (non-breaking space)

excerpt("A &amp; B", 5);
// 'A & B'

// Note: &lt;tag&gt; decodes to <tag>, which is then stripped as HTML
excerpt("&lt;tag&gt;", 7);
// '' (empty string)
```

### Edge Cases [#edge-cases]

```typescript
// Empty or zero limit
excerpt("<p>Hello</p>", 0);
// ''

excerpt("", 10);
// ''

// Nested HTML tags
excerpt("<div><p><strong>Nested</strong> content</p></div>", 15);
// 'Nested content'

// Tags with attributes
excerpt('<p class="test">Content</p>', 7);
// 'Content'

// Malformed HTML
excerpt("<p>Unclosed tag", 13);
// 'Unclosed tag'
```

### Excerpt Options [#excerpt-options]

```typescript
import type { ExcerptOptions } from "@visulima/string";

interface ExcerptOptions {
    // String to append when truncation occurs
    ellipsis?: string; // default: '…'

    // All other TruncateOptions except 'position' (always 'end')
    // See TruncateOptions for full details
}
```

## String Slicing [#string-slicing]

Unicode-aware string slicing that handles ANSI codes, emojis, and multi-byte characters.

### Basic Slicing [#basic-slicing]

```typescript
import { slice } from "@visulima/string";

slice("hello world", 0, 5); // 'hello'
slice("hello world", 6); // 'world'
slice("hello world", -5); // 'world'
```

### With Unicode Characters [#with-unicode-characters-1]

```typescript
// Handles emoji correctly
slice("Hello 👋 World", 0, 7); // 'Hello 👋'

// CJK characters
slice("こんにちは", 0, 3); // 'こんに'
```

### With ANSI Codes [#with-ansi-codes]

```typescript
const colored = "\x1b[31mRed Text\x1b[0m";
slice(colored, 0, 3);
// '\x1b[31mRed\x1b[0m' (preserves color codes)
```

## String Replacement with Ignore Ranges [#string-replacement-with-ignore-ranges]

Advanced string replacement with support for ignored regions.

### Basic Replacement [#basic-replacement]

```typescript
import { replaceString } from "@visulima/string";
import type { OptionReplaceArray, IntervalArray } from "@visulima/string";

const source = "Replace AB and CD";
const searches: OptionReplaceArray = [
    ["AB", "ab"],
    ["CD", "cd"],
];

replaceString(source, searches, []);
// "Replace ab and cd"
```

### With Ignore Ranges [#with-ignore-ranges]

```typescript
const source = "Replace AB and ignore CD";
const searches: OptionReplaceArray = [
    ["AB", "ab"],
    ["CD", "cd"],
];

// Ignore indices 19-22 (the word "ignore")
const ignoreRanges: IntervalArray = [[19, 22]];

replaceString(source, searches, ignoreRanges);
// "Replace ab and ignore CD"
```

### With Regular Expressions [#with-regular-expressions]

```typescript
const source = "Hello World";
const searches: OptionReplaceArray = [[/(\w+)\s+(\w+)/, "$2, $1"]];

replaceString(source, searches, []);
// "World, Hello"
```

### Overlapping Matches [#overlapping-matches]

```typescript
// Longer match takes precedence
const source = "abcde";
const searches: OptionReplaceArray = [
    ["abc", "123"],
    ["abcde", "54321"], // This wins
];

replaceString(source, searches, []);
// "54321"
```

## String Width Calculation [#string-width-calculation]

Accurate visual width calculation with Unicode support.

### Basic Width Calculation [#basic-width-calculation]

```typescript
import { getStringWidth } from "@visulima/string";

getStringWidth("hello"); // 5
getStringWidth("👋 hello"); // 7 (emoji is width 2)
getStringWidth("あいう"); // 6 (each char is width 2)
```

### With ANSI Codes [#with-ansi-codes-1]

```typescript
// ANSI codes ignored by default
getStringWidth("\x1b[31mRed\x1b[39m"); // 3

// Include ANSI codes in width
getStringWidth("\x1b[31mRed\x1b[39m", {
    countAnsiEscapeCodes: true,
}); // 11
```

### Custom Width Options [#custom-width-options]

```typescript
getStringWidth("hello", {
    regularWidth: 2, // Each regular char = 2
}); // 10

getStringWidth("你好", {
    fullWidth: 3, // CJK chars = 3 instead of 2
}); // 6
```

### Width with Truncation [#width-with-truncation]

```typescript
import { getStringTruncatedWidth } from "@visulima/string";

getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "...",
});
// { width: 8, truncated: true, ellipsed: true, index: 5 }
```

## Utility Functions [#utility-functions]

### countOccurrences [#countoccurrences]

Counts occurrences of a substring in a string. Handles Unicode characters correctly and prevents infinite loops.

```typescript
import { countOccurrences } from "@visulima/string";

// Basic usage
countOccurrences("foo", "o"); // 2
countOccurrences("fo fooo fo", "o"); // 5

// Unicode support
countOccurrences("a🤔b🤔c", "🤔"); // 2

// Empty string handling
countOccurrences("", "f"); // 0

// Throws error for empty substring
countOccurrences("test", ""); // TypeError: Expected non-empty substring
```

### direction [#direction]

Detects the direction of text: left-to-right, right-to-left, or neutral. Uses Unicode character ranges to identify RTL and LTR scripts.

```typescript
import { direction } from "@visulima/string";

// Left-to-right languages
direction("english"); // 'ltr'
direction("Hello World"); // 'ltr'
direction("Français"); // 'ltr'

// Right-to-left languages
direction("الجملة"); // 'rtl' (Arabic)
direction("נ"); // 'rtl' (Hebrew)
direction("الانجليزية"); // 'rtl'

// Neutral (numbers, symbols, empty)
direction("123"); // 'neutral'
direction("!@#"); // 'neutral'
direction(""); // 'neutral'
direction(" "); // 'neutral'
```

### escapeRegExp [#escaperegexp]

Escapes special regex characters for safe use in regular expressions.

```typescript
import { escapeRegExp } from "@visulima/string";

escapeRegExp("hello.world"); // 'hello\\.world'
escapeRegExp("(test)"); // '\\(test\\)'
escapeRegExp("$100"); // '\\$100'
```

### findStringOccurrences [#findstringoccurrences]

Finds all occurrences of multiple substrings and returns their positions.

```typescript
import { findStringOccurrences } from "@visulima/string";

findStringOccurrences("hello world hello", ["hello", "world"]);
// [[0, 4], [6, 10], [12, 16]]

findStringOccurrences("abc def abc", ["abc"]);
// [[0, 2], [8, 10]]
```

### hasChinese [#haschinese]

Checks if a string contains Chinese characters.

```typescript
import { hasChinese } from "@visulima/string";

hasChinese("你好"); // true
hasChinese("hello"); // false
hasChinese("hello 世界"); // true
```

### hasPunctuationOrSpace [#haspunctuationorspace]

Checks if a string contains punctuation or space characters.

```typescript
import { hasPunctuationOrSpace } from "@visulima/string";

hasPunctuationOrSpace("hello world"); // true
hasPunctuationOrSpace("hello,world"); // true
hasPunctuationOrSpace("helloworld"); // false
```

### inRange [#inrange]

Checks if a number falls within any of the specified intervals.

```typescript
import { inRange } from "@visulima/string";

inRange(5, [
    [0, 10],
    [20, 30],
]); // true (5 is in [0, 10])
inRange(15, [
    [0, 10],
    [20, 30],
]); // false
inRange(25, [
    [0, 10],
    [20, 30],
]); // true (25 is in [20, 30])
```

## Next Steps [#next-steps]

* [Slugification](/docs/packages/string/slugification) - Create URL-friendly slugs
* [String Width](/docs/packages/string/string-width) - Detailed width calculation
* [API Reference](/docs/packages/string/api) - Complete API documentation


# String Similarity (/docs/packages/string/string-similarity)



# String Similarity [#string-similarity]

Compare strings and find the closest matches using Levenshtein distance and similarity algorithms.

## Levenshtein Distance [#levenshtein-distance]

The Levenshtein distance measures the minimum number of single-character edits required to change one string into another.

### Basic Distance Calculation [#basic-distance-calculation]

```typescript
import { distance } from "@visulima/string";

// Identical strings
distance("hello", "hello"); // 0

// One character difference
distance("hello", "hallo"); // 1
distance("hello", "hullo"); // 1

// Multiple differences
distance("hello", "world"); // 4
distance("kitten", "sitting"); // 3

// Different lengths
distance("hello", "hello world"); // 6
distance("", "hello"); // 5
```

### Find Closest String [#find-closest-string]

Find the closest matching string from a list:

```typescript
import { closest } from "@visulima/string";

const options = ["apple", "apricot", "banana", "orange"];

closest("aple", options); // 'apple'
closest("banan", options); // 'banana'
closest("ornge", options); // 'orange'
```

### Find Multiple Closest Matches [#find-multiple-closest-matches]

Get the N closest matches:

```typescript
import { closestN } from "@visulima/string";

const options = ["apple", "apricot", "application", "apply"];

// Get 2 closest matches
closestN("app", options, 2);
// ['apple', 'apply']

// Get 3 closest matches
closestN("appl", options, 3);
// ['apple', 'apply', 'application']
```

## Closest String with Options [#closest-string-with-options]

The `closestString` function provides more control over finding similar strings.

### Basic Usage [#basic-usage]

```typescript
import { closestString } from "@visulima/string";

const options = ["react", "redux", "angular", "vue"];

closestString("reakt", options);
// { value: 'react', distance: 1, similarity: 0.8 }

closestString("anglar", options);
// { value: 'angular', distance: 1, similarity: 0.857 }
```

### Case-Insensitive Matching [#case-insensitive-matching]

```typescript
closestString("REACT", options, {
    caseSensitive: false,
});
// { value: 'react', distance: 0, similarity: 1.0 }

// Case-sensitive (default)
closestString("REACT", options, {
    caseSensitive: true,
});
// Higher distance due to case differences
```

### Threshold Filtering [#threshold-filtering]

```typescript
// Only return matches within threshold
closestString("xyz", options, {
    threshold: 0.5, // Minimum 50% similarity
});
// null (no match meets threshold)

closestString("reactt", options, {
    threshold: 0.7, // Minimum 70% similarity
});
// { value: 'react', distance: 1, similarity: 0.833 }
```

### Complete Options [#complete-options]

```typescript
import type { ClosestStringOptions } from "@visulima/string";

interface ClosestStringOptions {
    // Case-sensitive comparison (default: true)
    caseSensitive?: boolean;

    // Minimum similarity threshold (0-1, default: 0)
    threshold?: number;
}
```

## Compare Similarity [#compare-similarity]

Compare two strings and get detailed similarity metrics.

### Basic Comparison [#basic-comparison]

```typescript
import { compareSimilarity } from "@visulima/string";

compareSimilarity("hello", "hello");
// { distance: 0, similarity: 1.0, equal: true }

compareSimilarity("hello", "hallo");
// { distance: 1, similarity: 0.8, equal: false }

compareSimilarity("kitten", "sitting");
// { distance: 3, similarity: 0.571, equal: false }
```

### With Options [#with-options]

```typescript
// Case-insensitive comparison
compareSimilarity("Hello", "hello", {
    caseSensitive: false,
});
// { distance: 0, similarity: 1.0, equal: true }

// Case-sensitive (default)
compareSimilarity("Hello", "hello", {
    caseSensitive: true,
});
// { distance: 1, similarity: 0.8, equal: false }
```

### Similarity Score [#similarity-score]

The similarity score is calculated as:

```
similarity = 1 - (distance / maxLength)
```

Where `maxLength` is the length of the longer string.

```typescript
compareSimilarity("cat", "cats");
// distance: 1
// maxLength: 4
// similarity: 1 - (1/4) = 0.75

compareSimilarity("hello", "world");
// distance: 4
// maxLength: 5
// similarity: 1 - (4/5) = 0.2
```

## Word Similarity Sort [#word-similarity-sort]

Sort an array of strings by their similarity to a target string.

### Basic Sorting [#basic-sorting]

```typescript
import { wordSimilaritySort } from "@visulima/string";

const words = ["apple", "apricot", "banana", "application"];

wordSimilaritySort("app", words);
// ['apple', 'application', 'apricot', 'banana']

wordSimilaritySort("ban", words);
// ['banana', 'apple', 'apricot', 'application']
```

### Case-Insensitive Sorting [#case-insensitive-sorting]

```typescript
const words = ["Apple", "APRICOT", "Banana", "APPLICATION"];

wordSimilaritySort("app", words, {
    caseSensitive: false,
});
// ['Apple', 'APPLICATION', 'APRICOT', 'Banana']
```

### With Threshold [#with-threshold]

```typescript
const words = ["apple", "apricot", "banana", "application"];

// Only include words with 60% or higher similarity
wordSimilaritySort("app", words, {
    threshold: 0.6,
});
// ['apple', 'application']
// 'apricot' and 'banana' excluded due to low similarity
```

### Complete Options [#complete-options-1]

```typescript
import type { WordSimilaritySortOptions } from "@visulima/string";

interface WordSimilaritySortOptions {
    // Case-sensitive comparison (default: true)
    caseSensitive?: boolean;

    // Minimum similarity threshold (0-1, default: 0)
    threshold?: number;
}
```

## Use Cases [#use-cases]

### Command Suggestion [#command-suggestion]

```typescript
const commands = ["start", "stop", "restart", "status", "install"];
const userInput = "strt";

const suggestion = closest(userInput, commands);
console.log(`Did you mean: ${suggestion}?`);
// "Did you mean: start?"
```

### Typo Correction [#typo-correction]

```typescript
const dictionary = ["hello", "world", "javascript", "typescript"];

function correctTypo(word: string): string {
    const match = closestString(word, dictionary, {
        caseSensitive: false,
        threshold: 0.6, // At least 60% similar
    });

    return match ? match.value : word;
}

correctTypo("javascrip"); // 'javascript'
correctTypo("typscript"); // 'typescript'
correctTypo("xyz"); // 'xyz' (no match)
```

### Search with Fuzzy Matching [#search-with-fuzzy-matching]

```typescript
const products = ["iPhone 15 Pro", "Samsung Galaxy S24", "Google Pixel 8", "OnePlus 12"];

function searchProducts(query: string) {
    return wordSimilaritySort(query, products, {
        caseSensitive: false,
        threshold: 0.3,
    });
}

searchProducts("iphone");
// ['iPhone 15 Pro', ...]

searchProducts("galaxy");
// ['Samsung Galaxy S24', ...]
```

### Duplicate Detection [#duplicate-detection]

```typescript
const names = ["John Doe", "Jane Smith", "Jon Doe", "John Do"];

function findDuplicates(threshold: number = 0.8) {
    const duplicates: Array<[string, string, number]> = [];

    for (let i = 0; i < names.length; i++) {
        for (let j = i + 1; j < names.length; j++) {
            const result = compareSimilarity(names[i], names[j], {
                caseSensitive: false,
            });

            if (result.similarity >= threshold) {
                duplicates.push([names[i], names[j], result.similarity]);
            }
        }
    }

    return duplicates;
}

findDuplicates();
// [['John Doe', 'Jon Doe', 0.875], ['John Doe', 'John Do', 0.875]]
```

### Autocomplete Suggestions [#autocomplete-suggestions]

```typescript
const suggestions = ["javascript", "typescript", "java", "python", "ruby", "rust"];

function autocomplete(partial: string, maxResults: number = 5) {
    const sorted = wordSimilaritySort(partial, suggestions, {
        caseSensitive: false,
    });

    return sorted.slice(0, maxResults);
}

autocomplete("java");
// ['java', 'javascript']

autocomplete("type");
// ['typescript', ...]
```

### Spell Checker [#spell-checker]

```typescript
const dictionary = new Set(["hello", "world", "computer", "program", "algorithm"]);

function spellCheck(word: string) {
    // Check if word exists
    if (dictionary.has(word.toLowerCase())) {
        return { correct: true, suggestions: [] };
    }

    // Find suggestions
    const suggestions = closestN(word, Array.from(dictionary), 3);

    return {
        correct: false,
        suggestions,
    };
}

spellCheck("algorythm");
// { correct: false, suggestions: ['algorithm', ...] }
```

### Git-like Command Suggestions [#git-like-command-suggestions]

```typescript
const gitCommands = ["add", "commit", "push", "pull", "clone", "checkout", "branch", "merge", "rebase", "status"];

function suggestCommand(input: string) {
    const match = closestString(input, gitCommands, {
        threshold: 0.5,
    });

    if (!match) {
        return `Unknown command: ${input}`;
    }

    if (match.distance === 0) {
        return `Executing: git ${input}`;
    }

    return `Did you mean: git ${match.value}?`;
}

suggestCommand("comit");
// "Did you mean: git commit?"

suggestCommand("pul");
// "Did you mean: git pull?"
```

## Performance Considerations [#performance-considerations]

1. Levenshtein distance calculation is O(m × n) where m and n are string lengths
2. For large datasets, consider pre-filtering by string length
3. Use threshold to limit comparisons
4. Cache results for frequently compared strings

## Best Practices [#best-practices]

1. Use case-insensitive comparison for user input
2. Set appropriate threshold values (0.6-0.8 typically works well)
3. Limit the number of suggestions returned
4. Consider normalizing strings (trim, lowercase) before comparison
5. For very large datasets, consider indexing or alternative algorithms

## Next Steps [#next-steps]

* [Testing](/docs/packages/string/testing) - Test utilities for string comparisons
* [API Reference](/docs/packages/string/api/similarity) - Complete similarity API
* [Case Conversion](/docs/packages/string/case-conversion) - Normalize string case


# String Width (/docs/packages/string/string-width)



# String Width [#string-width]

Accurate visual width calculation for strings containing Unicode characters, ANSI escape codes, emojis, and more.

## Basic Width Calculation [#basic-width-calculation]

The `getStringWidth` function calculates the visual width of strings for terminal and display purposes.

### Simple Examples [#simple-examples]

```typescript
import { getStringWidth } from "@visulima/string";

// Regular ASCII
getStringWidth("hello"); // 5
getStringWidth("hello world"); // 11

// Empty string
getStringWidth(""); // 0

// Numbers and symbols
getStringWidth("12345"); // 5
getStringWidth("!@#$%"); // 5
```

### Unicode Characters [#unicode-characters]

```typescript
// Full-width CJK characters (width 2)
getStringWidth("あいう"); // 6
getStringWidth("こんにちは"); // 10
getStringWidth("你好"); // 4
getStringWidth("안녕"); // 4

// Mixed ASCII and CJK
getStringWidth("Hello 世界"); // 9 (5 + 4)
```

### Emoji Support [#emoji-support]

```typescript
// Single emoji (width 2)
getStringWidth("👋"); // 2
getStringWidth("🎉"); // 2

// Multiple emojis
getStringWidth("👋🎉🎂"); // 6

// Text with emojis
getStringWidth("Hello 👋 World"); // 13 (5 + 2 + 1 + 5)

// Complex emoji sequences
getStringWidth("👨‍👩‍👧‍👦"); // 2 (family emoji with ZWJ)
```

### ANSI Escape Codes [#ansi-escape-codes]

```typescript
// ANSI codes ignored by default
getStringWidth("\x1b[31mRed\x1b[39m"); // 3

// Bold text
getStringWidth("\x1b[1mBold\x1b[22m"); // 4

// Multiple colors
const colored = "\x1b[31mRed\x1b[0m and \x1b[32mGreen\x1b[0m";
getStringWidth(colored); // 13 ('Red and Green')

// Include ANSI codes in width
getStringWidth("\x1b[31mRed\x1b[39m", {
    countAnsiEscapeCodes: true,
}); // 11
```

### Special Characters [#special-characters]

```typescript
// Tab characters (default width 8)
getStringWidth("\t"); // 8
getStringWidth("a\tb"); // 10 (1 + 8 + 1)

// Zero-width characters
getStringWidth("a\u200Bb"); // 2 (zero-width space ignored)

// Control characters
getStringWidth("\x00\x01"); // 0 (control chars have width 0)

// Combining marks
getStringWidth("e\u0301"); // 1 (é with combining acute accent)
```

## Width Options [#width-options]

### Custom Character Widths [#custom-character-widths]

```typescript
import type { StringWidthOptions } from "@visulima/string";

// Regular characters
getStringWidth("hello", {
    regularWidth: 2,
}); // 10 (each char = 2)

// Full-width characters
getStringWidth("你好", {
    fullWidth: 3,
}); // 6 (each char = 3 instead of 2)

// Emoji width
getStringWidth("👋👋", {
    emojiWidth: 1,
}); // 2 (each emoji = 1 instead of 2)

// Wide characters
getStringWidth("ｆｕｌｌｗｉｄｔｈ", {
    wideWidth: 3,
}); // custom width
```

### Tab Width [#tab-width]

```typescript
// Default tab width is 8
getStringWidth("\t"); // 8

// Custom tab width
getStringWidth("\t", {
    tabWidth: 4,
}); // 4

getStringWidth("a\tb\tc", {
    tabWidth: 2,
}); // 7 (1 + 2 + 1 + 2 + 1)
```

### Ambiguous Characters [#ambiguous-characters]

```typescript
// Some characters have ambiguous width
// Default: treated as narrow (width 1)
getStringWidth("±§"); // 2

// Treat ambiguous as wide (width 2)
getStringWidth("±§", {
    ambiguousIsNarrow: false,
}); // 4
```

### Control Characters [#control-characters]

```typescript
// Control characters default to width 0
getStringWidth("\x00\x01\x02"); // 0

// Custom control character width
getStringWidth("\x00\x01", {
    controlWidth: 1,
}); // 2
```

### Complete Options [#complete-options]

```typescript
interface StringWidthOptions {
    // Treat ambiguous-width characters as narrow
    ambiguousIsNarrow?: boolean; // default: true

    // Width of ANSI escape sequences
    ansiWidth?: number; // default: 0

    // Width of control characters
    controlWidth?: number; // default: 0

    // Include ANSI codes in width calculation
    countAnsiEscapeCodes?: boolean; // default: false

    // Width of emoji characters
    emojiWidth?: number; // default: 2

    // Width of full-width characters
    fullWidth?: number; // default: 2

    // Width of regular characters
    regularWidth?: number; // default: 1

    // Width of tab characters
    tabWidth?: number; // default: 8

    // Width of wide characters
    wideWidth?: number; // default: 2
}
```

## Width with Truncation [#width-with-truncation]

The `getStringTruncatedWidth` function combines width calculation with truncation support.

### Basic Truncation [#basic-truncation]

```typescript
import { getStringTruncatedWidth } from "@visulima/string";

getStringTruncatedWidth("hello world", {
    limit: 8,
});
// { width: 8, truncated: true, ellipsed: false, index: 8 }

getStringTruncatedWidth("hello", {
    limit: 10,
});
// { width: 5, truncated: false, ellipsed: false, index: 5 }
```

### With Ellipsis [#with-ellipsis]

```typescript
getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "...",
});
// { width: 8, truncated: true, ellipsed: true, index: 5 }
// String would be truncated at index 5 to fit "he..." in 8 width

getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "…",
});
// { width: 8, truncated: true, ellipsed: true, index: 7 }
```

### With Unicode [#with-unicode]

```typescript
// CJK characters
getStringTruncatedWidth("あいうえお", {
    limit: 6,
    ellipsis: "...",
    fullWidth: 2,
});
// { width: 6, truncated: true, ellipsed: true, index: 2 }
// Truncated at character 2: "あい..."

// Emojis
getStringTruncatedWidth("👋👋👋👋", {
    limit: 5,
    ellipsis: "...",
    emojiWidth: 2,
});
// { width: 5, truncated: true, ellipsed: true, index: 1 }
```

### With ANSI Codes [#with-ansi-codes]

```typescript
const colored = "\x1b[31mRed Text\x1b[39m";

getStringTruncatedWidth(colored, {
    limit: 5,
    ellipsis: "...",
});
// Width calculated without ANSI codes
// { width: 5, truncated: true, ellipsed: true, index: ... }

getStringTruncatedWidth(colored, {
    limit: 15,
    ellipsis: "...",
    countAnsiEscapeCodes: true,
});
// Width includes ANSI codes
```

### Custom Ellipsis Width [#custom-ellipsis-width]

```typescript
// Auto-calculated ellipsis width
getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "...",
});
// Ellipsis width calculated automatically

// Explicit ellipsis width
getStringTruncatedWidth("hello world", {
    limit: 8,
    ellipsis: "…",
    ellipsisWidth: 1,
});
// Use specified width for ellipsis
```

### Result Interface [#result-interface]

```typescript
interface StringTruncatedWidthResult {
    // The calculated visual width
    width: number;

    // Whether the string was truncated
    truncated: boolean;

    // Whether an ellipsis was added
    ellipsed: boolean;

    // The index at which truncation occurred
    index: number;
}
```

### Complete Options [#complete-options-1]

```typescript
interface StringTruncatedWidthOptions extends StringWidthOptions {
    // String to append when truncation occurs
    ellipsis?: string; // default: ''

    // Width of ellipsis (auto-calculated if not provided)
    ellipsisWidth?: number;

    // Maximum width limit for the string
    limit?: number; // default: Infinity
}
```

## Character Width Utilities [#character-width-utilities]

### isFullwidthCodePoint [#isfullwidthcodepoint]

Check if a code point is a fullwidth or wide character.

```typescript
import { isFullwidthCodePoint } from "@visulima/string";

isFullwidthCodePoint("あ".codePointAt(0)); // true (Japanese)
isFullwidthCodePoint("谢".codePointAt(0)); // true (Chinese)
isFullwidthCodePoint("고".codePointAt(0)); // true (Korean)
isFullwidthCodePoint("a".codePointAt(0)); // false (ASCII)
isFullwidthCodePoint(Number.NaN); // false
```

### eastAsianWidth [#eastasianwidth]

Get the character width (1 or 2) for a Unicode code point based on East Asian Width.

```typescript
import { eastAsianWidth } from "@visulima/string";

eastAsianWidth("あ".codePointAt(0)); // 2 (fullwidth)
eastAsianWidth("a".codePointAt(0)); // 1 (narrow)

// With ambiguous option
eastAsianWidth("±".codePointAt(0), { ambiguousAsWide: true }); // 2
```

### eastAsianWidthType [#eastasianwidthtype]

Get the East Asian Width category for a code point.

```typescript
import { eastAsianWidthType } from "@visulima/string";

eastAsianWidthType("あ".codePointAt(0)); // 'wide'
eastAsianWidthType("Ａ".codePointAt(0)); // 'fullwidth'
eastAsianWidthType("a".codePointAt(0)); // 'narrow'
eastAsianWidthType("a".codePointAt(0)); // 'narrow'
// Returns: 'fullwidth' | 'halfwidth' | 'wide' | 'narrow' | 'neutral' | 'ambiguous'
```

## Use Cases [#use-cases]

### Terminal Output [#terminal-output]

```typescript
// Calculate width for terminal padding
const text = "Hello World";
const width = getStringWidth(text);
const padding = " ".repeat(80 - width);
console.log(text + padding + "|");
```

### Column Alignment [#column-alignment]

```typescript
const columns = ["Name", "Age", "都市"];
const widths = columns.map((col) => getStringWidth(col));
const maxWidth = Math.max(...widths);

// Pad each column to max width
const aligned = columns.map((col, i) => {
    const padding = " ".repeat(maxWidth - widths[i]);
    return col + padding;
});
```

### Progress Bars [#progress-bars]

```typescript
const progress = 0.6;
const barWidth = 50;
const filled = Math.floor(progress * barWidth);

const bar = "█".repeat(filled) + "░".repeat(barWidth - filled);
const width = getStringWidth(bar, { emojiWidth: 1 });
```

### Text Wrapping [#text-wrapping]

```typescript
const text = "A long string with 中文 and emojis 👋";
const maxWidth = 20;

let currentLine = "";
let currentWidth = 0;

for (const char of text) {
    const charWidth = getStringWidth(char);

    if (currentWidth + charWidth > maxWidth) {
        console.log(currentLine);
        currentLine = char;
        currentWidth = charWidth;
    } else {
        currentLine += char;
        currentWidth += charWidth;
    }
}
```

### Table Formatting [#table-formatting]

```typescript
const data = [
    ["Name", "Country", "City"],
    ["John", "USA", "New York"],
    ["田中", "日本", "東京"],
    ["Ahmed", "مصر", "Cairo"],
];

// Calculate max width for each column
const columnWidths = data[0].map((_, colIndex) => {
    return Math.max(...data.map((row) => getStringWidth(row[colIndex])));
});

// Format table
data.forEach((row) => {
    const formatted = row
        .map((cell, i) => {
            const width = getStringWidth(cell);
            const padding = " ".repeat(columnWidths[i] - width);
            return cell + padding;
        })
        .join(" | ");

    console.log(formatted);
});
```

## Best Practices [#best-practices]

1. Always use `getStringWidth` instead of `string.length` for visual width
2. Consider emoji width when calculating column widths
3. Account for ANSI codes in colored terminal output
4. Use `ambiguousIsNarrow: false` for East Asian applications
5. Test with various Unicode characters for international apps
6. Cache width calculations for frequently measured strings

## Performance Tips [#performance-tips]

1. Width calculation is relatively fast but avoid in tight loops
2. Cache results for static strings
3. Use `countAnsiEscapeCodes: false` (default) unless needed
4. Consider batching width calculations

## Next Steps [#next-steps]

* [String Manipulation](/docs/packages/string/string-manipulation) - Truncate and format strings
* [Text Alignment](/docs/packages/string/string-manipulation#text-alignment) - Align text based on width
* [API Reference](/docs/packages/string/api/width) - Complete width calculation API


# Testing Utilities (/docs/packages/string/testing)



# Testing Utilities [#testing-utilities]

@visulima/string provides specialized utilities for testing terminal output, ANSI colored strings, and formatted text.

## Vitest Integration [#vitest-integration]

Custom matchers for testing ANSI strings in Vitest.

### Setup [#setup]

```typescript
import { expect, describe, it } from "vitest";
import { toEqualAnsi } from "@visulima/string/test/vitest";

// Extend Vitest with custom matchers
expect.extend({ toEqualAnsi });
```

### Basic Usage [#basic-usage]

```typescript
import { red, green, blue } from "@visulima/colorize";

describe("colored output tests", () => {
    it("should match identical ANSI strings", () => {
        const actual = red("Error");
        const expected = red("Error");

        expect(actual).toEqualAnsi(expected);
    });

    it("should fail on different colors", () => {
        const actual = red("Error");
        const expected = blue("Error");

        // This will fail with detailed comparison
        expect(actual).toEqualAnsi(expected);
    });

    it("should match same text with different escape codes", () => {
        // Both produce red text but may use different codes
        const actual = "\x1b[31mError\x1b[39m";
        const expected = "\x1b[91mError\x1b[0m";

        // Compare only visible text
        expect(actual).toEqualAnsi(expected, { compareColors: false });
    });
});
```

### Error Messages [#error-messages]

When tests fail, `toEqualAnsi` provides detailed error messages:

```
Expected ANSI strings to match

Expected (visible): "Error message"
Actual (visible):   "Error message"

Expected (ANSI): "\x1b[31mError message\x1b[39m"
Actual (ANSI):   "\x1b[32mError message\x1b[39m"

Difference:
- Colors differ (red vs green)
- Same visible content
- Expected length: 22
- Actual length: 22
```

## ANSI String Formatting [#ansi-string-formatting]

Format ANSI strings for test output and debugging.

### Format ANSI String [#format-ansi-string]

```typescript
import { formatAnsiString } from "@visulima/string/test/utils";
import { red } from "@visulima/colorize";

const coloredText = red("Error message");
const formatted = formatAnsiString(coloredText);

console.log(formatted);
// {
//   ansi: "\x1b[31mError message\x1b[39m",
//   stripped: "Error message",
//   visible: "\\x1b[31mError message\\x1b[39m",
//   json: "\"\\u001b[31mError message\\u001b[39m\"",
//   lengthDifference: 9
// }
```

### Properties [#properties]

```typescript
interface FormattedAnsiString {
    // Original string with ANSI codes
    ansi: string;

    // String with ANSI codes removed
    stripped: string;

    // Escape codes shown as visible characters
    visible: string;

    // JSON stringified version
    json: string;

    // Difference between ANSI and stripped length
    lengthDifference: number;
}
```

### Usage in Tests [#usage-in-tests]

```typescript
import { formatAnsiString } from "@visulima/string/test/utils";

it("should format colored output correctly", () => {
    const output = getColoredOutput();
    const formatted = formatAnsiString(output);

    // Test visible content
    expect(formatted.stripped).toBe("Expected text");

    // Verify ANSI codes present
    expect(formatted.lengthDifference).toBeGreaterThan(0);
});
```

## Compare ANSI Strings [#compare-ansi-strings]

Detailed comparison between two ANSI strings.

### Basic Comparison [#basic-comparison]

```typescript
import { compareAnsiStrings } from "@visulima/string/test/utils";
import { red, blue } from "@visulima/colorize";

const string1 = red("Error");
const string2 = blue("Error");

const result = compareAnsiStrings(string1, string2);

console.log(result);
// {
//   ansiEqual: false,
//   strippedEqual: true,
//   summary: "Same text, different colors",
//   actual: { ansi: "...", stripped: "Error", ... },
//   expected: { ansi: "...", stripped: "Error", ... }
// }
```

### Comparison Result [#comparison-result]

```typescript
interface AnsiComparisonResult {
    // Whether ANSI strings are identical
    ansiEqual: boolean;

    // Whether visible content is the same
    strippedEqual: boolean;

    // Human-readable summary
    summary: string;

    // Formatted actual string
    actual: FormattedAnsiString;

    // Formatted expected string
    expected: FormattedAnsiString;
}
```

### Usage in Tests [#usage-in-tests-1]

```typescript
it("should compare ANSI strings", () => {
    const actual = getActualOutput();
    const expected = getExpectedOutput();

    const comparison = compareAnsiStrings(actual, expected);

    if (!comparison.strippedEqual) {
        console.log(comparison.summary);
        console.log("Actual:", comparison.actual.stripped);
        console.log("Expected:", comparison.expected.stripped);
    }
});
```

## Testing Patterns [#testing-patterns]

### Snapshot Testing [#snapshot-testing]

```typescript
import { formatAnsiString } from "@visulima/string/test/utils";

it("should match snapshot", () => {
    const output = generateColoredOutput();

    // Test with ANSI codes
    expect(output).toMatchSnapshot();

    // Test without ANSI codes
    const formatted = formatAnsiString(output);
    expect(formatted.stripped).toMatchSnapshot();
});
```

### Testing Color Consistency [#testing-color-consistency]

```typescript
describe("color consistency", () => {
    it("should use consistent colors for errors", () => {
        const error1 = formatError("First error");
        const error2 = formatError("Second error");

        const fmt1 = formatAnsiString(error1);
        const fmt2 = formatAnsiString(error2);

        // Compare ANSI codes pattern
        const ansiPattern1 = fmt1.ansi.replace(/[^\\x1b\[0-9;m]/g, "");
        const ansiPattern2 = fmt2.ansi.replace(/[^\\x1b\[0-9;m]/g, "");

        expect(ansiPattern1).toBe(ansiPattern2);
    });
});
```

### Testing Multi-line Output [#testing-multi-line-output]

```typescript
it("should format multi-line output correctly", () => {
    const output = generateMultiLineOutput();
    const lines = output.split("\n");

    lines.forEach((line) => {
        const formatted = formatAnsiString(line);

        // Each line should have balanced ANSI codes
        expect(formatted.ansi).toMatch(/^\x1b\[[0-9;]+m.*\x1b\[0m$/);
    });
});
```

### Testing Terminal Width [#testing-terminal-width]

```typescript
import { getStringWidth } from "@visulima/string";
import { formatAnsiString } from "@visulima/string/test/utils";

it("should fit within terminal width", () => {
    const output = generateOutput();
    const maxWidth = 80;

    const formatted = formatAnsiString(output);
    const width = getStringWidth(formatted.stripped);

    expect(width).toBeLessThanOrEqual(maxWidth);
});
```

### Testing Error Messages [#testing-error-messages]

```typescript
describe("error formatting", () => {
    it("should format error messages correctly", () => {
        const error = new Error("Test error");
        const formatted = formatErrorMessage(error);

        expect(formatted).toEqualAnsi(red("Error: ") + "Test error");
    });

    it("should include stack trace with colors", () => {
        const error = new Error("Test error");
        const formatted = formatErrorWithStack(error);

        const fmt = formatAnsiString(formatted);

        expect(fmt.stripped).toContain("Error: Test error");
        expect(fmt.stripped).toContain("at ");
        expect(fmt.lengthDifference).toBeGreaterThan(0);
    });
});
```

### Testing Progress Bars [#testing-progress-bars]

```typescript
import { getStringWidth } from "@visulima/string";

describe("progress bar", () => {
    it("should maintain consistent width", () => {
        const bar1 = createProgressBar(0.0);
        const bar2 = createProgressBar(0.5);
        const bar3 = createProgressBar(1.0);

        const width1 = getStringWidth(formatAnsiString(bar1).stripped);
        const width2 = getStringWidth(formatAnsiString(bar2).stripped);
        const width3 = getStringWidth(formatAnsiString(bar3).stripped);

        expect(width1).toBe(width2);
        expect(width2).toBe(width3);
    });
});
```

### Testing Color Schemes [#testing-color-schemes]

```typescript
describe("color scheme", () => {
    it("should apply consistent colors", () => {
        const scheme = {
            error: red,
            warning: yellow,
            success: green,
            info: blue,
        };

        const messages = {
            error: scheme.error("Error message"),
            warning: scheme.warning("Warning message"),
            success: scheme.success("Success message"),
            info: scheme.info("Info message"),
        };

        // Each should have different ANSI codes
        const formatted = Object.entries(messages).map(([key, msg]) => ({
            type: key,
            formatted: formatAnsiString(msg),
        }));

        const ansiCodes = formatted.map((f) => f.formatted.ansi);
        const uniqueCodes = new Set(ansiCodes);

        expect(uniqueCodes.size).toBe(ansiCodes.length);
    });
});
```

## Best Practices [#best-practices]

1. Use `toEqualAnsi` for comparing colored output
2. Test both with and without ANSI codes
3. Verify visual width for terminal output
4. Use snapshots for complex formatted output
5. Test color consistency across similar messages
6. Verify ANSI codes are properly closed
7. Test with various terminal width constraints

## Common Testing Scenarios [#common-testing-scenarios]

### CLI Output [#cli-output]

```typescript
it("should format CLI output correctly", () => {
    const output = generateCLIOutput();

    const formatted = formatAnsiString(output);

    // Test visible content
    expect(formatted.stripped).toContain("Expected text");

    // Verify colors are applied
    expect(formatted.lengthDifference).toBeGreaterThan(0);

    // Check width
    const width = getStringWidth(formatted.stripped);
    expect(width).toBeLessThanOrEqual(80);
});
```

### Log Messages [#log-messages]

```typescript
it("should format log messages", () => {
    const log = createLogMessage("info", "Test message");

    expect(log).toEqualAnsi(blue("[INFO]") + " Test message");
});
```

### Table Output [#table-output]

```typescript
it("should format table correctly", () => {
    const table = generateTable();
    const lines = table.split("\n");

    lines.forEach((line) => {
        const formatted = formatAnsiString(line);
        const width = getStringWidth(formatted.stripped);

        // All lines should have same width
        expect(width).toBe(expectedWidth);
    });
});
```

## Next Steps [#next-steps]

* [String Width](/docs/packages/string/string-width) - Calculate visual width
* [String Manipulation](/docs/packages/string/string-manipulation) - Format strings
* [API Reference](/docs/packages/string/api/testing) - Complete testing API


# TypeScript Support (/docs/packages/string/typescript)



# TypeScript Support [#typescript-support]

@visulima/string is written in TypeScript and provides comprehensive type definitions with advanced type-level string manipulation.

## Type Definitions [#type-definitions]

The library exports all necessary types for type-safe string operations.

### Importing Types [#importing-types]

```typescript
import type { CaseOptions, TruncateOptions, StringWidthOptions, SlugifyOptions, OptionsTransliterate } from "@visulima/string";
```

### Case Conversion Types [#case-conversion-types]

```typescript
import type { CamelCase, PascalCase, SnakeCase, KebabCase, ConstantCase, DotCase, PathCase, TitleCase, SentenceCase } from "@visulima/string";

// Type-level case conversion
type Input = "hello-world";
type Camel = CamelCase<Input>; // 'helloWorld'
type Pascal = PascalCase<Input>; // 'HelloWorld'
type Snake = SnakeCase<Input>; // 'hello_world'
type Kebab = KebabCase<Input>; // 'hello-world'
type Constant = ConstantCase<Input>; // 'HELLO_WORLD'
```

### Using in Functions [#using-in-functions]

```typescript
import { camelCase } from "@visulima/string";
import type { CamelCase } from "@visulima/string";

function convertToCamel<T extends string>(input: T): CamelCase<T> {
    return camelCase(input) as CamelCase<T>;
}

const result = convertToCamel("hello-world");
// result type: 'helloWorld'
```

## Native String Type Extensions [#native-string-type-extensions]

Enhanced type definitions for native JavaScript string methods.

### Configuration [#configuration]

Add to your `tsconfig.json`:

```json title="tsconfig.json"
{
    "compilerOptions": {
        "types": ["@visulima/string/native-string-types"]
    }
}
```

Or use a triple-slash reference:

```typescript
/// <reference types="@visulima/string/native-string-types" />
```

### String Method Types [#string-method-types]

#### charAt [#charat]

```typescript
const str = "Hello";

// Type-safe character access
str.charAt<typeof str, 0>(); // type: 'H'
str.charAt<typeof str, 1>(); // type: 'e'
str.charAt<typeof str, 4>(); // type: 'o'
```

#### slice [#slice]

```typescript
const str = "Hello, World!";

str.slice<typeof str, 0, 5>(); // type: 'Hello'
str.slice<typeof str, 7, 12>(); // type: 'World'
str.slice<typeof str, -6>(); // type: 'World!'
```

#### split [#split]

```typescript
const str = "Hello, World!";

str.split<typeof str, ", ">(); // type: ['Hello', 'World!']
str.split<typeof str, " ">(); // type: ['Hello,', 'World!']
```

#### concat [#concat]

```typescript
const str = "Hello";

str.concat<typeof str, " World">(); // type: 'Hello World'
str.concat<typeof str, "!">(); // type: 'Hello!'
```

#### toLowerCase / toUpperCase [#tolowercase--touppercase]

```typescript
const str = "Hello, World!";

str.toLowerCase<typeof str>(); // type: 'hello, world!'
str.toUpperCase<typeof str>(); // type: 'HELLO, WORLD!'
```

#### startsWith / endsWith [#startswith--endswith]

```typescript
const str = "Hello, World!";

str.startsWith<typeof str, "Hello">(); // type: true
str.startsWith<typeof str, "World">(); // type: false
str.endsWith<typeof str, "World!">(); // type: true
str.endsWith<typeof str, "Hello">(); // type: false
```

#### includes [#includes]

```typescript
const str = "Hello, World!";

str.includes<typeof str, "World", 0>(); // type: true
str.includes<typeof str, "World", 10>(); // type: false
str.includes<typeof str, "xyz", 0>(); // type: false
```

#### padStart / padEnd [#padstart--padend]

```typescript
const str = "Hello";

str.padStart<typeof str, 10, "_">(); // type: '_____Hello'
str.padEnd<typeof str, 10, "_">(); // type: 'Hello_____'
```

#### trim / trimStart / trimEnd [#trim--trimstart--trimend]

```typescript
const str = "  hello  ";

str.trim<typeof str>(); // type: 'hello'
str.trimStart<typeof str>(); // type: 'hello  '
str.trimEnd<typeof str>(); // type: '  hello'
```

#### replace / replaceAll [#replace--replaceall]

```typescript
const str = "Hello World";

str.replace<typeof str, "World", "TypeScript">();
// type: 'Hello TypeScript'

str.replaceAll<typeof str, "l", "L">();
// type: 'HeLLo WorLd'
```

#### repeat [#repeat]

```typescript
const str = "abc";

str.repeat<typeof str, 3>(); // type: 'abcabcabc'
str.repeat<typeof str, 2>(); // type: 'abcabc'
```

### Template Literal Types [#template-literal-types]

```typescript
// Combine with template literal types
type Greeting<T extends string> = `Hello, ${T}!`;

const name = "World";
type Message = Greeting<typeof name>; // 'Hello, World!'

// With case conversion
type UpperGreeting<T extends string> = Uppercase<Greeting<T>>;
type Lower = UpperGreeting<"world">; // 'HELLO, WORLD!'
```

## Generic Type Utilities [#generic-type-utilities]

### String Manipulation Types [#string-manipulation-types]

```typescript
import type { Split, Join, Repeat, Reverse, Trim, TrimStart, TrimEnd, Replace, ReplaceAll } from "@visulima/string";

// Split string into array
type Words = Split<"hello-world", "-">; // ['hello', 'world']

// Join array into string
type Joined = Join<["hello", "world"], "-">; // 'hello-world'

// Repeat string
type Repeated = Repeat<"abc", 3>; // 'abcabcabc'

// Reverse string
type Reversed = Reverse<"hello">; // 'olleh'
```

### Type Guards [#type-guards]

```typescript
import type { IsStringLiteral, IsNumberLiteral, IsBooleanLiteral } from "@visulima/string";

// Check if type is string literal
type IsStr = IsStringLiteral<"hello">; // true
type NotStr = IsStringLiteral<string>; // false

// Check if type is number literal
type IsNum = IsNumberLiteral<42>; // true
type NotNum = IsNumberLiteral<number>; // false
```

### Array Types [#array-types]

```typescript
import type { IsStringLiteralArray, All, Any } from "@visulima/string";

// Check if all items are string literals
type AreStrings = IsStringLiteralArray<["a", "b", "c"]>; // true

// All items match condition
type AllMatch = All<[true, true, true]>; // true

// Any item matches condition
type AnyMatch = Any<[false, true, false]>; // true
```

## Type-Safe Options [#type-safe-options]

### Case Conversion Options [#case-conversion-options]

```typescript
import type { CaseOptions, LocaleOptions } from "@visulima/string";

const options: CaseOptions = {
    locale: "en",
    knownAcronyms: ["API", "URL", "XML"],
    cache: true,
    cacheMaxSize: 1000,
};

const localeOptions: LocaleOptions = {
    locale: "ja", // Japanese
};
```

### String Width Options [#string-width-options]

```typescript
import type { StringWidthOptions } from "@visulima/string";

const widthOptions: StringWidthOptions = {
    ambiguousIsNarrow: true,
    emojiWidth: 2,
    fullWidth: 2,
    regularWidth: 1,
    tabWidth: 4,
    countAnsiEscapeCodes: false,
};
```

### Truncate Options [#truncate-options]

```typescript
import type { TruncateOptions } from "@visulima/string";

const truncateOptions: TruncateOptions = {
    ellipsis: "...",
    position: "end",
    preferTruncationOnSpace: true,
    width: {
        emojiWidth: 2,
        fullWidth: 2,
    },
};
```

### Slugify Options [#slugify-options]

```typescript
import type { SlugifyOptions } from "@visulima/string";

const slugifyOptions: SlugifyOptions = {
    allowedChars: "a-z0-9-",
    separator: "-",
    lowercase: true,
    transliterate: true,
    fixChineseSpacing: true,
    replaceBefore: {
        "C++": "cpp",
    },
};
```

## Advanced Type Patterns [#advanced-type-patterns]

### Conditional Types [#conditional-types]

```typescript
import type { CamelCase, SnakeCase } from "@visulima/string";

type ConvertCase<T extends string, Format extends "camel" | "snake"> = Format extends "camel" ? CamelCase<T> : Format extends "snake" ? SnakeCase<T> : T;

type Result1 = ConvertCase<"hello-world", "camel">; // 'helloWorld'
type Result2 = ConvertCase<"hello-world", "snake">; // 'hello_world'
```

### Mapped Types [#mapped-types]

```typescript
type CaseMap<T extends Record<string, string>> = {
    [K in keyof T]: CamelCase<T[K]>;
};

type Original = {
    firstName: "john-doe";
    lastName: "jane-smith";
};

type Converted = CaseMap<Original>;
// {
//   firstName: 'johnDoe';
//   lastName: 'janeSmith';
// }
```

### Generic Constraints [#generic-constraints]

```typescript
function convertKeys<T extends Record<string, any>>(obj: T): { [K in keyof T as CamelCase<string & K>]: T[K] } {
    // Implementation
}

const result = convertKeys({
    "first-name": "John",
    "last-name": "Doe",
});
// Type: { firstName: string; lastName: string; }
```

## Type Inference [#type-inference]

### Automatic Type Inference [#automatic-type-inference]

```typescript
import { camelCase } from "@visulima/string";

// Type is inferred automatically
const result1 = camelCase("hello-world");
// Type: string

// With explicit generic
const result2 = camelCase<"hello-world">("hello-world");
// Type: specific literal type
```

### Function Overloads [#function-overloads]

```typescript
import { truncate } from "@visulima/string";

// Multiple overloads for different options
truncate("hello", 3);
truncate("hello", 3, { position: "end" });
truncate("hello", 3, { position: "start" });
```

## Best Practices [#best-practices]

1. Import types separately from runtime code
2. Use const assertions for literal types
3. Leverage type inference when possible
4. Use generic constraints for reusable utilities
5. Prefer type-level operations for compile-time checks
6. Document complex generic types

## Type-Safe Patterns [#type-safe-patterns]

### Builder Pattern [#builder-pattern]

```typescript
class StringBuilder<T extends string = ""> {
    private value: T;

    constructor(initial: T) {
        this.value = initial;
    }

    append<U extends string>(text: U): StringBuilder<`${T}${U}`> {
        return new StringBuilder(`${this.value}${text}` as `${T}${U}`);
    }

    getValue(): T {
        return this.value;
    }
}

const result = new StringBuilder("").append("Hello").append(" ").append("World").getValue();
// Type: 'Hello World'
```

### Type-Safe Configuration [#type-safe-configuration]

```typescript
interface Config<T extends string> {
    input: T;
    output: CamelCase<T>;
    transform: (input: T) => CamelCase<T>;
}

const config: Config<"hello-world"> = {
    input: "hello-world",
    output: "helloWorld",
    transform: (input) => camelCase(input) as any,
};
```

## Next Steps [#next-steps]

* [API Reference](/docs/packages/string/api) - Complete API documentation
* [Testing](/docs/packages/string/testing) - Testing utilities
* [Examples](/docs/packages/string/examples) - More code examples


# API Reference (/docs/packages/tabular/api)



# API Reference [#api-reference]

## Functions [#functions]

### `createTable(options?)` [#createtableoptions]

Create a new table instance.

### `createGrid(options?)` [#creategridoptions]

Create a new grid instance.

## Table Methods [#table-methods]

### `setHeaders(headers)` [#setheadersheaders]

Set table headers.

### `addRow(row)` [#addrowrow]

Add a single row.

### `addRows(rows)` [#addrowsrows]

Add multiple rows.

### `render()` [#render]

Render the table as a string.

## Options [#options]

```typescript
interface TableOptions {
    maxWidth?: number;
    showHeader?: boolean;
    wordWrap?: boolean;
    style?: {
        paddingLeft?: number;
        paddingRight?: number;
        borderStyle?: string;
    };
}
```


# Introduction (/docs/packages/tabular)



# @visulima/tabular [#visulimatabular]

Create beautiful ASCII tables and grids with full Unicode support, ANSI colors, and flexible configuration options.

## Key Features [#key-features]

* **ASCII Tables** - Create formatted tables with headers and rows
* **Unicode Support** - Handle CJK characters and emojis correctly
* **ANSI Colors** - Full support for colored table content
* **Flexible Styling** - Customizable borders, padding, alignment
* **Column Spanning** - rowSpan and colSpan support
* **Word Wrapping** - Automatic content wrapping
* **TypeScript** - Full type definitions included

## Quick Start [#quick-start]

```typescript
import { createTable } from "@visulima/tabular";

const table = createTable();
table.setHeaders(["Name", "Age", "City"]);
table.addRow(["John Doe", "30", "New York"]);
table.addRow(["Jane Smith", "25", "Los Angeles"]);

console.log(table.render());
// ┌───────────┬─────┬─────────────┐
// │ Name      │ Age │ City        │
// ├───────────┼─────┼─────────────┤
// │ John Doe  │ 30  │ New York    │
// │ Jane Smith│ 25  │ Los Angeles │
// └───────────┴─────┴─────────────┘
```

<Cards>
  <Card title="Installation" href="/docs/packages/tabular/installation">
    Install the package
  </Card>

  <Card title="Quick Start" href="/docs/packages/tabular/quick-start">
    Create your first table
  </Card>

  <Card title="Usage Guide" href="/docs/packages/tabular/usage">
    Explore all features
  </Card>

  <Card title="API Reference" href="/docs/packages/tabular/api">
    Complete API docs
  </Card>
</Cards>


# Installation (/docs/packages/tabular/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/tabular
```

## Import [#import]

```typescript
import { createTable, createGrid } from "@visulima/tabular";
```


# Quick Start (/docs/packages/tabular/quick-start)



# Quick Start [#quick-start]

## Basic Table [#basic-table]

```typescript
import { createTable } from "@visulima/tabular";

const table = createTable();
table.setHeaders(["Name", "Email"]);
table.addRow(["John", "john@example.com"]);
table.addRow(["Jane", "jane@example.com"]);

console.log(table.render());
```

## With Styling [#with-styling]

```typescript
const table = createTable({
    maxWidth: 80,
    style: {
        paddingLeft: 1,
        paddingRight: 1,
    },
});
```

## Column Alignment [#column-alignment]

```typescript
table.setHeaders(["Name", { content: "Age", hAlign: "center" }, { content: "Score", hAlign: "right" }]);
```


# Usage Guide (/docs/packages/tabular/usage)



# Usage Guide [#usage-guide]

## Creating Tables [#creating-tables]

```typescript
import { createTable } from "@visulima/tabular";

const table = createTable({
    maxWidth: 100,
    showHeader: true,
    wordWrap: true,
});
```

## Headers [#headers]

```typescript
// Simple headers
table.setHeaders(["Col1", "Col2", "Col3"]);

// With alignment
table.setHeaders(["Name", { content: "Age", hAlign: "center" }, { content: "Score", hAlign: "right" }]);
```

## Adding Rows [#adding-rows]

```typescript
// Single row
table.addRow(["Value1", "Value2", "Value3"]);

// Multiple rows
table.addRows([
    ["A", "B", "C"],
    ["D", "E", "F"],
]);
```

## Column Spanning [#column-spanning]

```typescript
table.addRow([{ colSpan: 2, content: "Spans 2 columns" }, "Normal cell"]);
```

## Styling [#styling]

```typescript
const table = createTable({
    style: {
        paddingLeft: 1,
        paddingRight: 1,
        borderStyle: "double",
    },
});
```

## Rendering [#rendering]

```typescript
const output = table.render();
console.log(output);
```


# API Reference (/docs/packages/task-runner/api)



# API Reference [#api-reference]

## Concurrent Process Runner [#concurrent-process-runner]

### `runConcurrently(commands, options?)` [#runconcurrentlycommands-options]

Run commands concurrently with real-time output streaming. Automatically uses native Rust addon when available.

```typescript
import { runConcurrently } from "@visulima/task-runner";

const result = await runConcurrently(["npm run build", { command: "npm run test", name: "test" }], {
    maxProcesses: 4,
    killOthers: ["failure"],
    onEvent: (event) => console.log(event),
});
// result: { success: boolean, closeEvents: ConcurrentCloseEvent[] }
```

**Options:**

| Option             | Type                         | Default         | Description                |
| ------------------ | ---------------------------- | --------------- | -------------------------- |
| `maxProcesses`     | `number`                     | `0` (unlimited) | Max simultaneous processes |
| `killOthers`       | `("failure" \| "success")[]` | `[]`            | Kill others on condition   |
| `killSignal`       | `string`                     | `"SIGTERM"`     | Signal for killing         |
| `killTimeout`      | `number`                     | `5000`          | Ms before SIGKILL          |
| `successCondition` | `string`                     | `"all"`         | Success evaluation         |
| `shellPath`        | `string`                     | auto-detected   | Custom shell path          |
| `restart`          | `{ tries, delay }`           | none            | Retry failed commands      |
| `teardown`         | `string[]`                   | none            | Cleanup commands           |
| `timings`          | `boolean`                    | `false`         | Print timing table         |
| `onEvent`          | `(event) => void`            | none            | Event callback             |

### `parseCommands(inputs, options?)` [#parsecommandsinputs-options]

Parse command strings through the expansion pipeline: strip quotes, expand shortcuts (`npm:build`), expand wildcards (`npm run watch-*`), expand argument placeholders (`{1}`, `{@}`, `{*}`).

```typescript
import { parseCommands } from "@visulima/task-runner";

const commands = parseCommands(['"npm:build"', "npm run watch-*"], { additionalArguments: ["--verbose"] });
```

### `detectScriptShell()` [#detectscriptshell]

Detect the npm `script-shell` configuration. Checks `npm_config_script_shell` env var first, then queries `npm config get script-shell` (cached). Returns `string | undefined`.

### Flow Controllers [#flow-controllers]

* `withRestart(runFn, commands, options, restartOptions)` - Wrap a runner with retry logic
* `createInputHandler(commands, options?)` - Route stdin to child processes by name/index prefix
* `logTimings(closeEvents, output?)` - Print timing summary table to a stream
* `formatTimingTable(closeEvents)` - Generate timing table as a string
* `runTeardown(options)` - Run cleanup commands sequentially

### Command Parsers [#command-parsers]

* `stripQuotes(config)` - Remove surrounding quotes
* `expandShortcut(config)` - Expand `npm:build` to `npm run build`
* `expandWildcard(config)` - Expand `npm run watch-*` against package.json/deno.json scripts
* `expandArguments(config, args)` - Replace `{1}`, `{@}`, `{*}` placeholders

## Task Runner [#task-runner]

### `defaultTaskRunner(tasks, options, context)` [#defaulttaskrunnertasks-options-context]

The main entry point. Returns `Promise<TaskResults>`.

## Task Graph [#task-graph]

### `createTaskGraph(tasks, options)` [#createtaskgraphtasks-options]

Creates a dependency-ordered task graph from task definitions. `options` is a `CreateTaskGraphOptions` object with `projectGraph`, `targetDefaults?`, and `workspace`.

### `getTaskId(target)` [#gettaskidtarget]

Creates a task ID string from a `TaskTarget` object (`"project:target:configuration"`).

### `parseTaskId(id)` [#parsetaskidid]

Parses a task ID into `{ project, target, configuration? }`.

### Graph Utilities [#graph-utilities]

* `findCycle(graph)` - Returns first cycle found, or undefined
* `findCycles(graph)` - Returns all cycles
* `makeAcyclic(graph)` - Removes cycle-forming edges
* `walkTaskGraph(graph, fn)` - Walk in topological order
* `getDependentTasks(graph, taskId)` - Find all tasks depending on a task
* `getTransitiveDependencies(graph, taskId)` - Find all transitive deps
* `getLeafTasks(graph)` - Find tasks with no dependencies
* `reverseTaskGraph(graph)` - Reverse edge directions

## Hashing [#hashing]

### `InProcessTaskHasher` [#inprocesstaskhasher]

Computes task hashes from explicit input declarations.

```typescript
const hasher = new InProcessTaskHasher({
    workspaceRoot,
    projects,
    namedInputs,
    targetDefaults,
    envVars,
    globalInputs,
    globalEnv,
    smartLockfileHashing,
    frameworkInference,
});

const details = await hasher.hashTask(task);
```

### `computeTaskHash(hashDetails)` [#computetaskhashhashdetails]

Computes a final SHA-256 hash from `TaskHashDetails`.

### `IncrementalFileHasher` [#incrementalfilehasher]

mtime-based file hasher that only re-hashes changed files.

```typescript
const hasher = new IncrementalFileHasher({
    workspaceRoot,
    snapshotPath: "node_modules/.cache/task-runner/file-snapshot.json", // default
});

const hashes = await hasher.hashDirectory("packages/my-app/src");
```

## Cache [#cache]

### `Cache` [#cache-1]

Local file-based cache with LRU eviction.

* `get(hash)` - Retrieve cached result
* `put(hash, output, outputs, code, fingerprint?)` - Store result
* `restoreOutputs(hash, outputs)` - Restore build artifacts
* `clear()` - Clear entire cache

### `RemoteCache` [#remotecache]

Turborepo-compatible HTTP cache client.

* `retrieve(hash, localCacheDirectory)` - Download from remote
* `store(hash, localCacheDirectory)` - Upload to remote

Options include `compression: "gzip" | "brotli"` (default `"gzip"` for Turborepo wire compatibility). Brotli reduces tarball size significantly on source-tree payloads but requires vis clients on both ends.

## Lockfile [#lockfile]

### `LockfileHasher` [#lockfilehasher]

Smart lockfile parser that hashes per-package dependency versions.

* `hashForPackage(packageJsonPath)` - Returns `PackageLockfileHash | undefined`
* `lockfileType` - Detected format (`"npm" | "pnpm" | "yarn" | undefined`)

### Lockfile Parsers [#lockfile-parsers]

* `parseNpmLockfile(content)` - Parse package-lock.json
* `parsePnpmLockfile(content)` - Parse pnpm-lock.yaml
* `parseYarnLockfile(content)` - Parse yarn.lock

## Framework Inference [#framework-inference]

* `detectFrameworks(packageJsonPath)` - Returns detected frameworks
* `inferFrameworkEnvPatterns(workspaceRoot, projects)` - Returns env patterns
* `getFrameworkEnvVariables(packageJsonPath, env?)` - Returns matching env vars

## Affected Detection [#affected-detection]

* `getChangedFiles(workspaceRoot, base, head)` - Git diff to get changed file paths
* `getAffectedProjects(options)` - Detect affected projects from git changes (`AffectedOptions`)
* `filterAffectedTasks(taskIds, affectedProjects)` - Filter task IDs by affected project set

## Visualization [#visualization]

* `toGraphvizDot(graph, options?)` - DOT format
* `toGraphJson(graph, options?)` - JSON format
* `toGraphHtml(graph, options?)` - Self-contained HTML
* `toGraphAscii(graph, options?)` - ASCII tree
* `projectGraphToDot(projectGraph)` - Project graph DOT

## Run Summary [#run-summary]

* `generateRunSummary(results, taskGraph, startTime)` - Create summary
* `writeRunSummary(summary, workspaceRoot)` - Write a timestamped JSON under `.task-runner/runs/`
* `writeLastRunSummary(summary, workspaceRoot)` - Overwrite `.task-runner/last-summary.json` (one file, always latest)
* `readLastRunSummary(workspaceRoot)` - Returns the last persisted summary or `undefined` if none
* `getLastRunSummaryPath(workspaceRoot)` - Canonical path where the last-run summary lives

The orchestrator writes `last-summary.json` automatically after every completed (non-aborted) run, so CLI integrations can render "last run details" without re-executing.

## Log Reporter [#log-reporter]

* `createLogReporter(mode, write?)` - Factory returning a `LogReporter`
* `LogReporter` - Implements `LifeCycleInterface`; renders `printTaskTerminalOutput` per mode

Modes:

| Mode          | Behavior                                                                         |
| ------------- | -------------------------------------------------------------------------------- |
| `interleaved` | Pass-through — emit each task's buffered output verbatim                         |
| `labeled`     | Prefix every line with `[project#target]` so parallel tasks stay distinguishable |
| `grouped`     | Wrap each task's output in a `── project#target ──` header + blank-line footer   |

Matches vite-task's `--log` flag semantics. Pair with `CompositeLifeCycle` to keep your existing UI renderer alongside the log reporter.

## Chrome Tracing Profile [#chrome-tracing-profile]

* `toChromeTrace(summary)` - Convert a `RunSummary` to a Chrome Tracing event array
* `writeChromeTrace(summary, outputPath)` - Write the trace JSON to disk

```typescript
import { writeChromeTrace, generateRunSummary } from "@visulima/task-runner";

const summary = generateRunSummary(results, taskGraph, startTime);
await writeChromeTrace(summary, "trace.json");
// Open in chrome://tracing or Perfetto to see the gantt.
```

Parallel tasks are packed into synthetic `tid` lanes via sweep-line scheduling, so the timeline reflects true concurrency even without real thread IDs. Dependency edges render as flow arrows between spans.

## Lifecycle [#lifecycle]

* `ConsoleLifeCycle` - Logs events to console
* `EmptyLifeCycle` - No-op implementation
* `CompositeLifeCycle` - Combines multiple lifecycles

Optional hooks on `LifeCycleInterface` (implement what you need):

| Hook                                          | When                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `printCacheMiss(task, reasons)`               | Auto-fingerprint cache miss, with diagnostic reason                                                                             |
| `printSelfModifyingSkip(task, modifiedFiles)` | Cache skipped because the task wrote to its own tracked inputs                                                                  |
| `printEmptyFingerprintWarning(task, reason)`  | Tracker ran but returned zero workspace accesses — likely a static binary without strace                                        |
| `printWhenSkip(task, reason)`                 | A `when:` clause did not match the current environment. Co-fires with `printTaskTerminalOutput` (status `"skipped"`) — pick one |
| `onTaskStdout(task, chunk)`                   | Streaming stdout chunk in arrival order. Non-blocking — the orchestrator does not await. Buffered executors skip this hook      |
| `onTaskStderr(task, chunk)`                   | Streaming stderr chunk in arrival order. Same contract as `onTaskStdout`                                                        |

`onTaskStdout` / `onTaskStderr` are forwarded by streaming executors (e.g. `vis run`'s concurrent executor). Buffered executors (the simple test executor) skip them — rely on `printTaskTerminalOutput` for the final dump.

## Native Bindings [#native-bindings]

The native (Rust / NAPI) addon is exposed through `loadNativeBindings()` and `isNativeAvailable()`. The loader is lazy and cached after the first attempt — when the addon is missing the loader returns `undefined` and callers fall through to TypeScript implementations.

```typescript
import { loadNativeBindings, isNativeAvailable } from "@visulima/task-runner";

if (isNativeAvailable()) {
    const native = loadNativeBindings();
    const hash = native?.hashFile("/abs/path");
}
```

Pure-TypeScript fallbacks ship for everything the native addon exposes (parallel file hashing, cycle detection, concurrent process runner) so callers never need to branch on platform.

## Worktree detection [#worktree-detection]

Three top-level helpers wrap the native worktree API with a pure-Node fallback (uses `git rev-parse --git-common-dir`). They share a per-process memoization cache and are safe to call from any code path — the cache directory resolver, affected detection, and lockfile resolution all use them to point at the right `.git` inside linked git worktrees.

```typescript
import { getMainWorktreeRoot, isLinkedWorktree, resetWorktreeCache } from "@visulima/task-runner";

const mainRoot = getMainWorktreeRoot(workspaceRoot);
// mainRoot is the absolute path to the primary checkout for a linked
// worktree, or undefined for primary checkouts / non-git directories.
```

| Function                             | Returns               | Notes                                                                                                            |
| ------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `getMainWorktreeRoot(workspaceRoot)` | `string \| undefined` | Resolves the main worktree root for a linked worktree; `undefined` for primary checkouts and non-git directories |
| `isLinkedWorktree(workspaceRoot)`    | `boolean`             | `true` when `workspaceRoot` is a linked worktree (not the primary)                                               |
| `resetWorktreeCache()`               | `void`                | Clears the per-process resolution cache. Test-only escape hatch                                                  |

## Types [#types]

Key interfaces: `Task`, `TaskGraph`, `TaskResult`, `TaskRunnerOptions`, `TaskRunnerContext`, `ProjectGraph`, `ProjectConfiguration`, `TargetConfiguration`, `TaskHashDetails`, `InputDefinition`, `FileSetInput`, `FileSetPattern`, `FileSetBase`, `TaskFingerprint`, `CacheMissReason`, `RunSummary`, `ChromeTraceEvent`, `LogMode`, `RemoteCacheCompression`, `DetectedFramework`, `ConcurrentCommandConfig`, `ConcurrentCommandInput`, `ConcurrentRunnerOptions`, `ConcurrentRunResult`, `ConcurrentCloseEvent`, `ProcessEvent`.

`TaskResult` adds `selfModified?: boolean` and `emptyFingerprint?: boolean` flags when caching is skipped for those reasons. `TaskFingerprint` adds `modifiedInputs?: string[]` populated when the auto-fingerprint tracker sees both read and write accesses against the same workspace path.


# Auto-Fingerprinting (/docs/packages/task-runner/concepts/auto-fingerprinting)



# Auto-Fingerprinting [#auto-fingerprinting]

Auto-fingerprinting eliminates the need for manual input configuration. Instead of declaring which files affect a task, the runner automatically tracks which files a task actually accesses during execution.

## How It Works [#how-it-works]

1. **First run** - Execute the task while tracking file system access
2. **Record fingerprint** - Store content hashes of all accessed files
3. **Subsequent runs** - Validate the fingerprint against current file state
4. **Cache hit** - If all files are unchanged, replay cached result
5. **Cache miss** - Re-execute and update the fingerprint

## Enable Auto-Fingerprinting [#enable-auto-fingerprinting]

```typescript
const results = await defaultTaskRunner(
    tasks,
    {
        autoFingerprint: true,
        fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
        cacheDiagnostics: true,
    },
    context,
);
```

## What Gets Tracked [#what-gets-tracked]

The fingerprint captures:

* **File reads** - Content hashes of all files opened during execution
* **Missing files** - Files that were probed but didn't exist (creating them later invalidates the cache)
* **Directory listings** - If a command scans a directory (e.g., glob for `*.test.ts`), adding/removing files invalidates the cache
* **Environment variables** - Matching the configured patterns
* **Command arguments** - Task overrides and configuration

## File Access Tracking [#file-access-tracking]

On Linux, file accesses are tracked via `strace` intercepting `open`, `openat`, `creat`, `stat`, `access`, `unlink`, `rename`, and related syscalls. On other platforms, a preload script patches `fs` / `fs/promises` calls.

Both backends classify accesses as `read`, `stat`, `readdir`, `write`, or `missing`. Writes are used for [self-modifying task detection](#self-modifying-task-detection).

## Self-modifying task detection [#self-modifying-task-detection]

When a task both reads and writes the same workspace-relative file (e.g. a `tsc --build` invocation that updates its own `.tsbuildinfo`), caching that task's output would capture post-write state and guarantee false cache hits on subsequent runs.

The fingerprint manager populates a `modifiedInputs` field with every path seen as both read and write. The orchestrator skips the cache write for that task and fires `printSelfModifyingSkip(task, modifiedFiles)` so the UI can explain the skip. The next run re-executes from scratch.

In Nx-style (non-auto-fingerprint) mode, the orchestrator re-hashes every declared input after execution and compares against the pre-run hash — same effect without needing write tracking.

## Empty-fingerprint safety net [#empty-fingerprint-safety-net]

Static binaries on platforms without strace (esbuild on macOS/Windows, Rust/Go tools) can bypass the preload script entirely, which means the tracker returns zero file accesses. Persisting that empty fingerprint would produce a false cache hit on every subsequent run.

When the real tracker is used but returns zero workspace accesses, the orchestrator:

1. Skips the cache write.
2. Sets `result.emptyFingerprint = true`.
3. Fires `printEmptyFingerprintWarning(task, reason)` — implementers typically print a hint to add the task's inputs explicitly or fall back to Nx-style declarations.

This closes the "silent stale cache" class of bugs without needing a full [`fspy`-style native syscall interceptor](https://github.com/voidzero-dev/vite-task/tree/main/crates/fspy).

## Cache Miss Diagnostics [#cache-miss-diagnostics]

When `cacheDiagnostics` is enabled, the runner explains exactly why a cache miss occurred:

```
Cache miss reasons:
  - File modified: src/index.ts
  - Environment variable changed: NODE_ENV
  - Directory contents changed: src/components
```

## Untracked Environment Variables [#untracked-environment-variables]

Some env vars should be available to tasks but not affect the cache (e.g., CI build IDs):

```typescript
{
    autoFingerprint: true,
    fingerprintEnvPatterns: ["VITE_*", "CI_*"],
    untrackedEnvVars: ["CI_BUILD_ID", "CI_JOB_URL"],
}
```

## Comparison with Nx-style [#comparison-with-nx-style]

| Aspect        | Nx-style                           | Auto-fingerprint                      |
| ------------- | ---------------------------------- | ------------------------------------- |
| Configuration | Manual input declarations          | Zero-config                           |
| Accuracy      | May miss files or include too many | Tracks exact files                    |
| First run     | Hash computed upfront              | Must execute to build fingerprint     |
| Performance   | Faster cache checks                | Slightly slower (validates all files) |
| Remote cache  | Full support                       | Local only                            |


# Caching (/docs/packages/task-runner/concepts/caching)



# Caching (Nx-style) [#caching-nx-style]

The default caching mode uses explicit input declarations to compute deterministic hashes. If the hash matches a previous run, the cached result is replayed instantly.

## How It Works [#how-it-works]

1. **Collect inputs** - File patterns, env vars, runtime commands, external dependencies, and the hashes of `dependsOn` dependencies
2. **Compute hash** - SHA-256 hash of all input contents
3. **Check cache** - Look up hash in local (then remote) cache
4. **Hit?** Replay terminal output and restore build artifacts
5. **Miss?** Execute task, store result for next time

## Inputs [#inputs]

### File patterns [#file-patterns]

```typescript
const options = {
    namedInputs: {
        production: ["{projectRoot}/src/**/*", "{projectRoot}/package.json", "!{projectRoot}/**/*.test.ts"],
    },
    targetDefaults: {
        build: { inputs: ["production"] },
    },
};
```

Bare glob strings resolve relative to the project root. For workspace-root-relative paths (shared configs, root lockfiles), use the object form:

```typescript
inputs: ["src/**", { fileset: { pattern: "tsconfig.base.json", base: "workspace" } }, { fileset: { pattern: "!packages/*/dist", base: "workspace" } }];
```

`base` accepts `"package"` (default, same as a bare string) or `"workspace"`. Negation with `!` works in both forms.

### Environment variables [#environment-variables]

```typescript
{
    envVars: ["NODE_ENV", "API_URL"],
    globalEnv: ["CI"], // Changes bust ALL caches
}
```

### Runtime commands [#runtime-commands]

```typescript
const inputs = [{ runtime: "node --version" }, { env: "NODE_ENV" }, { externalDependencies: ["typescript", "esbuild"] }];
```

### Dependency hashes (`dependsOn`) [#dependency-hashes-dependson]

`dependsOn` does more than order execution — a task's cache key also folds in the hashes of its direct dependencies. When a dependency's source changes, its hash changes, which changes the dependent's hash, so the dependent re-runs instead of replaying a stale result.

```typescript
targetDefaults: {
    // `check` runs after each dependency's `build` AND invalidates when any
    // dependency's `build` hash changes — even if the checking project's own
    // files are untouched.
    check: { dependsOn: ["^build"] },
};
```

This is what makes cross-package tasks (type-checking, bundling, integration tests) cache-correct: a task whose output depends on a sibling's `dist` can no longer restore a cache hit after that `dist` was rebuilt. Coverage is transitive — every task folds its direct dependencies, whose hashes already fold theirs (a Merkle-style chain).

Because this is keyed on the dependency's hash (not its output files), you don't have to enumerate a dependency's `dist` paths as inputs. Tasks with no `dependsOn` edge to a project are unaffected by that project's changes, so invalidation stays scoped to the declared graph.

## Global Inputs [#global-inputs]

Files that invalidate every task's cache when changed:

```typescript
{
    globalInputs: [
        "package-lock.json",  // Default
        "pnpm-lock.yaml",     // Default
        "yarn.lock",          // Default
        "tsconfig.base.json", // Default
        "tsconfig.json",      // Default
        ".env",               // Default
    ],
}
```

## Outputs [#outputs]

Each task declares the files it produces via `outputs`. Entries can be:

* **Glob patterns** — relative to the workspace root (`"packages/app/dist/**"`). Resolved via `fs.glob` and filtered to files only.
* **Negations** — `"!dist/cache/**"` excludes paths the positive globs would otherwise capture. Applied after the combined positive set is expanded.
* **`{ auto: true }`** — uses whatever files the task actually wrote, as recorded by the file-access tracker. Silently behaves as "no outputs" when tracking isn't active for this task.

```typescript
targets: {
    build: {
        outputs: ["dist/**", "!dist/cache/**", { auto: true }],
    },
}
```

Resolved paths are deduped, sorted, and filtered to files inside the workspace before archiving — archives are byte-reproducible across invocations.

## Cache Storage [#cache-storage]

Cache entries are stored atomically in `.task-runner-cache/`:

```
.task-runner-cache/
  <hash>/
    outputs/          # Archived build outputs
    code              # Exit code
    terminalOutput    # Captured terminal output
    fingerprint.json  # Auto-fingerprint data (optional)
    .commit           # Marker for complete entries
```

## Cache Size Management [#cache-size-management]

```typescript
{
    maxCacheSize: "1GB",           // Evict oldest entries when exceeded
    maxCacheAge: 7 * 24 * 60 * 60 * 1000, // 7 days (default)
}
```

## Performance [#performance]

* **Parallel cache I/O** — output staging and restore swap run with bounded concurrency (16 in flight by default), so tasks with many small files saturate disk without overwhelming it.
* **Streaming HMAC verification** — when `remoteCache.signing.secret` is set, downloads from the HTTP backend recompute `HMAC-SHA256(secret, hash || body)` chunk-by-chunk off disk. Constant-time comparison rejects tampered or replayed artifacts before they ever land in the local cache. With `verifyOnDownload: true` the client also rejects unsigned downloads outright.

## Dry Run [#dry-run]

Inspect hashes without executing:

```typescript
const results = await defaultTaskRunner(
    tasks,
    {
        dryRun: true,
    },
    context,
);
// Each task reports "skipped" with its computed hash
```


# Concurrent Process Runner (/docs/packages/task-runner/concepts/concurrent-runner)



# Concurrent Process Runner [#concurrent-process-runner]

The concurrent process runner executes multiple shell commands in parallel with real-time output streaming, process tree management, and signal propagation. It uses a native Rust addon (NAPI bindings) for performance, with an automatic JavaScript fallback.

## Architecture [#architecture]

```
parseCommands(inputs)            ← optional: shortcuts, wildcards, args
        │
runConcurrently(commands, options)
        │
        ├── detectScriptShell()     ← npm script-shell config
        │
        ├── Native (Rust/tokio)     ← when .node binary available
        │   ├── Process spawning    ← tokio::process::Command
        │   ├── I/O multiplexing   ← async BufReader line-by-line
        │   ├── Process groups     ← setsid/killpg (Unix), Job Objects (Windows)
        │   └── Signal handling    ← SIGINT/SIGTERM/SIGHUP propagation
        │
        └── Fallback (JS)          ← when native unavailable
            ├── child_process.spawn
            ├── Line-buffered output
            └── process.kill(-pid) / taskkill /T
```

## Native vs Fallback [#native-vs-fallback]

The runner automatically selects the implementation:

| Feature           | Native (Rust)                 | Fallback (JS)                 |
| ----------------- | ----------------------------- | ----------------------------- |
| Process spawning  | tokio async                   | child\_process.spawn          |
| I/O multiplexing  | epoll/kqueue via tokio        | Node.js event loop            |
| Process tree kill | setsid + killpg / Job Objects | process.kill(-pid) / taskkill |
| Signal handling   | tokio::signal                 | process.on('SIGINT')          |
| Output buffering  | Line-buffered async           | Line-buffered event-based     |

Both implementations produce identical `ProcessEvent` streams and `ConcurrentRunResult` outputs.

## Process Tree Management [#process-tree-management]

### Unix [#unix]

Each child process is spawned in a new session via `setsid()`. This creates a process group with the child as the leader. When killing, `killpg()` sends the signal to the entire group, ensuring all grandchild processes are cleaned up.

### Windows [#windows]

Each child process is assigned to a Windows Job Object configured with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. This ensures:

* All child processes in the tree are terminated when the Job Object is closed
* If the parent process crashes, the OS automatically cleans up the children
* `TerminateJobObject()` provides instant tree killing (no `taskkill` subprocess)

## Signal Handling [#signal-handling]

When the parent process receives a signal:

| Signal          | Behavior                                                               |
| --------------- | ---------------------------------------------------------------------- |
| SIGINT (Ctrl+C) | Kill all process groups, translate exit codes to 0 (user cancellation) |
| SIGTERM         | Kill all process groups, preserve original exit codes                  |
| SIGHUP          | Kill all process groups, preserve original exit codes                  |

The SIGINT exit code translation matches `concurrently`'s behavior: pressing Ctrl+C is not considered a failure.

## Max Process Queue [#max-process-queue]

When `maxProcesses` is set, commands are queued and spawned as slots become available:

```
maxProcesses: 2, commands: [A, B, C, D]

Time 0: Spawn A, Spawn B         (C, D queued)
Time 1: A completes → Spawn C    (D queued)
Time 2: B completes → Spawn D    (queue empty)
Time 3: C completes
Time 4: D completes → Result
```

## Success Conditions [#success-conditions]

| Condition           | Meaning                                         |
| ------------------- | ----------------------------------------------- |
| `"all"` (default)   | All commands must exit with code 0              |
| `"first"`           | Only the first command to complete must succeed |
| `"last"`            | Only the last command to complete must succeed  |
| `"command-<name>"`  | Only the named command must succeed             |
| `"!command-<name>"` | All commands except the named one must succeed  |

## Shell Configuration [#shell-configuration]

The runner detects the shell in this order:

1. **Explicit `shellPath` option** — caller override
2. **`npm_config_script_shell` env var** — set by npm inside `npm run` (free to check)
3. **`npm config get script-shell`** — subprocess query, cached after first call
4. **Platform default** — `/bin/sh` (Unix) or `cmd.exe` (Windows)

Custom shells (Git Bash, zsh, fish) are invoked with POSIX-style `-c` arguments.

## Stdin Modes [#stdin-modes]

| Mode               | Description                   | Use Case                       |
| ------------------ | ----------------------------- | ------------------------------ |
| `"null"` (default) | stdin closed                  | Build tasks, CI                |
| `"pipe"`           | stdin is a writable pipe      | Programmatic input             |
| `"inherit"`        | child reads terminal directly | Dev servers (Vite `r`/`o`/`h`) |


# Remote Caching (/docs/packages/task-runner/concepts/remote-caching)



# Remote Caching [#remote-caching]

Remote caching allows team members and CI machines to share cached task results. The task runner exposes a pluggable backend interface so the same cache contract can run over multiple wire protocols:

* **HTTP** (default) — Turborepo v8 artifacts wire-compatible. Works with Vercel Remote Cache, `ducktors/turborepo-remote-cache`, and any server that speaks the Turborepo protocol.
* **REAPI** (Bazel Remote Execution API gRPC) — drop-in client for the existing OSS REAPI ecosystem (`bazel-remote`, BuildBuddy, BuildBarn, EngFlow). Implements `GetActionResult` / `BatchReadBlobs` / `Read` / `FindMissingBlobs` / `BatchUpdateBlobs` / `Write` / `UpdateActionResult` / `Capabilities`.

## Configuration [#configuration]

```ts
const results = await defaultTaskRunner(
    tasks,
    {
        remoteCache: {
            url: "https://cache.example.com",
            token: process.env.CACHE_TOKEN,
            teamId: "my-team",

            // Canonical mode — pick one. Defaults to "readwrite".
            mode: "readwrite", // "read" | "write" | "readwrite"

            // Backend selector. Defaults to "http".
            backend: "http", // "http" | "reapi"

            // Wire compression (HTTP backend only).
            compression: "gzip", // "gzip" (default) | "brotli"

            // Surface fire-and-forget upload errors. Without this hook
            // upload failures are silently dropped (uploads run
            // off the critical path so they never block the run).
            onUploadError: (hash, error) => {
                logger.warn("[remote-cache] upload failed", { error, hash });
            },
        },
    },
    context,
);
```

The same config object covers both backends. Backend-specific fields (`signing` / `compression` for HTTP; `bearerToken` / `instanceName` / `allowInsecureBearer` for REAPI) are read by the relevant backend and ignored by the other, so flipping `backend` rarely requires more than one line of config.

### `mode`: read / write / readwrite [#mode-read--write--readwrite]

A single canonical knob controls cache access:

| `mode`      | Reads from remote | Writes to remote | Typical use                      |
| ----------- | ----------------- | ---------------- | -------------------------------- |
| `readwrite` | yes (default)     | yes (default)    | CI, default for dev              |
| `read`      | yes               | no               | branch builds, untrusted CI jobs |
| `write`     | no                | yes              | warm-the-cache nightly jobs      |

The earlier `read` / `write` boolean pair was removed in favor of this single field — see the migration note below.

CLI overrides (work on `vis run`):

```bash
vis run build --cache-mode read           # read-only on this run
vis run build --cache-mode readwrite      # full access
vis run build --cache-backend http        # default
vis run build --cache-backend reapi       # selects REAPI gRPC backend
```

The CLI flags only take effect when a `remoteCache` block is already configured in `vis.config.ts` — they layer on top of config, never replace it.

## Backends [#backends]

### HTTP (Turborepo-compatible) [#http-turborepo-compatible]

The HTTP backend is the default and works today. It speaks the same wire protocol Turborepo and Vercel Remote Cache use, so any compliant server is a drop-in:

```
PUT /v8/artifacts/{hash}?teamId={team}  → Upload cached artifact
GET /v8/artifacts/{hash}?teamId={team}  → Download cached artifact
POST /v8/artifacts/events               → Analytics (optional)

Headers:
  Authorization: Bearer {token}
  Content-Type: application/octet-stream
```

#### Compression [#compression]

Artifact tarballs are compressed client-side before upload:

| Compression | Size ratio on typical dist payloads | Compatibility                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------- |
| `"gzip"`    | baseline                            | Turborepo wire-compatible — works with any server    |
| `"brotli"`  | \~15–20% smaller                    | vis clients on both ends (server is format-agnostic) |

Brotli uses Node's built-in `zlib.createBrotliCompress` at quality level 4. Switching formats invalidates existing remote entries — they'll re-populate on the next run. The upload includes an `X-Artifact-Compression` header so spec-extended servers can branch on format.

#### Self-hosted HTTP servers [#self-hosted-http-servers]

* [ducktors/turborepo-remote-cache](https://github.com/ducktors/turborepo-remote-cache) — Node.js, supports S3/GCS/Azure
* Vercel Remote Cache — managed, free on all plans
* [bazel-remote](https://github.com/buchgr/bazel-remote) — Go binary, also serves the REAPI gRPC API on the same instance

### REAPI (Bazel Remote Execution API) [#reapi-bazel-remote-execution-api]

REAPI is the lingua franca for self-hostable build caches. The same server can usually serve both the HTTP `/v8/artifacts` endpoint *and* the gRPC REAPI service, so picking REAPI is mostly about wire efficiency on large output sets — gRPC streaming + per-blob deduplication beats single-tarball uploads on builds with many small files.

`@visulima/task-runner` ships the `ReapiRemoteCache` backend over `@grpc/grpc-js`. Both gRPC libraries are listed as **optional peer dependencies** — they're only resolved when `backend: "reapi"` is selected:

```bash
pnpm add @grpc/grpc-js @grpc/proto-loader
```

Configuration:

```ts
remoteCache: {
    backend: "reapi",
    url: "grpcs://cache.example.com:443", // grpc:// for cleartext
    bearerToken: process.env.CACHE_TOKEN, // sent as `authorization: Bearer <token>` metadata
    instanceName: "my-team",              // optional REAPI `instance_name` for multi-tenant servers
    mode: "readwrite",
}
```

#### Auth model [#auth-model]

The REAPI backend reads `bearerToken` (not `token` — that's HTTP-only) and sends it in the `authorization` gRPC metadata header. To prevent token leaks over cleartext, the constructor **throws** if a bearer token is set on a `grpc://` URL:

```text
[task-runner] remoteCache.backend = "reapi" refuses to send a bearer token over cleartext gRPC.
Use `grpcs://` (or terminate TLS at a reverse proxy), or pass `allowInsecureBearer: true`
for trusted-boundary deployments (loopback, mesh mTLS sidecar).
```

Use `allowInsecureBearer: true` only for trusted boundaries (local Docker, mesh mTLS sidecar that re-encrypts the next hop). The default refuses, so the dangerous case has to be opt-in.

#### Capability negotiation [#capability-negotiation]

`Capabilities.GetCapabilities` is called lazily on the first RPC and cached for the connection's lifetime. The negotiation:

* captures `max_batch_total_size_bytes` so `BatchUpdateBlobs` / `BatchReadBlobs` never frame a request over the server limit;
* captures `digest_functions` and refuses to issue further RPCs if the server advertises a non-empty list that doesn't include `SHA256` (vis pins sha256 for action digests; a server expecting BLAKE3 would reject every call with `INVALID_ARGUMENT`);
* re-throws `UNAUTHENTICATED` / `PERMISSION_DENIED` from negotiation rather than swallowing them — a misconfigured token surfaces here, not on the next CAS write.

#### Wire flow [#wire-flow]

| Operation | Small blob (≤ batch limit) | Large blob                     |
| --------- | -------------------------- | ------------------------------ |
| Read      | `BatchReadBlobs`           | `ByteStream.Read` (streaming)  |
| Write     | `BatchUpdateBlobs`         | `ByteStream.Write` (resumable) |

Before any upload, `FindMissingBlobs` filters out blobs the server already has. Per-batch sizing accounts for \~256 bytes of envelope overhead per entry so a payload exactly at the server limit doesn't push the framed request over.

In-process upload dedup: two concurrent `storeAction` calls referencing the same blob hash share a single in-flight upload promise — matching REAPI's CAS dedup on the wire side.

## Capabilities matrix [#capabilities-matrix]

| Feature                             | HTTP backend                                 | REAPI backend                                                          |
| ----------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| Wire format                         | Turborepo v8                                 | gRPC, REAPI v2                                                         |
| Per-blob dedup across actions       | no (one tarball)                             | yes (CAS)                                                              |
| Streaming uploads                   | yes                                          | yes                                                                    |
| Capability negotiation              | n/a                                          | `Capabilities` RPC (cached per process)                                |
| Bearer-token auth                   | yes (`token`)                                | yes (`bearerToken`, refused over cleartext)                            |
| HMAC artifact signing               | yes (`signing.secret`)                       | n/a (sha256 content addressing instead)                                |
| mTLS                                | reverse-proxy                                | future work                                                            |
| Resumable large blob uploads        | no                                           | yes (`Write` RPC)                                                      |
| Multi-tenant via instance namespace | `teamId` query param                         | `instance_name` field                                                  |
| In-process upload dedup             | yes (per-digest)                             | yes (per-digest)                                                       |
| Wire compression                    | gzip / brotli (client-side, header-tagged)   | identity (REAPI compressors are negotiated; vis pins identity for now) |
| Servers in OSS today                | turborepo-remote-cache, Vercel, bazel-remote | bazel-remote, BuildBuddy, BuildBarn, EngFlow                           |

## Self-hosting with bazel-remote [#self-hosting-with-bazel-remote]

`bazel-remote` is the simplest path to a self-hosted cache that's ready for both backends. Single Go binary, no managed service required.

### Local Docker quickstart [#local-docker-quickstart]

```bash
docker run -d \
    --name bazel-remote \
    -v /tmp/bazel-remote:/data \
    -p 9090:9090 \
    -p 9092:9092 \
    buchgr/bazel-remote-cache \
    --max_size=20 \
    --http_address=0.0.0.0:9090 \
    --grpc_address=0.0.0.0:9092
```

Point the HTTP backend at it from your `vis.config.ts`:

```ts
remoteCache: {
    url: "http://localhost:9090",
    token: "any-string-works-locally",
    mode: "readwrite",
}
```

The same instance also serves REAPI on `:9092` — swap to `backend: "reapi"` and `url: "grpc://localhost:9092"` (cleartext) or `grpcs://...` (TLS, behind a reverse proxy) without redeploying anything.

### S3-backed (production) [#s3-backed-production]

`bazel-remote` can stream to S3 and serve cached entries to your team:

```bash
docker run -d \
    --name bazel-remote \
    -p 9090:9090 \
    -p 9092:9092 \
    -e AWS_ACCESS_KEY_ID=... \
    -e AWS_SECRET_ACCESS_KEY=... \
    buchgr/bazel-remote-cache \
    --s3.bucket=my-vis-cache \
    --s3.prefix=visulima \
    --s3.endpoint=s3.us-east-1.amazonaws.com \
    --max_size=200 \
    --http_address=0.0.0.0:9090 \
    --grpc_address=0.0.0.0:9092
```

Run it behind a reverse proxy that terminates TLS and validates a shared bearer token, then set `url: "https://cache.example.com"` and `token: process.env.CACHE_TOKEN` in `vis.config.ts`.

## Read/write lifecycle [#readwrite-lifecycle]

For a single task:

1. **Local lookup** by `task.hash` (xxh3-128 over inputs). Hit → replay outputs.
2. **Local miss + `mode` includes read** → bridge derives an action digest with `actionDigestForTaskHash(taskHash)` and calls `backend.retrieveAction`. Hit → extract into the local cache, replay outputs.
3. **Remote miss** → execute task.
4. **Successful exec** → write local cache.
5. **`mode` includes write** → fire-and-forget `backend.storeAction` (errors surface through `onUploadError`; never block the run).

The local cache writes blobs first (atomic via `tmp/<uid>` + `rename`, where `uid` is `crypto.randomUUID()`) and the AC entry last, so a partially-written entry is never observable.

### Action digest derivation [#action-digest-derivation]

The orchestrator hashes inputs with `xxh3-128` for the local task hash, but REAPI servers reject anything other than sha256 on the wire. `actionDigestForTaskHash` bridges the two:

```ts
const key = `vis-task:${taskHash}`;
const action = {
    hash: sha256(key),
    sizeBytes: 0, // identifies an *action* (an ActionResult key), not a CAS blob
};
```

`sizeBytes` is `0` because this digest names an entry in the Action Cache, not a stored blob — REAPI ignores `size_bytes` for action keys. Setting it to `key.length` would make the server believe a blob of that exact length lives at this hash and any downstream `BatchReadBlobs` against the digest would mismatch.

Every vis client computes the same action digest from the same task hash, so a write from one machine and a read from another converge on the same Action Cache entry.

### Tarball compatibility (HTTP backend) [#tarball-compatibility-http-backend]

The HTTP backend ships a single tarball per action. The bridge uses [`nanotar`](https://github.com/unjs/nanotar) for tar/untar — pure-TS, no shellout, deterministic across OSes (forward-slash entry names, sorted directory walks). Path-traversal validation rejects absolute paths, `..` traversal, and Windows drive prefixes before any byte is written, so a malicious cache server cannot ship a tarball that escapes the destination directory.

## Diagnostics: `vis cache doctor` [#diagnostics-vis-cache-doctor]

When a build doesn't hit the remote cache, the question is usually one of: is the URL reachable, does my token work, does the server speak the protocol I think it does. `vis cache doctor` answers all three without forcing you to issue a real cache RPC.

```sh
vis cache doctor                                     # probes whatever vis.config.ts has wired up
vis cache doctor --url=grpcs://cache.example.com:443 # ad-hoc URL probe
vis cache doctor --backend=reapi --json              # machine-readable
vis cache doctor --timeout=2000                      # fail fast in CI
```

Backend selection is inferred from the URL scheme (`grpc://`/`grpcs://` → REAPI, anything else → HTTP) unless `--backend` overrides it.

* **HTTP backend**: sends a `HEAD` against the configured URL. Reachable servers typically reply `401`/`403`/`404` (depending on auth/team/no-such-artifact) — anything that isn't a network error proves the server is alive. Reports HTTP status and round-trip latency.
* **REAPI backend**: dials the gRPC channel, calls `Capabilities`, and reports the negotiated `digest_functions` and `max_batch_total_size_bytes`. Bearer tokens, instance names, and the `allowInsecureBearer` escape hatch are forwarded from `vis.config.ts`. The probe bypasses the read/write `mode` gate so it works even on caches configured `mode: "write"`.

Exit code is `1` on any probe failure (network error, auth failure, missing config), so CI jobs can `vis cache doctor || exit 1` as a pre-flight check before relying on the cache for the real run.

## Environment variables [#environment-variables]

For Turborepo compatibility the HTTP backend reads:

```bash
TURBO_API=https://cache.example.com
TURBO_TEAM=my-team
TURBO_TOKEN=your-auth-token
```

These map onto `url`, `teamId`, and `token` respectively when the corresponding fields aren't set in config.

## Migration from earlier vis releases [#migration-from-earlier-vis-releases]

The earlier `read` / `write` boolean pair was removed. Translate to `mode`:

```ts
// before
remoteCache: { url, token, read: true, write: false }
// after
remoteCache: { url, token, mode: "read" }
```

| Old shape                     | New `mode`    |
| ----------------------------- | ------------- |
| `{ read: true, write: true }` | `"readwrite"` |
| `{ read: true, write: false}` | `"read"`      |
| `{ read: false, write: true}` | `"write"`     |

Leaving `mode` unset keeps the existing default of `"readwrite"`.

The local cache layout has also been extended with a content-addressable v2 schema (`<cacheDir>/v2/{ac,cas,task-hash-index}/<aa>/...`). Existing `<cacheDir>/<hash>/` entries continue to be readable; new writes still emit the legacy layout for now to keep cache portability across vis versions during the rollout.


# Task Graph (/docs/packages/task-runner/concepts/task-graph)



# Task Graph [#task-graph]

The task graph is the foundation of the task runner. It defines tasks, their dependencies, and determines execution order.

## Structure [#structure]

A task graph consists of:

* **Tasks** - Individual units of work (e.g., `app:build`, `lib:test`)
* **Dependencies** - Edges between tasks that define execution order
* **Roots** - Tasks with no dependencies (entry points)

```typescript
import { createTaskGraph } from "@visulima/task-runner";

const taskGraph = createTaskGraph(tasks, {
    projectGraph,
    targetDefaults: {
        build: { dependsOn: ["^build"] }, // Run dependency builds first
    },
    workspace,
});
```

## Task IDs [#task-ids]

Tasks are identified by the format `project:target:configuration`:

```typescript
import { getTaskId, parseTaskId } from "@visulima/task-runner";

const id = getTaskId({ project: "my-app", target: "build", configuration: "production" });
// → "my-app:build:production"

const parsed = parseTaskId("my-app:build");
// → { project: "my-app", target: "build" }
```

## Dependency Resolution [#dependency-resolution]

The `^` prefix in `dependsOn` means "run this target in dependency projects first":

```typescript
const targetDefaults = {
    build: {
        dependsOn: ["^build"], // Build all dependencies before this project
    },
    test: {
        dependsOn: ["build"], // Build this project before testing
    },
};
```

## Graph Utilities [#graph-utilities]

```typescript
import { findCycle, makeAcyclic, walkTaskGraph, getDependentTasks, getTransitiveDependencies } from "@visulima/task-runner";

// Detect cycles
const cycle = findCycle(taskGraph);

// Remove cycle-forming edges
const acyclicGraph = makeAcyclic(taskGraph);

// Walk in topological order
walkTaskGraph(taskGraph, (taskId) => {
    console.log(`Processing ${taskId}`);
});
```

## Scheduling [#scheduling]

The `TaskScheduler` handles parallel execution with priority-based ordering:

1. Tasks with more dependents are scheduled first (unblocks more work)
2. Deeper projects in the dependency graph go first
3. Respects `maxParallel` concurrency limits

```typescript
import { TaskScheduler } from "@visulima/task-runner";

const scheduler = new TaskScheduler(taskGraph, projectGraph, 4);

while (!scheduler.isComplete()) {
    const batch = scheduler.getNextBatch();
    // Execute batch in parallel...
}
```


# Configuration (/docs/packages/task-runner/configuration)



# Configuration [#configuration]

All options are passed to `defaultTaskRunner` as the second argument.

## Caching [#caching]

| Option             | Type      | Default              | Description                      |
| ------------------ | --------- | -------------------- | -------------------------------- |
| `cacheDirectory`   | `string`  | `.task-runner-cache` | Cache storage directory          |
| `maxCacheSize`     | `string`  | unlimited            | Max cache size (e.g., `"1GB"`)   |
| `maxCacheAge`      | `number`  | 7 days (ms)          | Max cache entry age              |
| `skipNxCache`      | `boolean` | `false`              | Skip reading from cache          |
| `dryRun`           | `boolean` | `false`              | Compute hashes without executing |
| `cacheDiagnostics` | `boolean` | `false`              | Log cache miss reasons           |

## Targets [#targets]

These keys live on a `TargetConfiguration` (under `targetDefaults` or a project's own `targets`) and are carried onto each `Task` at graph creation.

| Option           | Type                  | Default                                        | Description                                                                                       |
| ---------------- | --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `outputs`        | `OutputSpec[]`        | `[]`                                           | Glob patterns, negations (`!dist/cache/**`), or `{ auto: true }` markers. See [Outputs](#outputs) |
| `when`           | `WhenCondition`       | -                                              | Predicate gating execution. Failing tasks are marked `"skipped"`, not failed                      |
| `always`         | `boolean`             | `false`                                        | Run after the main graph completes, even on upstream failures. See [`always`](#always-tasks)      |
| `warningPattern` | `string \| string[]`  | -                                              | JS-flavor regex(es); first match flips `TaskResult.hadWarnings`                                   |
| `cacheOnWarning` | `boolean`             | `true`                                         | When `false`, exit-0 runs that tripped `warningPattern` are not seeded into the cache             |
| `cacheRestore`   | `CacheRestoreOptions` | `{ preserveMtime: true, preservePerms: true }` | Per-target cache rehydration controls (see below)                                                 |

### `when` [#when]

`when` accepts the following predicates. All positive clauses must match (AND); array values mean any-of (OR). `not.*` mirrors apply the inverse.

| Clause   | Type                             | Notes                                                                                                  |
| -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `os`     | `NodePlatform \| NodePlatform[]` | `process.platform` values (`"linux"`, `"darwin"`, `"win32"`, ...). `"windows"` is sugar for `"win32"`. |
| `env`    | `EnvMatcher \| EnvMatcher[]`     | A bare string asserts the var is set & non-empty; the object form supports `equals` or `exists`.       |
| `branch` | `string \| string[]`             | Matches the current `git rev-parse --abbrev-ref HEAD`. Detached HEAD never matches.                    |
| `ci`     | `boolean`                        | Detects CI via the `CI` env var (truthy, not `"false"`/`"0"`).                                         |

```ts
when: { os: ["linux", "darwin"], ci: true, env: { name: "DEPLOY_TOKEN", exists: true } }
```

Tasks whose `when` returns `false` are recorded with status `"skipped"` (not `"failure"`) and never reach the executor.

### `always`-tasks [#always-tasks]

Targets marked `always: true` run **sequentially** after the main task graph completes, even if upstream tasks failed. They:

* bypass the cache (no lookup, no fingerprint, no store) — cleanup tasks are expected to run every invocation;
* still honour `when`, so a `notify-on-deploy` task can stay branch-gated;
* are skipped on SIGINT — the user's explicit ask is to stop now;
* are not part of the dependency graph and never block other tasks.

### `warningPattern` & `cacheOnWarning` [#warningpattern--cacheonwarning]

`warningPattern` is one or more JavaScript regex sources scanned against the task's combined terminal output after a `0`-exit. The first match sets `TaskResult.hadWarnings = true`. With `cacheOnWarning: false`, a warning-tainted run still surfaces `hadWarnings` but is not written to the local or remote cache.

```ts
build: {
    warningPattern: ["\\bwarning\\b", "TS\\d{4}"],
    cacheOnWarning: false,
}
```

### `outputs` [#outputs]

Each entry is one of:

| Form                 | Behavior                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `"dist/**"` (string) | Glob relative to workspace root. Literal paths and metacharacters (`* ? [ ] { }`) both supported. |
| `"!dist/cache/**"`   | Negation — applied to the combined positive set after expansion.                                  |
| `{ auto: true }`     | Use the file-access tracker's recorded writes for this run. No-op when tracking isn't active.     |

Resolved paths are deduped, sorted, and filtered to files inside the workspace before archiving.

### `cacheRestore` [#cacherestore]

Per-target overrides for how cached outputs are rehydrated.

| Field           | Type      | Default | Description                                                                |
| --------------- | --------- | ------- | -------------------------------------------------------------------------- |
| `preserveMtime` | `boolean` | `true`  | Restore each file's mtime from the captured tar header (second precision). |
| `preservePerms` | `boolean` | `true`  | Restore POSIX mode bits (low 12 bits). Ignored on Windows.                 |

Flip individually when downstream tooling needs the legacy "now"-stamped behaviour (e.g. bundlers that use newer-than-source heuristics).

## Inputs [#inputs]

| Option                 | Type          | Default                                               | Description                    |
| ---------------------- | ------------- | ----------------------------------------------------- | ------------------------------ |
| `namedInputs`          | `NamedInputs` | `{}`                                                  | Named input definitions        |
| `targetDefaults`       | `Record`      | `{}`                                                  | Default target configurations  |
| `envVars`              | `string[]`    | `[]`                                                  | Env vars to include in hash    |
| `globalInputs`         | `string[]`    | lockfiles + tsconfig.base.json + tsconfig.json + .env | Files that bust all caches     |
| `globalEnv`            | `string[]`    | `[]`                                                  | Env vars that bust all caches  |
| `smartLockfileHashing` | `boolean`     | `false`                                               | Per-package lockfile hashing   |
| `frameworkInference`   | `boolean`     | `false`                                               | Auto-detect framework env vars |

## Auto-Fingerprinting [#auto-fingerprinting]

| Option                   | Type       | Default | Description                          |
| ------------------------ | ---------- | ------- | ------------------------------------ |
| `autoFingerprint`        | `boolean`  | `false` | Enable auto-fingerprinting mode      |
| `fingerprintEnvPatterns` | `string[]` | `[]`    | Env var patterns to fingerprint      |
| `untrackedEnvVars`       | `string[]` | `[]`    | Env vars to exclude from fingerprint |

## Execution [#execution]

| Option     | Type                | Default | Description        |
| ---------- | ------------------- | ------- | ------------------ |
| `parallel` | `number \| boolean` | `3`     | Max parallel tasks |

## Remote Cache [#remote-cache]

| Option                            | Type                                             | Default       | Description                                                                                               |
| --------------------------------- | ------------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------- |
| `remoteCache.url`                 | `string`                                         | -             | Cache server URL. HTTP: `https://...`. REAPI: `grpcs://host:port` (TLS) or `grpc://host:port` (cleartext) |
| `remoteCache.token`               | `string`                                         | -             | HTTP `Authorization: Bearer …` token. HTTP-only — REAPI uses `bearerToken`                                |
| `remoteCache.teamId`              | `string`                                         | -             | Team / namespace for cache isolation                                                                      |
| `remoteCache.mode`                | `"read" \| "readwrite" \| "write"`               | `"readwrite"` | Canonical read/write flag (replaces the removed `read` / `write` boolean pair)                            |
| `remoteCache.backend`             | `"http" \| "reapi"`                              | `"http"`      | Wire protocol selector. `"reapi"` requires the optional peers `@grpc/grpc-js` + `@grpc/proto-loader`      |
| `remoteCache.compression`         | `"gzip" \| "brotli"`                             | `"gzip"`      | HTTP-only tarball compression                                                                             |
| `remoteCache.signing`             | `{ secret: string, verifyOnDownload?: boolean }` | -             | HTTP HMAC-SHA256 signing. Secret must be ≥ 16 chars. Streaming verification on download                   |
| `remoteCache.bearerToken`         | `string`                                         | -             | REAPI bearer token. Refused over `grpc://` unless `allowInsecureBearer: true`                             |
| `remoteCache.instanceName`        | `string`                                         | -             | REAPI `instance_name` for multi-tenant servers                                                            |
| `remoteCache.allowInsecureBearer` | `boolean`                                        | `false`       | Opt out of REAPI's cleartext-bearer guard (loopback / mesh-mTLS sidecar only)                             |
| `remoteCache.timeout`             | `number`                                         | `30000`       | Per-call request timeout in ms                                                                            |
| `remoteCache.onUploadError`       | `(hash, error) => void`                          | -             | Surfaces fire-and-forget upload errors (otherwise silently dropped)                                       |

The earlier `read` / `write` boolean pair was removed in favor of `mode`. There is no automatic migration — translate manually:

```ts
// before
remoteCache: { url, token, read: true, write: false }
// after
remoteCache: { url, token, mode: "read" }
```

## Output [#output]

| Option      | Type      | Default | Description               |
| ----------- | --------- | ------- | ------------------------- |
| `summarize` | `boolean` | `false` | Generate JSON run summary |


# Affected Detection (/docs/packages/task-runner/guides/affected-detection)



# Affected Detection [#affected-detection]

Affected detection uses `git diff` to determine which packages have changed since a base branch, then filters the task graph to only include tasks for those packages and their dependents.

## Usage [#usage]

```typescript
import { getChangedFiles, getAffectedProjects, filterAffectedTasks } from "@visulima/task-runner";

// Detect affected projects (uses git diff internally)
const affected = await getAffectedProjects({
    base: "main",
    head: "HEAD",
    projectGraph,
    projects,
    workspaceRoot,
});

// Filter task IDs to only affected projects
const filteredTaskIds = filterAffectedTasks(taskIds, new Set(affected.affectedProjects));
```

## Transitive Expansion [#transitive-expansion]

If package A depends on package B, and B changes, then A is also affected. The affected detection expands transitively through the project dependency graph.

## CI Integration [#ci-integration]

```typescript
const results = await defaultTaskRunner(filterAffectedTasks(taskIds, new Set(affected.affectedProjects)), options, context);
```


# Command Tokens (/docs/packages/task-runner/guides/command-tokens)



# Command Tokens [#command-tokens]

`parseCommands` and `expandTokens` substitute first-class `${…}` references in command strings so tasks like `eslint ${affected.files}` resolve to the actual file list at run time.

## Supported tokens [#supported-tokens]

| Token                                | Expands to                                                              |
| ------------------------------------ | ----------------------------------------------------------------------- |
| `${affected.files}`                  | Space-joined, shell-quoted paths from the supplied `affectedFiles` list |
| `${changed_files}`                   | Alias of `${affected.files}` — same source list, different name         |
| `${affected.files \| flag '--file'}` | One `--file <path>` pair per file: `--file 'a.ts' --file 'b.ts' …`      |
| `${changed_files \| flag "-i"}`      | Same, with double-quoted flag value                                     |

Both `'single'` and `"double"` quotes around the flag value are accepted. An empty flag value (`| flag ''`) is a no-op — the renderer emits the bare paths as if the flag were omitted.

Unknown tokens (`${UNSET_VAR}`) are left in place so the shell may expand them at runtime — silently dropping them would mask bugs in user commands.

## Path quoting & project-relative rewriting [#path-quoting--project-relative-rewriting]

* Every emitted path is run through a POSIX-aware shell quoter so spaces, quotes, `$`, and other metacharacters are escaped before they hit the shell.
* When `TokenContext.projectRoot` is set, paths are rewritten **relative to that project root** and any file outside the root is dropped. A task scoped to `packages/app` won't accidentally lint a sibling package's file.
* Affected file lists come from `git diff --name-only`, which always emits forward slashes — even on Windows.

## Escape [#escape]

Prefix with a single backslash to emit the literal token without expansion:

```
node ./scripts/render.mjs --pattern '\${affected.files}'
```

The regex consumes at most one leading backslash, so use a different surrounding quoting scheme if you need a real backslash adjacent to a token.

## Usage [#usage]

`parseCommands` runs token expansion as part of its pipeline when a `tokens` context is supplied:

```typescript
import { parseCommands, runConcurrently } from "@visulima/task-runner";

const commands = parseCommands(["eslint ${affected.files}", "prettier --write ${changed_files | flag '--file'}"], {
    tokens: {
        affectedFiles: ["packages/app/src/index.ts", "packages/lib/src/util.ts"],
        projectRoot: "packages/app", // optional — drops paths outside this root
    },
});

await runConcurrently(commands);
```

The lower-level `expandTokensInString` and `expandTokens` are also exported for callers that build their own command pipeline.


# Running Concurrent Processes (/docs/packages/task-runner/guides/concurrent-processes)



# Running Concurrent Processes [#running-concurrent-processes]

This guide covers common patterns for running multiple processes concurrently.

## Basic Usage [#basic-usage]

```typescript
import { runConcurrently } from "@visulima/task-runner";

const result = await runConcurrently(["npm run build", "npm run test", "npm run lint"]);

if (!result.success) {
    console.error("Some commands failed:");
    for (const event of result.closeEvents) {
        if (event.exitCode !== 0) {
            console.error(`  ${event.name ?? event.command}: exit ${event.exitCode}`);
        }
    }
}
```

## Command Shortcuts [#command-shortcuts]

Use `parseCommands` to expand package manager shorthand before passing to `runConcurrently`:

```typescript
import { parseCommands, runConcurrently } from "@visulima/task-runner";

const commands = parseCommands([
    "npm:build", // npm run build
    "pnpm:test", // pnpm run test
    "yarn:lint", // yarn run lint
    "bun:dev", // bun run dev
    "node:script", // node --run script
    "deno:check", // deno task check
]);

await runConcurrently(commands);
```

> **Note:** `runConcurrently` does not expand shortcuts internally. Always use `parseCommands` first if you need shortcut or wildcard expansion.

## Wildcard Expansion [#wildcard-expansion]

Expand commands against package.json scripts using `parseCommands`:

```typescript
import { parseCommands, runConcurrently } from "@visulima/task-runner";

// If package.json has: { "scripts": { "watch-js": "...", "watch-css": "...", "watch-tests": "..." } }
const commands = parseCommands(["npm:watch-*"]);
// Result: [{ command: "npm run watch-js" }, { command: "npm run watch-css" }, ...]

await runConcurrently(commands);

// Deno tasks from deno.json are also supported:
const denoCommands = parseCommands(["deno:dev-*"]);
```

## Real-Time Output Streaming [#real-time-output-streaming]

Stream stdout/stderr as lines arrive:

```typescript
await runConcurrently(["npm run build", "npm run test"], {
    onEvent: (event) => {
        switch (event.kind) {
            case "stdout":
                console.log(`[${event.index}] ${event.text}`);
                break;
            case "stderr":
                console.error(`[${event.index}] ${event.text}`);
                break;
            case "close":
                console.log(`[${event.index}] exited with ${event.exitCode}`);
                break;
            case "error":
                console.error(`[${event.index}] ${event.message}`);
                break;
        }
    },
});
```

## Controlling Parallelism [#controlling-parallelism]

Limit the number of simultaneous processes:

```typescript
// Run at most 2 processes at a time
await runConcurrently(["build-a", "build-b", "build-c", "build-d"], { maxProcesses: 2 });
```

## Kill Others on Failure [#kill-others-on-failure]

Stop all processes when one fails:

```typescript
await runConcurrently(["npm run typecheck", "npm run lint", "npm run test"], {
    killOthers: ["failure"], // Kill all if any exits non-zero
    killTimeout: 3000, // Wait 3s, then SIGKILL
});
```

## Running Dev Servers [#running-dev-servers]

For long-running processes, use `stdin: "inherit"` so the child can read keyboard input:

```typescript
await runConcurrently([
    { command: "vite dev", name: "frontend", stdin: "inherit" },
    { command: "node server.js", name: "backend" },
]);

// Ctrl+C sends SIGINT to all process groups
// Exit codes are translated to 0 (user cancellation is not failure)
```

## Retry Failed Commands [#retry-failed-commands]

Automatically restart failed commands with configurable delay:

```typescript
// Fixed delay
await runConcurrently(["flaky-build"], {
    restart: { tries: 3, delay: 1000 }, // 3 retries, 1s between each
});

// Exponential backoff (1s, 2s, 4s, 8s, ...)
await runConcurrently(["flaky-build"], {
    restart: { tries: 5, delay: "exponential" },
});
```

## Cleanup After Completion [#cleanup-after-completion]

Run teardown commands sequentially after all processes finish:

```typescript
await runConcurrently(["npm run dev", "docker compose up"], {
    teardown: ["docker compose down", "rm -rf .cache"],
});
```

## Timing Summary [#timing-summary]

Print a timing table after all commands complete:

```typescript
await runConcurrently(["npm run build", "npm run test", "npm run lint"], { timings: true });

// Output:
// ── Timing Summary ───────────────────────────────────
//
// name  │ duration │ code │ killed │ command
// ──────┼──────────┼──────┼────────┼────────────────────
// test  │ 5.2s     │ 0    │ no     │ npm run test
// build │ 3.1s     │ 0    │ no     │ npm run build
// lint  │ 1.8s     │ 0    │ no     │ npm run lint
```

## Custom Shell [#custom-shell]

Override the shell used for command execution:

```typescript
// Auto-detected from npm config (npm config set script-shell)
await runConcurrently(["echo hello"]);

// Explicit override
await runConcurrently(["echo hello"], {
    shellPath: "C:\\Program Files\\Git\\bin\\bash.exe",
});

// Direct execution (no shell)
await runConcurrently([{ command: "node build.js", shell: false }]);
```

## Argument Placeholders [#argument-placeholders]

Pass arguments to commands via placeholders:

```typescript
import { parseCommands } from "@visulima/task-runner";

const commands = parseCommands(["echo {1} {2}", "echo {@}", "echo {*}"], { additionalArguments: ["hello", "world"] });

// Results:
// echo 'hello' 'world'    ← {1} and {2} replaced individually
// echo 'hello' 'world'    ← {@} = all args, individually quoted
// echo 'hello world'      ← {*} = all args as single string
```

## Named Commands [#named-commands]

Give commands meaningful names for logging and success conditions:

```typescript
const result = await runConcurrently(
    [
        { command: "npm run build", name: "build" },
        { command: "npm run test", name: "test" },
        { command: "npm run lint", name: "lint" },
    ],
    {
        // Only "test" needs to pass
        successCondition: "command-test",
    },
);
```


# Conditional Tasks (/docs/packages/task-runner/guides/conditional-tasks)



# Conditional Tasks [#conditional-tasks]

Two target-level keys control when a task runs: `when:` (predicate gate, evaluated before execution) and `always: true` (run after the main graph regardless of upstream state).

## `when:` predicates [#when-predicates]

`when:` accepts four positive clauses and a `not.*` mirror. All positive clauses must match (AND); array values mean any-of (OR). Tasks whose `when` evaluates to `false` are recorded with status `"skipped"` (not `"failure"`) and never reach the executor.

| Clause   | Type                             | Example                                                                    |
| -------- | -------------------------------- | -------------------------------------------------------------------------- |
| `os`     | `NodePlatform \| NodePlatform[]` | `os: "linux"` — `"windows"` is sugar for `"win32"`                         |
| `env`    | `EnvMatcher \| EnvMatcher[]`     | `env: "DEPLOY_TOKEN"` (set & non-empty) or `{ name, equals?, exists? }`    |
| `branch` | `string \| string[]`             | `branch: ["main", "alpha"]` — matches `git rev-parse --abbrev-ref HEAD`    |
| `ci`     | `boolean`                        | `ci: true` — detects CI via `process.env.CI` (truthy, not `"false"`/`"0"`) |

### Examples [#examples]

Run a release task only on `main`, only in CI, and only when a deploy token is present:

```ts
targets: {
    deploy: {
        command: "node ./scripts/deploy.mjs",
        when: {
            branch: "main",
            ci: true,
            env: { name: "DEPLOY_TOKEN", exists: true },
        },
    },
}
```

Skip a task on Windows without an explicit alternative:

```ts
targets: {
    "build:native": {
        command: "make native",
        when: { not: { os: "windows" } },
    },
}
```

Match an exact env value:

```ts
when: {
    env: { name: "NODE_ENV", equals: "production" },
}
```

## `always:` finally-tasks [#always-finally-tasks]

Targets marked `always: true` run **sequentially** after the main task graph completes — even if upstream tasks failed. They are intended for cleanup, teardown, or notifications.

Behaviour:

* bypass the cache entirely (no lookup, no fingerprint, no store) — every invocation re-runs;
* still honour `when`, so an `always`-task can stay branch- or env-gated;
* skipped on SIGINT — the user's explicit ask is to stop now;
* not part of the dependency graph and never block other tasks.

```ts
targets: {
    "notify-slack": {
        always: true,
        command: "node ./scripts/notify.mjs",
        when: { ci: true, branch: "main" },
    },
}
```

## Combining the two [#combining-the-two]

A common shape is a CI-only finally-task that posts a build status regardless of outcome:

```ts
targets: {
    "build-status": {
        always: true,
        command: "node ./scripts/post-status.mjs",
        when: { ci: true },
    },
}
```

The skipped status surfaces through `printWhenSkip(task, reason)` on `LifeCycleInterface` (with a short diagnostic such as `branch=feat/foo does not match "main"`) and as the standard `"skipped"` status in run summaries.


# Cooperative Cache Hints (/docs/packages/task-runner/guides/cooperative-cache-hints)



# Cooperative Cache Hints [#cooperative-cache-hints]

Auto-fingerprinting **observes** a task — it watches file syscalls and resolves the env patterns you declare in config. That covers unmodified tools, but a tool knows things the runner can't observe: which reads are throw-away cache noise, which writes are scratch, when a run is non-deterministic, and — most importantly for cache correctness — **which environment variables it actually reads**.

[`@visulima/task-runner-client`](https://www.npmjs.com/package/@visulima/task-runner-client) lets a task *tell* the runner. It's a zero-dependency package; outside a runner-managed task every call is a no-op, so it's safe to ship in a tool used both standalone and under the runner.

```sh
npm install @visulima/task-runner-client
```

## Tracking environment variables [#tracking-environment-variables]

This is the headline use case. Declaring env patterns in config (`env: ["VITE_*"]`) works, but it has two weaknesses:

* **Over-tracking** — `VITE_*` busts the cache when *any* matching var changes, even one the build never reads.
* **Silent under-tracking** — read `MY_FLAG` without listing it, and a change to it produces a **stale cache hit** with no warning. This is the dangerous one.

`getEnv` closes both gaps by registering the dependency **at the point of use** — reading and tracking become the same call, so you can't forget:

```ts
import { getEnv, getEnvs } from "@visulima/task-runner-client";

// Reads process.env.API_URL AND registers it as a cache dependency.
// Change API_URL → this task's cache entry is invalidated. Leave it
// unchanged → the cached result is reused.
const apiUrl = getEnv("API_URL");

// Glob form: every matching var becomes a dependency, and adding /
// removing / changing any VITE_* var busts the entry.
const viteEnv = getEnvs("VITE_*");

// Read without tracking (value only, no cache dependency):
const ci = getEnv("CI", { tracked: false });
```

### How it relates to config `env` patterns [#how-it-relates-to-config-env-patterns]

The two are additive, not exclusive. Patterns you set in config still apply to every task; `getEnv`/`getEnvs` add **per-task** dependencies on top. Use config patterns for workspace-wide vars (`NODE_ENV`) and `getEnv` inside a tool for the vars only it knows it consumes. A changed value from *either* source invalidates the cache via the same `env-changed` check.

## Refining inferred inputs and outputs [#refining-inferred-inputs-and-outputs]

```ts
import { disableCache, ignoreInput, ignoreOutput } from "@visulima/task-runner-client";

// Our own cache dir is read every run but isn't a real input — don't
// let it into the fingerprint.
ignoreInput("node_modules/.cache/my-tool");

// A scratch file we write but that isn't a build artifact.
ignoreOutput(".my-tool-tmp");

// This run hit the network / ran in debug mode / was aborted — don't
// cache it at all.
if (nonDeterministic) {
    disableCache();
}
```

Relative paths resolve against the task's working directory.

## API [#api]

| Function                         | Effect                                                                                             |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `getEnv(name, { tracked? })`     | Return `process.env[name]`; with `tracked` (default `true`) register `name` as a cache dependency. |
| `getEnvs(pattern, { tracked? })` | Return env matching the `*`-glob; with `tracked` (default `true`) register the pattern.            |
| `ignoreInput(path)`              | Drop reads under `path` from inferred cache inputs.                                                |
| `ignoreOutput(path)`             | Drop writes under `path` from inferred cache outputs.                                              |
| `disableCache()`                 | Mark this run non-deterministic — the runner won't cache it.                                       |

## How it works [#how-it-works]

The runner sets `TASK_RUNNER_HINTS` to a per-task file path before spawning the command. Each client call appends one NDJSON line to that file (synchronous + append-only, so a hint survives even if the tool crashes right after). After the command exits, the runner reads the file and folds the hints into the fingerprint before it's sealed — `getEnv` names are added to the env set, `ignoreInput`/`ignoreOutput` filter the observed accesses, and `disableCache` skips the cache write. Because the transport is a plain file, it works on **every platform**, not just where syscall tracking is available.

## Seeing what was tracked [#seeing-what-was-tracked]

Run with `summarize: true` (or `vis run --summarize`) and each task entry records the provenance:

```json
{
    "taskId": "web:build",
    "cacheSkipReason": "disabled-by-task",
    "cacheHints": {
        "ignoredInputs": ["/repo/apps/web/node_modules/.cache/vite"],
        "ignoredOutputs": [],
        "trackedEnv": ["API_URL"],
        "trackedEnvPatterns": ["VITE_*"]
    }
}
```

`cacheSkipReason` explains why a task that ran seeded no cache entry — `disabled-by-task`, `self-modified`, or `empty-fingerprint`. Under `vis` each of these also prints an inline notice (e.g. `ⓘ <task>: caching disabled by task via disableCache()`).

## Adopting tools written for vite-task [#adopting-tools-written-for-vite-task]

A tool that already imports [`@voidzero-dev/vite-task-client`](https://github.com/voidzero-dev/vite-task/tree/main/packages/vite-task-client) emits nothing here — that client only talks to vite+'s addon. Because `@visulima/task-runner-client` is an API-compatible drop-in, you can alias it with a package-manager override:

```yaml
# pnpm-workspace.yaml (or package.json "pnpm.overrides")
overrides:
    "@voidzero-dev/vite-task-client": "npm:@visulima/task-runner-client@^1"
```

`vis run` detects the vite client in your workspace and offers to add this override automatically (interactive TTY only — it remembers a decline and never prompts in CI). See the [`@visulima/task-runner-client` README](https://www.npmjs.com/package/@visulima/task-runner-client) for the npm/yarn forms.


# Framework Inference (/docs/packages/task-runner/guides/framework-inference)



# Framework Inference [#framework-inference]

Framework inference automatically detects frontend frameworks in your projects and includes their public environment variable prefixes in task hashes. This ensures cache correctness when framework-specific env vars change.

## Enable [#enable]

```typescript
const results = await defaultTaskRunner(
    tasks,
    {
        frameworkInference: true,
    },
    context,
);
```

## Detected Frameworks [#detected-frameworks]

| Framework        | Package                               | Env Prefix       |
| ---------------- | ------------------------------------- | ---------------- |
| Next.js          | `next`                                | `NEXT_PUBLIC_*`  |
| Vite             | `vite`                                | `VITE_*`         |
| Create React App | `react-scripts`                       | `REACT_APP_*`    |
| Gatsby           | `gatsby`                              | `GATSBY_*`       |
| Nuxt             | `nuxt`, `nuxt3`                       | `NUXT_PUBLIC_*`  |
| Expo             | `expo`                                | `EXPO_PUBLIC_*`  |
| Remix            | `@remix-run/react`, `@remix-run/node` | `REMIX_PUBLIC_*` |
| Astro            | `astro`                               | `PUBLIC_*`       |
| SvelteKit        | `@sveltejs/kit`                       | `PUBLIC_*`       |
| Solid Start      | `@solidjs/start`, `solid-start`       | `VITE_*`         |

## How It Works [#how-it-works]

1. Read each project's `package.json`
2. Check `dependencies` and `devDependencies` for known framework packages
3. For detected frameworks, scan `process.env` for matching prefixes
4. Include matching env vars in the task hash

## Works with Auto-Fingerprinting [#works-with-auto-fingerprinting]

When both `frameworkInference` and `autoFingerprint` are enabled, the inferred env patterns are automatically merged into `fingerprintEnvPatterns`:

```typescript
{
    autoFingerprint: true,
    frameworkInference: true,
    // No need to manually add fingerprintEnvPatterns for frameworks
}
```

## Standalone Usage [#standalone-usage]

```typescript
import { detectFrameworks, getFrameworkEnvVariables } from "@visulima/task-runner";

const frameworks = await detectFrameworks("/path/to/package.json");
// [{ name: "Next.js", envPrefixes: ["NEXT_PUBLIC_"] }]

const envVars = await getFrameworkEnvVariables("/path/to/package.json");
// { NEXT_PUBLIC_API_URL: "https://...", NEXT_PUBLIC_GA_ID: "G-..." }
```


# Graph Visualization (/docs/packages/task-runner/guides/graph-visualization)



# Graph Visualization [#graph-visualization]

The task runner provides multiple output formats for visualizing task graphs and project dependency graphs.

## Formats [#formats]

### DOT (Graphviz) [#dot-graphviz]

```typescript
import { toGraphvizDot } from "@visulima/task-runner";

const dot = toGraphvizDot(taskGraph, {
    focusedTasks: ["app:build"], // Highlight specific tasks
    taskStatuses: taskStatusMap, // Color by execution status
    groupByProject: true, // Group tasks by project
});

// Render with: dot -Tpng graph.dot -o graph.png
```

### JSON [#json]

```typescript
import { toGraphJson } from "@visulima/task-runner";

const json = toGraphJson(taskGraph);
// { nodes: [...], edges: [...] }
```

### HTML (Self-contained) [#html-self-contained]

```typescript
import { toGraphHtml } from "@visulima/task-runner";

const html = toGraphHtml(taskGraph);
// Self-contained HTML page with embedded visualization
```

### ASCII [#ascii]

```typescript
import { toGraphAscii } from "@visulima/task-runner";

const ascii = toGraphAscii(taskGraph);
// app:build
//   ├── lib-a:build
//   │   └── shared:build
//   └── lib-b:build
//       └── shared:build (*)
```

### Project Graph [#project-graph]

```typescript
import { projectGraphToDot } from "@visulima/task-runner";

const dot = projectGraphToDot(projectGraph);
// Generates DOT with different colors for applications vs libraries
// and dashed edges for implicit dependencies
```


# Run Summaries (/docs/packages/task-runner/guides/run-summaries)



# Run Summaries [#run-summaries]

Run summaries generate a detailed JSON report after execution, capturing task inputs, hashes, timings, cache status, and environment info. Useful for debugging cache misses and comparing runs.

## Enable [#enable]

```typescript
const results = await defaultTaskRunner(
    tasks,
    {
        summarize: true,
    },
    context,
);
```

## Output [#output]

Summary files are written to `.task-runner/runs/{run-id}.json`:

```json
{
    "id": "2026-03-21T18-00-00-000Z_abc123",
    "startTime": "2026-03-21T18:00:00.000Z",
    "endTime": "2026-03-21T18:00:05.000Z",
    "duration": 5000,
    "tasks": [
        {
            "taskId": "app:build",
            "target": { "project": "app", "target": "build" },
            "hash": "a1b2c3d4...",
            "hashDetails": {
                "command": "...",
                "nodes": { "src/index.ts": "..." },
                "runtime": { "env:NODE_ENV": "..." }
            },
            "cacheStatus": "MISS",
            "exitCode": 0,
            "duration": 3000,
            "dependencies": ["lib:build"],
            "cacheable": true
        }
    ],
    "taskGraph": {
        "dependencies": {
            "app:build": ["lib:build"],
            "lib:build": []
        },
        "roots": ["lib:build"]
    },
    "stats": {
        "total": 5,
        "succeeded": 3,
        "failed": 0,
        "cached": 2,
        "skipped": 0
    },
    "environment": {
        "nodeVersion": "v22.0.0",
        "platform": "linux",
        "arch": "x64"
    }
}
```

## Cache Status Values [#cache-status-values]

* **HIT** - Local cache hit
* **REMOTE\_HIT** - Remote cache hit
* **MISS** - No cache, task executed
* **SKIPPED** - Dry-run mode

## Standalone Usage [#standalone-usage]

```typescript
import { generateRunSummary, writeRunSummary } from "@visulima/task-runner";

const summary = generateRunSummary(results, taskGraph, startTime);
const filePath = await writeRunSummary(summary, workspaceRoot);
```

## Last-run replay (`last-summary.json`) [#last-run-replay-last-summaryjson]

The orchestrator writes a `.task-runner/last-summary.json` after every completed run regardless of whether `summarize` is enabled. It's a single overwritten file — always the most-recent run — designed for CLIs that want to show "last run details" without re-executing.

```typescript
import { readLastRunSummary } from "@visulima/task-runner";

const previous = await readLastRunSummary(workspaceRoot);

if (previous) {
    console.log(`Last run: ${previous.stats.succeeded} succeeded, ${previous.stats.failed} failed`);
}
```

`readLastRunSummary` returns `undefined` when no previous run exists or the file can't be parsed. Treat it as an informational lookup, not a hard dependency.

Interrupted runs (Ctrl-C) are not persisted — the incomplete snapshot would mislead callers.

## Chrome Tracing Profile [#chrome-tracing-profile]

For visual timeline analysis, convert a summary to Chrome Tracing JSON:

```typescript
import { writeChromeTrace } from "@visulima/task-runner";

await writeChromeTrace(summary, "trace.json");
```

Open the file in `chrome://tracing` or [Perfetto](https://ui.perfetto.dev) to see a gantt of task execution with dependency arrows. Parallel tasks are packed into separate lanes automatically — useful for spotting over-serialized `dependsOn` chains.


# Smart Lockfile Hashing (/docs/packages/task-runner/guides/smart-lockfile-hashing)



# Smart Lockfile Hashing [#smart-lockfile-hashing]

By default, lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock) are included in the global hash. This means **any** lockfile change invalidates **every** task's cache.

Smart lockfile hashing parses the lockfile and only hashes the resolved versions of each package's actual dependencies. A lockfile change only busts cache for affected packages.

## Enable [#enable]

```typescript
const results = await defaultTaskRunner(
    tasks,
    {
        smartLockfileHashing: true,
    },
    context,
);
```

## How It Works [#how-it-works]

1. **Parse lockfile** - Reads package-lock.json, pnpm-lock.yaml, or yarn.lock
2. **Read package.json** - Gets each project's declared dependencies
3. **Filter** - Extract only the resolved versions relevant to each project
4. **Hash** - Include filtered versions in the task hash as `__lockfile__` implicit dep

## Supported Lockfile Formats [#supported-lockfile-formats]

* **package-lock.json** - npm v1, v2, v3
* **pnpm-lock.yaml** - pnpm v6+
* **yarn.lock** - Yarn Classic (v1) and Berry (v2+)

## Example [#example]

Given a monorepo with packages A (depends on lodash) and B (depends on express):

* Updating lodash in the lockfile → only package A's cache is busted
* Updating express in the lockfile → only package B's cache is busted
* Updating both → both caches are busted

## Standalone Usage [#standalone-usage]

```typescript
import { LockfileHasher } from "@visulima/task-runner";

const hasher = new LockfileHasher("/path/to/workspace");
const result = await hasher.hashForPackage("packages/my-app/package.json");

console.log(result?.hash); // SHA-256 hash of resolved deps
console.log(result?.dependencies); // [{ name: "lodash", version: "4.17.21" }]
console.log(hasher.lockfileType); // "npm" | "pnpm" | "yarn"
```


# Introduction (/docs/packages/task-runner)



# Task Runner [#task-runner]

**High-performance monorepo task runner with intelligent caching, dependency-aware scheduling, and auto-fingerprinting.**

`@visulima/task-runner` provides the core building blocks for running tasks in monorepos with maximum cache hit rates. It supports both explicit input declarations (like Nx) and automatic file access tracking (like Vite Task).

## Why Task Runner? [#why-task-runner]

* **Concurrent process runner** - Run multiple commands in parallel with native Rust performance and JS fallback
* **Process tree management** - Clean signal propagation via setsid/killpg (Unix) and Job Objects (Windows)
* **Command parser** - `npm:build` shortcuts, `npm run watch-*` wildcards, `{1}` argument placeholders
* **npm script-shell support** - Honors `npm config set script-shell` for custom shells
* **Long-running processes** - Configurable stdin (null/pipe/inherit), bounded output buffers
* **Two caching modes** - Choose Nx-style explicit inputs or Vite Task-style auto-fingerprinting
* **Smart lockfile hashing** - Lockfile changes only bust cache for affected packages
* **Framework env inference** - Auto-detects Next.js, Vite, CRA, Gatsby, Nuxt, Expo, and more
* **Remote caching** - Turborepo-compatible HTTP cache protocol
* **Native Rust addon** - Parallel file hashing (xxHash) and concurrent process management via tokio
* **Dependency-aware scheduling** - Topological ordering with priority-based batching
* **Incremental hashing** - mtime-based change detection for near-instant cache checks
* **Affected detection** - Git diff-based filtering
* **Run summaries** - Detailed JSON reports for debugging cache behavior
* **Cache diagnostics** - Explains exactly why a cache miss occurred

## Quick Start [#quick-start]

```typescript
import { defaultTaskRunner } from "@visulima/task-runner";

const results = await defaultTaskRunner(
    tasks,
    {
        smartLockfileHashing: true,
        frameworkInference: true,
        globalInputs: ["pnpm-lock.yaml", "tsconfig.base.json"],
        globalEnv: ["NODE_ENV"],
    },
    context,
);
```

## How It Works [#how-it-works]

1. **Build the task graph** - Define tasks and their dependencies
2. **Compute cache keys** - Hash file contents, env vars, and command arguments
3. **Check cache** - Skip execution if inputs haven't changed
4. **Execute tasks** - Run in parallel, respecting dependency order
5. **Store results** - Cache terminal output and build artifacts for next time

## Comparison [#comparison]

| Feature             | Task Runner | Nx       | Turborepo | Vite Task     |
| ------------------- | ----------- | -------- | --------- | ------------- |
| Input detection     | Both modes  | Explicit | Explicit  | Automatic     |
| Output caching      | Yes         | Yes      | Yes       | Terminal only |
| Remote cache        | Yes         | Yes      | Yes       | No            |
| Smart lockfile hash | Yes         | No       | Yes       | No            |
| Framework inference | Yes         | No       | Yes       | No            |
| Auto-fingerprinting | Yes         | No       | No        | Yes           |
| Cache diagnostics   | Yes         | Partial  | No        | Yes           |
| LRU cache eviction  | Yes         | No       | No        | No            |
| Graph visualization | Yes         | Yes      | No        | No            |
| Run summaries       | Yes         | No       | Yes       | No            |


# Installation (/docs/packages/task-runner/installation)



# Installation [#installation]

## Package Managers [#package-managers]

### npm [#npm]

```bash
npm install @visulima/task-runner
```

### yarn [#yarn]

```bash
yarn add @visulima/task-runner
```

### pnpm [#pnpm]

```bash
pnpm add @visulima/task-runner
```

## Requirements [#requirements]

* **Node.js**: 20.19 or higher
* **TypeScript**: Optional but recommended for full type safety

## Optional: Native Addon [#optional-native-addon]

For maximum performance, the task runner includes an optional Rust-based native addon that provides:

* **xxHash xxh3-128** file hashing (5-10x faster than SHA-256)
* **Parallel file hashing** via rayon (utilizes all CPU cores)

The native addon is loaded automatically when available and falls back to pure TypeScript implementations otherwise. No additional installation is required.


# API Reference (/docs/packages/tsconfig/api)



# API Reference [#api-reference]

## findTsConfig() / findTsConfigSync() [#findtsconfig--findtsconfigsync]

Find a tsconfig.json file by searching upward (falling back to jsconfig.json). `findTsConfig` is asynchronous; `findTsConfigSync` is the synchronous variant. Throws when no config file is found.

**Signature:**

```typescript
function findTsConfig(cwd?: URL | string, options?: FindTsConfigOptions): Promise<TsConfigResult>;

function findTsConfigSync(cwd?: URL | string, options?: FindTsConfigOptions): TsConfigResult;
```

**Options (`FindTsConfigOptions`, extends `ReadTsConfigOptions`):**

* `configFileName` - Name of the file to search for. Defaults to `"tsconfig.json"`. Supplying a custom name disables the `jsconfig.json` fallback.
* `cache` - `boolean | Map<string, TsConfigResult>`. `true` uses a process-wide cache; pass a `Map` for a caller-owned cache. Keys embed the file mtime, so on-disk edits invalidate cached entries automatically.
* `tscCompatible`, `typescriptVersion` - forwarded to `readTsConfig`.

> Only the upward file search is async. Parsing (including the full `extends` chain) is synchronous.

## readTsConfig() [#readtsconfig]

Read and parse a tsconfig.json file. **This function is synchronous** — it returns the resolved config object directly (no `await`).

**Signature:**

```typescript
function readTsConfig(
    tsconfigPath: string,
    options?: {
        tscCompatible?: "5.4" | "5.5" | "5.6" | "5.7" | "5.8" | "5.9" | "6.0" | true;
        typescriptVersion?: "auto" | false | string;
    },
): TsConfigJsonResolved;
```

**Options:**

* `tscCompatible` - Synthesize the *derived* defaults TypeScript would imply from other options for the given version (e.g. `module: nodenext` ⇒ `moduleResolution: nodenext`). `true` targets the latest supported version. Default `undefined`.
* `typescriptVersion` - Apply the *unconditional* compiler-option defaults of a TypeScript version. `"auto"` detects the installed version (including Yarn PnP); a string pins an explicit version; `false` (default) applies none. Can be combined with `tscCompatible`.

## writeTsConfig() / writeTsConfigSync() [#writetsconfig--writetsconfigsync]

Write the provided TypeScript configuration object to a tsconfig.json file. `writeTsConfig` is asynchronous; `writeTsConfigSync` is the synchronous variant.

**Signature:**

```typescript
function writeTsConfig(tsConfig: TsConfigJson, options?: WriteJsonOptions & { cwd?: URL | string }): Promise<void>;

function writeTsConfigSync(tsConfig: TsConfigJson, options?: WriteJsonOptions & { cwd?: URL | string }): void;
```

**Options:**

* `cwd` - Directory to write tsconfig.json (plus any `@visulima/fs` `WriteJsonOptions`).

## TsConfig Type [#tsconfig-type]

```typescript
interface TsConfig {
    extends?: string | string[];
    compilerOptions?: CompilerOptions;
    include?: string[];
    exclude?: string[];
    files?: string[];
    references?: ProjectReference[];
    // ... all TypeScript config options
}
```


# Introduction (/docs/packages/tsconfig)



# @visulima/tsconfig [#visulimatsconfig]

Find, read, and parse TypeScript configuration files with full extends resolution, comment support, and validation against TypeScript's schema.

## Key Features [#key-features]

* **Find tsconfig.json** - Search from any directory
* **Parse with Comments** - Supports comments and trailing commas
* **Resolve Extends** - Automatically resolves extends paths
* **Validate** - Validates configuration against TypeScript schema
* **Write Config** - Write tsconfig.json files
* **TypeScript Compatible** - Tested against TypeScript for correctness
* **Fully Typed** - Complete TypeScript definitions

## Quick Start [#quick-start]

```typescript
import { findTsConfig, readTsConfig } from "@visulima/tsconfig";

// Find tsconfig.json
const result = await findTsConfig();
console.log(result.config.compilerOptions);

// Read specific tsconfig (synchronous — no await)
const config = readTsConfig("/path/to/tsconfig.json");
```

## Use Cases [#use-cases]

```typescript
// Build tools
import { findTsConfig } from "@visulima/tsconfig";

const { config } = await findTsConfig();
const outDir = config.compilerOptions?.outDir || "dist";

// Config generation
import { writeTsConfig } from "@visulima/tsconfig";

await writeTsConfig({
    compilerOptions: {
        target: "ES2020",
        module: "ESNext",
        strict: true,
    },
});
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/tsconfig/installation">
    Install and import
  </Card>

  <Card title="Usage" href="/docs/packages/tsconfig/usage">
    Usage guide
  </Card>

  <Card title="API" href="/docs/packages/tsconfig/api">
    API reference
  </Card>
</Cards>


# Installation (/docs/packages/tsconfig/installation)



# Installation [#installation]

```bash npm2yarn
npm install @visulima/tsconfig
```

## Import [#import]

```typescript
import { findTsConfig, readTsConfig, writeTsConfig } from "@visulima/tsconfig";
```

## Requirements [#requirements]

* **Node.js:** 22.13 or higher


# Usage (/docs/packages/tsconfig/usage)



# Usage Guide [#usage-guide]

## Find tsconfig.json [#find-tsconfigjson]

```typescript
import { findTsConfig } from "@visulima/tsconfig";

const result = await findTsConfig();
// => {
//   path: "/path/to/tsconfig.json",
//   config: { compilerOptions: { ... } }
// }

// From specific directory
const result2 = await findTsConfig("/path/to/project");
```

## Read tsconfig.json [#read-tsconfigjson]

`readTsConfig` is synchronous — it returns the resolved config directly (no `await`).

```typescript
import { readTsConfig } from "@visulima/tsconfig";

const config = readTsConfig("/path/to/tsconfig.json");

// Match the derived defaults of a specific TypeScript version
const config2 = readTsConfig("/path/to/tsconfig.json", {
    tscCompatible: "5.8",
});

// Apply the unconditional defaults of the installed TypeScript
const config3 = readTsConfig("/path/to/tsconfig.json", {
    typescriptVersion: "auto",
});
```

## Write tsconfig.json [#write-tsconfigjson]

```typescript
import { writeTsConfig } from "@visulima/tsconfig";

await writeTsConfig({
    compilerOptions: {
        target: "ES2022",
        module: "ESNext",
        moduleResolution: "bundler",
        strict: true,
    },
});

// Custom path
await writeTsConfig(config, { cwd: "./packages/app" });
```

## Extends Resolution [#extends-resolution]

```typescript
import { readTsConfig } from "@visulima/tsconfig";

// Automatically resolves extends
const config = readTsConfig("/path/to/tsconfig.json");
// Merges base configurations from extends field
```


# README (/docs/packages/tui/README)



# Docs maintainer notes [#docs-maintainer-notes]

## Conventions [#conventions]

* **Tone:** direct and technical.
* **Links:** use relative links (e.g. `[Hooks](hooks.md)`).
* **Code blocks:** always include language tags (`tsx`, `ts`, `bash`).
* **Accuracy first:** verify behavior against source before documenting it.

## Page ownership [#page-ownership]

| Page                           | Source of truth                                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `package-map.md`               | `packages/*/package.json`, package README files                                                          |
| `components.md`                | `../react/src/react.ts`, `../react/src/styles.ts`, `../react/src/renderer.ts`                            |
| `hooks.md`                     | `../react/src/hooks.ts`, `../react/src/focus.ts`, `../core/src/input.ts`                                 |
| `ink-compat.md`                | `../react/src/react.ts`, `../react/src/hooks.ts`, `../../compat-test/`                                   |
| `raw-buffer.md`                | `../core/src/lib.rs`, `../core/src/terminal.rs`, `../core/src/inline.ts`, `../core/index.d.ts`           |
| `ts-buffer-guide.md`           | `../core/src/lib.rs`, `../core/src/cell.ts`, `../../examples-raw/harness.ts`                             |
| `why-is-ink-slow.md`           | `../react/src/renderer.ts`, `../core/src/lib.rs`, `../../benchmark/startup/`, `../ink/src/`              |
| `ink-performance-plan.md`      | `why-is-ink-slow.md`, `../ink/benchmark/` outputs, maintainer roadmap decisions                          |
| `render-loop.md`               | `../react/src/react.ts`, `../core/src/app.ts`, `../react/src/reconciler.ts`                              |
| `renderer-correctness-plan.md` | `../react/__test__/renderer-xterm-roundtrip.spec.ts`, `../react/src/text-width.ts`, `../core/src/lib.rs` |
| `decisions.md`                 | Maintainer-updated architecture log                                                                      |
| `examples.md`                  | `../../examples/`, `../../examples-raw/`                                                                 |

## Update checklist [#update-checklist]

When API behavior changes:

1. Update reference docs (`components.md`, `hooks.md`, `ink-compat.md`)
2. Update quickstarts if entry flow changed
3. Update `examples.md` for renamed/added/removed demos
4. Validate internal links
5. Run at least one relevant example

## Adding a new page [#adding-a-new-page]

1. Create `packages/docs/<name>.md`
2. Add it to `packages/docs/index.md`
3. Cross-link from related pages

## GitHub Pages config [#github-pages-config]

Pages config lives in `packages/docs/_config.yml` (Jekyll/minima).


# Components (/docs/packages/tui/components)



# Components [#components]

`@visulima/tui` exposes Ink-compatible core components plus native renderer additions.

```tsx
import { Box } from "@visulima/tui/components/box";
import { Cursor } from "@visulima/tui/components/cursor";
import { Newline } from "@visulima/tui/components/newline";
import { Spacer } from "@visulima/tui/components/spacer";
import { Static } from "@visulima/tui/components/static";
import { Text } from "@visulima/tui/components/text";
import { Transform } from "@visulima/tui/components/transform";
import { ConfirmInput } from "@visulima/tui/components/confirm-input";
import { FilePicker } from "@visulima/tui/components/file-picker";
import { Gradient } from "@visulima/tui/components/gradient";
import { Help } from "@visulima/tui/components/help";
import { MultiSelect } from "@visulima/tui/components/multi-select";
import { Paginator } from "@visulima/tui/components/paginator";
import { ProgressBar } from "@visulima/tui/components/progress-bar";
import { SelectInput } from "@visulima/tui/components/select-input";
import { Spinner } from "@visulima/tui/components/spinner";
import { Stopwatch } from "@visulima/tui/components/stopwatch";
import { Tab } from "@visulima/tui/components/tab";
import { Tabs } from "@visulima/tui/components/tabs";
import { TextInput } from "@visulima/tui/components/text-input";
import { Timer } from "@visulima/tui/components/timer";
```

### Heavy components (subpath imports) [#heavy-components-subpath-imports]

`BigText`, `Code`, `DiffView`, `Markdown` and `Table` each ship with at least one heavy optional peer dependency. They are exported from per-component subpaths so the optional deps are only loaded when you actually import the component.

```tsx
import { BigText } from "@visulima/tui/components/big-text"; // requires: cfonts
import { Code } from "@visulima/tui/components/code"; // requires: shiki, @shikijs/langs, @shikijs/themes
import { DiffView } from "@visulima/tui/components/diff-view"; // requires: diff (+ shiki for syntax highlighting)
import { Markdown } from "@visulima/tui/components/markdown"; // requires: marked (+ shiki for code blocks)
import { Table } from "@visulima/tui/components/table"; // requires: @visulima/tabular
```

See the [Package Map › Heavy component subpaths](/docs/packages/tui/package-map#heavy-component-subpaths) table for a full peer-dep matrix and `npm install` commands.

## `Box` [#box]

Layout primitive backed by Yoga.

```tsx
<Box
    flexDirection="row" // row | column | row-reverse | column-reverse
    flexGrow={1}
    flexShrink={1}
    width={40}
    height={10}
    minWidth={10}
    minHeight={4}
    padding={1}
    paddingX={2}
    margin={1}
    gap={1}
    alignItems="center"
    justifyContent="space-between"
    borderStyle="round" // single | double | round | bold | classic | singleDouble | doubleSingle
    borderColor="cyan"
    borderBackgroundColor="blue"
    borderTop={true}
    borderRight={true}
    borderBottom={true}
    borderLeft={true}
>
    {children}
</Box>
```

### Overflow and CSS-Level Scrolling [#overflow-and-css-level-scrolling]

`Box` supports CSS-level scrolling via `overflow: 'scroll'`. This is separate from the component-based `ScrollView` and provides native-style overflow clipping with integrated scrollbar rendering.

```tsx
<Box
    overflow="scroll" // visible | hidden | scroll
    overflowX="hidden" // per-axis overflow control
    overflowY="scroll" // per-axis overflow control
    scrollTop={0} // vertical scroll position (rows)
    scrollLeft={0} // horizontal scroll position (columns)
    scrollbarThumbColor="gray" // scrollbar thumb color
    scrollbar={true} // show/hide scrollbar (default: true)
    height={10}
    width={40}
>
    {longContent}
</Box>
```

### Sticky Headers [#sticky-headers]

Elements within a scrollable `Box` can be pinned to the top or bottom of the viewport using the `sticky` prop. A sticky header remains pinned only while its parent section is visible.

```tsx
<Box overflow="scroll" height={15}>
    <Box sticky>
        <Text bold>Section A</Text>
    </Box>
    {sectionAContent}

    <Box sticky>
        <Text bold>Section B</Text>
    </Box>
    {sectionBContent}
</Box>
```

| Prop        | Type                           | Description                                                                                       |
| ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `sticky`    | `boolean \| 'top' \| 'bottom'` | Pin this element during scroll. `true` and `'top'` pin to the top; `'bottom'` pins to the bottom. |
| `opaque`    | `boolean`                      | Marks this element as opaque for rendering optimization (not yet active).                         |
| `scrollbar` | `boolean`                      | Show/hide the scrollbar for scrollable elements. Defaults to `true`.                              |

Notes:

* `Box` defaults to `flexDirection="row"` unless you set it explicitly.
* Border side toggles (`borderTop`, etc.) are supported.
* Per-side border colors are supported: `borderTopColor`, `borderBottomColor`, `borderLeftColor`, `borderRightColor`.
* Per-side border background colors are supported: `borderTopBackgroundColor`, `borderBottomBackgroundColor`, `borderLeftBackgroundColor`, `borderRightBackgroundColor`.
* Per-side dim is supported: `borderTopDimColor`, `borderBottomDimColor`, `borderLeftDimColor`, `borderRightDimColor`.

## `Text` [#text]

Renders styled text.

```tsx
<Text
    color="cyan" // named, #rgb, #rrggbb, rgb(r,g,b), or ANSI index 0-255
    backgroundColor="blue"
    bold
    italic
    underline
    strikethrough
    dim
    inverse
>
    Hello world
</Text>
```

`dimColor` is supported as an Ink-compat alias for `dim`.

## `Cursor` [#cursor]

Declaratively position the terminal cursor. Two modes are available:

### Inline mode (no props) [#inline-mode-no-props]

Place `<Cursor />` after a `<Text>` node. The cursor appears where the preceding text ended, even when text wraps across lines.

```tsx
<Box>
    <Text>{prompt + value}</Text>
    <Cursor />
</Box>
```

This is the recommended approach for text inputs. It handles text wrapping, wide characters (CJK, emoji), and multi-line output automatically because the cursor position is derived from the actual rendered text output.

For editable text with a cursor position in the middle:

```tsx
<Box>
    <Text>{value.slice(0, cursorPos)}</Text>
    <Cursor />
    <Text>{value.slice(cursorPos)}</Text>
</Box>
```

### Anchor mode [#anchor-mode]

Pass `anchorRef` and/or `x`/`y` to position the cursor relative to another element's content origin.

```tsx
const ref = useRef(null);

<Box ref={ref}>
    <Text>{content}</Text>
</Box>
<Cursor anchorRef={ref} x={5} y={1} />
```

| Prop        | Type                         | Default     |
| ----------- | ---------------------------- | ----------- |
| `anchorRef` | `RefObject<DOMElement/null>` | parent node |
| `x`         | `number`                     | `0`         |
| `y`         | `number`                     | `0`         |

Notes:

* `<Cursor>` must not be rendered inside `<Text>`.
* If multiple `<Cursor>` components are rendered, the last one controls the terminal cursor.
* If `anchorRef` is set but unresolved, the cursor is hidden for that frame.
* See also [`useCursor()`](/docs/packages/tui/hooks#usecursor) for imperative cursor control (e.g. IME support).

## `Code` [#code]

Syntax-highlighted code display using [Shiki](https://shiki.style/). Supports 25+ languages with lazy loading and VS Code-quality tokenization.

> **Subpath import.** Imported from `@visulima/tui/components/code`. Requires the optional peers `shiki`, `@shikijs/langs`, `@shikijs/themes`.
>
> ```bash npm2yarn
> npm install shiki @shikijs/langs @shikijs/themes
> ```

```tsx
import { Code } from "@visulima/tui/components/code";

<Code code='const x = "hello";' language="javascript" />
<Code code={source} language="python" showLineNumbers startLine={10} />
```

| Prop              | Type                  | Default                 | Description                                |
| ----------------- | --------------------- | ----------------------- | ------------------------------------------ |
| `code`            | `string`              | *(required)*            | Source code to highlight                   |
| `language`        | `string`              | —                       | Programming language (e.g. `"typescript"`) |
| `theme`           | `string`              | `"github-dark-default"` | Shiki theme name                           |
| `showLineNumbers` | `boolean`             | `false`                 | Show line number gutter                    |
| `startLine`       | `number`              | `1`                     | Starting line number (for excerpts)        |
| `highlightLines`  | `ReadonlySet<number>` | —                       | Line numbers to visually emphasize         |

Supported languages: `javascript`, `typescript`, `jsx`, `tsx`, `json`, `html`, `css`, `python`, `ruby`, `rust`, `go`, `java`, `bash`, `shell`, `sql`, `markdown`, `yaml`, `toml`, `xml`, `svelte`, `vue`, and more. Unknown languages fall back to plain text.

The highlighter loads asynchronously — the first render shows plain text, then re-renders with colors once Shiki is ready.

## `DiffView` [#diffview]

Display file differences with colored additions/deletions. Supports unified and split (side-by-side) views with optional inline character-level diff highlighting.

> **Subpath import.** Imported from `@visulima/tui/components/diff-view`. Requires the optional peer `diff`. To enable syntax highlighting via the `language` prop, also install `shiki`, `@shikijs/langs`, and `@shikijs/themes`.
>
> ```bash npm2yarn
> npm install diff
> # optional, for syntax highlighting:
> npm install shiki @shikijs/langs @shikijs/themes
> ```

```tsx
import { DiffView } from "@visulima/tui/components/diff-view";

<DiffView oldText={original} newText={modified} />
<DiffView diff={unifiedDiffString} mode="split" />
<DiffView oldText={a} newText={b} oldLabel="v1.0" newLabel="v2.0" inlineDiff />
```

| Prop              | Type                     | Default                 | Description                                           |
| ----------------- | ------------------------ | ----------------------- | ----------------------------------------------------- |
| `oldText`         | `string`                 | `""`                    | Original text (left / old)                            |
| `newText`         | `string`                 | `""`                    | Modified text (right / new)                           |
| `diff`            | `string`                 | —                       | Pre-computed unified diff (overrides oldText/newText) |
| `mode`            | `"unified"` \| `"split"` | `"unified"`             | Display mode                                          |
| `showLineNumbers` | `boolean`                | `true`                  | Show line numbers                                     |
| `context`         | `number`                 | `3`                     | Unchanged context lines around changes                |
| `inlineDiff`      | `boolean`                | `true`                  | Character-level highlighting within changed lines     |
| `oldLabel`        | `string`                 | `"old"`                 | Label for the old version                             |
| `newLabel`        | `string`                 | `"new"`                 | Label for the new version                             |
| `language`        | `string`                 | —                       | Programming language for syntax highlighting          |
| `theme`           | `string`                 | `"github-dark-default"` | Shiki theme for syntax highlighting                   |

### Syntax highlighting in diffs [#syntax-highlighting-in-diffs]

When `language` is provided, diff content is highlighted with Shiki (same engine as the `Code` component). Syntax colors are preserved for context lines, and overlaid with diff colors (red/green) for changed lines.

```tsx
<DiffView oldText={oldCode} newText={newCode} language="typescript" />
```

Colors: additions in green (`+`), deletions in red (`-`), context lines dimmed. Inline diff highlights changed characters with inverted background.

## `FilePicker` [#filepicker]

A file system browser for picking files and navigating directories in the terminal.

```tsx
import { FilePicker } from "@visulima/tui/components/file-picker";
<FilePicker
    onSelect={(entry) => console.log("Selected:", entry.path)}
    filter={{ extensions: [".ts", ".tsx"] }}
/>
<FilePicker
    initialPath="/home/user/projects"
    showSize
    showPermissions
    limit={15}
    onCancel={() => exit()}
/>
```

| Prop              | Type                         | Default         | Description                            |
| ----------------- | ---------------------------- | --------------- | -------------------------------------- |
| `initialPath`     | `string`                     | `process.cwd()` | Starting directory                     |
| `filter`          | `FilePickerFilter`           | `{}`            | File filtering options (see below)     |
| `onSelect`        | `(entry: FileEntry) => void` | —               | Called when a file is selected (Enter) |
| `onCancel`        | `() => void`                 | —               | Called when Escape is pressed          |
| `showPermissions` | `boolean`                    | `false`         | Show file permissions column           |
| `showSize`        | `boolean`                    | `false`         | Show file size column                  |
| `isFocused`       | `boolean`                    | `true`          | Whether keyboard navigation is active  |
| `limit`           | `number`                     | `10`            | Visible items (viewport height)        |
| `accentColor`     | `string`                     | `"cyan"`        | Focused item highlight color           |
| `directoryColor`  | `string`                     | `"blue"`        | Directory name color                   |
| `fileColor`       | `string`                     | `"white"`       | File name color                        |

### Filter options [#filter-options]

| Field             | Type       | Default | Description                                  |
| ----------------- | ---------- | ------- | -------------------------------------------- |
| `extensions`      | `string[]` | —       | Allowed extensions (e.g. `[".ts", ".json"]`) |
| `showHidden`      | `boolean`  | `false` | Include hidden files (dotfiles)              |
| `showDirectories` | `boolean`  | `true`  | Include directories                          |
| `showFiles`       | `boolean`  | `true`  | Include regular files                        |

### FileEntry shape [#fileentry-shape]

```ts
type FileEntry = {
    name: string;
    path: string;
    isDirectory: boolean;
    isHidden: boolean;
    size: number;
    permissions: string;
};
```

### Keyboard [#keyboard]

| Key               | Action                        |
| ----------------- | ----------------------------- |
| `↑` / `↓`         | Move focus                    |
| `Enter`           | Open directory or select file |
| `Backspace` / `←` | Go to parent directory        |
| `Escape`          | Cancel (`onCancel`)           |
| `Page Up/Down`    | Jump by viewport height       |
| `Home` / `End`    | Jump to first/last entry      |
| `.`               | Refresh directory listing     |

## `BigText` [#bigtext]

Render large ASCII art text using [CFonts](https://github.com/dominikwilkowski/cfonts). Ported from [`ink-big-text`](https://github.com/sindresorhus/ink-big-text).

> **Subpath import.** Imported from `@visulima/tui/components/big-text`. Requires the optional peer `cfonts`.
>
> ```bash npm2yarn
> npm install cfonts
> ```

```tsx
import { BigText } from "@visulima/tui/components/big-text";

<BigText text="Hello" />
<BigText text="Cool" font="chrome" colors={["red", "blue"]} />
```

| Prop              | Type                            | Default         |
| ----------------- | ------------------------------- | --------------- |
| `text`            | `string`                        | required        |
| `font`            | `Font`                          | `'block'`       |
| `align`           | `'left' \| 'center' \| 'right'` | `'left'`        |
| `colors`          | `string[]`                      | `['system']`    |
| `backgroundColor` | `BackgroundColor`               | `'transparent'` |
| `letterSpacing`   | `number`                        | `1`             |
| `lineHeight`      | `number`                        | `1`             |
| `space`           | `boolean`                       | `true`          |
| `maxLength`       | `number`                        | `0`             |

Available fonts: `block`, `slick`, `tiny`, `grid`, `pallet`, `shade`, `simple`, `simpleBlock`, `3d`, `simple3d`, `chrome`, `huge`.

## `Gradient` [#gradient]

Apply a terminal color gradient to child text. Ported from [`ink-gradient`](https://github.com/sindresorhus/ink-gradient), uses `@visulima/colorize` internally.

```tsx
import { Gradient } from "@visulima/tui/components/gradient";
import { Text } from "@visulima/tui/components/text";
<Gradient name="rainbow">
    <Text>Hello, World!</Text>
</Gradient>

<Gradient colors={["#ff0000", "#00ff00", "#0000ff"]}>
    <Text>Custom gradient</Text>
</Gradient>
```

| Prop     | Type             | Default |
| -------- | ---------------- | ------- |
| `name`   | `GradientName`   | —       |
| `colors` | `GradientColors` | —       |

`name` and `colors` are mutually exclusive — exactly one must be provided.

Built-in presets: `rainbow`, `cristal`, `teen`, `mind`, `morning`, `vice`, `passion`, `fruit`, `instagram`, `atlas`, `retro`, `summer`, `pastel`.

## `Help` [#help]

Auto-generated keybinding help bar. Renders key-description pairs from an array of `KeyBinding` definitions (typically returned by `useKeyBindings`).

```tsx
import { Help } from "@visulima/tui/components/help";
import { useKeyBindings } from "@visulima/tui/hooks/use-key-bindings";
const { bindings } = useKeyBindings([
    { binding: { key: "q", description: "Quit" }, handler: () => exit() },
    { binding: { key: ["↑", "k"], description: "Up", group: "Navigation" }, handler: () => moveUp() },
]);

<Help bindings={bindings} />
<Help bindings={bindings} mode="full" />
```

| Prop               | Type                  | Default      | Description                                   |
| ------------------ | --------------------- | ------------ | --------------------------------------------- |
| `bindings`         | `KeyBinding[]`        | *(required)* | Key bindings to display                       |
| `mode`             | `"short"` \| `"full"` | `"short"`    | Short = single line; full = multi-column grid |
| `separator`        | `string`              | `" · "`      | Separator between pairs in short mode         |
| `keyColor`         | `string`              | `"cyan"`     | Color for key labels                          |
| `descriptionColor` | `string`              | —            | Color for descriptions (defaults to dim)      |
| `maxColumns`       | `number`              | `3`          | Max columns in full mode                      |

### Short mode [#short-mode]

Renders all bindings on a single line, truncated to terminal width:

```
q Quit · ↑/k Up · ↓/j Down · enter Select
```

### Full mode [#full-mode]

Groups bindings by the `group` field into columns:

```
Navigation          Actions
↑/k Up              enter Select
↓/j Down            q Quit
```

Key names are automatically humanized: `"upArrow"` → `"↑"`, `"return"` → `"enter"`, `"escape"` → `"esc"`, etc.

## `Link` [#link]

Create clickable hyperlinks in the terminal using OSC 8 sequences. Ported from [`ink-link`](https://github.com/sindresorhus/ink-link).

```tsx
import { Link } from "@visulima/tui/components/link";
import { Text } from "@visulima/tui/components/text";
<Link url="https://example.com">
    <Text color="cyan">My Website</Text>
</Link>

// Custom fallback for unsupported terminals
<Link url="https://example.com" fallback={(text, url) => `[${text}](${url})`}>
    <Text>Docs</Text>
</Link>
```

| Prop       | Type                                                 | Default | Description                        |
| ---------- | ---------------------------------------------------- | ------- | ---------------------------------- |
| `url`      | `string`                                             | —       | The URL to link to (required)      |
| `fallback` | `boolean \| ((text: string, url: string) => string)` | `true`  | Fallback for unsupported terminals |
| `children` | `ReactNode`                                          | —       | Link text content                  |

When `fallback` is `true`, unsupported terminals show: `My Website https://example.com`. When `false`, only the text is shown. A function receives `(text, url)` for custom formatting.

[Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)

## `Markdown` [#markdown]

Render Markdown content as terminal UI elements. Parses with [marked](https://marked.js.org/) and maps tokens to Ink components. Code blocks are syntax-highlighted via the `Code` component.

> **Subpath import.** Imported from `@visulima/tui/components/markdown`. Requires the optional peer `marked`. Code blocks pull in `shiki`, `@shikijs/langs`, `@shikijs/themes`; tables pull in `@visulima/tabular` — install whichever your content needs.
>
> ```bash npm2yarn
> npm install marked
> # for code-block highlighting:
> npm install shiki @shikijs/langs @shikijs/themes
> # for table rendering inside markdown:
> npm install @visulima/tabular
> ```

````tsx
import { Markdown } from "@visulima/tui/components/markdown";

<Markdown>{"# Hello World\n\nThis is **bold** and *italic*."}</Markdown>
<Markdown codeTheme="github-dark-default">{"```js\nconst x = 1;\n```"}</Markdown>
````

| Prop        | Type      | Default                 | Description                          |
| ----------- | --------- | ----------------------- | ------------------------------------ |
| `children`  | `string`  | *(required)*            | Markdown source string               |
| `codeTheme` | `string`  | `"github-dark-default"` | Shiki theme for code blocks          |
| `maxWidth`  | `number`  | terminal width          | Maximum text wrap width              |
| `streaming` | `boolean` | `false`                 | Progressive rendering for LLM output |

### Streaming mode [#streaming-mode]

Enable `streaming` when rendering Markdown that arrives incrementally (e.g., token-by-token from an AI model). The component handles incomplete Markdown gracefully — unclosed code fences and partial blocks render as text until they close.

```tsx
const [text, setText] = useState("");
// ... text grows as tokens arrive ...
<Markdown streaming>{text}</Markdown>;
```

### Supported Markdown features [#supported-markdown-features]

* **Headings** (H1-H6) — bold, color-coded by depth
* **Paragraphs** — with word wrapping
* **Code blocks** — syntax highlighted via `\<Code>` component
* **Inline code** — rendered with inverse styling
* **Bold**, **italic**, **strikethrough**
* **Links** — rendered via the existing `\<Link>` component (OSC 8)
* **Ordered and unordered lists** — via existing `\<OrderedList>` / `\<UnorderedList>`
* **Blockquotes** — with left border
* **Horizontal rules**
* **Tables** — via existing `\<Table>` component
* **Images** — displayed as `[image: alt text]` (terminals cannot render images)

## `Newline` [#newline]

```tsx
<Newline />
<Newline count={2} />
```

## `Spacer` [#spacer]

```tsx
<Box flexDirection="row">
    <Text>Left</Text>
    <Spacer />
    <Text>Right</Text>
</Box>
```

## `Static` [#static]

Append-only region for completed items and log lines.

```tsx
<Static items={completedTasks}>
    {(task) => (
        <Box key={task.id}>
            <Text color="green">✓ {task.name}</Text>
        </Box>
    )}
</Static>
```

`Static` only appends new tail items from `items`.

## `Transform` [#transform]

Applies a transform function to the collected text output of its subtree.

```tsx
<Transform transform={(s) => s.toUpperCase()}>
    <Text>hello world</Text>
</Transform>
```

## `Spinner` [#spinner]

Animated spinner. Backed by [`@visulima/spinner`](https://visulima.com/packages/spinner) (replaces the previous `cli-spinners` dependency). The frame set and tick interval are determined by the named preset; pass `type` to switch presets.

```tsx
<Spinner />
<Spinner type="dots" />
<Spinner type="wave" />
```

| Prop   | Type          | Default  | Description                              |
| ------ | ------------- | -------- | ---------------------------------------- |
| `type` | `SpinnerName` | `"dots"` | Any preset name from `@visulima/spinner` |

Available presets include `dots`, `breathe`, `cascade`, `checkerboard`, `columns`, `diagSwipe`, `dna`, `doubleArrow`, `fillSweep`, `helix`, `infinity`, `orbit`, `pulse`, `rain`, `scan`, `scanline`, `snake`, `sparkle`, `wave`, `waveRows`, plus every preset re-exported from `cli-spinners`. See `packages/terminal/spinner/src/spinners.ts` for the full list.

## `Stopwatch` [#stopwatch]

A count-up elapsed time display. Exposes `start`, `stop`, `toggle`, `reset`, and `lap` controls via ref.

```tsx
import { Stopwatch } from "@visulima/tui/components/stopwatch";
import { useRef } from "react";

const ref = useRef(null);

<Stopwatch ref={ref} autoStart />
<Stopwatch autoStart color="green" bold />
<Stopwatch format={(ms) => `${(ms / 1000).toFixed(1)}s`} />
```

| Prop        | Type                          | Default            | Description                   |
| ----------- | ----------------------------- | ------------------ | ----------------------------- |
| `autoStart` | `boolean`                     | `false`            | Start counting immediately    |
| `interval`  | `number`                      | `1000`             | Tick interval in milliseconds |
| `format`    | `(elapsed: number) => string` | `MM:SS`/`HH:MM:SS` | Custom time formatter         |
| `color`     | `string`                      | —                  | Text color                    |
| `bold`      | `boolean`                     | —                  | Bold text                     |

### Ref methods [#ref-methods]

```tsx
ref.current.start(); // Start counting
ref.current.stop(); // Pause
ref.current.toggle(); // Toggle start/stop
ref.current.reset(); // Reset to 00:00 and stop
ref.current.lap(); // Capture current elapsed time
```

For headless usage, use the [`useStopwatch`](/docs/packages/tui/hooks#usestopwatch) hook directly.

## `Timer` [#timer]

A countdown timer display. Exposes `start`, `stop`, `toggle`, and `reset` controls via ref.

```tsx
import { Timer } from "@visulima/tui/components/timer";
import { useRef } from "react";

const ref = useRef(null);

<Timer ref={ref} duration={60_000} autoStart />
<Timer duration={300_000} autoStart color="red" onTimeout={() => alert("Done!")} />
```

| Prop        | Type                            | Default            | Description                        |
| ----------- | ------------------------------- | ------------------ | ---------------------------------- |
| `duration`  | `number`                        | *(required)*       | Countdown duration in milliseconds |
| `autoStart` | `boolean`                       | `false`            | Start counting immediately         |
| `interval`  | `number`                        | `1000`             | Tick interval in milliseconds      |
| `onTimeout` | `() => void`                    | —                  | Called when the timer reaches zero |
| `format`    | `(remaining: number) => string` | `MM:SS`/`HH:MM:SS` | Custom time formatter              |
| `color`     | `string`                        | —                  | Text color                         |
| `bold`      | `boolean`                       | —                  | Bold text                          |

### Ref methods [#ref-methods-1]

```tsx
ref.current.start(); // Start countdown
ref.current.stop(); // Pause
ref.current.toggle(); // Toggle start/stop
ref.current.reset(); // Reset to original duration and stop
```

For headless usage, use the [`useTimer`](/docs/packages/tui/hooks#usetimer) hook directly.

## `ProgressBar` [#progressbar]

A terminal progress bar that fills proportionally to a percentage value. Ported from [`ink-progress-bar`](https://github.com/brigand/ink-progress-bar).

```tsx
import { ProgressBar } from "@visulima/tui/components/progress-bar";
<ProgressBar percent={0.5} />
<ProgressBar percent={0.75} color="green" left={10} right={5} />
<ProgressBar percent={1} character="▓" rightPad />
```

All `Text` props (color, bold, dimColor, etc.) are forwarded to the underlying `\<Text>`.

| Prop        | Type      | Default | Description                                    |
| ----------- | --------- | ------- | ---------------------------------------------- |
| `percent`   | `number`  | `1`     | Completion between 0 and 1 (clamped)           |
| `columns`   | `number`  | `0`     | Override terminal width (0 = auto-detect)      |
| `left`      | `number`  | `0`     | Columns reserved on the left (e.g. for labels) |
| `right`     | `number`  | `0`     | Columns reserved on the right                  |
| `character` | `string`  | `'█'`   | Fill character for the completed portion       |
| `rightPad`  | `boolean` | `false` | Pad remaining space with whitespace            |

Example with labels:

```tsx
<Box>
    <Text>Progress: </Text>
    <ProgressBar percent={0.6} left={10} right={5} color="cyan" />
    <Text> 60%</Text>
</Box>
```

## `Slider` [#slider]

A keyboard-driven range input for selecting numeric values. Supports horizontal and vertical orientations.

```tsx
import { Slider } from "@visulima/tui/components/slider";
<Slider defaultValue={50} onChange={(v) => console.log(v)} />
<Slider defaultValue={22} min={10} max={40} step={1} accentColor="red" width={30} />
<Slider defaultValue={60} orientation="vertical" width={8} />
```

| Prop              | Type                           | Default        | Description                                  |
| ----------------- | ------------------------------ | -------------- | -------------------------------------------- |
| `value`           | `number`                       | —              | Controlled value                             |
| `defaultValue`    | `number`                       | `0`            | Initial value (uncontrolled)                 |
| `min`             | `number`                       | `0`            | Minimum value                                |
| `max`             | `number`                       | `100`          | Maximum value                                |
| `step`            | `number`                       | `1`            | Increment per arrow key press                |
| `orientation`     | `"horizontal"` \| `"vertical"` | `"horizontal"` | Layout direction                             |
| `width`           | `number`                       | `20`           | Track width in columns (or rows if vertical) |
| `isFocused`       | `boolean`                      | `true`         | Whether the component responds to input      |
| `isDisabled`      | `boolean`                      | `false`        | Ignores all input and dims the slider        |
| `filledCharacter` | `string`                       | `"█"`          | Character for the filled portion             |
| `emptyCharacter`  | `string`                       | `"░"`          | Character for the empty portion              |
| `thumbCharacter`  | `string`                       | `"●"`          | Character marking the current position       |
| `accentColor`     | `string`                       | `"green"`      | Color for filled portion and thumb           |
| `defaultColor`    | `string`                       | `"gray"`       | Color for empty portion                      |
| `onChange`        | `(value: number) => void`      | —              | Called when value changes                    |

### Keyboard [#keyboard-1]

* **Left/Right arrows** (horizontal) or **Up/Down** (vertical): move by `step`
* **Home/End**: jump to min/max
* **Page Up/Down**: move by 10 × step
* **0–9**: jump to 0%, 10%, … 90% of the range

### Controlled mode [#controlled-mode]

```tsx
const [value, setValue] = useState(50);
<Slider value={value} onChange={setValue} />;
```

## `ConsoleOverlay` [#consoleoverlay]

A dockable panel that captures `console.log`/`warn`/`error`/`debug` output and displays it within the TUI. Similar to browser devtools console.

```tsx
import { Box } from "@visulima/tui/components/box";
import { ConsoleOverlay } from "@visulima/tui/components/console-overlay";
<Box flexDirection="column" height="100%">
    <Box flexGrow={1}>{/* main app content */}</Box>
    <ConsoleOverlay dock="bottom" height={6} />
</Box>;
```

| Prop            | Type                  | Default    | Description                    |
| --------------- | --------------------- | ---------- | ------------------------------ |
| `dock`          | `"top"` \| `"bottom"` | `"bottom"` | Panel position                 |
| `height`        | `number`              | `8`        | Visible rows                   |
| `maxEntries`    | `number`              | `200`      | Buffer size                    |
| `showTimestamp` | `boolean`             | `true`     | Show `[HH:MM:SS]` prefix       |
| `showLevel`     | `boolean`             | `true`     | Show level label (LOG/WRN/ERR) |
| `filter`        | `ConsoleLevel[]`      | all levels | Which levels to capture        |

Entries are color-coded: gray (debug), white (log), blue (info), yellow (warn), red (error). Auto-scrolls to show the latest entry.

## `ConfirmInput` [#confirminput]

A Y/N confirmation prompt. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/confirm-input.png" width="200" alt="ConfirmInput demo" />

```tsx
import { ConfirmInput } from "@visulima/tui/components/confirm-input";
import { Text } from "@visulima/tui/components/text";
<Text>Do you want to continue? </Text>
<ConfirmInput
    onConfirm={() => console.log("Confirmed!")}
    onCancel={() => console.log("Cancelled.")}
/>
```

| Prop            | Type                      | Default      | Description                              |
| --------------- | ------------------------- | ------------ | ---------------------------------------- |
| `defaultChoice` | `"confirm"` \| `"cancel"` | `"confirm"`  | Default action when Enter is pressed     |
| `isDisabled`    | `boolean`                 | `false`      | Ignores all input when true              |
| `submitOnEnter` | `boolean`                 | `true`       | Whether Enter submits the default choice |
| `onConfirm`     | `() => void`              | *(required)* | Called when user presses Y               |
| `onCancel`      | `() => void`              | *(required)* | Called when user presses N               |

Shows `Y/n` when default is confirm, `y/N` when default is cancel. Press `Y`/`y` to confirm, `N`/`n` to cancel, Enter to submit the default.

## `MultiSelect` [#multiselect]

Multi-choice selection component with checkboxes and keyboard navigation. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/multi-select.gif" width="400" alt="MultiSelect demo" />

```tsx
import { MultiSelect } from "@visulima/tui/components/multi-select";
const options = [
    { label: "TypeScript", value: "ts" },
    { label: "JavaScript", value: "js" },
    { label: "Python", value: "py" },
];

<MultiSelect options={options} onSubmit={(values) => console.log("Selected:", values)} />;
```

| Prop           | Type                         | Default      | Description                                         |
| -------------- | ---------------------------- | ------------ | --------------------------------------------------- |
| `options`      | `MultiSelectOption[]`        | *(required)* | Available choices                                   |
| `defaultValue` | `string[]`                   | `[]`         | Initially selected values                           |
| `isDisabled`   | `boolean`                    | `false`      | Ignores all input when true                         |
| `isFocused`    | `boolean`                    | `true`       | Whether the component captures input                |
| `limit`        | `number`                     | —            | Max visible options; auto-limits to terminal height |
| `accentColor`  | `string`                     | `"blue"`     | Color for the focused indicator                     |
| `defaultColor` | `string`                     | —            | Color for unfocused, unselected labels              |
| `onChange`     | `(values: string[]) => void` | —            | Called when selection changes (space)               |
| `onSubmit`     | `(values: string[]) => void` | —            | Called when Enter is pressed                        |

Keyboard: arrow keys or `j`/`k` to navigate, Space to toggle, `a` to select/deselect all, Enter to submit.

## `TextInput` [#textinput]

Single-line text input with cursor navigation, autocomplete suggestions, and optional password masking. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/text-input.gif" width="400" alt="TextInput demo" />

```tsx
import { TextInput } from "@visulima/tui/components/text-input";
<TextInput placeholder="Enter your name..." onSubmit={(value) => console.log("Name:", value)} />;
```

| Prop           | Type                      | Default | Description                                           |
| -------------- | ------------------------- | ------- | ----------------------------------------------------- |
| `defaultValue` | `string`                  | `""`    | Starting value                                        |
| `isDisabled`   | `boolean`                 | `false` | Ignores all input when true                           |
| `mask`         | `boolean`                 | `false` | Renders asterisks instead of characters               |
| `placeholder`  | `string`                  | —       | Greyed-out text when input is empty                   |
| `suggestions`  | `string[]`                | —       | Autocomplete candidates (case-sensitive prefix match) |
| `onChange`     | `(value: string) => void` | —       | Called on every keystroke                             |
| `onSubmit`     | `(value: string) => void` | —       | Called when Enter is pressed                          |

Keyboard: left/right arrows for cursor, Home/End or Ctrl+A/E for start/end, Ctrl+U/K/W for line editing, Backspace/Delete, right arrow to accept suggestion, Enter to submit (accepts suggestion if pending).

### Password mode [#password-mode]

```tsx
<TextInput mask onSubmit={(password) => authenticate(password)} />
```

### Autocomplete [#autocomplete]

```tsx
<TextInput suggestions={["react", "react-dom", "react-native"]} onSubmit={install} />
```

The first matching suggestion is shown dimmed after the cursor. Press right arrow or Enter to accept it.

## `Textarea` [#textarea]

Multi-line text input with cursor navigation, selection, clipboard copy (OSC 52), undo/redo, paste support, and viewport scrolling.

```tsx
import { Textarea } from "@visulima/tui/components/textarea";
<Textarea
    placeholder="Write something..."
    rows={8}
    showLineNumbers
    onChange={(value) => console.log(value)}
    onSubmit={(value) => console.log("Submitted:", value)}
/>;
```

| Prop              | Type                      | Default | Description                                  |
| ----------------- | ------------------------- | ------- | -------------------------------------------- |
| `defaultValue`    | `string`                  | `""`    | Starting content                             |
| `placeholder`     | `string`                  | —       | Greyed-out text shown when empty             |
| `rows`            | `number`                  | `5`     | Visible rows (viewport height)               |
| `maxRows`         | `number`                  | —       | Auto-grow up to this height before scrolling |
| `isDisabled`      | `boolean`                 | `false` | Ignores all input and dims the text          |
| `isFocused`       | `boolean`                 | `true`  | Whether the component responds to input      |
| `showLineNumbers` | `boolean`                 | `false` | Show line numbers in the left gutter         |
| `tabSize`         | `number`                  | `2`     | Number of spaces inserted for Tab            |
| `onChange`        | `(value: string) => void` | —       | Called on every edit                         |
| `onSubmit`        | `(value: string) => void` | —       | Called on Meta+Enter or Ctrl+Enter           |

### Keyboard [#keyboard-2]

| Key                     | Action                     |
| ----------------------- | -------------------------- |
| Arrow keys              | Move cursor                |
| Shift+Arrows            | Extend selection           |
| Home / Ctrl+A           | Start of line              |
| End / Ctrl+E            | End of line                |
| Ctrl+Home               | Start of buffer            |
| Ctrl+End                | End of buffer              |
| Enter                   | Insert newline             |
| Meta+Enter / Ctrl+Enter | Submit (`onSubmit`)        |
| Backspace / Delete      | Delete character           |
| Ctrl+U                  | Kill to line start         |
| Ctrl+K                  | Kill to line end           |
| Ctrl+W                  | Kill word backward         |
| Tab                     | Insert spaces (`tabSize`)  |
| Ctrl+Z                  | Undo                       |
| Ctrl+Y                  | Redo                       |
| Ctrl+Shift+A            | Select all                 |
| Ctrl+C (with selection) | Copy to clipboard (OSC 52) |
| Escape                  | Clear selection            |
| Paste (bracketed)       | Insert pasted text         |

### Auto-growing height [#auto-growing-height]

```tsx
<Textarea rows={3} maxRows={15} placeholder="Grows from 3 to 15 rows..." />
```

### With line numbers [#with-line-numbers]

```tsx
<Textarea showLineNumbers defaultValue={"function hello() {\n  return 'world';\n}"} rows={5} />
```

## `SelectInput` [#selectinput]

Interactive select input for choosing from a list of options. Ported from [`ink-select-input`](https://github.com/vadimdemedes/ink-select-input).

<img src="./media/ink-ui/select.gif" width="400" alt="SelectInput demo" />

```tsx
import { SelectInput } from "@visulima/tui/components/select-input";
const items = [
    { label: "TypeScript", value: "ts" },
    { label: "JavaScript", value: "js" },
    { label: "Python", value: "py" },
];

<SelectInput items={items} onSelect={(item) => console.log(item.value)} />;
```

Navigate with arrow keys or `j`/`k`, select with Enter, or jump to an item by pressing a number key (1–9).

### Props [#props]

| Prop                 | Type                                      | Default                | Description                                                  |
| -------------------- | ----------------------------------------- | ---------------------- | ------------------------------------------------------------ |
| `items`              | `Item\<V>[]`                              | `[]`                   | Choices to display                                           |
| `isFocused`          | `boolean`                                 | `true`                 | Whether the component captures keyboard input                |
| `initialIndex`       | `number`                                  | —                      | Initially-selected item index; omit for no initial selection |
| `index`              | `number`                                  | —                      | Controlled selected index (see below)                        |
| `limit`              | `number`                                  | —                      | Max visible items; enables scroll windowing                  |
| `accentColor`        | `string`                                  | `"blue"`               | Color for the selected item and indicator                    |
| `defaultColor`       | `string`                                  | —                      | Color for unselected items                                   |
| `indicatorComponent` | `FC\<IndicatorProps>`                     | `SelectInputIndicator` | Custom indicator component                                   |
| `itemComponent`      | `FC\<ItemProps>`                          | `SelectInputItem`      | Custom item component                                        |
| `onSelect`           | `(item: Item\<V>) => void`                | —                      | Called on Enter or number key press                          |
| `onHighlight`        | `(item: Item\<V>, index: number) => void` | —                      | Called when selection moves; second arg is the new index     |
| `resetOnItemsChange` | `boolean`                                 | `true`                 | Reset selection when item values change                      |

Each item in the `items` array must have a `label` (display text) and a `value` (returned on select). An optional `key` provides a stable React key. An optional `action` function is called automatically when the item is selected.

### Item actions [#item-actions]

Instead of switching on `value` in the `onSelect` handler, you can define per-item behavior inline:

```tsx
const items = [
    { label: "Build", value: "build", action: () => runBuild() },
    { label: "Test", value: "test", action: () => runTests() },
    { label: "Deploy", value: "deploy", action: () => deploy() },
];

<SelectInput items={items} initialIndex={0} />;
```

When an item is selected (Enter or number key), `onSelect` fires first (if provided), then `item.action()` is called. Both are optional — you can use either or both.

### Separators [#separators]

Add non-focusable separator lines between groups of items. Separators are skipped during keyboard navigation and cannot be selected:

```tsx
const items = [
    { label: "Cut", value: "cut" },
    { label: "Copy", value: "copy" },
    { label: "Paste", value: "paste" },
    { isSeparator: true },
    { label: "Select All", value: "selectAll" },
];

<SelectInput items={items} initialIndex={0} />;
```

A separator renders as `───` by default. Pass a custom `label` to change the text:

```tsx
{ isSeparator: true, label: "── Advanced ──" }
```

The `SeparatorItem` type is exported for use in typed item arrays:

```tsx
import type { SelectInputEntry, SelectInputSeparator } from "@visulima/tui/components/select-input";
const items: SelectInputEntry<string>[] = [{ label: "Option A", value: "a" }, { isSeparator: true }, { label: "Option B", value: "b" }];
```

Note: the reset check compares item **values** only — changing labels or other properties while keeping the same values will not trigger a reset. Set `resetOnItemsChange={false}` to preserve the selection across all item changes.

### No initial selection [#no-initial-selection]

When `initialIndex` is omitted, no item is highlighted until the user presses a navigation key. This is useful for rendering a list without a pre-selected value, similar to an empty radio group:

```tsx
<SelectInput items={items} onHighlight={(item) => console.log("Browsing:", item.label)} />
```

The first down arrow or `j` press highlights the first item; the first up arrow or `k` press highlights the last. Enter is a no-op until an item is highlighted. Number keys (1–9) still work for direct selection.

To start with the first item already highlighted, pass `initialIndex={0}`.

### Controlled mode [#controlled-mode-1]

Pass `index` to control the selection externally. When `index` is set, `initialIndex` is ignored. Update `index` from your `onHighlight` callback to track the selection:

```tsx
const [selectedIndex, setSelectedIndex] = useState(0);

<SelectInput
    items={items}
    index={selectedIndex}
    onHighlight={(item, idx) => setSelectedIndex(idx)}
    onSelect={(item) => console.log("Selected:", item.value)}
/>;
```

### Scroll windowing [#scroll-windowing]

When no `limit` is specified and the list has more items than the terminal has rows, the component automatically caps the visible items to the terminal height. This prevents overflow without any manual measurement.

You can also set `limit` explicitly to control the window size:

```tsx
<SelectInput items={longList} limit={5} />
```

The list wraps around when navigating past the first or last visible item.

### Custom colors [#custom-colors]

Override the default blue highlight with `accentColor` and `defaultColor`:

```tsx
<SelectInput items={items} accentColor="green" defaultColor="gray" />
```

These colors are passed through to the indicator and item components.

### Focus dimming [#focus-dimming]

When multiple `SelectInput` components are on screen, the unfocused ones automatically dim their selected item using `dimColor`. This makes it easy to tell which list has focus:

```tsx
<Box>
    <SelectInput items={leftItems} initialIndex={0} isFocused={leftActive} />
    <SelectInput items={rightItems} initialIndex={0} isFocused={!leftActive} />
</Box>
```

The `isFocused` prop is passed through to both `indicatorComponent` and `itemComponent`, so custom components can implement their own unfocused styling.

### Custom components [#custom-components]

Replace the default indicator or item rendering:

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
const CustomIndicator = ({ isSelected, isFocused, accentColor }) => (
    <Box marginRight={1}>
        <Text color={isSelected ? accentColor : undefined} dimColor={!isFocused}>
            {isSelected ? "→" : " "}
        </Text>
    </Box>
);

const CustomItem = ({ label, isSelected, isFocused, accentColor, defaultColor }) => (
    <Text bold={isSelected} color={isSelected ? accentColor : defaultColor} dimColor={isSelected && !isFocused}>
        {label}
    </Text>
);

<SelectInput items={items} indicatorComponent={CustomIndicator} itemComponent={CustomItem} />;
```

Custom components receive `isSelected`, `isFocused`, `accentColor`, and (for items) `defaultColor` plus the item's own `label`/`value`/`key` fields.

## `Tab` / `Tabs` [#tab--tabs]

Tabbed navigation component with keyboard support. Inspired by [`ink-tab`](https://github.com/jdeniau/ink-tab).

```tsx
import { Tab } from "@visulima/tui/components/tab";
import { Tabs } from "@visulima/tui/components/tabs";
<Tabs onChange={(name, tab) => console.log("Active:", name)}>
    <Tab name="files">Files</Tab>
    <Tab name="search">Search</Tab>
    <Tab name="settings">Settings</Tab>
</Tabs>;
```

### `Tabs` Props [#tabs-props]

| Prop            | Type                                                           | Default      | Description                                                                                                           |
| --------------- | -------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `children`      | `ReactNode`                                                    | *(required)* | `<Tab>` elements                                                                                                      |
| `onChange`      | `(name: string, tab: ReactElement) => void`                    | *(required)* | Fired when the active tab changes (both modes). In controlled mode the parent must update `value` from this callback. |
| `value`         | `string`                                                       | —            | Controlled active tab name. When set, the component is controlled and `defaultValue` is ignored.                      |
| `defaultValue`  | `string`                                                       | —            | Initial active tab in uncontrolled mode                                                                               |
| `flexDirection` | `"row"` \| `"column"` \| `"row-reverse"` \| `"column-reverse"` | `"row"`      | Layout direction                                                                                                      |
| `isFocused`     | `boolean \| null`                                              | `undefined`  | Focus state; `false` disables input, `null` = unmanaged                                                               |
| `showIndex`     | `boolean`                                                      | `true`       | Show 1-based index numbers before tab names                                                                           |
| `width`         | `number \| string`                                             | —            | Container width (also separator width in column layouts)                                                              |
| `keyMap`        | `KeyMap`                                                       | —            | Custom keyboard bindings                                                                                              |
| `colors`        | `TabColors`                                                    | —            | Active tab color customization                                                                                        |

### Controlled mode [#controlled-mode-2]

```tsx
const [active, setActive] = useState("files");

<Tabs value={active} onChange={(name) => setActive(name)}>
    <Tab name="files">Files</Tab>
    <Tab name="search">Search</Tab>
</Tabs>;
```

### `Tab` Props [#tab-props]

| Prop       | Type        | Default      | Description                     |
| ---------- | ----------- | ------------ | ------------------------------- |
| `name`     | `string`    | *(required)* | Unique identifier for this tab  |
| `children` | `ReactNode` | *(required)* | Content rendered inside the tab |

### Keyboard [#keyboard-3]

* **Left/Right arrows** (or Up/Down in column layout): navigate between tabs
* **Tab/Shift+Tab**: cycle through tabs (only when `isFocused` is unmanaged)
* **Meta/Cmd + 1–9**: jump to a specific tab by index

### Column layout [#column-layout]

```tsx
<Tabs flexDirection="column" onChange={handleChange}>
    <Tab name="a">Alpha</Tab>
    <Tab name="b">Beta</Tab>
</Tabs>
```

### Custom colors [#custom-colors-1]

```tsx
<Tabs colors={{ activeTab: { color: "cyan", backgroundColor: "white" } }} onChange={handleChange}>
    <Tab name="one">One</Tab>
    <Tab name="two">Two</Tab>
</Tabs>
```

## `Table` [#table]

Render data as a formatted table in the terminal. Uses [`@visulima/tabular`](https://visulima.com/packages/tabular) as the rendering engine, supporting multiple border styles, column configuration, cell formatting, and word wrap. Ported from [`ink-table`](https://github.com/maticzav/ink-table).

> **Subpath import.** Imported from `@visulima/tui/components/table`. Requires the optional peer `@visulima/tabular`.
>
> ```bash npm2yarn
> npm install @visulima/tabular
> ```

```tsx
import { Table } from "@visulima/tui/components/table";

const data = [
    { name: "Alice", age: 30, city: "NYC" },
    { name: "Bob", age: 25, city: "LA" },
];

<Table data={data} />
<Table data={data} borderStyle="rounded" padding={2} />
```

### Props [#props-1]

| Prop           | Type                                  | Default      | Description                                       |
| -------------- | ------------------------------------- | ------------ | ------------------------------------------------- |
| `data`         | `T[]`                                 | *(required)* | Array of objects to display as rows               |
| `columns`      | `(string \| ColumnConfig)[]`          | all keys     | Columns to display and their order                |
| `padding`      | `number`                              | `1`          | Cell padding (left and right) in characters       |
| `borderStyle`  | `string \| BorderStyle`               | `"default"`  | Border preset or custom object (see below)        |
| `maxWidth`     | `number`                              | —            | Maximum table width; columns truncate/wrap to fit |
| `showHeader`   | `boolean`                             | `true`       | Whether to show the header row                    |
| `formatCell`   | `(value, column, rowIndex) => string` | —            | Custom cell value formatter                       |
| `formatHeader` | `(column) => string`                  | —            | Custom header label formatter                     |
| `skeleton`     | `string`                              | `""`         | Replacement for `null`/`undefined` cells          |
| `wordWrap`     | `boolean`                             | `false`      | Enable word wrap instead of truncation            |

### Column Configuration [#column-configuration]

Columns accept either simple key strings or `ColumnConfig` objects for advanced control:

```tsx
<Table data={data} columns={[{ key: "name", header: "Full Name", width: 20, align: "left" }, { key: "age", header: "Years", align: "right" }, "city"]} />
```

| ColumnConfig field | Type                            | Description                           |
| ------------------ | ------------------------------- | ------------------------------------- |
| `key`              | `string&#x60; &#x2A;(required)* | Key from the data object              |
| `header`           | `string`                        | Custom header label (defaults to key) |
| `width`            | `number`                        | Fixed column width in characters      |
| `align`            | `"left" \| "center" \| "right"` | Horizontal alignment                  |

### Border Styles [#border-styles]

Available presets: `"default"`, `"rounded"`, `"double"`, `"minimal"`, `"dots"`, `"markdown"`, `"ascii"`, `"none"`, `"block"`, `"thick"`.

```tsx
<Table data={data} borderStyle="rounded" />
<Table data={data} borderStyle="ascii" />
<Table data={data} borderStyle="none" />
```

You can also pass a custom `BorderStyle` object from `@visulima/tabular` for full control.

### Custom Formatting [#custom-formatting]

```tsx
<Table
    data={data}
    formatCell={(value, column, rowIndex) => {
        if (column === "name") return String(value).toUpperCase();
        return String(value ?? "");
    }}
    formatHeader={(column) => column.toUpperCase()}
    skeleton="N/A"
/>
```

> **Note:** Unlike the original `ink-table`, this component uses function-based formatters (`formatCell`, `formatHeader`) instead of custom React component props (`header`, `cell`, `skeleton`), because the table is rendered as a single string via `@visulima/tabular`.

## `Badge` [#badge]

Uppercase colored label badge for status indicators. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/badge.png" width="400" alt="Badge demo" />

```tsx
import { Badge } from "@visulima/tui/components/badge";
<Badge>new</Badge>
<Badge color="red">error</Badge>
<Badge color="green">success</Badge>
```

| Prop       | Type        | Default      | Description                                |
| ---------- | ----------- | ------------ | ------------------------------------------ |
| `children` | `ReactNode` | *(required)* | Label content; strings are auto-uppercased |
| `color`    | `string`    | `"magenta"`  | Background color for the badge             |

## `StatusMessage` [#statusmessage]

Status notification with a colored variant icon. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/status-message.png" width="400" alt="StatusMessage demo" />

```tsx
import { StatusMessage } from "@visulima/tui/components/status-message";
<StatusMessage variant="success">Build completed</StatusMessage>
<StatusMessage variant="error">Connection failed</StatusMessage>
<StatusMessage variant="warning">Disk space low</StatusMessage>
<StatusMessage variant="info">3 updates available</StatusMessage>
```

| Prop       | Type                                                | Default      | Description               |
| ---------- | --------------------------------------------------- | ------------ | ------------------------- |
| `children` | `ReactNode`                                         | *(required)* | Message text              |
| `variant`  | `"success"` \| `"error"` \| `"warning"` \| `"info"` | *(required)* | Determines icon and color |

Icons: ✔ (success/green), ✖ (error/red), ⚠ (warning/yellow), ℹ (info/blue).

## `Alert` [#alert]

Bordered alert box with a variant-specific icon and optional title. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/alert.png" width="600" alt="Alert demo" />

```tsx
import { Alert } from "@visulima/tui/components/alert";
<Alert variant="info">Check the docs for details.</Alert>
<Alert variant="warning" title="Deprecation Notice">
    This API will be removed in v3.
</Alert>
```

| Prop       | Type                                                | Default      | Description                |
| ---------- | --------------------------------------------------- | ------------ | -------------------------- |
| `children` | `ReactNode`                                         | *(required)* | Alert message              |
| `variant`  | `"info"` \| `"success"` \| `"error"` \| `"warning"` | *(required)* | Border color and icon      |
| `title`    | `string`                                            | —            | Bold heading above message |

## `UnorderedList` [#unorderedlist]

Bullet list with nesting support and customizable markers. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/unordered-list.png" width="400" alt="UnorderedList demo" />

```tsx
import { UnorderedList } from "@visulima/tui/components/unordered-list";
<UnorderedList items={[{ label: "TypeScript" }, { label: "JavaScript" }, { label: "Python", children: [{ label: "Django" }, { label: "Flask" }] }]} />;
```

| Prop     | Type                   | Default           | Description                                       |
| -------- | ---------------------- | ----------------- | ------------------------------------------------- |
| `items`  | `UnorderedListEntry[]` | *(required)*      | List entries with `label` and optional `children` |
| `marker` | `string` \| `string[]` | `["─", "◦", "▪"]` | Bullet symbol(s); arrays cycle by depth           |

Each entry has `label: ReactNode` and optional `children: UnorderedListEntry[]` for nesting.

## `OrderedList` [#orderedlist]

Numbered list with hierarchical nesting and auto-padded markers. Inspired by [ink-ui](https://github.com/vadimdemedes/ink-ui).

<img src="./media/ink-ui/ordered-list.png" width="400" alt="OrderedList demo" />

```tsx
import { OrderedList } from "@visulima/tui/components/ordered-list";
<OrderedList
    items={[
        { label: "Install dependencies" },
        { label: "Configure", children: [{ label: "Create config file" }, { label: "Set environment variables" }] },
        { label: "Deploy" },
    ]}
/>;
```

| Prop    | Type                 | Default      | Description                                       |
| ------- | -------------------- | ------------ | ------------------------------------------------- |
| `items` | `OrderedListEntry[]` | *(required)* | List entries with `label` and optional `children` |

Numbers are right-padded for alignment (e.g., ` 1.`, ` 2.`, `10.`). Nested lists produce hierarchical markers (`1.`, `1.1.`, `1.2.`).

## `Paginator` [#paginator]

A pagination component with a render-prop pattern and configurable page indicators. Handles keyboard navigation and slices items by page.

```tsx
import { Box } from "@visulima/tui/components/box";
import { Paginator } from "@visulima/tui/components/paginator";
import { Text } from "@visulima/tui/components/text";
<Paginator items={allItems} pageSize={5}>
    {(pageItems, meta) => (
        <Box flexDirection="column">
            {pageItems.map((item, i) => (
                <Text key={i}>{item}</Text>
            ))}
        </Box>
    )}
</Paginator>;
```

| Prop             | Type                                            | Default      | Description                           |
| ---------------- | ----------------------------------------------- | ------------ | ------------------------------------- |
| `items`          | `T[]`                                           | *(required)* | Full item list to paginate            |
| `pageSize`       | `number`                                        | *(required)* | Items per page                        |
| `children`       | `(pageItems: T[], meta: PageMeta) => ReactNode` | *(required)* | Render prop for page content          |
| `page`           | `number`                                        | —            | Controlled current page (0-indexed)   |
| `defaultPage`    | `number`                                        | `0`          | Initial page for uncontrolled mode    |
| `onChange`       | `(page: number) => void`                        | —            | Called when page changes              |
| `isFocused`      | `boolean`                                       | `true`       | Whether keyboard navigation is active |
| `style`          | `"dots"` \| `"numeric"` \| `"fraction"`         | `"dots"`     | Indicator style                       |
| `indicatorColor` | `string`                                        | `"cyan"`     | Color for the active indicator        |

### PageMeta [#pagemeta]

The render-prop receives a `PageMeta` object as the second argument:

```ts
type PageMeta = {
    currentPage: number;
    totalPages: number;
    startIndex: number;
    endIndex: number;
    isFirstPage: boolean;
    isLastPage: boolean;
};
```

### Indicator styles [#indicator-styles]

* **dots**: `● ○ ○ ○` — active dot highlighted
* **numeric**: `‹ 1 / 4 ›` — arrows dim at boundaries
* **fraction**: `1/4` — compact display

### Keyboard [#keyboard-4]

| Key               | Action        |
| ----------------- | ------------- |
| `←` / `Page Up`   | Previous page |
| `→` / `Page Down` | Next page     |
| `Home`            | First page    |
| `End`             | Last page     |

### Controlled mode [#controlled-mode-3]

```tsx
const [page, setPage] = useState(0);
<Paginator items={data} pageSize={10} page={page} onChange={setPage}>
    {(items) => <MyList items={items} />}
</Paginator>;
```

## `TreeView` [#treeview]

Interactive tree view with keyboard navigation, expand/collapse, single/multi selection, async lazy-loading, and viewport virtualization. Ported from [ink-tree-view](https://github.com/costajohnt/ink-tree-view).

```tsx
import { TreeView } from "@visulima/tui/components/tree-view";
import type { TreeNode } from "@visulima/tui/components/tree-view";
const data: TreeNode[] = [
    {
        id: "src",
        label: "src",
        children: [
            { id: "src/index.ts", label: "index.ts" },
            {
                id: "src/components",
                label: "components",
                children: [{ id: "src/components/App.tsx", label: "App.tsx" }],
            },
        ],
    },
    { id: "package.json", label: "package.json" },
];

<TreeView data={data} defaultExpanded="all" />;
```

### Keyboard controls [#keyboard-controls]

| Key       | Action                                                  |
| --------- | ------------------------------------------------------- |
| `↑` / `↓` | Move focus                                              |
| `→`       | Expand node, or move to first child if already expanded |
| `←`       | Collapse node, or move to parent if already collapsed   |
| `Enter`   | Toggle expand (none mode) or select (single/multi mode) |
| `Space`   | Toggle selection (multi mode) or expand (none/single)   |
| `Home`    | Focus first node                                        |
| `End`     | Focus last node                                         |

### Props [#props-2]

| Prop               | Type                                               | Default       | Description                                                                            |
| ------------------ | -------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `data`             | `TreeNode\<T>[]`                                   | *(required)*  | Tree data. Must be referentially stable (use `useMemo`).                               |
| `selectionMode`    | `"none"` \| `"single"` \| `"multiple"`             | `"none"`      | `"single"` shows a tick, `"multiple"` shows checkboxes.                                |
| `defaultExpanded`  | `ReadonlySet\<string>` \| `"all"`                  | —             | IDs of nodes expanded on mount. Pass `"all"` to expand everything.                     |
| `defaultSelected`  | `ReadonlySet\<string>`                             | —             | IDs of nodes selected on mount.                                                        |
| `visibleNodeCount` | `number`                                           | `Infinity`    | Limits visible rows (viewport virtualization). Scroll indicators appear automatically. |
| `renderNode`       | `(props: TreeNodeRendererProps\<T>) => ReactNode`  | —             | Custom node renderer. Receives `{ node, state }`.                                      |
| `loadChildren`     | `(node: TreeNode\<T>) => Promise\<TreeNode\<T>[]>` | —             | Async function called when expanding a node with `isParent: true` and no children.     |
| `onFocusChange`    | `(nodeId: string) => void`                         | —             | Called when the focused node changes.                                                  |
| `onExpandChange`   | `(expandedIds: ReadonlySet\<string>) => void`      | —             | Called when the expanded set changes.                                                  |
| `onSelectChange`   | `(selectedIds: ReadonlySet\<string>) => void`      | —             | Called when the selection changes.                                                     |
| `onLoadError`      | `(nodeId: string, error: Error) => void`           | —             | Called when `loadChildren` rejects.                                                    |
| `isDisabled`       | `boolean`                                          | `false`       | Ignores keyboard input when `true`.                                                    |
| `ariaLabel`        | `string`                                           | `"Tree view"` | Accessible label for the tree container.                                               |

### `TreeNode\<T>` shape [#treenodet-shape]

```ts
type TreeNode<T = Record<string, unknown>> = {
    id: string; // unique across the whole tree
    label: string; // display text
    data?: T; // arbitrary user data
    children?: TreeNode<T>[]; // child nodes
    isParent?: boolean; // show expand indicator even with no children (for async loading)
};
```

### Custom rendering [#custom-rendering]

Use `renderNode` for full control over each row:

```tsx
<TreeView
    data={data}
    defaultExpanded="all"
    renderNode={({ node, state }) => (
        <Box gap={1}>
            <Text dimColor>{"  ".repeat(state.depth)}</Text>
            <Text color={state.isFocused ? "blue" : undefined}>
                {state.hasChildren ? (state.isExpanded ? "📂" : "📁") : "📄"} {node.label}
            </Text>
        </Box>
    )}
/>
```

### Async lazy-loading [#async-lazy-loading]

Mark nodes with `isParent: true` and provide a `loadChildren` callback:

```tsx
const data: TreeNode[] = [{ id: "root", label: "Remote Files", isParent: true }];

<TreeView
    data={data}
    loadChildren={async (node) => {
        const response = await fetch(`/api/files/${node.id}`);
        return response.json();
    }}
    onLoadError={(nodeId, error) => console.error(`Failed to load ${nodeId}:`, error)}
/>;
```

A loading indicator (`⟳`) is shown while children are being fetched.

### Viewport virtualization [#viewport-virtualization]

Limit the visible rows for large trees:

```tsx
<TreeView data={largeTree} defaultExpanded="all" visibleNodeCount={15} />
```

Scroll indicators (`↑ N more above` / `↓ N more below`) appear automatically.

### Headless usage [#headless-usage]

For full control, use the hooks directly instead of the `\<TreeView>` component:

```tsx
import { useTreeView, useTreeViewState } from "@visulima/tui/components/tree-view";
function CustomTree({ data }) {
    const state = useTreeViewState({ data, selectionMode: "single" });
    useTreeView({ state, selectionMode: "single" });

    return (
        <Box flexDirection="column">
            {state.viewportNodes.map(({ node, state: nodeState }) => (
                <Text key={node.id} color={nodeState.isFocused ? "blue" : undefined}>
                    {"  ".repeat(nodeState.depth)}
                    {nodeState.isExpanded ? "▾" : nodeState.hasChildren ? "▸" : " "} {node.label}
                </Text>
            ))}
        </Box>
    );
}
```

### Theming [#theming]

The default theme can be imported and inspected:

```tsx
import { treeViewTheme } from "@visulima/tui/components/tree-view";
// treeViewTheme.styles.label({ isFocused: true, isSelected: false })
// => { color: "blue" }
```

For full visual customization, prefer `renderNode` over theme overrides.

## `Accordion` [#accordion]

Keyboard-navigable accordion. Arrow keys (or `j`/`k`) move between panels; Enter or Space toggles.

| Prop              | Type                | Default  | Description                        |
| ----------------- | ------------------- | -------- | ---------------------------------- |
| `items`           | `AccordionItem[]`   | required | Panels (`{ id, title, content }`)  |
| `allowMultiple`   | `boolean`           | `false`  | Allow multiple panels open at once |
| `defaultExpanded` | `readonly string[]` | —        | Ids open on mount                  |
| `accentColor`     | `string`            | `"blue"` | Color of the focused header        |
| `autoFocus`       | `boolean`           | `false`  | Auto-focus the first item on mount |
| `isDisabled`      | `boolean`           | `false`  | Disable input                      |

```tsx
<Accordion items={[{ id: "one", title: "Section 1", content: <Text>Body</Text> }]} />
```

## `AnimatePresence` [#animatepresence]

Orchestrates enter / exit animations for keyed children. Wrap a dynamic list of `\<Transition />` (or any component accepting `show: boolean` + `onExit`) to keep outgoing children mounted until their exit animation finishes.

```tsx
<AnimatePresence>
    {visible && (
        <Transition key="banner" preset="slide-down">
            <Text>Saved!</Text>
        </Transition>
    )}
</AnimatePresence>
```

Children must have a `key` to be tracked. Components opt in by exposing `show` + `onExit` props or by setting a static `isAnimatable = true` on the component type.

## `ApprovalPrompt` [#approvalprompt]

Three-way prompt for tool calls. `y` / Enter → `allow-once`, `a` → `allow-always`, `n` / Esc → `deny`.

| Prop          | Type                            | Default    | Description                           |
| ------------- | ------------------------------- | ---------- | ------------------------------------- |
| `tool`        | `string`                        | required   | Name of the action under review       |
| `onDecision`  | `(d: ApprovalDecision) => void` | required   | Resolution callback                   |
| `risk`        | `"low" \| "medium" \| "high"`   | `"medium"` | Severity badge / border color         |
| `description` | `string`                        | —          | Body text                             |
| `params`      | `Record\<string, unknown>`      | —          | Key=value preview                     |
| `children`    | `ReactNode`                     | —          | Optional body (diff, command preview) |
| `accentColor` | `string`                        | risk color | Override option-letter color          |
| `autoFocus`   | `boolean`                       | `true`     | Auto-focus on mount                   |
| `isDisabled`  | `boolean`                       | `false`    | Disable input                         |

```tsx
<ApprovalPrompt tool="bash" risk="high" params={{ cmd: "rm -rf /" }} onDecision={resolve} />
```

## `AreaChart` [#areachart]

Line chart with the area between each line and the baseline filled with shaded blocks.

| Prop          | Type                             | Default    | Description                                |
| ------------- | -------------------------------- | ---------- | ------------------------------------------ |
| `series`      | `LineSeries[]`                   | required   | Series to plot (same shape as `LineChart`) |
| `width`       | `number`                         | `40`       | Plot width in columns                      |
| `height`      | `number`                         | `10`       | Plot height in rows                        |
| `fillDensity` | `"light" \| "medium" \| "heavy"` | `"medium"` | Glyph used for the fill                    |
| `minY`/`maxY` | `number`                         | auto       | Y-axis bounds                              |
| `palette`     | `string[]`                       | default    | Fallback colors                            |
| `axisColor`   | `string`                         | `"gray"`   | Axis label color                           |
| `showLegend`  | `boolean`                        | `true`     | Render the legend                          |

```tsx
<AreaChart series={[{ name: "load", data: [1, 4, 2, 5, 3] }]} />
```

## `BarChart` [#barchart]

Vertical or horizontal bar chart. Uses braille / block glyphs.

| Prop          | Type                         | Default      | Description                              |
| ------------- | ---------------------------- | ------------ | ---------------------------------------- |
| `data`        | `BarDatum[]`                 | required     | `{ value, label?, color? }` per bar      |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Bar orientation                          |
| `width`       | `number`                     | auto         | Plot width in columns                    |
| `height`      | `number`                     | `10`         | Plot height in rows                      |
| `max`         | `number`                     | auto         | Upper bound for the axis                 |
| `palette`     | `string[]`                   | default      | Fallback colors                          |
| `showLabels`  | `boolean`                    | `true`       | Render labels under (or beside) each bar |
| `showValues`  | `boolean`                    | `false`      | Render numeric values next to each bar   |

```tsx
<BarChart
    data={[
        { value: 12, label: "Mon" },
        { value: 8, label: "Tue" },
    ]}
/>
```

## `BlinkDot` [#blinkdot]

Steady or blinking indicator dot.

| Prop        | Type      | Default | Description                                      |
| ----------- | --------- | ------- | ------------------------------------------------ |
| `character` | `string`  | `"●"`   | Glyph                                            |
| `color`     | `string`  | `"red"` | Color                                            |
| `interval`  | `number`  | `800`   | Milliseconds per blink cycle                     |
| `isActive`  | `boolean` | `true`  | When `false`, the dot stays solid (no animation) |

```tsx
<BlinkDot color="green" /> Connected
```

## `Breadcrumb` [#breadcrumb]

Render a breadcrumb trail; the last item is highlighted as the current location.

| Prop           | Type               | Default  | Description                |
| -------------- | ------------------ | -------- | -------------------------- |
| `items`        | `BreadcrumbItem[]` | required | `{ label, icon?, key? }`   |
| `separator`    | `string`           | `"›"`    | Separator glyph            |
| `currentColor` | `string`           | `"blue"` | Color applied to last item |

```tsx
<Breadcrumb items={[{ label: "Home" }, { label: "Settings" }, { label: "Profile" }]} />
```

## `Button` [#button]

Focusable button. Triggers `onPress` on Enter or Space.

| Prop          | Type                                               | Default     | Description                   |
| ------------- | -------------------------------------------------- | ----------- | ----------------------------- |
| `children`    | `ReactNode`                                        | required    | Label                         |
| `onPress`     | `() => void`                                       | —           | Pressed callback              |
| `variant`     | `"primary" \| "secondary" \| "outline" \| "ghost"` | `"primary"` | Visual style                  |
| `accentColor` | `string`                                           | `"blue"`    | Color when focused            |
| `autoFocus`   | `boolean`                                          | `false`     | Focus on mount                |
| `isDisabled`  | `boolean`                                          | `false`     | Ignores input and renders dim |

```tsx
<Button onPress={() => save()} autoFocus>
    Save
</Button>
```

## `Calendar` [#calendar]

Month grid with keyboard navigation. Arrow keys move day-by-day; Enter submits.

| Prop             | Type                | Default   | Description                       |
| ---------------- | ------------------- | --------- | --------------------------------- |
| `value`          | `Date`              | —         | Controlled selected date          |
| `defaultValue`   | `Date`              | today     | Initial selection (uncontrolled)  |
| `onChange`       | `(d: Date) => void` | —         | Called on navigation or selection |
| `onSubmit`       | `(d: Date) => void` | —         | Called on Enter                   |
| `minDate`        | `Date`              | —         | Lower bound                       |
| `maxDate`        | `Date`              | —         | Upper bound                       |
| `firstDayOfWeek` | `0 \| 1`            | `1`       | Sunday (`0`) or Monday (`1`)      |
| `accentColor`    | `string`            | `"blue"`  | Color of today / focused cell     |
| `selectedColor`  | `string`            | `"green"` | Color of the selected day         |
| `autoFocus`      | `boolean`           | `false`   | Auto-focus on mount               |
| `isDisabled`     | `boolean`           | `false`   | Disable input                     |

```tsx
<Calendar onSubmit={(d) => setDate(d)} autoFocus />
```

## `Canvas` [#canvas]

A fixed-size cell grid backed by typed arrays. The imperative `draw` callback paints into a `CanvasContext`; only rows the draw pass dirties are re-serialized. Bumping `version` invalidates the cache.

| Prop      | Type                           | Description                                 |
| --------- | ------------------------------ | ------------------------------------------- |
| `width`   | `number`                       | Columns (cells horizontally)                |
| `height`  | `number`                       | Rows                                        |
| `draw`    | `(ctx: CanvasContext) => void` | Draw callback                               |
| `version` | `unknown`                      | Cache invalidation key (data hash, counter) |

```tsx
<Canvas width={20} height={5} version={frame} draw={(ctx) => ctx.setCell(0, 0, "█", { color: "cyan" })} />
```

This is the foundation for chart components (`LineChart`, `BarChart`, `Heatmap`, `ScatterPlot`).

## `Card` [#card]

Container with optional title, subtitle, header-right, and footer.

| Prop          | Type               | Default   | Description                      |
| ------------- | ------------------ | --------- | -------------------------------- |
| `children`    | `ReactNode`        | required  | Body                             |
| `title`       | `string`           | —         | Heading                          |
| `subtitle`    | `string`           | —         | Sub-heading                      |
| `headerRight` | `ReactNode`        | —         | Content rendered after the title |
| `footer`      | `ReactNode`        | —         | Footer below body                |
| `borderColor` | `string`           | —         | Border color                     |
| `titleColor`  | `string`           | —         | Title color                      |
| `borderStyle` | border preset      | `"round"` | Passed to `Box`                  |
| `width`       | `number \| string` | fill      | Card width                       |

```tsx
<Card title="Build" subtitle="Step 2 of 3" footer={<Text dimColor>Press q to cancel</Text>}>
    <Text>Bundling…</Text>
</Card>
```

## `Checkbox` [#checkbox]

Toggleable boolean input.

| Prop             | Type                         | Default  | Description                  |
| ---------------- | ---------------------------- | -------- | ---------------------------- |
| `isChecked`      | `boolean`                    | —        | Controlled checked state     |
| `defaultChecked` | `boolean`                    | `false`  | Initial state (uncontrolled) |
| `onChange`       | `(checked: boolean) => void` | —        | Called on toggle             |
| `children`       | `ReactNode`                  | —        | Label                        |
| `accentColor`    | `string`                     | `"blue"` | Color when focused           |
| `autoFocus`      | `boolean`                    | `false`  | Focus on mount               |
| `isDisabled`     | `boolean`                    | `false`  | Disable input                |

```tsx
<Checkbox onChange={setEnabled}>Enable notifications</Checkbox>
```

## `Collapsible` [#collapsible]

Toggleable section with a focusable header.

| Prop          | Type                      | Default  | Description                  |
| ------------- | ------------------------- | -------- | ---------------------------- |
| `title`       | `ReactNode`               | required | Header label                 |
| `children`    | `ReactNode`               | required | Body shown when open         |
| `defaultOpen` | `boolean`                 | `false`  | Initial state (uncontrolled) |
| `isOpen`      | `boolean`                 | —        | Controlled open state        |
| `onToggle`    | `(open: boolean) => void` | —        | Called on toggle             |
| `accentColor` | `string`                  | `"blue"` | Header color when focused    |
| `autoFocus`   | `boolean`                 | `false`  | Focus on mount               |
| `isDisabled`  | `boolean`                 | `false`  | Disable interaction          |

## `CommandBlock` [#commandblock]

Render a shell command and its output with a status header.

| Prop            | Type                                          | Default  | Description                             |
| --------------- | --------------------------------------------- | -------- | --------------------------------------- |
| `command`       | `string`                                      | required | Command rendered in the header          |
| `status`        | `"idle" \| "running" \| "success" \| "error"` | `"idle"` | Lifecycle state — drives icon and color |
| `cwd`           | `string`                                      | —        | Working directory shown after command   |
| `output`        | `ReactNode`                                   | —        | Output (string or any node)             |
| `exitCode`      | `number`                                      | —        | Exit code shown when finished           |
| `durationMs`    | `number`                                      | —        | Duration shown when finished            |
| `maxOutputRows` | `number`                                      | —        | Truncate output beyond this many rows   |

## `CommandPalette` [#commandpalette]

Searchable command palette.

| Prop          | Type                                  | Default                         | Description                |
| ------------- | ------------------------------------- | ------------------------------- | -------------------------- |
| `commands`    | `CommandEntry[]`                      | required                        | Entries to search          |
| `onSelect`    | `(id: string, query: string) => void` | required                        | Selection callback         |
| `onCancel`    | `() => void`                          | —                               | Called on Escape           |
| `limit`       | `number`                              | `8`                             | Max rows                   |
| `placeholder` | `string`                              | `"Type a command or search..."` | Search field placeholder   |
| `emptyText`   | `string`                              | `"No results"`                  | Shown when no matches      |
| `accentColor` | `string`                              | `"cyan"`                        | Border / focused row color |
| `autoFocus`   | `boolean`                             | `false`                         | Auto-focus on mount        |

## `ConfirmDialog` [#confirmdialog]

Modal confirm prompt with focusable buttons.

| Prop           | Type                              | Default     | Description              |
| -------------- | --------------------------------- | ----------- | ------------------------ |
| `onConfirm`    | `() => void`                      | required    | Confirm callback         |
| `onCancel`     | `() => void`                      | required    | Cancel callback          |
| `title`        | `string`                          | —           | Heading                  |
| `children`     | `ReactNode`                       | —           | Body content             |
| `confirmLabel` | `string`                          | `"Confirm"` | Confirm button label     |
| `cancelLabel`  | `string`                          | `"Cancel"`  | Cancel button label      |
| `defaultFocus` | `"confirm" \| "cancel"`           | `"confirm"` | Initially focused button |
| `tone`         | `"info" \| "warning" \| "danger"` | `"info"`    | Border color             |
| `width`        | `number`                          | —           | Dialog width             |
| `autoFocus`    | `boolean`                         | `true`      | Auto-focus on mount      |
| `isDisabled`   | `boolean`                         | `false`     | Disable input            |

## `ContentSwitcher` [#contentswitcher]

Segmented control for picking among 2–5 options.

| Prop           | Type                      | Default  | Description                       |
| -------------- | ------------------------- | -------- | --------------------------------- |
| `options`      | `ContentSwitcherOption[]` | required | Segments (`{ id, label, icon? }`) |
| `value`        | `string`                  | —        | Controlled selected id            |
| `defaultValue` | `string`                  | first    | Initial selection (uncontrolled)  |
| `onChange`     | `(id: string) => void`    | —        | Called when the selection changes |
| `accentColor`  | `string`                  | `"blue"` | Color of the selected segment     |
| `autoFocus`    | `boolean`                 | `false`  | Auto-focus on mount               |
| `isDisabled`   | `boolean`                 | `false`  | Disable input                     |

## `DatePicker` [#datepicker]

Input row that opens an inline `Calendar` on focus / Enter.

| Prop           | Type                  | Default         | Description                     |
| -------------- | --------------------- | --------------- | ------------------------------- |
| `value`        | `Date`                | —               | Controlled selected date        |
| `defaultValue` | `Date`                | —               | Initial date (uncontrolled)     |
| `onChange`     | `(d: Date) => void`   | —               | Called when the user commits    |
| `placeholder`  | `string`              | `"Pick a date"` | Shown when no value is selected |
| `formatValue`  | `(d: Date) => string` | locale          | Custom display formatter        |
| `minDate`      | `Date`                | —               | Lower bound                     |
| `maxDate`      | `Date`                | —               | Upper bound                     |
| `accentColor`  | `string`              | `"blue"`        | Calendar accent color           |
| `autoFocus`    | `boolean`             | `false`         | Auto-focus on mount             |
| `isDisabled`   | `boolean`             | `false`         | Disable input                   |

## `DefinitionList` [#definitionlist]

Term/definition pairs.

| Prop        | Type                    | Default    | Description                                  |
| ----------- | ----------------------- | ---------- | -------------------------------------------- |
| `items`     | `DefinitionItem[]`      | required   | `{ term, description }` entries              |
| `layout`    | `"inline" \| "stacked"` | `"inline"` | Inline = same row; stacked = term above      |
| `termColor` | `string`                | `"cyan"`   | Color applied to the term                    |
| `termWidth` | `number`                | —          | Min width to align inline terms              |
| `columnGap` | `number`                | `2`        | Spacing between term and description columns |

## `Dialog` [#dialog]

Bordered, scrollable container that fills a fraction of the terminal. Used for modal-style overlays.

| Prop              | Type                  | Default     | Description                      |
| ----------------- | --------------------- | ----------- | -------------------------------- |
| `children`        | `ReactNode`           | required    | Dialog body                      |
| `title`           | `ReactNode`           | —           | Heading                          |
| `footer`          | `ReactNode`           | —           | Footer below the scrollable area |
| `visible`         | `boolean`             | `true`      | Render only when truthy          |
| `width`           | `number`              | `60`        | Width in columns                 |
| `maxHeight`       | `number`              | `0.8`       | Fraction (≤1) or absolute rows   |
| `borderStyle`     | border preset         | `"round"`   | Passed to `Box`                  |
| `borderColor`     | `string`              | `"cyan"`    | Border color                     |
| `backgroundColor` | `string`              | terminal bg | Dialog background                |
| `paddingX`        | `number`              | `2`         | Inner horizontal padding         |
| `paddingY`        | `number`              | `1`         | Inner vertical padding           |
| `scrollRef`       | `Ref\<ScrollViewRef>` | —           | Ref to the inner `ScrollView`    |
| `scrollbarStyle`  | scrollbar preset      | `"block"`   | Scrollbar visual style           |

## `Divider` [#divider]

Horizontal or vertical rule with an optional centered label.

| Prop           | Type                         | Default        | Description                                   |
| -------------- | ---------------------------- | -------------- | --------------------------------------------- |
| `orientation`  | `"horizontal" \| "vertical"` | `"horizontal"` | Direction                                     |
| `length`       | `number`                     | fill           | Total length                                  |
| `character`    | `string`                     | `─`/`│`        | Override the line glyph                       |
| `label`        | `string`                     | —              | Text rendered in the middle (horizontal only) |
| `labelPadding` | `number`                     | `1`            | Padding around the label                      |
| `color`        | `string`                     | —              | Line color                                    |
| `dimColor`     | `boolean`                    | `false`        | Render dim                                    |

```tsx
<Divider label="Settings" />
```

## `Form` [#form]

Layout primitive for forms — pairs nicely with `useForm` and the `\<Form.Field>` sub-component for label/error styling.

| Prop          | Type        | Default  | Description                        |
| ------------- | ----------- | -------- | ---------------------------------- |
| `children`    | `ReactNode` | required | `\<Form.Field>` rows (or any node) |
| `title`       | `string`    | —        | Heading                            |
| `description` | `string`    | —        | Subtitle below the heading         |
| `footer`      | `ReactNode` | —        | Footer (buttons, hints)            |
| `bordered`    | `boolean`   | `true`   | Render with a border               |
| `accentColor` | `string`    | `"blue"` | Form chrome accent                 |
| `width`       | `number`    | —        | Fixed width                        |

`Form.Field` accepts `{ label, description?, error?, required?, isDisabled?, children }` and renders consistent label + error styling around any control.

## `Gauge` [#gauge]

Numeric range display. Useful for usage / load / capacity readouts.

| Prop          | Type                             | Default    | Description                               |
| ------------- | -------------------------------- | ---------- | ----------------------------------------- |
| `value`       | `number`                         | required   | Current value (clamped into `[min, max]`) |
| `min`         | `number`                         | `0`        | Lower bound                               |
| `max`         | `number`                         | `100`      | Upper bound                               |
| `size`        | `"small" \| "medium" \| "large"` | `"medium"` | Dimension preset                          |
| `label`       | `string`                         | —          | Label rendered above the readout          |
| `formatValue` | `(v: number) => string`          | round      | Format the numeric readout                |
| `thresholds`  | `GaugeThreshold[]`               | —          | Color thresholds (see source)             |
| `showValue`   | `boolean`                        | `true`     | Show the numeric readout in the middle    |
| `showLegend`  | `boolean`                        | `false`    | Show a threshold legend below the gauge   |

## `Heading` [#heading]

Convenience wrapper around `Text` that picks color and decoration by level.

| Prop        | Type                         | Default  | Description                          |
| ----------- | ---------------------------- | -------- | ------------------------------------ |
| `children`  | `ReactNode`                  | required | Heading content                      |
| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1`      | Determines decoration / color        |
| `color`     | `string`                     | —        | Explicit color override              |
| `underline` | `boolean`                    | `false`  | Render an underline on a second line |

## `Heatmap` [#heatmap]

2D matrix rendered as a colored cell grid.

| Prop           | Type         | Default  | Description                        |
| -------------- | ------------ | -------- | ---------------------------------- |
| `data`         | `number[][]` | required | Rows × cols matrix                 |
| `cellWidth`    | `number`     | `2`      | Width of each cell in columns      |
| `character`    | `string`     | `"█"`    | Glyph painted in each cell         |
| `palette`      | `string[]`   | default  | Color ramp from low → high         |
| `min`/`max`    | `number`     | data     | Fixed bounds for consistent scales |
| `rowLabels`    | `string[]`   | —        | Labels rendered to the left        |
| `columnLabels` | `string[]`   | —        | Labels rendered below              |

(Type is `HeatmapProps`.)

## `Histogram` [#histogram]

Bin numeric values into bars.

| Prop         | Type       | Default  | Description                           |
| ------------ | ---------- | -------- | ------------------------------------- |
| `data`       | `number[]` | required | Raw values to bin                     |
| `bins`       | `number`   | `10`     | Number of equal-width buckets         |
| `thresholds` | `number[]` | —        | Explicit bin edges (overrides `bins`) |
| `min`/`max`  | `number`   | auto     | Fixed min/max                         |
| `width`      | `number`   | auto     | Plot width                            |
| `height`     | `number`   | `10`     | Plot height                           |
| `color`      | `string`   | —        | Bar color                             |
| `showValues` | `boolean`  | `false`  | Show the numeric count above each bar |

## `Kbd` [#kbd]

Render a single key cap.

| Prop       | Type                             | Default   | Description      |
| ---------- | -------------------------------- | --------- | ---------------- |
| `children` | `ReactNode`                      | required  | Key label        |
| `color`    | `string`                         | `"gray"`  | Background color |
| `variant`  | `"solid" \| "outline" \| "bare"` | `"solid"` | Visual style     |

```tsx
Press <Kbd>Ctrl</Kbd>+<Kbd>C</Kbd> to copy.
```

## `LineChart` [#linechart]

Multi-series line chart drawn on a `Canvas` braille grid.

| Prop          | Type           | Default  | Description                        |
| ------------- | -------------- | -------- | ---------------------------------- |
| `series`      | `LineSeries[]` | required | Series (`{ name?, data, color? }`) |
| `width`       | `number`       | `40`     | Plot width in columns              |
| `height`      | `number`       | `10`     | Plot height in rows                |
| `minY`/`maxY` | `number`       | auto     | Y-axis bounds                      |
| `palette`     | `string[]`     | default  | Fallback colors                    |
| `axisColor`   | `string`       | `"gray"` | Axis tick color                    |
| `showLegend`  | `boolean`      | `true`   | Show legend                        |

(Type is `LineChartProps`.)

## `LoadingIndicator` [#loadingindicator]

Spinner + optional inline message.

| Prop       | Type          | Default  | Description                                 |
| ---------- | ------------- | -------- | ------------------------------------------- |
| `type`     | `SpinnerName` | `"dots"` | `@visulima/spinner` preset                  |
| `color`    | `string`      | `"cyan"` | Spinner and label color                     |
| `children` | `ReactNode`   | —        | Optional message rendered after the spinner |

```tsx
<LoadingIndicator>Building…</LoadingIndicator>
```

## `MaskedInput` [#maskedinput]

Single-line input constrained by a literal mask. `#` (or a custom token) marks editable positions; every other character is rendered literally.

| Prop              | Type                      | Default  | Description                            |
| ----------------- | ------------------------- | -------- | -------------------------------------- |
| `mask`            | `string`                  | required | Mask, e.g. `"(###) ###-####"`          |
| `defaultValue`    | `string`                  | `""`     | Initial raw value (no mask characters) |
| `onChange`        | `(value: string) => void` | —        | Called whenever the raw value changes  |
| `onSubmit`        | `(value: string) => void` | —        | Called on Enter                        |
| `token`           | `string`                  | `"#"`    | Editable-position marker               |
| `placeholderChar` | `string`                  | `"_"`    | Character shown in empty positions     |
| `isDisabled`      | `boolean`                 | `false`  | Disable input                          |

## `Menu` [#menu]

Vertical menu with optional sections, icons, and shortcuts.

| Prop          | Type                   | Default  | Description                              |
| ------------- | ---------------------- | -------- | ---------------------------------------- |
| `onSelect`    | `(id: string) => void` | required | Selection callback                       |
| `items`       | `MenuItem[]`           | —        | Flat list (ignored if `sections` is set) |
| `sections`    | `MenuSection[]`        | —        | Grouped items                            |
| `title`       | `string`               | —        | Header                                   |
| `bordered`    | `boolean`              | `true`   | Render a border                          |
| `accentColor` | `string`               | `"blue"` | Color of the focused row                 |
| `autoFocus`   | `boolean`              | `false`  | Auto-focus on mount                      |

## `MessageBubble` [#messagebubble]

Conversation bubble with a role-based icon and color.

| Prop       | Type                                          | Default       | Description                                 |
| ---------- | --------------------------------------------- | ------------- | ------------------------------------------- |
| `children` | `ReactNode`                                   | required      | Bubble body                                 |
| `role`     | `"user" \| "assistant" \| "system" \| "tool"` | `"assistant"` | Determines alignment, color, icon           |
| `label`    | `string`                                      | —             | Text rendered above the bubble              |
| `meta`     | `string`                                      | —             | Metadata next to the label (e.g. timestamp) |
| `color`    | `string`                                      | —             | Override the role color                     |
| `flat`     | `boolean`                                     | `false`       | Render without a border                     |

## `ModelBadge` [#modelbadge]

Compact badge for model names.

| Prop       | Type                               | Default     | Description                             |
| ---------- | ---------------------------------- | ----------- | --------------------------------------- |
| `model`    | `string`                           | required    | Model identifier                        |
| `provider` | `string`                           | —           | Provider chip rendered before the model |
| `icon`     | `ReactNode`                        | —           | Optional icon                           |
| `color`    | `string`                           | `"magenta"` | Background color                        |
| `variant`  | `"solid" \| "subtle" \| "outline"` | `"solid"`   | Visual style                            |

```tsx
<ModelBadge model="claude-opus-4.7" provider="Anthropic" />
```

## `OperationTree` [#operationtree]

Tree-shaped task list. Each node carries a status (`pending`, `running`, `completed`, `error`, `skipped`); running nodes show a spinner.

| Prop          | Type              | Default  | Description           |
| ------------- | ----------------- | -------- | --------------------- |
| `nodes`       | `OperationNode[]` | required | Tree of operations    |
| `showSpinner` | `boolean`         | `true`   | Animate running nodes |

## `OptionList` [#optionlist]

Static list with optional icons / descriptions / shortcuts. Non-interactive (use `SelectInput` or `Menu` for navigable lists).

| Prop              | Type                | Default  | Description                     |
| ----------------- | ------------------- | -------- | ------------------------------- |
| `options`         | `OptionListEntry[]` | required | Entries (`{ id, label, ... }`)  |
| `currentId`       | `string`            | —        | Id of the row to highlight      |
| `accentColor`     | `string`            | —        | Highlight color                 |
| `bordered`        | `boolean`           | `false`  | Render with a border            |
| `iconColumnWidth` | `number`            | `2`      | Icon column width for alignment |

## `Paragraph` [#paragraph]

Block-level wrapper around `Text` with vertical margin. Useful inside long-form layouts.

| Prop           | Type        | Default  | Description        |
| -------------- | ----------- | -------- | ------------------ |
| `children`     | `ReactNode` | required | Paragraph body     |
| `color`        | `string`    | —        | Foreground color   |
| `dimColor`     | `boolean`   | `false`  | Render dim         |
| `marginTop`    | `number`    | `0`      | Blank lines before |
| `marginBottom` | `number`    | `1`      | Blank lines after  |

## `Placeholder` [#placeholder]

Skeleton blocks for loading states.

| Prop        | Type       | Default          | Description                      |
| ----------- | ---------- | ---------------- | -------------------------------- |
| `rows`      | `number`   | `3`              | Number of skeleton rows          |
| `widths`    | `number[]` | `[1, 0.85, 0.6]` | Per-row width fractions (cycled) |
| `width`     | `number`   | fill             | Total width reference            |
| `character` | `string`   | `"█"`            | Fill character                   |
| `color`     | `string`   | `"gray"`         | Block color                      |
| `animated`  | `boolean`  | `true`           | Pulse the blocks                 |
| `interval`  | `number`   | `500`            | Pulse interval (ms)              |

## `RadioGroup` [#radiogroup]

Single-choice list of options.

| Prop               | Type                         | Default      | Description                                                                                             |
| ------------------ | ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `options`          | `RadioOption[]`              | required     | Choices (`{ value, label, ... }`)                                                                       |
| `value`            | `string`                     | —            | Controlled selected value                                                                               |
| `defaultValue`     | `string`                     | —            | Initial value (uncontrolled)                                                                            |
| `onChange`         | `(value: string) => void`    | —            | Called when selection changes                                                                           |
| `onSubmit`         | `(value: string) => void`    | —            | Called on Enter                                                                                         |
| `orientation`      | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction                                                                                        |
| `commitOnNavigate` | `boolean`                    | `true`       | If true, arrow keys commit and fire `onChange`. If false, focus is independent and Space/Enter commits. |
| `accentColor`      | `string`                     | `"blue"`     | Color of focused / selected indicator                                                                   |
| `autoFocus`        | `boolean`                    | `false`      | Auto-focus on mount                                                                                     |
| `isDisabled`       | `boolean`                    | `false`      | Disable input                                                                                           |

## `ScatterPlot` [#scatterplot]

Scatter chart drawn on a braille `Canvas`. Uses `LineSeries` (the `data` array supplies points).

| Prop          | Type           | Default  | Description            |
| ------------- | -------------- | -------- | ---------------------- |
| `series`      | `LineSeries[]` | required | Series of points       |
| `width`       | `number`       | `40`     | Plot width             |
| `height`      | `number`       | `10`     | Plot height            |
| `minX`/`maxX` | `number`       | auto     | X-axis bounds          |
| `minY`/`maxY` | `number`       | auto     | Y-axis bounds          |
| `palette`     | `string[]`     | default  | Series fallback colors |
| `axisColor`   | `string`       | `"gray"` | Axis label color       |
| `showLegend`  | `boolean`      | `true`   | Show legend            |

## `SearchInput` [#searchinput]

Single-line search input with leading icon and optional autocomplete suggestions.

| Prop           | Type                      | Default       | Description              |
| -------------- | ------------------------- | ------------- | ------------------------ |
| `defaultValue` | `string`                  | `""`          | Initial value            |
| `onChange`     | `(value: string) => void` | —             | Fired on every keystroke |
| `onSubmit`     | `(value: string) => void` | —             | Fired on Enter           |
| `placeholder`  | `string`                  | `"Search..."` | Empty-state text         |
| `icon`         | `ReactNode`               | `"⌕"`         | Leading icon             |
| `suggestions`  | `string[]`                | —             | Autocomplete candidates  |
| `accentColor`  | `string`                  | `"blue"`      | Border / icon color      |
| `isDisabled`   | `boolean`                 | `false`       | Disable input            |

## `SelectInputIndicator` / `SelectInputItem` [#selectinputindicator--selectinputitem]

Default sub-components used by `\<SelectInput>` for the indicator and item rendering. Exported so custom components can re-use the styling primitives, or so consumers can pass them through `indicatorComponent`/`itemComponent` props.

`SelectInputIndicator` accepts `{ isSelected?, isFocused?, accentColor? }`.

`SelectInputItem` accepts `{ label, isSelected?, isFocused?, accentColor?, defaultColor? }`.

## `ShimmerText` [#shimmertext]

Text with a sweeping highlight band — a lightweight skeleton/loading effect.

| Prop             | Type     | Default   | Description                          |
| ---------------- | -------- | --------- | ------------------------------------ |
| `text`           | `string` | required  | Text to render                       |
| `bandWidth`      | `number` | `3`       | Width of the highlight in characters |
| `interval`       | `number` | `60`      | Frame interval (ms)                  |
| `color`          | `string` | —         | Base text color                      |
| `highlightColor` | `string` | `"white"` | Highlight band color                 |

## `Sparkline` [#sparkline]

Tiny inline chart drawn with the eight Unicode block glyphs.

| Prop    | Type       | Default  | Description    |
| ------- | ---------- | -------- | -------------- |
| `data`  | `number[]` | required | Values to plot |
| `min`   | `number`   | data     | Fixed minimum  |
| `max`   | `number`   | data     | Fixed maximum  |
| `color` | `string`   | —        | Glyph color    |

```tsx
<Sparkline data={[1, 4, 2, 5, 3, 7, 6]} color="cyan" />
```

## `StaticRender` [#staticrender]

Pre-renders its children once and caches the result on the underlying DOM node. The next layout pass composites the cached region directly via `addRegionTree()`, skipping the entire subtree traversal.

`StaticRender` is a featured perf primitive used heavily by `vis` for completed-task output, log lines, and other content that does not change.

```tsx
<StaticRender deps={[completed.length]}>
    {() => (
        <Box flexDirection="column">
            {completed.map((task) => (
                <Text key={task.id} color="green">
                    ✓ {task.name}
                </Text>
            ))}
        </Box>
    )}
</StaticRender>
```

| Prop       | Type              | Default  | Description                                                                                                                                                                                                                             |
| ---------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `() => ReactNode` | required | Render function invoked once. The result is cached and composited on subsequent renders.                                                                                                                                                |
| `deps`     | `DependencyList`  | —        | React-style dependency array (shallow `Object.is` comparison). When any entry changes the cache is invalidated and `children()` is invoked again. If omitted, the cache invalidates whenever the `children` function reference changes. |
| `style`    | `Styles`          | —        | Style applied to the static-render container                                                                                                                                                                                            |
| `width`    | `number`          | —        | Fixed width for the cached region                                                                                                                                                                                                       |

Pass a stable `deps` array (or memoize the `children` function) — otherwise a fresh function identity on every render forces a re-render.

> Distinct from `\<Static>`, which is the append-only Ink primitive for completed log lines.

## `StatusLine` [#statusline]

Single-row status bar with `left` / `center` / `right` slots.

| Prop              | Type        | Default | Description                  |
| ----------------- | ----------- | ------- | ---------------------------- |
| `left`            | `ReactNode` | —       | Content rendered flush-left  |
| `center`          | `ReactNode` | —       | Content rendered centered    |
| `right`           | `ReactNode` | —       | Content rendered flush-right |
| `color`           | `string`    | —       | Default foreground           |
| `backgroundColor` | `string`    | —       | Background spanning the row  |

```tsx
<StatusLine left={<Text>main</Text>} right={<Text>UTF-8 · LF</Text>} />
```

## `Stepper` [#stepper]

Progress indicator across discrete steps.

| Prop          | Type                         | Default        | Description                                          |
| ------------- | ---------------------------- | -------------- | ---------------------------------------------------- |
| `steps`       | `StepperStep[]`              | required       | List of steps                                        |
| `activeIndex` | `number`                     | `0`            | Index of the current step (when steps lack a status) |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction                                     |
| `accentColor` | `string`                     | `"blue"`       | Color for active / completed steps                   |
| `errorColor`  | `string`                     | `"red"`        | Color for error steps                                |

## `StreamingText` [#streamingtext]

Reveal text one character at a time. Useful for typing-style output (LLM streaming, intros).

| Prop                 | Type         | Default  | Description                                |
| -------------------- | ------------ | -------- | ------------------------------------------ |
| `text`               | `string`     | required | Full text to stream                        |
| `interval`           | `number`     | `20`     | Milliseconds between characters            |
| `cursor`             | `string`     | `"▊"`    | Cursor character shown while streaming     |
| `showCursorWhenDone` | `boolean`    | `false`  | Keep the cursor after streaming completes  |
| `onComplete`         | `() => void` | —        | Called once per `text` value when complete |
| `color`              | `string`     | —        | Text color                                 |

## `Switch` [#switch]

Toggle switch with a labelled track.

| Prop           | Type                       | Default         | Description                     |
| -------------- | -------------------------- | --------------- | ------------------------------- |
| `value`        | `boolean`                  | —               | Controlled value                |
| `defaultValue` | `boolean`                  | `false`         | Initial value (uncontrolled)    |
| `onChange`     | `(value: boolean) => void` | —               | Called on toggle                |
| `children`     | `ReactNode`                | —               | Label rendered after the switch |
| `labels`       | `[string, string]`         | `["off", "on"]` | Track labels                    |
| `accentColor`  | `string`                   | `"green"`       | Color when on                   |
| `autoFocus`    | `boolean`                  | `false`         | Focus on mount                  |
| `isDisabled`   | `boolean`                  | `false`         | Disable input                   |

## `Tag` [#tag]

Inline label / chip.

| Prop       | Type                               | Default    | Description             |
| ---------- | ---------------------------------- | ---------- | ----------------------- |
| `children` | `ReactNode`                        | required   | Tag content             |
| `color`    | `string`                           | `"blue"`   | Base color              |
| `icon`     | `ReactNode`                        | —          | Optional leading symbol |
| `variant`  | `"subtle" \| "solid" \| "outline"` | `"subtle"` | Visual style            |

## `Toast` [#toast]

Auto-dismissing notification.

| Prop        | Type                                          | Default  | Description                                       |
| ----------- | --------------------------------------------- | -------- | ------------------------------------------------- |
| `children`  | `ReactNode`                                   | required | Body                                              |
| `title`     | `string`                                      | —        | Optional title before the body                    |
| `variant`   | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Determines icon and border color                  |
| `duration`  | `number`                                      | `4000`   | Auto-dismiss timeout (ms); `0` disables           |
| `onDismiss` | `() => void`                                  | —        | Called after auto-dismiss                         |
| `visible`   | `boolean`                                     | —        | Manually control visibility (disables `duration`) |
| `width`     | `number`                                      | —        | Optional fixed width                              |

## `Tooltip` [#tooltip]

Inline tooltip attached to an anchor element. Terminal rendering does not support floating layers, so the tooltip is placed inline next to (or above / below) the anchor.

| Prop        | Type                                     | Default   | Description             |
| ----------- | ---------------------------------------- | --------- | ----------------------- |
| `children`  | `ReactNode`                              | required  | Anchor content          |
| `content`   | `ReactNode`                              | required  | Tooltip body            |
| `placement` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Relative position       |
| `color`     | `string`                                 | `"gray"`  | Border color            |
| `isVisible` | `boolean`                                | `true`    | Render only when truthy |

## `Transition` [#transition]

Animate enter / exit of a child subtree. Pair with `\<AnimatePresence>` to keep outgoing children mounted until exit completes.

| Prop           | Type                                                                                | Default  | Description                                                                       |
| -------------- | ----------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `children`     | `ReactNode`                                                                         | required | Content to animate                                                                |
| `show`         | `boolean`                                                                           | `true`   | Drive towards `entered` (true) or `exited` (false). Flip to trigger an animation. |
| `preset`       | `"fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "reveal"` | `"fade"` | Animation preset                                                                  |
| `duration`     | `number`                                                                            | `240`    | Total duration in milliseconds                                                    |
| `distance`     | `number`                                                                            | `4`      | Slide offset (slide presets) or row span (reveal)                                 |
| `tickInterval` | `number`                                                                            | `30`     | Frame interval in milliseconds                                                    |
| `onExit`       | `() => void`                                                                        | —        | Called once the exit animation finishes (used by `\<AnimatePresence>`)            |


# Decisions (/docs/packages/tui/decisions)



# Architecture Decisions [#architecture-decisions]

> Part of the [TUI docs](/docs/packages/tui). See also: [Render Loop](/docs/packages/tui/render-loop) · [Raw Buffer API](/docs/packages/tui/raw-buffer)

Key design decisions made during development, with rationale.

***

## Render loop: game engine style `setInterval` poll [#render-loop-game-engine-style-setinterval-poll]

The native renderer uses a `setInterval`-driven render loop (default 60fps) rather than painting synchronously from `resetAfterCommit`. React 18's concurrent scheduler in Node.js uses `setImmediate` to batch and defer work — timer-driven state updates (`setTimeout`, streaming, async) pile up and don't commit until the next user input event flushes the scheduler. This makes the `resetAfterCommit` hook unreliable as a paint trigger.

The loop decouples painting from React scheduling: `resetAfterCommit` sets a `pendingCommit` flag, the loop polls and paints when set. Worst-case latency is one frame interval (16ms at 60fps). `maxFps` is tunable via `render()` options. See [render-loop.md](/docs/packages/tui/render-loop) for full detail.

## `onBeforeFlush`: direct buffer painting hook [#onbeforeflush-direct-buffer-painting-hook]

`app.onBeforeFlush(fn)` registers a callback that fires after React fills the `Uint32Array` buffer but before the Rust diff engine flushes to stdout. Used by examples that paint directly into the buffer (animated graphs, logo, stress-test) and by DevTools for FPS measurement. Supports multiple listeners (array, fires in registration order). Returns an unsubscribe function.

## Cell buffer: `[charCode, attrCode]` tuple [#cell-buffer-charcode-attrcode-tuple]

`Cell.pack()` returns a `[charCode, attrCode]` pair. An earlier design packed both into a single u32 which lost the char vs attr distinction and made buffer layout opaque.

## Color resolution in `styles.ts` [#color-resolution-in-stylests]

`resolveColor()` lives in `styles.ts` and is imported by both the reconciler and renderer. Putting it in the reconciler would create a circular dependency.

## `useApp()` returns `{ exit, quit }` [#useapp-returns--exit-quit-]

Ink uses `const { exit } = useApp()`. `exit` is the Ink-compat alias; `quit` is the native renderer name. Both call the same underlying `app.quit()`.

## `FocusProvider` + `TabHandler` wired inside `render()` [#focusprovider--tabhandler-wired-inside-render]

Every app tree is automatically wrapped with `<FocusProvider><TabHandler>`. Users get Tab/Shift+Tab focus cycling for free, matching Ink's behavior. The alternative (user-managed) forces boilerplate in every app.

## `yogaOwner` Map as authoritative parent registry [#yogaowner-map-as-authoritative-parent-registry]

`child.parent` (a LayoutNode reference) and Yoga's internal parent tracking both drift during React batch commits. A module-level `yogaOwner = new Map<YogaNode, LayoutNode>()` is the single source of truth for which LayoutNode owns a given Yoga node. `child.parent` is kept in sync but treated as secondary.

## Yoga `insertChild` index clamped to `getChildCount()` [#yoga-insertchild-index-clamped-to-getchildcount]

During React batch commits, the JS `children` array and Yoga's internal child list can diverge. We clamp: `safeIndex = Math.min(index, yogaNode.getChildCount())`. Yoga's "Child already has a parent" error is misleading — it's thrown for both OOB inserts and actual double-parent inserts.

## Yoga wasm call before JS bookkeeping [#yoga-wasm-call-before-js-bookkeeping]

If `yogaNode.insertChild` throws, updating `this.children` first leaves JS state permanently desync'd. Rule: always mutate the external/wasm state first, update JS only on success.

## `yogaNode.free()` called on destroy — safe after removeChild [#yoganodefree-called-on-destroy--safe-after-removechild]

Calling `free()` in `destroy()` is safe. React's commit order guarantees `removeChild` (which calls `yogaNode.removeChild`) always runs before `detachDeletedInstance` (which calls `destroy()`), so the node is already detached from the Yoga tree when `free()` fires. Belt-and-suspenders: check `getParent()` before freeing and remove if still attached.

The prior decision to skip `free()` was a misdiagnosis. The "Child already has a parent" corruption during keyed list reordering was caused by the double-parented insert bug, not by `free()`. Spikes confirmed safety in all configurations: isolated detach, batch subtree deletion (children before parents), and freeing a parent with children still attached. 100k nodes, 0.05 MB heap delta after GC.

## stdout buffering during alternate screen [#stdout-buffering-during-alternate-screen]

`useStdout`/`useStderr` writes are buffered in `TuiApp.stdoutBuffer`/`stderrBuffer` while the alternate screen is active, then flushed after `stop()` restores the normal screen. This prevents TUI corruption. Ink uses a different approach (inline cursor-up rewrite via `log-update`) because it doesn't use an alternate screen.

## Both `setRawMode` calls required [#both-setrawmode-calls-required]

`crossterm::enable_raw_mode()` sets OS terminal flags (affects how the kernel delivers keystrokes). Node's `stdin.setRawMode(true)` is a separate stream-layer switch that tells Node to not buffer or echo input. Both must be called independently — they are not redundant.

## Transform: collect-then-paint approach [#transform-collect-then-paint-approach]

`<Transform>` collects all descendant text via `collectText()`, applies the transform function, then paints the result as a flat string. This matches Ink's `squashTextNodes` semantics. The transform node's children are not recursed into — the transform takes full ownership of its subtree's output.

## `renderToString` uses `updateContainerSync` + `flushSyncWork` [#rendertostring-uses-updatecontainersync--flushsyncwork]

Unlike `render()` which uses async concurrent mode, `renderToString` uses React's synchronous legacy-root APIs. This ensures the output reflects the committed state after a single synchronous render pass, matching what Ink's `renderToString` does.

## Scroll: slice the data, not the DOM [#scroll-slice-the-data-not-the-dom]

`marginTop={-offset}` inside a Yoga flex column shifts the entire column including siblings (e.g., an input bar). Yoga doesn't clip — it literally moves boxes. For scrollable content in a fixed viewport, walk the data array and build a `visibleItems[]` slice (skipping `offset` rows, filling up to `viewportRows`). Render the slice directly with no margin tricks.


# Examples (/docs/packages/tui/examples)



# Examples [#examples]

All examples in this page are part of this repository.

Run from repository root:

```bash
node --import @oxc-node/core/register examples/<name>.tsx
node --import @oxc-node/core/register examples-raw/<name>.ts
```

## React Mode (`examples/`) [#react-mode-examples]

### Basics [#basics]

| File                  | What it demonstrates                                          |
| --------------------- | ------------------------------------------------------------- |
| `counter.tsx`         | `useState` + `useInput` minimal app                           |
| `use-input.tsx`       | Key parsing: arrows, ctrl/meta combos, special keys           |
| `borders.tsx`         | Border styles: `single`, `double`, `round`, `bold`, `classic` |
| `box-slices.tsx`      | All 16 permutations of per-side border toggles                |
| `box-backgrounds.tsx` | Background colors                                             |
| `justify-content.tsx` | Flex alignment and spacing                                    |
| `terminal-resize.tsx` | `useWindowSize` with live resize behavior                     |
| `htop.tsx`            | htop-style system monitor (Unix-like; uses `ps aux`)          |

### Input and Interaction [#input-and-interaction]

| File                            | What it demonstrates                              |
| ------------------------------- | ------------------------------------------------- |
| `cursor-input/cursor-input.tsx` | Declarative `<Cursor />` inline text input        |
| `cursor-ime.tsx`                | `useCursor()` with IME and wide character support |
| `use-focus.tsx`                 | `useFocus` + Tab cycling                          |
| `use-focus-with-id.tsx`         | Named focus targets + `focus(id)`                 |
| `use-mouse.tsx`                 | `useMouse` buttons, wheel, modifiers              |
| `use-paste.tsx`                 | `usePaste` routing vs `useInput` fallback         |
| `use-clipboard.tsx`             | `useClipboard` OSC 52 copy-to-clipboard           |

### Layout and Composition [#layout-and-composition]

| File                 | What it demonstrates                              |
| -------------------- | ------------------------------------------------- |
| `use-scrollable.tsx` | `useScrollable` viewport state + sliced rendering |
| `static.tsx`         | `<Static>` append-only output                     |
| `chat.tsx`           | Chat-style history + live input                   |

### Components [#components]

| File                 | What it demonstrates                                    |
| -------------------- | ------------------------------------------------------- |
| `code.tsx`           | `<Code>` syntax highlighting with line numbers          |
| `markdown.tsx`       | `<Markdown>` full markdown rendering in terminal        |
| `diff-view.tsx`      | `<DiffView>` unified and split diff views               |
| `spinner.tsx`        | `<Spinner>` defaults + custom frames                    |
| `progress-bar.tsx`   | `<ProgressBar>` states and options                      |
| `text-input.tsx`     | `<TextInput>` typing, placeholder, submit               |
| `confirm-input.tsx`  | `<ConfirmInput>` Y/N confirmation prompt                |
| `multi-select.tsx`   | `<MultiSelect>` checkbox selection with keyboard nav    |
| `select-input.tsx`   | `<SelectInput>` single-choice list with separators      |
| `badge.tsx`          | `<Badge>` colored status labels                         |
| `status-message.tsx` | `<StatusMessage>` variant icons (success/error/warning) |
| `alert.tsx`          | `<Alert>` bordered alert boxes with title support       |
| `unordered-list.tsx` | `<UnorderedList>` nested bullet lists                   |
| `ordered-list.tsx`   | `<OrderedList>` nested numbered lists                   |
| `slider.tsx`         | `<Slider>` horizontal/vertical range inputs             |
| `textarea.tsx`       | `<Textarea>` multi-line editor with undo, selection     |
| `tabs.tsx`           | `<Tabs>` tabbed navigation with keyboard switching      |
| `timer.tsx`          | `<Timer>` countdown with start/stop/reset controls      |
| `stopwatch.tsx`      | `<Stopwatch>` with lap capture                          |
| `help.tsx`           | `<Help>` keybinding bar with `useKeyBindings`           |
| `paginator.tsx`      | `<Paginator>` paginated list with dot/numeric styles    |
| `file-picker.tsx`    | `<FilePicker>` file system browser                      |
| `kitchen-sink.tsx`   | Multi-feature demo in one app                           |

### Form controls & disclosure [#form-controls--disclosure]

| File                | What it demonstrates                                                         |
| ------------------- | ---------------------------------------------------------------------------- |
| `form-controls.tsx` | `<Button>`, `<Checkbox>`, `<Switch>`, `<RadioGroup>`, `<Divider>`            |
| `disclosure.tsx`    | `<Accordion>` and `<Collapsible>` with keyboard navigation                   |
| `feedback.tsx`      | `<Stepper>`, `<Toast>` (auto-dismiss), `<Placeholder>` skeleton              |
| `form.tsx`          | `<Form>` + `useForm` + `<MaskedInput>` + `<SearchInput>` + `<ConfirmDialog>` |

### Layout & content [#layout--content]

| File                    | What it demonstrates                                                                         |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `layout-components.tsx` | `<Card>`, `<Heading>`, `<Paragraph>`, `<Kbd>`, `<Tag>`, `<Breadcrumb>`, `<LoadingIndicator>` |
| `definition-list.tsx`   | `<DefinitionList>` inline + stacked layouts                                                  |
| `sparkline.tsx`         | `<Sparkline>` live inline mini-chart                                                         |

### Navigation [#navigation]

| File                  | What it demonstrates                                       |
| --------------------- | ---------------------------------------------------------- |
| `navigation.tsx`      | `<Menu>`, `<Tooltip>`, `<ContentSwitcher>`, `<OptionList>` |
| `command-palette.tsx` | `<CommandPalette>` fuzzy finder with ranked results        |
| `date-picker.tsx`     | `<Calendar>` and `<DatePicker>`                            |

### AI widgets [#ai-widgets]

| File             | What it demonstrates                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ai-widgets.tsx` | `<OperationTree>`, `<MessageBubble>`, `<StreamingText>`, `<ApprovalPrompt>`, `<CommandBlock>`, `<ShimmerText>`, `<ModelBadge>`, `<BlinkDot>`, `<StatusLine>` |

### Animation [#animation]

| File                | What it demonstrates                                                |
| ------------------- | ------------------------------------------------------------------- |
| `use-animation.tsx` | `useAnimation` multi-speed demo: rainbow unicorn, sparkles, spinner |
| `animation.tsx`     | `<Transition>` presets and `<AnimatePresence>` list orchestration   |

### Charts & canvas [#charts--canvas]

| File         | What it demonstrates                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `charts.tsx` | `<BarChart>`, `<LineChart>`, `<AreaChart>`, `<ScatterPlot>`, `<Histogram>`, `<Heatmap>`, `<Gauge>` |
| `canvas.tsx` | Imperative `<Canvas>` drawing API with custom visualizations                                       |

### Hooks [#hooks]

| File                       | What it demonstrates                          |
| -------------------------- | --------------------------------------------- |
| `use-interval.tsx`         | `useInterval` pausable periodic callback      |
| `use-timeout.tsx`          | `useTimeout` one-shot timer with cancel/reset |
| `use-hotkey.tsx`           | `useHotkey` string + descriptor shortcuts     |
| `use-key-chord.tsx`        | `useKeyChord` multi-key sequences (vim-style) |
| `use-persistent-state.tsx` | `usePersistentState` with pluggable storage   |

### Async and React Features [#async-and-react-features]

| File                        | What it demonstrates          |
| --------------------------- | ----------------------------- |
| `suspense.tsx`              | Suspense with async data      |
| `concurrent-suspense.tsx`   | Concurrent rendering behavior |
| `use-transition.tsx`        | `useTransition`               |
| `incremental-rendering.tsx` | Frequent partial updates      |
| `sierpinski.tsx`            | Fiber-heavy animated tree     |

### Internationalization [#internationalization]

| File       | What it demonstrates                                     |
| ---------- | -------------------------------------------------------- |
| `i18n.tsx` | `react-i18next` locale switching, plurals, env detection |

See [i18n](/docs/packages/tui/i18n) for the full guide.

### Inline Mode [#inline-mode]

| File                 | What it demonstrates           |
| -------------------- | ------------------------------ |
| `inline-minimal.tsx` | Minimal `renderInline()` usage |
| `inline-picker.tsx`  | Inline picker UI               |

### Native Renderer Demos [#native-renderer-demos]

| File              | What it demonstrates                        |
| ----------------- | ------------------------------------------- |
| `logo.tsx`        | `onBeforeFlush` direct buffer overlays      |
| `rattata.tsx`     | Streaming fake-assistant demo               |
| `stress-test.tsx` | \~700 FPS sustained full-terminal animation |

## Raw-Buffer Mode (`examples-raw/`) [#raw-buffer-mode-examples-raw]

| File               | What it demonstrates                        |
| ------------------ | ------------------------------------------- |
| `ascii-3d.ts`      | Spinning ASCII-shaded 3D cube with z-buffer |
| `matrix.ts`        | Matrix rain                                 |
| `conway.ts`        | Conway's Game of Life                       |
| `plasma.ts`        | Plasma effect                               |
| `fire.ts`          | Fire effect                                 |
| `jitter.ts`        | Frame-time oscilloscope                     |
| `scope.ts`         | Multi-harmonic oscilloscope                 |
| `inline-picker.ts` | Inline picker without React                 |

All raw examples use `examples-raw/harness.ts`.


# Getting Started (/docs/packages/tui/getting-started)



# Getting Started [#getting-started]

`@visulima/tui` supports three runtime modes.

| Mode            | Primary API                                                    | Import path                                  | Best for                                            |
| --------------- | -------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------- |
| React mode      | `render(<App />)`                                              | `@visulima/tui/react`                        | Component-driven TUIs with hooks and Yoga layout    |
| Raw-buffer mode | `Renderer` + `renderer.render`                                 | `@visulima/tui/core`                         | Direct per-cell rendering and custom loops          |
| Inline mode     | `renderInline` / `createInlineLoop`                            | `@visulima/tui/react` / `@visulima/tui/core` | Fixed-height UI below the cursor                    |
| Testing         | `render` / `cleanup` / `screen` / `keys` / `waitFor` / `flush` | `@visulima/tui/test`                         | Test components with mock streams, no real terminal |

## Install [#install]

### React apps (most users) [#react-apps-most-users]

```bash npm2yarn
npm install @visulima/tui react react-reconciler
```

### Raw-buffer / non-React apps [#raw-buffer--non-react-apps]

```bash npm2yarn
npm install @visulima/tui
```

> `@visulima/tui/core` is a TypeScript-facing runtime with a native Rust diff/render engine. React is an optional peer dependency.

### Component imports [#component-imports]

Every component is published at its own subpath under `@visulima/tui/components/<kebab-name>`. Hooks, `render`, and primitives stay on the bare `@visulima/tui` entry.

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { Spinner } from "@visulima/tui/components/spinner";
import { useApp } from "@visulima/tui/hooks/use-app";
import { useInput } from "@visulima/tui/hooks/use-input";
import { render } from "@visulima/tui";
```

This means you only pull in the components you actually use, and heavy peer dependencies stay tree-shakeable.

> **Breaking from earlier alphas.** Components are no longer re-exported from the bare `@visulima/tui` entry — you must import each one from its own subpath.

### Optional peer dependencies [#optional-peer-dependencies]

A few components have heavy peer dependencies. Install only the peers for the components you actually use:

| Component  | Subpath                              | Required peers                                                                                            |
| ---------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `BigText`  | `@visulima/tui/components/big-text`  | `cfonts`                                                                                                  |
| `Code`     | `@visulima/tui/components/code`      | `shiki`, `@shikijs/langs`, `@shikijs/themes`                                                              |
| `DiffView` | `@visulima/tui/components/diff-view` | `diff` (+ `shiki`, `@shikijs/langs`, `@shikijs/themes` for syntax highlighting)                           |
| `Markdown` | `@visulima/tui/components/markdown`  | `marked` (+ `shiki`, `@shikijs/langs`, `@shikijs/themes` for code blocks; `@visulima/tabular` for tables) |
| `Table`    | `@visulima/tui/components/table`     | `@visulima/tabular`                                                                                       |

To enable the React DevTools overlay (`DEV=true`), install the optional peers `react-devtools-core` and `ws`.

See [Package Map › Heavy component subpaths](/docs/packages/tui/package-map#heavy-component-subpaths) for full installation snippets.

## Requirements [#requirements]

* **Node.js**: 20.19 or higher

## Run examples in this repository [#run-examples-in-this-repository]

```bash
# React mode
node --import @oxc-node/core/register examples/kitchen-sink.tsx
node --import @oxc-node/core/register examples/counter.tsx

# Raw-buffer mode
node --import @oxc-node/core/register examples-raw/matrix.ts
node --import @oxc-node/core/register examples-raw/conway.ts

# Inline mode (React)
node --import @oxc-node/core/register examples/inline-minimal.tsx
```

See [Examples](/docs/packages/tui/examples) for the full list.

## Ink migration (typical) [#ink-migration-typical]

```diff
- import { render, Box, Text } from 'ink'
+ import { render } from '@visulima/tui'
+ import { Box } from '@visulima/tui/components/box'
+ import { Text } from '@visulima/tui/components/text'
```

Most app-level API usage maps directly. See [Ink Compatibility](/docs/packages/tui/ink-compat) for caveats and stubs.

## Next Steps [#next-steps]

<Cards>
  <Card title="Package Map" href="/docs/packages/tui/package-map">
    Choose the right sub-package for your use case
  </Card>

  <Card title="Quickstart: React" href="/docs/packages/tui/quickstart-react">
    Build a TUI app with React components and hooks
  </Card>

  <Card title="Quickstart: Raw Buffer" href="/docs/packages/tui/quickstart-raw-buffer">
    Drive the Rust renderer directly without React
  </Card>

  <Card title="Testing" href="/docs/packages/tui/testing">
    Test components with mock streams and frame capture
  </Card>
</Cards>


# Hooks (/docs/packages/tui/hooks)



# Hooks [#hooks]

Use these hooks inside components rendered with `render()`. Hooks that rely on the full app event emitter are marked as `render()`-mode only.

```tsx
import { useApp, useCursor, useFocus, useFocusManager, useInput, useMouse, usePaste, useScrollable, useTextInput } from "@visulima/tui/react";
```

## `useInput` [#useinput]

Subscribe to typed characters and key events.

Bracketed paste payloads belong to [`usePaste`](#usepaste). If no `usePaste` handler is active, paste text is still forwarded to `useInput` for backward compatibility, but **that fallback is deprecated** and will be removed in the next major version.

```tsx
useInput((input, key) => {
    if (key.upArrow) moveUp();
    if (key.downArrow) moveDown();
    if (key.return) submit();
    if (key.escape) cancel();
    if (key.ctrl && input === "c") exit();
});
```

### `key` Fields [#key-fields]

| Field        | Type      |
| ------------ | --------- |
| `upArrow`    | `boolean` |
| `downArrow`  | `boolean` |
| `leftArrow`  | `boolean` |
| `rightArrow` | `boolean` |
| `return`     | `boolean` |
| `backspace`  | `boolean` |
| `delete`     | `boolean` |
| `pageUp`     | `boolean` |
| `pageDown`   | `boolean` |
| `home`       | `boolean` |
| `end`        | `boolean` |
| `tab`        | `boolean` |
| `shift`      | `boolean` |
| `escape`     | `boolean` |
| `ctrl`       | `boolean` |
| `meta`       | `boolean` |

## `usePaste` [#usepaste]

Subscribe to bracketed paste events.

```tsx
usePaste((text) => {
    handlePaste(text);
});
```

`usePaste` is the dedicated API for paste blobs. When at least one active `usePaste` listener exists, pasted text is routed to `usePaste` and not forwarded to `useInput`. If no paste listener is active, paste still falls back to `useInput`, but **that fallback is deprecated** and will be removed in the next major version.

### Options [#options]

```tsx
usePaste(handler, { isActive: false });
```

| Option     | Type      | Default |
| ---------- | --------- | ------- |
| `isActive` | `boolean` | `true`  |

## `useClipboard` [#useclipboard]

Copy text to the system clipboard via OSC 52 terminal escape sequences. Works in terminals that support OSC 52 (Alacritty, Ghostty, Kitty, WezTerm, iTerm2, xterm, foot, Windows Terminal, etc.).

```tsx
import { useClipboard } from "@visulima/tui/hooks/use-clipboard";
const { copy, isSupported } = useClipboard();
copy("Hello, clipboard!");
```

### Options [#options-1]

```tsx
const { copy } = useClipboard({ target: "p" }); // primary selection (X11)
```

| Option   | Type                | Default | Description                                            |
| -------- | ------------------- | ------- | ------------------------------------------------------ |
| `target` | `"c" \| "p" \| "s"` | `"c"`   | Clipboard target (c=clipboard, p=primary, s=secondary) |

### Return Value [#return-value]

| Field         | Type                     | Description                                  |
| ------------- | ------------------------ | -------------------------------------------- |
| `copy`        | `(text: string) => void` | Copy text; no-op if terminal is unsupported  |
| `isSupported` | `boolean`                | Whether the current terminal supports OSC 52 |

### Low-level utilities [#low-level-utilities]

For use outside React components:

```tsx
import { writeOsc52, clearOsc52, isOsc52Supported } from "@visulima/tui";
if (isOsc52Supported()) {
    writeOsc52(process.stdout, "text to copy", "c");
}
```

## `useTextBuffer` [#usetextbuffer]

Manages a multi-line text buffer with cursor, selection, undo/redo. This is the data model behind the `<Textarea>` component, exposed for custom editor implementations.

```tsx
import { useTextBuffer } from "@visulima/tui/hooks/use-text-buffer";
const buffer = useTextBuffer("initial\ntext");

buffer.insert("hello");
buffer.newline();
buffer.moveCursor("up");
buffer.undo();
```

### Return Value [#return-value-1]

| Field               | Type                                    | Description                         |
| ------------------- | --------------------------------------- | ----------------------------------- |
| `lines`             | `ReadonlyArray<string>`                 | Current lines of text               |
| `cursor`            | `{ line: number, col: number }`         | Current cursor position             |
| `anchor`            | `{ line: number, col: number } \| null` | Selection anchor (null if none)     |
| `value`             | `string`                                | Joined text (lines joined by `\n`)  |
| `insert`            | `(text: string) => void`                | Insert text at cursor               |
| `newline`           | `() => void`                            | Insert a newline                    |
| `deleteBack`        | `() => void`                            | Backspace                           |
| `deleteForward`     | `() => void`                            | Delete key                          |
| `deleteLine`        | `() => void`                            | Delete entire current line          |
| `deleteToLineEnd`   | `() => void`                            | Ctrl+K                              |
| `deleteToLineStart` | `() => void`                            | Ctrl+U                              |
| `deleteWord`        | `() => void`                            | Ctrl+W                              |
| `moveCursor`        | `(dir, selecting?) => void`             | Move cursor (up/down/left/right)    |
| `moveToLineStart`   | `(selecting?) => void`                  | Home                                |
| `moveToLineEnd`     | `(selecting?) => void`                  | End                                 |
| `moveToStart`       | `(selecting?) => void`                  | Start of buffer                     |
| `moveToEnd`         | `(selecting?) => void`                  | End of buffer                       |
| `selectAll`         | `() => void`                            | Select all text                     |
| `clearSelection`    | `() => void`                            | Clear the selection                 |
| `getSelectedText`   | `() => string`                          | Get selected text                   |
| `hasSelection`      | `() => boolean`                         | Whether text is selected            |
| `deleteSelection`   | `() => void`                            | Delete selected text                |
| `replaceSelection`  | `(text: string) => void`                | Replace selection with text         |
| `undo`              | `() => void`                            | Undo last edit                      |
| `redo`              | `() => void`                            | Redo last undo                      |
| `setValue`          | `(value: string) => void`               | Replace entire buffer (clears undo) |

Undo coalesces rapid keystrokes within 300ms into a single entry. The undo stack holds up to 100 snapshots.

## `useTextSelection` [#usetextselection]

Manages text selection on a DOM element using the existing `Selection`/`Range` API, with optional auto-copy to clipboard.

```tsx
import { useTextSelection } from "@visulima/tui/hooks/use-text-selection";
const ref = useRef(null);
const { selectedText, selectAll, clearSelection } = useTextSelection(ref, {
    copyOnSelect: true,
    onSelectionChange: (text) => console.log("Selected:", text),
});

return (
    <Box ref={ref}>
        <Text>Selectable content</Text>
    </Box>
);
```

### Options [#options-2]

| Option              | Type                     | Default | Description                         |
| ------------------- | ------------------------ | ------- | ----------------------------------- |
| `isActive`          | `boolean`                | `true`  | Enable/disable text selection       |
| `copyOnSelect`      | `boolean`                | `false` | Auto-copy to clipboard on selection |
| `onSelectionChange` | `(text: string) => void` | —       | Called when selected text changes   |

### Return Value [#return-value-2]

| Field            | Type         | Description                       |
| ---------------- | ------------ | --------------------------------- |
| `selection`      | `Selection`  | The underlying Selection instance |
| `selectedText`   | `string`     | Currently selected text           |
| `selectAll`      | `() => void` | Select all content in the element |
| `clearSelection` | `() => void` | Clear the current selection       |

## `useColorBlindness` [#usecolorblindness]

Simulate or compensate for color vision deficiency. Returns a `transformColor` function that maps hex colors through a color blindness matrix.

```tsx
import { useColorBlindness } from "@visulima/tui/hooks/use-color-blindness";
const { transformColor } = useColorBlindness({ mode: "deuteranopia" });
<Text color={transformColor("#ff0000")}>This text</Text>;
```

| Option       | Type                                                                                  | Default  |
| ------------ | ------------------------------------------------------------------------------------- | -------- |
| `mode`       | `"protanopia"` \| `"deuteranopia"` \| `"tritanopia"` \| `"achromatopsia"` \| `"none"` | `"none"` |
| `compensate` | `boolean`                                                                             | `false`  |

Simulation mode shows how colors appear to affected users. Compensation mode shifts colors to a distinguishable range. Low-level utilities (`applyColorMatrix`, `COLOR_BLINDNESS_SIMULATION`, `COLOR_BLINDNESS_COMPENSATION`) are also exported for direct use.

## `useConsoleCapture` [#useconsolecapture]

Capture `console.log`/`warn`/`error`/`info`/`debug` output into a React state buffer. Used by the `<ConsoleOverlay>` component.

```tsx
import { useConsoleCapture } from "@visulima/tui/hooks/use-console-capture";
const { entries, clear } = useConsoleCapture({ maxEntries: 100 });
```

| Option       | Type             | Default                                     |
| ------------ | ---------------- | ------------------------------------------- |
| `maxEntries` | `number`         | `200`                                       |
| `filter`     | `ConsoleLevel[]` | `["log", "info", "warn", "error", "debug"]` |
| `isActive`   | `boolean`        | `true`                                      |

Each entry has `id`, `level`, `message`, and `timestamp`.

> **Note:** Only one active `useConsoleCapture` instance should exist at a time. The `<ConsoleOverlay>` component uses this hook internally — do not use both simultaneously unless the hook has `isActive: false`.

## `useScrollAcceleration` [#usescrollacceleration]

macOS-style scroll physics with momentum. Tracks scroll event velocity and applies exponential acceleration when events arrive rapidly.

```tsx
import { useScrollAcceleration } from "@visulima/tui/hooks/use-scroll-acceleration";
const { handleScroll } = useScrollAcceleration({
    onScroll: (delta) => scrollViewRef.current?.scrollBy(delta),
});
```

| Option         | Type                      | Default |
| -------------- | ------------------------- | ------- |
| `acceleration` | `number`                  | `1.5`   |
| `decayRate`    | `number` (0-1)            | `0.92`  |
| `maxVelocity`  | `number`                  | `20`    |
| `isActive`     | `boolean`                 | `true`  |
| `onScroll`     | `(delta: number) => void` | —       |

Returns `handleScroll(direction)`, `velocity`, and `isCoasting`.

## `useScrollInput` [#usescrollinput]

Wire keyboard input to scroll actions. Used internally by `ScrollView`/`ScrollList` when `keyboard` prop is enabled, but also available standalone for custom scroll containers.

```tsx
import { useScrollInput } from "@visulima/tui/hooks/use-scroll-input";
const { isFocused } = useScrollInput({
    scrollBy: (delta) => ref.current?.scrollBy(delta),
    scrollToTop: () => ref.current?.scrollToTop(),
    scrollToBottom: () => ref.current?.scrollToBottom(),
    viewportHeight: 20,
    vimBindings: true,
});
```

| Option           | Type                      | Default  |
| ---------------- | ------------------------- | -------- |
| `scrollBy`       | `(delta: number) => void` | required |
| `scrollToTop`    | `() => void`              | required |
| `scrollToBottom` | `() => void`              | required |
| `viewportHeight` | `number`                  | required |
| `isActive`       | `boolean`                 | `true`   |
| `vimBindings`    | `boolean`                 | `false`  |

Returns `{ isFocused }`.

## `createLinkedScrollGroup` [#createlinkedscrollgroup]

Synchronize scroll position across multiple `ScrollView` instances.

```tsx
import { createLinkedScrollGroup } from "@visulima/tui/hooks/use-linked-scroll";
const group = createLinkedScrollGroup();

// In each linked component:
const { ref, onScroll } = group.useLinkedScroll();
// Attach ref and onScroll to your ScrollView
```

Returns a `LinkedScrollGroup` with a `useLinkedScroll()` hook that provides `{ ref, onScroll }` for each consumer.

## `useTerminalPalette` [#useterminalpalette]

Query the terminal emulator for its current color palette using OSC escape sequences.

```tsx
import { useTerminalPalette } from "@visulima/tui/hooks/use-terminal-palette";
const { palette, isLoading, isSupported } = useTerminalPalette();
if (palette?.background) {
    console.log("Terminal background:", palette.background);
}
```

Returns `palette` (with `foreground`, `background`, `cursor`, and `colors` array of 16 ANSI colors as hex strings), `isLoading`, and `isSupported`. Low-level `queryTerminalPalette()` and `isTerminalPaletteQuerySupported()` are also exported.

## `useMouse` (native renderer only) [#usemouse-native-renderer-only]

Low-level callback hook for mouse events. Subscribe to every mouse event with full modifier info.

```tsx
useMouse((event) => {
    // event.button: left | right | middle | scrollUp | scrollDown
    // event.x, event.y are 0-based terminal coordinates
    if (event.button === "left") onClick(event.x, event.y);
});
```

### Event Shape [#event-shape]

| Field    | Type      | Notes                                 |
| -------- | --------- | ------------------------------------- |
| `x`      | `number`  | 0-based column                        |
| `y`      | `number`  | 0-based row                           |
| `button` | `string`  | left/right/middle/scrollUp/scrollDown |
| `shift`  | `boolean` | modifier                              |
| `ctrl`   | `boolean` | modifier                              |
| `meta`   | `boolean` | modifier                              |

> For higher-level mouse hooks with element hover/click detection, see [Mouse Support](/docs/packages/tui/mouse) (Ink layer, imported from `@visulima/tui`).

## `useTextInput` (native renderer only) [#usetextinput-native-renderer-only]

Managed text input with cursor and editing shortcuts.

```tsx
const { value, cursor, clear } = useTextInput({
    onSubmit: (v) => send(v),
});

return (
    <Text>
        {value.slice(0, cursor)}
        <Text inverse>{value[cursor] ?? " "}</Text>
        {value.slice(cursor + 1)}
    </Text>
);
```

### Options [#options-3]

| Option         | Type                  | Default |
| -------------- | --------------------- | ------- |
| `initialValue` | `string`              | `''`    |
| `onSubmit`     | `(v: string) => void` | —       |
| `onChange`     | `(v: string) => void` | —       |
| `isActive`     | `boolean`             | `true`  |

### Return Value [#return-value-3]

| Field      | Type                  |
| ---------- | --------------------- |
| `value`    | `string`              |
| `cursor`   | `number`              |
| `setValue` | `(v: string) => void` |
| `clear`    | `() => void`          |

Supported editing keys: arrows, Home/End, Backspace/Delete, Ctrl+A/E/U/K/W, Enter, paste.

## `useScrollable` (native renderer only) [#usescrollable-native-renderer-only]

Virtual scrolling state for fixed-height viewports.

```tsx
const viewportHeight = 20;
const scroll = useScrollable({
    viewportHeight,
    contentHeight: items.length,
});

useInput((_input, key) => {
    if (key.upArrow) scroll.scrollUp();
    if (key.downArrow) scroll.scrollDown();
    if (key.pageUp) scroll.scrollBy(-10);
    if (key.pageDown) scroll.scrollBy(10);
    if (key.home) scroll.scrollToTop();
    if (key.end) scroll.scrollToBottom();
});

const visible = items.slice(scroll.offset, scroll.offset + viewportHeight);
```

### Return Value [#return-value-4]

`offset`, `scrollUp`, `scrollDown`, `scrollBy`, `scrollToTop`, `scrollToBottom`, `atTop`, `atBottom`.

## `useFocus` [#usefocus]

Register a focusable component.

```tsx
const { isFocused, focus } = useFocus({ id: "search", autoFocus: true });
```

Tab/Shift+Tab focus cycling is wired automatically by `render()`.

## `useFocusManager` [#usefocusmanager]

Programmatic focus control.

```tsx
const { focusNext, focusPrevious, focus, activeId, enableFocus, disableFocus } = useFocusManager();
```

## `useApp` [#useapp]

Lifecycle controls.

```tsx
const { exit, quit } = useApp();
```

`exit()` and `quit()` are equivalent.

## `useWindowSize` [#usewindowsize]

Returns `{ columns, rows }` and updates on terminal resize.

```tsx
const { columns, rows } = useWindowSize();
```

> This hook relies on the full app event emitter and is intended for `render()` mode.

## `useStdout` / `useStderr` [#usestdout--usestderr]

Write outside the rendered frame.

```tsx
const { write } = useStdout();
const { write: writeErr } = useStderr();

write("log line\n");
writeErr("warning\n");
```

## `useStdin` [#usestdin]

Access stdin and raw mode controls.

```tsx
const { stdin, setRawMode, isRawModeSupported } = useStdin();
```

## `useBoxMetrics` [#useboxmetrics]

Read computed layout metrics from a `Box` ref.

```tsx
const ref = useRef(null);
const { width, height, left, top, hasMeasured } = useBoxMetrics(ref);

return <Box ref={ref}>...</Box>;
```

Returns zeroed metrics until first layout pass.

> This hook relies on the full app event emitter and is intended for `render()` mode.

## `measureElement` [#measureelement]

Imperative element measurement. Returns position and dimensions.

```tsx
const { x, y, width, height } = measureElement(ref.current);
```

Additional measurement utilities are available for advanced use cases:

```tsx
import { getBoundingBox } from "@visulima/tui";
// ResizeObserver example
const observer = new ResizeObserver((entries) => {
    for (const entry of entries) {
        console.log(`Size changed: ${entry.contentRect.width}x${entry.contentRect.height}`);
    }
});
observer.observe(ref.current);
```

## `useCursor` [#usecursor]

Imperative cursor positioning. Use this when you need precise control over cursor placement, for example with IME (Input Method Editor) support where you need to account for wide characters.

```tsx
const { setCursorPosition } = useCursor();

const prompt = "> ";
setCursorPosition({ x: stringWidth(prompt + text), y: 1 });

return (
    <Box flexDirection="column">
        <Text>Header</Text>
        <Text>
            {prompt}
            {text}
        </Text>
    </Box>
);
```

### `setCursorPosition` [#setcursorposition]

| Argument   | Type                                      | Description                               |
| ---------- | ----------------------------------------- | ----------------------------------------- |
| `position` | `{ x: number, y: number }` or `undefined` | Absolute position, or `undefined` to hide |

Notes:

* `x` and `y` are 0-based coordinates relative to the top-left of the rendered output.
* Use `stringWidth()` from `@visulima/string` for correct column calculation with wide characters.
* The cursor is automatically hidden when the component using `useCursor` unmounts.
* For most text input use cases, prefer the declarative [`<Cursor />`](/docs/packages/tui/components#cursor) component instead.

## `useAnimation` [#useanimation]

Drive frame-based or time-based animations. Returns a frame counter, elapsed time, frame delta, and a reset function. All animations share a single timer internally, so multiple `useAnimation` calls consolidate into one render cycle instead of spawning independent timers.

```tsx
import { Text } from "@visulima/tui/components/text";
import { useAnimation } from "@visulima/tui/hooks/use-animation";
const Spinner = () => {
    const { frame } = useAnimation({ interval: 80 });
    const characters = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

    return <Text>{characters[frame % characters.length]}</Text>;
};
```

### Options [#options-4]

| Option     | Type      | Default | Description                                                                                                                 |
| ---------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `interval` | `number`  | `100`   | Time between ticks in milliseconds.                                                                                         |
| `isActive` | `boolean` | `true`  | Whether the animation is running. When set to `false`, the animation stops. When toggled back to `true`, values reset to 0. |

### Return Value [#return-value-5]

| Field   | Type         | Description                                                                                                                            |
| ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `frame` | `number`     | Discrete counter that increments by 1 each interval. Useful for indexed sequences like spinner frames.                                 |
| `time`  | `number`     | Total elapsed milliseconds since the animation started or was last reset. Useful for continuous math-based animations like sine waves. |
| `delta` | `number`     | Milliseconds since the previous rendered tick. Accounts for throttled renders. Useful for physics-based or velocity-driven motion.     |
| `reset` | `() => void` | Resets `frame`, `time`, and `delta` to 0 and restarts timing from the current moment.                                                  |

### Examples [#examples]

#### Continuous sine-wave animation using `time` [#continuous-sine-wave-animation-using-time]

```tsx
const Pulse = () => {
    const { time } = useAnimation({ interval: 50 });
    const brightness = Math.sin((time / 1000) * Math.PI * 2);
    const width = Math.round((brightness + 1) * 10);

    return <Text color="cyan">{"█".repeat(width)}</Text>;
};
```

#### Pausable animation using `isActive` [#pausable-animation-using-isactive]

```tsx
import { useState } from "react";
import { Text } from "@visulima/tui/components/text";
import { useAnimation } from "@visulima/tui/hooks/use-animation";
import { useInput } from "@visulima/tui/hooks/use-input";
const PausableCounter = () => {
    const [paused, setPaused] = useState(false);
    const { frame } = useAnimation({ interval: 100, isActive: !paused });

    useInput((input) => {
        if (input === " ") setPaused((prev) => !prev);
    });

    return (
        <Text>
            Frame: {frame} {paused ? "(paused)" : ""}
        </Text>
    );
};
```

#### Resettable one-shot animation using `reset` [#resettable-one-shot-animation-using-reset]

```tsx
import { Text } from "@visulima/tui/components/text";
import { useAnimation } from "@visulima/tui/hooks/use-animation";
import { useInput } from "@visulima/tui/hooks/use-input";
const Flash = () => {
    const { frame, reset } = useAnimation({ interval: 100 });

    useInput((input) => {
        if (input === "r") reset();
    });

    return <Text>{frame < 10 ? "Flash!" : "Press r to flash again"}</Text>;
};
```

#### Physics-based motion using `delta` [#physics-based-motion-using-delta]

```tsx
import { useRef } from "react";
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { useAnimation } from "@visulima/tui/hooks/use-animation";
const BouncingDot = () => {
    const posRef = useRef(0);
    const velRef = useRef(0.05);
    const { delta } = useAnimation({ interval: 16 });

    posRef.current += velRef.current * delta;

    if (posRef.current > 40 || posRef.current < 0) {
        velRef.current *= -1;
        posRef.current = Math.max(0, Math.min(40, posRef.current));
    }

    return <Text>{" ".repeat(Math.round(posRef.current))}●</Text>;
};
```

#### Multiple animations at different speeds [#multiple-animations-at-different-speeds]

Multiple calls share one internal timer. The scheduler wakes at the earliest deadline and lets slower animations skip that tick.

```tsx
const Dashboard = () => {
    const { frame: fast } = useAnimation({ interval: 80 });
    const { frame: slow } = useAnimation({ interval: 500 });

    const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
    const dots = [".  ", ".. ", "..."];

    return (
        <Box flexDirection="column">
            <Text>
                {spinner[fast % spinner.length]} Loading
                {dots[slow % dots.length]}
            </Text>
        </Box>
    );
};
```

### Interaction with `maxFps` [#interaction-with-maxfps]

The `maxFps` option on `render()` controls how often Ink flushes frames to the terminal. `useAnimation` respects this throttle — when `maxFps` is low (e.g., `maxFps: 5`), animation callbacks are coalesced and the `delta` value reflects the actual time between rendered frames, not the interval. The `frame` and `time` values are always computed from elapsed wall-clock time, so they remain accurate regardless of throttling.

## `useTimer` [#usetimer]

A countdown timer hook built on `useAnimation`. Returns the remaining time and control methods.

```tsx
import { useTimer } from "@visulima/tui/hooks/use-timer";
const { remaining, isRunning, isFinished, start, stop, toggle, reset } = useTimer({
    duration: 60_000,
    interval: 1000,
    onTimeout: () => console.log("Time's up!"),
});
```

### Options [#options-5]

| Option      | Type         | Default      | Description                        |
| ----------- | ------------ | ------------ | ---------------------------------- |
| `duration`  | `number`     | *(required)* | Countdown duration in milliseconds |
| `interval`  | `number`     | `1000`       | Tick frequency in milliseconds     |
| `autoStart` | `boolean`    | `false`      | Start counting immediately         |
| `onTimeout` | `() => void` | —            | Called once when time reaches zero |

### Return Value [#return-value-6]

| Field        | Type         | Description                              |
| ------------ | ------------ | ---------------------------------------- |
| `remaining`  | `number`     | Milliseconds remaining (clamped to >= 0) |
| `isRunning`  | `boolean`    | Whether the timer is counting down       |
| `isFinished` | `boolean`    | Whether the countdown has reached zero   |
| `start`      | `() => void` | Start the countdown                      |
| `stop`       | `() => void` | Pause the countdown                      |
| `toggle`     | `() => void` | Toggle between running and stopped       |
| `reset`      | `() => void` | Reset to original duration and stop      |

For a visual component, see [`<Timer>`](/docs/packages/tui/components#timer).

## `useStopwatch` [#usestopwatch]

A count-up stopwatch hook built on `useAnimation`. Returns elapsed time, control methods, and lap functionality.

```tsx
import { useStopwatch } from "@visulima/tui/hooks/use-stopwatch";
const { elapsed, isRunning, start, stop, toggle, reset, lap, laps } = useStopwatch({
    interval: 100,
    autoStart: true,
});
```

### Options [#options-6]

| Option      | Type      | Default | Description                    |
| ----------- | --------- | ------- | ------------------------------ |
| `interval`  | `number`  | `1000`  | Tick frequency in milliseconds |
| `autoStart` | `boolean` | `false` | Start counting immediately     |

### Return Value [#return-value-7]

| Field       | Type           | Description                              |
| ----------- | -------------- | ---------------------------------------- |
| `elapsed`   | `number`       | Milliseconds elapsed since start/reset   |
| `isRunning` | `boolean`      | Whether the stopwatch is running         |
| `start`     | `() => void`   | Start counting                           |
| `stop`      | `() => void`   | Pause counting                           |
| `toggle`    | `() => void`   | Toggle between running and stopped       |
| `reset`     | `() => void`   | Reset to zero, clear laps, and stop      |
| `lap`       | `() => number` | Capture current elapsed time; returns it |
| `laps`      | `number[]`     | Accumulated lap times                    |

For a visual component, see [`<Stopwatch>`](/docs/packages/tui/components#stopwatch).

## `useKeyBindings` [#usekeybindings]

Declarative keybinding hook. Registers multiple key bindings with handlers and returns the enabled bindings for display in a [`<Help>`](/docs/packages/tui/components#help) component.

```tsx
import { Help } from "@visulima/tui/components/help";
import { useKeyBindings } from "@visulima/tui/hooks/use-key-bindings";
const { bindings } = useKeyBindings([
    { binding: { key: "q", description: "Quit" }, handler: () => exit() },
    { binding: { key: ["upArrow", "k"], description: "Move up", group: "Navigation" }, handler: () => moveUp() },
    { binding: { key: "ctrl+s", description: "Save" }, handler: () => save() },
    { binding: { key: "escape", description: "Cancel", enabled: false }, handler: () => cancel() },
]);

<Help bindings={bindings} />;
```

### Key Binding Format [#key-binding-format]

The `key` field supports:

* **Single character**: `"q"`, `"a"`, `" "` (space)
* **Special key name**: `"return"`, `"escape"`, `"upArrow"`, `"leftArrow"`, `"backspace"`, `"tab"`, `"pageUp"`, `"pageDown"`, `"home"`, `"end"`, `"delete"`
* **Modifier combo**: `"ctrl+c"`, `"meta+s"`, `"shift+tab"` (modifier + key)
* **Array**: `["upArrow", "k"]` — matches any of the listed keys

### KeyBinding type [#keybinding-type]

```ts
type KeyBinding = {
    key: string | readonly string[];
    description: string;
    enabled?: boolean; // default: true
    group?: string; // for Help grouping
};
```

### Options [#options-7]

| Option     | Type      | Default | Description               |
| ---------- | --------- | ------- | ------------------------- |
| `isActive` | `boolean` | `true`  | Whether input is captured |

### Return Value [#return-value-8]

| Field      | Type           | Description                               |
| ---------- | -------------- | ----------------------------------------- |
| `bindings` | `KeyBinding[]` | Enabled bindings, for passing to `<Help>` |

Disabled bindings (`enabled: false`) are excluded from both the returned array and keyboard matching.

## `useIsScreenReaderEnabled` [#useisscreenreaderenabled]

Returns whether screen reader mode is active. When enabled, components render `aria-label` text instead of visual content.

```tsx
const isEnabled = useIsScreenReaderEnabled();
```

Screen reader mode is enabled by either:

* Passing `isScreenReaderEnabled: true` to `render()`
* Setting the `INK_SCREEN_READER=true` environment variable

Defaults to `false`. This matches upstream Ink behavior — there is no automatic detection of screen readers.

## `useTreeViewState` [#usetreeviewstate]

State management hook for the `<TreeView>` component. Use this for headless tree view implementations where you want full control over rendering.

```tsx
import { useTreeViewState } from "@visulima/tui/components/tree-view";
const state = useTreeViewState({
    data: treeNodes,
    selectionMode: "single",
    defaultExpanded: "all",
    visibleNodeCount: 20,
    onFocusChange: (id) => console.log("focused:", id),
    onExpandChange: (ids) => console.log("expanded:", ids),
    onSelectChange: (ids) => console.log("selected:", ids),
});
```

Returns a `TreeViewState<T>` object with:

* **Read-only state:** `focusedId`, `expandedIds`, `selectedIds`, `viewportNodes`, `visibleCount`, `hasScrollUp`, `hasScrollDown`, `loadingIds`, `nodeMap`
* **Actions:** `focusNext()`, `focusPrevious()`, `focusFirst()`, `focusLast()`, `expand()`, `collapse()`, `expandNode(id)`, `collapseNode(id)`, `toggleExpanded()`, `expandAll()`, `collapseAll()`, `select()`, `focusParent()`, `focusFirstChild()`, `setLoading(id, bool)`, `insertChildren(parentId, children)`

## `useTreeView` [#usetreeview]

Keyboard input hook for the tree view. Binds arrow keys, Enter, Space, Home, and End to the tree view state actions. Use alongside `useTreeViewState` for headless implementations.

```tsx
import { useTreeView, useTreeViewState } from "@visulima/tui/components/tree-view";
const state = useTreeViewState({ data, selectionMode: "none" });

useTreeView({
    state,
    selectionMode: "none",
    isDisabled: false,
    loadChildren: async (node) => fetchChildren(node.id),
    onLoadError: (nodeId, err) => console.error(err),
});
```

| Prop            | Type                                            | Default  | Description                      |
| --------------- | ----------------------------------------------- | -------- | -------------------------------- |
| `state`         | `TreeViewState<T>`                              | required | State from `useTreeViewState`    |
| `selectionMode` | `"none"` \| `"single"` \| `"multiple"`          | required | Determines Enter/Space behavior  |
| `isDisabled`    | `boolean`                                       | `false`  | Ignores all keyboard input       |
| `loadChildren`  | `(node: TreeNode<T>) => Promise<TreeNode<T>[]>` | —        | Async child loader               |
| `onLoadError`   | `(nodeId: string, error: Error) => void`        | —        | Error callback for async loading |

## `useForm` [#useform]

Headless form state machine. Tracks values, touched state, errors, and submission in-flight. Pair with `<Form>` and `<Form.Field>` for default layout, or wire your own inputs.

```tsx
import { useForm } from "@visulima/tui/hooks/use-form";
const { values, errors, touched, setValue, setTouched, submit, isSubmitting, reset } = useForm({
    fields: {
        email: {
            initialValue: "",
            validate: (v) => (v.includes("@") ? undefined : "Invalid email"),
        },
        name: { initialValue: "" },
    },
    onSubmit: async (vs) => {
        await api.create(vs);
    },
});
```

### Options [#options-8]

| Option     | Type                                | Description                                        |
| ---------- | ----------------------------------- | -------------------------------------------------- |
| `fields`   | `Record<string, FieldConfig<V>>`    | Field declarations (`{ initialValue, validate? }`) |
| `onSubmit` | `(values) => void \| Promise<void>` | Called by `submit()` when all fields validate      |

### Return Value [#return-value-9]

| Field          | Type                                | Description                                                             |
| -------------- | ----------------------------------- | ----------------------------------------------------------------------- |
| `values`       | `FormValues<S>`                     | Current values                                                          |
| `errors`       | `Partial<Record<keyof S, string>>`  | Validation errors (per field)                                           |
| `touched`      | `Partial<Record<keyof S, boolean>>` | Per-field touched flag                                                  |
| `isSubmitting` | `boolean`                           | True while the last `submit()` is in-flight                             |
| `setValue`     | `(name, value) => void`             | Update a single field (validates the field)                             |
| `setTouched`   | `(name, touched?) => void`          | Mark a field as touched                                                 |
| `submit`       | `() => Promise<boolean>`            | Validate all, mark touched, call `onSubmit`. Returns `true` on success. |
| `reset`        | `() => void`                        | Reset to initial values; clear errors and touched                       |

`submit()` returns `false` (and skips `onSubmit`) when any field is invalid.

## `useHotkey` [#usehotkey]

Bind a single keyboard shortcut to a callback. Accepts either a short string (`"ctrl+s"`, `"shift+tab"`, `"?"`, `"escape"`) or a structured `HotkeyDescriptor`.

```tsx
import { useHotkey } from "@visulima/tui/hooks/use-hotkey";
useHotkey("ctrl+s", () => save());
useHotkey("?", () => setShowHelp(true));
useHotkey({ ctrl: true, input: "k" }, () => openPalette());
```

### Shortcut string syntax [#shortcut-string-syntax]

`+`-separated tokens. Modifiers: `ctrl`/`control`, `shift`, `meta`/`cmd`/`alt`. Named keys: `escape`/`esc`, `enter`/`return`, `tab`, `up`/`down`/`left`/`right` (or `upArrow`/...), `home`/`end`, `pageUp`/`pageDown`, `backspace`/`delete`. Anything else is matched against the typed character.

### Options [#options-9]

| Option     | Type      | Default | Description                                              |
| ---------- | --------- | ------- | -------------------------------------------------------- |
| `isActive` | `boolean` | `true`  | Disable the binding while keeping the component rendered |

For multiple bindings with help-bar integration, use [`useKeyBindings`](#usekeybindings) + `<Help>` instead.

## `useInterval` [#useinterval]

Invoke `callback` every `interval` ms. The callback ref is captured, so re-renders do not rebuild the timer; only `interval` and `isActive` do.

```tsx
import { useInterval } from "@visulima/tui/hooks/use-interval";
const { clear } = useInterval(() => poll(), 5_000);
useInterval(() => tick(), 1_000, { isActive: !paused });
```

### Options [#options-10]

| Option     | Type      | Default | Description                                                 |
| ---------- | --------- | ------- | ----------------------------------------------------------- |
| `isActive` | `boolean` | `true`  | When `false` the timer is paused; flipping back restarts it |

Returns `{ clear }` for manual cancellation. Invalid intervals (`0`, `NaN`, `Infinity`) pause the timer.

## `usePersistentState` [#usepersistentstate]

`useState` that persists its value through a configurable storage backend (file on disk by default).

```tsx
import { usePersistentState } from "@visulima/tui/hooks/use-persistent-state";
const [theme, setTheme] = usePersistentState("theme", "dark");
const [recent, setRecent] = usePersistentState<string[]>("recent", [], { namespace: "vis" });
```

### Options [#options-11]

| Option      | Type                | Default                        | Description                                    |
| ----------- | ------------------- | ------------------------------ | ---------------------------------------------- |
| `namespace` | `string`            | `"tui"`                        | Used by the default file storage to scope keys |
| `storage`   | `PersistentStorage` | `createFileStorage(namespace)` | Custom storage backend                         |

The backend is captured once on mount; mutating `options.storage` later has no effect. Remount the hook (e.g. via a `key` prop) to swap backends.

### Storage backends [#storage-backends]

```tsx
import { createFileStorage, createMemoryStorage, usePersistentState } from "@visulima/tui/hooks/use-persistent-state";
// File storage — JSON file at ~/.cache/visulima-tui/<namespace>.json,
// written via temp-file + rename so partial writes can't corrupt the file.
const fileStorage = createFileStorage("vis");

// In-memory storage — useful in tests or read-only environments.
const memoryStorage = createMemoryStorage();

const [value, setValue] = usePersistentState("layout", "single", { storage: memoryStorage });
```

A custom backend just needs to implement `{ read(key): string | undefined, write(key, value): void }`. Values are JSON-encoded by the hook before they reach `write`. Errors thrown by the backend are swallowed by the hook so the UI keeps working in read-only environments.


# Internationalization (i18n) (/docs/packages/tui/i18n)



# Internationalization (i18n) [#internationalization-i18n]

`@visulima/tui` does **not** ship a built-in i18n system. Instead, use any framework-agnostic React i18n library — they work unchanged because the TUI renderer is just a React reconciler.

This page covers the recommended library, how to wire it up, and terminal-specific gotchas.

## Why not built-in? [#why-not-built-in]

The React i18n ecosystem is mature and none of the mainstream libraries rely on DOM APIs. Reimplementing plurals, ICU formatting, and locale loading inside the TUI would duplicate work without adding value. Picking one off-the-shelf keeps the TUI focused on rendering.

## Recommendation: `react-i18next` [#recommendation-react-i18next]

[`react-i18next`](https://react.i18next.com/) + [`i18next`](https://www.i18next.com/) is the safest default:

* **Zero DOM assumptions.** The core uses React context + `use-sync-external-store`; no `document`, `window`, `localStorage`, or `fetch`.
* **Largest plugin ecosystem.** File-system backends, HTTP backends, ICU post-processors, backend adapters.
* **First-class Node support.** The library is explicitly designed to run on the server.

### Installation [#installation]

```bash
pnpm add i18next react-i18next
# Optional: load JSON locales from disk at startup
pnpm add i18next-fs-backend
```

### Minimal setup [#minimal-setup]

Initialize `i18next` **before your first render** so `I18nextProvider` receives a ready instance:

```tsx
// i18n.ts
import i18next from "i18next";
import { initReactI18next } from "react-i18next";

await i18next.use(initReactI18next).init({
    fallbackLng: "en",
    // Detect from the user's shell env — see "Locale detection" below.
    lng: resolveLocale(),
    interpolation: {
        // Safe: React renders strings directly, no HTML escaping needed.
        escapeValue: false,
    },
    resources: {
        en: {
            translation: {
                greeting: "Hello, {{name}}!",
                items_one: "{{count}} item",
                items_other: "{{count}} items",
            },
        },
        fr: {
            translation: {
                greeting: "Bonjour, {{name}} !",
                items_one: "{{count}} élément",
                items_other: "{{count}} éléments",
            },
        },
    },
});

export default i18next;

function resolveLocale(): string {
    const raw = process.env["LC_ALL"] ?? process.env["LANG"] ?? "en";

    // "en_US.UTF-8" → "en"
    return raw.split(/[._]/)[0] ?? "en";
}
```

### Using translations in components [#using-translations-in-components]

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { render } from "@visulima/tui/react";
import { I18nextProvider, useTranslation } from "react-i18next";
import React from "react";

import i18n from "./i18n";

function Greeting() {
    const { t } = useTranslation();

    return (
        <Box flexDirection="column">
            <Text>{t("greeting", { name: "World" })}</Text>
            <Text dimColor>{t("items", { count: 3 })}</Text>
        </Box>
    );
}

render(
    <I18nextProvider i18n={i18n}>
        <Greeting />
    </I18nextProvider>,
);
```

### Locale detection [#locale-detection]

**Do not use [`i18next-browser-languagedetector`](https://github.com/i18next/i18next-browser-languageDetector)** — it relies on `localStorage`, cookies, and `navigator.language`, all of which are missing in Node.

Detect from environment variables instead:

```ts
const resolveLocale = (): string => {
    const raw = process.env["LC_ALL"] ?? process.env["LC_MESSAGES"] ?? process.env["LANG"] ?? "en";

    // Normalize "en_US.UTF-8" → "en-US", then return just the base ("en").
    const locale = raw.split(".")[0]!.replace("_", "-");

    return locale.split("-")[0]!;
};
```

### Loading locales from disk [#loading-locales-from-disk]

For larger apps, keep translations in JSON and load them via `i18next-fs-backend`:

```ts
import Backend from "i18next-fs-backend";
import { fileURLToPath } from "node:url";
import path from "node:path";
import i18next from "i18next";
import { initReactI18next } from "react-i18next";

const here = path.dirname(fileURLToPath(import.meta.url));

await i18next
    .use(Backend)
    .use(initReactI18next)
    .init({
        backend: {
            loadPath: path.join(here, "locales/{{lng}}/{{ns}}.json"),
        },
        fallbackLng: "en",
        ns: ["common", "errors"],
        defaultNS: "common",
    });
```

Expected layout:

```
locales/
  en/
    common.json
    errors.json
  fr/
    common.json
    errors.json
```

### Pluralization [#pluralization]

`i18next` uses [CLDR plural rules](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html). Suffix keys with the plural form:

```json
{
    "items_one": "{{count}} item",
    "items_other": "{{count}} items",
    "minutes_zero": "now",
    "minutes_one": "{{count}} minute ago",
    "minutes_other": "{{count}} minutes ago"
}
```

```tsx
t("items", { count: 0 }); // "0 items"
t("items", { count: 1 }); // "1 item"
t("items", { count: 42 }); // "42 items"
```

Polish, Arabic, Russian, and others use more plural forms — i18next picks the correct one automatically.

## Terminal-specific gotchas [#terminal-specific-gotchas]

### 1. Right-to-left (RTL) text [#1-right-to-left-rtl-text]

Real bidirectional rendering is **not supported by most terminals** — they render text left-to-right regardless of Unicode bidi markers. Two pragmatic options:

* **Accept LTR visual order** for RTL locales like Arabic / Hebrew: many Arabic users are accustomed to terminal output reading left-to-right character by character. Most CLIs ship as-is.
* **Mirror your layout manually** for specific screens where it matters. Swap `justifyContent="flex-start"` ↔ `"flex-end"`, reverse `Box` children, and move side panels.

```tsx
import { useTranslation } from "react-i18next";

const RTL_LANGS = new Set(["ar", "he", "fa", "ur"]);

function useDirection() {
    const { i18n } = useTranslation();

    return RTL_LANGS.has(i18n.language.split("-")[0] ?? "") ? "rtl" : "ltr";
}
```

### 2. East-Asian character widths (CJK) [#2-east-asian-character-widths-cjk]

CJK characters occupy **two columns** each. `@visulima/tui`'s text measurement already accounts for this via `inkCharacterWidth`, so layout is correct out of the box — no action needed. Just make sure hard-coded column widths in your UI account for it (e.g. avoid `width={10}` for a field that might hold Japanese text).

### 3. Numeric and date formatting [#3-numeric-and-date-formatting]

`react-i18next` delegates `{{value, number}}` / `{{value, datetime}}` to [`Intl` APIs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). Node 16+ ships full-ICU by default on most distros; earlier Node versions ship `small-icu` (English only). Install the [`full-icu`](https://www.npmjs.com/package/full-icu) npm package or set `NODE_ICU_DATA` if you need non-English locale data.

### 4. Emoji and variable-width glyphs in messages [#4-emoji-and-variable-width-glyphs-in-messages]

Some localized strings include emoji or other wide characters that change a line's visual width. Keep layout slack (don't cap widths at the exact length of English strings) so translated text doesn't get truncated.

## Alternatives [#alternatives]

| Library                                                    | When to reach for it                                                                                                                                                                                           |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[`react-intl`](https://formatjs.github.io/) (FormatJS)** | You want [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) strictly; you already use FormatJS tooling. Pure-JS, works in Node. Requires full-ICU in older Node versions. |
| **[`@lingui/react`](https://lingui.dev/)**                 | You want compile-time message catalogs, smaller runtime. Uses `"use client"` directives harmless in Node/TUI contexts.                                                                                         |

Both integrate the same way: wrap your app in their provider and use their hook in components.

## Complete example [#complete-example]

See [`examples/i18n.tsx`](https://github.com/visulima/visulima/blob/main/packages/terminal/tui/examples/i18n.tsx) for a runnable demo with locale switching, pluralization, and env-based detection.

## Further reading [#further-reading]

* [i18next documentation](https://www.i18next.com/)
* [react-i18next documentation](https://react.i18next.com/)
* [CLDR plural rules chart](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html)


# Introduction (/docs/packages/tui)



# @visulima/tui [#visulimatui]

**React-based terminal UI library powered by a native Rust diff engine.**

`@visulima/tui` provides a component-driven TUI framework with an Ink-compatible API, a high-performance Rust diff renderer, and first-class support for React hooks, Yoga layout, mouse events, scrolling, and raw-buffer rendering.

## Key Features [#key-features]

* **Ink-compatible API** — Drop-in replacement for most Ink component and hook usage
* **Rust diff engine** — Native NAPI binding emits only changed terminal cells as ANSI
* **Three rendering modes** — React, raw-buffer, and inline mode
* **Full hook set** — Input, paste, mouse, focus, scrollable, text input, window size
* **Native renderer extras** — `useMouse`, `useScrollable`, `useTextInput`, `DevTools`, `renderInline`
* **TypeScript first** — Full type safety with exported types
* **Testing utilities** — Framework-agnostic `render()` + mock streams via `@visulima/tui/test`

## Quick Start [#quick-start]

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { render, useInput } from "@visulima/tui/react";
import React, { useState } from "react";

function Counter() {
    const [count, setCount] = useState(0);

    useInput((_input, key) => {
        if (key.upArrow) setCount((c) => c + 1);
        if (key.downArrow) setCount((c) => c - 1);
    });

    return (
        <Box flexDirection="column" padding={1}>
            <Text bold color="cyan">
                Counter
            </Text>
            <Text>Count: {count}</Text>
            <Text dim>↑↓ to change · Ctrl+C to exit</Text>
        </Box>
    );
}

render(<Counter />);
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Getting Started" href="/docs/packages/tui/getting-started">
    Installation, requirements, and mode selection
  </Card>

  <Card title="Quickstart: React" href="/docs/packages/tui/quickstart-react">
    Build your first TUI app with React components
  </Card>

  <Card title="Quickstart: Raw Buffer" href="/docs/packages/tui/quickstart-raw-buffer">
    Drive the Rust renderer directly without React
  </Card>

  <Card title="Components" href="/docs/packages/tui/components">
    Box, Text, Static, Spinner, ProgressBar, and more
  </Card>

  <Card title="Hooks" href="/docs/packages/tui/hooks">
    Input, mouse, focus, scrollable, and other hooks
  </Card>

  <Card title="Testing" href="/docs/packages/tui/testing">
    Test components with mock streams and frame capture
  </Card>

  <Card title="API Reference" href="/docs/packages/tui/ink-compat">
    Ink compatibility matrix and native-only exports
  </Card>
</Cards>


# Ink Compatibility (/docs/packages/tui/ink-compat)



# Ink Compatibility [#ink-compatibility]

`@visulima/tui` targets Ink API compatibility for core component and hook workflows, with a few documented stubs and behavior differences.

## Core API Parity [#core-api-parity]

| Export                       | Status | Notes                                                         |
| ---------------------------- | ------ | ------------------------------------------------------------- |
| `render()`                   | ✅      | Returns `{ rerender, unmount, waitUntilExit, app, input }`    |
| `Box`                        | ✅      | Yoga-backed layout                                            |
| `Text`                       | ✅      | Core style props supported                                    |
| `Newline`                    | ✅      | `count` supported                                             |
| `Spacer`                     | ✅      | Flex grow spacer                                              |
| `Static`                     | ✅      | Append-only semantics                                         |
| `Transform`                  | ✅      | Transform callback support                                    |
| `renderToString()`           | ✅      | Synchronous snapshot                                          |
| `measureElement()`           | ✅      | Returns `{ x, y, width, height }`                             |
| `useApp()`                   | ✅      | `exit` + `quit`                                               |
| `useInput()`                 | ✅      | Arrows, Enter, Escape, Ctrl, Meta, paging keys                |
| `usePaste()`                 | ✅      | Bracketed paste routing                                       |
| `useFocus()`                 | ✅      | Focus state and `focus(id)`                                   |
| `useFocusManager()`          | ✅      | Focus navigation methods                                      |
| `useStdin()`                 | ✅      | Raw mode helpers                                              |
| `useStdout()`                | ✅      | Buffered while app is running                                 |
| `useStderr()`                | ✅      | Buffered while app is running                                 |
| `useBoxMetrics()`            | ✅      | Layout metrics + `hasMeasured` (intended for `render()` mode) |
| `useWindowSize()`            | ✅      | `{ columns, rows }` (intended for `render()` mode)            |
| `Cursor`                     | ✅      | Declarative cursor; inline mode + anchor mode                 |
| `useCursor()`                | ✅      | Imperative cursor positioning with IME support                |
| `useAnimation()`             | ✅      | Shared-timer animation driver: frame, time, delta, reset      |
| `Link`                       | ✅      | Ported from `ink-link`, OSC 8 clickable hyperlinks            |
| `ProgressBar`                | ✅      | Ported from `ink-progress-bar`, percent-based fill            |
| `SelectInput`                | ✅      | Ported from `ink-select-input`, interactive list selection    |
| `TextInput`                  | ✅      | Inspired by `ink-ui`, single-line text entry with cursor      |
| `ConfirmInput`               | ✅      | Inspired by `ink-ui`, Y/N confirmation prompt                 |
| `MultiSelect`                | ✅      | Inspired by `ink-ui`, multi-choice selection with checkboxes  |
| `Badge`                      | ✅      | Inspired by `ink-ui`, uppercase colored label                 |
| `StatusMessage`              | ✅      | Inspired by `ink-ui`, status icon + message                   |
| `Alert`                      | ✅      | Inspired by `ink-ui`, bordered variant alert box              |
| `UnorderedList`              | ✅      | Inspired by `ink-ui`, bullet list with nesting                |
| `OrderedList`                | ✅      | Inspired by `ink-ui`, numbered list with nesting              |
| `useIsScreenReaderEnabled()` | ✅      | Enabled via `render()` option or `INK_SCREEN_READER` env var  |

## Render Option Differences [#render-option-differences]

`render()` accepts Ink-style options, but these are currently ignored:

* `concurrent`
* `patchConsole`
* `exitOnCtrlC`
* `incrementalRendering`
* `debug`

`maxFps` is used.

## Mouse Support (Ink Layer) [#mouse-support-ink-layer]

Ported from [`@zenobius/ink-mouse`](https://github.com/zenobi-us/ink-mouse). Import from `@visulima/tui`.

| Export                   | Description                                      |
| ------------------------ | ------------------------------------------------ |
| `<MouseProvider>`        | Enables mouse tracking for descendant components |
| `<Fullscreen>`           | Terminal-filling Box container                   |
| `useMouseContext()`      | Full mouse context (position, events, actions)   |
| `useMousePosition()`     | Reactive mouse coordinates                       |
| `useMouseAction()`       | Current action (click/scroll/drag)               |
| `useOnMouseClick(ref)`   | Click detection on an element                    |
| `useOnMouseHover(ref)`   | Hover detection on an element                    |
| `useOnMouseState(ref)`   | Combined `{ hovering, clicking }` state          |
| `useElementPosition()`   | Absolute element position via Yoga tree          |
| `useElementDimensions()` | Element width and height                         |
| `isIntersecting()`       | Hit-test utility                                 |

See the [Mouse Support](/docs/packages/tui/mouse) page for full documentation.

## Scroll Components (Ink Layer) [#scroll-components-ink-layer]

Ported from [`ink-scroll-view`](https://github.com/ByteLandTechnology/ink-scroll-view), [`@byteland/ink-scroll-bar`](https://github.com/ByteLandTechnology/ink-scroll-bar), and [`ink-scroll-list`](https://github.com/ByteLandTechnology/ink-scroll-list). Import from `@visulima/tui`.

| Export                   | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `<ScrollView>`           | Scrollable viewport with imperative ref for scroll control    |
| `<ControlledScrollView>` | Controlled variant — parent owns `scrollOffset`               |
| `<ScrollBar>`            | Vertical scroll bar indicator (border or inset placement)     |
| `<ScrollBarBox>`         | Box with integrated scroll bar on one border                  |
| `<ScrollList>`           | ScrollView + externally controlled selection with auto-scroll |

See the [Scroll Components](/docs/packages/tui/scroll) page for full documentation.

## CSS-Level Scroll and Measurement APIs [#css-level-scroll-and-measurement-apis]

Ported from [jacob314/ink](https://github.com/jacob314/ink) (Google's Gemini CLI fork). These extend Ink's `Box` with CSS-level overflow scrolling, sticky headers, and advanced measurement.

| Export                                   | Description                                                      |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `Box` `overflow="scroll"`                | CSS-level overflow scrolling with integrated scrollbar rendering |
| `Box` `sticky`                           | Sticky headers that pin to viewport edges during scroll          |
| `Box` `scrollbar`                        | Show/hide scrollbar on scrollable containers                     |
| `ResizeObserver`                         | Browser-like API for observing element size changes              |
| `getBoundingBox()`                       | Scroll-aware absolute position and dimensions                    |
| `getInnerWidth()` / `getInnerHeight()`   | Inner dimensions excluding borders                               |
| `getScrollHeight()` / `getScrollWidth()` | Total scroll content dimensions                                  |
| `getScrollTop()` / `getScrollLeft()`     | Current scroll position                                          |
| `calculateScroll()`                      | Compute scroll state for a scrollable element                    |
| `getVerticalScrollbarBoundingBox()`      | Scrollbar thumb position for hit testing                         |
| `getHorizontalScrollbarBoundingBox()`    | Horizontal scrollbar position                                    |
| `setStringWidthFunction()`               | Replace the string width function for custom terminals           |
| `getRelativeTop()` / `getRelativeLeft()` | Position relative to an ancestor element                         |

## Native Renderer API (No Ink Equivalent) [#native-renderer-api-no-ink-equivalent]

| Export                                                                | Description                                                                                                           |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `useScrollable()`                                                     | Virtual scrolling state helper                                                                                        |
| `useMouse()`                                                          | Mouse click/wheel events with modifiers                                                                               |
| `useTextInput()`                                                      | Managed text editing hook                                                                                             |
| `Spinner`                                                             | Animated spinner component                                                                                            |
| `renderInline()`                                                      | React inline rendering mode                                                                                           |
| `createInlineLoop()`                                                  | Raw-buffer inline rendering loop                                                                                      |
| `Renderer` / `TerminalGuard`                                          | Raw-buffer runtime primitives                                                                                         |
| `render` / `cleanup` / `screen` / `keys` / `waitFor` / `flush` (test) | Testing utilities with mock streams, screen queries, keyboard simulation, and async assertions (`@visulima/tui/test`) |

## Architectural Differences vs Ink [#architectural-differences-vs-ink]

| Concern            | Ink                  | @visulima/tui                |
| ------------------ | -------------------- | ---------------------------- |
| Render strategy    | JS string renderer   | Rust diff over `Uint32Array` |
| Screen mode        | Inline rewrite model | Alternate screen model       |
| `patchConsole`     | Integrated           | Not implemented              |
| Screen reader hook | Functional           | Functional (opt-in)          |
| Cursor hook        | Functional           | Functional                   |

## Ports of Upstream Ink PRs [#ports-of-upstream-ink-prs]

A handful of in-flight upstream Ink PRs are vendored in `@visulima/tui` ahead of merge. Behavior is intended to match upstream; any drift is a bug.

| Upstream PR                                                                                                | Behavior in `@visulima/tui`                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [#115 — Math.round on Yoga computed values](https://github.com/vadimdemedes/ink/pull/115)                  | All Yoga `getComputedLeft/Top/Width/Height` reads are wrapped in `Math.round` (`render-node-to-output.ts`, `render-text-node.ts`) so subpixel layouts snap to integer cells.                                    |
| [#119 — `StaticRender` `deps` prop](https://github.com/vadimdemedes/ink/pull/119)                          | `<StaticRender>` accepts a `deps: DependencyList` prop. The cached subtree is invalidated when any dep changes (shallow `Object.is` compare). See [components.mdx](/docs/packages/tui/components#staticrender). |
| [#123 — neighbor-merge & ASCII fast paths in text rendering](https://github.com/vadimdemedes/ink/pull/123) | Text rendering reuses neighbor cells where possible and takes a fast path for ASCII spans, reducing per-cell allocation in the most common case.                                                                |
| [#125 — conditional accessibility objects in Box](https://github.com/vadimdemedes/ink/pull/125)            | `<Box>` only emits an `internal_accessibility` object when `role` or `aria-state` is set, avoiding wasted allocations on the layout-only path.                                                                  |

## `compat-test/` Status [#compat-test-status]

The `compat-test/` directory tracks runnable Ink example ports.

* Most files are direct ports with import-path changes
* Two files include small TypeScript typing fixes from upstream examples (`use-focus.tsx`, `use-focus-with-id.tsx`)

Run examples manually:

```bash
node --import @oxc-node/core/register compat-test/counter.tsx
node --import @oxc-node/core/register compat-test/chat.tsx
```


# Ink Performance Plan (/docs/packages/tui/ink-performance-plan)



# Ink performance plan (without switching to Ratatat) [#ink-performance-plan-without-switching-to-ratatat]

> Part of the [Ratatat docs](/docs/packages/tui). See also: [Why Ink is slower on heavy redraws](/docs/packages/tui/why-is-ink-slow)

This document turns the ideas in section 8 of `why-is-ink-slow.md` into an execution plan.

The goal is to answer: &#x2A;*if we were improving Ink itself, what should we build first, how would we validate it, and how would we ship it safely?**

Status: this plan has a research-grade PoC implementation in `ink-fast`, including committed benchmark snapshots.

***

## 1) Goals and constraints [#1-goals-and-constraints]

## Goals [#goals]

* Improve Ink runtime performance for heavy redraw workloads.
* Preserve Ink's public API and existing app behavior.
* Keep a pure-JS path available by default.

## Non-goals [#non-goals]

* Rewriting Ink to match Ratatat internals 1:1.
* Breaking changes to core component/hook APIs.
* Trading correctness/accessibility for benchmark-only wins.

## Constraints [#constraints]

* Must stay compatible with React + Yoga architecture.
* Must preserve Unicode/ANSI correctness.
* Must not regress low-frequency CLI UX.

***

## 2) Current bottleneck model [#2-current-bottleneck-model]

```text
Ink today (simplified)

React commit
  -> Yoga layout
  -> tree walk -> render ops
  -> JS output structure build
  -> ANSI-rich frame string
  -> log-update string/line diff
  -> terminal writes
```

Most performance pain for dense updates is in the post-Yoga JS text pipeline.

***

## 3) Success metrics [#3-success-metrics]

Use three benchmark classes:

1. **Dense redraw**: 80x24 and 160x48, 100% dirty each frame
2. **Mixed redraw**: 5–25% dirty
3. **Unicode-heavy**: wide glyphs + ANSI styles

Track:

* median/p95 frame time
* max sustainable FPS at fixed CPU budget
* allocations / GC pause time
* terminal write bytes per second

Target outcomes (initial):

* 20–30% lower median frame time on dense redraws
* 30% lower allocation rate on dense redraws
* no functional regressions in existing examples/tests

***

## 4) Delivery phases [#4-delivery-phases]

## Phase 0 — Instrumentation first (low risk, high ROI) [#phase-0--instrumentation-first-low-risk-high-roi]

**Why first:** without stage timing, optimization work is guesswork.

### Work [#work]

* Add internal timing hooks around:
  * tree walk/render op generation
  * output assembly
  * diff generation
  * terminal write
* Add optional debug output / callback API for stage timings.
* Add stable benchmark fixtures for dense, sparse, unicode workloads.

### Exit criteria [#exit-criteria]

* Repeatable numbers across runs
* per-stage timings visible
* baseline snapshot committed

***

## Phase 1 — Low-risk JS optimizations [#phase-1--low-risk-js-optimizations]

### 1. Persistent output surface [#1-persistent-output-surface]

**Idea:** stop rebuilding full output structures every frame.

* Reuse row/cell containers and scratch buffers
* Track dirty ranges per row
* Avoid full re-init unless geometry changed

**Expected impact:** lower allocations + GC pressure.

### 2. Hot-path text cache improvements [#2-hot-path-text-cache-improvements]

**Idea:** cache expensive text transforms by `(text, width, style, wrapMode)`.

* cache wrapped/truncated results
* cache tokenized ANSI segments for repeated strings
* optimize invalidation strategy to avoid stale style outputs

**Expected impact:** lower CPU in text-heavy UIs.

### 3. log-update path tightening [#3-log-update-path-tightening]

* reduce redundant string splitting/joining
* fast-path “no output change” and small-cursor moves
* reduce escape sequence churn where possible

**Expected impact:** lower JS overhead in frequent rerender loops.

### Exit criteria [#exit-criteria-1]

* measurable wins in dense + mixed benchmarks
* no regressions in Unicode/ANSI correctness tests

***

## Phase 2 — Algorithmic diff improvements (medium risk) [#phase-2--algorithmic-diff-improvements-medium-risk]

### 1. Better diff granularity than whole-line rewrites [#1-better-diff-granularity-than-whole-line-rewrites]

* Move from coarse string/line diff toward segment-level diff for changed lines
* Keep unchanged line segments untouched

### 2. Dirty-region propagation [#2-dirty-region-propagation]

* Derive minimal affected regions from node/layout changes
* Skip full-frame output work when only local regions changed

### Exit criteria [#exit-criteria-2]

* p95 frame time reduced for partial-dirty workloads
* write volume reduced on sparse updates

***

## Phase 3 — Optional cell backend inside Ink (higher impact) [#phase-3--optional-cell-backend-inside-ink-higher-impact]

### Idea [#idea]

Keep React+Yoga front half, add alternate backend:

```text
Ink with optional cell backend

React -> Yoga -> typed cell surface -> cell diff -> ANSI
```

Implement as feature flag / opt-in config first:

* `backend: 'string' | 'cells'` (example shape)
* default remains `'string'` for compatibility

### Why this matters [#why-this-matters]

This directly attacks the biggest current bottleneck: frame-sized JS string assembly/diff in hot paths.

### Exit criteria [#exit-criteria-3]

* clear wins on dense redraws
* behavior parity with string backend on compatibility tests

***

## Phase 4 — Optional native accelerator (longer-term) [#phase-4--optional-native-accelerator-longer-term]

If a pure-JS cell backend still leaves performance on the table:

* add opt-in native diff/write module (N-API, optional dependency)
* keep pure-JS fallback as default
* enable only when available + explicitly requested

This gives an escape hatch for high-performance workloads without forcing native runtime requirements on all users.

***

## 5) Risk register [#5-risk-register]

| Risk                                          | Impact | Mitigation                                                 |
| --------------------------------------------- | ------ | ---------------------------------------------------------- |
| Unicode/ANSI rendering regressions            | High   | Add golden tests for wide chars + styled segments          |
| Terminal-specific behavior differences        | Medium | Test matrix: macOS Terminal, iTerm2, Linux terminals, CI   |
| Optimization complexity hurts maintainability | Medium | Phase-gate changes, keep feature flags, document internals |
| Benchmark-only wins without real-world gains  | Medium | Include app-like mixed workloads, not only synthetic tests |

***

## 6) Suggested implementation slices (PR-sized) [#6-suggested-implementation-slices-pr-sized]

1. Stage timing hooks + baseline benchmark harness
2. Persistent output surface reuse
3. Text/token cache improvements
4. log-update fast paths
5. Segment-level diff prototype behind flag
6. Optional cell backend behind flag
7. Native accelerator spike (optional)

Each slice should include:

* before/after benchmark snapshot
* regression tests
* rollback path (flag or isolated module)

***

## 7) Decision gate: when to stop [#7-decision-gate-when-to-stop]

Stop after Phase 1 or 2 if:

* targets are met,
* maintenance cost stays low,
* and real app traces improve enough.

Only move to cell/native backend if measured gains justify complexity.


# Mouse Support (/docs/packages/tui/mouse)



# Mouse Support [#mouse-support]

Provides mouse position tracking, hover detection, click handling, drag tracking, and element hit-testing for Ink-compatible components.

Ported from [`@zenobius/ink-mouse`](https://github.com/zenobi-us/ink-mouse) by Zeno Jiricek (Apache-2.0), rewritten to integrate with the ink input pipeline.

## Features [#features]

* Mouse position tracking across the terminal
* Hover detection on specific elements
* Click detection on specific elements
* Drag tracking
* Scroll wheel events
* Element position and dimension tracking
* Hit-test utility for custom intersection logic

## Quick Start [#quick-start]

Wrap your app with `<MouseProvider>` and use the hooks inside child components.

> **Note:** You must also use `useInput` to prevent raw escape sequences from being printed to the terminal during mouse movements.

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
import { render } from "@visulima/tui";
import { Fullscreen, MouseProvider, useMousePosition, useOnMouseClick, useOnMouseHover, useOnMouseState } from "@visulima/tui";
import React, { useMemo, useRef, useState } from "react";
import type { ComponentProps, RefObject } from "react";
import type { DOMElement } from "@visulima/tui";
function App() {
    return (
        <MouseProvider>
            <Demo />
        </MouseProvider>
    );
}

function Demo() {
    const position = useMousePosition();
    const [count, setCount] = useState(0);

    // Consume escape sequences so they don't print to the terminal
    useInput(() => {});

    return (
        <Box gap={1} flexDirection="column" width={40} height={10} borderStyle="round" padding={1}>
            <Box gap={1}>
                <Button label="Click me" onClick={() => setCount((c) => c + 1)} />
            </Box>
            <Box flexDirection="column" gap={1}>
                <Text>
                    Mouse: {position.x}, {position.y}
                </Text>
                <Text>Clicked: {count} times</Text>
            </Box>
        </Box>
    );
}

function Button({ label, onClick }: { label: string; onClick?: () => void }) {
    const ref = useRef<DOMElement | null>(null);
    const [hovering, setHovering] = useState(false);
    const [clicking, setClicking] = useState(false);

    useOnMouseClick(ref, (event) => {
        setClicking(event);
        if (event && onClick) {
            onClick();
        }
    });
    useOnMouseHover(ref, setHovering);

    const border = useMemo((): ComponentProps<typeof Box>["borderStyle"] => {
        if (clicking) return "double";
        if (hovering) return "singleDouble";
        return "single";
    }, [clicking, hovering]);

    return (
        <Box gap={1} paddingX={1} ref={ref} borderStyle={border}>
            <Text>{label}</Text>
        </Box>
    );
}

render(<App />);
```

## Components [#components]

### `<MouseProvider>` [#mouseprovider]

Wraps the component tree to enable mouse tracking. Listens on ink's input pipeline for SGR mouse sequences and provides mouse state to all descendant hooks via context.

Mouse tracking ANSI codes are enabled on mount and disabled on unmount.

```tsx
<MouseProvider>
    <YourApp />
</MouseProvider>
```

### `<Fullscreen>` [#fullscreen]

A convenience component that fills the entire terminal. Uses `useWindowSize` to track terminal dimensions.

```tsx
<MouseProvider>
    <Fullscreen>
        <YourApp />
    </Fullscreen>
</MouseProvider>
```

## Hooks [#hooks]

All hooks below must be used inside a `<MouseProvider>`.

### `useMouseContext()` [#usemousecontext]

Returns the full mouse context object. Useful for accessing the internal event emitter directly.

```tsx
const mouse = useMouseContext();
// mouse.position  - { x, y }
// mouse.button    - "left" | "middle" | "right" | null
// mouse.click     - "press" | "release" | null
// mouse.scroll    - "scrollup" | "scrolldown" | null
// mouse.drag      - "dragging" | null
// mouse.events    - EventEmitter (position, click, scroll, drag events)
```

### `useMousePosition()` [#usemouseposition]

Returns reactive mouse coordinates. Re-renders the component on every mouse move.

```tsx
const { x, y } = useMousePosition();
```

### `useMouseAction()` [#usemouseaction]

Returns the most recent mouse action (click, scroll, or drag).

```tsx
const action = useMouseAction();
// "press" | "release" | "scrollup" | "scrolldown" | "dragging" | null
```

### `useOnMouseClick(ref, onChange, options?)` [#useonmouseclickref-onchange-options]

Fires `onChange(true, button)` when the mouse clicks inside the element, `onChange(false)` otherwise. Supports left, middle, and right mouse buttons.

```tsx
const ref = useRef<DOMElement | null>(null);

// Respond to any button
useOnMouseClick(ref, (isClicking, button) => {
    if (isClicking) {
        console.log(`${button} click!`);
    }
});

// Respond to right-click only
useOnMouseClick(
    ref,
    (isClicking) => {
        if (isClicking) showContextMenu();
    },
    { button: "right" },
);

return <Box ref={ref}>...</Box>;
```

| Argument   | Type                                                |
| ---------- | --------------------------------------------------- |
| `ref`      | `RefObject<DOMElement \| null>`                     |
| `onChange` | `(clicking: boolean, button?: MouseButton) => void` |
| `options?` | `{ button?: MouseButton }`                          |

When `options.button` is set, the hook only fires for that specific button.

### `useOnMouseHover(ref, onChange)` [#useonmousehoverref-onchange]

Fires `onChange(true)` when the mouse enters the element, `onChange(false)` when it leaves.

```tsx
const ref = useRef<DOMElement | null>(null);

useOnMouseHover(ref, (isHovering) => {
    setHighlighted(isHovering);
});

return <Box ref={ref}>...</Box>;
```

| Argument   | Type                            |
| ---------- | ------------------------------- |
| `ref`      | `RefObject<DOMElement \| null>` |
| `onChange` | `(hovering: boolean) => void`   |

### `useOnMouseState(ref)` [#useonmousestateref]

Combines click and hover detection into a single hook.

```tsx
const ref = useRef<DOMElement | null>(null);
const { hovering, clicking } = useOnMouseState(ref);

return (
    <Box ref={ref} borderStyle={clicking ? "double" : hovering ? "bold" : "single"}>
        <Text>{hovering ? "Hovered!" : "Move mouse here"}</Text>
    </Box>
);
```

Returns `{ hovering: boolean, clicking: boolean }`.

### `useElementPosition(ref, deps?)` [#useelementpositionref-deps]

Returns the absolute position of the element by walking the Yoga layout tree.

```tsx
const ref = useRef<DOMElement | null>(null);
const { left, top } = useElementPosition(ref);
```

Terminal coordinates are 1-indexed. Pass optional `deps` array to recompute on specific changes.

### `useElementDimensions(ref, deps?)` [#useelementdimensionsref-deps]

Returns the computed dimensions of the element.

```tsx
const ref = useRef<DOMElement | null>(null);
const { width, height } = useElementDimensions(ref);
```

## Utilities [#utilities]

### `isIntersecting({ mouse, element })` [#isintersecting-mouse-element-]

Hit-test utility. Returns `true` if the mouse position falls within the element bounds.

```tsx
import { isIntersecting } from "@visulima/tui";
const hit = isIntersecting({
    mouse: { x: 10, y: 5 },
    element: { left: 8, top: 3, width: 20, height: 10 },
});
// true
```

## Types [#types]

```tsx
import type {
    MouseButton,
    MousePosition,
    MouseClickAction,
    MouseScrollAction,
    MouseDragAction,
    MouseAction,
    MouseContextShape,
    MouseEvents,
    SgrMouseEvent,
} from "@visulima/tui";
```

| Type                | Definition                                    |
| ------------------- | --------------------------------------------- |
| `MouseButton`       | `"left" \| "middle" \| "right"`               |
| `MousePosition`     | `{ x: number; y: number }`                    |
| `MouseClickAction`  | `"press" \| "release" \| null`                |
| `MouseScrollAction` | `"scrollup" \| "scrolldown" \| null`          |
| `MouseDragAction`   | `"dragging" \| null`                          |
| `MouseAction`       | `MouseClickAction \| MouseScrollAction`       |
| `MouseContextShape` | Full context value shape (includes `button`)  |
| `MouseEvents`       | `EventEmitter` for position/click/scroll/drag |
| `SgrMouseEvent`     | Discriminated union from `parseSgrMouse()`    |

## Architecture [#architecture]

The mouse module integrates with ink's existing input pipeline rather than attaching a separate stdin listener:

```
Terminal stdin
    |
    v
Ink App.tsx (reads stdin, parses escape sequences)
    |
    v
internal_eventEmitter.emit("input", sequence)
    |
    +---> useInput (keyboard)
    |
    +---> MouseProvider (detects SGR mouse sequences)
              |
              v
          EventEmitter (position/click/scroll/drag)
              |
              +---> useMousePosition()
              +---> useMouseAction()
              +---> useOnMouseClick(ref)
              +---> useOnMouseHover(ref)
              +---> useOnMouseState(ref)
```

This avoids competing stdin listeners and keeps mouse events in sync with keyboard input.

### `parseSgrMouse(input)` [#parsesgrmouseinput]

Low-level utility to parse an SGR 1006 mouse escape sequence. Returns a discriminated union or `null`.

```tsx
import { parseSgrMouse } from "@visulima/tui";
const event = parseSgrMouse("\x1b[<0;10;20M");
// { type: "click", button: "left", action: "press", x: 10, y: 20 }
```

Event types: `"click"`, `"drag"`, `"move"`, `"scroll"`. Modifier bits (shift, meta, ctrl) are automatically stripped from the button code.

## Known Limitations [#known-limitations]

* Overlapping elements both receive click/hover events (no z-order handling)
* Drag examples are limited
* Windows CMD.exe has limited ANSI support; Windows Terminal works


# Package Map (/docs/packages/tui/package-map)



# Package Map [#package-map]

`@visulima/tui` is a single package with multiple entry points.

Use this page to decide which entry to import and where each API lives.

## Quick Choice [#quick-choice]

| If you want to…                                    | Use entry point                         | Why                                                              |
| -------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| Get `render` and lower-level primitives            | `@visulima/tui`                         | Bare entry — render, layout/measurement, mouse, terminal palette |
| Use any hook (`useInput`, `useFocus`, …)           | `@visulima/tui/hooks/<kebab-name>`      | Each hook is published at its own subpath                        |
| Build a React TUI with the native renderer         | `@visulima/tui/react`                   | Native renderer with Rust-backed diff engine                     |
| Paint terminal cells directly from a `Uint32Array` | `@visulima/tui/core`                    | Lowest-level runtime, direct control over render loop and buffer |
| Use any component (`Box`, `Text`, `Spinner`, …)    | `@visulima/tui/components/<kebab-name>` | Each component is published at its own subpath                   |
| Render ASCII-art headlines (cfonts)                | `@visulima/tui/components/big-text`     | Heavy `cfonts` dep is loaded only when imported                  |
| Render syntax-highlighted code (shiki)             | `@visulima/tui/components/code`         | Heavy `shiki` deps are loaded only when imported                 |
| Render diffs (diff + shiki)                        | `@visulima/tui/components/diff-view`    | Heavy `diff` + `shiki` deps are loaded only when imported        |
| Render Markdown (marked + shiki)                   | `@visulima/tui/components/markdown`     | Heavy `marked` + `shiki` deps are loaded only when imported      |
| Render data tables (`@visulima/tabular`)           | `@visulima/tui/components/table`        | Heavy `@visulima/tabular` dep is loaded only when imported       |
| Test TUI components in isolation                   | `@visulima/tui/test`                    | Framework-agnostic render + mock streams for testing             |

## `@visulima/tui` [#visulimatui]

The bare entry point — `render`, layout/measurement helpers, and other lower-level primitives. Components and hooks live on per-symbol subpaths (see [`@visulima/tui/components/<name>`](#visulima-tui-components-name) and [`@visulima/tui/hooks/<name>`](#visulima-tui-hooks-name) below).

Primary exports:

* `render`, `renderToString`
* primitives: `MouseProvider`, `parseSgrMouse`, `processLayout`, `measureElement`, `applySelectionToStyledLine`, `clearOsc52`, `writeOsc52`, …

```bash npm2yarn
npm install @visulima/tui react
```

```typescript
import { render } from "@visulima/tui";
```

## `@visulima/tui/hooks/<name>` [#visulimatuihooksname]

Every hook lives at its own subpath under `@visulima/tui/hooks/<kebab-name>`. This keeps the import graph small and makes it explicit which hook you depend on.

```typescript
import { useAnimation } from "@visulima/tui/hooks/use-animation";
import { useFocus } from "@visulima/tui/hooks/use-focus";
import { useInput } from "@visulima/tui/hooks/use-input";
import { useTimer } from "@visulima/tui/hooks/use-timer";
```

Each subpath exports the hook as both a named export and a default export, plus its option/result types. Hook names map directly to their kebab-case subpath (`useAnimation` → `use-animation`, `useFocusManager` → `use-focus-manager`). The `createLinkedScrollGroup` factory lives at `use-linked-scroll`.

> **Breaking from earlier alphas.** Hooks are no longer re-exported from the bare `@visulima/tui` entry — you must import each one from its own subpath.

## `@visulima/tui/components/<name>` [#visulimatuicomponentsname]

Every component lives at its own subpath under `@visulima/tui/components/<kebab-name>`. This keeps the import graph small — you only pull in what you use, and heavy peer dependencies are loaded only when their component is imported.

```typescript
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { Spinner } from "@visulima/tui/components/spinner";
import { TextInput } from "@visulima/tui/components/text-input";
import { ProgressBar } from "@visulima/tui/components/progress-bar";
```

Each subpath exports the component as both a named export and a default export, plus its `*Props` type. PascalCase component names map to kebab-case subpaths (`BigText` → `big-text`, `SelectInput` → `select-input`, `TreeView` → `tree-view`).

> **Breaking from earlier alphas.** Components are no longer re-exported from the bare `@visulima/tui` entry — you must import each one from its own subpath.

### Heavy component subpaths [#heavy-component-subpaths]

A few components have large optional peer dependencies. Importing them via their subpath keeps your bundle small and makes the peer requirements explicit per component.

| Subpath                              | Component  | Required peer dependencies                             |
| ------------------------------------ | ---------- | ------------------------------------------------------ |
| `@visulima/tui/components/big-text`  | `BigText`  | `cfonts`                                               |
| `@visulima/tui/components/code`      | `Code`     | `shiki`, `@shikijs/langs`, `@shikijs/themes`           |
| `@visulima/tui/components/diff-view` | `DiffView` | `diff`, `shiki`, `@shikijs/langs`, `@shikijs/themes`   |
| `@visulima/tui/components/markdown`  | `Markdown` | `marked`, `shiki`, `@shikijs/langs`, `@shikijs/themes` |
| `@visulima/tui/components/table`     | `Table`    | `@visulima/tabular`                                    |

Install only what you need:

```bash npm2yarn
# BigText
npm install @visulima/tui react cfonts

# Code (and DiffView with syntax highlighting)
npm install @visulima/tui react shiki @shikijs/langs @shikijs/themes

# DiffView (without syntax highlighting)
npm install @visulima/tui react diff

# Markdown (with code block highlighting)
npm install @visulima/tui react marked shiki @shikijs/langs @shikijs/themes

# Table
npm install @visulima/tui react @visulima/tabular
```

> Importing a heavy subpath without its peer dependencies installed will throw a module-not-found error at runtime.

### React DevTools [#react-devtools]

Mounting the React DevTools overlay is opt-in and gated by the `DEV=true` environment variable. To enable it, install the optional peers:

```bash npm2yarn
npm install --save-dev react-devtools-core ws
```

```bash
DEV=true node ./my-app.js
```

When `DEV` is unset, neither `react-devtools-core` nor `ws` is loaded.

## `@visulima/tui/core` [#visulimatuicore]

Framework-agnostic runtime backed by the Rust diff engine.

Primary APIs are exposed to TypeScript/JavaScript while rendering is handled by a native Rust diff engine.

Primary exports:

* `Renderer`
* `TerminalGuard`
* `terminalSize`
* `Cell`, `StyleMasks`
* `InputParser`
* `TuiApp`
* `createInlineLoop`

```bash npm2yarn
npm install @visulima/tui
```

```typescript
import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";
```

## `@visulima/tui/react` [#visulimatuireact]

Native React renderer — uses a Rust-backed diff engine for high-performance rendering.

Depends on `@visulima/tui/core` for terminal output and native diffing.

Primary exports:

* `render`, `renderInline`, `renderToString`
* components: `Static`, `DevTools`
* hooks: `useInput`, `useApp`, `useFocus`, `useFocusManager`, `useMouse`, `useScrollable`, `useTextInput`, `useWindowSize`, and more

> Components (`Box`, `Text`, `Spinner`, etc.) are imported from their dedicated subpaths under `@visulima/tui/components/<name>` — the native renderer uses the same components.

```bash npm2yarn
npm install @visulima/tui react
```

```typescript
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { render, useInput } from "@visulima/tui/react";
```

## `@visulima/tui/test` [#visulimatuitest]

Framework-agnostic testing utilities for TUI components. Inspired by [ink-testing-library](https://github.com/vadimdemedes/ink-testing-library) and [ink-testing](https://github.com/cjroth/ink-web/tree/main/packages/ink-testing).

Primary exports:

* `render` — render a component with mock streams, returns test instance with `screen`, `keys`, `waitFor`, `flush`
* `cleanup` — unmount all test instances (use in `afterEach`)
* `createScreen` — standalone screen query helpers with ANSI stripping
* `createKeySender` — standalone keyboard input simulator
* `KEY` — raw ANSI escape sequence constants for all common keys
* `waitFor` — standalone async polling assertion

```typescript
import { render, cleanup, KEY, createScreen, createKeySender, waitFor } from "@visulima/tui/test";
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Getting Started" href="/docs/packages/tui/getting-started">
    Installation and first-run setup
  </Card>

  <Card title="Quickstart: React" href="/docs/packages/tui/quickstart-react">
    Build a TUI app with React components
  </Card>

  <Card title="Quickstart: Raw Buffer" href="/docs/packages/tui/quickstart-raw-buffer">
    Direct cell rendering without React
  </Card>

  <Card title="Rendering Modes" href="/docs/packages/tui/rendering-modes">
    Full comparison of all three modes
  </Card>
</Cards>


# Quickstart: Raw-Buffer Mode (/docs/packages/tui/quickstart-raw-buffer)



# Quickstart: Raw-Buffer Mode [#quickstart-raw-buffer-mode]

Drive the Rust renderer directly — no React, no Yoga, no JSX.

Use this mode when you want explicit control over every terminal cell.

```bash npm2yarn
npm install @visulima/tui
```

## Minimal Example [#minimal-example]

```ts
import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";

const { cols, rows } = terminalSize();
const guard = new TerminalGuard();
const renderer = new Renderer(cols, rows);

// 2 u32 slots per cell: [codepoint, attrCode]
let buf = new Uint32Array(cols * rows * 2);
let frame = 0;

const loop = setInterval(() => {
    buf.fill(0);

    const text = `Hello! Frame ${frame++}`;
    for (let i = 0; i < text.length; i++) {
        const idx = (2 * cols + 2 + i) * 2;
        buf[idx] = text.codePointAt(i)!;
        buf[idx + 1] = (1 << 16) | (2 << 8) | 6; // bold | bg=green(2) | fg=cyan(6)
    }

    renderer.render(buf);
}, 16);

process.on("SIGINT", () => {
    clearInterval(loop);
    guard.leave();
    process.exit(0);
});
```

Run it:

```bash
node --import @oxc-node/core/register app.ts
```

## Buffer Contract [#buffer-contract]

Each terminal cell uses two consecutive `u32` values:

```text
buf[idx * 2]     = Unicode codepoint
buf[idx * 2 + 1] = attr code
```

Cell index for `(col, row)`:

```ts
const idx = row * cols + col;
```

### Attr Code Format [#attr-code-format]

```text
attr = (styleBits << 16) | (bg << 8) | fg
```

`fg` and `bg` are ANSI 256-color indices (`0-255`).

Style bitmask:

| Bit | Style         |
| --- | ------------- |
| 1   | Bold          |
| 2   | Dim           |
| 4   | Italic        |
| 8   | Underline     |
| 16  | Blink         |
| 32  | Invert        |
| 64  | Hidden        |
| 128 | Strikethrough |

Example attr values:

```ts
const plain = 0;
const boldCyan = (1 << 16) | 6;
const redOnBlue = (4 << 8) | 1; // fg red(1), bg blue(4)
const dimGreen = (2 << 16) | 2;
```

## `TerminalGuard` [#terminalguard]

`TerminalGuard` controls terminal lifecycle (raw mode, alternate screen, cursor visibility).

```ts
const guard = new TerminalGuard(); // no mouse/paste tracking
const guardWithMouse = new TerminalGuard(true); // enable mouse + bracketed paste tracking
```

Always call `guard.leave()` on shutdown.

## `Renderer` [#renderer]

```ts
const renderer = new Renderer(cols, rows);

renderer.render(buf); // diff + write
renderer.resize(cols, rows);
renderer.renderDiff(buf); // returns ANSI string
renderer.writeRaw("\x1b[2J");
```

`renderer.render()` only emits changed cells.

## Resize Handling [#resize-handling]

```ts
process.on("SIGWINCH", () => {
    const { cols, rows } = terminalSize();
    renderer.resize(cols, rows);
    buf = new Uint32Array(cols * rows * 2);
});
```

## Inline Mode: `createInlineLoop()` [#inline-mode-createinlineloop]

```ts
import { createInlineLoop } from "@visulima/tui/core";

const loop = createInlineLoop(
    (buf, cols, rows, frame) => {
        buf.fill(0);
        const msg = `frame ${frame}`;
        for (let i = 0; i < msg.length; i++) {
            const idx = i * 2;
            buf[idx] = msg.codePointAt(i)!;
            buf[idx + 1] = 6; // cyan fg
        }
    },
    {
        rows: 4,
        fps: 30,
        onExit: "preserve",
    },
);

loop.start();
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Raw Buffer API" href="/docs/packages/tui/raw-buffer">
    Deep dive: buffer format, helpers, clearing strategies
  </Card>

  <Card title="TypeScript Buffer Guide" href="/docs/packages/tui/ts-buffer-guide">
    Indexing, packing attributes, and drawing helpers
  </Card>

  <Card title="Examples" href="/docs/packages/tui/examples">
    Raw-buffer demo apps
  </Card>

  <Card title="Rendering Modes" href="/docs/packages/tui/rendering-modes">
    Compare React, raw-buffer, and inline modes
  </Card>
</Cards>


# Quickstart: React Mode (/docs/packages/tui/quickstart-react)



# Quickstart: React Mode [#quickstart-react-mode]

Build a TUI app with React components, hooks, and Yoga layout.

```bash npm2yarn
npm install @visulima/tui react
```

## Minimal Example [#minimal-example]

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { render, useInput } from "@visulima/tui/react";
import React, { useState } from "react";

function Counter() {
    const [count, setCount] = useState(0);

    useInput((_input, key) => {
        if (key.upArrow) setCount((c) => c + 1);
        if (key.downArrow) setCount((c) => c - 1);
    });

    return (
        <Box flexDirection="column" padding={1}>
            <Text bold color="cyan">
                Counter
            </Text>
            <Text>Count: {count}</Text>
            <Text dim>↑↓ to change · Ctrl+C to exit</Text>
        </Box>
    );
}

render(<Counter />);
```

Run it:

```bash
node --import @oxc-node/core/register app.tsx
```

## Render Path [#render-path]

1. `render(<App />)` mounts your tree into Yoga layout nodes
2. React commits set a dirty flag
3. A frame loop checks the dirty flag at `maxFps` (default 60)
4. Dirty frames run layout + paint into `Uint32Array`
5. Rust diff emits only changed terminal cells as ANSI

## Layout: `Box` [#layout-box]

`Box` is the main layout primitive.

```tsx
<Box flexDirection="row" gap={2} padding={1}>
    <Box flexDirection="column" flexGrow={1} borderStyle="round">
        <Text>Left panel</Text>
    </Box>
    <Box flexDirection="column" width={30} borderStyle="single">
        <Text>Right panel</Text>
    </Box>
</Box>
```

Common props: `flexDirection`, `flexGrow`, `flexShrink`, `width`, `height`, `padding`, `margin`, `gap`, `alignItems`, `justifyContent`, `borderStyle`.

## Text Styling [#text-styling]

```tsx
<Text color="cyan" bold>Bold cyan text</Text>
<Text color="#ff6600">Hex color</Text>
<Text backgroundColor="blue" color="white">Highlighted</Text>
<Text italic dim>Dim italic</Text>
```

Color accepts named values, `#rgb`, `#rrggbb`, `rgb(r,g,b)`, and ANSI 256-color indices (`0-255`).

## Keyboard Input [#keyboard-input]

```tsx
useInput((input, key) => {
    if (key.upArrow) moveUp();
    if (key.downArrow) moveDown();
    if (key.return) submit();
    if (key.escape) cancel();
    if (key.ctrl && input === "c") exit();
});
```

See [Hooks: useInput](/docs/packages/tui/hooks#useinput) for the full key map.

## App Lifecycle [#app-lifecycle]

```tsx
import { Text } from "@visulima/tui/components/text";
import { useApp, useInput } from "@visulima/tui/react";

function App() {
    const { exit } = useApp();

    useInput((_input, key) => {
        if (key.escape) exit();
    });

    return <Text>Press Esc to quit</Text>;
}
```

`useApp()` returns both `exit()` and `quit()`.

## `render()` Options and Return Value [#render-options-and-return-value]

```tsx
const { rerender, unmount, waitUntilExit } = render(<App />, {
    maxFps: 30, // default 60
});

rerender(<App theme="dark" />);
unmount();
await waitUntilExit();
```

## `renderToString` for Tests [#rendertostring-for-tests]

```tsx
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { renderToString } from "@visulima/tui/react";
import React from "react";

const output = renderToString(
    <Box>
        <Text color="green">hello</Text>
    </Box>,
);

// output: 'hello'
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Components" href="/docs/packages/tui/components">
    Box, Text, Static, Spinner, ProgressBar props reference
  </Card>

  <Card title="Hooks" href="/docs/packages/tui/hooks">
    Input, mouse, focus, scrollable, and other hooks
  </Card>

  <Card title="Examples" href="/docs/packages/tui/examples">
    Runnable demo apps
  </Card>
</Cards>


# Raw Buffer API (/docs/packages/tui/raw-buffer)



# Raw Buffer API [#raw-buffer-api]

The Rust renderer in `@visulima/tui/core` accepts a `Uint32Array` back buffer and emits minimal ANSI updates.

## Core Contract [#core-contract]

```text
Uint32Array(cols × rows × 2) -> Rust diff -> ANSI writes
```

You control how the buffer is filled.

## Buffer Format [#buffer-format]

Each cell uses two `u32` values:

```text
buffer[idx * 2]     = Unicode codepoint
buffer[idx * 2 + 1] = attr code = (styles << 16) | (bg << 8) | fg
```

Cell index for `(x, y)`:

```ts
const idx = y * cols + x;
```

* `fg` / `bg`: ANSI 256 color (`0-255`)
* style bits:

| Bit | Style         |
| --- | ------------- |
| 1   | Bold          |
| 2   | Dim           |
| 4   | Italic        |
| 8   | Underline     |
| 16  | Blink         |
| 32  | Invert        |
| 64  | Hidden        |
| 128 | Strikethrough |

## Minimal Setup [#minimal-setup]

```ts
import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";

const guard = new TerminalGuard();
const { cols, rows } = terminalSize();
const renderer = new Renderer(cols, rows);
let buf = new Uint32Array(cols * rows * 2);

function paint() {
    buf.fill(0);

    // 'H' at (5, 3), bright red fg
    const idx = (3 * cols + 5) * 2;
    buf[idx] = "H".codePointAt(0)!;
    buf[idx + 1] = 196;

    renderer.render(buf);
}

const timer = setInterval(paint, 16);

process.on("SIGINT", () => {
    clearInterval(timer);
    guard.leave();
    process.exit(0);
});
```

## Convenience Helpers [#convenience-helpers]

### `Cell.pack` [#cellpack]

```ts
import { Cell, StyleMasks } from "@visulima/tui/core";

const [charCode, attrCode] = Cell.pack("A", 196, 0, StyleMasks.BOLD);
buf[idx * 2] = charCode;
buf[idx * 2 + 1] = attrCode;
```

### `setCell` Helper from Repo Examples [#setcell-helper-from-repo-examples]

```ts
import { setCell } from "./examples-raw/harness";

setCell(buf, cols, x, y, "A", 196, 0, 1); // 1 = bold style bit
```

## Resize Handling [#resize-handling]

```ts
process.on("SIGWINCH", () => {
    const { cols, rows } = terminalSize();
    renderer.resize(cols, rows);
    buf = new Uint32Array(cols * rows * 2);
});
```

## Clearing Strategy [#clearing-strategy]

Use one of these patterns per frame:

**1. Full clear + repaint**

```ts
buf.fill(0);
// repaint everything you want visible this frame
```

**2. Sparse updates with explicit stale clears**

Track previously painted cells and write spaces into cells that are no longer active.

Useful for pointer/cursor/sprite style renderers.

## Character Caveat [#character-caveat]

Block glyphs (`█`, `▓`, `▒`, `░`) can visually look like background fills.
For moving marks, narrow foreground glyphs (`▪`, `·`, `│`, `─`) are often easier to clear cleanly.

## Harness Pattern in Repo Examples [#harness-pattern-in-repo-examples]

`examples-raw/harness.ts` wraps common loop boilerplate (guard, renderer, resize, Ctrl+C):

```ts
import { createLoop } from "./examples-raw/harness";

const loop = createLoop((buf, cols, rows, frame) => {
    // paint frame
}, 60);

loop.start();
```

## Inline Mode: `createInlineLoop()` [#inline-mode-createinlineloop]

`createInlineLoop` draws a fixed-height region below the current cursor, without alternate screen takeover.

```ts
import { createInlineLoop } from "@visulima/tui/core";

const loop = createInlineLoop(
    (buf, cols, rows, frame) => {
        buf.fill(0);
        const text = `frame ${frame}`;
        for (let i = 0; i < text.length; i++) {
            const idx = i * 2;
            buf[idx] = text.codePointAt(i)!;
            buf[idx + 1] = 51;
        }
    },
    { rows: 5, fps: 30, onExit: "preserve" },
);

loop.start();
```

Options:

* `rows` (default `10`)
* `fps` (default `60`)
* `onExit: 'preserve' | 'destroy'`

Current behavior: stopping the inline loop exits the process.

## Example Commands [#example-commands]

```bash
node --import @oxc-node/core/register examples-raw/ascii-3d.ts
node --import @oxc-node/core/register examples-raw/conway.ts
node --import @oxc-node/core/register examples-raw/fire.ts
node --import @oxc-node/core/register examples-raw/matrix.ts
node --import @oxc-node/core/register examples-raw/jitter.ts
node --import @oxc-node/core/register examples-raw/scope.ts
node --import @oxc-node/core/register examples-raw/plasma.ts
node --import @oxc-node/core/register examples-raw/inline-picker.ts
```


# Render Loop (/docs/packages/tui/render-loop)



# Ratatat Render Loop [#ratatat-render-loop]

> Part of the [Ratatat docs](/docs/packages/tui). See also: [Troubleshooting](/docs/packages/tui/troubleshooting) · [Architecture Decisions](/docs/packages/tui/decisions)

Ratatat uses a **game engine style render loop** to drive terminal output. This doc explains why, how it works, and how to tune it.

## The problem with push-based rendering [#the-problem-with-push-based-rendering]

The naive approach for a React terminal renderer is to paint whenever React commits:

```
React commit → resetAfterCommit() → paint()
```

This works for synchronous state updates triggered by user input. It breaks for timer-driven updates — `setTimeout`, `setInterval`, streaming responses, anything async. React 18's concurrent scheduler in Node.js uses `setImmediate` to batch and defer work. Between user input events, deferred commits pile up and never flush. State changes pile up silently and only appear on the next keypress.

`DiscreteEventPriority` doesn't fix it. Calling `paint()` synchronously from `resetAfterCommit` doesn't fix it reliably either. The scheduler's batching behavior is non-deterministic from the renderer's perspective.

## The solution: decouple state from painting [#the-solution-decouple-state-from-painting]

```
React commit → pendingCommit = true        (React just sets a flag)
setInterval(16ms) → if pendingCommit → paint()   (loop drives all painting)
```

Two independent systems:

**React** owns state. When it commits, it sets `pendingCommit = true`. That's its only job in the paint pipeline.

**The render loop** owns painting. It polls `pendingCommit` every `frameMs` and paints when set. It has no knowledge of React internals and doesn't care what triggered the state change.

## Why this is reliable [#why-this-is-reliable]

The `setInterval` is unconditional. It fires whether the state change came from:

* A keypress
* A `setTimeout` callback
* A `setInterval` tick
* A Promise resolution
* A streaming text update

React's scheduler batching is irrelevant — we're not asking React to drive the paint, we're polling it. Worst-case latency is one frame interval (16ms at 60fps), which is imperceptible in a terminal.

The `setInterval` also keeps the Node.js event loop alive between user inputs. Without it, the event loop could go idle and the `setImmediate`-scheduled React work would have nowhere to land.

## The game engine analogy [#the-game-engine-analogy]

A game engine separates the **update tick** (physics, AI, input) from the **render tick** (draw everything). The render tick doesn't wait for the update tick to say "paint now" — it runs at a fixed frequency and draws whatever the current state is.

Ratatat maps directly onto this model:

| Game engine  | Ratatat                                 |
| ------------ | --------------------------------------- |
| Update tick  | React (runs on events + timers)         |
| Render tick  | `setInterval` at `maxFps`               |
| Shared state | `pendingCommit` flag + Yoga layout tree |

The render tick is **pull-based**, not push-based. The loop pulls whenever it sees dirty state. That inversion is what makes it reliable.

## The paint path [#the-paint-path]

When `pendingCommit` is true, one synchronous call chain fires:

```
pendingCommit = true (set by resetAfterCommit)
        │
        ▼
setInterval tick (every frameMs)
        │
        ▼
app.paintNow(calcLayout, renderBuf)
        │
        ├── rootNode.calculateLayout(width, height)    ← Yoga layout
        ├── renderTreeToBuffer(rootNode, buffer, w, h)  ← TS buffer painter
        ├── onBeforeFlush listeners (optional)          ← direct buffer painting
        └── renderer.render(buffer)                    ← Rust diff + stdout write
```

`onBeforeFlush` listeners fire after React fills the buffer but before Rust sees it — the correct insertion point for animated graphs, overlays, or anything that paints directly into the `Uint32Array`. Register via `app.onBeforeFlush(fn)` which returns an unsubscribe function. Multiple listeners are supported.

Resize is handled outside the loop — `SIGWINCH` calls `paintNow()` directly for immediate response.

## CPU cost [#cpu-cost]

The loop runs every 16ms. On frames where nothing changed, the cost is:

1. Check `pendingCommit` — one boolean read, branch not taken
2. That's it

The Yoga layout, buffer paint, and Rust diff only run when `pendingCommit` is true. The Rust diff engine only writes ANSI bytes for cells that actually changed, so a frame where nothing visually changed produces zero terminal writes.

## Tuning with `maxFps` [#tuning-with-maxfps]

```ts
render(<App />, { maxFps: 30 })  // 33ms frame interval — half the CPU overhead
render(<App />, { maxFps: 60 })  // 16ms frame interval — default
render(<App />, { maxFps: 120 }) // 8ms frame interval — smoother animations
```

Lower `maxFps` reduces how often the loop wakes up. For apps without animation (static dashboards, prompts), `maxFps: 10` or even `maxFps: 4` is perfectly usable and costs almost nothing.

Higher `maxFps` reduces maximum paint latency for smooth streaming or animations.

## Where this lives in the code [#where-this-lives-in-the-code]

* `packages/react/src/react.ts` — render loop setup, `pendingCommit` flag, `frameMs` calculation
* `packages/core/src/app.ts` — `paintNow()` method: layout + buffer paint + Rust render
* `packages/react/src/reconciler.ts` — `resetAfterCommit` sets `pendingCommit = true`


# Renderer Correctness Plan (/docs/packages/tui/renderer-correctness-plan)



# Renderer correctness hardening (xterm harness → wide-char correctness → synchronized output) [#renderer-correctness-hardening-xterm-harness--wide-char-correctness--synchronized-output]

Status: &#x2A;*implemented on `main`** (March 2026).

This page keeps the original hardening plan plus what shipped.

## Goals (completed) [#goals-completed]

1. Add a terminal-accurate correctness harness (xterm-headless replay tests).
2. Fix wide character handling end-to-end (layout measure + raster + diff emission).
3. Add DEC 2026 synchronized output wrapping to reduce visual tearing.

***

## Phase 1 — xterm replay harness ✅ [#phase-1--xterm-replay-harness-]

Delivered:

* xterm-backed replay tests in `packages/react/__test__/renderer-xterm-roundtrip.spec.ts`
* deterministic round-trip tests for incremental diff replay
* randomized ASCII smoke coverage

Outcome:

* Renderer diffs are now validated against a real terminal model, not just string snapshots.

***

## Phase 2 — wide-char correctness ✅ [#phase-2--wide-char-correctness-]

Delivered:

* width-aware measurement in `packages/react/src/layout.ts` via `packages/react/src/text-width.ts`
* width-aware rasterization in `packages/react/src/renderer.ts`
  * wide glyph cursor advancement by display width
  * explicit continuation-cell marker (`0x110000` sentinel)
* width-aware diff cursor progression in `packages/core/src/lib.rs`
* targeted tests for CJK/emoji continuation behavior and replay correctness

Outcome:

* CJK and emoji rendering/diff behavior is significantly more stable and deterministic.

***

## Phase 3 — DEC 2026 synchronized output ✅ [#phase-3--dec-2026-synchronized-output-]

Delivered:

* frame writes wrapped in `\x1b[?2026h` / `\x1b[?2026l` in:
  * `packages/core/src/app.ts`
  * `packages/core/src/inline.ts`
* tests asserting synchronized output wrappers in frame paths

Outcome:

* reduced visible tearing/flicker on terminals that support synchronized updates.

***

## Current verification checklist [#current-verification-checklist]

* [x] `npm run build`
* [x] `npm test`
* [x] focused renderer and replay tests
* [x] `cargo test`

***

## Remaining gaps (intentional) [#remaining-gaps-intentional]

* Full grapheme-cluster layout/render handling for complex ZWJ emoji sequences
* Broader fuzz/property coverage across mixed Unicode categories
* Additional terminal-emulator matrix validation beyond xterm-headless


# Rendering Modes (/docs/packages/tui/rendering-modes)



# Rendering Modes [#rendering-modes]

`@visulima/tui` supports three runtime modes.

## React Mode [#react-mode]

Use when you want component-driven terminal apps with hooks and Yoga layout.

```tsx
import { render } from "@visulima/tui/react";

render(<App />);
```

What you get:

* React components and hooks
* Yoga flex layout
* Focus management (Tab/Shift+Tab)
* Alternate screen lifecycle
* Resize handling (`SIGWINCH`)

Guide: [Quickstart: React Mode](/docs/packages/tui/quickstart-react)

## Raw-Buffer Mode [#raw-buffer-mode]

Use when you want direct control over every cell.

```ts
import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";

const { cols, rows } = terminalSize();
const guard = new TerminalGuard();
const renderer = new Renderer(cols, rows);
const buf = new Uint32Array(cols * rows * 2);

renderer.render(buf);
```

What you get:

* Direct `Uint32Array` painting
* Rust diff engine output
* No React/Yoga overhead
* Alternate screen lifecycle

Guide: [Quickstart: Raw-Buffer Mode](/docs/packages/tui/quickstart-raw-buffer)

## Inline Mode [#inline-mode]

Use when you want a fixed-height region below the current cursor (no alternate screen takeover).

### `renderInline()` [#renderinline]

```tsx
import { renderInline } from "@visulima/tui/react";

renderInline(<Picker />, { rows: 8, onExit: "preserve" });
```

### `createInlineLoop()` [#createinlineloop]

```ts
import { createInlineLoop } from "@visulima/tui/core";

const loop = createInlineLoop(
    (buf, cols, rows, frame) => {
        // paint frame
    },
    { rows: 8, fps: 30, onExit: "preserve" },
);

loop.start();
```

Notes:

* Inline mode preserves normal scrollback behavior.
* `onExit: 'preserve'` keeps rendered lines; `onExit: 'destroy'` clears the region.
* Current implementation exits the process when the inline loop stops.

Guide: [Raw Buffer API](/docs/packages/tui/raw-buffer#inline-mode-createinlineloop)

## Quick Comparison [#quick-comparison]

| Capability        | React mode | Raw-buffer mode | Inline mode |
| ----------------- | ---------- | --------------- | ----------- |
| Alternate screen  | ✅          | ✅               | ❌           |
| Yoga layout       | ✅          | ❌               | optional    |
| React hooks       | ✅          | ❌               | optional    |
| Direct cell paint | indirect   | direct          | direct      |


# Scroll Components (/docs/packages/tui/scroll)



























# Scroll Components [#scroll-components]

`@visulima/tui` provides two approaches to scrolling:

1. **CSS-level scrolling** via `Box` props (`overflow="scroll"`, `scrollTop`, `sticky`) — integrated into the layout engine with native scrollbar rendering and sticky header support. See the [Box component docs](/docs/packages/tui/components#overflow-and-css-level-scrolling).
2. **Component-based scrolling** via `ScrollView`, `ScrollList`, etc. — higher-level React components with imperative APIs, selection management, and alignment modes.

### When to use which [#when-to-use-which]

| Feature                         | Box `overflow="scroll"`                       | `ScrollView` component                                       |
| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| **Scrollbar**                   | Built-in (`scrollbar` prop, on by default)    | Built-in (`scrollbar` prop)                                  |
| **Scroll position**             | You manage via `scrollTop`/`scrollLeft` props | Managed internally, control via ref (`scrollBy`, `scrollTo`) |
| **Keyboard navigation**         | You handle via `useInput`                     | Built-in (`keyboard` prop, optional `vimBindings`)           |
| **Sticky headers**              | Yes (`sticky` prop on children)               | No                                                           |
| **Selection tracking**          | No                                            | Yes (via `ScrollList` with `selectedIndex`)                  |
| **Follow output (log tailing)** | No                                            | Yes (`followOutput` prop)                                    |
| **Virtualization**              | No                                            | Yes (`virtualize` prop)                                      |
| **Reach callbacks**             | No                                            | Yes (`onReachEnd`/`onReachStart`)                            |
| **Best for**                    | Simple overflow with sticky headers           | Lists, dynamic content, keyboard-driven UIs                  |

> **Important:** These are separate scroll systems. Do not nest `ScrollView` inside a `Box` with
> `overflow="scroll"` — the Box scrollbar will not reflect ScrollView's scroll position because
> they track scroll state independently. Use one or the other, not both.

## Component-Based Scroll [#component-based-scroll]

Ported from the [ByteLand](https://github.com/ByteLandTechnology) scroll ecosystem. Import from `@visulima/tui`.

```tsx
import { ControlledScrollView } from "@visulima/tui/components/controlled-scroll-view";
import { ScrollBar } from "@visulima/tui/components/scroll-bar";
import { ScrollBarBox } from "@visulima/tui/components/scroll-bar-box";
import { ScrollList } from "@visulima/tui/components/scroll-list";
import { ScrollView } from "@visulima/tui/components/scroll-view";
```

## `ScrollView` [#scrollview]

A scrollable viewport that manages its own scroll state. Control it imperatively via a ref.

<img alt="Scrolling Demo" src="__img0" />

```tsx
import { useRef } from "react";
import { Box } from "@visulima/tui/components/box";
import { ScrollView } from "@visulima/tui/components/scroll-view";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
import type { ScrollViewRef } from "@visulima/tui/components/scroll-view";
const Demo = () => {
    const scrollRef = useRef<ScrollViewRef>(null);

    useInput((input, key) => {
        if (key.downArrow) scrollRef.current?.scrollBy(1);
        if (key.upArrow) scrollRef.current?.scrollBy(-1);
    });

    return (
        <Box height={10} borderStyle="single">
            <ScrollView ref={scrollRef}>
                {items.map((item) => (
                    <Text key={item.id}>{item.label}</Text>
                ))}
            </ScrollView>
        </Box>
    );
};
```

### Dynamic Items [#dynamic-items]

<img alt="Dynamic Items Demo" src="__img1" />

### Expand / Collapse [#expand--collapse]

<img alt="Expand Demo" src="__img2" />

### Terminal Resize [#terminal-resize]

<img alt="Resize Demo" src="__img3" />

### Width Changes (Text Wrapping) [#width-changes-text-wrapping]

<img alt="Width Demo" src="__img4" />

### Props [#props]

Extends `BoxProps`.

| Prop                    | Type       | Description                                                                 |
| ----------------------- | ---------- | --------------------------------------------------------------------------- |
| `onScroll`              | `function` | Callback with current scroll offset                                         |
| `onViewportSizeChange`  | `function` | Fires when viewport dimensions change                                       |
| `onContentHeightChange` | `function` | Fires when total content height changes                                     |
| `onItemHeightChange`    | `function` | Fires when an individual item resizes                                       |
| `debug`                 | `boolean`  | Disables overflow hidden for debugging                                      |
| `keyboard`              | `boolean`  | Enable built-in keyboard navigation (default: `false`)                      |
| `vimBindings`           | `boolean`  | Enable vim-style keys j/k/g/G/u/d (requires `keyboard`, default: `false`)   |
| `followOutput`          | `boolean`  | Auto-scroll to bottom when content grows (default: `false`)                 |
| `followThreshold`       | `number`   | Lines from bottom that count as "at bottom" for followOutput (default: `3`) |
| `onReachEnd`            | `function` | Fires once when scrolled within `reachThreshold` of the end                 |
| `onReachStart`          | `function` | Fires once when scrolled within `reachThreshold` of the start               |
| `reachThreshold`        | `number`   | Distance in lines to trigger reach callbacks (default: `5`)                 |
| `scrollbar`             | `boolean`  | Show a scrollbar when content overflows (default: `false`)                  |
| `scrollbarColor`        | `string`   | Color of the scrollbar thumb and track                                      |
| `virtualize`            | `boolean`  | Only render visible items + overscan (default: `false`)                     |
| `overscan`              | `number`   | Extra items to render outside viewport when virtualized (default: `3`)      |

### Ref Methods [#ref-methods]

| Method                | Description                          |
| --------------------- | ------------------------------------ |
| `scrollTo(offset)`    | Scroll to absolute position          |
| `scrollBy(delta)`     | Scroll by relative amount            |
| `scrollToTop()`       | Scroll to top                        |
| `scrollToBottom()`    | Scroll to bottom                     |
| `getScrollOffset()`   | Current scroll position              |
| `getContentHeight()`  | Total content height                 |
| `getViewportHeight()` | Visible viewport height              |
| `getBottomOffset()`   | Max scroll offset                    |
| `getItemHeight(i)`    | Height of item at index              |
| `getItemPosition(i)`  | Position and height of item at index |
| `remeasure()`         | Re-measure viewport dimensions       |
| `remeasureItem(i)`    | Re-measure a specific child          |

## `ControlledScrollView` [#controlledscrollview]

Lower-level variant where the parent owns the `scrollOffset` state.

```tsx
import { useState } from "react";
import { Box } from "@visulima/tui/components/box";
import { ControlledScrollView } from "@visulima/tui/components/controlled-scroll-view";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
const Demo = () => {
    const [offset, setOffset] = useState(0);

    useInput((input, key) => {
        if (key.downArrow) setOffset((o) => o + 1);
        if (key.upArrow) setOffset((o) => Math.max(0, o - 1));
    });

    return (
        <Box height={10} borderStyle="single">
            <ControlledScrollView scrollOffset={offset}>
                {items.map((item) => (
                    <Text key={item.id}>{item.label}</Text>
                ))}
            </ControlledScrollView>
        </Box>
    );
};
```

## `ScrollBar` [#scrollbar]

A visual scroll position indicator. Works in two placement modes:

* **Border mode** (`placement="left"` or `"right"`): Integrates with a container's border.
* **Inset mode** (`placement="inset"`): Placed inside the content area.

### Border Mode [#border-mode]

<img alt="Border Mode Demo" src="__img5" />

### Inset Mode [#inset-mode]

<img alt="Inset Mode Demo" src="__img6" />

### Auto Hide [#auto-hide]

<img alt="Auto Hide Demo" src="__img7" />

```tsx
import { Box } from "@visulima/tui/components/box";
import { ScrollBar } from "@visulima/tui/components/scroll-bar";
import { Text } from "@visulima/tui/components/text";
<Box flexDirection="row">
    <Box borderStyle="single" borderRight={false} height={10}>
        <Text>Content here</Text>
    </Box>
    <ScrollBar placement="right" style="single" contentHeight={100} viewportHeight={10} scrollOffset={scrollOffset} />
</Box>;
```

### Props [#props-1]

| Prop             | Type                 | Default   | Description                         |
| ---------------- | -------------------- | --------- | ----------------------------------- |
| `contentHeight`  | `number`             | required  | Total content height                |
| `viewportHeight` | `number`             | required  | Visible viewport height             |
| `scrollOffset`   | `number`             | required  | Current scroll position             |
| `placement`      | `ScrollBarPlacement` | `'right'` | `'left'`, `'right'`, or `'inset'`   |
| `style`          | `ScrollBarStyle`     | varies    | Visual style                        |
| `thumbChar`      | `string`             | ---       | Custom thumb character (inset only) |
| `trackChar`      | `string`             | ---       | Custom track character (inset only) |
| `autoHide`       | `boolean`            | `false`   | Hide when content fits (inset only) |
| `color`          | `string`             | ---       | Scroll bar color                    |
| `dimColor`       | `boolean`            | `false`   | Dimmed styling                      |

## `ScrollBarBox` [#scrollbarbox]

A `Box` with a built-in scroll bar on one border.

```tsx
import { ScrollBarBox } from "@visulima/tui/components/scroll-bar-box";
import { Text } from "@visulima/tui/components/text";
<ScrollBarBox height={12} borderStyle="single" contentHeight={50} viewportHeight={10} scrollOffset={scrollOffset}>
    {visibleItems.map((item) => (
        <Text key={item.id}>{item.label}</Text>
    ))}
</ScrollBarBox>;
```

### Props [#props-2]

Extends `BoxProps`.

| Prop                | Type                | Default   | Description                  |
| ------------------- | ------------------- | --------- | ---------------------------- |
| `contentHeight`     | `number`            | required  | Total content height         |
| `viewportHeight`    | `number`            | required  | Visible viewport height      |
| `scrollOffset`      | `number`            | required  | Current scroll position      |
| `scrollBarPosition` | `'left' \| 'right'` | `'right'` | Which side to show the bar   |
| `scrollBarAutoHide` | `boolean`           | `false`   | Hide thumb when content fits |
| `thumbChar`         | `string`            | ---       | Custom thumb character       |

## `ScrollList` [#scrolllist]

A `ScrollView` with externally controlled selection and automatic scroll-into-view.

### Selection & Navigation [#selection--navigation]

<img alt="Selection Demo" src="__img8" />

### Scroll Alignment Modes [#scroll-alignment-modes]

<img alt="Alignment Demo" src="__img9" />

### Expand / Collapse [#expand--collapse-1]

<img alt="Expand Demo" src="__img10" />

### Dynamic Items [#dynamic-items-1]

<img alt="Dynamic Demo" src="__img11" />

```tsx
import { useRef, useState } from "react";
import { Box } from "@visulima/tui/components/box";
import { ScrollList } from "@visulima/tui/components/scroll-list";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
const Demo = () => {
    const [selected, setSelected] = useState(0);
    const items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];

    useInput((input, key) => {
        if (key.downArrow) setSelected((i) => Math.min(i + 1, items.length - 1));
        if (key.upArrow) setSelected((i) => Math.max(i - 1, 0));
    });

    return (
        <ScrollList height={5} selectedIndex={selected}>
            {items.map((item, i) => (
                <Box key={i}>
                    <Text color={i === selected ? "blue" : "white"}>
                        {i === selected ? "> " : "  "}
                        {item}
                    </Text>
                </Box>
            ))}
        </ScrollList>
    );
};
```

### Props [#props-3]

Extends `ScrollViewProps`.

| Prop              | Type              | Default  | Description                               |
| ----------------- | ----------------- | -------- | ----------------------------------------- |
| `selectedIndex`   | `number`          | ---      | Currently selected item (controlled)      |
| `scrollAlignment` | `ScrollAlignment` | `'auto'` | How to position the selected item in view |

Alignment modes:

* `'auto'` --- Minimal scrolling to bring item into view
* `'top'` --- Align item to top of viewport
* `'bottom'` --- Align item to bottom of viewport
* `'center'` --- Center item in viewport

## Keyboard Navigation [#keyboard-navigation]

Enable built-in keyboard controls on any `ScrollView` or `ScrollList` with the `keyboard` prop:

```tsx
<ScrollView keyboard height={20}>
    {items.map((item) => (
        <Text key={item.id}>{item.label}</Text>
    ))}
</ScrollView>
```

**Default key bindings:**

| Key           | Action                    |
| ------------- | ------------------------- |
| Arrow Up/Down | Scroll by 1 line          |
| Page Up/Down  | Scroll by viewport height |
| Home/End      | Jump to top/bottom        |
| Ctrl+U/D      | Half-page scroll          |

**Vim bindings** (add `vimBindings` prop):

```tsx
<ScrollView keyboard vimBindings height={20}>
    ...
</ScrollView>
```

| Key     | Action            |
| ------- | ----------------- |
| `j`/`k` | Scroll down/up    |
| `G`     | Jump to bottom    |
| `g`     | Jump to top       |
| `u`/`d` | Half-page up/down |

The `useScrollInput` hook is also available for custom scroll containers:

```tsx
import { useScrollInput } from "@visulima/tui/hooks/use-scroll-input";
useScrollInput({
    scrollBy: (delta) => ref.current?.scrollBy(delta),
    scrollToTop: () => ref.current?.scrollToTop(),
    scrollToBottom: () => ref.current?.scrollToBottom(),
    viewportHeight: 20,
    vimBindings: true,
});
```

## Auto-Follow (Log Tailing) [#auto-follow-log-tailing]

Keep a ScrollView pinned to the bottom as content grows — useful for log viewers:

```tsx
<ScrollView followOutput height={20}>
    {logLines.map((line, i) => (
        <Text key={i}>{line}</Text>
    ))}
</ScrollView>
```

When `followOutput` is enabled:

* If the user is at/near the bottom, new content auto-scrolls to stay at the bottom
* If the user scrolls up, auto-follow pauses
* Scrolling back to the bottom resumes auto-follow

Adjust `followThreshold` (default 3) to control how many lines from the bottom still counts as "at bottom".

## Infinite Scroll Callbacks [#infinite-scroll-callbacks]

Detect when the user scrolls near the edges for lazy loading:

```tsx
<ScrollView height={20} onReachEnd={() => loadMoreItems()} onReachStart={() => loadPreviousItems()} reachThreshold={5}>
    {items.map((item) => (
        <Text key={item.id}>{item.label}</Text>
    ))}
</ScrollView>
```

Callbacks fire once per entry into the threshold zone and don't re-fire until the user scrolls away and back.

## Linked Scroll [#linked-scroll]

Synchronize scroll position across multiple ScrollView instances (e.g., diff viewers, multi-pane layouts):

```tsx
import { ScrollView } from "@visulima/tui/components/scroll-view";
import { Text } from "@visulima/tui/components/text";
import { createLinkedScrollGroup } from "@visulima/tui/hooks/use-linked-scroll";
const group = createLinkedScrollGroup();

const LeftPane = () => {
    const { ref, onScroll } = group.useLinkedScroll();

    return (
        <ScrollView ref={ref} onScroll={onScroll} height={20}>
            {leftItems.map((item) => (
                <Text key={item.id}>{item.label}</Text>
            ))}
        </ScrollView>
    );
};

const RightPane = () => {
    const { ref, onScroll } = group.useLinkedScroll();

    return (
        <ScrollView ref={ref} onScroll={onScroll} height={20}>
            {rightItems.map((item) => (
                <Text key={item.id}>{item.label}</Text>
            ))}
        </ScrollView>
    );
};
```

Scrolling one pane automatically scrolls all others in the same group.

## Virtualization [#virtualization]

For large lists, enable virtualization to only render items visible in the viewport:

```tsx
<ScrollView virtualize overscan={5} height={20}>
    {thousandsOfItems.map((item) => (
        <Text key={item.id}>{item.label}</Text>
    ))}
</ScrollView>
```

* Items are measured on first render, then only visible items (plus `overscan` buffer) are rendered
* Spacer elements maintain correct scroll position and content height
* Works with all other ScrollView features (keyboard, followOutput, etc.)


# Testing (/docs/packages/tui/testing)



# Testing [#testing]

`@visulima/tui/test` provides a framework-agnostic testing utility for TUI components. It renders components into mock stdout/stderr/stdin streams so you can assert on output without a real terminal.

Inspired by [ink-testing-library](https://github.com/vadimdemedes/ink-testing-library).

## Install [#install]

The testing utilities are included in the main package — no extra install needed:

```bash npm2yarn
npm install @visulima/tui react
```

## Quick Start [#quick-start]

```tsx
import { afterEach, describe, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

describe("my component", () => {
    it("renders greeting", () => {
        const { lastFrame } = render(<Text>Hello World</Text>);

        expect(lastFrame()).toBe("Hello World");
    });
});
```

## API [#api]

### `render(node, options?)` [#rendernode-options]

Renders a React element for testing with mock streams. The component renders synchronously into an in-memory buffer — no real terminal is involved.

```tsx
import { render } from "@visulima/tui/test";

const instance = render(<MyComponent />);
```

**Parameters:**

| Parameter         | Type            | Description                                           |
| ----------------- | --------------- | ----------------------------------------------------- |
| `node`            | `ReactElement`  | The React element to render                           |
| `options.columns` | `number`        | Terminal column width for mock streams (default: 100) |
| `options.options` | `RenderOptions` | Additional render options passed to the renderer      |

**Returns:** `TestInstance`

| Property    | Type                                     | Description                                         |
| ----------- | ---------------------------------------- | --------------------------------------------------- |
| `lastFrame` | `() => string \| undefined`              | Most recently rendered stdout frame                 |
| `frames`    | `readonly string[]`                      | All captured stdout frames                          |
| `screen`    | `Screen`                                 | Query helpers with built-in ANSI stripping          |
| `keys`      | `KeySender`                              | Named key methods for simulating keyboard input     |
| `flush`     | `() => Promise<void>`                    | Wait for pending React renders to commit            |
| `waitFor`   | `(condition, options?) => Promise<void>` | Async polling assertion                             |
| `rerender`  | `(node: ReactElement) => void`           | Replace the rendered component                      |
| `unmount`   | `() => void`                             | Unmount the component                               |
| `cleanup`   | `() => void`                             | Unmount and clean up resources                      |
| `stdout`    | `TestInstanceStdout`                     | Mock stdout with `lastFrame()`, `frames`, `write()` |
| `stderr`    | `TestInstanceStderr`                     | Mock stderr with `lastFrame()`, `frames`, `write()` |
| `stdin`     | `TestInstanceStdin`                      | Mock stdin with `write()` for simulating input      |

### `cleanup()` [#cleanup]

Unmounts and cleans up all rendered test instances. Call this in your test teardown to prevent leaks between tests.

```tsx
import { cleanup } from "@visulima/tui/test";

afterEach(() => {
    cleanup();
});
```

### `screen` [#screen]

The `screen` property on a test instance provides query helpers that automatically strip ANSI escape codes. No need to manually import a strip utility for assertions.

| Method          | Return     | Description                                        |
| --------------- | ---------- | -------------------------------------------------- |
| `text()`        | `string`   | Last frame with ANSI codes stripped                |
| `rawText()`     | `string`   | Last frame with ANSI codes preserved               |
| `contains(str)` | `boolean`  | Whether the current screen contains the given text |
| `matches(re)`   | `boolean`  | Whether the current screen matches a regex         |
| `line(n)`       | `string`   | Get a specific line by zero-based index            |
| `lines()`       | `string[]` | All non-empty lines                                |
| `frames()`      | `string[]` | All captured frames (ANSI-stripped)                |
| `rawFrames()`   | `string[]` | All captured frames (raw)                          |

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("queries screen content", () => {
    const { screen } = render(
        <Box flexDirection="column">
            <Text color="green">Hello</Text>
            <Text>World</Text>
        </Box>,
    );

    // ANSI codes are stripped automatically
    expect(screen.text()).toContain("Hello");
    expect(screen.contains("World")).toBe(true);
    expect(screen.matches(/Hello/)).toBe(true);
    expect(screen.line(0)).toBe("Hello");
    expect(screen.lines()).toEqual(["Hello", "World"]);
});
```

You can also use `createScreen` standalone if you need screen helpers outside of `render()`:

```tsx
import { createScreen } from "@visulima/tui/test";

const screen = createScreen(() => someLastFrame(), allFrames);
```

### `keys` (KeySender) [#keys-keysender]

The `keys` property provides named methods for simulating keyboard input — no need to memorize ANSI escape sequences.

| Method        | Description                          |
| ------------- | ------------------------------------ |
| `enter()`     | Press Enter / Return                 |
| `escape()`    | Press Escape                         |
| `tab()`       | Press Tab                            |
| `backspace()` | Press Backspace                      |
| `delete()`    | Press Delete                         |
| `up()`        | Press Up arrow                       |
| `down()`      | Press Down arrow                     |
| `left()`      | Press Left arrow                     |
| `right()`     | Press Right arrow                    |
| `space()`     | Press Space                          |
| `pageUp()`    | Press Page Up                        |
| `pageDown()`  | Press Page Down                      |
| `home()`      | Press Home                           |
| `end()`       | Press End                            |
| `type(text)`  | Type a string character by character |
| `press(char)` | Send a single character              |
| `raw(data)`   | Send arbitrary raw data to stdin     |

```tsx
import React, { useState } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
afterEach(() => {
    cleanup();
});

const Menu = () => {
    const [selected, setSelected] = useState(0);
    const items = ["Apple", "Banana", "Cherry"];

    useInput((_input, key) => {
        if (key.downArrow) {
            setSelected((prev) => Math.min(prev + 1, items.length - 1));
        }
        if (key.upArrow) {
            setSelected((prev) => Math.max(prev - 1, 0));
        }
    });

    return <Text>{items[selected]}</Text>;
};

it("navigates with named key methods", () => {
    const { keys, screen } = render(<Menu />);

    expect(screen.text()).toBe("Apple");

    keys.down();
    expect(screen.text()).toBe("Banana");

    keys.down();
    expect(screen.text()).toBe("Cherry");

    keys.up();
    expect(screen.text()).toBe("Banana");
});
```

#### `KEY` Constants [#key-constants]

The `KEY` object exports the raw ANSI escape sequences if you need them directly:

```tsx
import { KEY } from "@visulima/tui/test";

// KEY.return  → "\r"
// KEY.escape  → "\x1B"
// KEY.up      → "\x1B[A"
// KEY.down    → "\x1B[B"
// KEY.left    → "\x1B[D"
// KEY.right   → "\x1B[C"
// KEY.tab     → "\t"
// KEY.backspace → "\x7F"
// KEY.delete  → "\x1B[3~"
// KEY.space   → " "
// KEY.ctrlC   → "\x03"
// KEY.pageUp  → "\x1B[5~"
// KEY.pageDown → "\x1B[6~"
// KEY.home    → "\x1B[H"
// KEY.end     → "\x1B[F"
```

### `waitFor(condition, options?)` [#waitforcondition-options]

Async polling assertion inspired by [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-async/#waitfor). Useful for testing async components that update over time.

**Parameters:**

| Parameter          | Type                   | Description                                           |
| ------------------ | ---------------------- | ----------------------------------------------------- |
| `condition`        | `string \| () => void` | Text to wait for, or callback that throws until ready |
| `options.timeout`  | `number`               | Max wait time in ms (default: 3000)                   |
| `options.interval` | `number`               | Polling interval in ms (default: 50)                  |

If `condition` is a **string**, waits until the screen contains it. If `condition` is a **function**, waits until it stops throwing (like React Testing Library's `waitFor`).

```tsx
import React, { useEffect, useState } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

const AsyncGreeting = () => {
    const [message, setMessage] = useState("Loading...");

    useEffect(() => {
        const timer = setTimeout(() => setMessage("Hello!"), 100);
        return () => clearTimeout(timer);
    }, []);

    return <Text>{message}</Text>;
};

it("waits for text to appear (string condition)", async () => {
    const instance = render(<AsyncGreeting />);

    await instance.waitFor("Hello!");
    expect(instance.screen.text()).toBe("Hello!");
});

it("waits for assertion to pass (callback condition)", async () => {
    const instance = render(<AsyncGreeting />);

    await instance.waitFor(() => {
        expect(instance.screen.text()).toBe("Hello!");
    });
});
```

You can also use `waitFor` as a standalone function:

```tsx
import { waitFor } from "@visulima/tui/test";

await waitFor("expected text", () => screen.text(), { timeout: 5000 });
```

### `flush()` [#flush]

Awaits two microtick delays, giving React time to commit pending renders before your assertions run. Useful when testing components that update asynchronously within the same tick.

```tsx
it("flushes pending renders", async () => {
    const { keys, screen, flush } = render(<MyInput />);

    keys.type("hello");
    await flush();

    expect(screen.text()).toContain("hello");
});
```

## Examples [#examples]

### Rendering a component [#rendering-a-component]

The simplest use case — render a component and check its output:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("renders a greeting", () => {
    const { lastFrame } = render(<Text>Hello World</Text>);

    expect(lastFrame()).toBe("Hello World");
});

it("renders nested layout", () => {
    const { lastFrame } = render(
        <Box flexDirection="column">
            <Text>Line 1</Text>
            <Text>Line 2</Text>
        </Box>,
    );

    expect(lastFrame()).toContain("Line 1");
    expect(lastFrame()).toContain("Line 2");
});
```

### Rerendering with new props [#rerendering-with-new-props]

Use `rerender()` to update the component with new props and verify the output changes:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

const Counter = ({ count }: { count: number }) => <Text>Count: {count}</Text>;

it("updates on rerender", () => {
    const { lastFrame, rerender } = render(<Counter count={0} />);

    expect(lastFrame()).toBe("Count: 0");

    rerender(<Counter count={1} />);

    expect(lastFrame()).toBe("Count: 1");

    rerender(<Counter count={42} />);

    expect(lastFrame()).toBe("Count: 42");
});
```

### Inspecting render history with frames [#inspecting-render-history-with-frames]

Every render produces a frame. Use `frames` to inspect the full render history:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("tracks all rendered frames", () => {
    const { frames, rerender } = render(<Text>Frame 1</Text>);

    rerender(<Text>Frame 2</Text>);
    rerender(<Text>Frame 3</Text>);

    expect(frames[0]).toBe("Frame 1");
    expect(frames.at(-1)).toBe("Frame 3");
    expect(frames.length).toBeGreaterThanOrEqual(3);
});
```

### Simulating keyboard input [#simulating-keyboard-input]

Use `stdin.write()` to simulate user input. This works with components that use `useInput`:

```tsx
import React, { useState } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
afterEach(() => {
    cleanup();
});

const InputEcho = () => {
    const [text, setText] = useState("");

    useInput((input) => {
        setText((prev) => prev + input);
    });

    return <Text>{text || "Type something..."}</Text>;
};

it("receives keyboard input", () => {
    const { stdin, lastFrame } = render(<InputEcho />);

    expect(lastFrame()).toBe("Type something...");

    stdin.write("h");
    stdin.write("i");

    expect(lastFrame()).toBe("hi");
});
```

### Simulating special keys [#simulating-special-keys]

Use the `keys` helper for named key methods — no escape sequences to remember:

```tsx
import React, { useState } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
import { useInput } from "@visulima/tui/hooks/use-input";
afterEach(() => {
    cleanup();
});

const Menu = () => {
    const [selected, setSelected] = useState(0);
    const items = ["Apple", "Banana", "Cherry"];

    useInput((_input, key) => {
        if (key.downArrow) {
            setSelected((prev) => Math.min(prev + 1, items.length - 1));
        }
        if (key.upArrow) {
            setSelected((prev) => Math.max(prev - 1, 0));
        }
    });

    return <Text>{items[selected]}</Text>;
};

it("navigates with arrow keys", () => {
    const { keys, screen } = render(<Menu />);

    expect(screen.text()).toBe("Apple");

    keys.down();
    expect(screen.text()).toBe("Banana");

    keys.down();
    expect(screen.text()).toBe("Cherry");

    keys.up();
    expect(screen.text()).toBe("Banana");
});
```

You can also use raw escape sequences via `stdin.write()` or `keys.raw()` if needed:

```tsx
stdin.write("\u001B[B"); // Down arrow: ESC [ B
keys.raw("\u001B[A"); // Up arrow: ESC [ A
```

### Testing components that exit [#testing-components-that-exit]

Components that call `useApp().exit()` can be tested by awaiting `waitUntilExit` on the underlying instance:

```tsx
import React, { useEffect } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
import { useApp } from "@visulima/tui/hooks/use-app";
afterEach(() => {
    cleanup();
});

const AutoExit = ({ message }: { message: string }) => {
    const { exit } = useApp();

    useEffect(() => {
        exit();
    }, [exit]);

    return <Text>{message}</Text>;
};

it("renders and exits", () => {
    const { lastFrame } = render(<AutoExit message="Done!" />);

    expect(lastFrame()).toContain("Done!");
});
```

### Capturing stderr output [#capturing-stderr-output]

Components that write to stderr (via `useStderr`) have their output captured in a separate stream:

```tsx
import React, { useEffect } from "react";
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
import { useStderr } from "@visulima/tui/hooks/use-stderr";
afterEach(() => {
    cleanup();
});

const Logger = () => {
    const { write } = useStderr();

    useEffect(() => {
        write("Warning: something happened");
    }, [write]);

    return <Text>All good</Text>;
};

it("captures stderr separately", () => {
    const { lastFrame, stderr } = render(<Logger />);

    expect(lastFrame()).toBe("All good");
    expect(stderr.lastFrame()).toBe("Warning: something happened");
});
```

### Stripping ANSI codes for assertions [#stripping-ansi-codes-for-assertions]

When components use colors or styles, the output contains ANSI escape sequences. The `screen` helper strips ANSI automatically:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("renders colored text", () => {
    const { screen } = render(<Text color="green">Success</Text>);

    // screen.text() strips ANSI codes automatically
    expect(screen.text()).toBe("Success");

    // screen.rawText() preserves ANSI codes if needed
    expect(screen.rawText()).toContain("\u001B[");
});
```

You can also use `@visulima/ansi` directly with `lastFrame()` if you prefer:

```tsx
import { strip } from "@visulima/ansi";

const { lastFrame } = render(<Text color="green">Success</Text>);
expect(strip(lastFrame()!)).toBe("Success");
```

### Custom terminal width [#custom-terminal-width]

Pass `columns` to control the virtual terminal width. This affects text wrapping and layout:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("wraps text in narrow terminal", () => {
    const { lastFrame } = render(
        <Box width={20}>
            <Text>This is a long line that should wrap</Text>
        </Box>,
        { columns: 20 },
    );

    const output = lastFrame()!;
    const lines = output.split("\n");

    expect(lines.length).toBeGreaterThan(1);
});
```

### Testing multiple independent instances [#testing-multiple-independent-instances]

Each `render()` call creates an isolated instance with its own streams:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("renders multiple isolated instances", () => {
    const a = render(<Text>Instance A</Text>);
    const b = render(<Text>Instance B</Text>);

    expect(a.lastFrame()).toBe("Instance A");
    expect(b.lastFrame()).toBe("Instance B");

    // Rerendering one doesn't affect the other
    a.rerender(<Text>Updated A</Text>);

    expect(a.lastFrame()).toBe("Updated A");
    expect(b.lastFrame()).toBe("Instance B");
});
```

### Unmounting and lifecycle [#unmounting-and-lifecycle]

Use `unmount()` for a single instance or `cleanup()` for all instances:

```tsx
import { afterEach, expect, it } from "vitest";
import { cleanup, render } from "@visulima/tui/test";
import { Text } from "@visulima/tui/components/text";
afterEach(() => {
    cleanup();
});

it("unmounts a single instance", () => {
    const { lastFrame, unmount } = render(<Text>Hello</Text>);

    expect(lastFrame()).toBe("Hello");

    unmount();

    // After unmount, the renderer writes a final empty frame
    expect(lastFrame()).toBe("\n");
});

it("cleanup unmounts all instances", () => {
    render(<Text>One</Text>);
    render(<Text>Two</Text>);
    render(<Text>Three</Text>);

    // cleanup() unmounts all three at once
    cleanup();
});
```

## Common ANSI Escape Sequences for stdin [#common-ansi-escape-sequences-for-stdin]

When simulating special keys via `stdin.write()`, use these escape sequences:

| Key         | Escape sequence | Code            |
| ----------- | --------------- | --------------- |
| Enter       | `\r`            | Carriage return |
| Escape      | `\u001B`        | ESC             |
| Up arrow    | `\u001B[A`      | ESC \[ A        |
| Down arrow  | `\u001B[B`      | ESC \[ B        |
| Right arrow | `\u001B[C`      | ESC \[ C        |
| Left arrow  | `\u001B[D`      | ESC \[ D        |
| Tab         | `\t`            | HT              |
| Backspace   | `\u007F`        | DEL             |
| Delete      | `\u001B[3~`     | ESC \[ 3 \~     |
| Space       | ` `             | Space           |
| Ctrl+C      | `\u0003`        | ETX             |

## Works With Any Test Runner [#works-with-any-test-runner]

The testing utilities use plain `EventEmitter`-based mock streams with no test framework dependencies. They work with Vitest, Jest, Node.js built-in test runner, or any other framework:

```ts
// Vitest
import { afterEach } from "vitest";
import { cleanup } from "@visulima/tui/test";
afterEach(() => cleanup());

// Jest
afterEach(() => {
    const { cleanup } = require("@visulima/tui/test");
    cleanup();
});

// Node.js test runner
import { afterEach } from "node:test";
import { cleanup } from "@visulima/tui/test";
afterEach(() => cleanup());
```

## Tips [#tips]

* Always call `cleanup()` in `afterEach` to avoid state leaks between tests
* Use `screen.text()` for ANSI-stripped assertions, `lastFrame()` for raw output
* Use `screen.contains()` and `screen.matches()` for quick boolean checks
* Use `keys.down()`, `keys.enter()`, etc. instead of memorizing escape sequences
* Use `keys.type("text")` to simulate typing a string character by character
* Use `waitFor("text")` or `waitFor(() => expect(...))` for async component testing
* Use `flush()` after input simulation to let React commit pending renders
* Use `frames` to verify render history or animation sequences
* The `stdout` and `stderr` objects expose the same `lastFrame()` and `frames` API independently
* `stdin.write()` emits both `readable` and `data` events on the mock stream
* The default terminal width is 100 columns — pass `{ columns }` to test responsive layouts
* `render()` uses `debug: true` internally, so each render produces a separate frame instead of overwriting


# Troubleshooting (/docs/packages/tui/troubleshooting)



# Troubleshooting [#troubleshooting]

## "Device not configured" (os error 6) [#device-not-configured-os-error-6]

**Cause:** stdin is not attached to a real TTY.

Common failure cases:

```bash
./app > output.log
printf '' | ./app
```

Run in an interactive terminal session instead.

## Scrollback History Is Cleared on Exit [#scrollback-history-is-cleared-on-exit]

`render()` uses `clearScreenAndHomeCursor` (CSI H + CSI 2J — viewport-only clear) when exiting and on rerender, replacing the older `resetTerminal` call. The terminal scrollback buffer is preserved so users can scroll back through prior output after the app exits.

## Terminal Left in Raw Mode After Crash [#terminal-left-in-raw-mode-after-crash]

If the process dies hard (`kill -9`, OOM, host crash), cleanup hooks do not run.

Recovery in the same terminal:

```bash
reset
# or
stty sane
```

## Blank Screen / No Visible Output [#blank-screen--no-visible-output]

Check these first:

1. Root component renders visible content (not `null`)
2. App is in a real TTY
3. Terminal emulator supports alternate screen mode

## Input Not Responding [#input-not-responding]

Checklist:

* `process.stdin.isTTY === true`
* In React mode, use `render()` (it starts input parser + app lifecycle)
* In raw-buffer mode, create a `TerminalGuard` before your loop

## Mouse Events Not Firing [#mouse-events-not-firing]

* React mode enables mouse tracking by default
* Raw-buffer mode needs `new TerminalGuard(true)`
* Confirm your terminal supports SGR mouse tracking (1006)

## Paste Not Routed to `usePaste` [#paste-not-routed-to-usepaste]

Routing behavior is intentional:

* If one or more active `usePaste` listeners exist, paste goes to `usePaste`
* Otherwise, paste falls back to `useInput`

In raw-buffer mode, bracketed paste requires `new TerminalGuard(true)`.

## Scrolling Content Moves Sibling UI Unexpectedly [#scrolling-content-moves-sibling-ui-unexpectedly]

If you use negative margins to "scroll" a child, Yoga shifts layout instead of clipping.

Use data slicing instead:

```tsx
const visible = items.slice(scroll.offset, scroll.offset + viewportHeight);
```

## Text Wraps Unexpectedly [#text-wraps-unexpectedly]

Text currently wraps to available layout width. There is no `Text wrap="..."` API in `@visulima/tui`.

If output looks wrong, check parent width constraints (`Box width`, `padding`, `border`, etc.).

## Wide Unicode/Emoji Alignment Issues [#wide-unicodeemoji-alignment-issues]

`@visulima/tui` uses width-aware rendering for full-width characters (CJK and many emoji) and marks continuation cells explicitly in the buffer/diff pipeline.

If alignment still looks off, it's usually due to terminal-specific grapheme behavior (some ZWJ emoji clusters). For strict layout-sensitive UIs, prefer single-codepoint glyphs over complex emoji sequences.

## `renderToString` Output Surprises [#rendertostring-output-surprises]

`renderToString` is synchronous and returns a plain string snapshot.

* `useLayoutEffect` updates can affect output
* `useEffect` async follow-up updates do not affect returned output


# TypeScript Buffer Guide (/docs/packages/tui/ts-buffer-guide)



# TypeScript Buffer Guide [#typescript-buffer-guide]

This guide focuses on the TypeScript side of raw-buffer rendering: indexing, packing attributes, and writing helpers you can reuse in demos or games.

## 1. Mental Model: Grid → Flat Array [#1-mental-model-grid--flat-array]

You draw to a terminal **grid** (`cols × rows`), but the renderer consumes a flat `Uint32Array`.

Each cell uses 2 slots:

* slot `0`: char codepoint
* slot `1`: attr code

Example for `cols = 4`, `rows = 3`:

```text
Grid cell index (y * cols + x)

y=0   0   1   2   3
y=1   4   5   6   7
y=2   8   9  10  11
```

```text
Flat Uint32Array slots (2 per cell)

cell 0  -> slots 0,1
cell 1  -> slots 2,3
cell 2  -> slots 4,5
...
cell 11 -> slots 22,23
```

Formulas:

```ts
const cell = y * cols + x;
const charSlot = cell * 2;
const attrSlot = charSlot + 1;
```

Equivalent one-liner:

```ts
const base = (y * cols + x) * 2;
```

## 2. Attr Code Bit Layout [#2-attr-code-bit-layout]

`attr` is packed as:

```text
attr = (styles << 16) | (bg << 8) | fg
```

Bit view:

```text
31                     24 23          16 15           8 7            0
+------------------------+--------------+--------------+--------------+
|        unused          |    styles    |      bg      |      fg      |
+------------------------+--------------+--------------+--------------+
```

* `fg`, `bg`: ANSI 256 color indices (`0-255`)
* `styles`: bitmask

Style bits:

| Bit | Style         |
| --- | ------------- |
| 1   | Bold          |
| 2   | Dim           |
| 4   | Italic        |
| 8   | Underline     |
| 16  | Blink         |
| 32  | Invert        |
| 64  | Hidden        |
| 128 | Strikethrough |

## 3. Practical Helper Functions [#3-practical-helper-functions]

Use helpers so you never repeat indexing math.

```ts
function inBounds(x: number, y: number, cols: number, rows: number) {
    return x >= 0 && x < cols && y >= 0 && y < rows;
}

function packAttr(fg = 255, bg = 255, styles = 0) {
    return ((styles & 0xff) << 16) | ((bg & 0xff) << 8) | (fg & 0xff);
}

function setCell(buf: Uint32Array, cols: number, rows: number, x: number, y: number, ch: string, fg = 255, bg = 255, styles = 0) {
    if (!inBounds(x, y, cols, rows)) return;
    const base = (y * cols + x) * 2;
    buf[base] = ch.codePointAt(0) ?? 32;
    buf[base + 1] = packAttr(fg, bg, styles);
}

function drawText(buf: Uint32Array, cols: number, rows: number, x: number, y: number, text: string, fg = 255, bg = 255, styles = 0) {
    let cx = x;
    for (const ch of text) {
        setCell(buf, cols, rows, cx, y, ch, fg, bg, styles);
        cx++;
    }
}
```

## 4. Frame Loop Template [#4-frame-loop-template]

```ts
import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";

const guard = new TerminalGuard();
let { cols, rows } = terminalSize();
let renderer = new Renderer(cols, rows);
let buf = new Uint32Array(cols * rows * 2);
let frame = 0;

const timer = setInterval(() => {
    buf.fill(0);

    drawText(buf, cols, rows, 2, 1, `frame ${frame++}`, 46);
    drawText(buf, cols, rows, 2, 3, "no react / pure ts", 51);

    renderer.render(buf);
}, 16);

process.on("SIGWINCH", () => {
    ({ cols, rows } = terminalSize());
    renderer.resize(cols, rows);
    buf = new Uint32Array(cols * rows * 2);
});

process.on("SIGINT", () => {
    clearInterval(timer);
    guard.leave();
    process.exit(0);
});
```

## 5. ASCII Drawing Patterns [#5-ascii-drawing-patterns]

### Horizontal Line [#horizontal-line]

```ts
for (let x = 0; x < cols; x++) {
    setCell(buf, cols, rows, x, 5, "─", 244);
}
```

### Filled Rectangle [#filled-rectangle]

```ts
function fillRect(buf: Uint32Array, cols: number, rows: number, x: number, y: number, w: number, h: number, ch: string, fg = 255, bg = 255) {
    for (let yy = y; yy < y + h; yy++) {
        for (let xx = x; xx < x + w; xx++) {
            setCell(buf, cols, rows, xx, yy, ch, fg, bg);
        }
    }
}
```

### Box Border (ASCII-friendly) [#box-border-ascii-friendly]

```ts
function drawBox(buf: Uint32Array, cols: number, rows: number, x: number, y: number, w: number, h: number, fg = 255) {
    if (w < 2 || h < 2) return;

    setCell(buf, cols, rows, x, y, "+", fg);
    setCell(buf, cols, rows, x + w - 1, y, "+", fg);
    setCell(buf, cols, rows, x, y + h - 1, "+", fg);
    setCell(buf, cols, rows, x + w - 1, y + h - 1, "+", fg);

    for (let xx = x + 1; xx < x + w - 1; xx++) {
        setCell(buf, cols, rows, xx, y, "-", fg);
        setCell(buf, cols, rows, xx, y + h - 1, "-", fg);
    }

    for (let yy = y + 1; yy < y + h - 1; yy++) {
        setCell(buf, cols, rows, x, yy, "|", fg);
        setCell(buf, cols, rows, x + w - 1, yy, "|", fg);
    }
}
```

## 6. Common Mistakes [#6-common-mistakes]

| Mistake                                                 | Symptom                            | Fix                                                        |
| ------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| Forgetting `* 2` slot stride                            | Corrupt output or random styles    | Always compute `base = (y * cols + x) * 2`                 |
| Writing out of bounds                                   | Missing chars or runtime weirdness | Add `inBounds()` checks                                    |
| Using `charCodeAt` on complex Unicode in loops by index | Broken emoji/surrogate rendering   | Iterate with `for (const ch of text)` and `codePointAt(0)` |
| Not reallocating buffer on resize                       | Stretched/truncated frames         | On `SIGWINCH`, call `renderer.resize()` and recreate `buf` |
| Forgetting `guard.leave()` on exit                      | Terminal remains in raw mode       | Always cleanup on `SIGINT`/shutdown                        |

## 7. Harness vs Direct Renderer [#7-harness-vs-direct-renderer]

If you're inside this repo, use the helper harness at `examples-raw/harness.ts`:

* `createLoop(...)`
* `setCell(...)`
* `fillRect(...)`

If you're writing package-consumer code, use the public API directly (`Renderer`, `TerminalGuard`, `terminalSize`).


# Why Is Ink Slow (/docs/packages/tui/why-is-ink-slow)



# Why is Ink slow? (and why Ratatat is faster) [#why-is-ink-slow-and-why-ratatat-is-faster]

> Part of the [Ratatat docs](/docs/packages/tui). See also: [Ink performance plan](/docs/packages/tui/ink-performance-plan) · [Render Loop](/docs/packages/tui/render-loop) · [Rendering Modes](/docs/packages/tui/rendering-modes) · [Raw Buffer API](/docs/packages/tui/raw-buffer) · ink-fast PoC implementation

Short answer: **Yoga is not the main bottleneck**. Ink and Ratatat both use Yoga in broadly similar ways. The biggest performance difference shows up **after layout** in the render/output pipeline.

This page focuses on high-frequency or full-screen updates (animated dashboards, dense redraws, stress tests). Ink is usually fine for low-frequency CLIs and forms.

Research note: this analysis was executed as a working PoC in `ink-fast`, with committed snapshots in `benchmark/render/results`.

***

## 1) What Ink and Ratatat do the same [#1-what-ink-and-ratatat-do-the-same]

Both pipelines include:

* React reconciler host config
* Yoga layout tree per host node
* layout compute before paint
* terminal ANSI output

So this is **not** a “Yoga vs no-Yoga” story.

***

## 2) Ink render path (where cost accumulates) [#2-ink-render-path-where-cost-accumulates]

Ink (as of the current `ink` package build) flows roughly like this:

```text
React commit
  -> Yoga layout compute
  -> render-node-to-output (tree walk)
  -> Output canvas (JS structures)
  -> ANSI-rich multiline string
  -> log-update (string diff + erase/cursor sequences)
  -> stdout.write(...)
```

Concrete modules in Ink's build output:

* Yoga style mapping: `ink/build/styles.js`
* Host tree + Yoga nodes: `ink/build/dom.js`, `ink/build/reconciler.js`
* Tree -> render ops: `ink/build/render-node-to-output.js`
* Output accumulation: `ink/build/output.js`
* Terminal diff/write orchestration: `ink/build/log-update.js`

### Why this gets expensive under heavy redraw [#why-this-gets-expensive-under-heavy-redraw]

Ink's backend does a lot of JS text work per frame:

1. **Builds/updates JS output structures** (cell rows, operations)
2. **Handles ANSI-aware text transforms** (`chalk`, color transforms)
3. **Performs width/wrap/truncate logic** (`string-width`, `wrap-ansi`, `cli-truncate`)
4. **Tokenizes styled output** (`@alcalzone/ansi-tokenize` in output path)
5. **Builds large frame strings** and diffs by strings/lines in `log-update`

For sparse/slow updates, this is often totally acceptable.
For dense/high-FPS updates, these JS allocations + string ops become a real CPU/GC cost center.

***

## 3) Ratatat render path (what's different) [#3-ratatat-render-path-whats-different]

Ratatat keeps React+Yoga, but swaps the backend representation and diff layer:

```text
React commit
  -> Yoga layout compute
  -> renderTreeToBuffer(...) into Uint32Array [char, attr]
  -> Rust front/back cell diff
  -> minimal ANSI bytes
  -> stdout lock write
```

Key repo modules:

* App/render loop: `packages/core/src/app.ts`
* Tree -> typed cell buffer: `packages/react/src/renderer.ts`
* Native diff engine: `packages/core/src/lib.rs` (`Renderer::generate_diff`)

Cell format:

```text
buffer[i*2]     = codepoint
buffer[i*2 + 1] = (styles << 16) | (bg << 8) | fg
```

That means no frame-sized ANSI string assembly in JS and no ANSI tokenization pass each frame. The expensive diff is done in native code at cell granularity.

***

## 4) Side-by-side: where bottlenecks usually are [#4-side-by-side-where-bottlenecks-usually-are]

```text
Ink (high-FPS, dense redraws)
[Yoga] -> [JS tree->ops] -> [JS string/tokens/wrap] -> [JS log diff] -> [write]
   low        medium              high                  medium-high      low

Ratatat (high-FPS, dense redraws)
[Yoga] -> [typed buffer fill] -> [Rust cell diff] -> [write]
   low         medium              medium/low         low
```

Again, this is workload-dependent. If your app redraws tiny deltas slowly, Ink may be perfectly adequate.

***

## 5) Why startup timings can be close [#5-why-startup-timings-can-be-close]

Startup benchmarks mostly include:

* process bootstrap
* module load/initialization
* first render setup

Those costs can dominate before steady-state rendering begins. The backend differences show up much more clearly in sustained update workloads.

***

## 6) Practical rule of thumb [#6-practical-rule-of-thumb]

Use Ink when:

* updates are infrequent
* output is small/moderate
* portability/ecosystem matters more than max throughput

Use Ratatat when:

* redraw frequency is high
* screen area touched per frame is large
* you need lower backend overhead in terminal rendering

***

## 7) Key takeaways [#7-key-takeaways]

* **Yoga itself is not the main differentiator** between Ink and Ratatat for heavy redraw workloads.
* Ink's biggest cost center is usually the **post-layout JS text pipeline** (string assembly, tokenization, wrapping, string/line diff).
* Ratatat's biggest advantage is the **typed-cell + native diff backend** (`Uint32Array` -> Rust cell diff).
* **Similar startup times do not imply similar runtime throughput**. Startup and sustained rendering stress different parts of each stack.
* For low-frequency, small-output CLIs, Ink can still be a great fit.

***

## 8) If you wanted to make Ink faster (without switching to Ratatat) [#8-if-you-wanted-to-make-ink-faster-without-switching-to-ratatat]

These are Ink-side architecture ideas — same public API, different backend strategy.

1. **Add a cell-buffer backend inside Ink**
   * Keep React + Yoga, but render into a typed cell surface (`char + attr`) instead of producing a frame-sized ANSI string first.
   * Diff cells, then emit ANSI from the diff.
   * This targets the largest current cost center (string-heavy post-layout work).

2. **Keep a persistent output surface between frames**
   * Avoid rebuilding the full `Output` structure every render.
   * Reuse buffers/arrays and update only changed regions.
   * This reduces allocation churn and GC pressure.

3. **Move expensive text processing off the hottest path**
   * Precompute/cache style transforms where possible.
   * Cache wrapped/tokenized text by `(text, width, style)` more aggressively.
   * Focus especially on Unicode-heavy and ANSI-heavy text.

4. **Improve diff granularity beyond whole-string/line updates**
   * Current string/line-oriented updates are simple but can overwork JS for dense changes.
   * A segment/cell-level diff for changed lines would reduce unnecessary rewrite work.

5. **Offer an optional native accelerator**
   * Keep default pure-JS Ink behavior.
   * Add an opt-in native diff/output module for high-performance workloads.
   * This mirrors how many projects keep portability by default while offering a fast path.

6. **Add built-in stage timing/profiling hooks**
   * Expose timings for: tree walk, output assembly, diff generation, terminal write.
   * Better visibility would let Ink users identify whether their bottleneck is layout, string processing, or I/O.


# vis action-graph (/docs/packages/vis/commands/action-graph)



# vis action-graph [#vis-action-graph]

Displays the task execution plan that `vis run` would produce, without running anything. Useful for debugging dependency ordering and understanding what will execute.

## Usage [#usage]

```bash
vis action-graph <selector> [options]
```

## Examples [#examples]

```bash
vis action-graph build                                  # All projects
vis action-graph :test                                  # Moon-style selector
vis action-graph "#frontend:build"                      # Tag filter
vis action-graph build --json                           # Machine-readable output
vis action-graph lint --query "language=typescript"      # Filter by query
```

## Output Formats [#output-formats]

**ASCII (default)** — Tasks indented by graph depth, dependencies above dependents:

```
  @myorg/utils:build
@myorg/app:build (no-cache)
```

**JSON** (`--json`) — Machine-readable structure with roots, dependencies, and task metadata.

## Options [#options]

| Option    | Default | Description                        |
| --------- | ------- | ---------------------------------- |
| `--json`  | `false` | Emit JSON instead of ASCII         |
| `--query` |         | Filter matched projects by a query |

## Selectors [#selectors]

See [vis run selectors](/docs/packages/vis/commands/run#selectors) for the full selector syntax.


# vis add (/docs/packages/vis/commands/add)



# vis add [#vis-add]

Add packages using the detected package manager. Before installing, vis runs a **typosquat check** against a curated blocklist of known malicious package names, an offline **marshall pipeline** (author, provenance, s1ngularity, metadata, downloads, expired-domains, new-bin, archived-repo), and an optional **supply-chain security scan** (Socket.dev and/or Google's deps.dev — whichever providers you've enabled).

## Secure-by-default behavior [#secure-by-default-behavior]

`vis add` blocks dependency lifecycle scripts on every package manager (npm, pnpm, yarn, bun, aube, deno) — the same pnpm v10 default applied universally. The newly-installed package's `preinstall` / `install` / `postinstall` / `prepare` scripts will not run unless:

* the package is listed in `security.policies.installScripts.allow` in `vis.config.ts` (vis runs its scripts post-install), or
* you pass `--run-scripts` to opt out for one run.

This pairs with the typosquat and supply-chain checks: even if a malicious package slips past the name and score checks, its install hooks won't execute.

## Usage [#usage]

```bash
vis add <packages...> [options]
```

## Examples [#examples]

```bash
vis add react react-dom                # Add packages (scripts blocked by default)
vis add -D typescript @types/react     # Add as dev dependencies
vis add react --filter app             # Add to specific workspace package
vis add react --to web                 # Add to one package, conform to existing catalogs
vis add react --auto-install-peers     # Recursively install non-optional peer deps
vis add -g typescript                  # Add globally (uses npm)
vis add lodash -w                      # Add to workspace root
vis add esbuild --run-scripts          # Opt out of the universal script block for this run
vis add lodash --no-socket-check       # Skip the supply-chain provider scan (Socket.dev / deps.dev) for this run
vis add lodash --no-typosquat-check    # Skip typosquat name check
vis add lodash --no-marshall-check     # Skip the offline marshall pipeline
```

## Options [#options]

| Option                 | Alias | Default | Description                                                                                                                                                                                                                          |
| ---------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--save-dev`           | `-D`  | `false` | Add as dev dependency                                                                                                                                                                                                                |
| `--exact`              | `-E`  | `false` | Save exact version                                                                                                                                                                                                                   |
| `--save-peer`          | `-P`  | `false` | Add as peer dependency                                                                                                                                                                                                               |
| `--save-optional`      | `-O`  | `false` | Add as optional dependency                                                                                                                                                                                                           |
| `--global`             | `-g`  | `false` | Install globally (uses npm)                                                                                                                                                                                                          |
| `--workspace-root`     | `-w`  | `false` | Add to workspace root                                                                                                                                                                                                                |
| `--workspace`          |       | `false` | Use workspace protocol (pnpm)                                                                                                                                                                                                        |
| `--filter`             | `-F`  |         | Filter by workspace package name                                                                                                                                                                                                     |
| `--to`                 |       |         | Target a single workspace package and auto-conform the version to existing catalogs / sibling deps (syncpack#285)                                                                                                                    |
| `--auto-install-peers` |       | `false` | After adding, recursively install non-optional peer dependencies that aren't already in the workspace (matches nypm's `installPeerDependencies`)                                                                                     |
| `--run-scripts`        |       | `false` | One-off opt-out: run lifecycle scripts for all packages in this install, overriding the block-by-default policy. The persistent allowlist at `security.policies.installScripts.allow` is the recommended approach for repeated runs. |
| `--no-typosquat-check` |       | `false` | Skip typosquat name check before adding                                                                                                                                                                                              |
| `--no-marshall-check`  |       | `false` | Skip the offline marshall pipeline (author, provenance, s1ngularity, metadata, downloads, expired-domains, new-bin, archived-repo). Signatures are opt-in via config and are not run here even when the marshall check is enabled.   |
| `--no-socket-check`    |       | `false` | Skip the enabled supply-chain provider scan (Socket.dev / deps.dev) before adding. Flag name kept for back-compat.                                                                                                                   |

## How It Works [#how-it-works]

```mermaid
flowchart TD
    A["vis add &lt;packages&gt;"] --> B{Typosquat check\nenabled?}
    B -- no --> E
    B -- yes --> C["Check names against\nblocklist & heuristics"]
    C --> D{Typosquat\ndetected?}
    D -- no --> E{Supply-chain\nprovider enabled?}
    D -- yes --> P["Show warning:\n'Did you mean X?'"]
    P --> Q{User choice}
    Q -- "S (suggested)" --> R["Replace with correct\npackage name"]
    R --> E
    Q -- "y (keep original)" --> E
    Q -- "N (abort)" --> Z["Exit with code 1"]
    E -- no --> G
    E -- yes --> F["Fetch security reports\n(Socket.dev / deps.dev)"]
    F --> H{Score below\nthreshold?}
    H -- no --> G["Detect package manager\n(pnpm, npm, yarn, bun, deno)"]
    H -- yes --> I{User\nconfirms?}
    I -- yes --> G
    I -- no --> Z
    G --> J["Run native\nadd command"]
    J --> K["Done"]
```

## Typosquat Detection [#typosquat-detection]

When you run `vis add`, the package names are checked against a curated blocklist of known typosquats for popular packages (react, express, lodash, axios, etc.). The detection uses two methods:

1. **Blocklist lookup** -- Direct match against `data/typosquats.json`, a curated list of known typosquat names that exist on npm.
2. **Heuristic detection** -- Generates variants using common attack patterns (character omission, transposition, duplication, homoglyph substitution, separator swaps) and checks if your input matches any variant of a known package.

### Example [#example]

```bash
$ vis add axois
warn: Possible typosquat detected:
warn:   ⚠ axois — did you mean axios? (known typosquat)

Use suggested package instead? [S]uggested / [y]es, keep original / [N]o, abort (default: N)
```

Choosing **S** replaces `axois` with `axios` and continues the add, preserving any version specifier you provided (e.g., `axois@^1.0` becomes `axios@^1.0`).

In non-interactive mode (CI, piped stdin), typosquat detection always aborts to prevent automated installation of malicious packages.

## Supply-chain security check [#supply-chain-security-check]

When at least one supply-chain provider is enabled in `vis.config.ts`, each package is scored across multiple dimensions (license, maintenance, quality, supply chain, vulnerability). Packages scoring below the minimum threshold (default: 40%) require explicit confirmation.

Two providers are supported:

* **Socket.dev** — Basic-auth token (`security.socket.enabled: true` + `VIS_SOCKET_TOKEN`). Rich proprietary score + alert catalog.
* **deps.dev** — Google's Open Source Insights (`security.depsDev.enabled: true`). No auth required. Surfaces the OpenSSF Scorecard plus GHSA advisories.

You can enable either, or both. With both enabled, the reports are merged: the provider listed in `security.primaryProvider` wins on the overall score; alerts are deduped by id. The `--no-socket-check` flag disables **all** enabled providers for one run (the name is kept for backwards compatibility).

See [`vis init`](/docs/packages/vis/commands/init) to configure either provider, or the [Security audit guide](/docs/packages/vis/guides/security-audit) for a side-by-side comparison.

## Auto-install peers [#auto-install-peers]

`--auto-install-peers` mirrors nypm's `installPeerDependencies` behavior. After the primary `add` succeeds, vis reads each freshly-installed package's `package.json`, collects its non-optional `peerDependencies` (entries flagged `optional: true` in `peerDependenciesMeta` are skipped), and recursively adds the peers that aren't already present in the workspace.

The flag is **opt-in**, matching nypm's default. Deno is excluded — it has no peer dependency concept; the recursive add is a no-op there.


# vis advisories (/docs/packages/vis/commands/advisories)



# vis advisories [#vis-advisories]

`vis advisories` manages the local OSV advisory database that powers [`vis audit --offline`](/docs/packages/vis/commands/audit). All sub-commands share a single SQLite cache resolved via [`@visulima/find-cache-dir`](https://www.npmjs.com/package/@visulima/find-cache-dir) — typically `<workspace>/node_modules/.cache/vis/advisories/db.sqlite`.

## Sub-commands [#sub-commands]

| Command                       | Description                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `vis advisories sync`         | Download and ingest one or more OSV ecosystem dumps.                                   |
| `vis advisories status`       | Print the DB summary: path, schema version, per-ecosystem row counts, last sync, ETag. |
| `vis advisories prune`        | Delete the local DB.                                                                   |
| `vis advisories bloom sync`   | Fetch and verify the `endevco/osv-bloom` MAL-\* prefilter into the local cache.        |
| `vis advisories bloom status` | Print the local osv-bloom cache freshness (built-at, size, m/k params, set digest).    |

## `vis advisories sync` [#vis-advisories-sync]

Downloads `https://osv-vulnerabilities.storage.googleapis.com/<ecosystem>/all.zip` (or a configured mirror) and ingests it into the cache.

### Examples [#examples]

```bash
# Sync the npm ecosystem (default)
vis advisories sync

# Explicit ecosystem
vis advisories sync --ecosystem npm

# Several ecosystems in one pass
vis advisories sync --ecosystem npm,PyPI

# Force re-download even when the ETag matches
vis advisories sync --force

# Use a corporate OSV mirror (must be in security.audit.advisories.allowedHosts)
vis advisories sync --source https://mirror.example.com
```

### Options [#options]

| Option               | Default                            | Description                                                                     |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
| `--ecosystem <list>` | `npm`                              | Comma-separated list of ecosystems to sync.                                     |
| `--force`            | `false`                            | Re-download and re-ingest even if the upstream ETag is unchanged.               |
| `--source <url>`     | OSV.dev                            | Override the advisory source URL. Must be HTTPS and resolve to an allowed host. |
| `--db <path>`        | `<cache>/vis/advisories/db.sqlite` | Override the cache DB path.                                                     |
| `--format <fmt>`     | `table`                            | `table` (default) or `json`.                                                    |

### Allowed sources [#allowed-sources]

Only HTTPS sources resolving to hosts in the built-in allowlist (or `security.audit.advisories.allowedHosts`) will be fetched. This protects you from environment-variable injection of arbitrary mirrors at runtime.

## `vis advisories status` [#vis-advisories-status]

```bash
vis advisories status
vis advisories status --format json
```

Outputs the DB path, schema version, file size, and per-ecosystem rows:

```
DB: /workspace/node_modules/.cache/vis/advisories/db.sqlite
Schema: v2   Size: 12 MB

Ecosystem    Advisories   Last sync           ETag
──────────   ──────────   ─────────────────   ──────
npm                5,432  2026-05-11T08:14:00Z (2h ago)   "abc123"
```

Use the JSON form in CI to check staleness:

```bash
vis advisories status --format json | jq '.ecosystems[0].lastSyncIso'
```

## `vis advisories prune` [#vis-advisories-prune]

Deletes the DB. The next `vis audit --offline` will fail until you re-sync.

```bash
vis advisories prune          # confirm and delete
vis advisories prune --force  # delete without confirmation
```

## `vis advisories bloom` [#vis-advisories-bloom]

The `bloom` sub-commands manage the [`endevco/osv-bloom`](https://github.com/endevco/osv-bloom) MAL-\* bloom prefilter — a compact probabilistic filter that lets `vis audit` cheaply skip packages with no malicious-advisory match before hitting the full DB. Cached under `<cache>/vis/osv-bloom/`.

### `vis advisories bloom sync` [#vis-advisories-bloom-sync]

```bash
vis advisories bloom sync                                      # fetch from the default upstream
vis advisories bloom sync --force                             # re-download even when the set digest matches
vis advisories bloom sync --source https://bloom.example.com  # use an internal mirror (must be in allowedHosts)
```

| Option              | Default                  | Description                                                                 |
| ------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `--force`           | `false`                  | Re-download and re-verify even when the upstream set digest is unchanged    |
| `--source <url>`    | osv-bloom upstream       | Override the bloom source URL. Must be HTTPS and resolve to an allowed host |
| `--cache-dir <dir>` | `<cache>/vis/osv-bloom/` | Override the bloom cache directory                                          |
| `--format <fmt>`    | `table`                  | `table` (default) or `json`                                                 |

### `vis advisories bloom status` [#vis-advisories-bloom-status]

```bash
vis advisories bloom status
vis advisories bloom status --format json
```

| Option              | Default                  | Description                        |
| ------------------- | ------------------------ | ---------------------------------- |
| `--cache-dir <dir>` | `<cache>/vis/osv-bloom/` | Override the bloom cache directory |
| `--format <fmt>`    | `table`                  | `table` (default) or `json`        |

## Configuration [#configuration]

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    security: {
        audit: {
            advisories: {
                // Used by `vis advisories sync` unless `--source` overrides.
                source: "https://osv-vulnerabilities.storage.googleapis.com",
                // Extra mirror hosts permitted beyond the built-in allowlist.
                allowedHosts: ["mirror.corp.example.com"],
            },
        },
    },
});
```

## Related [#related]

* [`vis audit`](/docs/packages/vis/commands/audit) — the consumer of this cache.
* [Security audit guide](/docs/packages/vis/guides/security-audit).


# vis affected (/docs/packages/vis/commands/affected)



# vis affected [#vis-affected]

Detect which projects are affected by recent git changes and run a target only on those projects. Uses git diff to find changed files, maps them to projects, and includes transitively dependent projects.

## Usage [#usage]

```bash
vis affected <target> [options]
```

## Examples [#examples]

```bash
vis affected build
vis affected test --base=main
vis affected lint --base=HEAD~5 --head=HEAD
vis affected test --query "language=typescript"
vis affected build --downstream=direct
vis affected destroy --reverse
vis affected build --base=origin/main --sparse-checkout
```

## Options [#options]

| Option              | Default  | Description                                                                                                                             |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--base`            | `HEAD~1` | Git base ref for comparison                                                                                                             |
| `--head`            | `HEAD`   | Git head ref for comparison                                                                                                             |
| `--downstream`      | `deep`   | How far to include dependents: `none`, `direct`, `deep`                                                                                 |
| `--upstream`        | `none`   | How far to include dependencies: `none`, `direct`, `deep`                                                                               |
| `--parallel`        | `3`      | Maximum number of parallel tasks                                                                                                        |
| `--cache`           | `true`   | Enable caching (`--no-cache` to disable)                                                                                                |
| `--dry-run`         | `false`  | Show what would run without executing                                                                                                   |
| `--partition`       |          | Partition for distributed CI (e.g. `1/4`)                                                                                               |
| `--query`           |          | Filter affected projects by query                                                                                                       |
| `--reverse`         | `false`  | Run leaves-first (teardown order). Forwarded to `vis run`. See [Reverse order](/docs/packages/vis/commands/run#reverse-order-teardown). |
| `--sparse-checkout` | `false`  | Print the affected project roots (one per line, deduped + sorted) and exit **without** running the target                               |

## Affected Files Forwarding [#affected-files-forwarding]

When a target declares `options.affectedFiles` in `project.json`, the changed file paths are forwarded to the task process:

```json
{
    "targets": {
        "lint": {
            "command": "eslint",
            "options": {
                "affectedFiles": "args"
            }
        }
    }
}
```

| Mode   | Behavior                                        |
| ------ | ----------------------------------------------- |
| `args` | Appends changed file paths as command arguments |
| `env`  | Sets `VIS_AFFECTED_FILES` environment variable  |
| `both` | Both of the above                               |

## Sparse-checkout cone (`--sparse-checkout`) [#sparse-checkout-cone---sparse-checkout]

On very large monorepos, CI shards don't need the whole tree on disk. With
`--sparse-checkout`, `vis affected` computes the affected set exactly as usual
but, instead of delegating to `vis run`, prints the affected project roots — one
per line, deduplicated and sorted — and exits. Feed that list straight into git
sparse-checkout so a runner materialises **only** the directories a change
touches:

```bash
git sparse-checkout init --cone
vis affected build --base=origin/main --sparse-checkout | xargs git sparse-checkout set
vis affected build --base=origin/main   # now runs against a minimal working tree
```

The `--query` / `--upstream` / `--downstream` filters still apply, so the cone
matches the exact project set the subsequent run will execute. This pairs with
the [`vis doctor`](/docs/packages/vis/commands/doctor#runtime) `git-lfs` runtime check for keeping huge
checkouts fast.

`vis` only emits the project-root list — the actual partial-checkout behaviour
(cone mode, what stays virtual vs. materialised on disk) is plain git. See the
upstream reference: [`git sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout)
and the [cone-mode notes in `git read-tree`](https://git-scm.com/docs/git-read-tree#_sparse_checkout).

```mermaid
flowchart TD
    A["vis affected <target> --sparse-checkout"] --> B["git diff base..head"]
    B --> C["Map files → projects\n+ upstream/downstream + --query"]
    C --> D["Collect project roots\n(dedupe + sort)"]
    D --> E["Print roots to stdout, exit\n(no vis run delegation)"]
    E --> F["git sparse-checkout set <roots>"]
    F --> G["Minimal working tree → fast CI shard"]
```

## How It Works [#how-it-works]

1. **Diff** — Runs `git diff` between `--base` and `--head` to find changed files
2. **Map** — Maps changed files to the projects that contain them
3. **Expand** — Includes upstream/downstream based on `--upstream`/`--downstream` scope
4. **Query** — Applies `--query` filter on top of the affected set
5. **Forward** — Passes changed file list to `vis run` via `VIS_AFFECTED_FILES` env var
6. **Execute** — Runs the target on affected projects only, in dependency order

## Use Cases [#use-cases]

### CI Pipelines [#ci-pipelines]

Only test what changed in a pull request:

```bash
vis affected test --base=origin/main
```

Or use `vis ci` which wraps this with auto-detected refs:

```bash
vis ci lint,test,build
```

### Local Development [#local-development]

Run tests for recent changes:

```bash
vis affected test --base=HEAD~3
```

### Scoped CI [#scoped-ci]

Run tests only on affected TypeScript libraries:

```bash
vis affected test --query "language=typescript && layer=library"
```

### Teardown of changed stacks [#teardown-of-changed-stacks]

Tear down only the stacks affected by a change, in reverse order so dependents go first:

```bash
vis affected destroy --reverse --base=origin/main
```

Mirrors `vis affected deploy` — same project set, opposite order. See [`vis run` reverse order](/docs/packages/vis/commands/run#reverse-order-teardown) for the full mechanics.


# vis ai (/docs/packages/vis/commands/ai)



# vis ai [#vis-ai]

`vis ai` groups AI-assisted commands behind a common namespace. The root prints the subcommand catalogue (text or JSON) so a coding agent can discover what's available; the subcommands live underneath. Cache management is handled by [`vis cache`](/docs/packages/vis/commands/cache).

## Usage [#usage]

```bash
vis ai [subcommand] [options]
```

## Subcommands [#subcommands]

| Subcommand                        | Purpose                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [`providers`](#providers)         | List detected AI providers and show which one is selected                                                                |
| [`test`](#test)                   | Run a one-shot prompt against the selected provider to verify it works                                                   |
| [`fix`](#fix)                     | Read a failed task's logs and propose a structured patch (Phase 1: local, no git side effects)                           |
| [`heal`](#heal)                   | Self-healing CI loop: propose a fix, validate it via re-run, post the result to the PR/MR/build annotation               |
| [`heal accept`](#heal-accept)     | Re-validate the proposed fix and commit it to the PR/MR branch (triggered by a maintainer comment or block-step unblock) |
| [`discover-help`](#discover-help) | Emit the machine-readable subcommand catalogue as JSON (for AI agents)                                                   |

## Root: `vis ai` [#root-vis-ai]

Lists subcommands as a human-readable summary on stderr. Takes no options — for the JSON catalogue, use [`discover-help`](#discover-help).

```bash
vis ai                       # human-readable list (stderr)
```

## providers [#providers]

List every detected AI provider with its detection method, version, path, priority, and whether it's the one vis would use.

| Option     | Default | Description                      |
| ---------- | ------- | -------------------------------- |
| `--format` | `table` | Output format: `table` or `json` |

```bash
vis ai providers
vis ai providers --format json
```

The table marks the selected provider with `>>>` and prints a footer line naming it. With no provider available, the footer hints at installing one.

## test [#test]

Send a fixed prompt (`Reply with exactly: OK`) to the selected provider with a 30-second timeout. Useful for verifying configuration before relying on `fix`/`heal`.

```bash
vis ai test
```

Exits non-zero if no provider is available or the provider call fails.

## fix [#fix]

Read the latest run summary, find the requested failed task, and ask the AI to propose a structured patch. Phase 1 is local-only — no git operations, no auto-apply unless `--apply` is passed.

| Option       | Default | Description                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------- |
| `--format`   | `table` | Output format: `table` or `json`                                                             |
| `--run`      |         | Use a specific run ID from `.vis/runs/` instead of the latest run                            |
| `--apply`    | `false` | Apply the proposed patch to disk after printing it (prompts for confirmation unless `--yes`) |
| `--no-cache` | `false` | Bypass the AI response cache                                                                 |
| `--yes`      | `false` | Skip the confirmation prompt before applying                                                 |

```bash
vis ai fix @myorg/app:build
vis ai fix @myorg/app:build --apply --yes
vis ai fix @myorg/app:build --run 2026-04-28T12-00-00 --format json
```

## heal [#heal]

Self-healing CI loop. Reads the latest failed task, asks the AI for a patch, applies it, validates it by re-running just the failing target with `--no-cache --summarize --fail-fast`, and — when the validation passes — posts the proposal back to the PR/MR or, on Buildkite, to a build annotation.

The CI surface is auto-detected:

* **GitHub Actions** (`GITHUB_ACTIONS=true`): tries `gh pr comment` first, falls back to the GitHub REST API (`POST /repos/:owner/:repo/issues/:n/comments`) when `gh` is missing or fails. Uses `GITHUB_TOKEN` for the REST fallback.
* **GitLab CI** (`GITLAB_CI=true`): posts via the GitLab REST API (`POST /projects/:id/merge_requests/:iid/notes`). Requires `GITLAB_TOKEN` (or `CI_TOKEN`) — `CI_JOB_TOKEN` cannot post MR notes.
* **Buildkite** (`BUILDKITE=true`): posts a build [annotation](https://buildkite.com/docs/agent/v3/cli-annotate) via `buildkite-agent annotate` (no token needed — the agent's `BUILDKITE_AGENT_ACCESS_TOKEN` covers it). Falls back to the Buildkite REST API (`POST /v2/.../builds/{n}/annotations`, requires `BUILDKITE_API_TOKEN`) when the agent CLI isn't available. The annotation context is keyed on `BUILDKITE_BUILD_ID` so reruns update in place. Self-hosted Buildkite Enterprise honours `BUILDKITE_API_BASE_URL`.
* **Push events / unrecognised CI**: skipped with a notice — the patch is still applied + validated locally.

| Option                 | Default | Description                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------- |
| `--run`                |         | Use a specific run ID from `.vis/runs/` instead of the latest run |
| `--dry-run`            | `false` | Print the proposal but skip apply, validation, and PR/MR comment  |
| `--no-cache`           | `false` | Bypass the AI response cache                                      |
| `--validation-timeout` | `1800`  | Validation re-run timeout in seconds (default 30 min)             |

```bash
vis ai heal                                # heal latest failure, comment on the PR/MR (or annotate the Buildkite build)
vis ai heal --dry-run                      # print proposal, skip apply/validate/comment
vis ai heal --run 2026-04-28T12-00-00      # heal a specific historical failure
vis ai heal --validation-timeout 600       # cap validation at 10 minutes
```

The PR/MR comment (or Buildkite annotation) includes the failing task ID, the AI's root-cause explanation, an inline diff per file (with a backtick fence chosen to survive content collisions), and a `vis ai fix … --apply` snippet for local re-application. Comments larger than 60 KB drop the diff body and link back to `vis ai fix`.

## heal accept [#heal-accept]

Re-derives the latest heal proposal, re-validates it with the same `--no-cache --summarize --fail-fast` re-run that `heal` used, and — when validation passes again — commits the patch to the PR/MR branch via the upstream provider's REST API.

`heal accept` is **not invoked manually** in normal flow. It is wired into the per-provider acceptance trigger:

* **GitHub Actions / GitLab CI**: triggered when an allow-listed maintainer leaves a `/vis heal accept` comment on the PR/MR. The companion workflow (`.github/workflows/vis-heal-accept.yml` / `.gitlab-ci.yml` job) forwards the comment author and head ref to `vis ai heal accept`.
* **Buildkite**: triggered when an allow-listed maintainer **unblocks** a [block step](https://buildkite.com/docs/pipelines/block-step) in the pipeline. `BUILDKITE_UNBLOCKER_EMAIL` (preferred) or `BUILDKITE_UNBLOCKER` is the actor — there is no comment phrase to match. Buildkite has no commit API of its own, so the commit is derived from `BUILDKITE_REPO`: HTTPS or SSH URLs that match `*github*` route through GitHub, `*gitlab*` URLs route through GitLab. Set whichever `GITHUB_TOKEN` or `GITLAB_TOKEN` matches your remote.

| Option                 | Default | Description                                                       |
| ---------------------- | ------- | ----------------------------------------------------------------- |
| `--run`                |         | Use a specific run ID from `.vis/runs/` instead of the latest run |
| `--validation-timeout` | `1800`  | Validation re-run timeout in seconds (default 30 min)             |

`heal accept` refuses to run when:

* The trigger actor is not on the configured allow-list (the error names the env var(s) checked, so a misconfigured allow-list yields an actionable hint).
* The change targets a forked repository (the upstream provider can't push to a fork from the CI token).

A reference Buildkite pipeline with the propose + block-step accept shape is generated by [`vis generate buildkite-ci`](/docs/packages/vis/commands/generate#builtin-templates) and documented in the [CI/CD guide](/docs/packages/vis/guides/ci-cd#buildkite).

## discover-help [#discover-help]

Emits the subcommand catalogue as structured JSON to stdout — names, descriptions, examples, and option schemas — so a coding agent (Claude, Cursor, Zed, …) can introspect the namespace without parsing prose. The same payload is surfaced through the bundled MCP server; see the [AI Integration guide](/docs/packages/vis/guides/ai-integration).

```bash
vis ai discover-help
vis ai discover-help | jq '.subcommands[].path'
```

## Related [#related]

* [AI Integration guide](/docs/packages/vis/guides/ai-integration) — MCP server, Claude Skill, and the self-healing CI workflow.
* [`vis cache`](/docs/packages/vis/commands/cache) — manage the AI response cache (`vis cache rotate`, `vis cache stats`).


# vis analyze (/docs/packages/vis/commands/analyze)



# vis analyze [#vis-analyze]

Analyze the impact, security posture, or compatibility of updating a single package using the configured AI provider. Useful before merging a `vis update` candidate.

## Usage [#usage]

```bash
vis analyze <package> [version] [options]
```

## Examples [#examples]

```bash
vis analyze react
vis analyze react 19.0.0
vis analyze react --ai-type security
vis analyze react --format json
```

## Options [#options]

| Option       | Default  | Description                                                             |
| ------------ | -------- | ----------------------------------------------------------------------- |
| `--ai-type`  | `impact` | AI analysis type: `impact`, `security`, `compatibility`, or `recommend` |
| `--security` | `false`  | Check for known security vulnerabilities                                |
| `--format`   | `table`  | Output format: `table` or `json`                                        |


# vis approve-builds (/docs/packages/vis/commands/approve-builds)



# vis approve-builds [#vis-approve-builds]

Scan installed dependencies for packages with lifecycle (build) scripts and surface them for explicit approval. vis blocks dependency build scripts by default; use this command to populate `security.policies.installScripts.allow` (or the native PM equivalent) for the packages you trust.

## Usage [#usage]

```bash
vis approve-builds [options]
```

## Examples [#examples]

```bash
vis approve-builds                  # interactively review pending builds
vis approve-builds --all            # approve everything (pnpm only, no prompts)
vis approve-builds --sync-native    # mirror installScripts.allow into the native PM config
vis approve-builds --write          # write the suggested entries into vis.config.ts
```

## Options [#options]

| Option          | Default | Description                                                                                                                        |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--all`         | `false` | Approve all pending builds without prompting (pnpm only)                                                                           |
| `--scan`        | `false` | Force vis scanning even for pnpm (instead of delegating to `pnpm approve-builds`)                                                  |
| `--sync-native` | `false` | Sync `installScripts.allow` to the native PM config (bun: `trustedDependencies`, npm: `.npmrc`, yarn: `.yarnrc.yml`)               |
| `--write`       | `false` | Mutate `vis.config.ts` in place — add the unapproved packages to `security.policies.installScripts.allow` (LavaMoat `auto` parity) |

### `--write` behavior [#--write-behavior]

`--write` adds every unapproved package to `vis.config.ts` under `security.policies.installScripts.allow`. It is the non-interactive counterpart of LavaMoat's `allow-scripts auto`:

* Honors `security.pinVersions`: with pinning on, entries are written as `"<name>@<version>": true,`; otherwise as `"<name>": true,`.
* Three layouts are supported:
  * `security.policies.installScripts.allow` already exists → new entries are appended; existing keys are deduped.
  * `security.policies.installScripts` exists but no `allow` → an `allow` block is inserted as the first child of `installScripts`.
  * Neither exists → a fresh `security: { policies: { installScripts: { allow: { ... } } } }` is injected at the top of `defineConfig({ … })` / `export default { … }`.

If no `vis.config.{ts,js,mjs,cjs}` is found, the command reports `no-config` and prints the snippet you would paste in manually. If the file exists but cannot be anchored (no `defineConfig(` or `export default {`), the command reports `missing-anchor` and leaves the file untouched.

## Output sections [#output-sections]

When run with the vis scanner (i.e. for any non-pnpm PM, or pnpm with `--scan`), the output includes:

* **Unapproved** — installed packages with lifecycle scripts (`preinstall`, `install`, `postinstall`, `prepare`) that are not covered by `security.policies.installScripts.allow`. Packages that ship a `binding.gyp` but no install script are flagged with the synthetic hook `install (binding.gyp)` — npm runs `node-gyp rebuild` for them implicitly (LavaMoat allow-scripts parity).
* **Stale installScripts.allow entries** — patterns in `security.policies.installScripts.allow` that no longer match any installed package. Prune them from `vis.config.ts`.
* **Version drift** (only when `security.pinVersions: true`) — entries pinned to a version that is no longer installed, with a `from  →  to` migration suggestion you can paste into `vis.config.ts`.

When `security.pinVersions: true`, suggested allowlist keys are emitted as `"<name>@<version>": true,` so a copy-paste covers the exact installed version.

## Related [#related]

* `vis security list` — same triage report, also available as `--json` for tooling integration.
* `vis security sync` — push the updated `installScripts.allow` to the native PM config.


# vis attest (/docs/packages/vis/commands/attest)



# vis attest [#vis-attest]

Outbound and inbound supply-chain attestation. Two leaves:

* **`vis attest <subject>`** (emit) — build an in-toto SLSA v1 provenance statement for a
  built artifact and keyless-sign it via Sigstore (Fulcio cert from ambient CI OIDC,
  Rekor transparency log). Writes a serialized `.sigstore` bundle — authenticity, not
  just integrity.
* **`vis attest verify`** — compose the inbound provenance + registry-signature marshalls
  over the locked dependency graph and gate on regressions (publisher dropped provenance,
  unknown/expired key id, bad signature).

## Usage [#usage]

```bash
vis attest <subject> [options]    # emit
vis attest verify [options]       # verify
```

## attest (emit) [#attest-emit]

Build an in-toto SLSA v1 provenance statement for an artifact and keyless-sign it via
Sigstore. The artifact's sha256 becomes the in-toto subject digest.

```bash
vis attest dist/app.tgz                                  # emit dist/app.tgz.sigstore (keyless-signed in CI)
vis attest dist/app.tgz --output attest.sigstore         # write the bundle to a specific path
vis attest dist/app.tgz --predicate slsaProvenance       # predicate type (default: slsaProvenance)
vis attest dist/app.tgz --require-signing                # fail instead of skip-with-warn when no ambient OIDC
vis attest dist/app.tgz --format json                    # print the signed bundle summary as JSON
```

### Options — `vis attest <subject>` [#options--vis-attest-subject]

| Option              | Default              | Description                                                                                          |
| ------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `--format`          | `table`              | Output format: `table`, `json`, or `ndjson` (json/ndjson go to stdout, logs to stderr)               |
| `--output`          | `<subject>.sigstore` | Write the serialized Sigstore bundle here                                                            |
| `--predicate`       | `slsaProvenance`     | Predicate type (`slsaProvenance` → [https://slsa.dev/provenance/v1](https://slsa.dev/provenance/v1)) |
| `--require-signing` | `false`              | Error instead of skip-with-warn when no ambient OIDC token is available (i.e. outside CI)            |

## verify [#verify]

Verify inbound provenance + registry signatures across the locked dependency graph and
gate on regressions.

```bash
vis attest verify                       # check every locked dep for provenance/signature problems
vis attest verify --prod-only           # skip devDependencies
vis attest verify --format json         # machine-readable findings for CI
vis attest verify --fail-on error       # exit non-zero only on error-severity findings
```

### Options — `vis attest verify` [#options--vis-attest-verify]

| Option        | Default   | Description                                                                            |
| ------------- | --------- | -------------------------------------------------------------------------------------- |
| `--format`    | `table`   | Output format: `table`, `json`, or `ndjson` (json/ndjson go to stdout, logs to stderr) |
| `--prod-only` | `false`   | Skip devDependencies — verify the production graph only                                |
| `--fail-on`   | `warning` | Severity that triggers a non-zero exit: `warning` (any finding) or `error`             |
| `--allowlist` |           | Comma-separated package names to exclude from both marshalls                           |

## Related [#related]

* [`vis audit`](/docs/packages/vis/commands/audit) — full supply-chain audit (the inbound marshalls `verify` composes).
* [`vis security verify-lockfile`](/docs/packages/vis/commands/security) — lockfile-closure policy attestation.


# vis audit (/docs/packages/vis/commands/audit)



# vis audit [#vis-audit]

`vis audit` scans every installed package (resolved from the lockfile) against the OSV vulnerability database and, when configured, one or more supply-chain intelligence providers — [Socket.dev](https://socket.dev) and [Google deps.dev](https://deps.dev) (the latter ships OpenSSF Scorecard signals + GHSA advisories and needs no API token).

It defaults to the local **offline OSV cache** populated by [`vis advisories sync`](/docs/packages/vis/commands/advisories) — no network access required at scan time. Falls back to the live OSV API when no cache is present.

## Usage [#usage]

```bash
vis audit [options]
```

## Quick examples [#quick-examples]

```bash
# Full audit (offline if a synced cache exists, otherwise OSV API)
vis audit

# Severity gate
vis audit --severity high

# CI / pipeline output
vis audit --format json
vis audit --format sarif          # GitHub code-scanning
vis audit --format csaf           # Enterprise VEX pipelines
vis audit --format cyclonedx-vex  # SBOM + VEX in one document
vis audit --format gitlab         # GitLab CI dependency-scanning widget
vis audit --format junit          # JUnit XML (GitLab/Actions/Jenkins test reporters)

# Self-contained HTML report (auto-opens in a TTY)
vis audit --report ./audit-report.html

# Reachability filter — only flag vulns in statically-imported packages
vis audit --usage

# Fix loops (dry-run preview by default)
vis audit --show-fixes             # print fix suggestions (no apply, no rescan)
vis audit --fix                    # upgrade direct deps + rescan
vis audit --fix --yes              # non-interactive (required in CI)
vis audit --fix --allow-major      # permit major-version bumps
vis audit --fix-transitive         # write PM-specific overrides

# CI exit gates
vis audit --exit-code              # exit 1 on any finding
vis audit --fail-on high           # exit 1 on high/critical only

# Accepted-risk handling
vis audit --show-accepted          # include acknowledged risks
vis audit --sync                   # mirror accepted risks to native PM config

# Supply-chain policy engine
vis audit --policies license,vulnerability  # narrow to a subset for this run
vis audit --policies none                   # skip the policy engine entirely
```

## Options [#options]

### Filtering and scope [#filtering-and-scope]

| Option               | Default | Description                                                                                                                                                                   |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--severity <level>` | `low`   | Minimum severity to report: `low`, `medium`, `high`, `critical`.                                                                                                              |
| `--prod-only`        | `false` | Skip devDependencies — scan production graph only.                                                                                                                            |
| `--usage`            | `false` | Reachability filter — only report packages that are statically imported.                                                                                                      |
| `--no-usage`         | `false` | Disable the reachability filter even if enabled in config.                                                                                                                    |
| `--ecosystem <list>` | `npm`   | Comma-separated OSV ecosystems: `npm`, `pypi`, `crates.io` (or `cargo`), `maven`, `go`, `rubygems`. Non-npm ecosystems require `--offline` (the online OSV path is npm-only). |
| `--show-accepted`    | `false` | Include findings already on the workspace's accepted-risk list.                                                                                                               |

### Output formats [#output-formats]

| Option                   | Description                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format table`         | Default human-readable output.                                                                                                                                      |
| `--format json`          | Machine-readable JSON (for CI integration).                                                                                                                         |
| `--format sarif`         | [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/) — for GitHub / GitLab code-scanning.                                                                 |
| `--format csaf`          | [CSAF 2.0](https://oasis-open.github.io/csaf-documentation/) `csaf_vex` profile.                                                                                    |
| `--format cyclonedx-vex` | [CycloneDX 1.7](https://cyclonedx.org/specification/) BOM with `vulnerabilities[]` (SBOM + VEX in one document).                                                    |
| `--format gitlab`        | [GitLab dependency-scanning report](https://docs.gitlab.com/ee/development/integrations/secure.html) v15.2.1 — picked up by the Secure stage's Dependencies widget. |
| `--format junit`         | Surefire-flavoured JUnit XML — parsed by GitLab, GitHub Actions test-reporter, Jenkins, etc., without a plugin.                                                     |
| `--report <path>`        | Write a self-contained HTML report to `<path>`. Auto-opens in a TTY when not in CI.                                                                                 |

### Offline cache [#offline-cache]

| Option        | Default                            | Description                                                     |
| ------------- | ---------------------------------- | --------------------------------------------------------------- |
| `--offline`   | `false`                            | Query the local OSV cache only. Errors if the cache is missing. |
| `--db <path>` | `<cache>/vis/advisories/db.sqlite` | Override the offline advisory DB path.                          |

Run [`vis advisories sync`](/docs/packages/vis/commands/advisories) to populate the cache.

### Fix loops [#fix-loops]

| Option             | Default | Description                                                                                                                                       |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--show-fixes`     | `false` | Print fix-suggestion lines next to each finding (no apply, no rescan).                                                                            |
| `--fix`            | `false` | Upgrade direct deps for vulnerable packages by running the active PM update command, then rescan. Dry-run preview shown first.                    |
| `--fix-transitive` | `false` | Write PM-specific overrides for vulnerable transitives (pnpm-workspace.yaml / package.json overrides / resolutions). Dry-run preview shown first. |
| `--yes`            | `false` | Skip the confirmation prompt. &#x2A;*Required in CI for both `--fix` and `--fix-transitive`.**                                                    |
| `--allow-major`    | `false` | Allow `--fix` to bump a direct dep across a major version when the lowest fix is outside the existing range.                                      |

### CI exit gates [#ci-exit-gates]

| Option              | Default | Description                                                                          |
| ------------------- | ------- | ------------------------------------------------------------------------------------ |
| `--exit-code`       | `false` | Exit 1 if any actionable issue is found.                                             |
| `--fail-on <level>` | —       | Exit 1 only when a finding is at this severity or higher.                            |
| `--sync`            | `false` | Sync vis accepted risks to native PM config (`pnpm-workspace.yaml` / `.yarnrc.yml`). |

### Supply-chain policy engine [#supply-chain-policy-engine]

| Option               | Default                 | Description                                                                                                                                                                                                                                         |
| -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--policies <names>` | every configured policy | Comma list of policies to evaluate this run. Pass `none` to skip the engine entirely, `all` to force every known policy. Known: `malware`, `firstSeen`, `unexpectedDeps`, `publisherChange`, `installScripts`, `score`, `vulnerability`, `license`. |

### Backend selection [#backend-selection]

| Option             | Default | Description                                                                                                                                                                                                                                                         |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--backend <name>` | `auto`  | Vulnerability scanner backend. `auto` delegates to `aube audit` when aube is the active installer; `aube` forces delegation (errors if `aube` is not on `PATH`); `vis` always uses the built-in OSV scanner (plus any configured providers — Socket.dev, deps.dev). |

Resolution: CLI `--backend` → `VIS_AUDIT_BACKEND` env → `security.audit.backend` in `vis.config.ts` → `auto`.

### AI explanations [#ai-explanations]

| Option                | Default | Description                                                                                                                                                                                                                                         |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--explain [id\|idx]` | —       | Add a plain-English AI explanation to findings. Bare flag explains all findings at/above `--severity`; pass a finding index (e.g. `2`) or a CVE/GHSA id to explain just one. Auto-detects an installed AI CLI; mutually exclusive with `--offline`. |

Vis-only features (`--report`, `--fix-transitive`, `--usage`, `--policies`, `--format sarif|csaf|cyclonedx-vex|gitlab|junit`, `--ecosystem` beyond `npm`) print a warning and are dropped when delegating; pass `--backend vis` if you need them.

The policy engine wraps eight Socket.dev-style supply-chain gates. Each policy
is opt-in via the corresponding `security.policies.<name>` field — leaving the
field unset means the engine skips that policy entirely. `block`-severity
decisions feed into `--exit-code` and `--fail-on` the same way vulnerability
findings do.

This release ships four offline-clean policies:

| Policy           | What it does                                                                          |
| ---------------- | ------------------------------------------------------------------------------------- |
| `license`        | SPDX allow / deny lists. Deny wins on any sub-expression match in SPDX expressions.   |
| `installScripts` | Wraps the existing `allowBuilds` / `strictDepBuilds` scan; surfaces unapproved hooks. |
| `vulnerability`  | Surfaces OSV findings; `failOn` controls block vs. warn severity.                     |
| `unexpectedDeps` | Allow-list of acceptable transitives + baseline lockfile diff.                        |

Network-bound policies (`malware`, `firstSeen`, `publisherChange`, `score`)
plug into the same engine in a follow-up commit.

## Fix loops in depth [#fix-loops-in-depth]

The two fix loops are intentionally separated by surface:

| Loop               | Touches                                                      | When to use                                                                          |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `--fix`            | Direct deps in each `package.json` (every workspace member). | The vulnerable package is listed in your manifest.                                   |
| `--fix-transitive` | PM-specific override surface (one file).                     | The vulnerable package is pulled in by a transitive — your manifest doesn't list it. |

Both loops:

1. Build a plan from current findings.
2. Print a dry-run preview (which files / packages will change).
3. Prompt for confirmation (interactive TTY) or honour `--yes` (CI).
4. Apply, then re-scan to verify the issue is gone.

In CI, `--fix-transitive` requires `--yes` **and** `security.audit.apply.transitive.enabled = true` in `vis.config.ts` — a two-lock design so you don't end up rewriting overrides on every PR by accident.

## Configuration [#configuration]

`vis.config.ts`:

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    security: {
        audit: {
            // Default to the offline OSV cache when present.
            offlineByDefault: true,
            apply: {
                transitive: {
                    // CI gate — required alongside `--yes` before overrides are written.
                    enabled: false,
                },
            },
        },
        policies: {
            vulnerability: {
                // CI exit gate (overridable via --fail-on).
                failOn: "high",
                usage: {
                    // Apply the reachability filter by default.
                    enabled: true,
                },
            },
            license: {
                // SPDX allow / deny lists. Deny wins on any sub-expression
                // match within an SPDX expression (`(MIT OR GPL-3.0)`
                // is blocked when GPL-3.0 is on the deny list).
                allow: ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"],
                deny: ["GPL-3.0", "AGPL-3.0"],
            },
            installScripts: {
                // Build-script approval surface (mirrors pnpm allowBuilds
                // / strictDepBuilds). Strict mode blocks the install
                // when any dep declares an unapproved lifecycle script.
                allow: { esbuild: true, "@swc/core": true },
                strict: true,
            },
            unexpectedDeps: {
                // Net-new transitive detection. Either provide a
                // static allow list, a baseline lockfile path, or both
                // (intersection is enforced).
                baselineLockfile: "./security/baseline.pnpm-lock.yaml",
            },
        },
        socket: {
            enabled: true,
        },
        depsDev: {
            // No auth required. Pulls OpenSSF Scorecard signals +
            // GHSA advisories from api.deps.dev. Heavily cached
            // (24h project data, 7d versions + advisories).
            enabled: true,
        },
        // When both providers are enabled, this controls which one's
        // `score` wins on merge. Alerts from the secondary are still
        // appended and deduped by `key`.
        primaryProvider: "socket",
        // Workspace-scoped acknowledged risks (shared across all policies).
        acceptedRisks: {
            "some-package": {
                reason: "Vendor confirmed no fix available",
                acceptedAt: "2026-01-01",
                expiresAt: "2026-12-31",
            },
        },
    },
});
```

## Related [#related]

* [`vis advisories`](/docs/packages/vis/commands/advisories) — manage the offline OSV cache.
* [Security audit guide](/docs/packages/vis/guides/security-audit) — how to wire `vis audit` into pipelines and run apply loops.


# vis cache (/docs/packages/vis/commands/cache)



# vis cache [#vis-cache]

Manage the local task cache: list entries, prune old ones, print sizes, and diagnose why a task missed.

## Subcommands [#subcommands]

| Command                   | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `vis cache list`          | List every cache entry                                                 |
| `vis cache size`          | Print on-disk footprint                                                |
| `vis cache clean`         | Remove every cache entry                                               |
| `vis cache prune`         | Evict by age, size, or count                                           |
| `vis cache hash <task>`   | Print the recorded hash + per-bucket breakdown                         |
| `vis cache why <task>`    | Diff the task's hash inputs against the previous run to explain a miss |
| `vis cache verify <task>` | Diff the cached entry against the live workspace to detect drift       |
| `vis cache doctor`        | Probe the configured remote cache (HTTP / REAPI) and report capability |

All subcommands accept `--cache-dir <path>` to point at a non-default cache location.

## Cache scope and worktrees [#cache-scope-and-worktrees]

The task cache lives at `<workspaceRoot>/node_modules/.cache/vis` by default — deliberately **not** under `.vis/`, which also holds tracked source (`.vis/templates`, `.vis/hooks`). Keeping the cache out of the source-bearing directory means a CI step that caches it can never sweep tracked files into the GH Actions cache (a stale restore used to resurrect deleted templates). It is gitignored for free via `node_modules`.

When the workspace is a linked git worktree (created with `git worktree add`), vis defaults to a **shared** cache at `<mainWorktreeRoot>/node_modules/.cache/vis`. Sibling worktrees driven by parallel agents then share one cache instead of rebuilding the same hash N times. Single-checkout repos behave exactly as before.

Toggle the behaviour from `vis.config.ts`:

```ts
export default {
    sharedWorktreeCache: false, // default: true
};
```

`vis cache list`, `vis cache size`, and `vis cache prune` accept `--scope`:

| Value              | Cache directory                                                             |
| ------------------ | --------------------------------------------------------------------------- |
| `shared` (default) | The main worktree's cache (or this checkout when not in a linked worktree). |
| `worktree`         | This checkout's local `node_modules/.cache/vis`, never the main one.        |
| `all`              | Operate on both directories (skipped when they resolve to the same path).   |

```bash
vis cache list --scope=worktree   # only entries owned by this checkout
vis cache prune --scope=all       # garbage-collect both stores
vis cache size --scope=shared     # default; explicit for scripts
```

Explicit cache paths win over scope: `--cache-dir <path>`, `taskRunner.cacheDirectory` in `vis.config.ts`, and the `VIS_CACHE_DIRECTORY` env var (parity with `NX_CACHE_DIRECTORY`) all skip worktree remapping.

`vis cache clean` always nukes the directory the resolver picked. From a linked worktree without an explicit override, that's the *main* worktree's cache — so `clean` requires `--force` (or interactive confirmation) before deleting it because the path is outside the current `workspaceRoot`.

## `vis cache why <task>` [#vis-cache-why-task]

When a task you expected to be cached re-ran, ask vis what changed:

```bash
vis cache why @myorg/app:build
```

Reads `.vis/last-summary.json` (always written after each non-aborted run), finds the task, and diffs its `hashDetails` (`command`, `nodes`, `runtime`, `implicitDeps`) against the previous run. Output highlights which bucket rotated and which keys inside it were added, changed, or removed.

```bash
vis cache why @myorg/app:build --json     # machine-readable, stable shape for CI
vis cache why @myorg/app:build --run <id> # diff against a specific historical run
```

Diff requires a prior run to compare against. Past runs only land in `.vis/runs/` when invoked with `--summarize`, so for reliable diffs add `--summarize` to the runs you might want to inspect later (or set it as a default in CI).

## `vis cache hash <task>` [#vis-cache-hash-task]

Print the resolved hash and the contributing inputs without diffing:

```bash
vis cache hash @myorg/app:build
vis cache hash @myorg/app:build --json
vis cache hash @myorg/app:build --run <id>
```

Useful as a low-noise sanity check — e.g. confirming two runs produced the same hash, or piping into `jq` to extract a single bucket.

## `vis cache prune` [#vis-cache-prune]

Evict cache entries by any combination of age, total size, or count:

```bash
vis cache prune --max-age-days=7              # drop entries older than a week
vis cache prune --max-size=2GB                # evict oldest until under 2GB
vis cache prune --keep-last=30                # keep only the 30 newest entries
vis cache prune --keep-last=30 --max-age-days=14   # combine: 30-newest floor, then age cap
```

`--keep-last` runs first as a hard floor on count (newest-first by mtime), then `--max-age-days` and `--max-size` apply in sequence. Negative or non-integer values for `--keep-last` exit 1 rather than silently dropping the cache.

## `vis cache list` / `vis cache size` [#vis-cache-list--vis-cache-size]

```bash
vis cache list                  # human-friendly table
vis cache list --format=json    # array of { hash, sizeBytes, mtime, … }
vis cache size --format=json    # { totalBytes, entryCount }
```

## `vis cache clean` [#vis-cache-clean]

Removes every entry. Prompts for confirmation when the cache directory is outside the workspace; pass `--force` to skip the prompt (useful in CI). `--dry-run` previews without deleting.

`--type` scopes the wipe: `task` (the workspace task cache), `ai` (AI-response cache used by `vis ai`), `socket` (Socket.dev report cache used by `vis audit`), `deps-dev` (deps.dev report cache used by `vis audit`), or `all` (default).

## `vis cache verify <task>` [#vis-cache-verify-task]

Catches the "cache restored, but the workspace doesn't match" class of bugs. Extracts the cached entry into a tmp directory and diffs each output file's content, mode, and mtime against the live workspace.

```bash
vis cache verify @myorg/app:build
vis cache verify @myorg/app:build --format=json     # { status: "ok" | "drift", entries: [...] }
vis cache verify @myorg/app:build --cache-dir=.alt  # verify against a non-default cache
vis cache verify @myorg/app:build --scope=all       # search shared + worktree caches
```

Exits 1 on any drift (changed content, mode, or mtime) or if a cached output is missing from the workspace. Pairs with the cache-restoration fidelity work (timestamps, permissions, deterministic ordering) — use this in CI on a hot path to catch regressions in the archive layer.

## `vis cache doctor` [#vis-cache-doctor]

Probe the configured remote cache and report reachability, latency, and negotiated capabilities. HTTP backends get a HEAD probe; REAPI backends get a `Capabilities` RPC and report digests + max batch size.

```bash
vis cache doctor                                                # uses remoteCache from vis.config.ts
vis cache doctor --url=grpcs://cache.example.com:443 --backend=reapi  # ad-hoc override
vis cache doctor --json                                         # machine-readable for CI gating
vis cache doctor --timeout=10000                                # bump probe timeout (default 5s)
```

Useful as a CI step before relying on a remote cache: a non-zero exit means the run will silently fall back to local-only caching, so failing fast is usually cheaper than a slow build.


# vis check (/docs/packages/vis/commands/check)



# vis check [#vis-check]

Check for outdated dependencies, known security vulnerabilities, and supply-chain
settings. On **pnpm** / **bun** workspaces it checks catalog dependencies; on
**npm** / **yarn** it checks `dependencies` / `devDependencies` (scope with `--dev` /
`--prod`).

**Aliases:** `vis c`, `vis outdated`

## Usage [#usage]

```bash
vis check [packages] [options]
```

## Examples [#examples]

```bash
vis check                              # Check all catalog dependencies
vis check react                        # Check specific packages
vis check --target minor               # Only show minor/patch updates
vis check --exclude '@types/*'         # Exclude packages by pattern
vis check --no-security                # Skip vulnerability scanning
vis check --security-config            # Audit supply-chain security settings
vis check --security-config --sync     # Sync security config to pnpm-workspace.yaml
vis check --format json                # Machine-readable output
vis check --exit-code                  # Exit 1 if outdated (for CI)
```

## Options [#options]

| Option               | Alias | Default  | Description                                                                           |
| -------------------- | ----- | -------- | ------------------------------------------------------------------------------------- |
| `--target`           | `-t`  | `latest` | Update target: `latest`, `minor`, or `patch`                                          |
| `--include`          |       |          | Glob pattern to include packages (repeatable)                                         |
| `--exclude`          |       |          | Glob pattern to exclude packages (repeatable)                                         |
| `--prerelease`       |       | `false`  | Include prerelease versions                                                           |
| `--no-security`      |       | `false`  | Skip security vulnerability scanning                                                  |
| `--security-config`  |       | `false`  | Audit supply-chain security settings                                                  |
| `--sync`             |       | `false`  | Sync security settings to `pnpm-workspace.yaml` (pnpm only, with `--security-config`) |
| `--format`           |       | `table`  | Output format: `table`, `json`, or `minimal`                                          |
| `--exit-code`        |       | `false`  | Exit with code 1 if outdated dependencies found (for CI)                              |
| `--ai`               |       | `false`  | Run AI analysis on outdated packages                                                  |
| `--ai-type`          |       |          | AI analysis type: `impact`, `security`, `compatibility`, or `recommend`               |
| `--dev`              | `-D`  | `false`  | Check only `devDependencies` (npm/yarn mode; conflicts with `--prod`)                 |
| `--prod`             | `-P`  | `false`  | Check only `dependencies` (npm/yarn mode; conflicts with `--dev`)                     |
| `--peer`             |       | `false`  | Include `peerDependencies` in outdated checks                                         |
| `--include-internal` |       | `false`  | Also check workspace-owned package names against the registry                         |

## Output Formats [#output-formats]

### Table (default) [#table-default]

Displays a color-coded table showing package name, catalog, current version, target version, and update type (patch/minor/major).

### JSON [#json]

Machine-readable JSON output including both outdated entries and any packages that failed to fetch:

```json
{
    "failed": [],
    "outdated": [
        {
            "packageName": "typescript",
            "catalog": "default",
            "currentVersion": "5.3.0",
            "targetVersion": "5.7.0",
            "updateType": "minor"
        }
    ]
}
```

### Minimal [#minimal]

Compact one-line-per-package output, suitable for scripting.

## CI Usage [#ci-usage]

Use `--exit-code` to fail CI when outdated dependencies are found:

```yaml
- name: Check dependencies
  run: vis check --exit-code --format json > deps-report.json
```


# vis ci ignore (/docs/packages/vis/commands/ci-ignore)



# vis ci ignore [#vis-ci-ignore]

Decide whether a deployment should proceed, based on whether a given project is affected by the current commit. Drops directly into &#x2A;*Vercel's "Ignored Build Step"** and **Netlify's `ignore` field** using inverted exit codes.

Inspired by [`nx-ignore`](https://github.com/nrwl/nx-labs/tree/main/packages/nx-ignore) but reuses vis's own affected detection — no parallel Nx install required on the deploy runner.

## Usage [#usage]

```bash
vis ci ignore <project> [options]
```

## Exit codes [#exit-codes]

`vis ci ignore` uses **inverted** exit codes so it matches the contract Vercel and Netlify expect from an ignore hook:

| Exit code | Meaning                 | Platform behavior   |
| --------- | ----------------------- | ------------------- |
| `0`       | Project is not affected | Cancels the build   |
| `1`       | Project is affected     | Continues the build |

Pass `--exit-zero-on-build` to invert this back to normal semantics (useful for local testing and for gating downstream CI jobs where `0 = success`).

## Examples [#examples]

```bash
# Vercel / Netlify default — uses CI env vars automatically
vis ci ignore my-app

# Explicit base ref
vis ci ignore my-app --base "$VERCEL_GIT_PREVIOUS_SHA"

# Emit the decision as JSON (pipe into jq in GitHub Actions)
vis ci ignore my-app --json

# Normal exit semantics for local testing
vis ci ignore my-app --exit-zero-on-build

# Debug the decision path
vis ci ignore my-app --verbose
```

## Options [#options]

| Option                              | Default                   | Description                                            |
| ----------------------------------- | ------------------------- | ------------------------------------------------------ |
| `--base <ref>`                      | CI env var, then `HEAD~1` | Git base ref for the affected comparison               |
| `--head <ref>`                      | `HEAD`                    | Git head ref for the affected comparison               |
| `--downstream <none\|direct\|deep>` | `deep`                    | How far to follow dependents of changed projects       |
| `--upstream <none\|direct\|deep>`   | `none`                    | How far to follow dependencies of changed projects     |
| `--json`                            | `false`                   | Emit the decision as JSON on stdout instead of text    |
| `--exit-zero-on-build`              | `false`                   | Disable inverted exit codes (build exits `0`, not `1`) |
| `--verbose`                         | `false`                   | Print debug info about the decision path               |

## How it works [#how-it-works]

1. **Commit-message gating** — reads the latest commit message and short-circuits on skip or force-deploy keywords before touching git diff.
2. **Workspace discovery** — resolves the workspace root and verifies that the requested project actually exists. Unknown projects exit with `build` (defensive default).
3. **Base ref resolution** — walks `--base` flag → CI env var chain → `HEAD~1`. If the resolved ref isn't reachable (e.g. Vercel's shallow clone), silently falls back to `HEAD~1`.
4. **Affected detection** — runs the same `getAffectedProjects` pipeline as [`vis affected`](/docs/packages/vis/commands/affected), respecting `--downstream` and `--upstream` scope.
5. **Decision emit** — prints the outcome (human text or JSON) and calls `process.exit` with the inverted exit code.

## Commit-message keywords [#commit-message-keywords]

Keywords take precedence over git-diff detection — useful for emergency bypasses and forced deploys.

### Skip build [#skip-build]

| Token                  | Scope                                |
| ---------------------- | ------------------------------------ |
| `[skip ci]`            | All projects                         |
| `[ci skip]`            | All projects                         |
| `[no ci]`              | All projects                         |
| `[vis skip]`           | All projects                         |
| `[vis skip <project>]` | Single project                       |
| `[nx skip]`            | All projects (legacy, for migration) |
| `[nx skip <project>]`  | Single project (legacy)              |

### Force build [#force-build]

| Token                    | Scope                   |
| ------------------------ | ----------------------- |
| `[vis deploy]`           | All projects            |
| `[vis deploy <project>]` | Single project          |
| `[nx deploy]`            | All projects (legacy)   |
| `[nx deploy <project>]`  | Single project (legacy) |

Legacy `[nx …]` tokens are accepted so teams migrating from `nx-ignore` don't have to rewrite their commit automation on day one.

## Base SHA resolution order [#base-sha-resolution-order]

`vis ci ignore` probes these env vars in order. The first non-empty match wins, unless `--base` is passed explicitly.

| Priority | Env var                   | Provider          |
| -------- | ------------------------- | ----------------- |
| 1        | `--base <ref>` flag       | Explicit override |
| 2        | `CACHED_COMMIT_REF`       | Netlify           |
| 3        | `VERCEL_GIT_PREVIOUS_SHA` | Vercel            |
| 4        | `GITHUB_BASE_REF`         | GitHub Actions    |
| 5        | `CI_COMMIT_BEFORE_SHA`    | GitLab CI         |
| 6        | `HEAD~1`                  | Fallback          |

Cloudflare Pages, Cloudflare Workers Builds, Render, and AWS Amplify are **not** detected here — their platforms don't invoke custom ignore scripts at all, so env detection would only create the illusion of support. See the [supported platforms matrix](#supported-platforms).

## JSON output [#json-output]

`--json` writes a structured decision record to stdout and suppresses the human text. Useful for pipelines that gate downstream jobs on the decision.

```json
{
    "project": "my-app",
    "action": "skip",
    "reason": "project-not-affected",
    "message": "Skip my-app: not affected by changes between HEAD~1...HEAD",
    "base": "HEAD~1",
    "head": "HEAD",
    "affectedProjects": ["other-app"]
}
```

### Reason codes [#reason-codes]

| Reason                     | When it's emitted                                     |
| -------------------------- | ----------------------------------------------------- |
| `commit-skip`              | Commit message contains a skip token                  |
| `commit-force-deploy`      | Commit message contains a force-deploy token          |
| `no-changes`               | Git diff shows no changed files between base and head |
| `project-affected`         | Project appears in the affected set                   |
| `project-not-affected`     | Project does not appear in the affected set           |
| `project-unknown`          | Project not found in the workspace                    |
| `missing-project-argument` | Command was invoked without a project name            |
| `workspace-error`          | Workspace root or discovery failed                    |

Decisions with reasons `project-unknown`, `missing-project-argument`, and `workspace-error` always map to `action: "build"` — we never cancel a build because of a tooling problem.

## Supported platforms [#supported-platforms]

| Platform                      | Native hook                | `vis ci ignore` works?                      |
| ----------------------------- | -------------------------- | ------------------------------------------- |
| **Vercel**                    | Ignored Build Step         | Yes — drop-in                               |
| **Netlify**                   | `ignore` in `netlify.toml` | Yes — drop-in                               |
| **GitHub Actions**            | None (CI gating only)      | Yes — via `--json` + job `if:` conditions   |
| **GitLab CI**                 | None (CI gating only)      | Yes — via `--json` + `rules:`               |
| **Cloudflare Pages**          | Build Watch Paths (globs)  | No — platform doesn't invoke custom scripts |
| **Cloudflare Workers Builds** | Build Watch Paths          | No — same reason                            |
| **Render**                    | Build Filters (globs)      | No — use their path filters                 |
| **AWS Amplify**               | `[skip-cd]` commit keyword | No — no custom-command hook                 |

For platforms without a native hook, use their built-in path filtering alongside vis, or move CI gating into GitHub Actions / GitLab CI and wrap `vis ci ignore --json` there.

See the [CI/CD guide](/docs/packages/vis/guides/ci-cd) for complete deployment integration examples.

## See also [#see-also]

* [`vis affected`](/docs/packages/vis/commands/affected) — run a target only on affected projects (what `vis ci ignore` is built on)
* [CI/CD guide](/docs/packages/vis/guides/ci-cd) — full deployment integration patterns


# vis ci (/docs/packages/vis/commands/ci)



# vis ci [#vis-ci]

Bundles the CI lifecycle into a single command: install dependencies, detect affected projects, and run targets — with base/head refs auto-detected from CI provider environment variables.

> **Subcommand:** [`vis ci ignore <project>`](/docs/packages/vis/commands/ci-ignore) — the "Ignored Build Step" gate for Vercel/Netlify that decides whether a deploy should run based on affected status.

## Usage [#usage]

```bash
vis ci <targets> [options]
```

Targets are comma-separated:

```bash
vis ci lint,test,build
```

## Examples [#examples]

```bash
vis ci lint,test,build                     # Full CI pipeline
vis ci test --base=origin/main             # Override base ref
vis ci build --no-install                  # Skip install (deps already present)
vis ci build --parallel=6                  # Increase concurrency
vis ci test --query "language=typescript"  # Filter by project metadata
```

## How It Works [#how-it-works]

1. **Install** — Runs `vis install --frozen-lockfile` (skip with `--no-install`)
2. **Affected** — For each target, runs `vis affected <target>` with the detected base/head refs
3. **Refs** — Auto-detects from GitHub Actions (`GITHUB_BASE_REF`), GitLab CI (`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`), Buildkite (`BUILDKITE_PULL_REQUEST_BASE_BRANCH` / `BUILDKITE_COMMIT`), or CircleCI. Falls back to `origin/main`

## Options [#options]

| Option             | Default       | Description                                                                                                          |
| ------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--install`        | `true`        | Install deps first (`--no-install` to skip)                                                                          |
| `--skip-toolchain` | `false`       | Skip the toolchain pre-flight (no auto-install for any pinned tool: node/pnpm/yarn/npm/bun/deno/go/python/ruby/rust) |
| `--base`           | auto-detected | Git base ref for affected detection                                                                                  |
| `--head`           | `HEAD`        | Git head ref                                                                                                         |
| `--upstream`       | `none`        | Upstream scope: `none`, `direct`, `deep`                                                                             |
| `--downstream`     | `deep`        | Downstream scope: `none`, `direct`, `deep`                                                                           |
| `--parallel`       | `4`           | Max parallel tasks per target                                                                                        |
| `--partition`      |               | Partition for distributed CI (e.g. `1/4`)                                                                            |
| `--query`          |               | Filter affected projects by query                                                                                    |


# vis clean (/docs/packages/vis/commands/clean)



# vis clean [#vis-clean]

Remove `node_modules` from every workspace project, and optionally lockfiles and stale
package directories. Removal is symlink-safe (it never follows symlinks or Windows
junctions into their targets).

The workspace **root's own `node_modules` is always removed last** — package
`node_modules` symlink into the root store and the running `vis` resolves its own
binary and native addon from the root, so clearing the root first could pull those out
mid-run.

## Usage [#usage]

```bash
vis clean [options]
```

## Examples [#examples]

```bash
# Remove every node_modules directory in the workspace
vis clean

# Also remove lockfiles (pnpm-lock.yaml, package-lock.json, …)
vis clean --lockfile

# Also remove stale workspace directories that have no package.json
vis clean --empty-packages

# Preview what would be removed without deleting anything
vis clean --dry-run
```

## Options [#options]

| Option             | Alias | Default | Description                                                                                                                |
| ------------------ | ----- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--lockfile`       | `-l`  | `false` | Also remove lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `bun.lock`, `bun.lockb`) |
| `--empty-packages` | `-e`  | `false` | Also remove directories that match a workspace pattern but have no `package.json`                                          |
| `--dry-run`        |       | `false` | Show what would be removed without acting                                                                                  |

## `--empty-packages` [#--empty-packages]

Workspace patterns such as `packages/*` occasionally leave behind directories that no
longer contain a `package.json` — a half-deleted package, a renamed folder, a scratch
checkout. Installs and task discovery silently skip them, so they linger. `--empty-packages`
removes any directory that matches a configured workspace pattern (read from
`pnpm-workspace.yaml`, falling back to `package.json#workspaces`) but carries no
`package.json`.

A directory that still contains a package further down — e.g. a grouping folder
`packages/group` under a `packages/**` pattern with a real `packages/group/pkg/package.json`
— is **never** removed, so you can't accidentally delete a valid package.


# vis create (/docs/packages/vis/commands/create)



# vis create [#vis-create]

Create a new project from a template. Supports built-in templates, npm `create-*` packages, and git repository templates from GitHub, GitLab, Bitbucket, and Sourcehut.

When run without arguments in a terminal, launches an interactive wizard.

## Usage [#usage]

```bash
vis create [template] [name] [-- template-args...]
```

## Examples [#examples]

```bash
# Interactive mode (guided wizard)
vis create

# Built-in templates
vis create vis:monorepo my-workspace
vis create vis:app my-app
vis create vis:library my-lib
vis create vis:generator my-gen

# npm create-* packages
vis create vite my-app
vis create vite my-app -- --template react-ts
vis create next-app my-app
vis create svelte my-app

# Git repositories
vis create user/repo my-project
vis create github:user/repo
vis create gitlab:company/templates/node-service
vis create bitbucket:team/starter
vis create https://github.com/user/repo/tree/main/packages/template

# Show available templates
vis create --list
```

## Options [#options]

| Option             | Default | Description                                   |
| ------------------ | ------- | --------------------------------------------- |
| `--list`           | `false` | Show available templates and config aliases   |
| `--editor`         |         | Generate editor configs (`vscode`)            |
| `--git-init`       | `false` | Initialize a git repository after scaffolding |
| `--no-interactive` | `false` | Skip interactive prompts                      |

## Built-in Templates [#built-in-templates]

| Template        | Description                                              |
| --------------- | -------------------------------------------------------- |
| `vis:monorepo`  | Full pnpm workspace with `apps/` and `packages/` dirs    |
| `vis:app`       | Application scaffold via `create-vite`                   |
| `vis:library`   | TypeScript library with exports, vitest, and tsconfig    |
| `vis:generator` | Code generator with `bin/` entry point and `src/` layout |

## Git Repository Templates [#git-repository-templates]

Templates can be downloaded from any git host using [giget](https://github.com/unjs/giget):

| Format              | Example                                        |
| ------------------- | ---------------------------------------------- |
| GitHub shorthand    | `user/repo`                                    |
| GitHub with branch  | `user/repo#dev`                                |
| GitHub subdirectory | `user/repo/tree/main/packages/template`        |
| GitLab              | `gitlab:group/repo`                            |
| Bitbucket           | `bitbucket:team/repo`                          |
| Sourcehut           | `sourcehut:~user/repo`                         |
| SSH                 | `git:git@github.com:user/repo`                 |
| Full URL            | `https://github.com/user/repo`                 |
| Tarball URL         | `https://example.com/templates/starter.tar.gz` |

### Private Repositories [#private-repositories]

Set environment variables to authenticate with private repos:

```bash
# GitHub
export GITHUB_TOKEN=ghp_...

# GitLab
export GITLAB_TOKEN=glpat-...

# Bitbucket
export BITBUCKET_TOKEN=...
```

Or pass a token inline via URL:

```bash
vis create https://ghp_token@github.com/private-org/template
```

## Template Arguments [#template-arguments]

Arguments after `--` are forwarded to the template runner:

```bash
vis create vite my-app -- --template react-ts
vis create next-app my-app -- --typescript --eslint
```

## Interactive Mode [#interactive-mode]

When run without arguments in a TTY, an interactive wizard guides you through:

1. **Template selection** — choose from built-in templates or enter a custom one
2. **Project name** — with a random suggestion and npm validation
3. **Target directory** — with conflict detection and overwrite confirmation
4. **Package manager** — pnpm, npm, yarn, bun, or deno (standalone projects only)
5. **Git init** — initialize a git repository (standalone only)
6. **Editor config** — generate VS Code settings and extensions

## Post-Creation Tasks [#post-creation-tasks]

After scaffolding, vis automatically:

1. **Editor config** — Creates `.vscode/settings.json` and `extensions.json` (when `--editor=vscode`)
2. **AI instructions** — Creates `.ai/instructions` (skipped if already provided by template)
3. **Git init** — Runs `git init` (when `--git-init`, standalone projects only)
4. **Install dependencies** — Runs the detected package manager's install command

## Configuration [#configuration]

Configure defaults in `vis.config.ts`:

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    create: {
        // Skip the PM prompt — always use pnpm
        defaultPm: "pnpm",

        // Auto-generate VS Code config
        defaultEditor: "vscode",

        // Auto-init git for standalone projects
        gitInit: true,

        // Disable automatic dependency installation
        install: false,

        // Prefer cached templates (faster, works offline)
        preferOffline: true,

        // Auth token for private repository templates
        auth: "ghp_...",

        // Custom template registry
        registry: "https://my-registry.example.com",

        // Named aliases for quick access
        templates: {
            react: "github:vitejs/vite/packages/create-vite/template-react-ts",
            lib: "github:my-org/lib-template",
            internal: "gitlab:company/templates/node-service",
        },
    },
});
```

### Template Aliases [#template-aliases]

When `create.templates` is configured, use alias names directly:

```bash
vis create react my-app     # → github:vitejs/vite/packages/create-vite/template-react-ts
vis create internal my-svc  # → gitlab:company/templates/node-service

# Show all aliases
vis create --list
```

## Monorepo Awareness [#monorepo-awareness]

When run inside an existing monorepo workspace:

* **vis:monorepo** is hidden from the interactive template list (prevents nesting)
* Applications are placed in `apps/` and libraries in `packages/` automatically
* The package manager prompt is skipped (uses the workspace PM)
* Git init is skipped (the workspace already has git)


# vis dedupe (/docs/packages/vis/commands/dedupe)



# vis dedupe [#vis-dedupe]

Run the package manager's deduplication routine to collapse duplicate package versions in the lockfile. Use `--check` in CI to assert the lockfile is already deduped without modifying it.

## Usage [#usage]

```bash
vis dedupe [options]
```

## Examples [#examples]

```bash
vis dedupe
vis dedupe --check     # CI: exits non-zero when changes would be made
```

## Options [#options]

| Option    | Default | Description                                       |
| --------- | ------- | ------------------------------------------------- |
| `--check` | `false` | Preview changes without modifying files (dry-run) |

## Notes [#notes]

* **bun** and **yarn v1** have no native dedupe command — vis emits a warning and falls back to a no-op.
* **deno** has no dedupe command. vis falls back to running `deno install` with a warning, which re-resolves the lockfile.


# vis deps (/docs/packages/vis/commands/deps)



# vis deps [#vis-deps]

Workspace-wide dependency policy linter. Reads every `package.json` in the workspace and reports drift, banned deps, and redefinitions against the root. `--fix` rewrites files in place.

```bash
vis deps
```

Running with no flags enables every check at once. Pass a specific flag to scope the run.

## Usage [#usage]

```bash
vis deps [options]
```

## Examples [#examples]

```bash
# Run every enabled lint and exit non-zero on failures
vis deps

# Only check that internal deps use workspace:*
vis deps --workspace-protocol

# Auto-rewrite internal deps to use workspace:*
vis deps --workspace-protocol --fix

# Flag deps duplicated between root and child packages
vis deps --redefine-root

# Flag deps matching policy.bannedDeps in vis config
vis deps --banned-deps

# One-off ban: flag any package declaring left-pad or request
vis deps --ban left-pad --ban request

# Flag external deps declared at different versions across packages
vis deps --workspace-versions

# Rewrite drifting deps to the highest sibling version
vis deps --workspace-versions --fix

# One-off pin: flag any package declaring react at a different version
vis deps --pin react@18.2.0

# Rewrite drifting deps to catalog: when a catalog already pins them
vis deps --workspace-versions --resolve catalog --fix

# Suggest new catalog entries for deps ≥3 packages already agree on
vis deps --workspace-versions --resolve catalog --propose-min 3

# Flag drift in engines.{node,pnpm}, packageManager, volta.{node,pnpm,yarn}, devEngines
vis deps --custom-types

# Align all engines/packageManager/volta versions to the highest sibling
vis deps --custom-types --fix

# Emit findings as JSON for CI / editor integrations
vis deps --format json
```

## Options [#options]

| Option                      | Default | Description                                                                                       |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `--workspace-protocol`      | `false` | Lint that internal deps use the `workspace:` protocol                                             |
| `--redefine-root`           | `false` | Lint that no child re-declares a dep already pinned in the workspace root                         |
| `--banned-deps`             | `false` | Lint deps against `policy.bannedDeps` in vis config                                               |
| `--workspace-versions`      | `false` | Lint that all packages declare external deps at the same version                                  |
| `--custom-types`            | `false` | Lint `engines.{node,pnpm}`, `packageManager`, `volta.*`, `devEngines.*` for drift across packages |
| `--empty-deps`              | `false` | Flag empty dependency blocks (`dependencies: {}`, `devDependencies: {}`, …)                       |
| `--root-private`            | `false` | Ensure the workspace root `package.json` sets `"private": true`                                   |
| `--root-package-manager`    | `false` | Ensure the workspace root `package.json` declares a `packageManager` field                        |
| `--root-deps`               | `false` | Flag runtime dependencies on the private workspace root (move them to devDependencies)            |
| `--missing-package-json`    | `false` | Flag workspace directories that lack a `package.json`                                             |
| `--dead-workspace-patterns` | `false` | Flag workspace patterns that match zero packages                                                  |
| `--types-in-deps`           | `false` | Flag `@types/*` declared in `dependencies` on a private package (should be devDependencies)       |
| `--similar-deps`            | `false` | Flag version drift across related dep families (react+react-dom, `@babel/*`, `@storybook/*`, …)   |
| `--dep`                     |         | Restrict `--workspace-versions`/`--custom-types` to a single dep                                  |
| `--ban`                     |         | Ban a dep name or glob for this run (repeatable). Auto-enables `--banned-deps`                    |
| `--pin`                     |         | Pin a dep to an exact specifier for this run, e.g. `react@^18.2.0` (repeatable)                   |
| `--resolve`                 |         | Conflict resolution: `highest`, `lowest`, or `catalog` (default: `highest`)                       |
| `--propose-min`             |         | Propose catalog entries for deps ≥N packages already agree on. Activates with `--resolve catalog` |
| `--fix`                     | `false` | Auto-fix violations in place (writes `package.json` files)                                        |
| `--fix-specifier`           |         | Specifier used by `--fix` for workspace-protocol (default: `workspace:*`)                         |
| `--format`                  | `human` | Output format: `human`, `json`, or `minimal`                                                      |
| `--quiet`                   | `false` | Suppress all output except errors                                                                 |

## Lint kinds [#lint-kinds]

### `--workspace-protocol` [#--workspace-protocol]

Every internal dep — one whose name matches a workspace package — must use `workspace:*` (or `workspace:^` / `workspace:~` / a workspace-relative range). Catches the case where a package was extracted from the registry to the workspace but its consumers still pin the registry version.

### `--redefine-root` [#--redefine-root]

Flags every dep that appears in both the workspace root `package.json` and a child package's `package.json`. The root pin is canonical; redefining it in a child either masks the root version or silently drifts.

### `--banned-deps` [#--banned-deps]

Reads `policy.bannedDeps` (or `--ban <name>` repeatable) and flags every package that declares any of them. Glob support (`legacy-*`, `**deprecated**`).

Each rule is either a plain reason string or an object with `{ reason, replacement?, packages?, paths? }`. Optional `packages` (globs over the declaring package's `name`) and `paths` (globs over the workspace-relative `packageDir`) narrow where the rule applies; with both set, either match is enough. Omit both to ban anywhere — the default. Exact-name keys still beat globs, but only among rules whose scope matches the candidate dep.

```ts
policy: {
    bannedDeps: {
        request: "deprecated; use undici",
        moment: { reason: "huge bundle, frozen upstream", replacement: "date-fns" },
        // Apply only inside shared libs.
        react: { reason: "no react in shared libs", paths: ["packages/shared/**"] },
        // Apply only to apps.
        next: { reason: "apps only", packages: ["@app/*"] },
    },
},
```

### `--workspace-versions` [#--workspace-versions]

Detects "the same dep declared at different versions across packages." Default policy is highest-semver-wins per dep across `dependencies` ∪ `devDependencies` ∪ `peerDependencies`. With `--resolve catalog`, drifting deps are rewritten to `catalog:` when a sibling catalog already pins them; with `--propose-min N`, new catalog entries are suggested for deps that ≥N packages already agree on.

### `--custom-types` [#--custom-types]

Detects drift in version pins that live outside `*Dependencies` blocks. Five built-in customTypes:

| customType                  | Source                                                                |
| --------------------------- | --------------------------------------------------------------------- |
| `engines`                   | `pkg.engines.{node,pnpm,yarn,npm,...}`                                |
| `volta`                     | `pkg.volta.{node,pnpm,yarn}`                                          |
| `packageManager`            | `pkg.packageManager` — `name@version` or `name@version+sha512.<hash>` |
| `devEngines.runtime`        | `pkg.devEngines.runtime` (single object or `{name, version}[]`)       |
| `devEngines.packageManager` | `pkg.devEngines.packageManager` (same shape)                          |

Each `(customType × depName)` cluster is tracked independently — `engines.node` and `volta.node` do **not** cross-couple. Use a versionGroup once that lands if you need to enforce they agree.

`--fix` rewrites in place. The `+sha512.<hash>` integrity suffix on `packageManager` is **dropped** on bump — content-integrity hashes are tied to a specific tarball, not a version, so users must regenerate via Corepack:

```bash
vis deps --custom-types --fix
corepack use pnpm@10.32.1   # regenerate the +sha512 hash
```

#### User-defined customTypes (`policy.customTypes.extraTypes`) [#user-defined-customtypes-policycustomtypesextratypes]

When a tool stores version pins somewhere built-in customTypes don't reach (e.g. legacy `pnpm.overrides`, a private toolchain block, an in-house resolver field), declare it under `policy.customTypes.extraTypes`. Entries are layered **on top of** the built-ins — they never replace `engines`/`volta`/`packageManager` etc.

Pick a `strategy` matching how the version is encoded at the path:

| strategy         | Shape at `path`                  | When to use                                                           |
| ---------------- | -------------------------------- | --------------------------------------------------------------------- |
| `versionsByName` | `{ "<name>": "<version>", ... }` | A block of name → version, like `pnpm.overrides` or `engines`.        |
| `name@version`   | `"<name>@<version>"` (string)    | Single-string slots like `packageManager` (`pnpm@10.32.1`).           |
| `name~version`   | `"<name>~<version>"` (string)    | Tilde-separated single-string slots (mirrors syncpack's tilde form).  |
| `string`         | `"<version>"` (bare)             | A bare version string. Requires `depName` so we know what to call it. |

```ts
export default {
    policy: {
        customTypes: {
            extraTypes: [
                // Legacy pnpm.overrides — versionsByName at pnpm.overrides.
                { name: "pnpmOverridesLegacy", path: "pnpm.overrides", strategy: "versionsByName" },
                // Private toolchain pin: { runtime: "node@22.14.0" }
                { name: "myToolPin", path: "myTool.runtime", strategy: "name@version" },
                // Tilde-separated pin: { runtime: "node~22.14.0" }
                { name: "myToolTildePin", path: "myTool.tildeRuntime", strategy: "name~version" },
                // Bare version string: { minNode: "22.14.0" } — needs depName.
                { name: "minNode", path: "config.minNode", strategy: "string", depName: "node" },
            ],
        },
    },
};
```

A `name` that collides with a built-in (`engines`, `volta`, `packageManager`, `devEngines.runtime`, `devEngines.packageManager`) is rejected with a non-zero exit — the built-in stays canonical. Missing/duplicate `name`, missing `path`, invalid `strategy`, or `strategy: "string"` without `depName` all fail validation up front before the workspace is scanned.

`path` always splits on `.` literally — there is no escape mechanism, so a single `package.json` key that itself contains a `.` (e.g. `pkg["foo.bar"]`) cannot be reached. Use a parent-then-child layout if you control the schema.

#### Overlap with `vis doctor` [#overlap-with-vis-doctor]

* **`vis doctor`** verifies the *installed* runtime matches `engines.node` (machine-side: "is my Node binary the right version?").
* **`vis deps --custom-types`** verifies all packages *declare* the same `engines.node` (workspace-side: "do all my package.json files agree?").

Both ship; both useful. Run `vis doctor` on a developer machine to catch local mismatches; run `vis deps --custom-types` in CI to catch workspace drift.

## Configuration [#configuration]

Set defaults under `policy` in your `vis.config.ts` (or `vis.json`):

```ts
export default {
    policy: {
        bannedDeps: ["left-pad", "request", "lodash.*"],
        workspaceProtocol: {
            // true | false | "prompt" — three-state autofix opt-out.
            autofix: true,
        },
        workspaceVersions: {
            autofix: true,
            // Per-rule resolve override; CLI --resolve still wins.
            resolve: "highest",
            ignore: ["@types/node"],
        },
        customTypes: {
            autofix: true,
            ignore: ["bun"],
            resolve: "highest",
            // Optional — see "User-defined customTypes" above.
            extraTypes: [{ name: "pnpmOverridesLegacy", path: "pnpm.overrides", strategy: "versionsByName" }],
        },
    },
};
```

`autofix: false` denies the rewrite even when `--fix` is passed — the run still fails CI, but the file is left alone. Useful when a rule is inherently human-judgement (e.g., banning `latest` shouldn't be auto-fixed). `autofix: "prompt"` is reserved for future interactive UX; treats the run as report-only today.

## Output formats [#output-formats]

### Human (default) [#human-default]

Color-coded sections per lint kind, grouped by `${customType} ${depName}` for custom-types, and by `${depName}` for workspace-versions.

### JSON [#json]

Machine-readable output for CI / editor integrations:

```json
{
    "fixed": {
        "catalogProposals": false,
        "customTypes": false,
        "workspaceProtocol": false,
        "workspaceVersions": false
    },
    "customTypes": {
        "issues": [
            {
                "customType": "engines",
                "depName": "node",
                "specifier": "20.0.0",
                "fix": "22.14.0",
                "packageName": "@my/b",
                "packageJsonPath": "packages/b/package.json",
                "canonicalSource": "@my/a"
            }
        ],
        "total": 1
    }
}
```

`packageJsonPath` is always workspace-relative for portability across CI runners.

### Minimal [#minimal]

Tab-separated lines, one per issue, suitable for `awk`/`cut` pipelines:

```
custom-types	packages/b/package.json	engines	node	20.0.0 → 22.14.0
workspace-versions	packages/b/package.json	dependencies	react	^18.0.0 → ^18.2.0
```

## Exit codes [#exit-codes]

* `0` — no issues, or all issues were auto-fixed
* `1` — issues found and not fixed (or autofix denied by `policy.*.autofix: false`)

CI typically runs `vis deps` with no `--fix` flag; the non-zero exit fails the build on drift. `--fix` is for local developer machines and pre-commit hooks.


# vis devcontainer (/docs/packages/vis/commands/devcontainer)



# vis devcontainer [#vis-devcontainer]

Interactive editor for `.devcontainer/devcontainer.json`. Pick a starter template (Node, Node + pnpm, Postgres, full-stack, Python, Go, Rust, Java, DevOps, minimal, custom) and step through the prompts. Aliased as `vis dc`.

## Usage [#usage]

```bash
vis devcontainer [options]
vis dc [options]
```

## Examples [#examples]

```bash
vis devcontainer
vis dc
vis devcontainer --template node-pnpm
vis devcontainer --output .devcontainer/dev.json
```

## Options [#options]

| Option       | Alias | Default                           | Description                                                                                                                                          |
| ------------ | ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--template` | `-t`  |                                   | Start from a template: `node`, `node-pnpm`, `node-postgres`, `node-dind`, `fullstack`, `python`, `go`, `rust`, `java`, `devops`, `minimal`, `custom` |
| `--output`   | `-o`  | `.devcontainer/devcontainer.json` | Output path                                                                                                                                          |


# vis dlx (/docs/packages/vis/commands/dlx)



# vis dlx [#vis-dlx]

Execute a remote package without installing it permanently. Delegates to the detected package manager's `dlx` equivalent (`pnpm dlx`, `npx`, `yarn dlx`, `bunx`, `deno run -A npm:<pkg>`).

## Usage [#usage]

```bash
vis dlx <package[@version]> [args...]
```

## Examples [#examples]

```bash
# Run create-vite
vis dlx create-vite my-app

# Run a specific version
vis dlx typescript@5.5.4 tsc --version

# Multiple packages with shell mode
vis dlx -p cowsay -p lolcatjs -c 'echo hi | cowsay | lolcatjs'

# Hardened: pre-install, then resolve offline (no registry fetch on dlx)
vis install && vis dlx --offline typescript tsc --version
```

## Options [#options]

| Option         | Alias | Default | Description                                                                                                                        |
| -------------- | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--package`    | `-p`  |         | Additional packages to install (repeatable)                                                                                        |
| `--shell-mode` | `-c`  | `false` | Execute within shell environment                                                                                                   |
| `--silent`     | `-s`  | `false` | Suppress output except command results                                                                                             |
| `--offline`    |       | `false` | Resolve from local store only — fail rather than fetch from the registry. Pair with `vis install` for hardened npx-style workflows |


# vis docker (/docs/packages/vis/commands/docker)



# vis docker [#vis-docker]

Helpers for building efficient Docker images from monorepos. Keeps the install layer cache-friendly by copying only manifests first, then source code — plus a Dockerfile generator, a hadolint-powered linter, and a `.dockerignore` builder.

## Usage [#usage]

```bash
vis docker scaffold --focus=<project> [options]
vis docker prune --context=<path> [options]
vis docker init [path] [options]
vis docker lint [file...] [options]
```

> The `.dockerignore` generator moved to its own command — see [`vis ignore`](/docs/packages/vis/commands/ignore) (`vis ignore --target=docker`).

## Subcommands [#subcommands]

### scaffold [#scaffold]

Copies the minimum files needed for a Docker `COPY` + `pnpm install` layer:

```bash
vis docker scaffold --focus=my-app
vis docker scaffold --focus=my-app,my-lib --include-sources
vis docker scaffold --focus=my-app --out=.docker
```

Creates two directories inside `--out` (default `.vis/docker`):

* **`workspace/`** — Root manifests (`pnpm-workspace.yaml`, `vis.config.ts`, `.npmrc`, `package.json`) + per-project `package.json` / `project.json` for the focus project and all its transitive dependencies, plus a **rewritten lockfile** containing only the entries the focus closure needs.
* **`sources/`** — Full source trees for the focus project(s) only (when `--include-sources` is set).

Also writes a `vis-docker-manifest.json` listing the focus closure for the prune step.

#### Lockfile pruning [#lockfile-pruning]

`scaffold` rewrites the workspace lockfile so it carries only entries reachable from the focus closure. This drops dependencies that belong exclusively to unfocused projects and shrinks `pnpm install` time inside Docker accordingly. Supported package managers:

| Lockfile            | Manager      | Notes                                                                          |
| ------------------- | ------------ | ------------------------------------------------------------------------------ |
| `pnpm-lock.yaml`    | pnpm         | v6 and v9 (separate `snapshots` block) supported                               |
| `package-lock.json` | npm          | v3+ path-keyed `packages` map; nested `node_modules` resolution preserved      |
| `yarn.lock`         | yarn classic | Seeded from each project's `package.json` (no workspace block in the lockfile) |
| `yarn.lock`         | yarn berry   | Detected via `__metadata` block; uses `@workspace:` resolutions                |
| `bun.lock`          | bun          | JSONC (comments stripped); package-name-keyed graph walked from workspace deps |
| `bun.lockb`         | bun          | Binary; copied verbatim with a hint to run `bun install --save-text-lockfile`  |

Per-lockfile pruning summaries are emitted at `info` level (`pnpm-lock.yaml: kept 124/812 packages and 4 importers (dropped 688 packages, 12 importers)`). Pass `--no-prune-lockfile` to copy lockfiles verbatim instead — useful for lockfile parser edge cases or when shipping the full graph is intentional.

### prune [#prune]

Strips unfocused projects from the workspace after installing dependencies:

```bash
vis docker prune --context=.vis/docker
```

Reads `vis-docker-manifest.json` from the context directory and removes every project directory not in the focus closure.

### init [#init]

Generates a multi-stage Dockerfile wired to the `scaffold` / `prune` flow, using the package manager detected from your lockfile (pnpm, npm, yarn, bun) with BuildKit cache mounts for the install layer:

```bash
vis docker init                       # write ./Dockerfile for the detected package manager
vis docker init --focus=my-app        # target a specific project's build
vis docker init --node=24             # pin a different Node base image
vis docker init apps/web/Dockerfile   # custom output path
vis docker init --dry-run             # print the Dockerfile instead of writing it
```

`init` is **create-only**: if a `Dockerfile` already exists it prompts before overwriting (default **No**). Pass `--force` to overwrite without asking, or `--dry-run` to print to stdout. In a non-interactive shell (no TTY) it refuses to overwrite and exits non-zero unless `--force` is given.

The generated runtime stage ends with a placeholder `CMD` and a `# TODO` — point it at your app's entrypoint. To improve an existing Dockerfile, use [`lint --fix`](#lint) rather than `init`.

### lint [#lint]

Lints a Dockerfile with [hadolint](https://github.com/hadolint/hadolint), the standard Dockerfile linter (60+ `DL` rules plus embedded ShellCheck `SC` rules for `RUN` scripts):

```bash
vis docker lint                       # lint ./Dockerfile
vis docker lint apps/web/Dockerfile   # lint a specific file
vis docker lint --fix                 # apply safe autofixes, then report what remains
vis docker lint --install --json      # auto-download hadolint, emit JSON
```

hadolint is a static binary that vis **downloads on demand** the first time you run `lint` (it is not bundled). If it is not found on your `PATH`, vis asks for confirmation before downloading the pinned version into `~/.vis/cache/hadolint/`; the download is checksum-verified. Pass `--install` to skip the prompt (e.g. in CI), or install hadolint yourself and vis will use the copy on your `PATH`.

#### `--fix` [#--fix]

hadolint itself only reports issues, so vis applies its own line-precise autofixes for the mechanically-safe rules, then re-lints:

| Rule     | Fix                                                |
| -------- | -------------------------------------------------- |
| `DL3015` | add `--no-install-recommends` to `apt-get install` |
| `DL3014` | add `-y` to `apt-get install`                      |
| `DL3020` | rewrite `ADD` → `COPY` for plain files/dirs        |
| `DL3027` | rewrite `apt` → `apt-get`                          |

Every other finding (e.g. `DL3007` unpinned `:latest`) stays reported — fixes that require a judgement call are never applied automatically. `lint` exits non-zero when **error**-level findings remain.

## Example Dockerfile [#example-dockerfile]

```dockerfile
FROM node:22-slim AS deps
WORKDIR /app

# 1. Scaffold — only manifests
RUN corepack enable
COPY .vis/docker/workspace/ ./
RUN pnpm install --frozen-lockfile

# 2. Sources — only the focus project
FROM deps AS build
COPY .vis/docker/sources/ ./
COPY .vis/docker/vis-docker-manifest.json .vis/docker/
RUN pnpm --filter my-app build
RUN vis docker prune --context=.vis/docker

# 3. Production image
FROM node:22-slim
WORKDIR /app
COPY --from=build /app/packages/my-app/dist ./dist
CMD ["node", "dist/index.js"]
```

## Options [#options]

### scaffold [#scaffold-1]

| Option                | Default       | Description                                                  |
| --------------------- | ------------- | ------------------------------------------------------------ |
| `--focus`             | *required*    | Project name(s) to focus on, comma-separated                 |
| `--out`               | `.vis/docker` | Output directory for scaffold                                |
| `--include-sources`   | `false`       | Also copy focus project source trees                         |
| `--no-prune-lockfile` | *off*         | Copy the workspace lockfile verbatim instead of rewriting it |

### prune [#prune-1]

| Option      | Default       | Description             |
| ----------- | ------------- | ----------------------- |
| `--context` | `.vis/docker` | Scaffold root for prune |

### init [#init-1]

| Option      | Default | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| `--focus`   | *none*  | Focus project name for the build filter              |
| `--node`    | `22`    | Node.js version tag for the base image               |
| `--force`   | `false` | Overwrite an existing Dockerfile without prompting   |
| `--dry-run` | `false` | Print the Dockerfile to stdout instead of writing it |

### lint [#lint-1]

| Option      | Default | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| `--fix`     | `false` | Apply safe autofixes, then re-lint and report        |
| `--install` | `false` | Download hadolint without prompting if it is missing |
| `--config`  | *none*  | Path to a hadolint config (`.hadolint.yaml`)         |
| `--json`    | `false` | Emit findings as JSON                                |


# vis doctor (/docs/packages/vis/commands/doctor)



# vis doctor [#vis-doctor]

`vis doctor` is a one-command project health check. It runs every diagnostic scan in parallel and prints a single dashboard with actionable next steps.

```bash
vis doctor
```

> **Not the same as `vis deps --custom-types`.** `vis doctor` verifies the *installed* runtime matches `engines.node` on this machine. `vis deps --custom-types` verifies that every package.json in the workspace *declares* the same `engines.node`. Run doctor locally; run `vis deps --custom-types` in CI. See [`vis deps`](/docs/packages/vis/commands/deps#overlap-with-vis-doctor) for the workspace-side check.

## Usage [#usage]

```bash
vis doctor [options]
```

## Examples [#examples]

```bash
# Full project health check
vis doctor

# Auto-apply safe fixes (security overrides + codemods, SIGTERM orphans)
vis doctor --fix

# Same as --fix, but SIGKILL orphans that don't respond to SIGTERM
vis doctor --fix --fix-force

# Machine-readable output for CI
vis doctor --format json
vis doctor --json                # shorthand for --format json

# Run only the security scans (skips outdated, duplicates, optimization, runtime)
vis doctor --only security

# Skip the slowest optional scans
vis doctor --skip optimization,runtime

# Summary only (no per-section breakdown), still shows the live progress UI
vis doctor --quiet

# Disable the live progress UI (forces sequential plain logs)
vis doctor --no-progress

# Exit with code 1 if security issues found
vis doctor --exit-code

# Strict mode: fail on any issue (outdated, duplicates, runtime warnings, etc.)
vis doctor --exit-code --strict
```

## Options [#options]

| Option          | Default | Description                                                                                                                                               |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format`      | `table` | Output format: `table` or `json`                                                                                                                          |
| `--json`        | `false` | Shorthand for `--format json`                                                                                                                             |
| `--only`        |         | Comma-separated sections to run: `dependencies`, `security`, `optimization`, `runtime`                                                                    |
| `--skip`        |         | Comma-separated sections to skip                                                                                                                          |
| `--quiet`       | `false` | Suppress per-section detail; print summary only                                                                                                           |
| `--no-progress` | `false` | Disable live progress UI (forces sequential logs)                                                                                                         |
| `--exit-code`   | `false` | Exit with code 1 if security issues are found                                                                                                             |
| `--fix`         | `false` | Auto-apply safe fixes (Socket overrides + codemods, then re-install). Also SIGTERMs orphaned `vis` / `task-runner` processes the runtime check found.     |
| `--fix-force`   | `false` | With `--fix`: escalate orphan cleanup to `SIGKILL` (or `taskkill /F` on Windows). Use when SIGTERM is ignored — Windows child trees, blocked event loops. |
| `--strict`      | `false` | With `--exit-code`, also fail on outdated deps, duplicates, runtime warnings                                                                              |
| `--no-cache`    | `false` | Bypass the doctor result cache (`~/.vis/cache/doctor`)                                                                                                    |
| `--filter`      |         | Comma-separated package name patterns to scope findings (supports `*` globs, e.g. `'@types/*,react'`)                                                     |

### Live progress [#live-progress]

By default `vis doctor` shows a live multi-line spinner — one row per network-bound scan (outdated catalog deps, OSV vulnerability lookup, security-provider reports (Socket.dev, deps.dev), codemod availability under `--fix`). Each row finishes with its own status icon (`✓` ok, `⚠` warn, `✗` error) and elapsed time so you can spot the slow scan at a glance.

The progress UI auto-disables in any of these cases:

* non-TTY stdout (CI, piped output)
* `--json` / `--format json`
* `--no-progress` flag

In those modes, every scan still emits a single completion line so the log stays useful.

## What It Checks [#what-it-checks]

The dashboard is grouped into four diagnostic sections plus a static **Supply Chain** posture block. The four sections (`dependencies`, `security`, `optimization`, `runtime`) are gated by `--only` / `--skip`; the supply-chain block is config-only and always runs.

### Supply Chain [#supply-chain]

A static snapshot of the workspace's hardening posture, derived from `security.*` in `vis.config.ts`. The block lists each knob and flags the unset / permissive ones so you discover them before you need them.

| Setting                                 | What it does                                                                                       | Severity when unset / permissive                                                 |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `minimumReleaseAge`                     | Block packages published in the last N minutes (mitigates same-day supply-chain compromises).      | `warn` when unset or `0`.                                                        |
| `trustPolicy`                           | Block when a package's trust level decreases (e.g. OIDC-published → token-published).              | `warn` when unset or `off`. `no-downgrade` is the recommended hardened value.    |
| `blockExoticSubdeps`                    | Disallow git/tarball URLs in transitive deps.                                                      | `warn` when unset or `false`.                                                    |
| `allowBuilds`                           | Explicit allowlist of packages permitted to run lifecycle scripts (vis blocks scripts by default). | `warn` when empty — the block-by-default still applies, but nothing runs at all. |
| `strictDepBuilds` + empty `allowBuilds` | Active misconfiguration: every package with a build script will be blocked.                        | `error` — run `vis approve-builds` to populate the allowlist.                    |
| `patchedDependencies`                   | Validate every entry in your PM-native patch map points at a real `.patch` file on disk.           | `error` when a referenced file is missing — the next install will fail.          |

A doctor run with no `security` block at all surfaces a single warning pointing at `defineConfig()` from `@visulima/vis/config`.

`patchedDependencies` is read from `pnpm-workspace.yaml` (pnpm) or `package.json` (bun); npm and yarn use different formats and are skipped silently. The check resolves each entry's path relative to the workspace root and only reports problems — when every patch file resolves, the section adds a single `ok` finding with the entry count.

When [aube](https://github.com/endevco/aube) is the active installer, doctor also surfaces aube's effective security posture next to vis's `security.policies.*` findings. The block reads `aube-workspace.yaml` (falling back to `pnpm-workspace.yaml`) and reports on `paranoid`, `trustPolicy`, `blockExoticSubdeps`, `jailBuilds`, `strictDepBuilds`, `minimumReleaseAge`, and `allowBuilds`. Aube's defaults are already hardened, so most entries render as `ok`; the section only escalates to `warn` when a hardening knob is explicitly relaxed (e.g. `trustPolicy: off`, `blockExoticSubdeps: false`, `minimumReleaseAge: 0`).

### Dependencies [#dependencies]

* Total installed packages and detected workspaces.
* Outdated entries from `pnpm-workspace.yaml` catalogs (counts grouped by `major` / `minor` / `patch`).
* Duplicate package versions across the lockfile.

### Security [#security]

* Known CVEs (OSV.dev) for both outdated and currently installed packages.
* Optional security-provider alerts and low-score packages when Socket.dev or deps.dev is configured (see [`vis audit`](/docs/packages/vis/commands/audit)).

### Optimization [#optimization]

* Replaceable native APIs (e.g. `chalk` → `node:util.styleText`).
* Lighter alternatives flagged by [e18e](https://e18e.dev).
* Trivial micro-utilities that can be inlined.
* `@socketregistry` overrides available for known-bad packages.

Run [`vis optimize`](/docs/packages/vis/commands/optimize) for an interactive picker, or pass `--fix` to apply non-interactively.

### Runtime [#runtime]

The runtime block surfaces watch / signal subsystem state that silently breaks `vis run --watch` when misconfigured.

| Check      | Platform   | What it reports                                                                                                                                                                                                                                                                                                                             |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inotify`  | Linux only | Reads `/proc/sys/fs/inotify/max_user_watches`. Warns when the limit is below `65536` — large monorepos can exhaust this and `fs.watch` will silently miss events.                                                                                                                                                                           |
| `tty`      | All        | Confirms an interactive TTY is present so [watch keybinds](/docs/packages/vis/commands/run#keybinds) work. Reports `skip` in CI / piped mode (keybinds disabled, file-change reruns still fire).                                                                                                                                            |
| `watchman` | All        | Detects whether Facebook's `watchman` binary is on `PATH`. When present, [`vis run --watch`](/docs/packages/vis/commands/run#watch-mode) transparently uses the Watchman backend, which scales recursive watching far past `fs.watch` on large trees. Reports `skip` (with an install hint) when absent — the native watcher is still used. |
| `git-lfs`  | All        | Reads `.gitattributes` (relative to the workspace root, so it is found from subdirectories). Warns when LFS-tracked patterns exist but the `git lfs` binary is missing — checkouts would contain pointer files instead of real content. `ok` when LFS is configured and installed, `skip` when no LFS patterns are tracked.                 |
| `orphans`  | All        | Looks for stray `vis run` / task-runner processes left over from prior crashes. Up to two are reported as informational; three or more become a warning with a `kill` snippet. Pass `--fix` to send SIGTERM (or `taskkill` on Windows) to the matched PIDs automatically.                                                                   |

When the inotify warning fires, the suggested fix is:

```bash
sudo sysctl fs.inotify.max_user_watches=524288
```

(VS Code and IntelliJ recommend the same value; persist it via `/etc/sysctl.d/`.)

The `inotify`, `watchman`, and `git-lfs` checks together form the **VCS-scaling
posture** — they tell you whether watch mode and large checkouts will hold up as
the monorepo grows:

```mermaid
flowchart TD
    A["vis doctor (runtime)"] --> B["inotify capacity\n(Linux watch ceiling)"]
    A --> C["watchman on PATH?"]
    A --> D[".gitattributes LFS patterns?"]
    B -- "< 65536" --> B1["warn: bump max_user_watches"]
    C -- present --> C1["ok: vis run --watch uses\nWatchman daemon backend"]
    C -- absent --> C2["skip: native fs.watch fallback\n(install hint)"]
    D -- "LFS tracked + git-lfs missing" --> D1["warn: checkouts get\npointer files, not content"]
    D -- "LFS tracked + git-lfs present" --> D2["ok"]
    D -- "no LFS patterns" --> D3["skip"]
```

Upstream references for the tools these checks probe:
[inotify (`man 7 inotify`)](https://man7.org/linux/man-pages/man7/inotify.7.html),
[Watchman](https://facebook.github.io/watchman/), and
[Git LFS](https://git-lfs.com/).

Runtime warnings flip the exit code to `1` only under `--strict`, since none of them indicate a security issue.

The `orphans` warning is the only runtime check `--fix` can resolve. The auto-recover step shares its matcher with the diagnostic — what got warned about is exactly what gets killed — and treats `ESRCH` (process already exited) as success so a benign race doesn't surface as a failure. Failures are reported per PID with their `errno` so the user knows whether to escalate privileges (`EPERM`) or investigate.

`--fix` sends SIGTERM by default so the orphan can flush buffered output and tear down its child tree gracefully. Add `--fix-force` to escalate to SIGKILL (or `taskkill /F` on Windows) for processes that ignore SIGTERM — most commonly Windows child trees that hold open console handles, or processes with a blocked event loop. The doctor re-enumerates the process table on each `--fix` run rather than reusing the cached PIDs from the diagnostic, since the orphan set can change between the scan and the recovery step (a `vis run` in another terminal could exit, or a fresh crash could leave a new orphan).

## JSON Output [#json-output]

`--format json` (or `--json`) emits a stable schema suitable for CI:

```json
{
    "status": "warn",
    "elapsedMs": 3420,
    "dependencies": { "status": "warn", "installed": 1230, "outdated": 4, "duplicates": 0 },
    "security": { "status": "ok", "vulnerabilities": 0, "alerts": 0, "lowScorePackages": 0 },
    "optimizations": { "status": "warn", "total": 3, "native": 1, "preferred": 1, "microUtilities": 0, "socket": 1 },
    "supplyChain": {
        "status": "warn",
        "findings": [
            { "label": "minimumReleaseAge: 1440 minutes", "severity": "ok" },
            {
                "label": "trustPolicy: not set",
                "severity": "warn",
                "detail": "Packages whose trust level has decreased will not be blocked. Consider 'no-downgrade'."
            },
            { "label": "blockExoticSubdeps: true", "severity": "ok" },
            { "label": "allowBuilds: 3 entries", "severity": "ok" }
        ]
    },
    "runtimeStatus": "warn",
    "runtime": [
        {
            "id": "inotify",
            "status": "warn",
            "message": "inotify watcher limit is 8192 — large monorepos can exhaust this. Bump now with `sudo sysctl fs.inotify.max_user_watches=524288` and persist via `/etc/sysctl.d/99-vis.conf` so it survives reboot.",
            "detail": { "maxWatches": 8192 }
        },
        { "id": "tty", "status": "skip", "message": "No TTY on stdin/stdout — running in CI / piped mode (keybinds disabled)." },
        {
            "id": "watchman",
            "status": "skip",
            "message": "Watchman not found — `vis` uses native fs.watch (fine for small repos). Install Watchman + `fb-watchman` to scale watch mode on large monorepos."
        },
        { "id": "git-lfs", "status": "skip", "message": "No Git LFS tracking declared in .gitattributes." },
        { "id": "orphans", "status": "ok", "message": "No orphaned vis/task-runner processes detected." }
    ],
    "packageManager": "pnpm",
    "workspaces": 44
}
```

The top-level `status` rolls up the four diagnostic sections **and** `supplyChain.status` — a permissive supply-chain config can flip the overall result to `warn` even when every other section is `ok`.

Status fields:

* Top-level `status` and each section's `status` is one of `ok`, `warn`, `error`, or `skip`. The top-level value escalates over the section values (`error` > `warn` > `ok`).
* `skip` indicates the section was filtered out via `--only` / `--skip` — distinguishes "scanned clean" from "didn't run".
* `runtime[*].status` is one of `ok`, `skip`, or `warn`. The `detail` field is optional and varies per check.
* `elapsedMs` is the wall-clock time of the scan phase (excludes banner / dashboard rendering).

## Exit Codes [#exit-codes]

| Mode                    | Fails when                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `--exit-code` (default) | Vulnerabilities or provider alerts present                                                    |
| `--exit-code --strict`  | Any of: vulnerabilities, provider alerts, outdated deps, duplicate versions, runtime warnings |

Without `--exit-code`, doctor always exits `0` so it stays usable as an informational command.

## Related [#related]

* [`vis audit`](/docs/packages/vis/commands/audit) — detailed security analysis (Socket.dev, deps.dev, advisories).
* [`vis optimize`](/docs/packages/vis/commands/optimize) — interactive optimization picker (codemods, overrides).
* [`vis update`](/docs/packages/vis/commands/update) — update outdated dependencies.
* [`vis toolchain`](/docs/packages/vis/commands/toolchain) — Node / package-manager version pinning.
* [`vis run --watch`](/docs/packages/vis/commands/run#watch-mode) — uses the inotify capacity surfaced by the `inotify` runtime check and the Watchman backend surfaced by the `watchman` check.
* [`vis affected --sparse-checkout`](/docs/packages/vis/commands/affected#sparse-checkout-cone---sparse-checkout) — pairs with the `git-lfs` runtime check for keeping large checkouts fast.


# vis exec (/docs/packages/vis/commands/exec)



# vis exec [#vis-exec]

Run a binary from the workspace's `node_modules/.bin/` (or a project's local one). Unlike [`vis dlx`](/docs/packages/vis/commands/dlx), `exec` never falls back to fetching the package from the network — if it's not installed, it fails.

On deno, `vis exec` maps to `deno task <name>` rather than the npm-style binary path. The `--filter`, `--recursive`, and topological-order flags are no-ops there.

## Usage [#usage]

```bash
vis exec <command> [args...] [options]
```

## Examples [#examples]

```bash
vis exec eslint .
vis exec tsc --noEmit
vis exec -r -- eslint .          # run in every workspace package
vis exec -c 'echo $PATH'         # shell mode
```

## Options [#options]

| Option             | Alias | Default | Description                                   |
| ------------------ | ----- | ------- | --------------------------------------------- |
| `--shell-mode`     | `-c`  | `false` | Execute within shell environment              |
| `--recursive`      | `-r`  | `false` | Run in every workspace package                |
| `--workspace-root` | `-w`  | `false` | Run on workspace root only                    |
| `--filter`         | `-F`  |         | Filter packages by name pattern (repeatable)  |
| `--parallel`       |       | `false` | Run concurrently without topological ordering |
| `--reverse`        |       | `false` | Reverse topological execution order           |


# vis fmt (/docs/packages/vis/commands/fmt)



# vis fmt [#vis-fmt]

Runs every detected formatter against the workspace. Defaults to write mode (`--fix`); pass `--check` for a dry-run that lists files that would change without modifying them. Designed to add more formatters over time without changing the command surface.

Ships with adapters for **oxfmt**, **biome**, **dprint**, **Prettier**, **ruff format** (Python), and **deno fmt**. The orchestrator runs each one that's present in the workspace; when multiple are present, files are routed by extension.

## Usage [#usage]

```bash
vis fmt [files…] [options]
```

With no files, each adapter runs against `.` so its native ignore semantics apply. Pass file paths to format a specific subset; each file is routed to the adapter that owns its extension.

## Examples [#examples]

```bash
# Apply formatting in place using every detected formatter
vis fmt

# Report files that would change without writing (CI-friendly)
vis fmt --check

# Format a specific subset
vis fmt src/foo.ts src/bar.ts

# Emit findings as JSON for CI / editor integrations
vis fmt --format json

# Suppress per-file logs
vis fmt --quiet

# Only format files changed vs the main branch
vis fmt --since main

# Re-run formatters whenever watched files change
vis fmt --watch

# Write a SARIF report to a file instead of stdout
vis fmt --check --format sarif --output fmt.sarif
```

## Options [#options]

| Option     | Default | Description                                                                                  |
| ---------- | ------- | -------------------------------------------------------------------------------------------- |
| `--check`  | `false` | Report files that would change without writing                                               |
| `--format` | `human` | Output format: `human`, `json`, `minimal`, `sarif`, `junit`, or `github`                     |
| `--quiet`  | `false` | Suppress per-file logs                                                                       |
| `--since`  |         | Only format files changed vs the given git ref (branch/tag/sha)                              |
| `--staged` | `false` | Only format files currently staged in the git index                                          |
| `--output` |         | Write formatted output to a file path instead of stdout (also accepts `-`/`stdout`/`stderr`) |
| `--watch`  | `false` | Re-run formatters whenever watched files change                                              |

### `--since` [#--since]

`vis fmt --since <ref>` narrows the input to files that changed relative to `<ref>` — committed, staged, unstaged, and untracked all qualify. Each file is routed to the formatter that owns its extension. When `<ref>` doesn't exist (or the directory isn't a git repo) the command falls back to a workspace-wide run and warns.

### `--staged` [#--staged]

`vis fmt --staged` narrows the input to files currently in the git index — the same model `lint-staged` uses. Use it in a pre-commit hook to format only what is about to be committed. When no files are staged the command exits early with a `✓ fmt: no staged files` message. Outside a git repo (or with git unavailable) the command falls back to a workspace-wide run and warns.

### `--watch` [#--watch]

`vis fmt --watch` keeps the command running, runs an initial cycle, and then re-runs whenever a file matching any eligible adapter's extension set changes. Events are debounced (200 ms) and coalesced. Combine with `--check` to keep a "would change" report live while editing — the orchestrator's cache means each incremental cycle only respawns formatters whose inputs actually changed. The loop watches the workspace root recursively (Watchman when available, `node:fs.watch` otherwise) and ignores `node_modules`, `.git`, and `.vis`. Exit with Ctrl-C (SIGINT) or SIGTERM.

### `--output` [#--output]

`vis fmt --output <path>` writes the reporter payload to a file instead of stdout. The file's parent directory is created as needed; the special values `-` and `stdout` route to `process.stdout` and `stderr` routes to `process.stderr`. The flag only applies to machine-readable formats (`json`, `minimal`, `sarif`, `junit`, `github`) — combining it with the default `human` format logs a warning and is ignored.

## Pre-commit integration [#pre-commit-integration]

`vis fmt --staged` is the recommended entry for the `staged` block in `vis.config.ts` — it auto-detects every installed formatter, only sees staged files, and writes formatting fixes in place so the commit captures the formatted tree. Pair it with `vis lint --staged --fix` to enforce lint alongside formatting.

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    staged: {
        "*": ["vis lint --staged --fix", "vis fmt --staged"],
    },
});
```

`vis init` scaffolds exactly this block when pre-commit hooks are enabled; `vis hook install` then wires `.vis/hooks/pre-commit` to invoke `vis staged`. For CI gating that fails on unformatted files, run `vis fmt --check` (optionally `--since <base>`) as a separate target alongside lint.

## Caching [#caching]

`vis fmt --check` runs cache their results under `<workspaceRoot>/.vis/cache/lint-fmt/<adapter>/` keyed by the adapter's config fingerprint plus a SHA-256 of every input file's bytes. A subsequent `--check` with the same inputs replays the stored result without spawning the formatter.

The cache is skipped for:

* write mode (the default — fixing mutates the working tree)
* workspace-wide runs that pass `.` (the file vector is unbounded)
* runs where `VIS_NO_CACHE=1` is set

Failed or killed processes are never stored. Clear the cache with `vis cache clean` or by removing the directory directly.

## Detection [#detection]

The orchestrator probes each adapter against the workspace root and runs the ones that report themselves present. An adapter opts in when **either** a tool-native config file exists **or** the tool is declared in `package.json`.

| Adapter  | Config files probed                                                                               | package.json key          |
| -------- | ------------------------------------------------------------------------------------------------- | ------------------------- |
| oxfmt    | `.oxfmtrc[.{json,jsonc,ts,mts,cts,js,mjs,cjs}]`, `oxfmt.config.{ts,mts,js,mjs}`                   | `oxfmt`                   |
| biome    | `biome.json`, `biome.jsonc`                                                                       | `@biomejs/biome`          |
| dprint   | `dprint.json`, `dprint.jsonc`, `.dprint.json`, `.dprint.jsonc`                                    | `dprint`                  |
| prettier | `.prettierrc`, `.prettierrc.{json,yaml,yml,js,cjs,mjs,ts}`, `prettier.config.{js,cjs,mjs,mts,ts}` | `prettier`                |
| ruff-fmt | `ruff.toml`, `.ruff.toml`, `pyproject.toml` with `[tool.ruff]`                                    | `ruff`, `@astral-sh/ruff` |
| deno-fmt | `deno.json`, `deno.jsonc` (no npm package — `deno` is a runtime)                                  | —                         |

When multiple fmt adapters are detected, files are routed by extension via the registry's `routeFilesByExtension` helper. The default precedence inside the registry favours Rust-native formatters (`oxfmt` → `biome` → `dprint` → `prettier` → `deno-fmt`) so a `.ts` file owned by both oxfmt and prettier goes to oxfmt. `deno-fmt` ranks last so it only owns extensions no other adapter claims — deno coexists with the npm-native pipeline rather than replacing it. Override per-extension routing through `fmt.extensionOverrides` in `vis.config.ts` (e.g. send `.md` to `dprint` even when `prettier` also handles it).

## Configuration [#configuration]

`vis.config.ts` exposes a `fmt` block for workspace-wide tuning. CLI flags always win over config.

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    fmt: {
        // Override the default adapter precedence; unlisted adapters still run, appended after.
        order: ["biome", "prettier"],
        // Pin specific extensions to a specific adapter.
        extensionOverrides: { md: "dprint" },
        adapters: {
            // Skip an adapter even when its config is detected.
            "deno-fmt": { enabled: false },
            // Append flags verbatim to every prettier invocation.
            prettier: { extraArgs: ["--cache-strategy", "content"] },
        },
    },
});
```

## Output formats [#output-formats]

### Human (default) [#human-default]

Lists changed (or "would change") files grouped by adapter, with a friendly summary.

### JSON [#json]

```json
{
    "mode": "check",
    "findings": [{ "adapter": "prettier", "file": "/repo/src/a.ts", "fixable": true, "severity": "info", "message": "Code style issues would be auto-fixed" }],
    "runs": [{ "adapter": "prettier", "durationMs": 87, "exitCode": 1, "findingCount": 1 }]
}
```

### Minimal [#minimal]

Tab-separated lines, one per file, suitable for `awk`/`cut` pipelines:

```
prettier	src/a.ts
```

### SARIF [#sarif]

`vis fmt --check --format sarif` emits a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html) document — one `run` per formatter that participated. File-level "would change" findings appear as `note`-level results so SARIF-aware ingestors don't flag formatting churn as code-scanning errors.

### JUnit [#junit]

`vis fmt --check --format junit` emits a Surefire-flavoured JUnit XML report — one `<testsuite>` per formatter and one `<testcase>` per file that would change. Suitable for CI dashboards that already render JUnit artefacts.

### GitHub Actions [#github-actions]

`vis fmt --check --format github` emits [workflow commands](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions) — `::notice file=…::message` lines (formatter findings are `info`-severity, so they annotate as notices rather than errors). File paths are emitted relative to the workspace root so GitHub anchors annotations correctly against the checked-out tree.

## Exit codes [#exit-codes]

* `0` — nothing to change, or every change was successfully written in fix mode
* `1` — at least one file would change (in `--check`), or at least one adapter exited non-zero without producing any findings (process-level failure)

In fix mode, "would change" findings don't fail the run — the tool just wrote them. Use `--check` in CI to assert a clean tree.


# vis generate (/docs/packages/vis/commands/generate)



# vis generate [#vis-generate]

Run an in-repo template to scaffold a new component, service, package, or anything else. Templates live in your repo (under `.vis/templates/`) and have access to all of vis's prompt + writer machinery.

`vis generate` complements [`vis create`](/docs/packages/vis/commands/create): `create` scaffolds whole projects from remote templates, while `generate` scaffolds inside an existing repo from local (or remote) templates.

Two template formats are supported:

* **Native templates** — single TS/JS modules that export a typed `Template` object. Programmatic, no DSL.
* **Moon-format templates** — directory of files with `template.yml`, Tera filename interpolation, YAML frontmatter, partials. Drop-in compatible with the moon subset most users actually write.

## Usage [#usage]

```bash
vis generate [name|source] [-- --opt=value ...]
```

## Examples [#examples]

```bash
# Interactive picker over discovered templates
vis generate

# Run a specific template
vis generate package

# Pre-fill option values (everything after `--` is forwarded as overrides)
vis generate component -- --name=Button --style=primary

# Custom destination + overwrite without prompting
vis generate package --to=./packages/new --force

# Print planned writes without touching disk
vis generate package --dry-run

# Fetch a remote template via giget and run it
vis generate git://github.com/visulima/template-fixture#main
vis generate npm://@scope/template-pkg

# List discovered templates
vis generate --list
```

## Options [#options]

| Option             | Default | Description                                                                     |
| ------------------ | ------- | ------------------------------------------------------------------------------- |
| `--list`           | `false` | List discovered templates                                                       |
| `--describe`       | `false` | Print template metadata (about, destination, variables) without running produce |
| `--json`           | `false` | Emit JSON output (with `--list` or `--describe`)                                |
| `--to <dir>`       | cwd     | Destination directory                                                           |
| `--dry-run`        | `false` | Print planned writes without touching disk                                      |
| `--force`          | `false` | Overwrite existing files without prompting                                      |
| `--defaults`       | `false` | Skip prompts; use template defaults                                             |
| `--skip-scripts`   | `false` | Skip running post-generation scripts                                            |
| `--no-interactive` | `false` | Skip interactive prompts (errors on missing required values)                    |
| `--prefer-offline` | `false` | Prefer locally cached remote templates over re-downloading                      |

Anything after `--` is forwarded as variable overrides (`--name=Button` → `options.name = "Button"`, `--no-flag` → `options.flag = false`).

## Discovery [#discovery]

Templates are discovered, in priority order (first match wins):

1. `<workspace>/.vis/templates/<name>.{ts,js,mjs}` — native templates.
2. `<workspace>/.vis/templates/<name>/` (any directory containing `template.yml`) — moon-format templates living alongside native ones.
3. `<workspace>/.moon/templates/<name>/` — moon-format templates from the moon ecosystem (auto-discovered for zero-config migration).
4. Extra directories listed in `vis.config.ts` `generator.templates`.
5. **Builtin templates** shipped with `@visulima/vis` (e.g. `buildkite-ci`). Lowest priority — any user template with the same name overrides.

When a name resolves in multiple sources, **the higher-priority source wins** and a warning is printed at discovery so the conflict is visible. In particular, dropping `.vis/templates/<builtin-name>/` into your repo is the supported way to vendor and customise a bundled preset.

`--list` annotates each row with its source (`native`, `moon`, `config`, `builtin`, `remote`) so you can see at a glance which copy is in effect.

## Builtin templates [#builtin-templates]

`@visulima/vis` ships a small set of opinionated presets so you don't have to copy reference YAML out of the docs. They are bundled in the package's `templates/` directory and resolved relative to the installed module — they work the same in dev, production, and CI containers, with no extra setup.

| Template       | Generates                 | Purpose                                                                                                                           |
| -------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `buildkite-ci` | `.buildkite/pipeline.yml` | Buildkite pipeline that runs `vis ci` against affected packages, with an optional `vis ai heal` propose + block-step accept flow. |

Run `vis generate buildkite-ci` to invoke it; the prompts cover `targets`, `packageManager` (pnpm/npm/yarn), `withHeal`, and `agentQueue`. To customise, vendor a copy at `.vis/templates/buildkite-ci/` — the user copy wins over the bundled preset.

## Configuration [#configuration]

Add extra template directories in `vis.config.ts`:

```typescript
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    generator: {
        templates: ["./tools/generators", "./packages/scaffolding/templates"],
    },
});
```

## Writing a native template [#writing-a-native-template]

Native templates are TS modules under `.vis/templates/`:

```typescript
// .vis/templates/package.ts
import { createTemplate } from "@visulima/vis/generate";

export default createTemplate({
    about: { name: "package", description: "Scaffold a new visulima package" },
    options: {
        name: { type: "string", required: true, prompt: "Package name?" },
        category: { type: "enum", values: ["api", "fs", "tooling"], required: true },
    },
    async produce({ options, builtins }) {
        const dir = `packages/${options.category}/${options.name}`;

        return {
            files: {
                [`${dir}/package.json`]: JSON.stringify({ name: options.name }, null, 2),
                [`${dir}/src/index.ts`]: "export {};\n",
                [`${dir}/README.md`]: `# ${options.name}\n`,
            },
            scripts: ["pnpm install"],
            suggestions: ["Add a tag in project.json", "Add the package to apps/web/src/data/packages-metadata.json"],
        };
    },
});
```

The `Template` shape:

* `about.name` / `about.description` — surfaced by `--list` and the interactive picker.
* `options` — variable schema with types `string` / `number` / `boolean` / `enum` / `array`. Each can declare `required`, `default`, `prompt`, `internal`, `order`.
* `produce({ options, builtins })` — returns a `Creation`:
  * `files` — recursive `Record<string, string | Buffer | Record<…>>` (objects are nested directories, Buffers are binary writes).
  * `scripts` — strings or `{ commands, phase, silent }` objects, run after files are written (unless `--skip-scripts`).
  * `suggestions` — strings printed at the end as next steps.
* `destination` — optional default destination directory honored when the user does not pass `--to`.

`builtins` exposes `dest_dir`, `dest_rel_dir`, `working_dir`, `workspace_root`.

## Writing a moon-format template [#writing-a-moon-format-template]

Drop a directory into `.vis/templates/<name>/` (or use an existing `.moon/templates/<name>/`):

```
.vis/templates/component/
  template.yml
  [name].tsx.tera
  [name].test.tsx.tera     # frontmatter: if: withTest
  partials/_header.tera    # not emitted, used via {% include "header" %}
  README.md.raw            # copied verbatim
```

`template.yml`:

```yaml
title: Component
description: Scaffold a React component
variables:
    name:
        type: string
        required: true
        prompt: Component name?
    withTest:
        type: boolean
        default: true
    style:
        type: enum
        values: [primary, secondary]
        default: primary
```

`[name].tsx.tera`:

```tera
{% include "header" %}
import * as React from "react";

export const {{ name | pascal_case }}: React.FC = () => <div className="{{ style }}" />;
```

`[name].test.tsx.tera` (frontmatter `if: withTest` skips the file when `withTest === false`):

```tera
---
if: withTest
---
import { {{ name | pascal_case }} } from "./{{ name | pascal_case }}";
…
```

### Filename interpolation [#filename-interpolation]

Bracket syntax `[var]` and `[var | filter]` works in any path segment. The `.tera` and `.twig` suffixes are stripped on write.

### Frontmatter [#frontmatter]

YAML block at the top of any text file:

```yaml
---
to: alt/path/[name].tsx # override destination, supports interpolation
force: true # overwrite without prompting
if: withTest # include only when truthy
skip: false # skip when truthy
---
```

### Filters [#filters]

Eight case filters and two path helpers — names match moon:

`camel_case`, `kebab_case`, `lower_case`, `pascal_case`, `snake_case`, `upper_case`, `upper_kebab_case`, `upper_snake_case`, `path_join`, `path_relative`.

Chain with `|`: `{{ name | snake_case | upper_case }}`.

### Tera subset [#tera-subset]

Supported:

* `{{ var }}`, `{{ obj.field }}`, `{{ var | filter | filter(arg) }}` — unknown variables throw with file:line (so typos surface instead of silently empty output).
* `{% if expr %}` / `{% else %}` / `{% endif %}` — `expr` supports variables, `not var`, `a == "b"`, `a != "b"`, `a and b`, `a or b`, and parentheses. Undefined variables evaluate as falsy. `and` / `or` short-circuit.
* `{% for x in collection %}` / `{% endfor %}` — `collection` must be an array; missing/null collections render as empty.
* `{% include "name" %}` — pulls in a partial. Partials are any file whose &#x2A;*basename starts with `_`** (e.g. `_header.tera`) or whose path includes a `partials/` segment. Partials are not emitted. They can be referenced by bare basename (`header`), with or without the leading underscore, or by full path (`partials/header`, `layouts/header`).

**Unsupported** (errors with file:line and a clear hint):

* `{% set x = ... %}`
* `{% extends "..." %}`, `{% block %}` / `{% endblock %}`
* `{% macro %}` / `{% endmacro %}`
* `{% import %}`
* Custom whitespace control (`{%- -%}`)

Rewrite templates that use these — the supported subset covers what most moon templates actually use.

## Migrating from moon [#migrating-from-moon]

The vast majority of moon templates work unchanged. To migrate:

1. Either copy `.moon/templates/<name>/` to `.vis/templates/<name>/`, or leave it where it is — vis discovers `.moon/templates/` automatically.
2. Run `vis generate --list` to confirm vis sees your templates.
3. Run a template; if you hit an unsupported Tera feature, vis will point at the exact file:line.

What does **not** port:

* Tera macros / `{% set %}` / template inheritance — phase 2 work.
* `object` variable types — phase 2.
* The `glob://` template source — phase 2.
* The `variables()` function — phase 2.

Anything else should be a drop-in.


# vis graph (/docs/packages/vis/commands/graph)



# vis graph [#vis-graph]

Visualize the project dependency graph in various formats.

## Usage [#usage]

```bash
vis graph [options]
```

## Examples [#examples]

```bash
vis graph
vis graph --format=ascii
vis graph --format=dot
vis graph --format=json --output=graph.json
vis graph --format=html --output=graph.html
vis graph --depth=2
```

## Options [#options]

| Option     | Alias | Default       | Description                                                                                       |
| ---------- | ----- | ------------- | ------------------------------------------------------------------------------------------------- |
| `--format` | `-f`  | `tui`/`ascii` | Output format: `tui`, `ascii`, `dot`, `json`, `html` (default: `tui` in a TTY, `ascii` otherwise) |
| `--output` | `-o`  | stdout        | Write output to file instead of stdout                                                            |
| `--depth`  | `-d`  | unlimited     | Maximum dependency tree depth for ASCII output                                                    |

## Output Formats [#output-formats]

### TUI / ASCII (default) [#tui--ascii-default]

In an interactive terminal `vis graph` opens an interactive TUI; when piped or redirected it falls back to a tree-style ASCII representation. Best for quick inspections.

### DOT [#dot]

Outputs Graphviz DOT format. Render with:

```bash
vis graph --format=dot --output=graph.dot
dot -Tpng graph.dot -o graph.png
```

### JSON [#json]

Machine-readable format listing nodes and edges. Useful for custom tooling.

### HTML [#html]

Self-contained HTML file with an interactive graph visualization.


# vis hook (/docs/packages/vis/commands/hook)



# vis hook [#vis-hook]

Manage git hooks for your workspace. Supports installing, uninstalling, and migrating from husky or prek (pre-commit framework).

## Usage [#usage]

```bash
vis hook <action> [options]
```

## Actions [#actions]

### install [#install]

Install git hooks by configuring `core.hooksPath` to point to your hooks directory (`.vis/hooks` by default):

```bash
vis hook install
```

> **Migrating from `.vis-hooks`.** The hooks directory moved from `.vis-hooks` to `.vis/hooks`. `vis hook install` performs the move automatically: an existing `.vis-hooks` is renamed to `.vis/hooks` (your stage scripts and `config.json` come along) and `core.hooksPath` is re-pointed. Re-run `vis hook install` once after upgrading.

### uninstall [#uninstall]

Remove git hooks and reset `core.hooksPath`:

```bash
vis hook uninstall
```

### list [#list]

Print the hooks currently installed in the hooks directory, grouped by stage. Each hook block emitted by the migrator (lines of the form `# <id>: <name>`) is surfaced with its first command line for quick inspection.

```bash
vis hook list
```

### validate [#validate]

Sanity-check the hooks directory: verifies `core.hooksPath`, the dispatcher scripts, each stage script's shell syntax (`sh -n`), executable permissions, and — if any stage references the bundled `prek-runner.mjs` — that the runner exists and parses with `node --check`. Exits non-zero on any error.

```bash
vis hook validate
```

### run [#run]

Execute a stage's hook script manually, useful for CI or one-off checks. Environment variables forward extra selectors into the bundled runner, so the same hook logic that fires at commit time can be replayed over any file set:

```bash
vis hook run pre-commit                                          # run pre-commit against staged files
vis hook run pre-commit --all-files                              # run against every tracked file
vis hook run pre-commit --from-ref=main --to-ref=HEAD            # run against files changed between two refs
vis hook run pre-commit --last-commit                            # shortcut for --from-ref HEAD~1 --to-ref HEAD
```

`--all-files` maps to `VIS_HOOK_ALL_FILES=1`; `--from-ref`/`--to-ref` map to `VIS_HOOK_FROM_REF`/`VIS_HOOK_TO_REF`. The runner swaps `git diff --cached` for `git ls-files` or `git diff <from> <to>` accordingly. Stage defaults to `pre-commit` when omitted. `--all-files` wins if combined with `--from-ref`/`--to-ref` or `--last-commit`.

### migrate [#migrate]

Migrate an existing husky or prek (pre-commit framework) setup to vis:

```bash
vis hook migrate
vis hook migrate --dry-run   # preview: prints what would be written without touching disk
```

The command auto-detects the source:

* **husky** — reads `.husky/` or `.config/husky/`, copies shell scripts, uninstalls the husky npm package, and cleans `package.json` references.
* **prek / pre-commit** — reads `.pre-commit-config.yaml`, `.yml`, or `prek.toml`, converts eligible `local` hooks to shell scripts under the hooks directory, backs up the original config as `.bak`, and attempts `prek uninstall` if the binary is on your PATH.

If both a husky directory and a prek config are present, the command errors and asks you to remove one first.

#### What migrates from prek [#what-migrates-from-prek]

Local hooks with `language: system`, `language: script`, or `language: fail`, plus a curated set of remote hooks from `pre-commit/pre-commit-hooks`, are translated to plain shell + a small bundled Node runner. Everything else still needs the prek binary and is surfaced as a warning or manual step.

| prek feature                                                                                                                                            | migration behavior                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Local `system` / `script` / `fail` hooks                                                                                                                | routed through `.vis/hooks/.builtins/prek-runner.mjs`, which handles staged-file discovery, filters, and chunked argv dispatch                                                      |
| Remote hooks from `pre-commit/pre-commit-hooks` — `trailing-whitespace`, `end-of-file-fixer`, `check-merge-conflict`, `check-json`, `mixed-line-ending` | translated to bundled builtins (no prek binary required at runtime)                                                                                                                 |
| Other remote `repo: https://...` entries                                                                                                                | skipped with a warning                                                                                                                                                              |
| Local hooks with toolchain-managed languages (`python`, `node`, `golang`, `rust`, `ruby`, `docker`, `pygrep`, etc.)                                     | skipped with a warning                                                                                                                                                              |
| `files` / `exclude` (regex filters)                                                                                                                     | preserved — passed as argv flags to the runner, so user strings can't escape into the outer shell                                                                                   |
| `types` / `types_or` / `exclude_types`                                                                                                                  | preserved for the common types (`javascript`, `typescript`, `jsx`, `tsx`, `json`, `yaml`, `markdown`, `html`, `css`, `shell`, `toml`, `python`); unknown types warn and are skipped |
| `always_run`, `pass_filenames: false`                                                                                                                   | forwarded to the runner as flags                                                                                                                                                    |
| `additional_dependencies`                                                                                                                               | merged into `package.json` `devDependencies`; pip-style pins (`name==x`) are surfaced as a manual step instead                                                                      |
| `stages` (including legacy `commit`/`push`/`merge-commit` aliases)                                                                                      | translated to per-stage hook files                                                                                                                                                  |
| `default_stages`                                                                                                                                        | used as the fallback when a hook omits `stages`                                                                                                                                     |
| `pass_filenames: true` on `commit-msg`/`prepare-commit-msg`/`pre-rebase`/`post-*`                                                                       | forwards git's own argument as `"$@"` (bypasses the runner since pre-commit's filter semantics don't apply)                                                                         |
| Top-level `fail_fast: true`                                                                                                                             | prepends `set -e` to each generated script                                                                                                                                          |
| `manual` stage                                                                                                                                          | skipped silently (not a real git hook)                                                                                                                                              |
| `minimum_pre_commit_version`, `ci`, `default_language_version`, `default_install_hook_types`                                                            | ignored                                                                                                                                                                             |
| `prek.toml` (native format)                                                                                                                             | parsed via `@visulima/fs/toml`; YAML takes precedence if both are present                                                                                                           |

#### The bundled runner [#the-bundled-runner]

When a migration emits a hook that needs staged-file discovery or a built-in, the migrator writes `.vis/hooks/.builtins/prek-runner.mjs` — a small Node helper that:

* reads staged files from `git diff --cached --name-only --diff-filter=ACM -z` (null-separated, safe for names with spaces/newlines)
* applies `--files`/`--exclude` regex and `--types`/`--types-or`/`--exclude-types` filters in JavaScript (pre-commit semantics)
* chunks the file list to a conservative 32 KiB argv budget to stay under ARG\_MAX on all platforms
* either dispatches to a named `--builtin` or execs the hook's entry with filtered files as trailing argv

All user-supplied values (regex patterns, filenames, hook args) travel via `process.argv`, never as interpolated shell strings. Commit `.vis/hooks/.builtins/` alongside the rest of the hooks directory so teammates get the same behavior.

## Options [#options]

| Option          | Default      | Applies to | Description                                                         |
| --------------- | ------------ | ---------- | ------------------------------------------------------------------- |
| `--hooks-dir`   | `.vis/hooks` | all        | Custom hooks directory                                              |
| `--dry-run`     | `false`      | `migrate`  | Preview what would be written without touching disk                 |
| `--all-files`   | `false`      | `run`      | Run against every tracked file (sets `VIS_HOOK_ALL_FILES=1`)        |
| `--from-ref`    | —            | `run`      | Run against files changed since this ref (sets `VIS_HOOK_FROM_REF`) |
| `--to-ref`      | —            | `run`      | Run against files changed up to this ref (sets `VIS_HOOK_TO_REF`)   |
| `--last-commit` | `false`      | `run`      | Shortcut for `--from-ref HEAD~1 --to-ref HEAD`                      |

## Environment Variables [#environment-variables]

| Variable               | Description                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `VIS_GIT_HOOKS=0`      | Disable git hooks                                                                            |
| `VIS_GIT_HOOKS=1`      | Force hooks to run even when `skipInCI` would skip them under CI (per-job override)          |
| `VIS_GIT_HOOKS=2`      | Enable debug output for hooks                                                                |
| `VIS_HOOK_ALL_FILES=1` | Tells the bundled runner to discover files via `git ls-files` instead of `git diff --cached` |
| `VIS_HOOK_FROM_REF=…`  | Paired with `VIS_HOOK_TO_REF`, runs the hook against files changed between the two refs      |
| `VIS_HOOK_TO_REF=…`    | Paired with `VIS_HOOK_FROM_REF` (above)                                                      |

## Supported Hooks [#supported-hooks]

vis supports all standard git hooks:

* `pre-commit`
* `pre-merge-commit`
* `prepare-commit-msg`
* `commit-msg`
* `post-commit`
* `applypatch-msg`
* `pre-applypatch`
* `post-applypatch`
* `pre-rebase`
* `post-rewrite`
* `post-checkout`
* `post-merge`
* `pre-push`
* `pre-auto-gc`

## Creating Hook Scripts [#creating-hook-scripts]

After installing, create executable scripts in your hooks directory:

```bash
vis hook install

echo '#!/bin/sh
pnpm run lint-staged' > .vis/hooks/pre-commit

chmod +x .vis/hooks/pre-commit
```

Commit the hooks directory to version control so all team members use the same hooks.


# vis ignore (/docs/packages/vis/commands/ignore)



# vis ignore [#vis-ignore]

Generates a curated set of ignore patterns for files that don't belong in a build context or published package — docs, type-defs, source maps, tests, CI config, editor files — and merges them into an existing ignore file **without adding entries that are already present**. Re-running is idempotent.

Inspired by [`untracked`](https://github.com/Kikobeats/untracked), but reimplemented dependency-free and monorepo-aware.

> Looking for the CI "Ignored Build Step" gate that used to live at `vis ignore`? It moved to [`vis ci ignore`](/docs/packages/vis/commands/ci-ignore).

## Usage [#usage]

```bash
vis ignore [options]
```

## Targets [#targets]

The `--target` flag selects which ignore file to write and which extras to include:

| Target             | File            | Includes `node_modules`?                   |
| ------------------ | --------------- | ------------------------------------------ |
| `docker` (default) | `.dockerignore` | Yes (built inside the image)               |
| `vercel`           | `.vercelignore` | Yes                                        |
| `slug`             | `.slugignore`   | Yes                                        |
| `npm`              | `.npmignore`    | No — npm excludes it from tarballs already |

## Examples [#examples]

```bash
vis ignore                          # print a .dockerignore (deduped against an existing one)
vis ignore --write                  # write/merge .dockerignore in place
vis ignore --target=vercel --write  # write a .vercelignore
vis ignore --target=npm --json      # emit the npm-target result as JSON
```

## Merging (no duplicate entries) [#merging-no-duplicate-entries]

When the target file already exists, `vis ignore` reads it, compares each candidate pattern against the existing entries (verbatim, case-sensitive), and appends **only the missing ones** under a `# Added by vis ignore` section. Entries already present — including any you added by hand — are never duplicated or reordered. If nothing is missing, the file is left untouched.

By default the merged result is printed to stdout; pass `--write` to save it, or `--json` for a machine-readable `{ target, file, added }` record.

## Options [#options]

| Option     | Default  | Description                                           |
| ---------- | -------- | ----------------------------------------------------- |
| `--target` | `docker` | Ignore-file target: `docker`, `vercel`, `npm`, `slug` |
| `--write`  | `false`  | Write the result to disk instead of printing it       |
| `--json`   | `false`  | Emit the result as JSON                               |

## See also [#see-also]

* [`vis docker`](/docs/packages/vis/commands/docker) — Docker scaffold/prune, Dockerfile generation, and hadolint linting
* [`vis ci ignore`](/docs/packages/vis/commands/ci-ignore) — CI "Ignored Build Step" gate for Vercel/Netlify


# vis implode (/docs/packages/vis/commands/implode)



# vis implode [#vis-implode]

Self-uninstall. Removes the `vis` binary, caches, and (with confirmation) any installed Claude Skill / MCP integration. Pair with `--yes` for non-interactive teardown in CI.

## Usage [#usage]

```bash
vis implode [options]
```

## Examples [#examples]

```bash
vis implode
vis implode --yes
```

## Options [#options]

| Option  | Alias | Default | Description                  |
| ------- | ----- | ------- | ---------------------------- |
| `--yes` | `-y`  | `false` | Skip the confirmation prompt |


# vis info (/docs/packages/vis/commands/info)



# vis info [#vis-info]

Show registry metadata for any published package — versions, dependencies, maintainers, dist-tags, license, repository, and more. Wraps the detected package manager's native lookup (`npm view`, `pnpm view`, `yarn info`, `yarn npm info`, `bun pm view`, `deno info`) so the right spelling is used without having to remember each tool's quirks.

## Usage [#usage]

```bash
vis info <package> [field...] [--json]
```

## Examples [#examples]

```bash
# Full registry metadata for react
vis info react

# Just the latest version
vis info react version

# All published versions
vis info react versions

# Dependencies of a specific version
vis info react@18 dependencies

# JSON output for scripting
vis info react --json

# Alias matching npm / pnpm
vis view react
```

## Options [#options]

| Option   | Default | Description                      |
| -------- | ------- | -------------------------------- |
| `--json` | `false` | Emit JSON instead of pretty text |

## How It Works [#how-it-works]

`vis info` detects the active package manager (pnpm, npm, yarn v1, yarn berry, bun, or deno) and forwards the query using the correct command shape for that tool:

| Package manager | Command emitted               |
| --------------- | ----------------------------- |
| npm             | `npm view <pkg> [field…]`     |
| pnpm            | `pnpm view <pkg> [field…]`    |
| yarn v1         | `yarn info <pkg> [field]`     |
| yarn ≥ 2        | `yarn npm info <pkg>`         |
| bun             | `bun pm view <pkg> [field…]`  |
| deno            | `deno info npm:<pkg>` (graph) |

### Limitations [#limitations]

* **yarn v1** only supports a single field at a time — additional fields are dropped with a warning.
* **yarn ≥ 2** (`yarn npm info`) does not accept positional field filters — fields are ignored with a warning; parse the full output yourself (e.g. with `--json | jq`).
* **bun \< 1.3** does not ship `bun pm view` at all — vis prints a warning pointing you at `npm view <pkg>` as a workaround, then lets bun exit with its own "unknown subcommand" error. Upgrade to bun 1.3+ for native support.
* **deno** has no registry-info command. `deno info` is module-rooted (it prints a dependency graph) rather than registry metadata. Bare names are auto-prefixed with `npm:`; `jsr:` / `https:` / `http:` / `file:` specs are passed through unchanged. Field selectors are not supported and are dropped with a warning.

## See also [#see-also]

* `vis why <pkg>` — why a package is installed in *your* workspace (different question).
* `vis check` / `vis outdated` — compare installed versions against the registry's latest.


# vis init (/docs/packages/vis/commands/init)



# vis init [#vis-init]

Initialize a `vis.config.ts` configuration file with best-practice security defaults. In interactive mode, guides you through setting up supply-chain providers (Socket.dev and/or deps.dev), build script approval, git hooks, and PM config sync.

## Usage [#usage]

```bash
vis init [options]
```

## Examples [#examples]

```bash
# Interactive setup wizard
vis init

# Create minimal config without prompts
vis init --no-interactive

# Overwrite existing config
vis init --force

# Also sync to native PM config files
vis init --sync-native

# Print the workspace-relative $schema refs to paste into project.json / vis.config.ts
vis init --schema
```

## Options [#options]

| Option             | Default | Description                                                                                |
| ------------------ | ------- | ------------------------------------------------------------------------------------------ |
| `--force`          | `false` | Overwrite existing config file                                                             |
| `--no-interactive` | `false` | Skip interactive prompts                                                                   |
| `--sync-native`    | `false` | Sync settings to native PM config files                                                    |
| `--schema`         | `false` | Print workspace-relative `$schema` paths for `project.json` and `vis.config.ts`, then exit |

## Interactive Wizard [#interactive-wizard]

The wizard walks through:

1. **Socket.dev** — Enable supply-chain security scanning (Basic-auth token; opt-in)
2. **deps.dev** — Enable Google's OpenSSF Scorecard + GHSA advisory provider (no auth; opt-in). Can run alongside Socket — the two providers merge results, deduped by alert id.
3. **Build scripts** — Scan and approve packages with build scripts
4. **Minimum release age** — Optionally block freshly-published versions. Defaults to &#x2A;*2880 minutes (2 days)** when accepted.
5. **Git hooks** — Set up pre-commit hooks with lint-staged
6. **PM sync** — Sync security settings (allowBuilds + minimumReleaseAge) into the native PM config files (pnpm `pnpm-workspace.yaml`, bun `bunfig.toml`/`package.json`, npm `.npmrc`, yarn berry `.yarnrc.yml`)
7. **Migration detection** — Detect competing monorepo tools (Nx, Turbo) and offer migration

## Static (non-interactive) defaults [#static-non-interactive-defaults]

`vis init --no-interactive` writes a config with `security.minimumReleaseAge: 2880` plus the secure defaults applied automatically by `defineConfig()`. When combined with `--sync-native` the value is also mirrored into the active package manager's native config.

## Related [#related]

* `vis security sync` — re-push the current `vis.config` values to the PM-native config after editing.
* `vis security list` — inspect the build-script triage and the drift report.


# vis inspect (/docs/packages/vis/commands/inspect)



# vis inspect [#vis-inspect]

`vis inspect <pkg>[@<spec>]` runs the pre-install marshall pipeline against a single package and reports its findings without touching the lockfile or `node_modules`. Use it to vet a third-party dependency before a `vis add`, or in code review to surface red flags on a proposed addition.

## Usage [#usage]

```bash
vis inspect <package>[@<spec>] [options]
```

`<spec>` may be a version (`1.2.3`), a semver range (`^18`), or a dist-tag (`latest`, `next`). Defaults to `latest` when omitted.

## Quick examples [#quick-examples]

```bash
vis inspect express                       # latest dist-tag
vis inspect lodash@4.17.21                # exact pin
vis inspect react@^18                     # resolve range, inspect best match
vis inspect express --json                # JSON for CI integration
vis inspect express --strict              # exit non-zero on warnings too
vis inspect express --only author,downloads
vis inspect express --only signatures     # signatures are off by default; opt in here
```

## Marshalls [#marshalls]

Every marshall is identical to the one run during `vis add` / `vis install` / `vis update`:

| Marshall         | What it checks                                                                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `author`         | Recent version + new-publisher + dormant-maintainer heuristics from the packument `time`.                                                 |
| `provenance`     | Regression: prior version had `dist.attestations`, current version dropped them.                                                          |
| `s1ngularity`    | Composite: a version that both changed an install hook AND dropped provenance vs. the prior stable (the Aug 2025 s1ngularity / Nx shape). |
| `newBin`         | The new version introduces additional bin scripts not present in the immediately prior one.                                               |
| `metadata`       | README/license/repository presence, repo URL validity, placeholder README detection.                                                      |
| `downloads`      | Monthly downloads below a configurable warn/error threshold (npm stats API).                                                              |
| `expiredDomains` | Maintainer email domains whose authoritative NS records return NXDOMAIN/ENOTFOUND.                                                        |
| `signatures`     | ECDSA P-256 verification of `dist.signatures` against `/-/npm/v1/keys`.                                                                   |
| `archivedRepo`   | The package's GitHub repo is archived (no longer maintained) or returns 404.                                                              |

## Options [#options]

### `--json` [#--json]

Emit findings as a JSON document instead of the human-readable table:

```bash
vis inspect express --json | jq '.findings[] | select(.severity == "error")'
```

The schema is:

```ts
{
    errors: MarshallFinding[];
    warnings: MarshallFinding[];
    findings: MarshallFinding[];        // errors + warnings, stable order
    summary: { errorCount: number; warningCount: number };
}
```

### `--strict` [#--strict]

Exit non-zero on any finding — warnings included. Default behavior exits 0 when only warnings fire, mirroring the auto-continue countdown semantics on the install path.

### `--only <list>` [#--only-list]

Run only the listed marshalls (comma-separated). Known names: `author`, `provenance`, `s1ngularity`, `newBin`, `metadata`, `downloads`, `expiredDomains`, `signatures`, `archivedRepo`.

```bash
vis inspect lodash --only author,signatures
```

**Signatures are opt-in.** When `--only` is omitted, `signatures` is skipped — matching the pre-install pipeline default in `vis add` / `vis update`. npm's signing-key coverage still produces noisy warnings on legitimate packages, so the marshall only runs when you explicitly request it via `--only signatures`.

## Exit codes [#exit-codes]

| Code | Meaning                                                                |
| ---- | ---------------------------------------------------------------------- |
| 0    | No error findings (warnings allowed unless `--strict`).                |
| 1    | At least one error finding (or any finding with `--strict`).           |
| 2    | Package not found, or `<spec>` did not resolve to a published version. |

## Environment variables [#environment-variables]

Every `MARSHALL_DISABLE_*` toggle and `MARSHALL_DISABLE_ALL` documented in [Wrap your package manager](/docs/packages/vis/guides/shell-alias) applies here as well.

## See also [#see-also]

* [`vis add`](/docs/packages/vis/commands/add) — pre-install pipeline that includes these marshalls.
* [`vis audit`](/docs/packages/vis/commands/audit) — installed-set vulnerability scan.
* [Wrap your package manager](/docs/packages/vis/guides/shell-alias) — alias your PM through vis.


# vis install (/docs/packages/vis/commands/install)



# vis install [#vis-install]

Install project dependencies using the detected package manager (pnpm, npm, yarn, bun, deno, or [aube](https://github.com/endevco/aube)). Delegates to the native PM with vis's security enforcement applied.

## Secure-by-default behavior [#secure-by-default-behavior]

`vis install` applies two universal hardening defaults across every package manager, inspired by the [`npm`'s defaults are bad](https://nesbitt.io/2026/03/31/npms-defaults-are-bad.html) write-up:

1. **Frozen lockfile by default.** When a lockfile is present, `vis install` refuses to mutate it — `npm ci` semantics rather than `npm install`'s silent rewrites. Pass `--no-frozen-lockfile` to opt out (the lockfile-only and `--force` flows skip the default automatically).
2. **Lifecycle scripts blocked by default.** Mirrors pnpm v10: every PM (npm, pnpm, yarn, bun, aube) installs with `--ignore-scripts`. Packages listed in `security.policies.installScripts.allow` (in `vis.config.ts`) get their `preinstall` / `install` / `postinstall` / `prepare` hooks executed afterward by vis. Pass `--run-scripts` to restore the PM's native script behavior for one run. Deno does not run npm-style lifecycle scripts and is unaffected by these flags.

To bypass both at once, combine the flags: `vis install --no-frozen-lockfile --run-scripts`.

## Usage [#usage]

```bash
vis install [options]
```

## Examples [#examples]

```bash
# Install all dependencies (frozen-lockfile + scripts blocked by default)
vis install

# Allow lockfile updates for this run
vis install --no-frozen-lockfile

# Run lifecycle scripts (allowlisted packages run regardless via security.policies.installScripts.allow)
vis install --run-scripts

# Install with frozen lockfile (explicit; same as the default when a lockfile exists)
vis install --frozen-lockfile

# Cache-first install — use cached tarballs when available, fall back to network
vis install --prefer-offline

# Strict offline — fail if any package is not already cached
vis install --offline

# Without optional dependencies
vis install --no-optional

# Force re-install
vis install --force

# Force aube as the installer (errors if not on PATH)
vis install --installer aube

# Bypass aube for one run, use the lockfile-detected PM
vis install --no-aube
```

## Options [#options]

| Option                 | Alias | Default | Description                                                                                                                                            |
| ---------------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--frozen-lockfile`    |       | `false` | Explicitly use frozen lockfile (the default when a lockfile is present)                                                                                |
| `--no-frozen-lockfile` |       | `false` | Opt out of vis's default frozen-lockfile behavior and allow lockfile updates                                                                           |
| `--ci`                 |       | `false` | Clean install: wipes `node_modules` then installs with frozen lockfile (mirrors `npm ci` / `pnpm ci`)                                                  |
| `--force`              | `-f`  | `false` | Force re-resolution of all deps                                                                                                                        |
| `--no-optional`        |       | `false` | Skip optional dependencies                                                                                                                             |
| `--run-scripts`        |       | `false` | Run lifecycle scripts (opts out of the universal block-by-default policy; allowlisted packages still run via `security.policies.installScripts.allow`) |
| `--lockfile-only`      |       | `false` | Update lockfile without installing                                                                                                                     |
| `--offline`            |       | `false` | Strict offline: fail if any package is missing from the cache                                                                                          |
| `--prefer-offline`     |       | `false` | Cache-first: use cached packages when available, fall back to network for the rest                                                                     |
| `--dev`                | `-D`  | `false` | Install devDependencies only                                                                                                                           |
| `--prod`               | `-P`  | `false` | Skip devDependencies                                                                                                                                   |
| `--filter`             | `-F`  |         | Filter to specific workspace packages                                                                                                                  |
| `--installer`          |       | `auto`  | Pick the installer explicitly: `auto`, `aube`, `pnpm`, `npm`, `yarn`, `bun`, `deno`. Overrides `VIS_INSTALLER` and `vis.config`                        |
| `--no-aube`            |       | `false` | Bypass aube and use the lockfile-detected PM. Wins over `--installer`, `VIS_INSTALLER`, and `install.backend`                                          |

## Aube as an installer [#aube-as-an-installer]

[Aube](https://github.com/endevco/aube) is a Rust-native package manager that reads and writes `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, and `bun.lock` in place. `vis install` (and `add`, `remove`, `update`, `dlx`, `exec`, `link`, `unlink`, `dedupe`, `why`, `outdated`, `info`, `pm`) honors aube as a drop-in replacement.

### Selecting the installer [#selecting-the-installer]

Resolution precedence, highest first:

1. `--installer <name>` CLI flag (or `--no-aube` to force the lockfile PM)
2. `VIS_INSTALLER` environment variable
3. `install.backend` in `vis.config.ts`
4. Auto-detect — uses `aube` when it's on `PATH`, otherwise falls back to the lockfile-detected PM

```ts
// vis.config.ts — pin the installer for the whole team
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    install: { backend: "aube" }, // or "auto" | "pnpm" | "npm" | "yarn" | "bun" | "deno"
});
```

```bash
# Per-run override
VIS_INSTALLER=pnpm vis install

# CLI override (wins over env and config)
vis install --installer aube
```

### Installing aube [#installing-aube]

`vis` does not bundle aube — install it once, then enable via the resolution chain above:

```bash
npm install -g @endevco/aube
# or
mise use -g aube
# or
brew install endevco/tap/aube
```

`vis install --installer aube` errors with an actionable message when the binary is missing instead of silently falling back.

### Catalog support [#catalog-support]

Aube supports the pnpm `catalog:` and `catalog:<name>` protocol from `pnpm-workspace.yaml`, including walk-up resolution from subpackages. Visulima's own catalogs (`catalog:dev`, `catalog:lint`, etc.) work transparently.

### Lockfile drift caveat [#lockfile-drift-caveat]

Aube reuses `pnpm-lock.yaml` / `package-lock.json` / `yarn.lock` / `bun.lock` formats but its serialized output is **not byte-identical** to the original tool's. Consequences:

* The first `vis install --installer aube` on a workspace whose lockfile was written by another tool produces a one-time churn diff in git.
* A team that mixes tools on the same lockfile (some on aube, some on pnpm) will see ongoing drift on every install.

`vis install` surfaces a one-line warning when this is about to happen. To eliminate drift, pin `install.backend` in `vis.config.ts` so every team member uses the same installer.

### Lifecycle scripts [#lifecycle-scripts]

Aube already skips dependency lifecycle scripts by default — `--ignore-scripts` is a no-op under aube and `vis install` warns when you pass it. To opt specific packages back in, run `aube approve-builds` (the inverse direction from `pnpm`'s `--ignore-scripts` model).

## How It Works [#how-it-works]

```mermaid
flowchart TD
    A["vis install [options]"] --> B["Detect package manager\n(pnpm, npm, yarn, bun, deno)"]
    B --> C["Build install command\nfrom options"]
    C --> D{Frozen\nlockfile?}
    D -- yes --> E["Map to CI mode\n(npm ci / pnpm --frozen-lockfile)"]
    D -- no --> F["Standard install"]
    E --> G["Run native\ninstall command"]
    F --> G
    G --> H{Exit code\n= 0?}
    H -- yes --> I["Done"]
    H -- no --> J["Report failure"]
```

## Aliases [#aliases]

```bash
vis i          # Short for vis install
```


# vis link (/docs/packages/vis/commands/link)



# vis link [#vis-link]

Wire a local package into the consuming project for live-reload development. With a directory argument, links by path (works on every PM). With no argument or a global package name, registers/uses the global symlink (pnpm ≤ 10, yarn, npm, bun). Aliased as `vis ln`.

## Usage [#usage]

```bash
vis link [target]
vis ln [target]
```

## Examples [#examples]

```bash
vis link ./packages/utils    # link a local directory (works on all PMs)
vis link                     # register current package globally
vis link react               # link a previously-registered global package into the cwd
```

## Options [#options]

This command takes no flags — its behavior is determined by the positional `target`.

## Deno [#deno]

Deno has no `link` equivalent. `vis link` emits a warning and prints guidance: use `"imports"` in `deno.json` (or an import map) to point at a local path or a `jsr:` / `npm:` specifier instead.


# vis lint (/docs/packages/vis/commands/lint)



# vis lint [#vis-lint]

Runs every detected source-code linter against the workspace, normalizes their output into a shared `Finding` shape, and prints them in human, JSON, or minimal format. Designed to add new linters over time without changing the command surface.

Ships with adapters for **oxlint**, **biome**, **ESLint**, **stylelint** (CSS), **ruff** (Python), **markdownlint-cli2** (Markdown), **shellcheck** (shell scripts), and **deno lint**. The orchestrator runs each one that's present in the workspace.

## Usage [#usage]

```bash
vis lint [files…] [options]
```

With no files, the orchestrator runs each adapter against `.` so the tool's own ignore semantics apply. Pass file paths to lint a specific subset.

## Examples [#examples]

```bash
# Run every detected linter
vis lint

# Apply auto-fixes where the tool supports them
vis lint --fix

# Lint a specific subset
vis lint src/foo.ts src/bar.ts

# Emit findings as JSON for CI / editor integrations
vis lint --format json

# Suppress warnings — only errors are reported
vis lint --quiet

# Treat any warning as a failure (per-adapter --max-warnings 0)
vis lint --max-warnings 0

# Only lint files changed vs the main branch
vis lint --since main

# Only lint files currently staged in the git index
vis lint --staged

# Re-run linters whenever watched files change (cache makes incremental near-free)
vis lint --watch

# Write a SARIF report to a file instead of stdout
vis lint --format sarif --output lint.sarif
```

## Options [#options]

| Option           | Default | Description                                                                                  |
| ---------------- | ------- | -------------------------------------------------------------------------------------------- |
| `--fix`          | `false` | Apply auto-fixes in place                                                                    |
| `--format`       | `human` | Output format: `human`, `json`, `minimal`, `sarif`, `junit`, or `github`                     |
| `--quiet`        | `false` | Suppress warnings — report errors only                                                       |
| `--max-warnings` |         | Fail the run if more than N warnings are reported                                            |
| `--since`        |         | Only lint files changed vs the given git ref (branch/tag/sha)                                |
| `--staged`       | `false` | Only lint files currently staged in the git index                                            |
| `--output`       |         | Write formatted output to a file path instead of stdout (also accepts `-`/`stdout`/`stderr`) |
| `--watch`        | `false` | Re-run linters whenever watched files change                                                 |

### `--since` [#--since]

`vis lint --since <ref>` narrows the input to files that changed relative to `<ref>` — committed, staged, unstaged, and untracked all qualify. Each adapter only sees files whose extension it claims, so a CSS-only change skips ESLint and a TS-only change skips stylelint. When `<ref>` doesn't exist (or the directory isn't a git repo) the command falls back to a workspace-wide run and warns.

### `--staged` [#--staged]

`vis lint --staged` narrows the input to files currently in the git index — the same model `lint-staged` uses. Use it in a pre-commit hook to lint only what is about to be committed. Each adapter only sees staged files whose extension it claims. When nothing is staged the command exits early with a `✓ lint: no staged files` message. Outside a git repo (or with git unavailable) the command falls back to a workspace-wide run and warns.

### `--watch` [#--watch]

`vis lint --watch` keeps the command running, runs an initial cycle, and then re-runs whenever a file matching any eligible adapter's extension set changes. Events are debounced (200 ms) and coalesced — concurrent edits batch into a single follow-up run rather than queueing one per keystroke. The orchestrator's content-addressed cache means the incremental cycle only spawns the tools whose inputs actually changed. The loop watches the workspace root recursively (via Watchman when available, falling back to `node:fs.watch`) and ignores `node_modules`, `.git`, and `.vis`. Exit with Ctrl-C (SIGINT) or SIGTERM.

### `--output` [#--output]

`vis lint --output <path>` writes the reporter payload to a file instead of stdout. The file's parent directory is created as needed; the special values `-` and `stdout` route to `process.stdout` and `stderr` routes to `process.stderr`. The flag only applies to machine-readable formats (`json`, `minimal`, `sarif`, `junit`, `github`) — combining it with the default `human` format logs a warning and is ignored.

## Pre-commit integration [#pre-commit-integration]

`vis lint --staged --fix` is the recommended entry for the `staged` block in `vis.config.ts` — it auto-detects every installed linter, only sees staged files, and applies fixes in place so the commit ends up with the cleaned tree. Pair it with `vis fmt --staged` to enforce formatting alongside lint fixes.

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    staged: {
        "*": ["vis lint --staged --fix", "vis fmt --staged"],
    },
});
```

`vis init` scaffolds exactly this block when pre-commit hooks are enabled; `vis hook install` then wires `.vis/hooks/pre-commit` to invoke `vis staged`. In CI, `vis ci lint test build` runs lint as part of the affected-targets pipeline — no extra plumbing required.

## Caching [#caching]

When `vis lint` is invoked with an explicit file list or `--since`, results are cached under `<workspaceRoot>/.vis/cache/lint-fmt/<adapter>/` keyed by the adapter's config fingerprint plus a SHA-256 of every input file's bytes. A subsequent run with the same inputs replays the stored `RunResult` instead of spawning the tool.

The cache is skipped for:

* `--fix` runs (writes mutate the working tree)
* workspace-wide runs that pass `.` (the file vector is unbounded)
* runs where `VIS_NO_CACHE=1` is set

Failed or killed processes are never stored. Clear the cache with `vis cache clean` or by removing the directory directly.

## Detection [#detection]

The orchestrator probes each adapter against the workspace root and runs the ones that report themselves present. An adapter opts in when **either** a tool-native config file exists **or** the tool is declared in `package.json` (any dep field).

| Adapter      | Config files probed                                                                                                   | package.json key                        |
| ------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| oxlint       | `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.json`, `oxlint.jsonc`                                                    | `oxlint`                                |
| biome        | `biome.json`, `biome.jsonc`                                                                                           | `@biomejs/biome`                        |
| eslint       | `eslint.config.{js,mjs,cjs,ts,mts}`, `.eslintrc`, `.eslintrc.{js,cjs,json,yaml,yml}`                                  | `eslint`                                |
| stylelint    | `stylelint.config.{ts,js,mjs,cjs}`, `.stylelintrc`, `.stylelintrc.{json,js,cjs,yml,yaml}`                             | `stylelint`                             |
| ruff-check   | `ruff.toml`, `.ruff.toml`, `pyproject.toml` with `[tool.ruff]`                                                        | `ruff`, `@astral-sh/ruff`               |
| markdownlint | `.markdownlint.{json,jsonc,yaml,yml}`, `.markdownlintrc[.{json,yaml,yml}]`, `.markdownlint-cli2.{jsonc,yaml,cjs,mjs}` | `markdownlint-cli2`, `markdownlint-cli` |
| shellcheck   | `.shellcheckrc` (system binary — not an npm package)                                                                  | `shellcheck`                            |
| deno-lint    | `deno.json`, `deno.jsonc` (no npm package — `deno` is a runtime)                                                      | —                                       |

When multiple lint adapters are detected, they run in this default precedence: `oxlint → biome → eslint → stylelint → ruff-check → markdownlint → shellcheck → deno-lint`. The Rust-native oxlint pass runs first as a fast pre-filter, biome handles its bespoke rule set, ESLint catches what the others don't, stylelint covers CSS/SCSS, and deno-lint runs last since deno coexists with the npm-native pipeline rather than replacing it. Override with `lint.order` in `vis.config.ts`.

## Configuration [#configuration]

`vis.config.ts` exposes a `lint` block for workspace-wide tuning. CLI flags always win over config.

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    lint: {
        // Override the default precedence; unlisted adapters still run, appended after.
        order: ["biome", "eslint"],
        adapters: {
            // Skip an adapter even when its config is detected.
            "deno-lint": { enabled: false },
            // Append flags verbatim to every eslint invocation.
            eslint: { extraArgs: ["--rulesdir", "./eslint-rules"] },
        },
    },
});
```

## Output formats [#output-formats]

### Human (default) [#human-default]

Per-file blocks with `line:column severity message  ruleId`. A trailing line reports total errors and warnings.

### JSON [#json]

```json
{
    "findings": [
        {
            "adapter": "eslint",
            "file": "/repo/src/a.ts",
            "fixable": false,
            "line": 10,
            "column": 5,
            "message": "...",
            "ruleId": "no-bad",
            "severity": "error"
        }
    ],
    "runs": [{ "adapter": "eslint", "durationMs": 1234, "exitCode": 1, "findingCount": 1 }]
}
```

### Minimal [#minimal]

Tab-separated lines, one per finding, suitable for `awk`/`cut` pipelines:

```
eslint	src/a.ts	10	5	error	no-bad	'foo' is not defined
```

### SARIF [#sarif]

`--format sarif` emits a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html) document on stdout — one `run` per adapter, with `tool.driver.rules` aggregated from the findings. File paths under `workspaceRoot` are emitted relative to a `SRCROOT` `uriBaseId` so the report is portable across machines. Use this format with the [GitHub code-scanning upload action](https://github.com/github/codeql-action) or any other SARIF-aware ingestor.

### JUnit [#junit]

`--format junit` emits a Surefire-flavoured JUnit XML report — one `<testsuite>` per adapter and one `<testcase>` per finding. Errors land as `<failure type="error">`, warnings as `<failure type="warning">`. GitLab CI, GitHub Actions test reporters, Jenkins and Bitbucket all parse this dialect without an extra plugin.

### GitHub Actions [#github-actions]

`--format github` emits [workflow commands](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions) — one `::error|warning|notice file=…,line=…,col=…,title=…::message` line per finding — so the Actions runner annotates the corresponding lines inline in the pull request. File paths are emitted relative to the workspace root so GitHub resolves them against the checked-out tree. Multi-line messages and reserved characters in property values are percent-encoded per spec.

## Exit codes [#exit-codes]

* `0` — no errors and every adapter exited cleanly
* `1` — at least one error finding, or at least one adapter exited non-zero without producing any findings (process-level failure)

Warnings alone do not fail the run — that's `--max-warnings`' job.


# vis list (/docs/packages/vis/commands/list)



# vis list [#vis-list]

List all workspace projects with their type, layer, tags, and target counts. Add `--targets` for one row per `(project, target)` with cache status and description.

## Usage [#usage]

```bash
vis list [options]
```

## Examples [#examples]

```bash
vis list                                 # all projects with type, layer, tags, targets
vis list --targets                       # per-target rows
vis list --deps                          # human-readable dep-instance table
vis list --deps --internal-only          # only workspace deps
vis list --deps --format=ndjson          # stream every dep-instance as NDJSON for jq pipelines
vis list --deps --format=json --pretty   # single pretty-printed JSON array
vis list --format=json                   # machine-readable project listing
vis list --query "tag=frontend"          # filter by query
vis list --targets --format=json         # per-target rows as JSON
```

## Options [#options]

| Option            | Default | Description                                                                                         |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `--format`        | `table` | Output format: `table`, `json` (single document), or `ndjson` (one record per line; `--deps` only)  |
| `--pretty`        | `false` | Pretty-print with 2-space indent (only meaningful with `--format=json` in `--deps` mode)            |
| `--query`         |         | Filter projects by query (see below)                                                                |
| `--targets`       | `false` | Show per-target rows (type, cache, description)                                                     |
| `--inferred`      | `false` | Filter target rows to only inferred targets (implies `--targets`)                                   |
| `--deps`          | `false` | Render a dep-instance view (table by default; use `--format=ndjson`/`json` for jq-friendly streams) |
| `--dep-type`      |         | With `--deps`: restrict to specific dep blocks. Repeatable.                                         |
| `--internal-only` | `false` | With `--deps`: only show internal/workspace deps                                                    |
| `--external-only` | `false` | With `--deps`: only show external/registry deps                                                     |
| `--include`       |         | With `--deps`: glob of declaring package names to keep. Repeatable.                                 |
| `--exclude`       |         | With `--deps`: glob of declaring package names to drop. Repeatable.                                 |

## `--deps` columns [#--deps-columns]

When `--deps` is set, the table shows one row per `(declaring package, dep block, dep name)`:

| Column      | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `Package`   | `package.json#name` of the declaring package (or directory when no name)            |
| `Block`     | Dep block: `dependencies`, `devDependencies`, `peerDependencies`, `pnpm.overrides`… |
| `Dep`       | Dependency name (with scope)                                                        |
| `Specifier` | Verbatim version string as written in `package.json`                                |
| `Internal`  | `yes` when the dep resolves to another workspace package, otherwise `no`            |
| `Path`      | Workspace-relative path of the source `package.json` (or `pnpm-workspace.yaml`)     |

## `--deps --format=ndjson` record shape [#--deps---formatndjson-record-shape]

Each NDJSON line (or array entry under `--format=json`) has the same shape:

```json
{
    "packageName": "@my/app",
    "packageDir": "apps/app",
    "packageJsonPath": "apps/app/package.json",
    "depType": "dependencies",
    "depName": "react",
    "specifier": "^18.2.0",
    "isInternal": false
}
```

`packageJsonPath` is workspace-relative for portability across CI runners. `isInternal: true` indicates the dep name resolves to another workspace package. `pnpm-workspace.yaml#overrides` (pnpm v9+ moved `pnpm.overrides` from `package.json` into the workspace config) surfaces under `depType: "pnpm.overrides"` with `packageJsonPath` pointing at `pnpm-workspace.yaml`.

### `jq` recipes [#jq-recipes]

Count how many packages declare each dep:

```bash
vis list --deps --format=ndjson | jq -r '.depName' | sort | uniq -c | sort -rn | head
```

List every package that pins a specific dep:

```bash
vis list --deps --format=ndjson | jq -r 'select(.depName == "react") | "\(.packageName)\t\(.specifier)"'
```

Find specifier drift for a single dep (alternative to `vis deps --workspace-versions --dep <name>`):

```bash
vis list --deps --format=ndjson | jq -r 'select(.depName == "react") | .specifier' | sort -u
```

Audit which packages still declare a banned dep before turning on `vis deps --banned-deps`:

```bash
vis list --deps --format=ndjson | jq -r 'select(.depName | IN("left-pad","request","moment")) | "\(.packageName)\t\(.depName)"'
```

## Default columns [#default-columns]

| Column    | Source                                                    |
| --------- | --------------------------------------------------------- |
| `Project` | `package.json#name`                                       |
| `Type`    | `project.json#projectType` (defaults to `library`)        |
| `Layer`   | `project.json#layer`                                      |
| `Tags`    | `project.json#tags`                                       |
| `Targets` | Comma list of target names (truncated to 4 + total count) |

## `--targets` columns [#--targets-columns]

When `--targets` is set, the table shows one row per `(project, target)`:

| Column        | Description                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| `Project`     | `package.json#name`                                                                                     |
| `Target`      | Target name from `project.json#targets` (alphabetical)                                                  |
| `Type`        | Target's semantic `type` (`build` / `test` / `run`); `—` when unset                                     |
| `Cache`       | `yes` when `cache: true`, `no` when `cache: false`, `default` when unset (the runtime picks per `type`) |
| `Description` | The target's `description` field surfaced from `project.json` / `vis.task.ts`; `—` when unset           |

The footer reports the row count and the number of distinct projects.

## Query filter [#query-filter]

`--query` accepts the same syntax as [`vis run --query`](/docs/packages/vis/commands/run#query-language) — clauses joined by `&&` (all match) or `||` (any matches), filtered against project metadata fields (`tag`, `layer`, `language`, `stack`, `type`, etc.).

```bash
vis list --query "language=typescript && tag=lib"
vis list --targets --query "tag=frontend"
```


# vis migrate (/docs/packages/vis/commands/migrate)



# vis migrate [#vis-migrate]

Translates configuration from competing monorepo tools into vis format. Non-destructive — original config files are left in place for review.

## Usage [#usage]

```bash
vis migrate              # interactive TUI — pick which migrations to run
vis migrate <type> [options]
```

Running `vis migrate` with no subcommand opens an interactive terminal UI that
auto-detects every migration applicable to the current workspace, lets you
toggle each one on or off, and shows a per-migration preview of what will
change before you apply.

## Migration Types [#migration-types]

### turborepo [#turborepo]

Reads `turbo.json` and writes `vis.config.ts` with equivalent `tasks`:

```bash
vis migrate turborepo
vis migrate turborepo --dry-run    # Preview without writing
```

Translates:

* `tasks` / `pipeline` entries → `tasks`
* `^build` dependsOn → `{ dependencies: true, target: "build" }`
* `project#task` → `{ projects: "project", target: "task" }`
* `globalDependencies` → `taskRunner.globalInputs`
* `globalEnv` → `taskRunner.globalEnv`
* `persistent` / `interactive` → `options.persistent` / `options.interactive`

Remote cache is flagged in the migration report (vis uses the same Turborepo HTTP protocol).

### nx [#nx]

Reads `nx.json` and writes `vis.config.ts`:

```bash
vis migrate nx
vis migrate nx --dry-run
```

Translates:

* `namedInputs` → `namedInputs`
* `targetDefaults` → `tasks`

Per-project `project.json` files are **left untouched** — vis reads them natively (targets, tags, implicitDependencies, sourceRoot).

### moon [#moon]

Reads `.moon/tasks.yml` (or the first file in `.moon/tasks/`) and writes `vis.config.ts`:

```bash
vis migrate moon
vis migrate moon --dry-run
```

Translates:

* `tasks` → `tasks` (command + args merged, deps, inputs, outputs, type, preset, options)
* `fileGroups` → `fileGroups`
* `implicitInputs` → `namedInputs.default`

Per-project `moon.yml` files should be manually converted to `project.json` — the field names match (targets, tags, layer, stack, language, owners).

### deps [#deps]

Migrates package dependencies and scripts (husky → vis hooks):

```bash
vis migrate deps
```

### lint-staged [#lint-staged]

Merges lint-staged config into `vis.config.ts` staged block:

```bash
vis migrate lint-staged
```

### nano-staged [#nano-staged]

Same surface as `lint-staged` but for [nano-staged](https://github.com/usmanyunusov/nano-staged). Detects any of `.nano-staged.json`, `.nanostagedrc`, `.nano-staged.{js,cjs,mjs}`, `nano-staged.config.{js,cjs,mjs,ts,cts,mts}`, or a `nano-staged` block in `package.json`, and inlines the patterns into the `staged` field of `vis.config.ts`:

```bash
vis migrate nano-staged
vis migrate nano-staged --dry-run
```

JSON-format configs and `package.json#nano-staged` are auto-migrated; TS/JS configs are flagged with a manual step (no sandboxed evaluator). The `nano-staged` dependency and any `\bnano-staged\b` scripts are stripped (the latter is folded into `vis staged` by `vis migrate deps`).

### gitleaks [#gitleaks]

Converts a [gitleaks](https://github.com/gitleaks/gitleaks) setup into `vis secrets`:

```bash
vis migrate gitleaks
vis migrate gitleaks --dry-run
```

**Detects:**

* Config: `gitleaks.toml` / `.gitleaks.toml`
* Ignore file: `.gitleaksignore`
* Baseline: `gitleaks-report.json` / `.gitleaks-report.json` / `baseline.json`

**Auto-migrated:**

* The baseline JSON is converted to vis's allowlist shape and written into `vis.config.ts` (`secrets.allowlist`).
* `.gitleaksignore` fingerprints (`file:rule:line`) are translated to allowlist entries.
* Scripts matching `\bgitleaks\b` are rewritten to `vis secrets` invocations (with the original line preserved as a manual step when the mapping is ambiguous).
* Pre-commit hooks (`.husky/pre-commit`, `.vis/hooks/pre-commit`, `.git/hooks/pre-commit`) referencing `gitleaks` are rewritten to call `vis secrets`.

**Routed to manual steps:**

* `gitleaks.toml` (the rule definitions) is left in place — vis ships its own rule set, so the original config is preserved for reviewer comparison rather than translated.
* Custom regex rules: review and re-add them via `secrets.extraRules` in `vis.config.ts` if needed.

### kingfisher [#kingfisher]

Converts a [Kingfisher](https://github.com/mongodb/kingfisher) (MongoDB's secret scanner) setup into `vis secrets`:

```bash
vis migrate kingfisher
vis migrate kingfisher --dry-run
```

**Detects:**

* Baseline: `kingfisher-baseline.{yaml,yml}` / `.kingfisher-baseline.{yaml,yml}`
* Custom rules: `kingfisher-rules.{yaml,yml}` / `.kingfisher-rules.{yaml,yml}`

**Auto-migrated:**

* The YAML baseline is parsed and converted to vis allowlist entries (one per finding); each entry is annotated with a placeholder so reviewers can fill in the matched rule's vis equivalent.
* Scripts matching `kingfisher (scan|validate|rules|update|manage-baseline|report|github|gitlab|bitbucket)` are rewritten to `vis secrets` invocations.
* Pre-commit hooks referencing `kingfisher` are rewritten.

**Routed to manual steps:**

* `kingfisher-rules.{yaml,yml}` is flagged but **not auto-translated** — Kingfisher's rule DSL doesn't have a direct vis equivalent. Review the rules and add the ones you still need to `secrets.extraRules`.
* Baseline entries that the migrator can't map cleanly include a placeholder `// TODO: review` comment.

### secretlint [#secretlint]

Replaces a [secretlint](https://github.com/secretlint/secretlint) setup with `vis secrets`:

```bash
vis migrate secretlint
vis migrate secretlint --dry-run
```

**Detects:**

* Config: `.secretlintrc[.{json,js,mjs,cjs,yml,yaml}]`
* Ignore file: `.secretlintignore`

**Auto-migrated:**

* Active rule IDs are extracted from JSON/YAML configs and surfaced in the migration report so reviewers see what they had enabled.
* Scripts matching `\bsecretlint\b` are rewritten to `vis secrets` invocations.
* Pre-commit hooks referencing `secretlint` are rewritten.
* `.secretlintignore` is converted to vis allowlist entries.
* `secretlint` and `@secretlint/*` are removed from `dependencies` / `devDependencies`.
* `.secretlintrc.{json,yml,yaml}` is backed up (`.bak`) and removed.

**Routed to manual steps:**

* `.secretlintrc.{js,mjs,cjs}` configs are flagged but not auto-removed — `vis migrate` does not load executable config (no sandboxed evaluator). Convert to JSON or YAML first, or apply manually.
* Custom rule packages (`@secretlint/secretlint-rule-*`) are listed for the reviewer; vis bundles its own rule set, so the user decides whether each upstream rule is still needed.

### syncpack [#syncpack]

Translates the parts of a [syncpack](https://jamiemason.github.io/syncpack/) config that vis can act on today, strips the `syncpack` dependency / scripts, and routes the rest into `manualSteps` so reviewers see what's still pending:

```bash
vis migrate syncpack
vis migrate syncpack --dry-run
```

**Detects** (in priority order):

* `package.json#syncpack`
* `.syncpackrc` (parsed as JSON, falling back to YAML)
* `.syncpackrc.json`
* `.syncpackrc.yaml` / `.syncpackrc.yml`

**Auto-migrated:**

* `customTypes` (record) → `policy.customTypes.extraTypes` (array). Entries colliding with vis built-ins (`engines`, `volta`, `packageManager`, `devEngines.runtime`, `devEngines.packageManager`) are dropped with a warning — vis already lints those surfaces natively.
* `versionGroups[].isBanned: true` → `policy.bannedDeps`. Entries with a `packages` scope translate to the scoped object form (`{ packages, reason }`); unscoped entries become the string form. Conflicts (two banned groups targeting the same dep) keep the first match and warn.
* `syncpack` removed from `dependencies` / `devDependencies`.
* Any `scripts` matching `\bsyncpack\b` are deleted.
* `.syncpackrc{,.json,.yaml,.yml}` is backed up (`.bak`) and removed.
* The `syncpack` block inside `package.json` is removed.
* `syncpack` is stripped from catalog protocol locations: `pnpm-workspace.yaml#catalog`/`catalogs.<name>` and bun's `package.json#workspaces.catalog`/`workspaces.catalogs.<name>` (and the top-level `package.json#catalog`).

**Routed to manual steps:**

* Removed scripts are surfaced individually (one manual step each) with their full original text — mixed commands like `syncpack lint && eslint .` would otherwise lose the non-syncpack half silently.
* `versionGroups` (non-banned) and `semverGroups` — `pinVersion`, `snapTo`, `policy: "sameRange"`, and the broader DSL surface are deferred to [issue #622](https://github.com/visulima/visulima/issues/622).
* `dependencyTypes`, `specifierTypes`, `filter` — no direct vis equivalent today; reviewer is prompted to recreate them with `policy.*` filters.
* `source` (workspace globs) — vis derives these from `pnpm-workspace.yaml` / `package.json#workspaces`; reviewer is asked to verify they match.
* Pre-commit hooks (`.husky/pre-commit`, `.vis/hooks/pre-commit`, `.git/hooks/pre-commit`) referencing `syncpack` are flagged but **not auto-rewritten** — `syncpack lint` ≈ `vis deps` and `syncpack format` ≈ `vis sort-package-json`, but `fix-mismatches` / `set-semver-ranges` have no 1:1 mapping. The reviewer makes the call.
* CI workflow files (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `.circleci/config.yml`, `.woodpecker.yml`, `.drone.yml`) referencing `syncpack` are flagged with a manual step — YAML rewriting is too brittle to automate.

**Superseded (no migration needed):**

* `sortAz`, `sortFirst`, `sortExports`, `sortPackages`, `formatBugs`, `formatRepository` — handled by `vis sort-package-json`.
* `lintFormatting`, `lintSemverRanges`, `lintVersions` — covered by `vis deps` by default.
* `indent` — vis honors `.editorconfig` (when `editorconfig: true`), so explicit indent config is unnecessary.

**Not supported in v1:**

TS/JS configs (`.syncpackrc.{cjs,js,mjs,ts}`, `syncpack.config.{cjs,js,mjs,ts}`) are flagged with a manual step — `vis migrate` does not load executable config (no sandboxed evaluator). Convert them to `.syncpackrc.json` first, then re-run. Tracked in [#622](https://github.com/visulima/visulima/issues/622).

### sherif [#sherif]

Strips the `sherif` dep / scripts / `package.json#sherif` block and surfaces a positive `vis deps --<rule>` command suggestion (vis has no global rule-disable, so the migration translates sherif's `ignore-rules` into the explicit "rules to keep enabled" form):

```bash
vis migrate sherif
vis migrate sherif --dry-run
```

**Detects:**

* `package.json#sherif`
* `sherif` in `dependencies` / `devDependencies`
* Any `scripts` matching `\bsherif\b`

**Auto-migrated:**

* `sherif` removed from `dependencies` / `devDependencies`.
* Any `scripts` matching `\bsherif\b` are deleted (raw text preserved as a manual step so mixed commands aren't lost silently).
* The `sherif` block inside `package.json` is removed.
* A `.bak` of `package.json` is created before mutation.

**Sherif → vis deps mapping:**

| Sherif rule (in `ignore-rules`) | vis deps flag                                        |
| ------------------------------- | ---------------------------------------------------- |
| `empty-dependencies`            | `--empty-deps`                                       |
| `multiple-dependency-versions`  | `--workspace-versions`                               |
| `non-existant-packages`         | `--dead-workspace-patterns`                          |
| `packages-without-package-json` | `--missing-package-json`                             |
| `root-package-dependencies`     | `--root-deps`                                        |
| `root-package-manager-field`    | `--root-package-manager`                             |
| `root-package-private-field`    | `--root-private`                                     |
| `types-in-dependencies`         | `--types-in-deps`                                    |
| `unsync-similar-dependencies`   | `--similar-deps`                                     |
| `unordered-dependencies`        | *no equivalent* — covered by `vis sort-package-json` |

**Routed to manual steps:**

* `ignore-rules` (when set) → suggested replacement script: `vis deps --<rule> --<rule> ...` listing every covered rule *except* the disabled ones.
* `ignore-dependencies` → mirror in `vis.config.ts` under `policy.workspaceVersions.ignore`, `policy.customTypes.ignore`, `policy.typesInDeps.ignore`, `policy.redefineRoot.ignore` (per-rule scoping in vis vs. global in sherif).
* `ignore-packages` / `ignore-paths` → flagged for review; vis has no global package/path-skip yet (only per-rule scoping via `policy.bannedDeps.{packages,paths}`).
* Pre-commit hooks and CI workflows referencing `sherif` are flagged but not auto-rewritten — the reviewer chooses the right `vis deps` flag set.

### self [#self]

Rewrites an existing `vis.config.ts` / `vis.task.ts` (and any `extends` chain) to use the current field names after a vis hard-break rename. Run after upgrading vis when `VisConfigDeprecatedKeyError` fires at load time.

```bash
vis migrate self
vis migrate self --dry-run    # Preview without writing
```

**Current rename table** (vis 1.x → 2.0):

| Previous                      | New                      |
| ----------------------------- | ------------------------ |
| `VisConfig.targetDefaults`    | `VisConfig.tasks`        |
| `VisConfig.taskDefaults`      | `VisConfig.scopedTasks`  |
| `VisConfig.taskRunnerOptions` | `VisConfig.taskRunner`   |
| `ScopedTasksBlock.scope`      | `ScopedTasksBlock.match` |
| `ScopedTasksBlock.targets`    | `ScopedTasksBlock.tasks` |
| `VisTaskConfig.targets`       | `VisTaskConfig.tasks`    |

Rewrites `vis.config.{ts,mts,cts,js,mjs,cjs}` at the workspace root and every `vis.task.{ts,mts,cts,js,mjs,cjs}` overlay found beneath it (`node_modules`, `.git`, `.vis/`, and common build output directories are skipped). Source files are rewritten only when they contain an old key; a `.bak` is created next to each modified file. `--dry-run` lists which files would change without touching disk.

JSON configs and files referenced via `extends` are out of scope — rewrite those by hand (the rename table above is the full diff).

### verify [#verify]

Read-only audit that exits non-zero if it finds any leftover `gitleaks`, `secretlint`, `sherif`, or `syncpack` references. Scans `package.json` scripts/devDependencies/`#sherif` block, pre-commit hooks, stale config files, CI workflow files, and catalog protocol entries (pnpm-workspace.yaml + bun catalog). Useful as a CI gate after a migration.

```bash
vis migrate verify
```

### verify-graph [#verify-graph]

Proves a `turbo` / `nx` / `moon` → vis migration preserved the task graph and the cache-key surface. Migration coverage is not migration correctness — `verify-graph` reads the original source config and the migrated `vis.config.*` side by side, normalizes both into a tool-agnostic task graph, and reports every divergence. "Adopt risk-free" is only credible when you can prove the migration kept semantics; this is that proof, and it is CI-gateable.

```bash
vis migrate verify-graph                              # auto-detect source tool, diff vs vis.config.*
vis migrate verify-graph --from turbo --format json   # machine-readable report on stdout
vis migrate verify-graph --fail-on warning            # also gate on additive/extra-target warnings
```

The source tool is auto-detected when exactly one of `turbo.json`, `nx.json`, or `.moon/` is present; pass `--from turbo|nx|moon` to disambiguate. Each task is compared across six axes:

| Axis         | Meaning                                                          |
| ------------ | ---------------------------------------------------------------- |
| `target-set` | A task present in the source is missing from the migrated config |
| `dependsOn`  | Dependency edges (normalized across `^`/`#`/`^:`/`~:` dialects)  |
| `inputs`     | Cache-key input globs                                            |
| `outputs`    | Declared output globs                                            |
| `env`        | Environment variables that participate in the cache key          |
| `cache`      | The cache enable/disable flag                                    |

A dropped task, a lost dependency edge, or a narrowed input/output/env set is an **error** (exit 1). A purely additive change in the migrated config (an extra task, a widened input set) is a **warning** and does not fail by default. Turbo `project#task` overrides that the migrator deliberately folds into a base task are reported as a non-fatal `warning` ("skipped by design"). Pass `--fail-on warning` to gate CI on warnings too.

`--format` selects the report shape: `table` (default, human-readable, written to the logger), `json` (a single deterministic object), or `ndjson` (one finding per line). `json` and `ndjson` are written to **stdout only** and are byte-stable across runs, so they can be diffed or piped into other tooling.

## Options [#options]

| Option      | Default         | Applies to        | Description                                                |
| ----------- | --------------- | ----------------- | ---------------------------------------------------------- |
| `--dry-run` | `false`         | all but verifiers | Preview changes without writing to disk                    |
| `--from`    | *auto-detected* | `verify-graph`    | Source tool to compare against (`turbo` \| `nx` \| `moon`) |
| `--format`  | `table`         | `verify-graph`    | Report format (`table` \| `json` \| `ndjson`)              |
| `--fail-on` | `error`         | `verify-graph`    | Exit non-zero on `error` (default) or also on `warning`    |


# vis optimize (/docs/packages/vis/commands/optimize)



# vis optimize [#vis-optimize]

Two-phase dependency optimization with an interactive TUI. Phase 1 surfaces packages replaceable with native builtins or lighter alternatives (via [e18e](https://e18e.dev) `module-replacements`) and runs codemods on selected entries. Phase 2 writes `overrides` / `resolutions` for packages that have security-hardened `@socketregistry` alternatives.

In TTY mode it presents a picker; in non-TTY (CI) it prints a static report.

## Usage [#usage]

```bash
vis optimize [options]
```

## Examples [#examples]

```bash
vis optimize                  # interactive TUI
vis optimize --dry-run        # preview only
vis optimize --pin            # pin Socket overrides to exact versions
vis optimize --prod           # only optimize production deps
```

## Options [#options]

| Option         | Alias | Default | Description                                      |
| -------------- | ----- | ------- | ------------------------------------------------ |
| `--dry-run`    | `-d`  | `false` | Preview available optimizations without applying |
| `--pin`        |       | `false` | Pin Socket.dev overrides to exact versions       |
| `--prod`       |       | `false` | Only optimize production dependencies            |
| `--no-install` |       | `false` | Skip running install after applying overrides    |
| `--format`     |       | `table` | Output format: `table` or `json`                 |


# vis outdated (/docs/packages/vis/commands/outdated)



# vis outdated [#vis-outdated]

Report packages whose installed version is behind the latest published version. Delegates to the detected PM (`pnpm outdated`, `npm outdated`, `yarn outdated`, `bun outdated`, `deno outdated`) and normalizes the output.

## Usage [#usage]

```bash
vis outdated [packages...] [options]
```

## Examples [#examples]

```bash
vis outdated
vis outdated react
vis outdated --format json
vis outdated -r                      # all workspaces
vis outdated --compatible            # only semver-compatible updates (pnpm)
```

## Options [#options]

| Option             | Alias | Default | Description                                   |
| ------------------ | ----- | ------- | --------------------------------------------- |
| `--long`           |       | `false` | Show extended information                     |
| `--format`         |       | `table` | Output format: `table`, `list`, or `json`     |
| `--recursive`      | `-r`  | `false` | Check all workspaces                          |
| `--workspace-root` | `-w`  | `false` | Include workspace root                        |
| `--prod`           | `-P`  | `false` | Production dependencies only (pnpm)           |
| `--dev`            | `-D`  | `false` | Dev dependencies only (pnpm)                  |
| `--no-optional`    |       | `false` | Exclude optional dependencies (pnpm)          |
| `--compatible`     |       | `false` | Show only semver-compatible updates (pnpm)    |
| `--global`         | `-g`  | `false` | Check globally installed packages             |
| `--filter`         | `-F`  |         | Filter by workspace package name (repeatable) |


# vis pm (/docs/packages/vis/commands/pm)



# vis pm [#vis-pm]

Pass-through to the detected package manager's miscellaneous subcommands — cache management, publishing, auditing, listing, config, identity. The first positional becomes the PM subcommand and everything after it is forwarded.

## Usage [#usage]

```bash
vis pm <subcommand> [args...]
```

## Examples [#examples]

```bash
vis pm cache dir              # show cache directory
vis pm cache clean            # clean cache
vis pm publish --dry-run      # preview publishing
vis pm list --depth 0         # list direct dependencies
vis pm audit                  # run security audit
vis pm whoami                 # show logged-in user
vis pm plugin list            # yarn berry plugins (no-op on other PMs)
```

## Options [#options]

This command takes no flags of its own — every argument is forwarded to the resolved package manager. The PM is selected via the same precedence as [`vis install`](/docs/packages/vis/commands/install) (CLI `--installer` > `VIS_INSTALLER` > `install.backend` > auto).

## Cross-PM behavior [#cross-pm-behavior]

Some subcommands move between namespaces or were removed entirely depending on the PM. `vis pm` papers over the differences when there is a sensible substitution, and warns + exits 0 when there is not.

| Subcommand                            | Substitution                                                               |
| ------------------------------------- | -------------------------------------------------------------------------- |
| `whoami` (pnpm 11)                    | falls back to `npm whoami` (pnpm 11 removed `whoami`)                      |
| `whoami` (yarn berry)                 | rewrites to `yarn npm whoami`                                              |
| `whoami` (bun)                        | rewrites to `bun pm whoami`                                                |
| `login` / `logout` (yarn berry)       | rewrites to `yarn npm login` / `yarn npm logout`                           |
| `login` / `logout` (bun)              | falls back to `npm login` / `npm logout` (bun reads `~/.npmrc`)            |
| `audit` (yarn berry)                  | rewrites to `yarn npm audit`                                               |
| `publish` (yarn berry)                | rewrites to `yarn npm publish`                                             |
| `dist-tag` (yarn 1)                   | rewrites to `yarn tag`                                                     |
| `dist-tag` (yarn berry)               | rewrites to `yarn npm tag` (and translates `rm` → `remove`)                |
| `owner` (pnpm 11 / yarn berry / bun)  | falls back to `npm owner`                                                  |
| `ping` / `search` / `token` (pnpm 11) | falls back to `npm <sub>` (pnpm 11 removed each)                           |
| `config delete` (yarn berry)          | rewrites to `yarn config unset`                                            |
| `plugin` (anything but yarn berry)    | warn + exit 0                                                              |
| `prune` (yarn / bun / deno)           | warn + exit 0 (pruning happens on install)                                 |
| `rebuild` (yarn 1 / bun / deno)       | warn + exit 0                                                              |
| `config` (bun / deno)                 | warn + exit 0 (no config CLI; edit `bunfig.toml` / `.npmrc` / `deno.json`) |

## Deno [#deno]

Deno has no umbrella `pm` command, so vis maps the common subcommands to deno's nearest equivalents:

| Subcommand          | Deno equivalent                                                     |
| ------------------- | ------------------------------------------------------------------- |
| `cache <dir>`       | `deno info` (cache management lives in `--reload` / `DENO_DIR` env) |
| `list`              | `deno info`                                                         |
| `pack`              | `deno publish --dry-run`                                            |
| `view` / `info`     | `deno info npm:<pkg>`                                               |
| `prune` / `rebuild` | unsupported — vis emits a warning                                   |


# vis release (/docs/packages/vis/commands/release)



# vis release [#vis-release]

The release subsystem ships package versions, changelogs, git tags, and registry uploads from change files committed alongside your code. The mental model and recipes live in the [release guide](/docs/packages/vis/guides/release) — this page is the per-command reference.

> ⚠ &#x2A;*Unstable.** Set `release.acknowledgeUnstable: true` in `vis.config.ts` (or `VIS_RELEASE_SUPPRESS_UNSTABLE=1`) to silence the warning.

## Which command do I need? [#which-command-do-i-need]

| You want to…                                           | Command                                                   |
| ------------------------------------------------------ | --------------------------------------------------------- |
| Set up vis release for the first time                  | [`vis release init`](#vis-release-init)                   |
| Record a version bump for a change you just made       | [`vis release add`](#vis-release-add)                     |
| Auto-generate the change file from your commit history | [`vis release generate`](#vis-release-generate)           |
| See what's about to release                            | [`vis release status`](#vis-release-status)               |
| See just the next version of each package              | [`vis release next-version`](#vis-release-next-version)   |
| Override individual bumps before shipping              | [`vis release plan -i`](#vis-release-plan)                |
| Preview changelog entries without writing              | [`vis release changelog`](#vis-release-changelog)         |
| Gate that every changed package has a change file      | [`vis release check`](#vis-release-check)                 |
| Diagnose a broken setup                                | [`vis release doctor`](#vis-release-doctor)               |
| Apply pending bumps to disk (run locally — rare)       | [`vis release version`](#vis-release-version)             |
| Publish to npm (run locally — rare)                    | [`vis release publish`](#vis-release-publish)             |
| Ship an ephemeral PR preview install                   | [`vis release snapshot`](#vis-release-snapshot)           |
| Bootstrap npm trusted publishing for new packages      | [`vis release pretrust`](#vis-release-pretrust)           |
| Enter / exit a prerelease sprint mode                  | [`vis release pre`](#vis-release-pre)                     |
| Manage npm staged-publish records                      | [`vis release stage`](#vis-release-stage)                 |
| Dry-run a configured notification destination          | [`vis release notifications`](#vis-release-notifications) |
| Run the whole pipeline in CI                           | [`vis release ci release`](#vis-release-ci-release)       |
| Publish snapshots from CI and comment on the PR        | [`vis release ci snapshot`](#vis-release-ci-snapshot)     |
| Sticky-comment the release plan on a PR                | [`vis release ci check`](#vis-release-ci-check)           |
| Branch a workflow on whether anything is about to ship | [`vis release ci plan`](#vis-release-ci-plan)             |
| Get the secrets / permissions checklist for CI         | [`vis release ci setup`](#vis-release-ci-setup)           |
| Keep an open version-PR rebased on its base branch     | [`vis release ci rebase-pr`](#vis-release-ci-rebase-pr)   |

> 💡 &#x2A;*Tip:** Most release commands accept `--print-config[=debug]` to dump the resolved config and exit. Use it when something looks wrong and you want to see exactly what merged config CI sees. The flag is available on every command except `init`, `add`, `pre`, `stage`, `notifications`, `ci setup`, and `ci rebase-pr`.

***

## vis release init [#vis-release-init]

```bash
vis release init [flags]
```

Scaffold `.vis/release/` and migrate from an existing tool when detected.

**When to use.** Once per repo, after installing `@visulima/vis`. Re-run with `--workflows` if you add a new CI provider later.

```bash
vis release init
vis release init --from-semantic-release
vis release init --from-changesets
vis release init --fresh
vis release init --dry-run
vis release init --from-semantic-release --apply
vis release init --workflows
```

**What it does**

1. Auto-detects an existing release tool (`changesets` / `semantic-release` / `multi-semantic-release` / `bumpy`) and copies / converts artefacts.
2. Creates `.vis/release/` with a sample change file and `.gitignore` entries.
3. With `--workflows`, generates a GitHub Actions or GitLab CI workflow for the active provider.

**Options**

| Option                     | Type    | Description                                                                                                               |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--from-semantic-release`  | boolean | Force migration from semantic-release / multi-semantic-release                                                            |
| `--from-changesets`        | boolean | Force migration from changesets                                                                                           |
| `--from-bumpy`             | boolean | Force migration from bumpy                                                                                                |
| `--fresh`                  | boolean | Skip migration; start clean                                                                                               |
| `--dry-run`                | boolean | Print what would happen without writing files (default for migration runs)                                                |
| `--apply`                  | boolean | Actually perform the migration writes (opt out of the implicit dry-run)                                                   |
| `--yes`, `-y`              | boolean | Auto-confirm prompts (CI-safe)                                                                                            |
| `--workflows`              | boolean | Generate CI workflow files for the active provider                                                                        |
| `--package-manager <name>` | string  | Override the package manager used in generated workflows (npm / pnpm / yarn / bun)                                        |
| `--agent`                  | boolean | Append an idempotent "Releasing with vis" section to `AGENTS.md` so AI agents author change files instead of hand-bumping |

***

## vis release add [#vis-release-add]

```bash
vis release add [flags]
```

Author a change file — interactive by default, scriptable with `--packages`.

**When to use.** Every time you change a package. Run it before committing, and commit the resulting file alongside your code change.

```bash
vis release add
vis release add --packages '@scope/cerebro:minor,@scope/string:patch' --message 'Add tab completion'
vis release add --empty
vis release add --name fix-tab-completion
vis release add --from-bot-pr
```

**Options**

| Option             | Type    | Description                                                                                           |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `--packages <csv>` | string  | `@scope/a:minor,@scope/b:patch` — non-interactive package + bump pairs                                |
| `--message <text>` | string  | Changelog body                                                                                        |
| `--name <slug>`    | string  | Filename slug (default: random animal name)                                                           |
| `--empty`          | boolean | Author an empty change file (satisfies non-strict `check`)                                            |
| `--none`           | boolean | Author a `none`-bump file (acknowledged but no direct bump)                                           |
| `--from-bot-pr`    | boolean | Inspect the current PR via `gh pr view` and author a change file from its Dependabot / Renovate title |

***

## vis release generate [#vis-release-generate]

```bash
vis release generate [flags]
```

Auto-derive a change file from branch commits.

**When to use.** If you'd rather not hand-write change files. Uses the [conventional-commits](https://www.conventionalcommits.org) parser with a path-based fallback for repos that don't enforce them.

```bash
vis release generate
vis release generate --from origin/main
vis release generate --dry-run
```

**Options**

| Option                   | Type    | Description                                                                |
| ------------------------ | ------- | -------------------------------------------------------------------------- |
| `--from <ref>`           | string  | Git ref to compare against (default: merge-base with `release.baseBranch`) |
| `--name <slug>`          | string  | Filename slug (default: random animal name)                                |
| `--dry-run`              | boolean | Print the would-be content without writing                                 |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                 |

***

## vis release status [#vis-release-status]

```bash
vis release status [flags]
```

Print the pending plan in a human-readable table.

**When to use.** Anytime you want to check "what's queued up to release?". Safe to run on any branch — read-only.

```bash
vis release status
vis release status --json
vis release status --bump major,minor
vis release status --filter '@scope/*'
```

**Options**

| Option                   | Type    | Description                                |
| ------------------------ | ------- | ------------------------------------------ |
| `--json`                 | boolean | Machine-readable JSON                      |
| `--filter <glob>`        | string  | Filter by package name (single glob)       |
| `--bump <levels>`        | string  | Filter by bump level (`major,minor,patch`) |
| `--channel <name>`       | string  | Override branch-detected channel           |
| `--print-config[=debug]` | string  | Print the resolved release config and exit |

***

## vis release next-version [#vis-release-next-version]

```bash
vis release next-version [flags]
```

Print just the next computed version for each package in the plan. Read-only; no mutations.

**When to use.** When a downstream script only needs `pkg → newVersion` and the full `status` output is too verbose, or when you want to assert a specific package's next version in a hook.

```bash
vis release next-version
vis release next-version --package=@scope/a
vis release next-version --json
```

**Options**

| Option                   | Type    | Description                                                                                |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------ |
| `--package <name>`       | string  | Limit output to a single package                                                           |
| `--json`                 | boolean | Emit a `{ name: { from, to } }` map instead of pretty `pkg old -> new` lines               |
| `--channel <name>`       | string  | Override branch-detected channel                                                           |
| `--first-release`        | boolean | Bootstrap mode: preview without registry / tag lookups (matches `version --first-release`) |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                                 |

***

## vis release plan [#vis-release-plan]

```bash
vis release plan [flags]
```

Programmatic plan output and, with `--interactive`, a walkthrough that lets you override each bump.

**When to use.** When you need to override a specific bump (e.g. promote a patch to a minor) before CI ships it.

```bash
vis release plan                       # JSON
vis release plan --interactive         # Walk each release, accept or override
vis release plan -i --write            # Same, plus persist overrides as a new change file
```

**Options**

| Option                   | Type    | Description                                                                |
| ------------------------ | ------- | -------------------------------------------------------------------------- |
| `--filter <glob>`        | string  | Filter by package name                                                     |
| `--channel <name>`       | string  | Override branch-detected channel                                           |
| `-i`, `--interactive`    | boolean | Step through pending releases; accept or override each bump                |
| `--write`                | boolean | With `--interactive`, write the chosen overrides to `.vis/release/<id>.md` |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                 |

***

## vis release changelog [#vis-release-changelog]

```bash
vis release changelog [flags]
```

Render the would-be changelog entries without writing to disk.

**When to use.** To preview what the next CHANGELOG.md will look like, or to pipe into release-notes tooling.

```bash
vis release changelog
vis release changelog --json
vis release changelog --filter '@scope/*'
```

**Options**

| Option                   | Type    | Description                                |
| ------------------------ | ------- | ------------------------------------------ |
| `--json`                 | boolean | Emit `ChangelogResult` JSON                |
| `--filter <glob>`        | string  | Filter by package name (CSV)               |
| `--channel <name>`       | string  | Override branch-detected channel           |
| `--print-config[=debug]` | string  | Print the resolved release config and exit |

***

## vis release check [#vis-release-check]

```bash
vis release check [flags]
```

Verify that pending change files cover the packages that changed.

**When to use.** As a `pre-commit` / `pre-push` hook, or as a CI gate that fails the PR if someone forgot a change file.

```bash
vis release check
vis release check --strict             # Every changed package must have its own file
vis release check --hook pre-commit    # Run as a husky hook
vis release check --no-fail            # Warnings only, exit 0
```

**Options**

| Option                   | Type    | Description                                                                     |
| ------------------------ | ------- | ------------------------------------------------------------------------------- |
| `--strict`               | boolean | Require every changed package to have its own non-empty change file             |
| `--hook <name>`          | string  | Hook context (`pre-commit`, `pre-push`) — affects which file states are counted |
| `--no-fail`              | boolean | Always exit 0; warnings still print to stderr                                   |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                      |

***

## vis release doctor [#vis-release-doctor]

```bash
vis release doctor [flags]
```

Run read-only preflight diagnostics: `config-loads`, `workspace-discovered`, `pm-version`, `branch-channel`, `gh-cli-available`, `oidc-available`, and per-package `napi-*` checks (sidecar platforms + version alignment + optionalDependencies wiring).

**When to use.** First port of call when something looks broken. Each check is tagged `error` / `warn` / `info`; exits non-zero on any error.

```bash
vis release doctor
vis release doctor --json
vis release doctor --first-release
```

**Options**

| Option                   | Type    | Description                                                                          |
| ------------------------ | ------- | ------------------------------------------------------------------------------------ |
| `--json`                 | boolean | Emit a machine-readable report                                                       |
| `--first-release`        | boolean | Bootstrap mode: assert the workspace has no release tags and no package is published |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                           |

***

## vis release version [#vis-release-version]

```bash
vis release version [flags]
```

Apply the plan to disk: write `package.json` bumps, rewrite `workspace:` / `catalog:` ranges, prepend `CHANGELOG.md` entries, sync the lockfile, delete consumed change files.

**When to use.** Rarely run by hand — `vis release ci release` calls it for you. Run it locally only when you want to inspect the diff before pushing.

```bash
vis release version
vis release version --dry-run
vis release version --channel alpha
vis release version --commit
vis release version --first-release    # Greenfield monorepo, no prior tags
```

**Options**

| Option                   | Type    | Description                                                                              |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
| `--dry-run`              | boolean | Print the diff and exit; no writes                                                       |
| `--channel <name>`       | string  | Override branch-detected channel                                                         |
| `--filter <glob>`        | string  | Limit to packages matching the glob (CSV)                                                |
| `--commit`               | boolean | Auto-commit after applying                                                               |
| `--check-only`           | boolean | Run preflight checks (config + workspace + plan) and exit. No mutations.                 |
| `--first-release`        | boolean | Bootstrap mode: force `currentVersionResolver=disk` and skip remote tag-collision checks |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                               |

***

## vis release publish [#vis-release-publish]

```bash
vis release publish [flags]
```

Pack each managed package, publish the tarball, create + push git tags, then create GitHub / GitLab releases.

**When to use.** Rarely run by hand — `vis release ci release` calls it. Run locally only for emergency manual releases or when recovering from a failed CI run with `--resume`.

```bash
vis release publish
vis release publish --dry-run
vis release publish --tag alpha
vis release publish --filter '@scope/*'
vis release publish --resume
```

**Options**

| Option                   | Type    | Description                                                                              |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
| `--dry-run`              | boolean | Skip uploads; print what would happen                                                    |
| `--tag <name>`           | string  | Override the npm dist-tag                                                                |
| `--filter <glob>`        | string  | Limit to packages matching the glob (CSV)                                                |
| `--no-push`              | boolean | Skip `git push --tags` after publish                                                     |
| `--otp <code>`           | string  | 2FA token                                                                                |
| `--channel <name>`       | string  | Override branch-detected channel                                                         |
| `--resume`               | boolean | Resume from a previous run's state file (skips already-published packages)               |
| `--check-only`           | boolean | Preflight checks (config + workspace + plan + auth) and exit. No mutations.              |
| `--first-release`        | boolean | Bootstrap mode: force `currentVersionResolver=disk` and skip remote tag-collision checks |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                               |

***

## vis release snapshot [#vis-release-snapshot]

```bash
vis release snapshot --tag <name> [flags]
```

Publish ephemeral `0.0.0-<tag>-<sha>` versions of every affected package. Defaults to the active npm registry; point at [pkg-pr-new](https://pkg-pr-new.com) or another preview host via `--registry` or `release.snapshot.registry`.

**When to use.** Locally when you want a colleague to try a branch without merging — share the install command and they install it like any other version.

```bash
vis release snapshot --tag pr-1234
vis release snapshot --tag canary --filter '@scope/*'
vis release snapshot --tag pr-1234 --dry-run
```

**Options**

| Option                   | Type    | Description                                                       |
| ------------------------ | ------- | ----------------------------------------------------------------- |
| `--tag <name>`           | string  | Required: dist-tag for the snapshot release                       |
| `--registry <url>`       | string  | Override the registry (falls back to `release.snapshot.registry`) |
| `--filter <glob>`        | string  | Limit to packages matching the glob (CSV)                         |
| `--dry-run`              | boolean | Print what would publish without uploading                        |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                        |

***

## vis release pretrust [#vis-release-pretrust]

```bash
vis release pretrust [flags]
```

npm — unlike PyPI — refuses to configure a Trusted Publisher (OIDC) for a package that does not exist yet, so the **first** OIDC publish of a brand-new package fails. `pretrust` breaks that chicken-and-egg: for every managed package missing from the registry it publishes a minimal, explicitly non-functional placeholder, then runs `npm trust` to configure the Trusted Publisher automatically.

**When to use.** Once, before the first release of new packages (locally, by a maintainer who can clear the npm 2FA prompt). After it runs, `vis release publish` can publish those packages over OIDC. Mirrors [`azu/setup-npm-trusted-publish`](https://github.com/azu/setup-npm-trusted-publish).

```bash
vis release pretrust                       # placeholder + trust for every not-yet-published package
vis release pretrust --dry-run             # preview, no upload
vis release pretrust --filter '@scope/*'   # limit to a glob
vis release pretrust --no-trust            # publish placeholders only, configure trust manually
```

**What it does**

1. Skips packages that already exist on the registry (override with `--force`).
2. Publishes a README-only placeholder under a dedicated dist-tag (default `placeholder`, so `latest` stays unset and `npm install` keeps failing until the real release).
3. On a successful publish, runs `npm trust <provider> <pkg> --file <workflow> --allow-publish` (npm CLI ≥ 11.5.1). The provider, repo, and workflow file are auto-detected from the git remote and `.github/workflows`; override with `--provider`/`--repo`/`--workflow`/`--env`.
4. The first `npm trust` call may require a 2FA OTP — a failure there is reported per package (not fatal) with the `https://www.npmjs.com/package/<name>/access` URL as a manual fallback.

**Options**

| Option                   | Type    | Description                                                                           |
| ------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `--filter <glob>`        | string  | Limit to packages matching the glob (CSV)                                             |
| `--tag <name>`           | string  | dist-tag for the placeholder (default `placeholder`)                                  |
| `--version <semver>`     | string  | Placeholder version (default `0.0.0`)                                                 |
| `--access <level>`       | string  | `public` or `restricted` (default `public`)                                           |
| `--registry <url>`       | string  | Override the registry                                                                 |
| `--force`                | boolean | Publish a placeholder even if the package already exists                              |
| `--no-trust`             | boolean | Skip the `npm trust` step (publish placeholders only)                                 |
| `--provider <name>`      | string  | Trust claim provider: `github` or `gitlab` (default: auto-detect from the git remote) |
| `--repo <slug>`          | string  | Trust claim: `owner/repo` (github) or `group/project` (gitlab); default auto-detected |
| `--workflow <file>`      | string  | Trust claim: workflow/pipeline filename (`npm trust --file`); default auto-detected   |
| `--env <name>`           | string  | Trust claim: restrict to a deployment environment                                     |
| `--allow-stage-publish`  | boolean | Trust claim: also grant the staged-publish permission                                 |
| `--dry-run`              | boolean | Print what would publish without uploading                                            |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                            |

***

## vis release pre [#vis-release-pre]

```bash
vis release pre <enter|exit|status> [flags]
```

Enter / exit a prerelease sprint mode. Changesets-compatible — while active, every `vis release version` produces a prerelease bump (`1.2.0-alpha.0`, `1.2.0-alpha.1`, …) instead of the usual stable bump. Independent of channel-derived prerelease handling.

**When to use.** When you need to sustain an alpha / RC line on a branch where channels don't naturally produce one (e.g. on `main` for a few weeks while a major feature stabilises).

```bash
vis release pre enter alpha     # snapshot every package's version; future bumps are prerelease
vis release pre status          # check whether pre-mode is on / exit-pending / off
vis release pre exit            # mark for exit; the NEXT `version` consolidates + deletes pre.json

# Local triage without auto-committing the tracked pre.json:
vis release pre enter alpha --no-commit
vis release pre exit --no-push
```

**Positional**

* `<enter|exit|status>` — the action (default: `status`)
* `<tag>` — required for `enter`; the prerelease tag (e.g. `alpha`, `beta`, `rc`)

**Options**

| Option        | Type    | Default | Description                                   |
| ------------- | ------- | ------- | --------------------------------------------- |
| `--no-commit` | boolean | commit  | Skip auto-committing `pre.json` after writing |
| `--no-push`   | boolean | push    | Skip pushing the commit                       |

State lives in `.vis/release/pre.json` (tracked in git so CI sees the same mode across runs). Auto-committed with `[skip ci]` on every transition.

***

## vis release stage [#vis-release-stage]

```bash
vis release stage <list|approve|reject> [stage-ids...] [flags]
```

List, approve, or reject npm staged-publish records. `approve` and `reject` require 2FA on the npm side.

**When to use.** When you use npm staged publishes (publish-then-promote) and need to confirm a stage from the command line instead of the npm UI. `list` is also useful for auditing — it merges the local `.vis/release/staged.json` registry with the live npm staging endpoint.

```bash
vis release stage list                          # All staged versions (npm + local registry)
vis release stage list @scope/pkg               # Staged versions for one package
vis release stage list --json                   # Machine-readable
vis release stage approve <stage-id>            # Promote + drain from staged.json, commit + push
vis release stage approve --all                 # Approve every pending stage in staged.json
vis release stage reject <stage-id>             # Permanent — re-stage to retry
vis release stage approve <stage-id> --no-push  # Approve, commit locally, skip the push
vis release stage approve <stage-id> --no-commit # Approve and update registry only
```

**Positional**

* `<list|approve|reject>` — the action (default: `list`)
* `<stage-ids...>` — one or more stage IDs (only meaningful for `approve` / `reject`)

**Options**

| Option            | Type    | Default | Description                                                       |
| ----------------- | ------- | ------- | ----------------------------------------------------------------- |
| `--all`           | boolean |         | Approve every pending stage tracked in `.vis/release/staged.json` |
| `--filter <name>` | string  |         | Package name filter for `list`                                    |
| `--json`          | boolean |         | Emit machine-readable JSON                                        |
| `--no-commit`     | boolean | commit  | Update `staged.json` but skip the auto-commit                     |
| `--no-push`       | boolean | push    | Skip pushing the registry commit to the remote                    |

***

## vis release notifications [#vis-release-notifications]

```bash
vis release notifications test [flags]
```

Dry-run the configured notification channels (`slack` / `discord` / `webhook` / plugins) with a synthetic release context. Lets operators verify a destination is wired up *before* relying on it for a real release.

**When to use.** Once after configuring `release.notifications` in `vis.config.ts`, and again whenever you rotate a webhook secret.

```bash
vis release notifications test                                  # All configured channels
vis release notifications test --channel=slack                  # Every Slack channel only
vis release notifications test --channel=slack:eng              # The Slack channel with id=eng only
vis release notifications test --custom-context=./fake.json     # Use an operator-supplied context
vis release notifications test --json                           # Machine-readable results
```

**Positional**

* `<test>` — the action (default: `test`; only `test` is implemented today)

**Options**

| Option                    | Type    | Description                                                                                                 |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `--channel <kind[:id]>`   | string  | Restrict dispatch to a single channel kind (`slack`, `discord`, `webhook`) or an id'd channel (`slack:eng`) |
| `--custom-context <file>` | string  | Path to a JSON file containing a `NotificationContext` to use instead of the synthetic default              |
| `--json`                  | boolean | Emit machine-readable JSON instead of a per-channel report                                                  |

Exit 0 iff every dispatched channel succeeded.

***

## vis release ci release [#vis-release-ci-release]

```bash
vis release ci release [flags]
```

The main CI driver. Behaviour depends on the channel's `mode`:

* `version-pr` (default for `main` / `next&#x60;) — open or update a rolling **"Versioned release" PR**; publish only when the PR merges.
* `auto-publish` (default for `alpha` / `beta`) — version + publish inline on every push.

Force the auto-publish path with `--auto-publish` regardless of channel config.

**When to use.** In your release workflow's main job step. This is the command CI calls; you almost never invoke it by hand.

```bash
vis release ci release
vis release ci release --auto-publish
```

**Options**

| Option                   | Type    | Description                                                                    |
| ------------------------ | ------- | ------------------------------------------------------------------------------ |
| `--auto-publish`         | boolean | Skip the version-PR; version + publish inline                                  |
| `--branch <name>`        | string  | Override the version-PR branch (default: `vis-release/version-packages`)       |
| `--channel <name>`       | string  | Override branch-detected channel                                               |
| `--first-release`        | boolean | Bootstrap mode: force `currentVersionResolver=disk` and skip remote tag checks |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                     |

**Tokens**

* `GH_TOKEN` / `GITHUB_TOKEN` — comments and reads (default `${{ github.token }}`).
* `VIS_GH_TOKEN` — force-push the version-PR branch (the default `github.token` is anti-recursion-locked so it can't trigger downstream workflows).

See [the CI guide](/docs/packages/vis/guides/release-ci) for end-to-end workflow examples.

***

## vis release ci snapshot [#vis-release-ci-snapshot]

```bash
vis release ci snapshot [flags]
```

Publish snapshots in CI and post a sticky PR comment with the install snippet.

**When to use.** In a PR workflow. The default tag is `pr-<PR_NUMBER>`; override only if you want a different naming scheme (e.g. `canary` for `main`-targeted PRs).

```bash
vis release ci snapshot                # tag defaults to pr-<PR_NUMBER>
vis release ci snapshot --tag canary
vis release ci snapshot --on-close     # Clean up the snapshot when the PR closes (where supported)
```

**Options**

| Option                   | Type    | Description                                                                                                                                                                         |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tag <name>`           | string  | Override the dist-tag (default: `pr-<PR_NUMBER>`)                                                                                                                                   |
| `--on-close`             | boolean | PR-close cleanup mode — enumerates the closed PR's commit SHAs (via `gh api`, **GitHub-only**) and removes their snapshot tags from the registry (when the backend supports DELETE) |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                                                                                                                                          |

***

## vis release ci check [#vis-release-ci-check]

```bash
vis release ci check [flags]
```

Sticky-comment with the pending release plan for the PR. Same logic as `vis release check`, but posts the result instead of failing the build.

**When to use.** In a PR workflow when you want reviewers to see what's about to release in a comment rather than just a build status.

```bash
vis release ci check
vis release ci check --strict
```

**Options**

| Option                   | Type    | Description                                                  |
| ------------------------ | ------- | ------------------------------------------------------------ |
| `--strict`               | boolean | Require every changed package to be covered by a change file |
| `--no-fail`              | boolean | Always exit 0 (warnings still print)                         |
| `--print-config[=debug]` | string  | Print the resolved release config and exit                   |

***

## vis release ci plan [#vis-release-ci-plan]

```bash
vis release ci plan [flags]
```

Emit a JSON plan and write `{ mode, packages, json }` to `$GITHUB_OUTPUT` so downstream workflow steps can gate on whether anything is about to release.

**When to use.** When you want a workflow step to run only if a release is queued — e.g. preparing release notes, notifying Slack, smoke-testing the bumped packages.

```bash
vis release ci plan
```

```yaml
- id: plan
  run: pnpm exec vis release ci plan

- if: steps.plan.outputs.packages != ''
  run: pnpm run prepare-release-notes
```

**Options**

| Option                   | Type   | Description                                |
| ------------------------ | ------ | ------------------------------------------ |
| `--print-config[=debug]` | string | Print the resolved release config and exit |

***

## vis release ci setup [#vis-release-ci-setup]

```bash
vis release ci setup
```

Print the recommended secrets, OIDC trust, and workflow-permission checklist for your detected provider.

**When to use.** After `vis release init --workflows`, to make sure the runtime side (secrets in Settings → Secrets, OIDC trust on the npm package page, etc.) is configured.

```bash
vis release ci setup
```

This command takes no flags.

***

## vis release ci rebase-pr [#vis-release-ci-rebase-pr]

```bash
vis release ci rebase-pr [flags]
```

Fetch base, rebase the version-PR branch on top, and force-push. Idempotent — when the PR branch is already up to date, the command exits 0 without pushing.

**When to use.** As a scheduled CI job (cron / `schedule:` trigger) when the version-PR stays open for long periods and other PRs land on the base branch in the meantime. Without periodic rebases the version-PR's diff drifts and eventually merges with unrelated noise.

Rebase conflicts abort cleanly — the working tree is restored and the command exits non-zero. Resolve manually or rerun `vis release ci release` to recompute the PR from scratch.

```bash
vis release ci rebase-pr                       # rebase onto release.baseBranch
vis release ci rebase-pr --base develop        # override base
vis release ci rebase-pr --branch release/version  # override the version-PR branch
```

**Options**

| Option            | Type   | Description                                                              |
| ----------------- | ------ | ------------------------------------------------------------------------ |
| `--branch <name>` | string | Override the version-PR branch (default: `vis-release/version-packages`) |
| `--base <name>`   | string | Override the base branch (default: `release.baseBranch`)                 |

***

## Where to next [#where-to-next]

* [Release guide](/docs/packages/vis/guides/release) — recipes, change files, channels, configuration
* [Release CI guide](/docs/packages/vis/guides/release-ci) — full workflow examples for GitHub Actions + GitLab CI
* [Release comparison](/docs/packages/vis/guides/release-comparison) — vs changesets / semantic-release / release-please


# vis remove (/docs/packages/vis/commands/remove)



# vis remove [#vis-remove]

Uninstall packages from the current project (or a filtered workspace package). Aliased as `vis rm`, `vis un`, `vis uninstall`.

## Usage [#usage]

```bash
vis remove <packages...> [options]
```

## Examples [#examples]

```bash
vis remove lodash
vis rm old-package
vis remove --filter app react      # remove from a specific workspace package
vis remove -g typescript           # remove a global package
```

## Options [#options]

| Option             | Alias | Default | Description                                   |
| ------------------ | ----- | ------- | --------------------------------------------- |
| `--save-dev`       | `-D`  | `false` | Remove from devDependencies                   |
| `--global`         | `-g`  | `false` | Remove a global package                       |
| `--recursive`      | `-r`  | `false` | Remove from all workspace packages            |
| `--workspace-root` | `-w`  | `false` | Remove from workspace root                    |
| `--filter`         | `-F`  |         | Filter by workspace package name (repeatable) |


# vis replay (/docs/packages/vis/commands/replay)



# vis replay [#vis-replay]

Inspect a previous run summary without re-running anything. Pairs with `vis cache why` to debug "what happened yesterday?" — `replay` shows the per-task outcome (status, duration, hash, exit code), `vis cache why <task> --run <id>` then drills into the hash inputs that flipped.

```bash
vis replay                                  # last run summary
vis replay --run 2026-04-28T12-34-56_ab12   # specific historical run
vis replay --list                           # every recorded run, newest first
vis replay --task @myorg/app:build          # focus on one task in the loaded run
vis replay --failed                         # only failed tasks
vis replay --format=json                    # machine-readable
```

## Where summaries come from [#where-summaries-come-from]

Each `vis run --summarize` writes a JSON summary into `.vis/runs/<id>.json` and overwrites `.vis/last-summary.json`. `vis replay` reads from those files only — it never re-executes tasks. To make a run replayable later, pass `--summarize` (or set it as a default in CI). The most recent run is always available without `--summarize` because `last-summary.json` is written for every run.

## Loading a specific run [#loading-a-specific-run]

Pass `--run <id>` where `<id>` is the file basename without `.json` (e.g. `2026-04-28T12-34-56_ab12`). `vis replay --list` enumerates every available id, sorted newest-first by mtime.

## Filters [#filters]

| Flag          | Effect                                                           |
| ------------- | ---------------------------------------------------------------- |
| `--task <id>` | Render detail for one task; errors if the task is not in the run |
| `--failed`    | Show only tasks with a non-zero exit code                        |

`--task` and `--failed` compose. `vis replay --task @app/api:test --format=json` is a common CI shape — load yesterday's failed-test summary for one specific target.

## Exit code [#exit-code]

`vis replay` exits 1 when the loaded run had any failed tasks (`stats.failed > 0`), and 0 otherwise. This makes `vis replay --failed` usable as a CI status check, not just a viewer.

When a load fails (no summary, missing run id, or `--task` filter not matched), `vis replay` exits 1 with a one-line `pail.error` describing what went wrong.

## JSON shape [#json-shape]

`--format=json` is a stable contract. `--list` emits an array of `{ id, mtime, path }`. Otherwise the payload is:

```json
{
    "runId": "2026-04-28T12-34-56_ab12",
    "startTime": "...",
    "endTime": "...",
    "duration": 1234,
    "environment": { "platform": "linux", "arch": "x64", "nodeVersion": "v22.14.0" },
    "stats": { "total": 3, "succeeded": 2, "cached": 0, "skipped": 0, "failed": 1 },
    "tasks": [
        {
            "taskId": "@app/api:test",
            "cacheStatus": "MISS",
            "duration": 234,
            "exitCode": 1,
            "hash": "abc…",
            "dependencies": ["@app/api:db"],
            "startTime": "…",
            "endTime": "…"
        }
    ]
}
```

## Pairs with `vis cache why` [#pairs-with-vis-cache-why]

When `vis replay --failed` shows a task that re-ran when you expected a cache hit, copy the run id and the task id into `vis cache why`:

```bash
vis cache why @app/api:test --run 2026-04-28T12-34-56_ab12
```

That walks the task's `hashDetails` against the previous run's hash and tells you which bucket changed (command, nodes, runtime, implicitDeps).


# vis run (/docs/packages/vis/commands/run)



# vis run [#vis-run]

Run a target (e.g., `build`, `test`, `lint`) across workspace projects. Tasks are executed in dependency order with caching.

## Usage [#usage]

```bash
vis run <selector> [options]
```

## Selectors [#selectors]

vis supports moon-style target selectors:

| Syntax                      | Meaning                                                    |
| --------------------------- | ---------------------------------------------------------- |
| `vis run build`             | Run `build` on every project (legacy form)                 |
| `vis run :build`            | Same as above (explicit "all" selector)                    |
| `vis run ~:test`            | Run `test` on the project closest to the current directory |
| `vis run "#frontend:build"` | Run `build` on every project tagged `frontend`             |
| `vis run @myorg/app:build`  | Run `build` on a single named project                      |

## Examples [#examples]

```bash
vis run build                                             # All projects
vis run :build --query "language=typescript && tag=lib"    # Filter by metadata
vis run ~:test                                            # Closest project
vis run "#frontend:build"                                 # Tag filter
vis run test --projects=pkg-a,pkg-b                       # Explicit list
vis run build --parallel=5                                # Concurrency
vis run build --no-cache                                  # Skip cache
vis run test --watch                                      # Rerun on file change
vis run destroy --reverse                                 # Leaves-first (teardown order)
vis run dev --services=persistent --stop-services         # Boot service deps + clean them up on exit
```

## Options [#options]

| Option               | Alias | Default        | Description                                                                                                                                                                                                                                                                                                         |
| -------------------- | ----- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--projects`         | `-p`  | all            | Comma-separated list of projects to run                                                                                                                                                                                                                                                                             |
| `--parallel`         |       | `3`            | Maximum number of parallel tasks (also reads `VIS_RUN_CONCURRENCY_LIMIT`). The resolved value is exported to every task as `VIS_TASK_SLOTS` — see [Environment variables in child tasks](#environment-variables-in-child-tasks).                                                                                    |
| `--preflight`        |       | enabled        | Detect lockfile / `node_modules` drift before running. Warns in TTY, fails in CI. `--no-preflight` opts out per run; workspace-wide via `preflight.lockfile: false` in `vis.config.ts`.                                                                                                                             |
| `--skip-toolchain`   |       | `false`        | Skip the toolchain pre-flight (no auto-install for any pinned tool: node / pnpm / yarn / npm / bun / deno / go / python / ruby / rust)                                                                                                                                                                              |
| `--cache`            |       | `true`         | Enable caching (`--no-cache` to disable)                                                                                                                                                                                                                                                                            |
| `--skip-cache`       |       |                | Comma-separated selectors of tasks to bypass cache for (`app:test`, `:e2e`, `#flaky:lint`). Other tasks in the run still cache. `--no-cache` wins when both are set.                                                                                                                                                |
| `--cache-dir`        |       |                | Custom cache directory                                                                                                                                                                                                                                                                                              |
| `--cache-mode`       |       |                | Remote cache mode: `read`, `write`, or `readwrite` (overrides `remoteCache.mode` from config)                                                                                                                                                                                                                       |
| `--cache-backend`    |       |                | Remote cache wire backend: `http` (Turborepo-compatible) or `reapi` (Bazel REAPI gRPC)                                                                                                                                                                                                                              |
| `--dry-run`          |       | `false`        | Show what would run without executing                                                                                                                                                                                                                                                                               |
| `--summarize`        |       | `false`        | Generate a JSON run summary at `.vis/runs/<id>.json` (also enables historical diffs for `vis cache why` / `vis replay`)                                                                                                                                                                                             |
| `--fail-fast`        |       | `false`        | Stop all tasks on first failure                                                                                                                                                                                                                                                                                     |
| `--partition`        |       |                | Partition for distributed CI (e.g. `1/4`). Falls back to `VIS_PARTITION`.                                                                                                                                                                                                                                           |
| `--skip-constraints` |       | `false`        | Skip project constraint validation                                                                                                                                                                                                                                                                                  |
| `--query`            |       |                | Filter by query (e.g. `language=typescript && tag=lib`)                                                                                                                                                                                                                                                             |
| `--strict-env`       |       | config (`off`) | Fail a task whose command references an unset env var (no silent empty-string substitution). `--no-strict-env` disables when set in `vis.config.ts`. POSIX specials (`$1`, `$#`) and `${VAR:-fallback}` defaults are skipped.                                                                                       |
| `--watch`            |       | `false`        | Rerun on file change (Ctrl+C to exit)                                                                                                                                                                                                                                                                               |
| `--services`         |       | TTY: `auto`    | Auto-start service deps. `auto` (per-task: `dev` → ephemeral, others → persistent), `ephemeral` (die with the run), `persistent` (registered for future runs), `off` (skip and abort with the diagnostic). Default is `auto` in a TTY, `off` in CI / pipes. Workspace pin via `run.services` in `vis.config.ts`.    |
| `--stop-services`    |       | `false`        | Stop services this run auto-started in registry mode when the run exits (clean finish, `q`, or Ctrl+C). Pre-existing services and ephemeral services are unaffected — ephemeral already die with the run; only services this invocation booted via `--services=persistent` or the `auto` registry path are stopped. |
| `--flaky`            |       | `true`         | Show flaky report on failure (`--no-flaky` to suppress)                                                                                                                                                                                                                                                             |
| `--fail-on-retry`    |       | `false`        | Treat any task that succeeded only after one or more retries as a run failure (exit non-zero). Useful as a periodic CI check to surface flakes that retries would otherwise mask.                                                                                                                                   |
| `--log`              |       |                | Output mode: `interleaved`, `labeled` (`[pkg#task]` prefixes), or `grouped` (buffered block)                                                                                                                                                                                                                        |
| `--output-style`     |       |                | `normal` (default) prints every task; `quiet` skips output for successful and cached tasks (failures still print). Per-target `options.outputStyle` overrides this.                                                                                                                                                 |
| `--pty`              |       | `false`        | Run every task through a PTY so color-aware tools render as if attached to a TTY (disables caching)                                                                                                                                                                                                                 |
| `--retry-budget`     |       |                | Global cap on total retries across the run (per-target `retryCount` is honored up to budget)                                                                                                                                                                                                                        |
| `--profile`          |       |                | Write a Chrome Tracing JSON of the run to this path (open in chrome://tracing or Perfetto)                                                                                                                                                                                                                          |
| `--last-details`     |       | `false`        | Render the most-recent run's saved summary (`.vis/last-summary.json`) and exit without executing any tasks. Use for "what happened in the last build?" without re-running.                                                                                                                                          |
| `--reverse`          |       | `false`        | Run the dependency graph leaves-first (dependents before deps). Use for teardown targets like `destroy`/`undeploy` — see [Reverse order](#reverse-order-teardown).                                                                                                                                                  |
| `--runner-tags`      |       |                | Comma-separated tags this runner advertises (e.g. `gpu,slow`). Tasks declaring `options.runnerTags` only run when at least one tag overlaps; untagged tasks always run. Falls back to `VIS_RUNNER_TAGS`.                                                                                                            |

### Positional args after the target [#positional-args-after-the-target]

Extra arguments past the target name are forwarded **only** to the user-invoked target, not to `dependsOn` dependencies:

```bash
vis run test --reporter=verbose    # forwards --reporter=verbose to the test task only
```

`build` deps triggered by `test` do not receive the args.

### Interactive target picker [#interactive-target-picker]

Running `vis run` with no target in a TTY launches a readline numbered picker:

```
$ vis run
Available targets:
   1. build
   2. lint
   3. test

Select a target (number or name, blank to cancel):
```

The chosen target is appended to your shell history so up-arrow replays it verbatim (bash / zsh / fish; set `VIS_NO_SHELL_HISTORY=1` to disable). Non-TTY sessions keep the list-and-hint behavior.

## Query Language [#query-language]

The `--query` flag accepts clauses joined by `&&` (all match) or `||` (any matches):

```bash
vis run :build --query "language=typescript && tag=lib"
vis run :test --query "tag=frontend || tag=shared"
vis run :lint --query "layer=library"
```

Supported fields: `project`, `id`, `tag`, `tags`, `type`, `projectType`, `language`, `stack`, `layer`.

## Target Options [#target-options]

Targets in `project.json` support vis-specific options:

```json
{
    "$schema": "https://unpkg.com/@visulima/vis/schemas/project.schema.json",
    "targets": {
        "dev": {
            "command": "vite dev",
            "type": "run",
            "preset": "server",
            "options": {
                "persistent": true,
                "interactive": false,
                "envFile": ".env.local"
            }
        },
        "build": {
            "command": "vite build",
            "type": "build",
            "outputs": ["dist/**"],
            "options": {
                "retryCount": 2
            }
        },
        "migrate": {
            "command": "prisma migrate deploy",
            "options": {
                "mutex": "db-migration",
                "runFromWorkspaceRoot": true
            }
        }
    }
}
```

### Available Options [#available-options]

| Option                 | Type                                    | Default         | Description                                                                                                                                                                                             |
| ---------------------- | --------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `persistent`           | `boolean`                               | `false`         | Long-running process, run last, never cached                                                                                                                                                            |
| `interactive`          | `boolean`                               | `false`         | Claims stdin, serialized execution                                                                                                                                                                      |
| `internal`             | `boolean`                               | `false`         | Hidden from CLI, only invoked as a dependency                                                                                                                                                           |
| `pty`                  | `boolean`                               | `false`         | Run through a pseudo-terminal so colour-aware tools render as if attached to a TTY                                                                                                                      |
| `runInCI`              | `boolean \| "affected" \| "always"`     | `true`          | Whether to run in CI environments                                                                                                                                                                       |
| `runnerTags`           | `string[]`                              |                 | Capability tags required from the runner. Eligible iff at least one tag overlaps with `--runner-tags` / `VIS_RUNNER_TAGS`. Untagged tasks (no field or empty array) are general-purpose and always run. |
| `retryCount`           | `number`                                | `0`             | Auto-retry on failure                                                                                                                                                                                   |
| `retryDelay`           | `number \| "exponential"`               | `"exponential"` | Delay between retries                                                                                                                                                                                   |
| `timeout`              | `number`                                | `0`             | Wall-clock budget in ms. `0` disables the watchdog. Exceeding it sends `SIGTERM` and marks the task as timed out (exit code 124) — see [Timeouts & Signals](#timeouts--signals)                         |
| `killGracePeriodMs`    | `number`                                | `5000`          | Milliseconds between `SIGTERM` and the escalating `SIGKILL` when `timeout` fires. `0` disables escalation                                                                                               |
| `affectedFiles`        | `false \| "args" \| "env" \| "both"`    | `false`         | Forward changed files to task                                                                                                                                                                           |
| `envFile`              | `boolean \| string \| string[]`         |                 | Dotenv file(s) — see [env file layering](#env-file-layering)                                                                                                                                            |
| `mutex`                | `string`                                |                 | Named lock for serializing tasks                                                                                                                                                                        |
| `osType`               | `string \| string[]`                    |                 | Restrict to Linux (`linux`), macOS (`macos`), or Windows (`windows`)                                                                                                                                    |
| `outputStyle`          | `"normal" \| "quiet"`                   |                 | Per-target override for `--output-style`. `quiet` mutes a single noisy task on success/cache hit; `normal` keeps a critical task verbose under a global `--output-style=quiet`. Failures always print.  |
| `runFromWorkspaceRoot` | `boolean`                               | `false`         | Use workspace root as CWD                                                                                                                                                                               |
| `shell`                | `string`                                |                 | Per-target shell override                                                                                                                                                                               |
| `unixShell`            | `string`                                |                 | Shell override for Linux/macOS                                                                                                                                                                          |
| `when`                 | see [Task conditions](#task-conditions) |                 | Declarative gate — skip the task unless the condition matches                                                                                                                                           |
| `windowsShell`         | `string`                                |                 | Shell override for Windows                                                                                                                                                                              |

### Task metadata [#task-metadata]

Targets support optional metadata fields rendered by `vis list`:

```json
{
    "targets": {
        "test": {
            "command": "vitest run",
            "description": "Run unit + integration tests",
            "aliases": ["t", "spec"]
        }
    }
}
```

* `description` — one-liner shown in `vis list` and future per-task `--help`.
* `aliases` — alternate target names resolved before the selector runs. `vis run t` resolves to `test`. Aliases are workspace-global; the first declaration wins on conflict.

### Quieting noisy tasks [#quieting-noisy-tasks]

Combine the global `--output-style=quiet` flag with per-target `outputStyle` to silence chatter without losing failure logs:

```bash
vis run :build --output-style=quiet     # only failures print stdout/stderr
```

To mute a single noisy linter regardless of the CLI flag:

```json
{
    "targets": {
        "lint": {
            "command": "eslint .",
            "options": { "outputStyle": "quiet" }
        }
    }
}
```

To keep a critical task verbose even when the rest of the run is quiet:

```json
{
    "targets": {
        "migrate": {
            "command": "prisma migrate deploy",
            "options": { "outputStyle": "normal" }
        }
    }
}
```

Skipped tasks still print their reason — quiet only swallows successful and cached output. Unknown values for `--output-style` (e.g. `--output-style=verbose`) fall back to `normal` so a typo never silently mutes CI.

### Quiet on success [#quiet-on-success]

Passing `--output-style=quiet` on every invocation gets old. Set `run.quietOnSuccess` in `vis.config.ts` to make a clean run quiet by default:

```ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    run: {
        // Default: false. When true, a successful run is quiet and the
        // interactive TUI auto-closes a few seconds after it finishes.
        quietOnSuccess: true,
    },
});
```

When enabled, `quietOnSuccess` does two things:

* **Non-interactive output** behaves as if `--output-style=quiet` were passed — successful and cached tasks are silenced, failures still print in full (expanded as their own log group in CI).
* **The interactive TUI auto-closes after a clean run.** When every task succeeds, a countdown dialog (`Exiting in 3…`) appears and the TUI exits on its own; press any key to cancel the countdown and stay, or `q` to leave immediately. **A run with any failure never auto-closes** — the TUI stays open on the results so you can inspect what broke.

Precedence (most specific wins):

| Setting                        | Scope                         | Overrides                           |
| ------------------------------ | ----------------------------- | ----------------------------------- |
| `options.outputStyle` (target) | A single task                 | Everything below, for that task     |
| `--output-style` (CLI flag)    | The whole run's output        | `run.quietOnSuccess` output side    |
| `tui.autoExit` (config)        | The TUI auto-close countdown  | `run.quietOnSuccess` countdown side |
| `run.quietOnSuccess` (config)  | Output **and** TUI auto-close | The built-in defaults               |

So you can opt the whole repo into quiet, auto-closing runs with `quietOnSuccess: true`, then force a verbose run when debugging with `vis run build --output-style=normal` — the explicit flag wins and the TUI stays put.

### Env file layering [#env-file-layering]

`envFile` accepts three shapes:

```json
{ "envFile": ".env.local" }                       // single file
{ "envFile": [".env", ".env.local"] }              // array — later entries override earlier
{ "envFile": true }                                // auto-cascade
```

Auto-cascade (`true`) loads in Next.js order: `.env` → `.env.{NODE_ENV}` → `.env.local` → `.env.{NODE_ENV}.local`. `.env.local` is skipped when `NODE_ENV=test` to avoid leaking CI secrets into tests.

### Environment variables in child tasks [#environment-variables-in-child-tasks]

Beyond your own `env` / `envFile`, vis injects a few variables into every spawned task:

| Variable         | Value                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `INIT_CWD`       | The directory you invoked `vis` from (before workspace discovery changed cwd), matching the pnpm/npm/yarn convention. |
| `VIS_TASK_SLOTS` | The effective parallelism for this run — the resolved `--parallel` value (default `3`).                               |

`VIS_TASK_SLOTS` exists to avoid **nested oversubscription**. `vis run` already executes up to `VIS_TASK_SLOTS` projects at once; if each task then spawns its own worker pool sized to the full CPU count (Vitest's default `maxWorkers`, v8 coverage, jest, etc.), you get `slots × cores` processes fighting for the same cores — fast tasks blow past their timeouts and the whole run slows down. Size the inner pool against the slots vis grants you instead:

```ts
// vitest.config.ts
import os from "node:os";
import { defineConfig } from "vitest/config";

const slots = Number(process.env.VIS_TASK_SLOTS) || 1;
const maxWorkers = Math.max(1, Math.floor(os.availableParallelism() / slots));

export default defineConfig({
    test: { maxWorkers, minWorkers: 1 },
});
```

### Task conditions [#task-conditions]

The `when` option skips a task unless the condition holds. Kept declarative on purpose — no dynamic code execution.

```json
{
    "targets": {
        "release": {
            "command": "pnpm publish",
            "options": { "when": "$CI" }
        },
        "dev-only": {
            "command": "node scripts/dev.mjs",
            "options": { "when": "!CI" }
        },
        "mac-codesign": {
            "command": "codesign ...",
            "options": { "when": { "platform": "darwin" } }
        },
        "prod-only": {
            "command": "pnpm build",
            "options": { "when": { "env": "NODE_ENV", "equals": "production" } }
        }
    }
}
```

Shapes:

| `when`               | Matches when…                     |
| -------------------- | --------------------------------- |
| `"$VAR"`             | `process.env.VAR` is non-empty    |
| `"!VAR"`             | `process.env.VAR` is empty/unset  |
| `"VAR"`              | same as `"$VAR"`                  |
| `{ env, equals }`    | `process.env[env] === equals`     |
| `{ env, in: [...] }` | `process.env[env]` is in the list |
| `{ env }`            | `process.env[env]` is non-empty   |
| `{ platform }`       | `process.platform` matches        |
| `{ env, platform }`  | both conditions match             |

### Task Types [#task-types]

| Type    | Default Cache | Description                             |
| ------- | ------------- | --------------------------------------- |
| `build` | `true`        | Generates artifacts                     |
| `test`  | `true`        | Validation (lint, typecheck, unit test) |
| `run`   | `false`       | One-off or long-running process         |

### Presets [#presets]

| Preset    | Sets                                          |
| --------- | --------------------------------------------- |
| `server`  | `persistent=true, cache=false, runInCI=false` |
| `utility` | `cache=false, runInCI=false`                  |

## Watch Mode [#watch-mode]

With `--watch`, vis runs the target once, then watches the matched project roots for file changes and reruns automatically:

```bash
vis run :test --watch
```

Changes are debounced (150ms). Cache-aware reruns are fast — only tasks whose inputs changed will re-execute.

### Scope: watch never watches the whole workspace [#scope-watch-never-watches-the-whole-workspace]

The watch set is **only the selected project set**, never every project in the
config. Selection flows through the same filters as a normal run before the
watcher sees a single path — narrow it with `-p` / `--projects` or `--query`:

```bash
vis run dev --watch -p my-service                    # one project by name
vis run :dev --watch --query "projectType=service"   # by metadata
vis run :dev --watch --query "projectType=library"
vis run :dev --watch --query "projectType=application && stack=backend"
```

Only projects that also declare the running target survive into the watch set.
After the first run the watcher narrows **further**: it switches from "project
roots" mode to **tracked mode**, watching just the directories and files the
last run actually touched (derived from each task's hash inputs) rather than the
whole project root. When a run produces no hash inputs it stays on project-roots
mode. The watcher is rebuilt after every rerun so the set always reflects what
the newest run cares about.

### Backend: Watchman with native fallback [#backend-watchman-with-native-fallback]

vis picks the file-watching backend automatically:

* **Watchman** — if both the `fb-watchman` module *and* the `watchman` binary
  are present, vis subscribes through the Watchman daemon. One daemon-side crawl
  is shared across every root, so this scales far past `fs.watch` on large
  trees. `fb-watchman` is an **optional** peer dependency — install it (and the
  `watchman` binary) only if you want this path. See the upstream reference:
  [Watchman](https://facebook.github.io/watchman/) and the
  [`fb-watchman` client](https://www.npmjs.com/package/fb-watchman).
* **Native `fs.watch`** — the default fallback. Uses Node's recursive
  `fs.watch({ recursive: true })` per project root. No extra dependency.

Detection is synchronous and cached, so the backend choice can't lose a race
against the fallback. Both backends feed the **same** debounce / ignore / filter
pipeline and emit paths with identical (`fs.watch`-relative) semantics, so
behaviour is the same regardless of which one is active — Watchman only changes
throughput, not results. Run [`vis doctor`](/docs/packages/vis/commands/doctor#runtime) to see which
backend is active (the `watchman` runtime check).

```mermaid
flowchart TD
    A["vis run --watch"] --> B["Resolve selected project set\n(-p / --query / target)"]
    B --> C["First run"]
    C --> D{"fb-watchman module\n+ watchman binary?"}
    D -- yes --> E["Watchman daemon\nsubscription per root"]
    D -- no --> F["Native fs.watch\n(recursive) per root"]
    E --> G["Shared debounce + ignore\n+ tracked-file filter"]
    F --> G
    G --> H["Change detected → rerun\n(cache-aware)"]
    H --> I["Rebuild watcher in tracked mode\n(only files the run touched)"]
    I --> G
```

### Keybinds [#keybinds]

While `--watch` is active, vis listens for Vitest-style single-key commands on stdin (TTY only — piped input falls back to file-change reruns):

| Key            | Action                                                                                          |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `r` / `Enter`  | Rerun the active task set immediately                                                           |
| `a`            | Clear any active project filter and rerun the full set                                          |
| `p`            | Prompt for a project-name substring filter; subsequent reruns operate on matching projects only |
| `q` / `Ctrl+C` | Exit watch mode cleanly                                                                         |
| `h` / `?`      | Print the keybind reference                                                                     |

The filter prompt accepts a case-insensitive substring match against `task.target.project`. Submitting an empty line cancels the prompt without changing the active filter.

Keybinds are a no-op in non-TTY environments (CI, piped stdin) so unattended runs aren't blocked.

If watch reruns silently stop firing on Linux you may have exhausted inotify watch slots. Run [`vis doctor`](/docs/packages/vis/commands/doctor#runtime) — its `inotify` runtime check reports the current limit and prints the `sysctl` snippet to raise it.

## Timeouts & Signals [#timeouts--signals]

Set `timeout` on a target to enforce a wall-clock budget. When the budget elapses, vis dispatches signals in two phases — modeled after GNU `timeout(1) --kill-after`:

1. Send `SIGTERM` and mark the task as timed out (exit code `124`, prefixed with `[timeout]` in the output).
2. After `killGracePeriodMs` (default `5000` ms), send `SIGKILL` to processes that ignored the term signal.

```jsonc
// project.json
{
    "targets": {
        "test": {
            "command": "vitest run",
            "options": {
                "timeout": 600000,
                "killGracePeriodMs": 10000,
            },
        },
    },
}
```

Set `killGracePeriodMs: 0` to disable the escalation entirely (SIGTERM only). Set `timeout: 0` (the default) to disable the watchdog.

The escalation matters on Windows and for tasks that swallow `SIGTERM` (test runners holding open child processes, deep child trees) — without it, a single hung task can outlive its budget indefinitely.

On Windows the underlying task-runner spawns each child in its own process group (`CREATE_NEW_PROCESS_GROUP`) so SIGINT / `Ctrl+C` is delivered as `CTRL_BREAK_EVENT` first, with a Job Object `TerminateJobObject` as the hard backstop after the grace window. This mirrors the Unix `setsid` + `killpg(SIGTERM)` → `SIGKILL` flow and means well-behaved CLIs (Node, Python, Go) get a chance to clean up before being force-killed. Tools that ignore Ctrl+Break are still terminated by the Job Object.

### Persistent task quit (`q` / Ctrl+C) [#persistent-task-quit-q--ctrlc]

Persistent tasks (`dev`, `serve`, `watch`, anything with `persistent: true`) are sent `SIGTERM` when you press `q` in the TUI or `Ctrl+C`. After a 2-second grace window, anything still alive gets `SIGKILL`. This catches dev servers and watchers that ignore `SIGTERM` — without the escalation, `q` would hang and force the user to send a second `Ctrl+C`.

Auto-started ephemeral services follow the same SIGTERM → 1.5s wait → SIGKILL pattern at run-end (whether the run finishes cleanly or is interrupted), so detached service children never outlive the run. Registry-mode services this run started survive by default; pass `--stop-services` to extend the same cleanup to them, or run `vis service stop --all` afterwards.

## Reverse order (teardown) [#reverse-order-teardown]

`--reverse` flips the dependency graph so dependents run before the things they depend on. Use it for teardown-style targets where the build-time order is exactly wrong:

```bash
vis run destroy --reverse           # tear stacks down leaves-first
vis run undeploy --reverse          # mirror of `vis run deploy`
vis affected destroy --reverse      # same, scoped to git-affected projects
```

### Why this matters [#why-this-matters]

If `app` depends on `lib` (so `app` builds *after* `lib`), then a CDK/Pulumi/CloudFormation `destroy` must run on `app` **before** `lib`, because `lib`'s outputs (an `Fn::ImportValue`, a shared VPC, a network stack) are still being consumed by `app`. Tearing down `lib` first leaves dangling exports and blocks the destroy.

`--reverse` reuses the same `dependsOn` declarations you already have — no duplicate "destroy graph" to maintain. The reversal happens after service auto-attach and project resolution, so `--affected`, `--query`, `--projects`, and persistent services all keep working unchanged.

```bash
vis run destroy --reverse --dry-run    # preview the teardown order
```

The dry-run plan reflects the reversed order, so you can verify the sequence before letting it touch anything.

### When you don't need it [#when-you-dont-need-it]

If your `destroy` target already declares `dependsOn` pointing the right way (e.g. `dependsOn: ["^destroy"]` reversed manually as `dependents: ["destroy"]`-style hand-roll), you don't need the flag — but most teams use the same `dependsOn` for both directions and toggle the order with `--reverse` instead.

## How It Works [#how-it-works]

1. **Parse selector** — Resolves `:target`, `~:target`, `#tag:target`, or `project:target`
2. **Filter** — Applies `--projects`, `--query`, and per-target filters (internal, osType, runInCI)
3. **Split** — Separates persistent tasks (run last) from regular tasks
4. **Graph** — Builds a dependency graph; sorts topologically
5. **Cache** — Checks cache for each task; skips if inputs haven't changed
6. **Execute** — Runs tasks in parallel with mutex serialization, envFile loading, retry, and shell overrides
7. **Persistent** — After the graph completes, runs persistent tasks concurrently until interrupted

## Configuration [#configuration]

Set target defaults in `vis.config.ts`:

```typescript
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    tasks: {
        build: {
            dependsOn: ["^build"],
            outputs: ["{projectRoot}/dist/**"],
            cache: true,
        },
        test: {
            dependsOn: ["build"],
            cache: true,
        },
    },
});
```

### Execution model: vis runs the configured command [#execution-model-vis-runs-the-configured-command]

`vis run <project>:<target>` executes the **command configured for that target** — the `command` in `vis.config.ts` / `vis.task.ts`, or the matching `package.json` script discovered for the project. There is no separate built-in ESLint/lint "inference" layer: `vis run :lint:eslint` runs whatever `lint:eslint` is wired to, so editing that script *does* change what runs. Prerequisites (codegen, type generation, building a dependency) belong in `dependsOn`, not in vis-specific magic.

A corollary: if a target's `dependsOn` names a target that has **no command** anywhere (e.g. `dependsOn: ["codegen"]` but the project has no `codegen` script), the dependency is a no-op — it can't run something that doesn't exist. vis now warns when this happens:

```
codegen required via dependsOn but no command is configured for @acme/app — skipping (no-op).
```

instead of silently succeeding, so a missing prerequisite surfaces locally rather than only in CI once a downstream task fails.

## Flakiness Report [#flakiness-report]

When historical run summaries exist (from prior `--summarize` runs), vis automatically prints a flakiness table at the end of every run — successful or failed — so a clean run that masked a flake via retries doesn't hide history that would help you investigate. Suppress with `--no-flaky`.

A retried-but-passed task counts as half a flake observation: the pipeline didn't actually break, but the restart still happened. The `Retried` column shows how many times each task needed at least one restart to finish.

```bash
vis run :test --summarize
```

```
Flaky tasks (based on historical runs):

  Task              Runs  Failures  Retried  Rate   Last Failure
  ────────────────  ────  ────────  ───────  ─────  ─────────────────────
  @myorg/api:test   12    3         2        33.3%  2026-04-10T14:23:00Z
  @myorg/web:build  8     1         0        12.5%  2026-04-08T09:15:00Z
```

Inline run output also flags retried tasks so you spot them as they finish:

```
✓  @myorg/api:test [retried 2x] (4.2s)
```

To fix flaky tasks, add `retryCount` to their target options in `project.json`:

```json
{
    "targets": {
        "test": {
            "options": { "retryCount": 2, "retryDelay": "exponential" }
        }
    }
}
```

### `--fail-on-retry` [#--fail-on-retry]

By default, a task that succeeds after one or more retries still marks the run as a success — that's the point of the safety net. Set `--fail-on-retry` (or wire it into a periodic CI job) to flip this: any non-zero retry count fails the run, even when every task ultimately passed. Useful for nightly "health check" pipelines that want to surface masked flakes the day-to-day workflow tolerates.

```bash
vis run :test --fail-on-retry
```

## CI Log Grouping [#ci-log-grouping]

`vis run` automatically wraps each task's stdout in a collapsible group when it detects a supported CI runner — GitHub Actions (`GITHUB_ACTIONS=true`), GitLab CI (`GITLAB_CI=true`), Buildkite (`BUILDKITE=true`), or Azure Pipelines (`TF_BUILD=True`). Failed tasks render expanded so the failure is visible without an extra click. CircleCI is intentionally not auto-detected: its 2.0+ format has no inline grouping directive (steps auto-group in the web UI).

Override the default detection in `vis.config.ts → run.ciGrouping`:

```ts
export default defineConfig({
    run: {
        // "auto" (default) — detect via env. "off" disables grouping.
        // "azure" / "buildkite" / "github" / "gitlab" force the format
        // on self-hosted runners that don't set the standard env vars.
        ciGrouping: "auto",
    },
});
```

See the [CI/CD guide](/docs/packages/vis/guides/ci-cd) for the full env-var → format mapping.


# vis sbom (/docs/packages/vis/commands/sbom)



# vis sbom [#vis-sbom]

Generates a CycloneDX 1.7 Software Bill of Materials (SBOM) for the current workspace, capturing every workspace project, every reachable registry dependency, per-version licenses, and the dependency graph.

The generator walks the workspace project graph plus the lockfile closure, so the emitted BOM includes both direct and transitive dependencies — the same closure that is actually installed in `node_modules`.

## Usage [#usage]

```bash
vis sbom [options]
```

## Examples [#examples]

```bash
# Full-workspace SBOM → sbom.cdx.json
vis sbom

# Scope to a single project's closure
vis sbom --focus=my-app

# Focus multiple projects
vis sbom --focus=my-app,other-app

# XML output
vis sbom --format=xml --output=sbom.cdx.xml

# Include devDependencies
vis sbom --include-dev

# Write to stdout (for piping / CI)
vis sbom --output=-
```

## Options [#options]

| Option          | Default         | Description                                                                                       |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `--focus`       |                 | Project name(s) to focus on — comma-separated. Scopes the BOM to the transitive closure.          |
| `--format`      | `json`          | Output format: `json` (CycloneDX 1.7 JSON) or `xml`.                                              |
| `--output`      | `sbom.cdx.json` | Output file path (resolved against the workspace root). Use `-` to write to stdout.               |
| `--include-dev` | `false`         | Include `devDependencies` in the closure walk. Default is production-only, per industry practice. |

## What's in the BOM [#whats-in-the-bom]

Every emitted BOM passes the vendored CycloneDX 1.7 JSON Schema (`bom-1.7.schema.json`). Each `components[]` entry carries:

* `name` + `version` + `purl` (`pkg:npm/…` Package URL)
* `bom-ref` (unique per component)
* `type: "library"` (or `"application"` for the workspace root / focus target)
* `scope: "required" | "optional"` — `optional` propagates only through `optionalDependencies` edges; `required` wins on any shared path
* `hashes: [{ alg, content }]` — decoded from SRI when the lockfile provides one
* `licenses` — resolved against the specific installed `node_modules/.pnpm/<name>@<version>/` copy so different versions can carry different licenses
* `description`, `author`, `externalReferences` (`homepage`, `vcs`, `issue-tracker`) from the installed copy

`dependencies[]` edges cover both workspace project → project edges and registry → registry edges (from the lockfile graph walk).

## Package manager support [#package-manager-support]

| Package manager | Lockfile                      | SBOM coverage                                                                                                                                                                                                                                    |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| pnpm            | `pnpm-lock.yaml`              | ✅ Full                                                                                                                                                                                                                                           |
| npm             | `package-lock.json` (v2 / v3) | ✅ Full                                                                                                                                                                                                                                           |
| Yarn Classic    | `yarn.lock` (v1)              | ✅ Full                                                                                                                                                                                                                                           |
| Yarn Berry      | `yarn.lock` (v2+)             | ✅ Full except integrity hashes — Berry uses XXH64 (`checksum:`), which is not a cryptographic hash and is outside CycloneDX 1.7's `HashAlgorithm` enum. Berry components emit without a `hashes` entry; all other fields are populated normally. |
| Bun             | `bun.lock` (1.1+)             | ✅ Full                                                                                                                                                                                                                                           |

Binary `bun.lockb` is not supported.

## Focus mode [#focus-mode]

`--focus=<project>` scopes the BOM to one or more workspace projects plus their transitive closure. The focused project becomes `metadata.component`; other workspace projects outside the closure are excluded.

Useful for Docker images, deploy artifacts, or per-app compliance reports:

```bash
vis sbom --focus=web-app --output=dist/web-app/sbom.cdx.json
```

## Limitations [#limitations]

* **License lookup is best-effort**. The generator resolves each `name@version`'s license against its installed `package.json` — trying pnpm's virtual store (`node_modules/.pnpm/<name>@<version>/node_modules/<name>/package.json`, including peer-disambiguated suffixes) first, then the hoisted `node_modules/<name>/package.json` (version-matched). npm's nested `node_modules/parent/node_modules/<pkg>/` layouts and Yarn PnP are not searched; components whose installed copy isn't found emit without license decoration rather than failing.
* **Yarn Berry integrity** is dropped (XXH64 is not a supported algorithm). See the matrix above.

## Why [#why]

Regulatory mandates for SBOMs include:

* **US Executive Order 14028** (2021) — federal supply-chain security
* **EU Cyber Resilience Act** — effective December 2027
* **PCI DSS 4.0** — payment-card industry compliance

`vis sbom` is designed to be the first monorepo-native CycloneDX generator — moon, Nx, and Turborepo do not emit SBOMs out of the box. `cdxgen` exists but is heavy (200+ dependencies) and not monorepo-aware.

## Configuration [#configuration]

No `vis.config.ts` configuration is required. The command reads directly from the workspace lockfile + `package.json` files.


# vis secrets (/docs/packages/vis/commands/secrets)



# vis secrets [#vis-secrets]

Scan the workspace (or a subset) for hardcoded secrets and credentials. `vis secrets` is a workspace-aware wrapper around [`@visulima/secret-scanner`](/docs/packages/secret-scanner) — a Rust port of the gitleaks detection engine — that adds git-native file selection (`--staged`, `--since`, `--affected`), baseline tooling, SARIF rendering, opt-in rule presets, and optional live validation against provider APIs.

## Usage [#usage]

```bash
vis secrets [paths...] [options]
```

Positional `paths` default to the workspace root. Pass one or more directory or file paths to scope the scan.

## Examples [#examples]

```bash
# Scan the workspace (grouped, colourised output)
vis secrets

# Pre-commit mode — scan only files staged for the current commit
vis secrets --staged

# Scan only files changed since a ref
vis secrets --since main

# Scan projects affected by the current branch (git diff against HEAD~1 or $VIS_BASE)
vis secrets --affected

# Seed an initial baseline from current findings
vis secrets --init

# Preview the baseline without writing files
vis secrets --init --dry-run

# Enable opt-in rule groups additively (defaults still fire)
vis secrets --enable-rule tag:preset:weak-passwords
vis secrets --enable-rule tag:preset:password-manager
vis secrets --enable-rule tag:preset:exposed-files

# Restrict output to one opt-in group only (whitelist)
vis secrets --include-rule tag:preset:password-manager

# Audit a release artefact for accidentally-shipped exposures
vis secrets dist --enable-rule tag:preset:exposed-files

# Single-rule spot check
vis secrets --include-rule stripe-access-token

# Drop a noisy rule but keep the rest of the defaults
vis secrets --exclude-rule generic-api-key

# Raise the confidence floor — CI-friendly precision filter
vis secrets --min-confidence high

# Live-verify findings against provider APIs, then fail CI on unverified matches
vis secrets --validate --only-verified

# List non-HTTP validators referenced by the ruleset + install hints
vis secrets --list-validators

# Baseline suppression + diff
vis secrets --baseline .secrets-baseline.json

# Merge current findings into the baseline and exit 0
vis secrets --update-baseline

# SARIF output for GitHub code scanning
vis secrets --format sarif > report.sarif
```

## Modes [#modes]

`vis secrets` picks the scan target from the first matching flag (in order):

| Flag               | Source                                        | Best for                    |
| ------------------ | --------------------------------------------- | --------------------------- |
| `--staged`         | `git diff --cached --name-only`               | Pre-commit hooks            |
| `--since <ref>`    | `git diff <ref>..HEAD --name-only`            | CI on pull-request branches |
| `--affected`       | `git diff $VIS_BASE..HEAD` (default `HEAD~1`) | Incremental CI / monorepos  |
| *(none — default)* | Positional paths, else workspace root         | Full audit / seeding        |

`--staged`, `--since`, and `--affected` all require a git working tree — the command exits with code 2 if none is detected (except `--affected`, which falls back to a full scan with a warning).

Alongside those, three flags run a one-shot reporting pass instead of scanning:

* `--init` scaffolds `.secrets-baseline.json` from current findings. It refuses to overwrite an existing baseline; delete it first to re-init. Pair with `--dry-run` to preview.
* `--list-rules` prints every compiled rule (id, description, keywords, tags) and exits.
* `--list-validators` prints non-HTTP validator types referenced by the current ruleset with `npm add …` hints for the optional peer dependencies that unlock them.

## Options [#options]

### Input selection [#input-selection]

| Option                  | Type       | Default | Description                                                                        |
| ----------------------- | ---------- | ------- | ---------------------------------------------------------------------------------- |
| `--staged`              | boolean    | `false` | Scan only files staged for commit. Requires git.                                   |
| `--since <ref>`         | string     | —       | Scan only files changed since `<ref>` (e.g. `main`, `origin/HEAD`).                |
| `--affected`            | boolean    | `false` | Scan only files changed against `$VIS_BASE` (default `HEAD~1`).                    |
| `--exclude <pattern>`   | `string[]` | —       | Gitignore-syntax pattern to exclude from the walk. Repeatable.                     |
| `--exclude-from <path>` | `string[]` | —       | Gitignore-shaped file the walker should honor (e.g. `.secretsignore`). Repeatable. |
| `--include-hidden`      | boolean    | `false` | Visit dotfiles and hidden directory entries.                                       |
| `--no-gitignore`        | boolean    | `false` | Do not respect `.gitignore` / `.ignore` / global excludes.                         |
| `--max-size <bytes>`    | number     | 10 MiB  | Skip files larger than this.                                                       |

### Rule selection [#rule-selection]

| Option                   | Type       | Default | Description                                                                                       |
| ------------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------- |
| `--enable-rule <spec>`   | `string[]` | —       | Additive — turn on opt-in rules without restricting output. Rule id or `tag:<name>`. Repeatable.  |
| `--include-rule <spec>`  | `string[]` | —       | Whitelist — only emit matching findings. Implies enablement. Rule id or `tag:<name>`. Repeatable. |
| `--exclude-rule <spec>`  | `string[]` | —       | Blacklist — drop matching findings. Rule id or `tag:<name>`. Repeatable.                          |
| `--min-confidence <lvl>` | string     | `low`   | Drop rules whose author-declared confidence is below this floor: `low`, `medium`, `high`.         |
| `--config <path>`        | string     | —       | Path to a gitleaks-compatible JSON config.                                                        |
| `--no-extend-bundled`    | boolean    | `false` | With `--config`, replace the bundled ruleset instead of layering on top of it.                    |

**Bundled opt-in groups:** `tag:preset:weak-passwords` (low-entropy credentials complementing `generic-api-key`), `tag:preset:password-manager` (1Password / Bitwarden / LastPass / KeePass / browser-CSV export detection), `tag:preset:exposed-files` (37 path-driven rules covering committed `.env`, `.git/`, `.aws/credentials`, private keys, DB dumps, source maps with `sourcesContent`, lockfiles in `dist/`, IDE workspace dumps, …). All three ship `defaultEnabled: false`. Shorthand alternative: list them under `secrets.config.presets` in `vis.config.ts` (see below) and skip the long `tag:preset:*` strings on the CLI.

**Confidence semantics:** every bundled gitleaks rule defaults to `low` (no explicit label). Raising the floor to `medium` or `high` drops every unlabeled rule along with explicit low-confidence rules, so a ruleset needs confidence metadata before `--min-confidence high` is useful.

### Validation [#validation]

| Option              | Type    | Default | Description                                                                                    |
| ------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------- |
| `--validate`        | boolean | `false` | Live-verify findings against the provider's API after detection.                               |
| `--only-verified`   | boolean | `false` | With `--validate`, drop every finding whose validation is not `verified`. Useful for CI.       |
| `--list-validators` | boolean | `false` | Print non-HTTP validator types referenced by the current ruleset, with peer-dep install hints. |

Validation sends one HTTP request per finding (per-host concurrency capped at 4, global at 8). Supports Kingfisher-style HTTP validators with `StatusMatch` / `WordMatch` response matchers. Other validation kinds (gRPC, multi-step HTTP, checksum) mark the finding as `validation=skipped` — they don't block the pass.

> **Warning:** `--validate` sends the candidate secret to the provider. Some providers alert their security team on failed auth attempts. Only enable on repos you own or have explicit authorisation to test.

### Output [#output]

| Option              | Type    | Default | Description                                                           |
| ------------------- | ------- | ------- | --------------------------------------------------------------------- |
| `--format`          | string  | `text`  | Output format: `text`, `json`, `sarif`.                               |
| `--redact`          | boolean | `false` | Mask the `match` and `secret` strings in every emitted finding.       |
| `--quiet`           | boolean | `false` | Suppress progress output. Only findings are emitted.                  |
| `--verbose`         | boolean | `false` | Print diagnostic info to stderr (skipped rules, invalid regex, etc.). |
| `--concurrency <n>` | number  | auto    | Rayon worker threads. `0` / omit = auto.                              |

`text` is the default TTY format — grouped per file, colourised when stdout is a TTY. `json` emits an array of `Finding` objects with paths relative to the workspace root. `sarif` emits SARIF v2.1.0 with `file://` URIs, a `tool.driver.rules[]` cross-reference, and `result.level` — compatible with GitHub code scanning and GitLab security dashboards.

### Baseline [#baseline]

| Option               | Type    | Default                  | Description                                                          |
| -------------------- | ------- | ------------------------ | -------------------------------------------------------------------- |
| `--baseline <path>`  | string  | `.secrets-baseline.json` | Suppress findings whose fingerprint already appears in the baseline. |
| `--init`             | boolean | `false`                  | Scaffold a baseline from current findings. Refuses to overwrite.     |
| `--dry-run`          | boolean | `false`                  | With `--init`, preview without writing files.                        |
| `--update-baseline`  | boolean | `false`                  | Merge current findings into the baseline and exit 0.                 |
| `--replace-baseline` | boolean | `false`                  | With `--update-baseline`, replace rather than merge.                 |

Baselines are fingerprint-keyed JSON files (`<file>:<ruleID>:<startLine>`) committed to the repo. A missing file is treated as empty; a malformed file emits a stderr warning but never fails the scan. When a baseline is present the default text output appends a diff summary (`+N new`, `N unchanged`, `-N resolved`).

### Exit codes [#exit-codes]

| Code | Meaning                                                          |
| ---- | ---------------------------------------------------------------- |
| `0`  | No findings after suppression, or `--update-baseline` succeeded. |
| `1`  | One or more findings emitted.                                    |
| `2`  | Usage / configuration error (invalid flag value, no git tree).   |

## Workspace config [#workspace-config]

Commit defaults once in `vis.config.ts` under `secrets`. The grouped shape mirrors [`ScanOptions`](/docs/packages/secret-scanner/configuration):

```typescript
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    secrets: {
        baseline: ".secrets-baseline.json",
        config: {
            extendBundled: true,
            minConfidence: "medium",
            onlyVerified: false,
            // Opt-in preset shorthand — each entry expands to `tag:preset:<name>`
            // and is merged with `rules.enable`. See "Bundled opt-in groups"
            // above for the available presets.
            presets: ["weak-passwords", "exposed-files"],
            validate: false,
        },
        rules: {
            // `enable` still works for ad-hoc rule ids or tags; `presets` is the
            // ergonomic path for the bundled groups.
            exclude: ["generic-api-key"],
        },
        redact: false,
        walk: {
            excludeFromFiles: [".secretsignore"],
            excludePatterns: ["dist/**", "coverage/**"],
            gitignore: true,
            includeHidden: false,
            maxFileSize: 10 * 1024 * 1024,
        },
    },
});
```

CLI flags always take precedence over the config file. The full reference lives in [`@visulima/secret-scanner` → Configuration](/docs/packages/secret-scanner/configuration).

## Pre-commit hook [#pre-commit-hook]

```bash
vis hook add secrets
```

Appends a managed block to `.husky/pre-commit` (or creates one) that runs `vis secrets --staged --quiet`. Remove the block — or delete the file — to disable.

## CI recipe (SARIF upload) [#ci-recipe-sarif-upload]

```yaml
# .github/workflows/secrets.yml
name: Secrets
on: [push, pull_request]
jobs:
    scan:
        runs-on: ubuntu-latest
        permissions:
            security-events: write
            contents: read
        steps:
            - uses: actions/checkout@v4
              with: { fetch-depth: 0 }
            - uses: pnpm/action-setup@v4
            - run: pnpm install --frozen-lockfile
            - run: pnpm vis secrets --format sarif > report.sarif
              continue-on-error: true
            - uses: github/codeql-action/upload-sarif@v3
              with: { sarif_file: report.sarif }
```

For pull-request gating without a baseline, swap the scan command for:

```bash
pnpm vis secrets --since origin/${{ github.base_ref }} --min-confidence medium
```

## Migrating from other tools [#migrating-from-other-tools]

`vis migrate` ports existing gitleaks / secretlint setups to `vis secrets`:

```bash
vis migrate gitleaks     # keeps gitleaks.toml, rewrites scripts and hooks
vis migrate secretlint   # removes @secretlint/*, rewrites scripts and hooks
vis migrate verify       # sanity-check the migration
```

## Related [#related]

* [`@visulima/secret-scanner`](/docs/packages/secret-scanner) — the underlying engine and library API.
* [Configuration reference](/docs/packages/secret-scanner/configuration) — every field in `ScanOptions`.
* [Suppression guide](/docs/packages/secret-scanner/suppression) — inline markers, baseline workflow, allowlists.
* [`vis hook`](/docs/packages/vis/commands/hook) — install / uninstall / migrate git hooks.


# vis security (/docs/packages/vis/commands/security)



# vis security [#vis-security]

Inspect the build-script triage, push `vis.config` security settings to the active package manager's native config files, and verify the resolved lockfile closure against supply-chain policies. The subcommands give the same view that the post-install drift report uses.

## Usage [#usage]

```bash
vis security <action> [options]
```

## Actions [#actions]

### list [#list]

Show the full build-script triage report:

```bash
vis security list
vis security list --json
```

#### What it reports [#what-it-reports]

* **Approved** — installed packages with lifecycle scripts that match an entry in `security.allowBuilds`. Wildcard (`@scope/*`, `name@*`) and version-pinned (`name@1.2.3`, requires `pinVersions: true`) patterns are honored.
* **Unapproved** — installed packages with lifecycle scripts that have **no** matching entry. Includes the synthetic `install (binding.gyp)` hook for packages that ship a `binding.gyp` but no explicit install script — npm runs `node-gyp rebuild` for them implicitly.
* **Stale allowlist entries** — `security.allowBuilds` keys that don't match anything installed. Safe to prune.
* **Version drift** — only emitted when `security.pinVersions: true`. Entries pointing at a version that is no longer installed, with a `from  →  to` migration suggestion.
* **Native-config drift** — when `vis.config` and the PM's own config files (`pnpm-workspace.yaml`, `bunfig.toml`, `.npmrc`, `.yarnrc.yml`) disagree on `allowBuilds`, `minimumReleaseAge`, or `minimumReleaseAgeExclude`.

#### `--json` output shape [#--json-output-shape]

```json
{
    "packageManager": "pnpm",
    "pinVersions": false,
    "installed": [{ "name": "esbuild", "version": "0.20.0", "hooks": ["postinstall"] }],
    "unapproved": [{ "name": "sharp", "version": "0.32.6", "hooks": ["install"] }],
    "excess": ["removed-pkg"],
    "versionDrift": [{ "from": "esbuild@0.19.0", "to": "esbuild@0.20.0" }],
    "drift": { "hasDrift": false, "packageManager": "pnpm" }
}
```

### sync [#sync]

Push `security.allowBuilds`, `minimumReleaseAge`, and `minimumReleaseAgeExclude` from `vis.config` into the active package manager's native config files:

```bash
vis security sync
vis security sync --skip-allow-builds       # only sync minimumReleaseAge
vis security sync --skip-min-release-age    # only sync allowBuilds
```

### run [#run]

LavaMoat `allow-scripts run` parity — execute the lifecycle scripts for every package in `security.allowBuilds` **without reinstalling** the dependency tree. Use this after installing with `ignore-scripts=true` and triaging via `vis approve-builds`.

```bash
vis security run                # run preinstall/install/postinstall for every approved package
vis security run --with-root    # also run the workspace root's prepublish + prepare hooks
vis security run --root-only    # skip dependency scripts; run only root prepublish + prepare
```

Wildcards (`@scope/*`, `name@*`) and version-pinned patterns (`name@1.2.3`, requires `pinVersions: true`) are honored — the runner expands them against installed packages before invoking each hook. Unapproved packages are skipped silently.

### tripwire [#tripwire]

Install `@lavamoat/preinstall-always-fail` as a `devDependency`. Its preinstall script always fails, but is masked by `ignore-scripts=true`. If somebody removes that gate, the next install fails loudly instead of silently running every dependency's lifecycle scripts.

```bash
vis security tripwire             # install the tripwire devDependency via the detected PM
vis security tripwire --status    # report whether the tripwire is currently installed
vis security tripwire --remove    # delete the tripwire entry from package.json
```

The installer uses the detected PM's idiomatic `add -D` invocation (pnpm `add -D -w`, bun `add -d`, npm `install --save-dev`, yarn `add -D`). `--remove` only edits `package.json` — run your PM's install afterwards to clean `node_modules`.

#### Per-PM targets [#per-pm-targets]

| PM   | `allowBuilds` target                                                   | `minimumReleaseAge` target                                   | Excludes target                      |
| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------ |
| pnpm | `pnpm-workspace.yaml` `allowBuilds` map + `onlyBuiltDependencies` list | `pnpm-workspace.yaml` `minimumReleaseAge` (minutes)          | `minimumReleaseAgeExclude` list      |
| bun  | `package.json` `trustedDependencies`                                   | `bunfig.toml` `[install]` `minimumReleaseAge` (**seconds**)  | `minimumReleaseAgeExcludes` (plural) |
| npm  | *(no native allowlist)*                                                | `.npmrc` `min-release-age=<duration>` (e.g. `2d`, `48h`)     | *(npm has no native excludes list)*  |
| yarn | *(no native allowlist)*                                                | `.yarnrc.yml` `npmMinimalAgeGate: "<duration>"` (berry only) | *(yarn has no native excludes list)* |

Vis canonicalises all durations to **minutes**. The syncer rounds sub-minute fractional values up to whole minutes before writing so that the same vis-config value round-trips identically across PMs.

Yarn classic (no `.yarnrc.yml`) is silently skipped because it has no equivalent native setting.

### keys-refresh [#keys-refresh]

Force-refresh the cached npm signing keys used by the **signatures marshall**. The keys are fetched from `registry.npmjs.org` and cached on disk; use this to drop a stale cache or pre-warm a fresh key set.

```bash
vis security keys-refresh           # drop the disk cache and fetch a fresh key set
vis security keys-refresh --clear   # only drop the cache, do not refetch
vis security keys-refresh --json    # emit the refresh result as JSON for tooling
```

### verify-lockfile [#verify-lockfile]

Re-validate the **entire resolved lockfile closure** against the supply-chain policies — vis's counterpart to pnpm v11's lockfile-verification phase. Unlike the pre-install marshalls (which only inspect packages being *added*), this catches a tampered/poisoned lockfile even on npm/yarn/bun and even when nothing is being added.

```bash
vis security verify-lockfile            # re-validate every locked entry; exit non-zero on a violation
vis security verify-lockfile --offline  # skip network-bound policies (firstSeen, publisherChange)
vis security verify-lockfile --json     # emit the verification result as JSON for CI
```

It composes three configured checks into one pass/fail attestation:

* `security.policies.firstSeen.minutes` — block any locked version published less than N minutes ago.
* `security.policies.publisherChange.mode: "no-downgrade"` — block a locked version that dropped a provenance attestation a prior version carried.
* `security.blockExoticSubdeps` — flag transitive edges resolving from a git repo or remote tarball (honoring `security.exoticSubdepsAllow`).

When none of the three is configured the run is **skipped** (exit 0). A **missing lockfile fails** the attestation rather than silently passing — the closure cannot be attested. `firstSeen` / `publisherChange` are network-bound and emit an `info`-level skip under `--offline`; `blockExoticSubdeps` is offline-pure and always runs. Output mirrors pnpm's attestation lines:

```
✓ Lockfile passes supply-chain policies (148 entries, 0.4s)
✗ Lockfile failed supply-chain policy check (148 entries, 0.4s)
  [firstSeen] evil@1.0.0 was published 30 min ago — below the 1440 min firstSeen cooldown.
  [blockExoticSubdeps] git-dep pulled from exotic source by prod-pkg@1.0.0: github:attacker/evil#deadbeef
```

## Options [#options]

### `vis security list` [#vis-security-list]

| Option   | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| `--json` | `false` | Emit the report as JSON instead of human-readable text |

### `vis security sync` [#vis-security-sync]

| Option                   | Default | Description                                                                       |
| ------------------------ | ------- | --------------------------------------------------------------------------------- |
| `--skip-allow-builds`    | `false` | Skip syncing `allowBuilds` (`trustedDependencies` / `onlyBuiltDependencies` etc.) |
| `--skip-min-release-age` | `false` | Skip syncing `minimumReleaseAge` and its excludes                                 |

### `vis security run` [#vis-security-run]

| Option        | Default | Description                                                                    |
| ------------- | ------- | ------------------------------------------------------------------------------ |
| `--with-root` | `false` | After dependency scripts, also run the workspace root's prepublish + prepare   |
| `--root-only` | `false` | Skip dependency scripts and only run the workspace root's prepublish + prepare |

### `vis security tripwire` [#vis-security-tripwire]

| Option     | Default | Description                                                    |
| ---------- | ------- | -------------------------------------------------------------- |
| `--status` | `false` | Report whether `@lavamoat/preinstall-always-fail` is installed |
| `--remove` | `false` | Strip `@lavamoat/preinstall-always-fail` from `package.json`   |

### `vis security keys-refresh` [#vis-security-keys-refresh]

| Option    | Default | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| `--clear` | `false` | Only clear the cache, do not refetch                   |
| `--json`  | `false` | Emit the result as JSON instead of human-readable text |

### `vis security verify-lockfile` [#vis-security-verify-lockfile]

| Option      | Default | Description                                                         |
| ----------- | ------- | ------------------------------------------------------------------- |
| `--json`    | `false` | Emit the verification result as JSON instead of human-readable text |
| `--offline` | `false` | Skip network-bound policies (`firstSeen`, `publisherChange`)        |

## Drift report (post-install) [#drift-report-post-install]

After `vis install` / `vis update` / `vis add`, vis automatically runs the drift check and prints a one-line nudge per drifted field. The hint suggests `vis security sync` as the remediation:

```
vis.config and pnpm-native config disagree on security settings:
  allowBuilds — only in vis.config: sharp
  minimumReleaseAge — vis.config: 2880 min, pnpm: unset
  Run 'vis security sync' to push vis.config values to the native config.
```

## Related [#related]

* `vis approve-builds` — interactive review of unapproved build scripts.
* `vis init` — bootstrap a `vis.config.ts` with secure defaults and an optional `--sync-native` step.
* `vis audit` — full supply-chain audit; `verify-lockfile` is the closure-only attestation subset suitable for a single CI gate line.


# vis service (/docs/packages/vis/commands/service)



# vis service [#vis-service]

Manage shared sidecar services — Postgres, mock servers, devservers — that should outlive a single `vis run` invocation. A registered service stays alive in the background; subsequent `vis run` calls auto-attach to it instead of cold-starting.

## Subcommands [#subcommands]

| Command                    | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `vis service start <id>`   | Spawn the target's command detached, probe readiness, register it |
| `vis service stop <id>`    | SIGTERM (then SIGKILL after grace) and unregister                 |
| `vis service stop --all`   | Stop every service registered under the current workspace         |
| `vis service list`         | Show registered services (table, or `--format=json`)              |
| `vis service status <id>`  | Re-run the readiness probe; exit 0 healthy, 1 unhealthy           |
| `vis service restart <id>` | Stop + start in one call                                          |
| `vis service logs <id>`    | Print captured stdout/stderr; `-f`/`--follow` to tail             |

## Options [#options]

| Option            | Subcommand(s)                | Default | Description                                      |
| ----------------- | ---------------------------- | ------- | ------------------------------------------------ |
| `--timeout <ms>`  | `start`, `status`, `restart` | —       | Readiness probe timeout in milliseconds          |
| `--no-readiness`  | `start`, `restart`           | `false` | Skip the readiness probe                         |
| `--all`           | `stop`                       | `false` | Stop every service registered for this workspace |
| `--grace-ms <ms>` | `stop`, `restart`            | —       | Override the SIGTERM→SIGKILL grace period (ms)   |
| `--follow`, `-f`  | `logs`                       | `false` | Follow the log file (like `tail -f`)             |
| `--format <fmt>`  | `list`                       | `table` | Output format: `table` or `json`                 |

## Eligibility — declaring a service [#eligibility--declaring-a-service]

A target becomes registry-eligible when it carries a `service` block in `vis.task.ts`. Bare `preset: "server"` keeps today's behaviour (in-run-only persistent task).

```ts
// vis.task.ts
export default defineVisTaskConfig({
    targets: {
        "@app/api:db": {
            command: "docker compose up postgres",
            preset: "server",
            visOptions: {
                service: {
                    port: 5432,
                    env: { DB_URL: "postgres://127.0.0.1:5432/app" },
                    readiness: { tcp: { port: 5432, timeoutMs: 30_000 } },
                    killGracePeriodMs: 5_000,
                },
            },
        },
        "@app/api:test": {
            command: "vitest",
            dependsOn: ["@app/api:db"],
        },
    },
});
```

`service.env` is merged into every transitive dependent of `@app/api:db` when the service is satisfied externally — the test target sees `DB_URL` without ever booting Postgres itself.

## Lifecycle [#lifecycle]

```bash
vis service start @app/api:db   # boots Postgres, waits for :5432, registers it
vis service list                # @app/api:db | pid 12345 | uptime 3s | log /…/db.log
vis run @app/api:test           # detects the registered service, prunes db from the graph
vis service logs @app/api:db -f # tail captured output
vis service stop @app/api:db    # SIGTERM → grace → SIGKILL → deregister
```

`vis service start` refuses to register a service that fails its readiness probe — the spawned process is killed and no entry is written. Use `--no-readiness` to skip the probe (e.g. when the command never opens a port).

`vis service stop` is idempotent — a missing entry returns success without touching anything else.

## Auto-attach in `vis run` [#auto-attach-in-vis-run]

When `vis run` builds the task graph, it walks every task whose target carries `service` and:

* **service registered + readiness probe passes** → prune the service task from the graph and merge its `service.env` into every transitive dependent. The dependent runs with the registered service's env injected.
* **service registered + readiness probe fails** → demote to the missing-service path: emit a diagnostic with `vis service start <id>` and skip auto-attach.
* **service not registered, only present as a dep** → diagnostic; the run still proceeds for tasks that don't depend on it.
* **service not registered, user invoked it directly** → falls through to today's persistent-task path, booting in-process for the lifetime of the run.

Multiple services contributing env to the same dependent are merged in deterministic alphabetical order — last writer wins, so `@app/cache` overrides `@app/api`.

Auto-started registry-mode services persist past the run by design (so the next `vis run` reuses them). Pass `vis run --stop-services` to extend the run's clean/`q`/Ctrl+C cleanup to those services for the duration of a single run — handy when you want a fully ephemeral inner loop without giving up the registry's cross-run sharing.

## Registry layout [#registry-layout]

Per-workspace registry directory: `~/.vis-services/<sha256(workspaceRoot)[:12]>/`. Each entry is a 0o600 JSON file named after the slugified target id (`@app/api:db` → `@app_api__db.json`). Atomic writes (temp-then-rename) guard against half-written files; an exclusive-create file lock serializes concurrent `start`/`stop` for the same id.

The registry lives outside the workspace by design: detached PID files in the working tree would dirty `git status` and mislead `affected` detection.

## Cross-shell semantics [#cross-shell-semantics]

Services from one workspace are invisible to another — the directory hash is workspace-rooted. There is **no auto-cleanup on shell exit** in v1: a `vis service start` you forget about will keep running until you run `vis service stop`, the wrapper is killed, or the host is rebooted. `vis service list` shows orphans across all shells under the same workspace, and `vis service stop --all` is the catch-all.

## Liveness and crash recovery [#liveness-and-crash-recovery]

Liveness uses the POSIX `process.kill(pid, 0)` probe. If the registered PID is gone, `list` and `run` prune the entry. The harder case — wrapper alive, server crashed — is handled at attach time by re-running the readiness probe; the entry is demoted (not pruned) so the user sees a "not running" diagnostic rather than a silent half-run.

## `--format=json` [#--formatjson]

```bash
vis service list --format=json
```

Emits an array of registry entries with stable keys (`id`, `pid`, `slug`, `command`, `cwd`, `startedAt`, `logFile`, `visVersion`, `config`, `env`). Stable for CI and tooling.

## Deferred (not in v1) [#deferred-not-in-v1]

* HTTP / log-line readiness probes (TCP only).
* Auto-restart on crash (no supervisor loop).
* Cross-shell garbage collection (manual `stop --all` for now).
* `vis service exec <id>` — run a one-shot command in the service's env.


# vis sort-package-json (/docs/packages/vis/commands/sort-package-json)



# vis sort-package-json [#vis-sort-package-json]

Normalise every `package.json` in the workspace using the `sort-package-json` Rust implementation. Use `--check` in CI to assert the tree is already sorted without writing.

## Usage [#usage]

```bash
vis sort-package-json [options]
```

## Examples [#examples]

```bash
vis sort-package-json
vis sort-package-json --check                                  # CI: exit 1 if unsorted
vis sort-package-json --sort-scripts                           # also alphabetise the scripts field
vis sort-package-json --indent 4                               # force 4-space indent
vis sort-package-json --indent tab                             # force tab indent
vis sort-package-json --ignore '**/fixtures/**'                # skip globs (repeatable)
vis sort-package-json --sort-order name,version,license        # custom prefix order
vis sort-package-json --unsorted dependencies,devDependencies  # preserve key order in those sections
vis sort-package-json --no-final-newline                       # no trailing newline
vis sort-package-json --line-ending crlf                       # force CRLF
vis sort-package-json --no-format-bugs                         # keep `bugs: { url }` instead of collapsing to a string
vis sort-package-json --no-format-repository                   # keep full `repository: { type, url }` instead of `owner/repo`
vis sort-package-json --no-sort-exports                        # keep author-defined `exports` condition order
vis sort-package-json --no-editorconfig                        # ignore `.editorconfig` for indent / line-ending defaults
```

## Cosmetic post-sort normalisations [#cosmetic-post-sort-normalisations]

After the Rust sorter finishes, three opt-out cleanups run in TypeScript:

* **`formatBugs`** collapses `{ "bugs": { "url": "https://…" } }` to the bare string `{ "bugs": "https://…" }` when only `url` is present.
* **`formatRepository`** collapses `{ "repository": { "type": "git", "url": "git+https://github.com/owner/repo.git" } }` to the GitHub shorthand `{ "repository": "owner/repo" }`. SSH URLs (`git+ssh://git@github.com/...`) are recognised too. The shorthand is only emitted when `directory` is absent, so monorepo packages produced by `vis sync package-json-fields` keep their full object form.
* **`sortExports`** reorders condition keys inside `exports` to the canonical sequence `types`, `node-addons`, `node`, `import`, `require`, `default`. Subpath keys (`./foo`) are preserved in their original order.

`vis sync package-json-fields` always writes the canonical object form so two packages can be compared without false positives. The `format-*` flags here are what render the shorthand on disk after sort.

## .editorconfig integration [#editorconfig-integration]

When `editorconfig: true` (the default), the sorter discovers the nearest `.editorconfig` for each `package.json` and uses its `indent_size` / `indent_style` / `end_of_line` values as defaults. Explicit `--indent` / `--line-ending` flags still win. Pass `--no-editorconfig` to ignore the file entirely.

## Options [#options]

| Option                   | Alias | Default | Description                                                                                                             |
| ------------------------ | ----- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--check`                | `-c`  | `false` | Check if `package.json` files are sorted without writing (exits 1 if unsorted)                                          |
| `--sort-scripts`         |       | `false` | Also sort the `scripts` field alphabetically                                                                            |
| `--indent`               |       |         | Indent override: a number of spaces, `tab`, or a literal whitespace string. When unset, the file's indent is preserved. |
| `--ignore`               |       |         | Glob pattern of files to skip (basename match, or path-relative when the pattern contains `/`). Repeatable.             |
| `--sort-order`           |       |         | Comma-separated list of top-level keys to place first. Repeatable.                                                      |
| `--unsorted`             |       |         | Comma-separated list of top-level sections whose key order should be preserved. Repeatable.                             |
| `--no-final-newline`     |       | `false` | Do not append a trailing newline (default: append one).                                                                 |
| `--line-ending`          |       | `auto`  | Line ending to write: `auto` (per-file detection), `lf`, or `crlf`.                                                     |
| `--no-format-bugs`       |       | `false` | Disable collapsing `bugs: { url }` to the bare string form.                                                             |
| `--no-format-repository` |       | `false` | Disable collapsing `repository: { type, url }` to the GitHub `owner/repo` shorthand.                                    |
| `--no-sort-exports`      |       | `false` | Disable canonical sorting of `exports` condition keys.                                                                  |
| `--no-editorconfig`      |       | `false` | Disable `.editorconfig` discovery for indent / line-ending defaults.                                                    |


# vis staged (/docs/packages/vis/commands/staged)



# vis staged [#vis-staged]

Run a `lint-staged`-style pipeline against the files in the git index. Configuration lives in `vis.config.ts` under the `staged` key — a map of glob patterns to tasks; this command applies it.

## Usage [#usage]

```bash
vis staged [options]
```

## Examples [#examples]

```bash
vis staged
vis staged --verbose
vis staged --no-stash
vis staged --diff HEAD~1     # run against a different diff base
```

## Task forms [#task-forms]

The `staged` config maps a glob pattern to a task. A task can be:

```ts
// vis.config.ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    staged: {
        // a command string — the matched files are appended to the argv
        "*.css": "stylelint --fix",

        // an array runs serially
        "*.ts": ["eslint --fix", "prettier --write"],

        // a function receives the matched paths and returns command(s)
        "*.md": (files) => `prettier --write ${files.join(" ")}`,

        // a named side-effect task — no argv construction
        "*.json": { title: "validate", task: (files) => validateAll(files) },

        // run once per owning workspace package, cwd = that package dir
        "packages/**/*.{ts,tsx}": { command: "eslint --fix", perPackage: true },

        // pin a command to a fixed directory (files passed as absolute paths)
        "schemas/*.json": { command: "pnpm run schema:check", cwd: "tools/schema" },
    },
});
```

### `perPackage` — run from each package directory [#perpackage--run-from-each-package-directory]

`{ command, perPackage: true }` groups the pattern's matched files by the workspace
package that owns them and runs the command **once per package**, with the working
directory set to that package's directory and file paths made relative to it.

Use it for tools that resolve their config or plugins from the nearest `package.json` —
for example an ESLint shareable config that picks its plugin set from the current
directory. Running such a tool from the workspace root would load the wrong plugins for
package files; `perPackage` runs it from each package so the right config applies.

Workspace packages are discovered from `pnpm-workspace.yaml` (falling back to
`package.json#workspaces`). Files that sit under no workspace package collapse into a
single run from the workspace root. When no workspace is defined, `perPackage` is a
no-op and the command runs once from the root.

### `cwd` — run from a fixed directory [#cwd--run-from-a-fixed-directory]

`{ command, cwd: "tools/schema" }` runs the command once from the given directory
(resolved relative to the workspace root, or absolute). Matched files are passed as
**absolute** paths so they resolve regardless of where the command runs. `cwd` is
ignored when `perPackage` is set — that derives the directory per package instead.

> Both `perPackage` and `cwd` also prepend the target directory's `node_modules/.bin`
> to `PATH`, so bare binary names resolve from the package's own dependencies.

## Options [#options]

| Option                    | Default | Description                                                         |
| ------------------------- | ------- | ------------------------------------------------------------------- |
| `--allow-empty`           | `false` | Allow empty commits when tasks revert all staged changes            |
| `--auto-stage`            | `false` | Automatically stage new files that tasks create during the run      |
| `--concurrent`            |         | Number of concurrent tasks (or `false` for serial)                  |
| `--continue-on-error`     | `false` | Run all tasks to completion even if one fails                       |
| `--cwd`                   |         | Working directory to run all tasks in                               |
| `--debug`                 | `false` | Enable debug output                                                 |
| `--diff`                  |         | Override the default `--staged` flag of `git diff`                  |
| `--diff-filter`           |         | Override the default diff-filter                                    |
| `--fail-on-changes`       | `false` | Fail with exit code 1 when tasks modify tracked files               |
| `--force-kill`            | `false` | Kill in-flight tasks with SIGKILL on fast-fail (default is SIGTERM) |
| `--hide-partially-staged` | `false` | Hide unstaged changes from partially staged files                   |
| `--hide-unstaged`         | `false` | Hide all unstaged changes before running tasks                      |
| `--quiet`                 | `false` | Suppress console output                                             |
| `--relative`              | `false` | Pass filepaths relative to cwd to tasks                             |
| `--revert`                | `false` | Revert to original state in case of errors                          |
| `--stash`                 | `true`  | Enable backup stash (`--no-stash` to disable)                       |
| `--verbose`               | `false` | Show task output even when tasks succeed                            |


# vis status (/docs/packages/vis/commands/status)



# vis status [#vis-status]

One-screen overview of the workspace: project counts, recent run results, cache health, security posture. Pair with `--json` for CI dashboards.

## Usage [#usage]

```bash
vis status [options]
```

## Examples [#examples]

```bash
vis status
vis status --json
```

## Options [#options]

| Option   | Default | Description      |
| -------- | ------- | ---------------- |
| `--json` | `false` | Emit JSON output |


# vis sync (/docs/packages/vis/commands/sync)



# vis sync [#vis-sync]

Generates workspace-wide artefacts that are derived from per-project configuration.

## Usage [#usage]

```bash
vis sync <kind> [options]
```

## Kinds [#kinds]

### codeowners [#codeowners]

Aggregates `owners` entries from every project's `project.json` into a single `CODEOWNERS` file.

```bash
vis sync codeowners                           # Write to <workspace>/CODEOWNERS
vis sync codeowners --out=.github/CODEOWNERS  # Custom output path
vis sync codeowners --check                   # Verify file is up to date (CI guard)
vis sync codeowners --write-guard             # Also emit Write Guard CI (GitHub + GitLab)
vis sync codeowners --write-guard --check     # CI: fail if Write Guard files drift
```

#### project.json owners [#projectjson-owners]

Each project declares its code owners:

```json
{
    "$schema": "https://unpkg.com/@visulima/vis/schemas/project.schema.json",
    "owners": [
        { "path": "src/**", "owners": ["@myorg/core-team"] },
        { "path": "docs/**", "owners": ["@myorg/docs-team"], "channel": "#docs-reviews" }
    ]
}
```

#### vis.config.ts codeowners block [#visconfigts-codeowners-block]

```typescript
export default defineConfig({
    codeowners: {
        orderBy: "project-id", // or "file-source" (default)
        provider: "github", // "github" | "gitlab" | "bitbucket" | "other"
        globalPaths: {
            "/.github/**": ["@myorg/platform"],
            "/pnpm-workspace.yaml": ["@myorg/infra"],
        },
    },
});
```

#### Write Guard (`--write-guard`) [#write-guard---write-guard]

`--write-guard` is opt-in. On top of generating `CODEOWNERS`, it emits CI for
projects flagged `restricted: true` in their `project.json`. Two artefacts are
written so the guard works on both forges, scoped to the restricted project
roots only — unrelated changes are never blocked.

> **The two forges enforce at different strengths — this is deliberate.** The
> GitHub workflow is a **hard gate**: it fails the PR check when a restricted
> path changed without code-owner approval. The GitLab job is a **soft guard**:
> GitLab CI cannot portably gate a merge on code-owner *approval* from a job, so
> it only verifies CODEOWNERS freshness. &#x2A;*Real enforcement on GitLab requires
> enabling the native protected-branch &#x2A;"Require approval from Code Owners"*
> setting (GitLab Premium / Ultimate)** — the generated `.gitlab` file says this
> loudly in both a header comment and its own job log so it can't be mistaken
> for a blocking check.

| Forge  | Output path                         | Strength       | Mechanism                                                                                                                                       |
| ------ | ----------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub | `.github/workflows/write-guard.yml` | **Hard gate**  | `pull_request` workflow gated on restricted paths, delegates to the `geritol/write-guard` action (fails the check without approval)             |
| GitLab | `.gitlab/write-guard.gitlab-ci.yml` | **Soft guard** | Includable MR-gated job; verifies CODEOWNERS is in sync + loudly flags the change. Needs the native CODEOWNERS-approval setting for a real gate |

Opt a project in via its `project.json`:

```json
{
    "$schema": "https://unpkg.com/@visulima/vis/schemas/project.schema.json",
    "restricted": true,
    "owners": [{ "path": "src/**", "owners": ["@myorg/security"] }]
}
```

`include` the GitLab file from your root `.gitlab-ci.yml` **and*&#x2A; enable the
native protected-branch &#x2A;"Require approval from Code Owners"* setting — the CI
job alone is advisory until you do. With `--write-guard --check`, CI exits
non-zero if either generated file drifts from what the current `restricted` set
would produce — a clean `CODEOWNERS` does **not** reset that failure. When no
project is flagged `restricted: true`, the flag no-ops with an informational
message.

Upstream references: the GitHub workflow delegates to the
[`geritol/write-guard`](https://github.com/marketplace/actions/write-guard)
action; both forges build on native CODEOWNERS approval —
[GitHub CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
and [GitLab Code Owners](https://docs.gitlab.com/ee/user/project/codeowners/).

```mermaid
flowchart TD
    A["vis sync codeowners --write-guard"] --> B["Scan every project.json"]
    B --> C{"restricted: true?"}
    C -- none --> Z["Info: nothing restricted, skip"]
    C -- "1+ projects" --> D["Resolve + dedupe project-root globs"]
    D --> E["Render GitHub workflow"]
    D --> F["Render GitLab CI job"]
    E --> G{"--check?"}
    F --> G
    G -- no --> H["Write .github + .gitlab artefacts"]
    G -- yes --> I{"On-disk content == rendered?"}
    I -- yes --> J["Info: Write Guard up to date"]
    I -- no --> K["Error + exitCode=1\n(not reset by clean CODEOWNERS)"]
```

### package-json-fields [#package-json-fields]

Mirrors a small set of metadata fields from the **root** `package.json` to every workspace package, so each package keeps a consistent `license`, `author`, `bugs`, `homepage`, `engines`, and `repository`. `repository.directory` is preserved per package — only `type` and `url` are copied from root.

```bash
vis sync package-json-fields                            # Mirror defaults from root → every package
vis sync package-json-fields --check                    # CI: exit 1 if any package is out of sync
vis sync package-json-fields --fields license,engines   # Override the field list for this run
vis sync package-json-fields --ignore-package-name '@scope/internal-*'
vis sync package-json-fields --format=json              # Machine-readable diff
vis sync package-json-fields --quiet                    # Only print the summary line
```

#### Default fields [#default-fields]

`author`, `bugs`, `homepage`, `license`, `repository`, `engines`.

For `repository`, root's `type` and `url` overwrite the package's, but the package's `directory` (its subpath inside the monorepo) is kept. For every other field the root value is copied verbatim.

Fields missing from root are skipped — sync never deletes from a package. Fields already deep-equal to root are skipped — no mtime churn.

## Options [#options]

| Option                   | Default                  | Description                                                                                                                |
| ------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `--out`                  | `<workspace>/CODEOWNERS` | Output file path (codeowners only)                                                                                         |
| `--check`                | `false`                  | Exit non-zero if drift is found (no writes)                                                                                |
| `--from`                 | `project-json`           | Input sources for codeowners (comma-separated/repeatable): `project-json`, `nested-codeowners`, `package-json-maintainers` |
| `--nested-includes`      | `**/CODEOWNERS`          | Glob (repeatable) used to discover nested CODEOWNERS files (codeowners only)                                               |
| `--regeneration-command` |                          | Header instruction shown to reviewers, replacing the default note (codeowners only)                                        |
| `--preserve-block`       | `false`                  | Splice the generated block between markers in an existing file instead of overwriting (codeowners only)                    |
| `--write-guard`          | `false`                  | Also emit GitHub + GitLab Write Guard CI for `restricted: true` projects (codeowners only)                                 |
| `--fields`               |                          | Comma-separated field list to mirror (package-json-fields only). Repeatable.                                               |
| `--ignore-package-name`  |                          | Glob of package names to skip (package-json-fields only). Repeatable.                                                      |
| `--format`               | `human`                  | Output format for package-json-fields: `human` or `json`.                                                                  |
| `--quiet`                | `false`                  | Suppress per-package log lines; print only the summary (package-json-fields only).                                         |


# vis task-why (/docs/packages/vis/commands/task-why)



# vis task-why [#vis-task-why]

Trace a task back to whatever requested it. Useful when a `vis run` execution graph contains an unexpected task and you need to know which `dependsOn` / `^build` / target-default rule pulled it in.

## Usage [#usage]

```bash
vis task-why <taskId>
```

## Examples [#examples]

```bash
vis task-why @myorg/app:build
vis task-why lib-a:test
```

## Options [#options]

This command takes no flags — output is a textual chain from the requested task to its root cause.


# vis toolchain (/docs/packages/vis/commands/toolchain)



# vis toolchain [#vis-toolchain]

Inspects the repository's tool pins (`engines.node`, `.nvmrc`, `.node-version`, `packageManager`, `.prototools`, `.mise.toml`, `.tool-versions`, `volta` field) and delegates to whichever version managers the developer already has installed. Resolution is **per-tool**, not per-workspace: fnm handles Node, corepack handles npm, pnpm and yarn self-activate from the `packageManager` field — one pin at a time, best manager wins.

Unlike [vite+](https://viteplus.dev/guide/env), which ships its own managed Node.js runtime under `~/.vite-plus`, vis does not try to be a version manager. It keeps the binary small and fits into whatever ecosystem (proto, mise, fnm, volta, asdf, nvm, corepack) you already use.

## Usage [#usage]

```bash
vis toolchain <subcommand> [options]
```

## Subcommands [#subcommands]

| Subcommand                       | Purpose                                                                                                                |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `vis toolchain status`           | Show every detected manager plus expected-vs-actual versions. Each tool lists the manager vis would use to install it. |
| `vis toolchain detect`           | Print the primary manager's name (useful for shell scripts).                                                           |
| `vis toolchain install`          | Install pinned versions. Groups tools by manager and invokes each one appropriately.                                   |
| `vis toolchain use <tool>@<ver>` | Pin a tool version through the best manager for that specific tool.                                                    |
| `vis toolchain which <tool>`     | Resolve the binary path the manager would launch. Falls back to `PATH`.                                                |

## Examples [#examples]

```bash
# Read every pin and report drift
vis toolchain status

# Install everything — per-tool delegation
vis toolchain install

# Pin node 22.13.0 via the best runtime manager (fnm/volta/proto/...)
vis toolchain use node@22.13.0

# Pin pnpm via the packageManager field — pnpm 10+ self-activates
vis toolchain use pnpm@10.32.1

# Where would `node` actually run from?
vis toolchain which node

# Name of the primary manager — pipe-friendly
vis toolchain detect       # prints "proto" / "mise" / "fnm" / ... / "none"
```

## Options [#options]

| Option         | Subcommand(s)    | Description                                                                                                          |
| -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--json`       | `status`         | Emit a machine-readable JSON payload instead of the formatted status report.                                         |
| `--exit-code`  | `status`         | Exit with code 1 when any tool mismatches. Useful in CI preflight jobs.                                              |
| `--dry-run`    | `install`, `use` | Print the command that would run but don't execute it.                                                               |
| `--no-engines` | `use`            | Skip mirroring the pinned version into `engines.<tool>`. By default `use` updates that field when it already exists. |

## How detection works [#how-detection-works]

1. Walk `PATH` for `proto`, `mise`, `fnm`, `volta`, `asdf`, `corepack`. `nvm` is a shell function, so vis treats `$NVM_DIR` as the install marker.
2. Check for workspace-local config files: `.prototools`, `.mise.toml`, `.tool-versions`, `.nvmrc` / `.node-version`, a `volta` field in `package.json`, or a `packageManager` field in `package.json` (corepack).
3. Record every manager found (installed or referenced) in `status.detected`.
4. For each tool pin, `resolveManagerFor(spec)` walks a **source-aware preference list** and picks the first installed manager that can handle that specific tool.

## Per-tool resolution [#per-tool-resolution]

vis picks a manager **per tool**, not per workspace. Preference depends on where the pin came from:

| Pin source                 | Preference order                               |
| -------------------------- | ---------------------------------------------- |
| `.prototools`              | proto                                          |
| `.mise.toml`               | mise                                           |
| `.tool-versions`           | asdf, mise (mise reads asdf format)            |
| `.nvmrc` / `.node-version` | fnm, nvm, volta, proto, mise, asdf (node only) |
| `volta` field              | volta                                          |
| `packageManager` — pnpm    | self-activate, volta, proto, mise, corepack    |
| `packageManager` — yarn    | self-activate, volta, proto, mise, corepack    |
| `packageManager` — npm     | volta, proto, mise, asdf, corepack             |
| `packageManager` — bun     | proto, mise, asdf                              |
| `engines.*` / `vis.config` | proto, mise, fnm, volta, asdf, nvm, corepack   |

The first installed + capable manager wins. If nothing is installed, vis names the first capable manager as a "suggested install." `self-activate` is a pseudo-manager that means *the pnpm/yarn binary itself will switch versions from the `packageManager` field on next invocation* — no external manager required.

## Tool pin priority (when the same tool is pinned in multiple places) [#tool-pin-priority-when-the-same-tool-is-pinned-in-multiple-places]

**Later entries override earlier ones** — read top-to-bottom, the bottom wins. `toolchain.tools` in `vis.config.ts` overrides `.prototools`, which overrides `.mise.toml`, and so on down to `engines.*`.

1. `engines.*` in `package.json`
2. `packageManager` in `package.json`
3. `volta.<tool>` in `package.json`
4. `.nvmrc` / `.node-version`
5. `.tool-versions`
6. `.mise.toml` (`[tools]`)
7. `.prototools`
8. `toolchain.tools` in `vis.config.ts`

That matches what each manager reads at runtime — so `vis toolchain status` ends up reporting the same version the manager itself resolves.

## Configuration [#configuration]

```typescript
// vis.config.ts
import { defineConfig } from "@visulima/vis";

export default defineConfig({
    toolchain: {
        // Explicit override. Does NOT include "self-activate" — that's
        // resolved automatically for pnpm/yarn packageManager pins.
        preferredManager: "proto",

        // Overrides engines/packageManager-derived pins.
        tools: {
            node: ">=22.13",
            pnpm: "10.32.1",
        },
    },
});
```

## Manager compatibility [#manager-compatibility]

| Manager       | Handles                                          | `install` command                               | `use` command                                  | Config file touched                   |
| ------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------- | ------------------------------------- |
| proto         | node, bun, deno, go, python, ruby, rust, all PMs | `proto install`                                 | `proto pin <tool> <ver>`                       | `.prototools`                         |
| mise          | everything                                       | `mise install`                                  | `mise use -- <tool>@<ver>`                     | `.mise.toml`                          |
| fnm           | node only                                        | `fnm install [<ver>]`                           | `fnm use <ver>` (Node only)                    | `.nvmrc` / `.node-version`            |
| volta         | node, npm, pnpm, yarn                            | `volta install <tool>@<ver>`                    | `volta pin <tool>@<ver>`                       | `package.json` (`volta.<tool>` field) |
| asdf          | node, bun, deno, go, python, ruby, rust          | `asdf install`                                  | `asdf local <tool> <ver>`                      | `.tool-versions`                      |
| nvm           | node only                                        | (manual — shell function, run `nvm install`)    | writes `.nvmrc`, then prompts to run `nvm use` | `.nvmrc`                              |
| corepack      | npm, pnpm, yarn                                  | `corepack prepare <tool>@<ver> --activate`      | `corepack use <tool>@<ver>`                    | `package.json` (`packageManager`)     |
| self-activate | pnpm 10+, yarn berry                             | (no-op — runs on next `pnpm`/`yarn` invocation) | edit `packageManager` field                    | `package.json` (`packageManager`)     |

For most managers vis shells out to the manager itself (`proto pin`, `volta pin`, `mise use`, etc.) so the change integrates with shell hooks and caches the way each manager expects. The exceptions are **nvm** (a shell function — vis writes `.nvmrc` directly and prompts you to run `nvm use`) and **self-activate** (vis writes the `packageManager` field directly so pnpm/yarn pick it up on next invocation).

## A note on corepack [#a-note-on-corepack]

Corepack [is no longer shipped with Node.js 25+](https://socket.dev/blog/node-js-tsc-votes-to-stop-distributing-corepack). Users who need it must install it explicitly via `npm install -g corepack`. vis detects corepack on `PATH` like any other manager.

Most teams using `packageManager: "pnpm@X"` don't need corepack at all — **pnpm 10+ and yarn berry read the field natively and self-switch** on the next invocation. vis models this as the `self-activate` pseudo-manager, which is the default pick for pnpm/yarn pins and is always a no-op install.

Corepack remains useful for **npm version pinning** (npm itself doesn't self-switch) and in containers where pnpm/yarn aren't pre-installed.

## Cold start — no Node, no manager [#cold-start--no-node-no-manager]

`vis` is a Node CLI, so a truly empty machine can't run it until something installs Node. Two bootstrap scripts cover the cold-start flow.

### Linux & macOS (and WSL) [#linux--macos-and-wsl]

```bash
curl -fsSL https://visulima.com/install.sh | bash
```

The script:

1. Checks whether `node` is on PATH.
2. If not, installs **the latest Node LTS directly by default** — the OS package manager (Homebrew / apt / dnf-yum NodeSource) when it can provide it, otherwise the official, SHA256-verified nodejs.org tarball into `~/.vis/node`. A version manager (`proto`, `fnm`, `mise`, or `volta`) is offered as an opt-in alternative, not forced.
3. Installs `@visulima/vis` globally via pnpm (if present) or npm.
4. If the current directory has workspace pin files (`.nvmrc`, `.prototools`, etc.), runs `vis toolchain install` to match them.

> **Note on piping.** When you run `curl … | bash`, stdin isn't a TTY and the
> interactive picker is skipped — the script installs **the latest Node LTS directly**.
> Pass `--manager=proto|fnm|mise|volta` (or set `VIS_MANAGER`) to take the
> version-manager path instead, or `VIS_NODE_MAJOR` to install a different
> Node major.

### Windows (PowerShell 5.1+) [#windows-powershell-51]

```powershell
irm https://visulima.com/install.ps1 | iex
```

Same flow as the POSIX script. By default it installs **the latest Node LTS directly** via winget / Chocolatey / scoop, falling back to the official, SHA256-verified nodejs.org zip into `%USERPROFILE%\.vis\node`. The opt-in version managers use Windows-native installers:

* `proto` via `irm https://moonrepo.dev/install/proto.ps1 | iex` (vendor PowerShell installer)
* `fnm` via `winget install Schniz.fnm` (or `scoop install fnm`)
* `volta` via `winget install Volta.Volta` (or `scoop install volta`)

`mise` and the Unix `nvm` are not supported on native Windows — use WSL with `install.sh` for those.

### Passing arguments [#passing-arguments]

The pipe-into-shell form doesn't pass arguments. Use the scriptblock form to pass flags:

```bash
# bash
curl -fsSL <url>/install.sh | bash -s -- --yes --manager=proto --no-toolchain-install
```

```powershell
# PowerShell
& ([scriptblock]::Create((irm '<url>/install.ps1'))) -Yes -Manager proto -NoToolchainInstall
```

### Docker / CI examples [#docker--ci-examples]

```dockerfile
# Linux / macOS images
RUN curl -fsSL https://visulima.com/install.sh \
    | bash -s -- --yes --manager=proto --no-toolchain-install
```

```dockerfile
# Windows images (PowerShell)
RUN powershell -Command "& ([scriptblock]::Create((irm 'https://visulima.com/install.ps1'))) -Yes -Manager proto -NoToolchainInstall"
```

### Already have Node? [#already-have-node]

If Node is on PATH both scripts skip the manager install step and go straight to `npm install -g @visulima/vis`. In that case you can also just run that command directly — the install scripts are a convenience, not a requirement.

### Verifying the script before piping it into your shell [#verifying-the-script-before-piping-it-into-your-shell]

Each script has a SHA256 sidecar at `<script>.sha256`. To verify before executing:

```bash
curl -fsSL https://visulima.com/install.sh -o install.sh
curl -fsSL https://visulima.com/install.sh.sha256 | sha256sum -c -
# install.sh: OK
bash install.sh
```

```powershell
# Windows
$body = irm https://visulima.com/install.ps1
$expected = (irm https://visulima.com/install.ps1.sha256).Split(" ")[0]
$actual = (Get-FileHash -Algorithm SHA256 -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($body)))).Hash.ToLower()
if ($actual -ne $expected) { throw "SHA256 mismatch" }
$body | iex
```

The script body has a `# vis-install <version>` banner near the top, so once you've run it you can confirm which release you got. The banner is intentionally content-stable across rebuilds (no per-build timestamp) so the SHA256 only changes when the script body or vis version actually changes.

### Pinning to a specific version of the install script [#pinning-to-a-specific-version-of-the-install-script]

Versioned aliases let tutorials pin to a major version so a breaking flag rename in v2 doesn't silently break copy-paste:

```bash
# Pinned — body matches /install.sh today, won't follow breaking v2 changes.
curl -fsSL https://visulima.com/install/v1.sh | bash
```

```powershell
irm https://visulima.com/install/v1.ps1 | iex
```

The non-versioned URLs (`https://visulima.com/install.sh` and `…/install.ps1`) are the rolling latest.

## CI / CD recipes [#ci--cd-recipes]

`vis ci` calls `ensureToolchain()` automatically as its first step, so the simplest CI is:

### GitHub Actions [#github-actions]

```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
    ci:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - name: Bootstrap vis (installs proto + Node from .prototools / engines.node)
              run: curl -fsSL https://visulima.com/install/v1.sh | bash -s -- --yes --manager=proto
            - name: Lint, test, build (affected)
              run: vis ci lint,test,build
```

### GitLab CI [#gitlab-ci]

```yaml
# .gitlab-ci.yml
ci:
    image: ubuntu:22.04
    before_script:
        - apt-get update && apt-get install -y curl bash
        - curl -fsSL https://visulima.com/install/v1.sh | bash -s -- --yes --manager=proto
    script:
        - vis ci lint,test,build
```

### Skipping the toolchain pre-flight [#skipping-the-toolchain-pre-flight]

When the CI image already has the right Node version baked in (and you trust that), pass `--skip-toolchain` to short-circuit the pre-flight:

```bash
vis ci lint,test,build --skip-toolchain
```

Or set `toolchain.autoInstall: false` in `vis.config.ts` for a workspace-wide opt-out.

## Migrating from another version manager [#migrating-from-another-version-manager]

| Coming from  | What changes                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Volta**    | Nothing immediate — vis reads your existing `volta` field in package.json and routes pnpm/yarn/npm/node pins to `volta install`. New pins from `vis toolchain use` write to the same field.                                                                                                                                                                                                                  |
| **nvm**      | Keep your `.nvmrc`. `vis toolchain status` reads it; `vis toolchain use node@22.13.0` rewrites it. nvm-the-shell-function still owns activation (run `nvm use` to switch the shell).                                                                                                                                                                                                                         |
| **fnm**      | Keep your `.nvmrc` / `.node-version`. fnm continues to handle Node; vis runs `fnm use <ver>` to switch the current shell but does **not** persist the change to `.nvmrc`. If you also want vis to write `.nvmrc` on `vis toolchain use node@<ver>`, set `toolchain.preferredManager: "nvm"` in `vis.config.ts` (and ensure nvm is installed) — vis will then write `.nvmrc` and prompt you to run `nvm use`. |
| **proto**    | Native fit. `.prototools` is the source of truth, `vis toolchain install` runs `proto install`, `vis toolchain use <tool>@<ver>` runs `proto pin`.                                                                                                                                                                                                                                                           |
| **mise**     | Same as proto — `.mise.toml` is the config, vis maps `install` and `use` to `mise install` / `mise use`.                                                                                                                                                                                                                                                                                                     |
| **asdf**     | `.tool-versions` is the config. vis maps to `asdf install` / `asdf local <tool> <ver>`.                                                                                                                                                                                                                                                                                                                      |
| **corepack** | If you only used corepack to pin pnpm/yarn via the `packageManager` field, you can drop corepack on most projects: pnpm 10+ and yarn berry **self-activate** from that field on next invocation. vis surfaces this as the `self-activate` pseudo-manager. corepack is still needed when you want to pin **npm** itself (which doesn't self-switch).                                                          |

You don't have to migrate anything: vis runs alongside whatever manager you have. The benefits of explicit migration are smaller config drift and the ability to use `vis toolchain use` to update pins from the CLI.

## Why not embed a runtime manager? [#why-not-embed-a-runtime-manager]

Most developers already have `fnm`, `volta`, `mise`, or `proto` installed. Shipping another \~20 MB binary would violate the principle of least surprise and duplicate behaviour the OS-level manager already handles (PATH shims, global caches, shell activation). Delegation keeps vis small and portable.

When no manager is installed, `vis toolchain status` still reports the pinned versions and their sources — the same information `vis doctor` surfaces — plus names a manager that *could* install each tool, so the user can install it and re-run.

## Related [#related]

* [`vis doctor`](/docs/packages/vis/commands/doctor) — broader health check; surfaces `engines.node` mismatches but does not install anything.
* [`vis ci`](/docs/packages/vis/commands/ci) — runs `install + affected` in one step; picks up toolchain pins automatically when `autoInstall` is on.


# vis unlink (/docs/packages/vis/commands/unlink)



# vis unlink [#vis-unlink]

Reverse a previous [`vis link`](/docs/packages/vis/commands/link). With no argument, unregisters the current package's global symlink. With package names, removes those packages' symlinks from the current project.

## Usage [#usage]

```bash
vis unlink [packages...] [options]
```

## Examples [#examples]

```bash
vis unlink
vis unlink react
vis unlink -r           # unlink in every workspace package
```

## Options [#options]

| Option        | Alias | Default | Description                      |
| ------------- | ----- | ------- | -------------------------------- |
| `--recursive` | `-r`  | `false` | Unlink in all workspace packages |

## Deno [#deno]

Deno has no `unlink` equivalent — vis falls back to `deno remove` for the named packages and emits a warning. To undo an import-map override, edit `deno.json` directly.


# vis update (/docs/packages/vis/commands/update)



# vis update [#vis-update]

Update packages to their latest versions. Automatically uses **catalog mode** for pnpm/bun workspaces with catalogs, or wraps the native package manager otherwise.

**Alias:** `vis up`

## Usage [#usage]

```bash
vis update [packages] [options]
```

## Examples [#examples]

```bash
vis update react                    # Update react within semver range
vis up react -L                     # Update react to latest
vis update -i                       # Interactive mode
vis update --filter app             # Update in specific workspace
vis update -r                       # Update in all workspaces
vis update --target minor           # Only apply minor/patch updates (catalog)
vis update --dry-run                # Preview changes without applying
vis update --exclude '@types/*'     # Exclude packages by pattern
vis update --changelog              # Show changelog links after updating
vis update --rollback               # Restore catalog from last backup
```

## Options [#options]

| Option                         | Alias | Default  | Description                                                                                                                                                                                                                    |
| ------------------------------ | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--latest`                     | `-L`  | `false`  | Update to latest version (ignore semver range)                                                                                                                                                                                 |
| `--target`                     | `-t`  | `latest` | Update target: `latest`, `minor`, or `patch` (catalog)                                                                                                                                                                         |
| `--dry-run`                    | `-d`  | `false`  | Preview changes without applying                                                                                                                                                                                               |
| `--global`                     | `-g`  | `false`  | Update global packages                                                                                                                                                                                                         |
| `--recursive`                  | `-r`  | `false`  | Update recursively in all workspace packages                                                                                                                                                                                   |
| `--filter`                     |       |          | Filter packages in monorepo                                                                                                                                                                                                    |
| `--workspace-root`             | `-w`  | `false`  | Include workspace root                                                                                                                                                                                                         |
| `--dev`                        | `-D`  | `false`  | Update only devDependencies                                                                                                                                                                                                    |
| `--prod`                       | `-P`  | `false`  | Update only dependencies                                                                                                                                                                                                       |
| `--peer`                       |       | `false`  | Include `peerDependencies` in update checks                                                                                                                                                                                    |
| `--include-internal`           |       | `false`  | Also check workspace-owned package names against the registry (catalog mode)                                                                                                                                                   |
| `--interactive`                | `-i`  | `false`  | Interactive mode                                                                                                                                                                                                               |
| `--no-optional`                |       | `false`  | Don't update optionalDependencies                                                                                                                                                                                              |
| `--include-locked`             | `-l`  | `false`  | Include packages with pinned/exact versions (no `^` or `~` prefix)                                                                                                                                                             |
| `--no-save`                    |       | `false`  | Update lockfile only                                                                                                                                                                                                           |
| `--include`                    |       |          | Glob pattern to include packages (repeatable, catalog)                                                                                                                                                                         |
| `--exclude`                    |       |          | Glob pattern to exclude packages (repeatable, catalog)                                                                                                                                                                         |
| `--prerelease`                 |       | `false`  | Include prerelease versions (catalog)                                                                                                                                                                                          |
| `--security` / `--no-security` |       | `true`   | Check for known security vulnerabilities (OSV.dev); `--no-security` to skip                                                                                                                                                    |
| `--no-catalog`                 |       | `false`  | Skip catalog mode, use package manager directly                                                                                                                                                                                |
| `--format`                     |       | `table`  | Output format: `table`, `json`, or `minimal`                                                                                                                                                                                   |
| `--changelog`                  |       | `false`  | Show changelog URLs for updated packages                                                                                                                                                                                       |
| `--install`                    |       | `true`   | Run install after catalog update (`--no-install` to skip)                                                                                                                                                                      |
| `--rollback`                   |       | `false`  | Restore catalog file from the last backup                                                                                                                                                                                      |
| `--no-typosquat-check`         |       | `false`  | Skip typosquat name check for package arguments                                                                                                                                                                                |
| `--no-marshall-check`          |       | `false`  | Skip the offline marshall pipeline when explicit package arguments are supplied (author, provenance, s1ngularity, metadata, downloads, expired-domains, new-bin, archived-repo). Blanket `vis update` never runs the pipeline. |
| `--max-concurrent-requests`    |       | `8`      | Cap concurrent registry requests during outdated checks (catalog)                                                                                                                                                              |
| `--release-channel`            |       | `stable` | Channel filter: `stable`, `same` (match current's prerelease channel), or `any`                                                                                                                                                |
| `--no-actions`                 |       | `false`  | Skip the GitHub Actions ecosystem scan                                                                                                                                                                                         |
| `--no-docker`                  |       | `false`  | Skip the Docker ecosystem scan (Dockerfile + docker-compose)                                                                                                                                                                   |
| `--no-gitlab`                  |       | `false`  | Skip the GitLab CI ecosystem scan (.gitlab-ci.yml + .gitlab/ci/\*\*)                                                                                                                                                           |
| `--include-branches`           |       | `false`  | Include branch references (e.g. `actions/checkout@main`) when scanning workflows                                                                                                                                               |
| `--style`                      |       | `sha`    | Reference style for GitHub Actions: `sha` pins to commit SHA + version comment, `preserve` keeps the existing style                                                                                                            |
| `--actions-token`              |       |          | GitHub token override (falls back to `GITHUB_TOKEN` / `GH_TOKEN`)                                                                                                                                                              |
| `--gitlab-token`               |       |          | GitLab token override (falls back to `GITLAB_TOKEN` / `CI_JOB_TOKEN`)                                                                                                                                                          |
| `--ai`                         |       | `false`  | Run AI analysis on outdated packages before updating (catalog mode)                                                                                                                                                            |
| `--ai-type`                    |       | `impact` | AI analysis type: `impact`, `security`, `compatibility`, or `recommend`                                                                                                                                                        |
| `--yes`                        | `-y`  | `false`  | Skip the confirmation prompt for blanket `--latest` updates. Required in non-TTY contexts (CI) when running `vis update --latest` without explicit package arguments                                                           |

## How It Works [#how-it-works]

```mermaid
flowchart TD
    A["vis update [packages]"] --> B{Explicit packages\nprovided?}
    B -- yes --> C{Typosquat check\nenabled?}
    B -- no --> F
    C -- no --> F
    C -- yes --> D["Check names against\nblocklist & heuristics"]
    D --> E{Typosquat\ndetected?}
    E -- no --> F{Rollback\nrequested?}
    E -- yes --> P["Show warning:\n'Did you mean X?'"]
    P --> Q{User choice}
    Q -- "S (suggested)" --> R["Replace with\ncorrect name"]
    R --> F
    Q -- "y (keep)" --> F
    Q -- "N (abort)" --> Z["Exit with code 1"]
    F -- yes --> G["Restore from backup"]
    F -- no --> H{Catalogs\ndetected?}
    H -- yes --> I["Catalog mode:\nread catalogs, check\nnpm registry"]
    H -- no --> J["PM wrapper mode:\ndelegate to native\nupdate command"]
    I --> K{Interactive\nTTY?}
    K -- yes --> L["Interactive TUI\nwith selection"]
    K -- no --> M["Static output\n(table/json/minimal)"]
    L --> N["Apply selected\nupdates + backup"]
    M --> N
    J --> O["Done"]
    N --> O
```

## Catalog Mode vs Package Manager Mode [#catalog-mode-vs-package-manager-mode]

### Catalog Mode (pnpm/bun) [#catalog-mode-pnpmbun]

When catalogs are detected in `pnpm-workspace.yaml` or `package.json`, vis directly updates the catalog entries. This mode:

* Reads catalog definitions from the workspace config
* Checks the npm registry for newer versions
* Updates the catalog file in place
* Creates a backup before modifying
* Optionally runs `pnpm install` or `bun install` after updating

### Package Manager Mode [#package-manager-mode]

When catalogs are not available (or `--no-catalog` is used), vis wraps the native package manager's update command. Supported package managers:

* **pnpm** — Full feature support
* **npm** — Basic support
* **yarn v1** — Limited support
* **yarn berry** — Full support
* **bun** — Partial support
* **deno** — Maps to `deno outdated --update`. `--latest` and `--interactive` flow through; `--filter`, `--dev` / `--prod`, `--no-optional`, and `--no-save` are not supported and emit warnings (deno's update model is governed by `deno.json`)

## Backup and Rollback [#backup-and-rollback]

Every catalog update automatically creates a backup. To restore:

```bash
vis update --rollback
```

The backup is stored alongside the catalog file (e.g., `pnpm-workspace.yaml.backup`).

## Configuration [#configuration]

These settings can be defined in `vis.config.ts` under the `update` key:

```typescript
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    update: {
        target: "minor",
        exclude: ["@types/*"],
        includeLocked: false,
        packageMode: {
            typescript: "minor",
            "/^@vue/": "patch",
        },
        depFields: ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies", "overrides"],
    },
});
```

### `includeLocked` [#includelocked]

By default, packages with pinned/exact versions (no `^` or `~` prefix, e.g., `"react": "18.2.0"`) are skipped during update checks. Set `includeLocked: true` or pass `--include-locked` to opt them in.

### `packageMode` [#packagemode]

Per-package or per-pattern update target overrides. Keys can be:

* **Exact names**: `"typescript"` — matches only that package
* **Glob patterns**: `"@types/*"` — matches any `@types/` package
* **Regex patterns**: `"/^@vue/"` — wrapped in `/`, uses regex matching

## Non-npm ecosystem updates [#non-npm-ecosystem-updates]

In addition to npm/pnpm/bun catalogs, `vis update` auto-detects and **previews** updates to non-npm references. The preview always runs; **applying the changes requires explicit opt-in** so a plain `vis update` can never silently rewrite CI files:

* `--yes` applies the previewed ecosystem updates in one shot.
* `--interactive` plus an explicit catalog selection step opts you in.
* A `--dry-run` invocation, a failed PM install, or a TUI cancellation will leave CI files untouched even when updates were available.

### GitHub Actions [#github-actions]

Scans `.github/workflows/*.yml`, `.github/actions/*/action.yml`, and root `action.yml`. For every `uses:` reference it:

* Lists tags via the GitHub REST API (`/repos/{owner}/{repo}/tags`)
* Default-pins to the commit SHA with a `# vN.M.P` version-hint comment for readability
* Preserves the original YAML quote style (`uses: 'actions/checkout@v3'` round-trips quoted)
* Supports `--style preserve` to keep the existing tag-style reference
* Skips branch refs (`@main`, `@master`) unless `--include-branches` is passed
* Refuses to bump SHA pins lacking a `# vN.M.P` version-hint comment under `--target=minor|patch` (no current version → no constrained bump)
* Honours inline ignore directives: `# actions-up-ignore`, `# actions-up-ignore-next-line` (both on a line by themselves AND inline on the same `uses:` line), and block `# actions-up-ignore-start` / `# actions-up-ignore-end`
* Dedupes per `owner/repo` so a workflow with N references to the same action costs one API round-trip

Set `GITHUB_TOKEN` (or pass `--actions-token`) to raise the rate limit from 60 to 5000 requests/hour.

### Docker [#docker]

Scans every Dockerfile (any name matching `Dockerfile*` / `*.dockerfile`) and compose file (`docker-compose*.yml`, `compose*.yml`). For each `FROM` line and `image:` field it:

* Resolves tags from Docker Hub (`docker.io`), GHCR (`ghcr.io`), and any v2-compatible registry
* Handles registry bearer-token challenges automatically
* Handles BuildKit `FROM --platform=… node:18` flag lines correctly (multi-arch Dockerfiles work)
* Skips `latest`, `nightly`, and other non-semver tags unless `--include-branches` is passed
* Honours `# vis-update-ignore` and `# vis-update-ignore-next-line` directives (inline AND on a line by themselves)
* Refuses to update digest-pinned images (`image:tag@sha256:…`) — the supply-chain pin would be silently lost; refresh the digest manually instead

### GitLab CI [#gitlab-ci]

Scans `.gitlab-ci.yml` and any `*.yml` / `*.yaml` under `.gitlab/ci/`. Updates:

* `image:` and `services:` entries (resolved via Docker registries, same path as Docker scanning)
* `include: { project, ref }` blocks (resolved via the GitLab v4 REST API on `gitlab.com` or the host extracted from the project path for self-hosted instances)
* `include: { component: <host>/<group>/<project>@<ref> }` blocks

Set `GITLAB_TOKEN` or `CI_JOB_TOKEN` (or pass `--gitlab-token`) for private GitLab instances.

### Dependabot / Renovate integration [#dependabot--renovate-integration]

The ecosystem scan respects ignore lists declared in `.github/dependabot.yml` and `renovate.json` so you don't have to duplicate them. Specifically:

* Dependabot `ignore.dependency-name` entries (per `package-ecosystem`)
* Renovate top-level `ignoreDeps`
* Renovate per-manager `ignoreDeps` (`github-actions`, `dockerfile`, `docker-compose`, `gitlabci`, `gitlabci-include`)
* Renovate `packageRules` entries with `enabled: false`

The npm/catalog path is unchanged — Dependabot/Renovate npm ignore rules continue to be governed by your catalog config.

### Disabling ecosystem updates [#disabling-ecosystem-updates]

Pass `--no-actions`, `--no-docker`, or `--no-gitlab` to opt out of a single ecosystem. Passing explicit package arguments (`vis update lodash`) targets the npm path only and skips the ecosystem scan entirely.

Values are `"latest"`, `"minor"`, or `"patch"`. Unmatched packages use the global `target`.

### `depFields` [#depfields]

Controls which dependency fields are scanned for outdated packages. Beyond the standard fields (`dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`), you can include:

* `"overrides"` — npm overrides
* `"resolutions"` — yarn resolutions
* `"pnpm.overrides"` — pnpm overrides (nested field)

Values that reference other dependencies (e.g., `"$react"` in npm overrides) are automatically skipped.

### Maturity Period [#maturity-period]

The `update.minimumReleaseAge` setting (in minutes) filters out versions published too recently, so you don't adopt packages that might be yanked or found malicious shortly after publishing.

This is separate from `security.policies.firstSeen.minutes` (which applies at install time). The update setting is **not enabled by default** — all published versions are eligible for updates unless you opt in.

```typescript
export default defineConfig({
    update: {
        minimumReleaseAge: 1440, // 24 hours
        minimumReleaseAgeExclude: ["webpack", "@myorg/*"],
    },
});
```

If `minimumReleaseAge` is also configured in your package manager's native config (`pnpm-workspace.yaml` or `package.json`), vis will warn when the values are out of sync.


# vis self-update (/docs/packages/vis/commands/upgrade)



# vis self-update [#vis-self-update]

Self-update the `vis` binary. With no argument, installs the latest published version; pass an explicit version (`vis self-update 2.0.0`) to pin. Use `--check` to print the available upgrade without applying it.

> The command name registered with the CLI is `self-update` — `upgrade` is the source-tree directory name only.

## Usage [#usage]

```bash
vis self-update [version] [options]
```

## Examples [#examples]

```bash
vis self-update
vis self-update 2.0.0
vis self-update --check
vis self-update --force
```

## Options [#options]

| Option     | Default | Description                          |
| ---------- | ------- | ------------------------------------ |
| `--check`  | `false` | Check for updates without installing |
| `--force`  | `false` | Reinstall even if already current    |
| `--silent` | `false` | Suppress output (CI mode)            |


# vis why (/docs/packages/vis/commands/why)



# vis why [#vis-why]

Walk the dependency graph backwards to explain how a package ended up in `node_modules`. Aliased as `vis explain` for npm-compatibility.

## Usage [#usage]

```bash
vis why <packages...> [options]
```

## Examples [#examples]

```bash
vis why react
vis why react --json
vis why react -r            # all workspaces
vis explain react           # npm-compatible alias
```

## Options [#options]

| Option          | Alias | Default | Description                                   |
| --------------- | ----- | ------- | --------------------------------------------- |
| `--json`        |       | `false` | Output as JSON                                |
| `--long`        |       | `false` | Show extended information (pnpm)              |
| `--parseable`   |       | `false` | Machine-readable output (pnpm)                |
| `--recursive`   | `-r`  | `false` | Check across all workspaces                   |
| `--dev`         | `-D`  | `false` | Filter to dev dependencies (pnpm)             |
| `--prod`        | `-P`  | `false` | Filter to production dependencies (pnpm)      |
| `--no-optional` |       | `false` | Exclude optional dependencies (pnpm)          |
| `--global`      | `-g`  | `false` | Check globally installed packages (pnpm)      |
| `--depth`       |       |         | Limit dependency tree depth                   |
| `--filter`      | `-F`  |         | Filter by workspace package name (repeatable) |

## Deno [#deno]

Deno has no `why` command. vis falls back to `deno info <module>`, which prints a forward dependency graph rather than a reverse "who depends on this" trace — close enough to be useful for tracing, but not an exact equivalent.


# Configuration (/docs/packages/vis/configuration)



# Configuration [#configuration]

vis uses two configuration layers:

* **`vis.config.ts`** — workspace-wide settings (target defaults, security, constraints, codeowners, updates)
* **`project.json`** — per-project overrides (targets, tags, layer, owners)

## vis.config.ts [#visconfigts]

Create a `vis.config.ts` in your workspace root:

```typescript
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    // All sections are optional — secure defaults are applied automatically
});
```

Supported file names (checked in order): `vis.config.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`.

### Target Defaults [#target-defaults]

Apply default configuration to all projects that have a matching target.

#### Picking a defaults tool [#picking-a-defaults-tool]

vis ships four mechanisms for sharing target configuration. Use the smallest one that fits — they compose, so you can mix.

| Tool                | Reach for it when…                                                                                                             | Section                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `tasks`             | One target name should behave the same in **every** project (e.g. `build` always declares `^build`).                           | This section                                         |
| `scopedTasks`       | Defaults need to apply to a **subset** of projects matched by `tags` / `projectType` / `layer` / `stack` / `language`.         | [Scoped Tasks](#scoped-tasks)                        |
| `taskGroups`        | The same multi-entry `dependsOn` array repeats across **two or more** targets — name the bundle once, reuse.                   | [Task Groups](#task-groups)                          |
| `@inherit` sentinel | A single project needs to **extend** an inherited array (`dependsOn`, `inputs`, `outputs`, `aliases`) instead of replacing it. | [`@inherit` array sentinel](#inherit-array-sentinel) |

Per-target `project.json#targets` (and `vis.task.ts` overlays) override everything above — use them only for project-specific deviations, not as the default home for shared config.

```typescript
export default defineConfig({
    tasks: {
        build: {
            dependsOn: ["^build"],
            outputs: ["{projectRoot}/dist/**"],
            inputs: ["{projectRoot}/src/**"],
            cache: true,
            type: "build",
        },
        test: {
            dependsOn: ["build"],
            cache: true,
        },
        dev: {
            preset: "server",
        },
    },
});
```

| Property      | Type                         | Description                                                          |
| ------------- | ---------------------------- | -------------------------------------------------------------------- |
| `command`     | `string`                     | Shell command (overrides package.json script)                        |
| `dependsOn`   | `(string \| object)[]`       | Dependencies. `^build` = run on dep projects first                   |
| `outputs`     | `string[]`                   | Output patterns (`{projectRoot}` placeholder supported)              |
| `inputs`      | `(string \| object)[]`       | Input patterns for cache invalidation                                |
| `cache`       | `boolean`                    | Whether cacheable (default depends on `type`)                        |
| `parallelism` | `boolean`                    | Whether supports parallel execution                                  |
| `type`        | `"build" \| "test" \| "run"` | Semantic type (affects cache default)                                |
| `preset`      | `"server" \| "utility"`      | Preset bundle of options                                             |
| `options`     | `object`                     | See [target options](/docs/packages/vis/commands/run#target-options) |

### File Groups [#file-groups]

Named glob collections reusable from target `inputs` via `@filegroup:<name>`:

```typescript
export default defineConfig({
    fileGroups: {
        sources: ["src/**/*.ts", "!src/**/*.test.ts"],
        tests: ["**/*.test.ts", "**/*.spec.ts"],
        configs: ["tsconfig.json", "vis.config.ts"],
    },
    tasks: {
        build: {
            inputs: ["@filegroup:sources", "@filegroup:configs"],
        },
        test: {
            inputs: ["@filegroup:sources", "@filegroup:tests"],
        },
    },
});
```

### Input Forms [#input-forms]

`inputs` accepts three interchangeable string forms — the URI form is sugar over the object form, so all three hash identically and produce the same cache keys:

| Form            | Example                                     | Equivalent object form                               |
| --------------- | ------------------------------------------- | ---------------------------------------------------- |
| Bare glob       | `"src/**/*.ts"`, `"!{projectRoot}/dist/**"` | `{ fileset: "src/**/*.ts" }`                         |
| `file://`       | `"file://tsconfig.json"`                    | `{ fileset: "tsconfig.json" }`                       |
| `glob://`       | `"glob://{projectRoot}/src/**/*"`           | `{ fileset: "{projectRoot}/src/**/*" }`              |
| `env://`        | `"env://NODE_ENV"`                          | `{ env: "NODE_ENV" }`                                |
| `func://`       | `"func://node --version"`                   | `{ runtime: "node --version" }`                      |
| `dep://`        | `"dep://typescript,vitest"`                 | `{ externalDependencies: ["typescript", "vitest"] }` |
| `@filegroup:`   | `"@filegroup:sources"`                      | (expanded inline from `fileGroups.sources`)          |
| Named-input ref | `"production"`                              | (expanded inline from `namedInputs.production`)      |

Negation (`!`) works for fileset forms only: `!file://...`, `!glob://...`, `!{projectRoot}/dist/**`. Negating env/func/dep throws at config load — there is no semantic for "not this env var".

```typescript
export default defineConfig({
    tasks: {
        build: {
            inputs: [
                "glob://{projectRoot}/src/**/*", // fileset
                "file://{workspaceRoot}/tsconfig.base.json",
                "env://NODE_ENV", // env-var fingerprint
                "func://node --version", // runtime-command fingerprint
                "dep://typescript,vitest", // external-dep fingerprint
            ],
        },
    },
});
```

Unknown URI schemes (e.g. `gob://**` typo) throw `InvalidInputUriError` at config load rather than degrading silently into a glob — silent fallback would mask cache-correctness bugs.

### Layered Configuration [#layered-configuration]

`vis.config.ts` can `extends` other config files, and each project can ship a `vis.task.ts` overlay. Both are opt-in — projects without them behave identically to before.

#### `extends` chain [#extends-chain]

`extends` accepts a single string or an array. Each entry is either a relative path (`./` / `../`) resolved against the file declaring `extends`, or an npm package name resolved via Node.js module resolution. Absolute paths are rejected.

```typescript
// vis.config.ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    extends: [
        "@acme/vis-preset", // npm package
        "./shared/security.config.ts", // relative path
    ],
    security: { allowBuilds: { esbuild: true } },
});
```

Entries are processed left-to-right (later entries win). The consumer file always overrides anything pulled in from `extends`. Cycles raise `VisConfigCycleError`; missing entries raise `VisConfigNotFoundError`. Both errors include the full chain of files for debugging deep `extends` graphs.

By default the consumer's arrays replace inherited arrays wholesale. Use the [`@inherit` array sentinel](#inherit-array-sentinel) when you want to extend an array from `extends` (or from `tasks`) instead of replacing it.

#### Per-package `vis.task.ts` [#per-package-vistaskts]

Drop a `vis.task.ts` in a project to override its targets with full type-safety. `project.json` stays the canonical home for static metadata (`tags`, `layer`, `stack`, `language`, `owners`, `projectType`); `vis.task.ts` is the canonical home for dynamic, type-checked target overrides.

```typescript
// packages/api/crud/vis.task.ts
import { defineTaskConfig } from "@visulima/vis/config";

export default defineTaskConfig({
    tasks: {
        build: {
            inputs: ["@inherit", "src/proto/**/*.proto"],
            outputs: ["dist/**/*"],
        },
        test: {
            when: { not: { ci: true } }, // skip locally on CI
        },
    },
});
```

#### Merge precedence [#merge-precedence]

Lowest to highest priority — later overrides earlier:

1. `extends` chain (flattened depth-first, left-to-right)
2. Root `vis.config.ts` values
3. `scopedTasks` blocks (in declaration order)
4. `project.json#targets`
5. **`vis.task.ts#tasks`**
6. `package.json#scripts&#x60; &#x2A;(fallback only — fills `command` if still undefined)*
7. Preset
8. `defaultCacheForType`

#### `@inherit` array sentinel [#inherit-array-sentinel]

By default, child arrays replace parent arrays. To extend instead, use `"@inherit"` — every occurrence is replaced inline by the parent's entries:

```typescript
// vis.config.ts tasks
tasks: {
    build: { dependsOn: ["^build"] },
}

// packages/api/crud/vis.task.ts overlay
tasks: {
    build: { dependsOn: ["@inherit", "^proto-gen"] }, // → ["^build", "^proto-gen"]
}
```

Applies to `dependsOn`, `inputs`, `outputs`, and `aliases`. An empty array (`dependsOn: []`) is a deliberate reset; an array without `@inherit` is a wholesale replace.

**When to reach for `@inherit`:** one project needs an extra dependency, input, or output on top of the inherited defaults — not as a replacement. Common cases: a package that generates code before its build (`["@inherit", "^proto-gen"]`), a test target that also needs fixtures (`inputs: ["@inherit", "{projectRoot}/__fixtures__/**"]`), or an output target that emits a second artefact (`outputs: ["@inherit", "{projectRoot}/types/**"]`).

If you find yourself writing `@inherit` in two or more projects with the same addition, that's the signal to move the addition into `scopedTasks` (scoped) or `tasks` (universal) instead, and drop the per-project overlay.

### Scoped Tasks [#scoped-tasks]

Apply target defaults conditionally based on project metadata:

```typescript
export default defineConfig({
    scopedTasks: [
        {
            match: { tags: ["frontend"] },
            tasks: {
                build: { command: "vite build", outputs: ["dist/**"] },
            },
        },
        {
            match: { projectType: "library", language: "typescript" },
            tasks: {
                build: { command: "tsc --build" },
            },
        },
        {
            match: { layer: ["tool", "automation"] },
            tasks: {
                test: { options: { retryCount: 2 } },
            },
        },
    ],
});
```

Match fields (all optional, must all match):

| Field         | Type                         | Description                         |
| ------------- | ---------------------------- | ----------------------------------- |
| `tags`        | `string[]`                   | Project must have any of these tags |
| `projectType` | `"library" \| "application"` | Project type match                  |
| `layer`       | `string \| string[]`         | Layer match                         |
| `stack`       | `string \| string[]`         | Stack match                         |
| `language`    | `string \| string[]`         | Language match                      |

### Inferred Targets [#inferred-targets]

Project Crystal-style inference: vis can synthesize default targets (`build`, `test`, `dev`, `lint`, `format`, …) for each project by sniffing config files and `package.json` dependencies. Off by default.

```typescript
export default defineConfig({
    inferTargets: true,
});
```

Inferred targets are the **lowest-priority layer** in the merge chain — `package.json` scripts, `project.json`, and per-package `vis.task.ts` always win on a per-target-name basis. Add `"build": "vite build --mode foo"` to `package.json` and that script overrides whatever the Vite detector would have generated; everything else (e.g. `dev`, `preview`) keeps the inferred value.

Run `vis list --inferred` to see exactly what was synthesized in each project.

#### Per-detector opt-in / opt-out [#per-detector-opt-in--opt-out]

Use the object form to disable individual detectors. Detectors omitted from the object stay enabled:

```typescript
export default defineConfig({
    inferTargets: {
        // Drop Jest tests in favour of an explicit script
        jest: false,
        // Drop the legacy webpack detector workspace-wide
        webpack: false,
    },
});
```

To opt **in** to only specific detectors, set the rest to `false` — there is no implicit allow-list. (For most workspaces `true` plus a handful of overrides is the right shape.)

#### Detector coverage [#detector-coverage]

| Category          | Detectors (target names)                                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| App frameworks    | `nuxt`, `next`, `remix`, `astro`, `gatsby`, `docusaurus` — emit `build`, `dev`, `start`/`preview`/`serve`, plus framework-specific (`generate`, `develop`, …) |
| Bundlers          | `vite`, `rolldown`, `tsdown`, `tsup`, `packem`, `rollup`, `webpack` — emit `build` (and `dev`/`preview` where the tool supports it)                           |
| Server frameworks | `nest` — emits `build`, `dev`, `start`                                                                                                                        |
| Test runners      | `vitest`, `jest`, `bun`, `deno`, `playwright`, `cypress` — emit `test`, `test:watch`, `test:e2e`, `cypress:open`                                              |
| Stories           | `storybook` — emits `storybook`, `build-storybook`                                                                                                            |
| Typecheck / docs  | `typescript` (→ `typecheck`), `typedoc` (→ `docs`), `vitepress` (→ `docs:dev`, `docs:build`, `docs:preview`)                                                  |
| Lint / format     | `eslint`, `prettier`, `biome`, `oxlint`, `oxfmt`, `stylelint` (→ `lint:css`), `knip` (→ `knip`)                                                               |
| DB tooling        | `prisma`, `drizzle` — emit `db:generate`, `db:migrate`, `db:push`, `db:studio`                                                                                |
| Release plumbing  | `graphql-codegen` (→ `codegen`), `api-extractor` (→ `api-extract`), `changeset` (→ `changeset:status`, `changeset:version`, `changeset:publish`)              |

When two detectors would emit the same target name, the earlier one in the registry wins. Practical conflicts:

* `build`: nuxt > next > remix > astro > gatsby > docusaurus > vite > nest > rolldown > tsdown > tsup > packem > rollup > webpack
* `test`: vitest > jest > bun > deno
* `test:e2e`: playwright > cypress
* `lint`: eslint > biome > oxlint > deno
* `format` / `format:check`: prettier > biome > oxfmt
* `db:*`: prisma > drizzle

Stylelint and knip use distinct names (`lint:css`, `knip`) so they coexist with the primary linter. Mutating commands (`prettier --write`, `oxfmt`, `deno fmt`) deliberately omit `type` so the cache won't skip a re-format the user expected.

#### Trigger surface [#trigger-surface]

Most detectors fire when **either** a config file or a known dependency is present. Tools that frequently appear as transitive deps require a config file to avoid phantom targets — currently: `vite`, `rolldown`, `rollup`, `webpack`, `storybook`, `nest`, `remix`, `vitepress`, `bun`, `deno`, `changeset`. Detectors with a `fallbackDependency` (e.g. `vitest`) work even with the tool's default config (no `vitest.config.ts` needed).

### Constraints [#constraints]

Enforce dependency rules across the workspace:

```typescript
export default defineConfig({
    constraints: {
        enforceLayerRelationships: true,
        typeBoundaries: {
            enforceApplicationBoundary: true,
            allowedDependencyTypes: {
                application: ["library"],
            },
        },
        tagRelationships: {
            frontend: ["shared", "frontend"],
            backend: ["shared", "backend"],
        },
        dependencyKindRules: {
            noDevDependencyOnProductionDep: true,
            noProductionDependencyOnApplication: true,
        },
    },
});
```

#### Layer Hierarchy [#layer-hierarchy]

When `enforceLayerRelationships: true`, projects may only depend on projects at the same or lower layer:

```
configuration < library < scaffolding < tool < automation < application
```

### Version Constraint [#version-constraint]

Enforce a minimum vis CLI version for the workspace:

```typescript
export default defineConfig({
    versionConstraint: ">=1.0.0",
});
```

When the running vis binary is older than the constraint, vis exits with an actionable error before executing any command. Accepts semver range syntax (`>=1.0.0`, `^1.2.0`, `>=1.0.0 <2.0.0`).

### CODEOWNERS [#codeowners]

Configure `vis sync codeowners` output:

```typescript
export default defineConfig({
    codeowners: {
        orderBy: "project-id", // or "file-source" (default)
        provider: "github",
        globalPaths: {
            "/.github/**": ["@myorg/platform"],
        },
    },
});
```

### Security [#security]

Supply-chain security settings (secure defaults applied automatically):

```typescript
export default defineConfig({
    security: {
        strictDepBuilds: true,
        trustPolicy: "no-downgrade",
        blockExoticSubdeps: true,
        // Package names exempt from blockExoticSubdeps. Bare names and a
        // trailing `*` glob (`@scope/*`) are supported.
        exoticSubdepsAllow: ["@myorg/legacy", "internal-*"],
        // Re-verify the entire resolved lockfile closure (not just newly
        // added packages) against these policies. See `vis security
        // verify-lockfile`.
        policies: {
            firstSeen: { minutes: 1440 }, // block versions published < 24h ago
            publisherChange: { mode: "no-downgrade" }, // block provenance downgrades
        },
        minimumReleaseAge: 1440, // 24 hours; `vis init` writes 2880 by default
        minimumReleaseAgeExclude: ["@types/node"],
        socket: { enabled: true, minimumScore: 0.4 },
        // Optional second supply-chain provider (no auth, OpenSSF Scorecard + GHSA).
        // Off by default. Enable to cross-check Socket findings or replace them.
        depsDev: { enabled: true },
        // When both providers are enabled, the "primary" wins score conflicts;
        // alerts always dedupe by id. Defaults to "socket".
        primaryProvider: "socket",
        allowBuilds: { esbuild: true, "@prisma/client": true },
        // Optional: match allowBuilds keys as `name@version`. A version bump
        // drops the entry until you re-approve it. See `vis security list`
        // or `vis approve-builds` for the "Version drift" suggestions.
        pinVersions: false,
        // Silence bin-name conflicts (two packages exposing the same bin).
        // Bare names bless every package owning the bin; `pkg#bin` targets one.
        allowBins: { tsc: true, "left#eslint": true },
    },
});
```

Key knobs introduced with the build-script triage and drift checker:

* `allowBuilds` — the canonical allowlist. Wildcards (`@scope/*`, `name@*`) and version pins (`name@1.2.3`, requires `pinVersions: true`) are accepted.
* `minimumReleaseAge` — gating window in **minutes**. `vis init` writes `2880` (2 days) by default; `vis security sync` mirrors the value into the PM's native config (pnpm `minimumReleaseAge`, bun seconds, npm `min-release-age`, yarn `npmMinimalAgeGate`).
* `minimumReleaseAgeExclude` — package names exempt from the gate. Synced into pnpm and bun (the only PMs with a native excludes list).
* `pinVersions` — opt-in version-aware allowlist matching, ported from LavaMoat allow-scripts.
* `allowBins` — opt-in suppression for bin-name shadowing (LavaMoat allow-scripts parity). `vis security list` flags collisions when two or more installed packages declare the same bin name (e.g. both `typescript` and `competitor-ts` shipping `tsc`). Bare keys (`tsc: true`) silence every package owning that bin; qualified keys (`typescript#tsc: true`) only bless one — every other owner must also be blessed, or the conflict still surfaces.
* `blockExoticSubdeps` / `exoticSubdepsAllow` — flag transitive dependency edges resolving from a git repo or a direct remote tarball instead of the registry. pnpm enforces this natively (vis mirrors the knob into `pnpm-workspace.yaml`); the scanner closes the equivalent gap for **npm / yarn / bun**, whose lockfiles preserve the raw specifier on every edge. `exoticSubdepsAllow` exempts package names (bare or trailing-`*` glob) legitimately published as a git/tarball dependency.
* `policies.firstSeen` / `policies.publisherChange` — closure-verification policies. Unlike the pre-install marshalls (which only inspect packages being *added*), these re-validate the **entire resolved lockfile closure** every run, so a tampered/poisoned lockfile is caught even on npm/yarn/bun and even when nothing is being added. `firstSeen.minutes` blocks any locked version published less than N minutes ago (lockfile-side counterpart to pnpm's `minimumReleaseAge`); `publisherChange.mode: "no-downgrade"` blocks a locked version that dropped a provenance attestation a prior version carried. Both are network-bound and skipped under `--offline`. Run them on demand with [`vis security verify-lockfile`](/docs/packages/vis/commands/security#verify-lockfile).

After install/update commands vis automatically prints a **drift report** when `vis.config` and the PM-native config disagree. Run `vis security sync` to push vis-config values to the native config; run `vis security list` to inspect the full triage (approved / unapproved / stale / version-drift).

### Task Runner [#task-runner]

```typescript
export default defineConfig({
    taskRunner: {
        parallel: 5,
        smartLockfileHashing: true,
        frameworkInference: true,
        autoEnvVars: true, // auto-fingerprint $VAR refs in command text
        remoteCache: {
            url: "https://cache.example.com",
            token: "my-token",
            teamId: "my-team",
            compression: "brotli", // or "gzip" (default, Turborepo-compatible)
        },
    },
});
```

Notable options:

* `autoEnvVars` — when `true`, every task's command text is scanned for `$VAR` / `${VAR}` references and those env vars are automatically added to the cache fingerprint. Catches common mistakes like `curl ${VERCEL_URL}/api` that would otherwise silently return stale cached output.
* `remoteCache.compression` — `"gzip"` (default) keeps Turborepo protocol compatibility; `"brotli"` reduces upload size at the cost of lock-in to vis clients on both ends.
* `remoteCache.attestation` — keyless-sign artifacts with Sigstore in CI and pin the signer identity on download (provenance on top of the HMAC `signing` integrity layer). See the [Attested remote cache](/docs/packages/vis/guides/attested-cache) guide.

### Strict env [#strict-env]

```ts
export default defineConfig({
    strictEnv: true, // default: false
});
```

When `true`, every task's command is scanned for `${VAR}` / `$VAR` references before spawn. If any reference resolves to neither the task's effective env (envFile + service env + per-task `env` + `process.env`) nor an inline default (`${VAR:-fallback}`), the task fails with an actionable error naming the missing variable — no silent empty-string substitution. Override per-run with `--strict-env` / `--no-strict-env`. Override per target with `options.strictEnv`. Pairs naturally with `autoEnvVars` (fingerprint the references) — strict env catches references with no value at all, autoEnvVars catches stale cache hits when the value changed.

### Task Groups [#task-groups]

Named bundles of target dependencies, referenceable from any task's `dependsOn`. Groups expand recursively; cycles throw with a clear error.

```typescript
export default defineConfig({
    taskGroups: {
        lint: ["eslint", "prettier", "types"],
        "pre-build": [{ group: "lint" }, "codegen"],
    },
    tasks: {
        build: {
            // Expands to: ["eslint", "prettier", "types", "codegen"]
            dependsOn: [{ group: "pre-build" }],
        },
    },
});
```

Use groups when the same three-or-more-entry `dependsOn` array repeats across targets — the indirection is worth it once you have it in two or more places.

### Plugins [#plugins]

Typed plugin API built on [`hookable`](https://github.com/unjs/hookable). Each plugin registers handlers that fire at run / task / cache boundaries.

```typescript
import { defineConfig, definePlugin } from "@visulima/vis/config";

const slackNotifier = definePlugin({
    name: "slack-notifier",
    hooks: {
        "task:failure": async (task, result) => {
            await fetch(process.env.SLACK_WEBHOOK!, {
                method: "POST",
                body: JSON.stringify({
                    text: `❌ ${task.id} failed (exit ${result.code})`,
                }),
            });
        },
        "run:after": async (results) => {
            const failed = [...results.values()].filter((r) => r.status === "failure").length;
            // aggregate summary…
        },
    },
});

export default defineConfig({
    plugins: [slackNotifier],
});
```

Available hooks:

| Hook             | Arguments                          | When                                                   |
| ---------------- | ---------------------------------- | ------------------------------------------------------ |
| `run:before`     | `{ tasks, workspaceRoot }`         | Once, before any task starts. Throwing aborts the run. |
| `run:after`      | `results: Map<taskId, TaskResult>` | Once, after all tasks complete (success or failure).   |
| `task:before`    | `task: Task`                       | Before each task's command runs.                       |
| `task:after`     | `task, result: TaskResult`         | After each task completes (any status).                |
| `task:cacheHit`  | `task, result: TaskResult`         | Task served from local or remote cache.                |
| `task:cacheMiss` | `task, reasons: string`            | Auto-fingerprint cache miss with diagnostic reason.    |
| `task:failure`   | `task, result: TaskResult`         | Task exited non-zero.                                  |

For advanced cases (`hookOnce`, `removeHook`, `beforeEach`), use the imperative form:

```typescript
definePlugin({
    name: "once",
    setup(hooks) {
        hooks.hookOnce("run:before", async () => {
            // runs only on the first invocation
        });
    },
});
```

Handlers run in registration order, awaited sequentially. A handler that throws propagates out of `callHook` — wrap in try/catch inside the handler if failure shouldn't abort the run.

### Update Defaults [#update-defaults]

```typescript
export default defineConfig({
    update: {
        target: "minor",
        exclude: ["legacy-*"],
        packageMode: { typescript: "minor" },
    },
});
```

### Installer Backend [#installer-backend]

Pin which package manager runs `vis install`, `vis add`, `vis remove`, `vis update`, `vis dlx`, `vis exec`, and friends. Useful for opting a workspace into [aube](https://github.com/endevco/aube) — a Rust-native PM that reads/writes pnpm/npm/yarn/bun lockfiles in place — without forcing every team member to remember CLI flags.

```typescript
export default defineConfig({
    install: {
        backend: "auto", // "auto" | "aube" | "pnpm" | "npm" | "yarn" | "bun" | "deno"
    },
});
```

| Value                                              | Behavior                                                                                                       |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `"auto"&#x60; &#x2A;(default)*                     | Use `aube` when it's on `PATH`, otherwise fall back to the lockfile-detected PM                                |
| `"aube"`                                           | Always use aube. Errors with an actionable message when the binary is missing instead of silently falling back |
| `"pnpm"` / `"npm"` / `"yarn"` / `"bun"` / `"deno"` | Pin to the named PM regardless of what's on PATH                                                               |

#### Resolution precedence [#resolution-precedence]

Highest first:

1. CLI flag — `vis install --installer <name>` (or `--no-aube` to force the lockfile-detected PM for one run)
2. Environment variable — `VIS_INSTALLER=<name>`
3. This `install.backend` field
4. Auto-detect

#### Aube installation [#aube-installation]

`vis` does not bundle aube. Install it once via your tool of choice:

```bash
npm install -g @endevco/aube
# or
mise use -g aube
# or
brew install endevco/tap/aube
```

#### Lockfile drift [#lockfile-drift]

Aube reuses pnpm/npm/yarn/bun lockfile formats but its serialized output isn't byte-identical to the original tool's. The first install on a workspace whose lockfile was written by another PM produces a one-time churn diff in git, and teams that mix tools on the same lockfile see ongoing drift. `vis install` warns when this is about to happen — pin `install.backend` here to keep the team consistent.

#### Catalogs [#catalogs]

Aube supports the pnpm `catalog:` and `catalog:<name>` protocol from `pnpm-workspace.yaml`, including walk-up resolution from subpackages. No additional configuration needed.

### AI [#ai]

Configures provider selection, cache TTL, and the allow-list for `vis ai heal accept`.

```typescript
export default defineConfig({
    ai: {
        // Optional: pin to a specific provider; otherwise vis auto-detects.
        provider: "claude",
        // Optional: override default provider priority (higher = preferred).
        priority: { claude: 80, gemini: 50 },
        // Optional: override the AI response cache TTL (ms).
        cacheTtl: 3_600_000,
        heal: {
            // Allow-list for `vis ai heal accept`. Empty = auto-commit disabled.
            // GitHub/GitLab: platform usernames (no leading `@`).
            // Buildkite: BUILDKITE_UNBLOCKER_EMAIL value (preferred) or BUILDKITE_UNBLOCKER username.
            // List both shapes for any maintainer who accepts patches across providers.
            allowedActors: ["ada-lovelace", "maintainer@example.com"],
        },
    },
});
```

| Field                   | Default                            | Description                                                                                   |
| ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `ai.provider`           | auto-detect                        | Pin a specific AI runner (`"claude"`, `"gemini"`, etc.). Skips detection.                     |
| `ai.priority`           | built-in order                     | Override the per-provider priority. Higher numbers win when multiple are detected.            |
| `ai.cacheTtl`           | 1 h (30 min for security analyses) | AI response cache TTL in milliseconds.                                                        |
| `ai.heal.allowedActors` | `[]`                               | Usernames/emails authorised to trigger `vis ai heal accept`. Empty list disables auto-commit. |

The allow-list is the only gate between an AI proposal and a real commit, so vendoring `vis.config.ts` in a shared preset is the recommended way to manage it. A mismatched entry yields a provider-aware refusal that names the env var checked (`BUILDKITE_UNBLOCKER_EMAIL` on Buildkite, comment-author login on GitHub/GitLab) so the operator can fix the right thing. See the [AI integration guide](/docs/packages/vis/guides/ai-integration#acceptance-vis-ai-heal-accept) for the full per-provider trigger flow.

### Post-command notices [#post-command-notices]

vis prints two opt-out notices on stderr after a successful command completes — never on failure, never in CI, never on non-TTY shells. Each is rate-limited to once every 14 days per machine.

```typescript
export default defineConfig({
    sponsor: { enabled: false },
    mcpPromote: { enabled: false },
});
```

| Field                | Default | Description                                                                                                                                                                                                                                               |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sponsor.enabled`    | `true`  | One-line "consider sponsoring visulima" notice.                                                                                                                                                                                                           |
| `mcpPromote.enabled` | `true`  | One-line tip pointing at `@visulima/vis-mcp` install when an AI CLI (Claude Code, Cursor, Windsurf, Continue, Zed, Cline) is installed locally but vis-mcp is not yet wired into its config. Suppressed during `ai` / `mcp` / help / version invocations. |

Each notice has an equivalent env-var opt-out — useful when a single invocation should stay quiet without touching the config file:

| Env var                | Effect                                                  |
| ---------------------- | ------------------------------------------------------- |
| `VIS_NO_SPONSOR=1`     | Suppresses the sponsor notice for this invocation.      |
| `VIS_NO_MCP_PROMOTE=1` | Suppresses the vis-mcp install tip for this invocation. |

The MCP nudge never writes to your AI CLI's config — it prints a copy-paste command. Staying out of the trust chain is intentional.

### Generator [#generator]

Points `vis generate` at extra template directories beyond the defaults (`.vis/templates/`, `.moon/templates/`) and the bundled builtins.

```typescript
export default defineConfig({
    generator: {
        templates: ["./tools/generators", "./packages/scaffolding/templates"],
        // Optional: token forwarded to giget for `git://` / `npm://` remote
        // templates. Falls back to GIGET_AUTH / GITHUB_TOKEN / GH_TOKEN.
        auth: process.env.PRIVATE_TEMPLATES_TOKEN,
        // Optional: prefer locally-cached remote templates over re-downloading.
        preferOffline: false,
    },
});
```

| Field                     | Default | Description                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `generator.templates`     | `[]`    | Extra directories to scan. Each is checked for both native templates (`<name>.ts`) and moon-format directories (`<name>/template.yml`). |
| `generator.auth`          |         | Auth token for downloading private remote templates via giget. Falls back to `GIGET_AUTH` / `GITHUB_TOKEN` / `GH_TOKEN` env vars.       |
| `generator.preferOffline` | `false` | Prefer the giget cache over re-downloading. Override per-invocation with `--prefer-offline`.                                            |

Discovery and override semantics — including how to vendor a customised copy of a builtin (e.g. `buildkite-ci`) at `.vis/templates/<name>/` — are in the [`vis generate` reference](/docs/packages/vis/commands/generate#discovery).

***

## project.json [#projectjson]

Place a `project.json` in each workspace package for per-project configuration. Enable editor autocomplete with the `$schema` field:

```json
{
    "$schema": "https://unpkg.com/@visulima/vis/schemas/project.schema.json",
    "name": "my-library",
    "projectType": "library",
    "layer": "library",
    "stack": "frontend",
    "language": "typescript",
    "tags": ["frontend", "shared"],
    "sourceRoot": "src",
    "implicitDependencies": ["@myorg/config"],
    "owners": [{ "path": "src/**", "owners": ["@myorg/core-team"] }],
    "project": {
        "title": "My Library",
        "description": "Shared utilities",
        "owner": "@myorg/core-team"
    },
    "targets": {
        "build": {
            "command": "tsc --build",
            "type": "build",
            "outputs": ["dist/**"]
        },
        "dev": {
            "command": "vite dev",
            "preset": "server"
        }
    }
}
```

### Fields [#fields]

| Field                  | Type       | Description                                                                                                                                 |
| ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema`              | `string`   | JSON Schema for editor autocomplete                                                                                                         |
| `name`                 | `string`   | Project identity in the workspace graph and CLI filters. Falls back to `package.json#name` when omitted (see [Project name](#project-name)) |
| `projectType`          | `string`   | `"library"` or `"application"`                                                                                                              |
| `layer`                | `string`   | `configuration`, `library`, `scaffolding`, `tool`, `automation`, `application`                                                              |
| `stack`                | `string`   | `backend`, `frontend`, `data`, `infrastructure`, `systems`                                                                                  |
| `language`             | `string`   | Primary language (e.g. `typescript`, `rust`)                                                                                                |
| `tags`                 | `string[]` | Filterable tags for queries and constraints                                                                                                 |
| `sourceRoot`           | `string`   | Source root directory (default: `src`)                                                                                                      |
| `implicitDependencies` | `string[]` | Projects this project implicitly depends on                                                                                                 |
| `owners`               | `object[]` | Code ownership declarations (see [vis sync](/docs/packages/vis/commands/sync))                                                              |
| `project`              | `object`   | Human-readable metadata (title, description, owner)                                                                                         |
| `targets`              | `object`   | Target definitions (see [vis run](/docs/packages/vis/commands/run#target-options))                                                          |

### Project name [#project-name]

`project.json#name`, when set, becomes the project's identity in the workspace graph — it's what shows up in `vis list`, what `vis run <name>:build` matches, and the key the project graph uses internally. If omitted, vis falls back to `package.json#name`, matching the historic behaviour, so existing workspaces keep working without change.

Use it when:

* The npm name and the project name should differ — e.g. publish as `@myorg/web` but address it as `web` from the CLI.
* You're migrating from Nx — Nx workspaces declare project names in `project.json` and vis now reads them natively.

A `package.json` is still required alongside `project.json` — `name`-only projects without a `package.json` aren't supported.

Cross-project dependency edges still resolve through `package.json#dependencies` by their **npm name**, so an aliased project remains reachable from sibling packages without rewriting their dependency lists.

### Implicit Dependencies [#implicit-dependencies]

`implicitDependencies` declares project edges that don't exist in `package.json`. Use it when project A needs to rebuild whenever project B changes, but A doesn't actually `import` B — so the package-manager graph wouldn't pick it up.

```json
{
    "$schema": "https://unpkg.com/@visulima/vis/schemas/project.schema.json",
    "projectType": "application",
    "implicitDependencies": ["@myorg/eslint-config", "@myorg/tsconfig"]
}
```

Common triggers:

* **Shared config packages** — your `eslint-config` / `tsconfig` / `prettier-config` package isn't `import`ed at runtime, but every consumer needs its `build` to run first.
* **Codegen sources** — a `.proto` package or schema-generator that emits files into a sibling project. The consumer doesn't `import` the generator; it consumes its output.
* **Docs / fixture packages** — your `docs` app reads MDX from a sibling package via filesystem globs, not imports.
* **Composite-tsconfig roots** — TypeScript project references already imply rebuild ordering, but only if `tsc --build` runs; for cache invalidation in vis, declare the edge explicitly.

If two projects already have a `package.json` dependency edge (`"dependencies": { "@myorg/lib": "workspace:*" }`), vis picks that up automatically — don't duplicate it here. `implicitDependencies` is the escape hatch for the cases where the dep graph misses what the build graph needs.

Add the same project name to multiple consumers' `implicitDependencies` to fan it out; vis deduplicates during graph construction.

### Targets in project.json [#targets-in-projectjson]

Target definitions in `project.json` are merged on top of package.json scripts. If a target has a `command`, it overrides the script. If not, the package.json script is used as the command.

Targets support all fields from [target options](/docs/packages/vis/commands/run#target-options) including `type`, `preset`, and `options`.

### Conditional execution (`when:`) [#conditional-execution-when]

`when:` gates a task on the current environment. The orchestrator evaluates it just before launch; tasks that don't match are marked **skipped** (not failed) and the reason is reported in the run summary.

```json
{
    "targets": {
        "deploy": {
            "command": "pnpm run deploy",
            "when": {
                "branch": ["main", "alpha"],
                "ci": true,
                "env": { "name": "DEPLOY_TOKEN", "exists": true }
            }
        }
    }
}
```

Clauses are AND-ed; an array inside a clause is OR-ed.

| Clause   | Type                        | Meaning                                                                            |
| -------- | --------------------------- | ---------------------------------------------------------------------------------- |
| `os`     | `string \| string[]`        | Match `process.platform`. `"windows"` is sugar for `"win32"`.                      |
| `env`    | `string \| object \| array` | String form: var must be set+non-empty. Object form: `{ name, equals?, exists? }`. |
| `branch` | `string \| string[]`        | Current git branch (HEAD). Empty when not in a repo or on detached HEAD.           |
| `ci`     | `boolean`                   | `true` → only inside CI; `false` → only outside. Detected via `CI` env var.        |
| `not.*`  | mirrors of all of the above | Task runs only when *every* `not.*` clause **fails** to match.                     |

```json
// "macOS or Linux, only when running on a release branch, never in CI"
"when": {
    "os": ["darwin", "linux"],
    "branch": ["main", "next"],
    "not": { "ci": true }
}
```

### Finally tasks (`always:`) [#finally-tasks-always]

Set `always: true` to pull a task out of the dependency graph and run it after the main run completes — **even when upstream tasks fail**. Useful for cleanup, teardown, notifications, or anything that must fire regardless of build outcome.

```json
{
    "targets": {
        "test": { "command": "vitest run" },
        "stop-db": {
            "command": "docker compose down",
            "always": true
        }
    }
}
```

Always-tasks:

* never block the main graph (they don't appear as dependencies of other tasks)
* run sequentially after the main run, in declaration order
* are **not cached** (cleanup must always fire)
* are **skipped on SIGINT** (the user asked to stop — don't keep going)

### Affected-files tokens [#affected-files-tokens]

Tasks that should only act on files affected by the current change set can interpolate `${affected.files}` (or its alias `${changed_files}`) into the command string. Vis populates the values from `git diff --name-only` against the affected base.

```json
{
    "targets": {
        "lint": { "command": "eslint ${affected.files}" },
        "format": { "command": "prettier --write ${affected.files}" }
    }
}
```

Use the `| flag` variant when a tool needs the flag repeated per file:

```json
{
    "targets": {
        "stylelint": { "command": "stylelint ${changed_files | flag '--file'}" }
    }
}
```

Paths are workspace-relative by default and are shell-quoted so paths with spaces or quotes survive the shell. Files outside the project root are filtered out automatically — token interpolation only emits paths the task can act on.

When the affected set is empty the token expands to nothing, so chain a guard if you want to skip rather than run with no arguments:

```json
{
    "targets": {
        "lint": {
            "command": "test -z \"${affected.files}\" || eslint ${affected.files}"
        }
    }
}
```

Tokens are **complementary** to the `affectedFiles` target option (`"args"` / `"env"` / `"both"`) — tokens are explicit and embed paths exactly where you want them; the option is implicit and forwards paths to every invocation. Pick whichever matches the tool's expected interface.

Escape with a leading backslash (`\${affected.files}`) to emit the literal token without expansion.

For an end-to-end walkthrough including CI examples, see [Conditional and finally tasks](/docs/packages/vis/guides/conditional-and-finally-tasks).

***

## Workspace Discovery [#workspace-discovery]

vis automatically discovers your workspace structure:

1. **pnpm** — Reads `pnpm-workspace.yaml` for package patterns
2. **npm/yarn/bun** — Falls back to the `workspaces` field in root `package.json`
3. **Project metadata** — Reads `project.json` files for targets, tags, layer, stack, language, owners
4. **Dependency graph** — Built from `dependencies`, `devDependencies`, and `peerDependencies` in each project's `package.json`


# AI Integration (/docs/packages/vis/guides/ai-integration)



# AI Integration [#ai-integration]

vis ships an embedded **Model Context Protocol** server (`vis-mcp`) and a companion **Claude Skill**. Together they let an AI assistant inspect your workspace, plan target runs and scaffolds, and diagnose cache rotations — all through the same task graph the CLI uses.

* **MCP server** is the wire format. It works with any MCP-aware client: Claude Code, Claude Desktop, Cursor, Zed, ChatGPT (Pro+), Continue, and more.
* **Claude Skill** is workflow guidance layered on top. It teaches Claude *when* to call which tool, and reinforces the "agent prepares, human executes" pattern: every tool is read-only, so the assistant builds the right `vis run` / `vis generate` command and a person actually runs it.

The MCP SDK and `zod` are declared as **optional peer dependencies**. They are only required when you actually launch `vis-mcp` — running plain `vis` does not pull them in.

## Installation [#installation]

Install the optional peers alongside vis:

```bash
pnpm add @modelcontextprotocol/sdk zod
# or
npm install @modelcontextprotocol/sdk zod
```

Verify the bin is wired:

```bash
pnpm exec vis-mcp
# [vis-mcp] ready (workspace: /path/to/repo)
```

The server speaks JSON-RPC over stdio and never writes to stdout outside the protocol — all logs go to stderr.

## Client setup [#client-setup]

### Claude Code [#claude-code]

```bash
claude mcp add vis -- pnpm exec vis-mcp
```

Once added, the eight `vis` tools are available in any Claude Code session opened in this repo.

### Claude Desktop [#claude-desktop]

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
    "mcpServers": {
        "vis": {
            "command": "pnpm",
            "args": ["exec", "vis-mcp"],
            "cwd": "/absolute/path/to/your/repo"
        }
    }
}
```

Restart Claude Desktop. The `vis` server will appear in the tools panel.

### Cursor [#cursor]

Add to `.cursor/mcp.json` at the repo root (project-scoped) or `~/.cursor/mcp.json` (global):

```json
{
    "mcpServers": {
        "vis": {
            "command": "pnpm",
            "args": ["exec", "vis-mcp"]
        }
    }
}
```

### Zed [#zed]

Add to your settings:

```json
{
    "context_servers": {
        "vis": {
            "command": "pnpm",
            "args": ["exec", "vis-mcp"]
        }
    }
}
```

### ChatGPT (Developer Mode) [#chatgpt-developer-mode]

Add the server in **Settings → Connectors → Add MCP server**:

* Name: `vis`
* Command: `pnpm exec vis-mcp`
* Working directory: your repo path

### Workspace override [#workspace-override]

By default `vis-mcp` operates against `process.cwd()`. Override it from the client config:

```json
{
    "mcpServers": {
        "vis": {
            "command": "pnpm",
            "args": ["exec", "vis-mcp"],
            "env": { "VIS_MCP_WORKSPACE_ROOT": "/absolute/path/to/repo" }
        }
    }
}
```

## Claude Skill [#claude-skill]

The package also exports a Claude Skill at `node_modules/@visulima/vis/skills/vis/SKILL.md`. The skill encodes opinionated workflow guidance — when to use each tool, the safety story for `run_task`, and how to investigate cache misses.

To activate it project-wide, symlink the skill into your repo:

```bash
mkdir -p .claude/skills
ln -s ../../node_modules/@visulima/vis/skills/vis .claude/skills/vis
```

Or copy it directly if you prefer to keep skills version-controlled:

```bash
cp -R node_modules/@visulima/vis/skills/vis .claude/skills/vis
```

Skills and the MCP server are independent — you can use either, or both. The MCP server alone gives Claude tool access; the skill alone gives Claude workflow guidance for the tools it can already see.

## Tool reference [#tool-reference]

The MCP server exposes eight read-only tools.

### `list_projects` [#list_projects]

List all workspace projects with their language, type, layer, tags, and target metadata.

| Argument | Type      | Description                                                |
| -------- | --------- | ---------------------------------------------------------- |
| `query`  | `string?` | vis query string (e.g. `tag=frontend`, `type=application`) |

### `describe_project` [#describe_project]

Return full metadata for a single project.

| Argument | Type     | Description                             |
| -------- | -------- | --------------------------------------- |
| `name`   | `string` | Project name (e.g. `@visulima/cerebro`) |

### `list_targets` [#list_targets]

List per-target rows across the workspace. Optionally narrow to one project.

| Argument  | Type      | Description          |
| --------- | --------- | -------------------- |
| `project` | `string?` | Limit to one project |

### `list_templates` [#list_templates]

List scaffolding templates discovered in `.vis/templates/`, `.moon/templates/`, `vis.config.ts` `generator.templates`, and the builtins shipped with `@visulima/vis` (e.g. `buildkite-ci`).

Takes no arguments. Returns each template's `name`, `source` (`native` | `moon` | `config` | `builtin` | `remote`), on-disk `path`, and one-line `description`. The agent uses `source` to tell the user when a template is the bundled preset vs. their own copy — and that vendoring `.vis/templates/<builtin-name>/` is the supported way to override a builtin.

### `describe_template` [#describe_template]

Return the full schema for a single template — useful before suggesting a `vis generate` invocation.

| Argument | Type     | Description                                 |
| -------- | -------- | ------------------------------------------- |
| `name`   | `string` | Template name (e.g. `package`, `component`) |

Returns: `description`, `destination` (default target dir), and `variables[]` with `name`, `type`, `required`, `default`, `prompt`, and (for enums) `values`. The agent uses this to build a fully-qualified `vis generate <name> -- --foo=bar` command for the user to run.

### `get_run_logs` [#get_run_logs]

Read the run summary from `.vis/`. Defaults to `last-summary.json`.

| Argument | Type      | Description                          |
| -------- | --------- | ------------------------------------ |
| `runId`  | `string?` | Specific run ID (defaults to latest) |
| `taskId` | `string?` | Filter to one task                   |

### `cache_why` [#cache_why]

Diff a task's cache hash against the previous run to pinpoint what changed.

| Argument | Type      | Description                       |
| -------- | --------- | --------------------------------- |
| `taskId` | `string`  | Task ID like `@my/app:build`      |
| `runId`  | `string?` | Specific run (defaults to latest) |

### `cache_hash` [#cache_hash]

Print the recorded hash and per-input hash details (command, nodes, runtime, implicitDeps).

| Argument | Type      | Description                       |
| -------- | --------- | --------------------------------- |
| `taskId` | `string`  | Task ID like `@my/app:build`      |
| `runId`  | `string?` | Specific run (defaults to latest) |

## Safety: agent prepares, human executes [#safety-agent-prepares-human-executes]

`vis-mcp` deliberately ships **no side-effecting tools**. There is no `run_task` and no template-applying tool — the agent's job is to investigate (`list_*` / `describe_*` / `get_run_logs` / `cache_*`) and then propose the exact `vis run` or `vis generate` command for a human to execute. This mirrors the Nx MCP design and removes a whole class of failure modes (runaway builds, accidental writes, long timeouts) that come with letting an LLM drive the runner directly.

If you want the assistant to actually run something for you, paste the suggested command into your terminal — or wire it through a separate tool you trust (e.g. Claude Code's bash tool with explicit per-call approval).

## Self-healing CI [#self-healing-ci]

`vis ai heal` ([command reference](/docs/packages/vis/commands/ai#heal)) closes the loop on a failed CI run: it reads the latest failed task from `.vis/runs/`, asks the configured AI provider for a structured patch, applies it, validates the fix by re-running the failing target with `--no-cache --summarize --fail-fast`, and — when validation passes — posts the proposal back to the PR/MR.

CI surface detection lives in [`src/ai/ci-context.ts`](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/ai/ci-context.ts):

* **GitHub Actions** (`GITHUB_ACTIONS=true`): resolves the PR number from `GITHUB_REF` (`refs/pull/<n>/merge`) or the `GITHUB_EVENT_PATH` payload, captures the head SHA from the event, and reads `GITHUB_TOKEN` for REST fallback.
* **GitLab CI** (`GITLAB_CI=true`): reads `CI_MERGE_REQUEST_IID`, `CI_API_V4_URL`, `CI_PROJECT_ID` (with `CI_PROJECT_PATH` fallback), and `GITLAB_TOKEN` / `CI_TOKEN` (the auto-injected `CI_JOB_TOKEN` cannot post MR notes — `vis ai heal` skips it deliberately).
* **Buildkite** (`BUILDKITE=true`): captures `BUILDKITE_BUILD_ID` (annotation dedup key), `BUILDKITE_BUILD_NUMBER`, `BUILDKITE_ORGANIZATION_SLUG`, `BUILDKITE_PIPELINE_SLUG`, the literal `BUILDKITE_PULL_REQUEST` value (`"false"` for non-PR builds), and `BUILDKITE_API_BASE_URL` for self-hosted Enterprise. There is no PR-comment surface to listen to — heal acceptance flows through a [block step](https://buildkite.com/docs/pipelines/block-step) instead.
* **Anything else**: provider is reported as `unknown` and the comment step is skipped — the patch is still applied and validated locally.

Comment posting in [`src/ai/pr-comment.ts`](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/ai/pr-comment.ts) dispatches on the resolved provider:

* **GitHub**: tries `gh pr comment --body-file -` first (uses the runner's bundled `gh` and auto-injected token, falls back to `--repo` when the local clone lacks `origin`). On failure, falls back to `POST /repos/:owner/:repo/issues/:n/comments` with `GITHUB_TOKEN`.
* **GitLab**: posts directly to `POST /projects/:id/merge_requests/:iid/notes` via the REST API. `glab` is not preinstalled on shared runners and project tokens are the standard auth shape, so `vis` skips the CLI path entirely.
* **Buildkite**: posts a build [annotation](https://buildkite.com/docs/agent/v3/cli-annotate) via `buildkite-agent annotate` with `--context vis-ai-heal-${BUILDKITE_BUILD_ID}` so reruns update the same annotation in place. Falls back to the Buildkite REST API (`POST /v2/.../builds/{n}/annotations`, requires `BUILDKITE_API_TOKEN`, honours `BUILDKITE_API_BASE_URL`) when the agent CLI isn't available.
* **Push-event runs**: report `posted: false, method: "skipped"` — there's no PR/MR to comment on.

Pass `--dry-run` to inspect the proposal without applying or commenting; pass `--validation-timeout <seconds>` to cap how long the re-run is allowed to take (default 30 min). The PR/MR comment (or Buildkite annotation) is bounded at \~60 KB; oversized patch sets drop the inline diff body and leave a pointer to `vis ai fix … --apply`.

### Acceptance: `vis ai heal accept` [#acceptance-vis-ai-heal-accept]

`vis ai heal accept` ([command reference](/docs/packages/vis/commands/ai#heal-accept)) closes the loop: it re-validates the latest heal proposal, then commits the patch to the PR/MR branch via the upstream provider. The acceptance signal is provider-specific and lives in [`src/commands/ai/heal-accept.ts`](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/commands/ai/heal-accept.ts):

* **GitHub Actions / GitLab CI**: an allow-listed maintainer comments `/vis heal accept` on the PR/MR.
* **Buildkite**: an allow-listed maintainer **unblocks** a block step. `BUILDKITE_UNBLOCKER_EMAIL` (preferred) or `BUILDKITE_UNBLOCKER` is the actor checked against the allow-list — there is no comment phrase. Because Buildkite has no commit API of its own, vis derives the upstream provider from `BUILDKITE_REPO` (`*github*` → GitHub, `*gitlab*` → GitLab) and commits through whichever `GITHUB_TOKEN` / `GITLAB_TOKEN` is set. Both HTTPS and SSH `BUILDKITE_REPO` shapes are recognised, and non-default ports on self-hosted GitLab (e.g. `:8443`) are preserved in the synthesised API base URL.

When the trigger actor is missing from the allow-list, the error message is provider-aware so the operator can fix the right env var: GitHub/GitLab entries are platform usernames (no leading `@`), Buildkite entries are unblocker emails or Buildkite usernames. Acceptance is also refused when the change is on a forked repository — the CI token can't push to forks.

## Troubleshooting [#troubleshooting]

**`Cannot find module '@modelcontextprotocol/sdk'`** — install the optional peer: `pnpm add @modelcontextprotocol/sdk zod`.

**Claude doesn't see the tools** — check the client logs. Most clients write MCP startup errors to a debug log; in Claude Desktop it's `~/Library/Logs/Claude/mcp.log`.

**`vis-mcp` reports the wrong workspace** — set `VIS_MCP_WORKSPACE_ROOT` in the MCP server's `env` block. The default `process.cwd()` depends on where the parent client launches the process.

**JSON-RPC framing errors** — something in your `vis` config wrote to stdout. The server is a stdio transport, so any `console.log` in a config plugin or task hook will corrupt the protocol stream. Move logs to `console.error`.


# Attested remote cache (/docs/packages/vis/guides/attested-cache)



# Attested remote cache [#attested-remote-cache]

The remote cache has two independent trust layers:

* **`remoteCache.signing` (HMAC)** — *integrity*. A shared secret proves a stored artifact was not tampered with. Anyone holding the secret can produce a valid MAC, so it answers "was this changed?" — not "who produced it?".
* **`remoteCache.attestation` (Sigstore)** — *authenticity*. Each artifact is keyless-signed in CI against a short-lived [Fulcio](https://docs.sigstore.dev/) certificate minted from the workflow's OIDC token and logged in [Rekor](https://docs.sigstore.dev/logging/overview/). On download vis verifies the bundle **and pins the signer identity**, so a valid signature from an *unexpected* identity is rejected.

Use attestation when the cache is shared across trust boundaries (a public or multi-tenant bucket, untrusted PR runners) and you need "this artifact was produced by *our* release workflow," not just "this artifact is intact."

> The payload signed and verified is the artifact's sha256, recomputed from disk on both ends — never the digest the server claims. A server that swaps bytes but echoes the requested hash still fails verification.

## 1. Install the optional dependency [#1-install-the-optional-dependency]

Sigstore is an optional peer dependency — the weight (tuf-js, the bundle/protobuf machinery) is only paid where attestation is actually used:

```bash
pnpm add -D sigstore   # or: npm install -D sigstore / yarn add -D sigstore / bun add -d sigstore
```

If `remoteCache.attestation` is configured but `sigstore` is missing, `vis run` prints a startup warning with the exact install command and continues **unsigned** rather than failing the build. `vis attest` (interactive) offers to install it for you.

## 2. Configure the expected signer [#2-configure-the-expected-signer]

`expectedIdentity` is **required** — verifying a bundle without pinning *who* signed it only re-proves integrity, which the HMAC layer already does. Pick one of three forms:

```typescript
export default defineConfig({
    taskRunner: {
        remoteCache: {
            url: "https://cache.example.com",
            token: process.env.CACHE_TOKEN,
            attestation: {
                // (a) GitHub Actions preset — recommended
                expectedIdentity: {
                    github: {
                        repo: "visulima/visulima",
                        workflow: ".github/workflows/release.yml",
                        ref: "refs/heads/main",
                    },
                },
                requireOnDownload: true,
            },
        },
    },
});
```

| Form                                  | When to use                                              | Anchoring                                                                                                                                                                  |
| ------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ github: { repo, workflow, ref } }` | GitHub Actions (the common case)                         | Expands to issuer `https://token.actions.githubusercontent.com` and the literal SAN `https://github.com/{repo}/{workflow}@{ref}`, regex-escaped and `^…$`-anchored for you |
| `{ oidcIssuer, san }`                 | Any other OIDC provider; you know the exact identity URI | vis regex-escapes and anchors it — pass the **plain URI**, not a regex                                                                                                     |
| `{ oidcIssuer, sanRegex }`            | Advanced: you genuinely need a pattern (e.g. any tag)    | **Raw, unescaped regex — you own anchoring.** Unanchored values are substring-matched                                                                                      |

> **Why anchoring matters.** sigstore-js matches the SAN with `String.prototype.match`, i.e. as an *unanchored regex*. An unanchored pattern is substring-matched, so a longer attacker-controlled SAN that merely *contains* your expected value would pass. The `github` and literal `san` forms are escaped and anchored automatically; only `sanRegex` exposes this, and `vis run` warns if a `sanRegex` is not `^…$`-anchored.

## 3. Signing in CI [#3-signing-in-ci]

Signing needs an ambient OIDC token. In GitHub Actions, grant the job `id-token: write`:

```yaml
permissions:
    contents: read
    id-token: write # required for keyless signing
```

vis detects ambient OIDC via `CI=true`, `ACTIONS_ID_TOKEN_REQUEST_URL`, or `SIGSTORE_ID_TOKEN`. With a token present, every cache **upload** is signed and the bundle travels in the `X-Artifact-Attestation` header. Outside CI (local dev) signing is skipped and the upload proceeds **unsigned** — local machines shouldn't block on a Fulcio round-trip they can't complete.

## 4. `requireOnDownload` and the mixed-producer caveat [#4-requireondownload-and-the-mixed-producer-caveat]

`requireOnDownload` (default `false`) controls what happens to a download whose attestation is missing or fails verification:

* **`false`** — treat it as a cache *miss* and re-execute the task. Soft; no provenance guarantee, but no hard failure.
* **`true`** — reject it. Provenance is enforced.

Because local producers upload **unsigned**, a workspace that mixes local and CI producers against one cache will see local entries rejected by any consumer with `requireOnDownload: true`, forcing re-execution until CI repopulates them. That is intended. **Set `requireOnDownload: true` only where every producer runs in CI** (e.g. a read-only cache for PR runners, populated solely by the release workflow).

## 5. Observability [#5-observability]

Two callbacks are wired to `vis run`'s logger:

* **Rejection** — `remote cache entry <hash> rejected: attestation <invalid|missing>. Treating as a cache miss.`
* **Verification failure** — `attestation verification failed: <message>`. The message is sigstore's own, so an unexpected-signer mismatch (`certificate identity error - expected …, got …`) is distinguishable from a broken chain or an expired-cert error at a glance.

## Troubleshooting [#troubleshooting]

| Symptom                                                               | Cause                                               | Fix                                                                                                                    |
| --------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `…requires a pinned keyless signer via expectedIdentity` at startup   | `attestation` block has no valid `expectedIdentity` | Add one of the three identity forms                                                                                    |
| Startup warning: `sigstore package is not installed`                  | Optional dep missing                                | Run the printed install command; uploads stay unsigned until then                                                      |
| `verification failed: certificate identity error - expected X, got Y` | Signer identity ≠ pinned identity                   | The artifact was produced by a different workflow/ref. Confirm `repo`/`workflow`/`ref` (or fix the producing workflow) |
| All CI hits re-execute under `requireOnDownload: true`                | A local/unsigned producer populated the cache       | Ensure every producer for that cache runs in CI, or set `requireOnDownload: false`                                     |

See also: [Security audit](/docs/packages/vis/guides/security-audit) for inbound provenance verification, and `vis attest` for standalone (non-cache) artifact attestation.


# Best Practices (/docs/packages/vis/guides/best-practices)



# Best Practices [#best-practices]

Learn how to use `vis` effectively in team environments, enterprise workflows, and production systems.

## Team Collaboration [#team-collaboration]

### Shared Configuration [#shared-configuration]

Keep your `vis.json` configuration consistent across team members by committing it to version control:

```json
{
    "update": {
        "target": "minor",
        "exclude": ["legacy-*", "deprecated-*"]
    },
    "tasks": {
        "build": {
            "dependsOn": ["^build"],
            "outputs": ["{projectRoot}/dist/**"],
            "cache": true
        }
    }
}
```

### Code Review Guidelines [#code-review-guidelines]

**Pre-Review Checklist:**

* Run `vis check --dry-run` to preview changes
* Verify no breaking changes in major version updates
* Test critical functionality after dependency updates
* Review CHANGELOG files for updated packages

**Review Process:**

* **Security First** — Always review security-related dependency updates immediately
* **Batch Related Updates** — Group related packages (e.g., React ecosystem) in single PRs
* **Document Reasons** — Include rationale for version pinning or exclusions
* **Test Coverage** — Ensure adequate testing before merging dependency updates

### Communication Standards [#communication-standards]

Use clear commit messages when updating dependencies:

```bash
# Good commit messages
feat(deps): update React to v18.3.0 for improved performance
security(deps): patch lodash vulnerability CVE-2021-23337
chore(deps): update dev dependencies to latest versions

# Poor commit messages
update packages
fix deps
bump versions
```

## Enterprise Usage [#enterprise-usage]

### Governance and Compliance [#governance-and-compliance]

**Dependency Approval Process:**

* **Security Scanning** — All updates must pass security audits
* **License Compliance** — Verify license compatibility with internal policies
* **Stability Requirements** — Prefer LTS versions in production environments
* **Change Management** — Follow established change approval processes

**Enterprise Configuration:**

```json
{
    "update": {
        "target": "minor",
        "exclude": ["experimental-*"]
    }
}
```

### Private Registry Integration [#private-registry-integration]

Configure your workspace for corporate environments with private registries:

```ini
# .npmrc (workspace root)
@company:registry=https://npm.company.com/
//npm.company.com/:_authToken=${NPM_TOKEN}
registry=https://npm.company.com/

# Public packages fallback
@types:registry=https://registry.npmjs.org/
```

`vis check` and `vis update` automatically read `.npmrc` configuration, including scoped registry mappings and authentication tokens.

### Audit Trail and Reporting [#audit-trail-and-reporting]

Maintain records of dependency changes:

```bash
# Generate dependency reports
vis check --format json > dependency-report.json

# Include in CI/CD pipeline
vis check --format json > artifacts/deps-$(date +%Y%m%d).json
```

## Release Workflows [#release-workflows]

### Semantic Versioning Integration [#semantic-versioning-integration]

Align dependency updates with your release cycle:

**Pre-Release Phase:**

```bash
# Check for updates without applying
vis check --target patch

# Update only patch versions during freeze
vis update --target patch --exclude "major-framework-*"
```

**Release Preparation:**

```bash
# Update to latest stable versions
vis update --target minor --exclude "experimental-*"
```

**Post-Release:**

```bash
# Update to latest including major versions
vis update --target latest --interactive
```

### Staging Environment Testing [#staging-environment-testing]

**Pre-Production Validation:**

```bash
# Update dependencies (backup is created automatically)
vis update --target minor

# Run comprehensive tests
pnpm run test:integration
pnpm run test:e2e

# Rollback if issues found
vis update --rollback
```

## Security Best Practices [#security-best-practices]

### Vulnerability Management [#vulnerability-management]

**Response Priorities:**

| Severity        | Response Time                        |
| --------------- | ------------------------------------ |
| Critical / High | Update within 24 hours               |
| Moderate        | Update within 1 week                 |
| Low             | Include in next regular update cycle |

```bash
# Check for security vulnerabilities
vis check --security

# Review and apply security fixes
vis update --security --interactive
```

### Manual Security Reviews [#manual-security-reviews]

* Review all new dependencies before first use
* Audit package maintainers and download counts
* Verify package authenticity and signatures
* Check for known security issues in dependency chains

### Token Management [#token-management]

```bash
# Use scoped tokens with minimal permissions
NPM_TOKEN=npm_[REDACTED]_readonly_access_only

# Rotate tokens regularly (quarterly)
# Store tokens in secure credential management systems
# Never commit tokens to version control
```

## Performance Optimization [#performance-optimization]

### Large Monorepo Handling [#large-monorepo-handling]

For workspaces with many catalog entries, filter by scope:

```bash
# Process by categories
vis check --include "@company/ui-*"
vis check --include "@company/api-*"
vis check --include "@types/*" --target latest

# Use filtering for large operations
vis update --include "react*" --exclude "*-experimental"
```

### Task Caching [#task-caching]

Leverage `vis run` caching for faster builds:

```json
{
    "tasks": {
        "build": {
            "outputs": ["{projectRoot}/dist/**"],
            "cache": true
        },
        "test": {
            "cache": true
        }
    },
    "taskRunner": {
        "parallel": 5,
        "smartLockfileHashing": true
    }
}
```

### Network Optimization [#network-optimization]

```ini
# .npmrc — use faster registries geographically close to your location
registry=https://registry.npmjs.org/
```

## Error Handling and Recovery [#error-handling-and-recovery]

### Backup and Recovery [#backup-and-recovery]

`vis update` automatically creates a backup before modifying catalog files.

```bash
# Update with automatic backup
vis update --target minor

# Restore from backup if something goes wrong
vis update --rollback

# Manual backup as an alternative
cp pnpm-workspace.yaml pnpm-workspace.yaml.backup
```

### Version Rollback Strategy [#version-rollback-strategy]

```bash
# Rollback entire catalog
vis update --rollback

# Or restore from git
git checkout HEAD~1 pnpm-workspace.yaml
pnpm install
```

## Integration Patterns [#integration-patterns]

### Package.json Scripts [#packagejson-scripts]

```json
{
    "scripts": {
        "deps:check": "vis check",
        "deps:update:patch": "vis update --target patch",
        "deps:update:minor": "vis update --target minor --interactive",
        "deps:security": "vis check --security",
        "prerelease": "vis check && vis check --security"
    }
}
```

### Git Hooks Integration [#git-hooks-integration]

```bash
# Install vis git hooks
vis hook install

# Create a pre-commit hook
echo '#!/bin/sh
vis check --exit-code --format minimal || {
  echo "Dependency issues detected. Run vis check for details."
  exit 1
}' > .vis/hooks/pre-commit
chmod +x .vis/hooks/pre-commit
```

### Migrating from Husky [#migrating-from-husky]

```bash
# Automatically migrate existing husky hooks
vis hook migrate
```

## Quick Reference Checklist [#quick-reference-checklist]

### Daily Workflow [#daily-workflow]

* Check for security updates: `vis check --security`
* Review outdated dependencies: `vis check`
* Update patch versions: `vis update --target patch`

### Weekly Workflow [#weekly-workflow]

* Comprehensive dependency check: `vis check`
* Update minor versions: `vis update --target minor --interactive`
* Review and update exclusion rules in `vis.json`

### Monthly Workflow [#monthly-workflow]

* Review major version updates: `vis check --target latest`
* Update development dependencies: `vis update --dev`
* Audit dependency licenses and compliance
* Review and optimize `vis.json` configuration

### Before Releases [#before-releases]

* Run full security audit: `vis check --security`
* Preview all changes: `vis update --dry-run`
* Update in staging: `vis update --target minor`
* Test thoroughly, then rollback if needed: `vis update --rollback`


# CI/CD Integration (/docs/packages/vis/guides/ci-cd)



# CI/CD Integration [#cicd-integration]

Integrate vis into your continuous integration and deployment pipelines.

## GitHub Actions [#github-actions]

### Build and Test [#build-and-test]

Only build and test affected projects in pull requests:

```yaml
name: CI
on: [pull_request]

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0 # Full history for affected detection

            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: 20
                  cache: pnpm

            - run: pnpm install --frozen-lockfile

            - name: Build affected projects
              run: vis affected build --base=origin/main

            - name: Test affected projects
              run: vis affected test --base=origin/main
```

### Dependency Health Checks [#dependency-health-checks]

Run scheduled dependency checks:

```yaml
name: Dependency Check
on:
    schedule:
        - cron: "0 9 * * 1" # Every Monday at 9am

jobs:
    check:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: 20
                  cache: pnpm

            - run: pnpm install --frozen-lockfile

            - name: Check for outdated dependencies
              run: vis check --format json > deps-report.json

            - name: Security audit
              run: vis check --security --exit-code

            - name: Upload report
              if: always()
              uses: actions/upload-artifact@v4
              with:
                  name: dependency-report
                  path: deps-report.json
```

### Task Caching [#task-caching]

Cache task runner artifacts between CI runs:

```yaml
- name: Cache vis task runner
  uses: actions/cache@v4
  with:
      path: .vis/cache
      key: vis-cache-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
      restore-keys: |
          vis-cache-${{ runner.os }}-
```

### Collapsible Task Output [#collapsible-task-output]

`vis run` automatically wraps each task's output in a collapsible group when it detects a supported CI runner, so the web UI shows one foldable section per task instead of a single firehose of stdout. Failed tasks are always rendered expanded so the failure is visible without an extra click.

| Runner          | Detected via          | Format emitted               |
| :-------------- | :-------------------- | :--------------------------- |
| GitHub Actions  | `GITHUB_ACTIONS=true` | `::group::` / `::endgroup::` |
| GitLab CI       | `GITLAB_CI=true`      | `section_start:` ANSI lines  |
| Buildkite       | `BUILDKITE=true`      | `--- ` collapsed headers     |
| Azure Pipelines | `TF_BUILD=True`       | `##[group]` / `##[endgroup]` |

CircleCI is intentionally not auto-detected: its 2.0+ format has no inline grouping directive — steps auto-group in the web UI without any markup from the runner.

Override the default detection in `vis.config.ts`:

```ts
export default defineConfig({
    run: {
        // "auto" (default) — detect via env. "off" disables grouping.
        // "azure" / "buildkite" / "github" / "gitlab" force the format
        // on self-hosted runners that don't set the standard env vars.
        ciGrouping: "auto",
    },
});
```

## GitLab CI [#gitlab-ci]

`vis ci` auto-detects GitLab merge-request pipelines via `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` and `CI_COMMIT_SHA`, so the affected-graph base/head are derived without manual flags.

### Build and Test [#build-and-test-1]

```yaml
default:
    image: node:22

variables:
    GIT_DEPTH: 0 # Full history for affected detection

stages:
    - ci

ci:
    stage: ci
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    before_script:
        - corepack enable
        - corepack prepare pnpm@latest --activate
    script:
        - pnpm vis ci lint,test,build
```

`vis ci` runs `pnpm install --frozen-lockfile`, then `vis affected` for each comma-separated target. Pass `--no-install` if the install step is already handled elsewhere.

### vis ai heal on merge requests [#vis-ai-heal-on-merge-requests]

`vis ai heal` posts the proposed patch as an MR note. It needs an API token that can write notes — `CI_JOB_TOKEN` cannot, so set `GITLAB_TOKEN` (or `CI_TOKEN`) on the job:

```yaml
heal:
    stage: ci
    needs: [ci]
    when: on_failure
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    variables:
        GITLAB_TOKEN: $GITLAB_HEAL_TOKEN # project/group access token with `api` scope
    script:
        - pnpm vis ai heal
```

When a maintainer comments `/vis heal accept` on the MR, run `vis ai heal accept` from a follow-up pipeline (or scheduled poll) — the command re-derives the proposal, validates it, and commits via the GitLab REST API using the same token.

## Buildkite [#buildkite]

Buildkite agents auto-detect through `BUILDKITE`, `BUILDKITE_PULL_REQUEST_BASE_BRANCH`, and `BUILDKITE_COMMIT`. `vis ai heal` renders as a build [annotation](https://buildkite.com/docs/agent/v3/cli-annotate); acceptance is a manual unblock on a [block step](https://buildkite.com/docs/pipelines/block-step) — there is no PR-comment surface to listen to.

### Generate the pipeline [#generate-the-pipeline]

The shape below ships as a builtin `vis generate` template — point at the package preset instead of copy-pasting:

```bash
vis generate buildkite-ci
```

The template prompts for `targets`, `packageManager`, `withHeal`, and `agentQueue`, and writes to `.buildkite/pipeline.yml`. Vendor a customised copy at `.vis/templates/buildkite-ci/` to override the bundled preset — discovery prefers the user copy when names collide.

### Reference pipeline [#reference-pipeline]

The generator emits the same shape as below. Drop this in `.buildkite/pipeline.yml` if you'd rather hand-write it:

```yaml
steps:
    - label: ":hammer: vis ci"
      key: ci
      command: |
          corepack enable
          corepack prepare pnpm@latest --activate
          pnpm vis ci lint,test,build
      agents:
          queue: default

    - label: ":sparkles: vis ai heal"
      key: heal-propose
      depends_on: ci
      if: build.failed_jobs > 0
      command: pnpm vis ai heal
      env:
          # Required so heal can commit cross-VCS once accepted.
          # Set whichever matches the upstream repo.
          GITHUB_TOKEN: "${GITHUB_TOKEN}"
          # GITLAB_TOKEN: "${GITLAB_TOKEN}"

    - block: ":white_check_mark: Apply AI heal patch?"
      key: heal-gate
      depends_on: heal-propose
      prompt: "Unblocking will apply and commit the patch from the heal annotation."

    - label: ":robot_face: vis ai heal accept"
      depends_on: heal-gate
      command: pnpm vis ai heal accept
      env:
          GITHUB_TOKEN: "${GITHUB_TOKEN}"
          # GITLAB_TOKEN: "${GITLAB_TOKEN}"
```

The annotation context is keyed on `BUILDKITE_BUILD_ID`, so reruns update the existing annotation instead of stacking duplicates on the same build.

### Token requirements [#token-requirements]

| Surface                          | Token                                                        | Why                                                                                                                                          |
| -------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Annotation via `buildkite-agent` | none — uses the agent's `BUILDKITE_AGENT_ACCESS_TOKEN`       | First fallback path; works on every standard Buildkite agent.                                                                                |
| Annotation via REST              | `BUILDKITE_API_TOKEN` with `write_build_annotations`         | Second fallback when the CLI is missing (uncommon).                                                                                          |
| `vis ai heal accept` commit      | `GITHUB_TOKEN` *or* `GITLAB_TOKEN`                           | Buildkite has no commit API of its own — vis derives the upstream provider from `BUILDKITE_REPO` and commits through GitHub/GitLab directly. |
| Self-hosted Buildkite            | `BUILDKITE_API_BASE_URL=https://buildkite.acme.internal/api` | Honoured by the REST fallback; the agent CLI honours its own config.                                                                         |

The block-step unblocker is the acceptance signal — `BUILDKITE_UNBLOCKER_EMAIL` (preferred) or `BUILDKITE_UNBLOCKER` is checked against the heal allow-list, so `/vis heal accept` is implicit on Buildkite (no comment-trigger phrase to match).

### Allow-list entries on Buildkite [#allow-list-entries-on-buildkite]

`ai.heal.allowedActors` is matched against the trigger actor verbatim. The actor identifier differs by provider:

| Provider       | Source env / payload                                   | Example entry            |
| -------------- | ------------------------------------------------------ | ------------------------ |
| GitHub Actions | `comment.user.login` from the `issue_comment`          | `octocat`                |
| GitLab CI      | `VIS_HEAL_TRIGGER_ACTOR` (set by webhook bridge)       | `ada-lovelace`           |
| Buildkite      | `BUILDKITE_UNBLOCKER_EMAIL` then `BUILDKITE_UNBLOCKER` | `maintainer@example.com` |

If you operate the same allow-list across providers (vendoring `vis.config.ts` in a shared preset), include both shapes — Buildkite emails and platform usernames — for any maintainer authorised to accept heal patches. A mismatched allow-list yields an actionable refusal naming the missing entry shape.

### Push-event builds [#push-event-builds]

Push builds (no PR) report `BUILDKITE_PULL_REQUEST=false`. `vis ai heal` still runs and the annotation still renders, but heal-accept refuses to commit because there is no MR/PR head branch to push to. Gate the heal step on PR builds if you want it skipped entirely:

```yaml
- label: ":sparkles: vis ai heal"
  if: build.pull_request.id != null && build.failed_jobs > 0
  command: pnpm vis ai heal
```

## Enforcing Dependency Policies [#enforcing-dependency-policies]

Use `--exit-code` to fail the pipeline when outdated dependencies are found:

```yaml
- name: Enforce patch updates
  run: vis check --target patch --exit-code
```

Use `--security` to catch vulnerabilities:

```yaml
- name: Security gate
  run: vis check --security --exit-code
```

## Keeping Pipelines Pinned [#keeping-pipelines-pinned]

`vis update` auto-detects and bumps non-npm references alongside the catalog flow:

* **GitHub Actions** — every `uses:` in `.github/workflows/*.yml` and composite `action.yml` files. Defaults to pinning to a commit SHA with a `# vN.M.P` version comment for readability.
* **Docker** — every `FROM` line in any `Dockerfile*` and every `image:` field in `docker-compose*.yml`.
* **GitLab CI** — `image:`, `services:`, and `include: { project, ref }` blocks in `.gitlab-ci.yml` plus anything under `.gitlab/ci/`.

`vis update` honours ignore lists declared in `.github/dependabot.yml` and `renovate.json` (`ignoreDeps`, `ignore.dependency-name`, and `packageRules` with `enabled: false`) so existing automation rules are respected.

To pin actions in a workflow that runs the updater itself:

```yaml
- uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.0.0
- name: Update actions and docker references
  env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: vis update --yes --dry-run
```

Drop `--dry-run` to apply, or run `--style preserve` to keep existing tag-style refs. Pass `--no-actions`, `--no-docker`, or `--no-gitlab` to opt out of a specific ecosystem. Use `--include-branches` to also bump branch refs (`@main`).

## Deployment Build Gating [#deployment-build-gating]

Use [`vis ignore`](/docs/packages/vis/commands/ignore) to cancel deployment platform builds when the target app isn't affected by the latest commit. It exits with **inverted codes** (`0` = skip, `1` = build) so it drops directly into Vercel's "Ignored Build Step" and Netlify's `ignore` field.

### Vercel [#vercel]

Under **Project → Settings → Git → Ignored Build Step**:

```bash
npx @visulima/vis ignore my-app
```

Vercel exposes `VERCEL_GIT_PREVIOUS_SHA`, which `vis ignore` picks up automatically as the base ref. When the ref isn't reachable (Vercel's checkout is shallow by default), it silently falls back to `HEAD~1`.

### Netlify [#netlify]

`netlify.toml`:

```toml
[build]
ignore = "npx @visulima/vis ignore my-app"
```

Netlify exposes `CACHED_COMMIT_REF`, which `vis ignore` picks up automatically.

### GitHub Actions (preflight gate) [#github-actions-preflight-gate]

GitHub Actions has no native "ignore" hook, but you can run `vis ignore --json` as a preflight step and gate downstream jobs on the decision:

```yaml
name: CI
on: [pull_request]

jobs:
    gate:
        runs-on: ubuntu-latest
        outputs:
            action: ${{ steps.decide.outputs.action }}
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
            - uses: pnpm/action-setup@v4
            - run: pnpm install --frozen-lockfile

            - id: decide
              run: |
                  pnpm vis ignore my-app --json --exit-zero-on-build \
                      | tee decision.json
                  echo "action=$(jq -r .action decision.json)" >> "$GITHUB_OUTPUT"

    deploy:
        needs: gate
        if: needs.gate.outputs.action == 'build'
        runs-on: ubuntu-latest
        steps:
            - run: echo "Deploying…"
```

`--exit-zero-on-build` disables the inverted-exit-code contract so the preflight step itself always succeeds — the decision flows through the job output instead.

### Commit-message overrides [#commit-message-overrides]

Commit-message keywords take precedence over git diff detection, for emergency bypasses:

| Token                                                        | Effect                                |
| ------------------------------------------------------------ | ------------------------------------- |
| `[skip ci]` / `[ci skip]` / `[no ci]` / `[vis skip]`         | Skip build (all projects)             |
| `[vis skip <project>]`                                       | Skip build for one project            |
| `[vis deploy]`                                               | Force build (all projects)            |
| `[vis deploy <project>]`                                     | Force build for one project           |
| `[nx skip]` / `[nx skip <project>]&#x60; &#x2A;(legacy)*     | Skip, for nx-ignore migration         |
| `[nx deploy]` / `[nx deploy <project>]&#x60; &#x2A;(legacy)* | Force deploy, for nx-ignore migration |

See the [`vis ignore` reference](/docs/packages/vis/commands/ignore) for the full list of options and reason codes.

### Unsupported platforms [#unsupported-platforms]

Cloudflare Pages, Cloudflare Workers Builds, Render, and AWS Amplify do **not** invoke custom ignore scripts — they only support path-based filters and fixed commit keywords. Use their native filtering features instead, or move CI gating into GitHub Actions / GitLab CI as shown above.

## Generating Reports [#generating-reports]

Export JSON reports for monitoring dashboards or Slack notifications:

```yaml
- name: Generate reports
  run: |
      vis check --format json > check-results.json
      vis check --security --format json > security-results.json
```


# Conditional and finally tasks (/docs/packages/vis/guides/conditional-and-finally-tasks)



# Conditional and finally tasks [#conditional-and-finally-tasks]

Three task primitives let you express "run only sometimes" and "always clean up" without resorting to wrapper scripts:

* **`when:`** — gates execution on OS, env, branch, and CI.
* **`always:`** — runs a task after the main graph, even on failure.
* **`${affected.files}` tokens** — embed only the files that changed.

## `when:` — conditional execution [#when--conditional-execution]

The orchestrator evaluates `when:` immediately before launching a task. A failed predicate marks the task **skipped** (not failed) and surfaces the reason in the run summary, so it stays visible instead of disappearing silently.

### A first example [#a-first-example]

```json title="project.json"
{
    "targets": {
        "deploy": {
            "command": "pnpm run deploy",
            "when": {
                "branch": ["main", "alpha"],
                "ci": true,
                "env": { "name": "DEPLOY_TOKEN", "exists": true }
            }
        }
    }
}
```

This `deploy` runs only when **all** of these hold:

1. The current branch is `main` or `alpha`.
2. We're inside CI (the `CI` env var is truthy).
3. `DEPLOY_TOKEN` is set and non-empty.

Run it locally on a feature branch and you'll see:

```text
$ vis run deploy
↳ skipped: branch=feat/new-button does not match ["main","alpha"]
```

### Clause grammar [#clause-grammar]

Positive clauses are **AND**-ed. Within a clause, an array is **OR**-ed. The optional `not` block negates each clause individually.

| Clause         | Form                                      | Example                                      |
| -------------- | ----------------------------------------- | -------------------------------------------- |
| `os`           | `string` \| `string[]`                    | `"linux"` · `["linux", "darwin"]`            |
| `env` (string) | env var must be set and non-empty         | `"GITHUB_TOKEN"`                             |
| `env` (object) | `{ name, equals }` for exact value        | `{ name: "NODE_ENV", equals: "production" }` |
| `env` (object) | `{ name, exists: false }` for unset/empty | `{ name: "SKIP_BUILD", exists: false }`      |
| `branch`       | `string` \| `string[]`                    | `["main", "alpha", "beta"]`                  |
| `ci`           | `boolean`                                 | `true` (only in CI) · `false` (only locally) |
| `not.*`        | mirrors of every clause above             | `not: { ci: true }` (locally only)           |

The `os` clause accepts every Node.js platform value (`aix`, `darwin`, `freebsd`, `linux`, `openbsd`, `sunos`, `win32`) plus the friendly alias `windows` (treated as `win32`).

### Patterns that come up often [#patterns-that-come-up-often]

**Local-only task** — useful for things like opening Storybook or starting a dev tunnel:

```json
"when": { "ci": false }
```

**Skip on Windows** — for Unix-only tooling:

```json
"when": { "not": { "os": "win32" } }
```

**Release-branch CI smoke test**:

```json
"when": {
    "ci": true,
    "branch": ["main", "next", "alpha", "beta"]
}
```

**Toggle by feature flag** — useful when you want a task to participate in `vis run` only when an env var opts in:

```json
"when": { "env": "ENABLE_INTEGRATION_TESTS" }
```

## `always:` — finally tasks [#always--finally-tasks]

Set `always: true` to pull a task out of the dependency graph entirely. It runs once after the main run completes, **even if upstream tasks fail**.

```json title="project.json"
{
    "targets": {
        "test": { "command": "vitest run --coverage" },
        "stop-db": {
            "command": "docker compose down",
            "always": true
        },
        "upload-coverage": {
            "command": "codecov",
            "always": true,
            "when": { "ci": true }
        }
    }
}
```

When you `vis run test`, this happens:

1. `test` runs.
2. Whether `test` succeeds or fails, `stop-db` runs (the database is freed either way).
3. If we're in CI, `upload-coverage` also runs — `always:` and `when:` compose, so finally-tasks can still be conditional.

### Rules of the road [#rules-of-the-road]

* Always-tasks **never block** other tasks. They don't appear as `dependsOn` of anything.
* They run **sequentially** after the main run, in declaration order.
* They are **not cached** — cleanup that doesn't fire isn't cleanup.
* They are **skipped on SIGINT** (Ctrl+C). The user asked to stop; don't keep going.
* They **do** participate in retries and timeouts the same way other tasks do.

## `${affected.files}` — change-aware commands [#affectedfiles--change-aware-commands]

Many tools want a list of files to operate on. Tokens let you embed only the files that changed in the current run, computed from `git diff --name-only` against the affected base.

```json title="project.json"
{
    "targets": {
        "lint": { "command": "eslint ${affected.files}" },
        "format": { "command": "prettier --write ${affected.files}" }
    }
}
```

Run it through the affected pipeline:

```bash
vis affected lint --base=origin/main
```

Vis expands the token before invoking the shell. Paths are:

* workspace-relative by default
* rewritten relative to the project root when the task runs from a project
* **shell-quoted** so paths with spaces or quotes survive the shell
* **filtered** to drop files outside the project root

`${changed_files}` is an alias of `${affected.files}`.

### When you need a flag per file [#when-you-need-a-flag-per-file]

Some tools want `--file path1 --file path2 …` instead of a space-separated list:

```json
{
    "targets": {
        "stylelint": { "command": "stylelint ${changed_files | flag '--file'}" }
    }
}
```

The flag string is a literal — single or double quotes both work. An empty flag is a no-op (just emits the bare paths).

### Empty affected set [#empty-affected-set]

When nothing matches, the token expands to **nothing**. That can be a footgun for tools that read the working directory when given no arguments. Two ways to guard:

```json
// 1. Short-circuit in shell
"command": "test -z \"${affected.files}\" || eslint ${affected.files}"

// 2. Skip the task entirely with `when:` + a custom env var
// (set VIS_HAS_AFFECTED in your CI before the run if you want this)
"when": { "env": "VIS_HAS_AFFECTED" }
```

### Tokens vs. the `affectedFiles` option [#tokens-vs-the-affectedfiles-option]

The `affectedFiles: "args" | "env" | "both"` target option is the **implicit** counterpart of tokens — vis appends paths to the command line or sets `VIS_AFFECTED_FILES`. Use it when the tool already accepts files at the end of the command line.

Tokens are **explicit** — embed the paths exactly where the command needs them. Use them when:

* the tool wants a non-trailing argument position (`some-tool --check ${affected.files} --report=html`)
* you need the per-file flag form (`| flag '--file'`)
* you need to short-circuit on empty input

Both mechanisms can coexist on the same target. They're complementary, not exclusive.

### Escaping [#escaping]

A leading backslash emits the literal token:

```json
"command": "echo '\\${affected.files} expanded to:' && echo '${affected.files}'"
```

## Putting it together [#putting-it-together]

A realistic CI release pipeline using all three primitives:

```json title="project.json"
{
    "targets": {
        "build": {
            "command": "tsc -b",
            "type": "build"
        },
        "test": {
            "command": "vitest run --changed=${affected.files}",
            "dependsOn": ["build"]
        },
        "publish": {
            "command": "pnpm publish --access=public",
            "dependsOn": ["build", "test"],
            "when": {
                "ci": true,
                "branch": "main",
                "env": { "name": "NPM_TOKEN", "exists": true }
            }
        },
        "notify": {
            "command": "node scripts/notify-slack.mjs",
            "always": true,
            "when": { "ci": true }
        }
    }
}
```

Runs as: `build` → `test` (only against affected files) → `publish` (only on `main` in CI with a token), then `notify` always fires in CI to post a status update — pass or fail.


# Config Model (/docs/packages/vis/guides/config-model)



# Config Model [#config-model]

vis splits configuration across three files with different responsibilities. Knowing which file owns which setting saves a lot of refactoring later — and makes it obvious where to look when a value isn't behaving the way you expected.

This page is the narrative companion to [Configuration](/docs/packages/vis/configuration). The reference page documents every field; this page explains how the layers fit together and how to choose between them.

## The three files [#the-three-files]

| File            | Lives in                   | Owns                                                                                                                                                                       | Touched by                          |
| --------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `vis.config.ts` | Workspace root             | Workspace-wide policy: tasks, scoped tasks, file groups, named inputs, security, constraints, codeowners, secrets, update rules.                                           | Workspace lead / platform team      |
| `project.json`  | Each project root          | Per-project **metadata** (`name`, `projectType`, `tags`, `layer`, `stack`, `language`, `owners`, `implicitDependencies`, `sourceRoot`) plus optional per-target overrides. | Project owners                      |
| `vis.task.ts`   | Each project root (opt-in) | Per-project **typed** task overlay — same shape as `project.json#targets` but with full TypeScript inference, autocomplete, and access to runtime helpers.                 | Project owners who want type safety |

`package.json#scripts` is the fourth, implicit layer: any script vis doesn't find a target for is still runnable as a fallback. You almost never need to edit it for vis's sake — leave it for `npm run` ergonomics.

## What goes where — a decision flow [#what-goes-where--a-decision-flow]

Start at the top. The first match wins.

1. **Is this a project-specific deviation** (a single project does something different)?
   → `project.json#targets` for static config, or `vis.task.ts#tasks` for type-safe / dynamic config.
2. **Should this apply to a subset of projects** matched by tag / layer / stack / language / projectType?
   → `vis.config.ts#scopedTasks` (scoped block).
3. **Should this apply to every project** that has a matching target name (e.g. every `build`, every `test`)?
   → `vis.config.ts#tasks` (flat block).
4. **Is it workspace-wide policy** (security, codeowners, constraints, secrets, update rules)?
   → Top-level fields in `vis.config.ts`.

If you find yourself writing the same per-project override in two or more `project.json`s, that's the signal to promote it — step (1) becomes step (2) or step (3).

## Precedence stack [#precedence-stack]

Eight layers feed into the final config a target runs with. Later layers override earlier ones (`later wins`), with one exception: arrays use **wholesale replace by default**, and `"@inherit"` opts a single array entry into "splice the parent's values inline here." See [`@inherit` array sentinel](/docs/packages/vis/configuration#inherit-array-sentinel) for the mechanic.

1. `extends` chain — flattened depth-first, left-to-right
2. Root `vis.config.ts` values (e.g. `namedInputs`, `fileGroups`)
3. `vis.config.ts#tasks` (flat, applies universally)
4. `vis.config.ts#scopedTasks` blocks — in declaration order; only blocks whose `match` resolves against the project apply
5. `project.json#targets`
6. `vis.task.ts#tasks`
7. `package.json#scripts` — fallback only; fills `command` when nothing above set it
8. Preset (e.g. `preset: "server"`) — expanded last so it never clobbers explicit fields

If a target isn't doing what you expect, run [`vis task-why`](/docs/packages/vis/commands/task-why) — it traces every layer that contributed to a target and shows which rule pulled in each `dependsOn`, `inputs`, and `outputs` entry.

## Picking a defaults tool [#picking-a-defaults-tool]

Four mechanisms share target config across projects. Use the smallest one that fits — they compose.

### `tasks` — universal per target name [#tasks--universal-per-target-name]

When every project's `build` should declare the same `dependsOn` and `outputs`, that goes here. One block per target name.

```typescript
// vis.config.ts
export default defineConfig({
    tasks: {
        build: {
            dependsOn: ["^build"],
            outputs: ["{projectRoot}/dist/**"],
            cache: true,
        },
        test: {
            dependsOn: ["build"],
            cache: true,
        },
    },
});
```

**Reach for it when:** every project that exposes a target by this name should behave the same way. &#x2A;*Skip it when:** the rule only applies to a subset — use `scopedTasks` instead.

### `scopedTasks` — scoped to project metadata [#scopedtasks--scoped-to-project-metadata]

Same shape as `tasks`, but each block carries an optional `match` predicate matched against the project's `tags` / `projectType` / `layer` / `stack` / `language`. Blocks evaluate in declaration order; later matching blocks override earlier ones.

```typescript
export default defineConfig({
    scopedTasks: [
        {
            match: { tags: ["frontend"] },
            tasks: {
                build: { command: "vite build", outputs: ["dist/**"] },
            },
        },
        {
            match: { projectType: "library", language: "typescript" },
            tasks: {
                build: { command: "tsc --build" },
            },
        },
    ],
});
```

**Reach for it when:** frontends build with Vite but libraries build with tsc — the *target name* is the same (`build`) but the *command* differs by project shape. &#x2A;*Skip it when:** the rule applies universally (use `tasks`) or only to one project (override in that project's `project.json`).

### `taskGroups` — named dependency bundles [#taskgroups--named-dependency-bundles]

A reusable bundle that any target's `dependsOn` can pull in via `{ group: "name" }`. Groups expand recursively; cycles throw at load.

```typescript
export default defineConfig({
    taskGroups: {
        lint: ["eslint", "prettier", "types"],
        "pre-build": [{ group: "lint" }, "codegen"],
    },
    tasks: {
        build: {
            // expands to: ["eslint", "prettier", "types", "codegen"]
            dependsOn: [{ group: "pre-build" }],
        },
    },
});
```

**Reach for it when:** the same three-or-more-entry `dependsOn` array repeats across **two or more** targets. The indirection earns its keep at the second use site. &#x2A;*Skip it when:** the bundle only appears once — inlining is clearer.

### `@inherit` — additive per-project override [#inherit--additive-per-project-override]

The sentinel string `"@inherit"` inside a child array splices in the parent's entries instead of replacing them. Works inside `dependsOn`, `inputs`, `outputs`, and `aliases`.

```typescript
// vis.config.ts
tasks: {
    build: { dependsOn: ["^build"] },
}

// packages/api/crud/vis.task.ts
tasks: {
    build: { dependsOn: ["@inherit", "^proto-gen"] }, // → ["^build", "^proto-gen"]
}
```

**Reach for it when:** one project needs an extra entry on top of the default — codegen-before-build, fixtures-in-test-inputs, second-artefact-in-outputs. &#x2A;*Skip it when:** you see the same `@inherit` addition in two or more projects — promote the addition into `scopedTasks` (scoped) or `tasks` (universal).

An empty array (`dependsOn: []`) is a deliberate reset. An array without `@inherit` is a wholesale replace. Use `@inherit` to be explicit when you mean "extend, not replace."

## When to use which file for an override [#when-to-use-which-file-for-an-override]

Same setting, three places it could live. Pick by **blast radius** — the narrowest scope that satisfies the requirement.

```
                       blast radius (narrowest → widest)
                       ─────────────────────────────────────────────────
one project only       project.json#targets  /  vis.task.ts#tasks
project subset         vis.config.ts#scopedTasks  (with match)
every project          vis.config.ts#tasks
```

`project.json` vs. `vis.task.ts` for per-project overrides:

* **Use `project.json`** when the override is static JSON — commands, paths, simple options. JSON is friendlier to migration tools (`vis migrate`), generators (`vis generate`), and `vis sync`.
* **Use `vis.task.ts`** when the override needs TypeScript: computed values, conditional logic, type-safe references to your `vis.config.ts` types, runtime helpers. The overlay is opt-in and merges over `project.json#targets`.

## Project metadata vs. target config [#project-metadata-vs-target-config]

`project.json` carries two distinct kinds of data — keep them clean:

* **Metadata** (`name`, `projectType`, `tags`, `layer`, `stack`, `language`, `owners`, `implicitDependencies`, `sourceRoot`, `project`) describes *what the project is*. It's read by `vis query`, `vis sync codeowners`, scoped `scopedTasks`, and the constraint engine. `name` is optional and falls back to `package.json#name` — see [Project name](/docs/packages/vis/configuration#project-name).
* **Targets** (`targets`) describes *what the project builds*. It's read by `vis run`.

Putting `tags: ["frontend"]` in `project.json` lets a `scopedTasks` block target it without naming the project explicitly — that's the leverage. The more projects you tag, the more your defaults stay declarative instead of project-list-driven.

## Workspace-wide policy lives at the top [#workspace-wide-policy-lives-at-the-top]

These don't belong in `tasks` or `scopedTasks` because they don't run as part of a target — they're enforced by other commands:

| Field         | Read by                                                                        |
| ------------- | ------------------------------------------------------------------------------ |
| `security`    | `vis audit`, `vis add`, `vis install`, `vis update`, `vis check`, `vis doctor` |
| `policy`      | `vis deps`                                                                     |
| `constraints` | `vis run` (graph build), `vis check`                                           |
| `codeowners`  | `vis sync codeowners`                                                          |
| `secrets`     | `vis secrets`                                                                  |
| `update`      | `vis update`, `vis outdated`                                                   |
| `staged`      | `vis staged` (git pre-commit)                                                  |
| `install`     | `vis install`, `vis add`, `vis remove`, `vis update`, `vis ci`                 |
| `toolchain`   | `vis toolchain`, version-manager activation                                    |

Treat these as top-level workspace policy — one place, one source of truth, edited rarely. Per-command flags always win over config, so CI workflows can override without rewriting `vis.config.ts`.

## Shared config via `extends` [#shared-config-via-extends]

For monorepos managed by a platform team, hoist common config into a shared preset and `extends` it from every workspace:

```typescript
// vis.config.ts
export default defineConfig({
    extends: ["@myorg/vis-preset", "./shared/security.config.ts"],
    // workspace-specific overrides go below; they always win
    tasks: {
        build: { outputs: ["dist/**"] },
    },
});
```

Entries resolve left-to-right (later wins) and the consumer's own values override anything pulled in from `extends`. Cycles raise `VisConfigCycleError` at load.

## Inferred targets — the layer underneath [#inferred-targets--the-layer-underneath]

`inferTargets` (off by default) auto-generates targets from detected config files: a `vite.config.ts` synthesizes `build` / `dev` / `preview`; a `vitest.config.ts` synthesizes `test` / `test:watch`; and so on across \~36 tools. See the [`inferTargets` reference](/docs/packages/vis/configuration#inferred-targets) for the full detector list.

Inferred targets sit **below** everything in the precedence stack — anything explicit in `package.json#scripts`, `project.json#targets`, or `vis.task.ts` wins per-key. Turning inference on never overrides existing setups; it only fills gaps.

**Reach for it when:** you want to delete `"build": "vite build"` from `package.json#scripts` across 40 projects and let vis derive it. &#x2A;*Skip it when:** your commands are non-standard or the inferred default would be misleading.

## Migrating from another tool? [#migrating-from-another-tool]

`vis migrate` rewrites the source tool's vocabulary onto vis's schema — it's not a pass-through. See [`vis migrate`](/docs/packages/vis/commands/migrate) for the full per-tool mapping. The short version:

* **turborepo** — `tasks` / `pipeline` → `tasks`; `^build` → `{ dependencies: true, target: "build" }`; `globalDependencies` → `taskRunner.globalInputs`.
* **nx** — `namedInputs` carries over verbatim; `targetDefaults` → `tasks`; namespaced executors are dropped with hints.
* **moon** — `tasks` → `tasks`; `deps` → `dependsOn`; `implicitInputs` → `namedInputs.default`; scoped `.moon/tasks/<scope>.yml` → `scopedTasks` with a `match` block.

Per-project `project.json` (nx) and `moon.yml` (moon) are field-compatible enough that vis reads them natively — nx's stay untouched; moon's are flagged for manual conversion since the field names already match (`targets`, `tags`, `layer`, `stack`, `language`, `owners`).


# Git Hooks (/docs/packages/vis/guides/git-hooks)



# Git Hooks [#git-hooks]

vis provides built-in git hook management as a lightweight alternative to tools like husky.

## Getting Started [#getting-started]

### Installing Hooks [#installing-hooks]

```bash
vis hook install
```

This configures `core.hooksPath` to point to your hooks directory (`.vis/hooks` by default).

### Creating a Hook [#creating-a-hook]

Create executable scripts in the hooks directory:

```bash
echo '#!/bin/sh
pnpm run lint-staged' > .vis/hooks/pre-commit

chmod +x .vis/hooks/pre-commit
```

### Commit the Hooks Directory [#commit-the-hooks-directory]

Add the hooks directory to version control so the entire team shares the same hooks:

```bash
git add .vis/hooks/
git commit -m "chore: add git hooks"
```

## Migrating from Husky [#migrating-from-husky]

If your project currently uses husky, vis can automatically migrate your hooks:

```bash
vis hook migrate
```

The migration:

1. Detects your husky directory (`.husky` or `.husky/_`)
2. Copies all hook scripts to the vis hooks directory
3. Prompts for confirmation before making changes
4. Removes the husky directory after migration

## Migrating from prek / pre-commit [#migrating-from-prek--pre-commit]

If your project uses [prek](https://github.com/j178/prek) (a Rust reimplementation of the Python pre-commit framework) or pre-commit itself, the same command detects a `.pre-commit-config.yaml` and converts the eligible hooks to plain shell scripts:

```bash
vis hook migrate
```

vis hook scripts are plain shell, so anything that needs a managed toolchain still has to run via prek. The migrator covers everything else:

1. Parses `.pre-commit-config.yaml`, `.pre-commit-config.yml`, or `prek.toml` (YAML takes precedence when both are present).
2. For each `local` hook with `language: system`, `script`, or `fail`, writes one shell script per stage (e.g. `.vis/hooks/pre-commit`, `.vis/hooks/commit-msg`). Multiple hooks in the same stage are concatenated in declaration order.
3. Preserves `files`/`exclude` regex and `types`/`types_or`/`exclude_types` filters by routing the invocation through a bundled Node helper (`.vis/hooks/.builtins/prek-runner.mjs`) that replicates pre-commit's file-selection semantics. User strings pass via argv — never interpolated into the shell — so even hostile regex patterns can't break out.
4. Translates a curated set of remote hooks from `pre-commit/pre-commit-hooks` to bundled builtins so prek doesn't need to stay installed just for them: `trailing-whitespace`, `end-of-file-fixer`, `check-merge-conflict`, `check-json`, `mixed-line-ending`. Each is a faithful JavaScript port of the upstream Python implementation.
5. Merges each hook's `additional_dependencies` into the project's `package.json` `devDependencies`. Pip-style pins (`name==x.y.z`) are surfaced as a manual step instead of written to the manifest.
6. Forwards `"$@"` for stages where git passes an argument (`commit-msg`, `prepare-commit-msg`, `pre-rebase`, `post-*`) when `pass_filenames` is truthy.
7. Prepends `set -e` to each script when top-level `fail_fast: true` is set.
8. Backs up the original config as `.pre-commit-config.yaml.bak` (or `.yml.bak` / `prek.toml.bak`), removes the original, and runs `prek uninstall` if the binary is on your PATH.

Anything that can't be translated is surfaced as a warning:

* Remote repo entries that aren't in the bundled dictionary — keep prek installed for those, or reimplement the hook as a local `system` entry.
* Local hooks with toolchain-managed languages (`python`, `node`, `golang`, `rust`, `ruby`, `docker`, `pygrep`, ...).
* `types` entries that aren't in the runner's built-in pygments-derived extension map (`javascript`, `typescript`, `jsx`, `tsx`, `json`, `yaml`, `markdown`, `html`, `css`, `shell`, `toml`, `python`). The filter is still applied for supported types; unsupported ones are ignored with a warning.

TOML configs (`prek.toml`) are parsed via `@visulima/fs/toml` (which wraps `smol-toml`), so both formats work out of the box.

Commit `.vis/hooks/.builtins/` along with the rest of the hooks directory so teammates get the same runner and builtin implementations.

## Running hooks manually [#running-hooks-manually]

Hooks don't only fire at commit time. `vis hook run` replays the same stage script against any file set, which is handy for CI and for one-off checks:

```bash
vis hook run pre-commit                                 # default — staged files
vis hook run pre-commit --all-files                     # everything tracked by git
vis hook run pre-commit --from-ref=main --to-ref=HEAD   # files changed between refs
vis hook run pre-commit --last-commit                   # shortcut for --from-ref HEAD~1 --to-ref HEAD
```

These flags map to env vars (`VIS_HOOK_ALL_FILES`, `VIS_HOOK_FROM_REF`, `VIS_HOOK_TO_REF`) that the bundled runner picks up to swap `git diff --cached` for `git ls-files` or `git diff <from> <to>`. `--all-files` takes precedence if combined with a ref-range flag.

## Listing + validating hooks [#listing--validating-hooks]

* `vis hook list` — prints each stage's hook blocks with their first command line. Useful when you forget what's installed.
* `vis hook validate` — checks `core.hooksPath`, dispatcher scripts, per-stage shell syntax (`sh -n`), executable bits, and the bundled runner (`node --check`) if any script references it. Exits non-zero on errors.

## Disabling Hooks [#disabling-hooks]

Temporarily disable hooks using the environment variable:

```bash
VIS_GIT_HOOKS=0 git commit -m "skip hooks"
```

For debugging hook issues:

```bash
VIS_GIT_HOOKS=2 git commit -m "debug hooks"
```

## Skipping hooks in CI [#skipping-hooks-in-ci]

Automated commits in CI — release bots bumping versions, merge commits, changelog updates — shouldn't re-run your local hooks. The same checks (commitlint, secret scanning, lint-staged) usually run as dedicated CI jobs already, so firing them again on a generated commit just trips the pipeline (a release commit failing `commitlint` is the classic case).

Set `skipInCI` in `.vis/hooks/config.json` to skip **all** hooks whenever a non-empty `CI` environment variable is present (every major CI provider sets it):

```json
{
    "version": 1,
    "skipInCI": true,
    "stages": {}
}
```

```bash
vis hook install   # regenerate the dispatcher so the guard takes effect
```

`vis hook install` bakes the guard into the generated `_/` dispatcher, so it fires **before the hook body runs** — even for a hook that calls a tool directly (e.g. a raw `commitlint` `commit-msg`) instead of going through `vis hook run`. Because it lives in the dispatcher, &#x2A;*re-run `vis hook install` after changing `skipInCI`** to regenerate it.

Need hooks to run in one specific CI job (say, a lint job that *wants* commitlint)? Force them back on for that job only:

```bash
VIS_GIT_HOOKS=1 git commit -m "feat: …"   # overrides skipInCI
```

This is the portable, repo-tracked equivalent of setting `core.hooksPath=/dev/null` in a single job — `skipInCI` is the default for CI, `VIS_GIT_HOOKS=1` is the per-job exception, and both travel with the repo.

## Common Hook Recipes [#common-hook-recipes]

### Lint Staged Files [#lint-staged-files]

```bash
#!/bin/sh
# .vis/hooks/pre-commit
pnpm run lint-staged
```

### Validate Commit Messages [#validate-commit-messages]

```bash
#!/bin/sh
# .vis/hooks/commit-msg
pnpm run commitlint --edit "$1"
```

### Run Type Checks Before Push [#run-type-checks-before-push]

```bash
#!/bin/sh
# .vis/hooks/pre-push
pnpm run typecheck
```

### Check Dependencies Before Commit [#check-dependencies-before-commit]

```bash
#!/bin/sh
# .vis/hooks/pre-commit
vis check --exit-code --format minimal || {
  echo "Outdated dependencies detected. Run 'vis check' for details."
  exit 1
}
```

## Uninstalling [#uninstalling]

To remove vis hooks and reset git's `core.hooksPath`:

```bash
vis hook uninstall
```


# Writing plugins (/docs/packages/vis/guides/plugins)



# Writing plugins [#writing-plugins]

vis plugins subscribe to typed hooks that fire at run, task, and cache boundaries. The plugin API is built on [`hookable`](https://github.com/unjs/hookable) — the same library Nuxt uses — so plugins are small, async-friendly, and composable.

## Quick start [#quick-start]

```typescript
// vis.config.ts
import { defineConfig, definePlugin } from "@visulima/vis/config";

const timingPlugin = definePlugin({
    name: "timing-logger",
    hooks: {
        "task:after": (task, result) => {
            const duration = result.endTime! - result.startTime!;

            console.log(`${task.id}: ${duration}ms`);
        },
    },
});

export default defineConfig({
    plugins: [timingPlugin],
});
```

Running `vis run build` now logs each task's duration as it finishes.

## Hook reference [#hook-reference]

Each hook is awaited sequentially; returning a promise blocks the next hook firing until it resolves.

### `run:before(context)` [#runbeforecontext]

Fires once before any task in the graph starts. Good for one-off setup (fetching env, starting a local dependency, warming a cache).

```typescript
definePlugin({
    name: "docker-up",
    hooks: {
        "run:before": async () => {
            await execa("docker", ["compose", "up", "-d"]);
        },
    },
});
```

Throwing from `run:before` aborts the entire run — nothing in the task graph executes.

### `run:after(results)` [#runafterresults]

Fires once after all tasks complete, regardless of success or failure. `results` is a `Map<taskId, TaskResult>`.

```typescript
definePlugin({
    name: "metrics",
    hooks: {
        "run:after": async (results) => {
            const failed = [...results.values()].filter((r) => r.status === "failure");

            await metricsClient.recordRun({
                total: results.size,
                failed: failed.length,
                failedTasks: failed.map((r) => r.task.id),
            });
        },
    },
});
```

### `task:before(task)` [#taskbeforetask]

Fires right before each task's command executes — after scheduling, before the executor spawns the process.

### `task:after(task, result)` [#taskaftertask-result]

Fires after each task completes (success, failure, cache hit). Receives the final `TaskResult`.

### `task:cacheHit(task, result)` [#taskcachehittask-result]

Specialization of `task:after` — fires only when the task was served from local or remote cache.

### `task:cacheMiss(task, reason)` [#taskcachemisstask-reason]

Fires when auto-fingerprint cache diagnostics report a miss. `reason` is a human-readable string.

### `task:failure(task, result)` [#taskfailuretask-result]

Specialization of `task:after` — fires only when a task exited non-zero.

### `task:stdout(task, chunk)` / `task:stderr(task, chunk)` [#taskstdouttask-chunk--taskstderrtask-chunk]

Streaming hooks — fired with each output chunk as a running task emits it. Prefer these over `task:after` when shipping logs live (Slack, Datadog, S3 streaming):

```typescript
definePlugin({
    name: "datadog-logs",
    hooks: {
        "task:stdout": (task, chunk) => {
            ddLogger.info(chunk, { task: task.id, stream: "stdout" });
        },
        "task:stderr": (task, chunk) => {
            ddLogger.error(chunk, { task: task.id, stream: "stderr" });
        },
    },
});
```

These are fire-and-forget — handler errors are routed through the per-run error channel (warns by default) so a buggy plugin can't stall the executor's write loop.

### `task:retry(task, attempt, prevExitCode)` [#taskretrytask-attempt-prevexitcode]

Fires right before a failed task is re-spawned by the retry controller. `attempt` is 1-indexed and counts the retry that's about to start; `prevExitCode` is the failing exit status that triggered the retry.

```typescript
let budget = 10;

definePlugin({
    name: "retry-budget",
    hooks: {
        "task:retry": (task, attempt, prevExitCode) => {
            if (--budget < 0) {
                throw new Error(`Retry budget exhausted (last failure: ${task.id} → ${prevExitCode})`);
            }
        },
    },
});
```

The closure-scoped `budget` resets on every fresh `vis run` — for cross-invocation enforcement, persist the count to disk or a shared store inside the handler.

Throwing aborts the retry — the previous failure becomes the final result. Use this to gate retries on external state (rate-limit budgets, circuit breakers, deploy windows).

### `task:fingerprint(task, contributor)` [#taskfingerprinttask-contributor]

Fires during fingerprint construction, after built-in inputs (filesets, runtime, env) are gathered and **before** the cache lookup runs. Use it to mix arbitrary signals into the task hash — the contributor's calls are sorted and namespaced deterministically, so registration order doesn't change the resulting hash.

```typescript
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";

let workspaceRoot = process.cwd();

definePlugin({
    name: "schema-version",
    hooks: {
        // Cache the workspace root once; relative paths inside `task:fingerprint`
        // would resolve against the vis invocation's cwd, not the repo root.
        "run:before": ({ workspaceRoot: root }) => {
            workspaceRoot = root;
        },
        "task:fingerprint": async (task, contributor) => {
            // Bust cache when the GraphQL schema bumps, even though
            // the schema file isn't an explicit `inputs` entry.
            if (task.target.target !== "build") {
                return;
            }

            try {
                const schema = await readFile(resolve(workspaceRoot, "schemas/api.graphql"), "utf8");

                contributor.contribute("graphql-schema", schema);
            } catch (error) {
                // Throwing would fail every build task; treat a missing schema
                // as "no contribution" so unrelated tasks aren't held hostage.
                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
                    throw error;
                }
            }
        },
    },
});
```

Throwing aborts hashing for the offending task — the task fails before any cache read or write. This is intentional: a buggy plugin would otherwise silently corrupt cache state.

### `service:start(entry)` / `service:stop(entry)` / `service:attach(entry, taskIds)` [#servicestartentry--servicestopentry--serviceattachentry-taskids]

Fired around the long-lived service registry (`vis service start`, `vis service stop`, and the auto-attach that runs at the start of every `vis run`).

* **`service:start`** fires after a successful start and readiness probe.
* **`service:stop`** fires only when an alive entry was actually terminated (no-op stops don't fire it).
* **`service:attach`** fires once per satisfied service during `vis run`, after plugins are registered and before `run:before`. `taskIds` lists the in-graph dependents that consumed the service's `env` block.

```typescript
definePlugin({
    name: "service-tracker",
    hooks: {
        "service:start": (entry) => {
            metrics.gauge("vis.service.up", 1, { service: entry.id, slug: entry.slug });
        },
        "service:stop": (entry) => {
            metrics.gauge("vis.service.up", 0, { service: entry.id, slug: entry.slug });
        },
        "service:attach": (entry, taskIds) => {
            console.log(`[${entry.id}] → ${taskIds.length} dependent task(s): ${taskIds.join(", ")}`);
        },
    },
});
```

## Patterns [#patterns]

### Notifier on failure [#notifier-on-failure]

```typescript
definePlugin({
    name: "slack-on-failure",
    hooks: {
        "task:failure": async (task, result) => {
            if (!process.env.SLACK_WEBHOOK) {
                return;
            }

            await fetch(process.env.SLACK_WEBHOOK, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    text: `❌ \`${task.id}\` failed in ${process.env.CI_PROJECT_NAME}`,
                    attachments: [{ text: (result.terminalOutput ?? "").slice(-4000) }],
                }),
            });
        },
    },
});
```

### Conditional run gate [#conditional-run-gate]

```typescript
definePlugin({
    name: "block-release-without-changelog",
    hooks: {
        "run:before": async ({ tasks }) => {
            const hasRelease = tasks.some((t) => t.target.target === "release");

            if (!hasRelease) {
                return;
            }

            const { stdout } = await execa("git", ["log", "--name-only", "-1"]);

            if (!stdout.includes("CHANGELOG")) {
                throw new Error("Refusing to run release without a CHANGELOG update in HEAD");
            }
        },
    },
});
```

### Multiple handlers per hook [#multiple-handlers-per-hook]

Pass an array — both run in order:

```typescript
definePlugin({
    name: "multi",
    hooks: {
        "task:after": [(task) => console.log(`1st: ${task.id}`), (task) => console.log(`2nd: ${task.id}`)],
    },
});
```

### Imperative registration [#imperative-registration]

For `hookOnce`, `removeHook`, or `beforeEach`, use `setup`:

```typescript
definePlugin({
    name: "once",
    setup(hooks) {
        // Fire only on the first task, then auto-unregister.
        hooks.hookOnce("task:before", (task) => {
            console.log(`warming up for ${task.id}…`);
        });

        // beforeEach runs synchronously before every hook invocation.
        hooks.beforeEach((event) => {
            if (event.name.startsWith("task:")) {
                metrics.increment(`vis.hook.${event.name}`);
            }
        });
    },
});
```

## Authoring a reusable plugin [#authoring-a-reusable-plugin]

Publish a plugin as its own package with a factory function:

```typescript
// packages/vis-plugin-newrelic/src/index.ts
import type { VisPlugin } from "@visulima/vis/config";
import { definePlugin } from "@visulima/vis/config";

export interface NewRelicPluginOptions {
    apiKey: string;
    appName?: string;
}

export const newRelicPlugin = (options: NewRelicPluginOptions): VisPlugin =>
    definePlugin({
        name: "newrelic",
        hooks: {
            "task:after": async (task, result) => {
                // ship to New Relic…
            },
        },
    });
```

Consumers then:

```typescript
import { newRelicPlugin } from "vis-plugin-newrelic";

export default defineConfig({
    plugins: [newRelicPlugin({ apiKey: process.env.NEWRELIC_API_KEY! })],
});
```

## Execution order & error handling [#execution-order--error-handling]

* Plugins are registered in the order they appear in `config.plugins`.
* Handlers within a hook run in registration order, each awaited before the next.
* A handler that throws propagates out of `callHook` — if you don't want failure to abort the run, wrap the handler body in `try/catch`.
* `HookableLifeCycle` (the internal bridge) forwards task-level events from the task runner to plugins — plugin authors never need to touch the lower-level `LifeCycleInterface`.

## When to use plugins vs built-in options [#when-to-use-plugins-vs-built-in-options]

| Use-case                             | Prefer                        |
| ------------------------------------ | ----------------------------- |
| Skip a task unless `$CI` is set      | `when: "$CI"` target option   |
| Retry a flaky task 3 times           | `retryCount: 3` target option |
| Run `docker compose up` before build | Plugin — `run:before` hook    |
| Post to Slack on any failure         | Plugin — `task:failure` hook  |
| Stream metrics to Datadog            | Plugin — `task:after` hook    |
| Early-exit when no CHANGELOG change  | Plugin — `run:before` hook    |

Built-in options are stable, declarative, and appear in `vis list --json`. Plugins are strictly more powerful but require runtime to load and don't surface in static inspection. Reach for options first; graduate to a plugin when behavior can't be expressed declaratively.


# Release CI (/docs/packages/vis/guides/release-ci)



# Release CI [#release-ci]

This page walks you through wiring `vis release` into CI. Pair it with the [release guide](/docs/packages/vis/guides/release) for the mental model and the [commands reference](/docs/packages/vis/commands/release) for per-flag detail.

> 💡 &#x2A;*Don't write workflows by hand.** Run `vis release init --workflows` once. It writes the right files for your provider — `.github/workflows/vis-release{,-check,-snapshot}.yml` on GitHub or `.gitlab-ci.yml` on GitLab — and prints a follow-up checklist (`vis release ci setup`) for the secrets / OIDC trust pieces vis can't configure for you.

## Pick your setup [#pick-your-setup]

| Your situation                                          | Workflows to install                                                                     |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Stable releases on `main` + prereleases on `alpha`      | [A](#workflow-a-version-pr-on-main--next) + [B](#workflow-b-auto-publish-on-alpha--beta) |
| Stable releases only                                    | [A](#workflow-a-version-pr-on-main--next)                                                |
| Prereleases only (ship every push)                      | [B](#workflow-b-auto-publish-on-alpha--beta)                                             |
| Want PR review comments showing what's about to release | Add [C](#workflow-c-pr-sticky-comment)                                                   |
| Want installable previews from every PR                 | Add [D](#workflow-d-snapshot-previews-on-prs)                                            |

## How channels decide what CI does [#how-channels-decide-what-ci-does]

The `mode` in `release.channels.<name>.mode` decides what happens when CI runs on that branch:

| Mode           | Pending change files                                              | No pending change files                                             |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| `version-pr`   | Run `version` in a temp branch, force-push, open / update the PR. | Treat the push as the merged release-PR; publish + tag + push tags. |
| `auto-publish` | `version + publish + tag + push tags + create releases` inline.   | No-op (`Nothing to release`).                                       |

Typical channel layout:

```typescript
// vis.config.ts
export default {
    release: {
        channels: {
            main: { tag: "latest", mode: "version-pr" },
            next: { tag: "next", prerelease: "next", mode: "version-pr" },
            alpha: { tag: "alpha", prerelease: "alpha", mode: "auto-publish" },
            beta: { tag: "beta", prerelease: "beta", mode: "auto-publish" },
        },
    },
};
```

## Secrets and tokens [#secrets-and-tokens]

| Secret / env   | Used for                                                                                                                                                                                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GH_TOKEN`     | Comments, reads, and PR creation. On GitHub Actions, default to `${{ github.token }}`.                                                                                                                                                                                      |
| `VIS_GH_TOKEN` | Force-pushing the version-PR branch. **Required** for `version-pr` mode on GitHub — the default `github.token` is locked against recursion so it cannot trigger downstream workflows on the version-PR. Use a fine-grained PAT or a GitHub App token with `contents:write`. |
| `NPM_TOKEN`    | `npm publish`. Skip if you use OIDC trusted publishing (see below).                                                                                                                                                                                                         |
| `GITLAB_TOKEN` | GitLab adapter — used by `glab` for MR comments + release creation.                                                                                                                                                                                                         |
| `CI_JOB_TOKEN` | GitLab — pushes back to the project via the `oauth2:$CI_JOB_TOKEN@…` URL.                                                                                                                                                                                                   |

Run `vis release ci setup` to see the exact list for your provider.

## OIDC trusted publishing [#oidc-trusted-publishing]

npm trusted publishing skips long-lived registry tokens. Each package opts in via its npm settings page; CI claims an OIDC ID token at publish time and exchanges it for a one-shot registry credential.

> 💡 &#x2A;*Use it.** Long-lived `NPM_TOKEN` secrets are the most common credential leak in npm-publishing CI setups. OIDC tokens last seconds and bind to the workflow that issued them.

GitHub Actions — give the publish job `id-token: write`:

```yaml
permissions:
    contents: write
    id-token: write
    pull-requests: write
```

GitLab CI — the same idea via `id_tokens`:

```yaml
release:
    id_tokens:
        SIGSTORE_ID_TOKEN:
            aud: sigstore
    script:
        - pnpm exec vis release ci release
```

`vis release doctor` reports the OIDC sub claim it sees and which packages on the registry are configured to trust it.

## GitHub Actions [#github-actions]

### Workflow A — version-PR on main / next [#workflow-a--version-pr-on-main--next]

**What you get.** Push to `main&#x60; with pending change files → CI opens or updates a **"Versioned release" PR** with the version bumps applied. Merge that PR → CI publishes, pushes tags, and creates GitHub releases.

```yaml
# .github/workflows/vis-release.yml
name: vis release

on:
    push:
        branches: [main, next]
    workflow_dispatch:

# Serialise releases per branch — a second push queues behind the first.
concurrency:
    group: vis-release-${{ github.ref }}
    cancel-in-progress: false

permissions:
    contents: write
    id-token: write
    pull-requests: write

jobs:
    release:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  # VIS_GH_TOKEN lets the version-PR branch push trigger
                  # downstream workflows. The default github.token is locked
                  # against workflow recursion.
                  token: ${{ secrets.VIS_GH_TOKEN || github.token }}
                  persist-credentials: false

            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: "22"
                  cache: pnpm

            - run: pnpm install --frozen-lockfile
            - run: pnpm run build:packages:prod

            - run: pnpm exec vis release ci release
              env:
                  GH_TOKEN: ${{ github.token }}
                  VIS_GH_TOKEN: ${{ secrets.VIS_GH_TOKEN || github.token }}
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
                  GIT_AUTHOR_NAME: "vis-release-bot"
                  GIT_AUTHOR_EMAIL: "vis-release-bot@users.noreply.github.com"
                  GIT_COMMITTER_NAME: "vis-release-bot"
                  GIT_COMMITTER_EMAIL: "vis-release-bot@users.noreply.github.com"
```

### Workflow B — auto-publish on alpha / beta [#workflow-b--auto-publish-on-alpha--beta]

**What you get.** Every push to `alpha` or `beta` with pending change files publishes immediately. No PR review gate. Best for fast-iterating prereleases.

The channel `mode` in `vis.config.ts` is what actually picks the path — `--auto-publish` is only needed if you want to override a `version-pr` channel from the CLI. Most teams set the mode in config (see [How channels decide what CI does](#how-channels-decide-what-ci-does)) and run the same `vis release ci release` command on every branch.

```yaml
# .github/workflows/vis-release-prerelease.yml
name: vis release prerelease

on:
    push:
        branches: [alpha, beta]

concurrency:
    group: vis-release-${{ github.ref }}
    cancel-in-progress: false

permissions:
    contents: write
    id-token: write

jobs:
    release:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  persist-credentials: false

            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: "22"
                  cache: pnpm

            - run: pnpm install --frozen-lockfile
            - run: pnpm run build:packages:prod

            - run: pnpm exec vis release ci release
              env:
                  GH_TOKEN: ${{ github.token }}
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

### Workflow C — PR sticky-comment [#workflow-c--pr-sticky-comment]

**What you get.** Every PR targeting `main` or `next` gets a sticky comment summarising the release plan. Reviewers see exactly what's about to ship before approving.

```yaml
# .github/workflows/vis-release-check.yml
name: vis release check

on:
    pull_request:
        types: [opened, synchronize, reopened]

permissions:
    contents: read
    pull-requests: write

jobs:
    check:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  persist-credentials: false
            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: "22"
                  cache: pnpm
            - run: pnpm install --frozen-lockfile
            - run: pnpm exec vis release ci check
              env:
                  GH_TOKEN: ${{ github.token }}
```

### Workflow D — snapshot previews on PRs [#workflow-d--snapshot-previews-on-prs]

**What you get.** Every PR publishes ephemeral `0.0.0-pr-<n>-<sha>` versions of affected packages. The PR gets a sticky comment with `pnpm add @scope/pkg@pr-<n>` snippets. Closes the PR → snapshots are cleaned up (GitHub only; pkg-pr-new GCs by TTL otherwise).

```yaml
# .github/workflows/vis-release-snapshot.yml
name: vis release snapshot

on:
    pull_request:
        types: [opened, synchronize, reopened, closed]

concurrency:
    group: vis-release-snapshot-${{ github.event.pull_request.number }}
    cancel-in-progress: true

permissions:
    contents: read
    id-token: write
    pull-requests: write

jobs:
    snapshot:
        if: github.event.action != 'closed'
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  persist-credentials: false
            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: "22"
                  cache: pnpm
            - run: pnpm install --frozen-lockfile
            - run: pnpm run build:packages:prod
            - run: pnpm exec vis release ci snapshot
              env:
                  GH_TOKEN: ${{ github.token }}
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

    cleanup:
        if: github.event.action == 'closed'
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  persist-credentials: false
            - uses: pnpm/action-setup@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: "22"
                  cache: pnpm
            - run: pnpm install --frozen-lockfile
            - run: pnpm exec vis release ci snapshot --on-close
              env:
                  GH_TOKEN: ${{ github.token }}
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

### Workflow E — gating downstream steps on the plan [#workflow-e--gating-downstream-steps-on-the-plan]

Use `vis release ci plan` when a later step needs to know whether anything is about to release.

```yaml
- id: plan
  run: pnpm exec vis release ci plan
  env:
      GH_TOKEN: ${{ github.token }}

- if: steps.plan.outputs.packages != ''
  run: pnpm run prepare-release-notes
```

`vis release ci plan` writes `{ mode, packages, json }` to `$GITHUB_OUTPUT` and emits the JSON plan on stdout.

## GitLab CI [#gitlab-ci]

vis treats GitHub and GitLab the same — same commands, same modes, same secrets model. The remote adapter (`src/release/core/remote/gitlab.ts`) handles PR / MR upserts, sticky comments, and release creation via `glab`.

Point `glab` at the right host by setting `release.gitlabHost` in `vis.config.ts` (or `GITLAB_HOST` via `$CI_SERVER_HOST` for self-hosted).

```yaml
# .gitlab-ci.yml
stages: [build, release]

variables:
    NODE_VERSION: "24"

.node:
    image: node:${NODE_VERSION}
    cache:
        key: ${CI_COMMIT_REF_SLUG}-pnpm
        paths: [.pnpm-store]
    before_script:
        - corepack enable
        - pnpm config set store-dir .pnpm-store
        - pnpm install --frozen-lockfile

build:
    extends: .node
    stage: build
    script:
        - pnpm run build:packages:prod
    artifacts:
        paths: [packages/**/dist]

release:
    extends: .node
    stage: release
    needs: [build]
    rules:
        - if: $CI_COMMIT_BRANCH == "main"
        - if: $CI_COMMIT_BRANCH == "next"
        - if: $CI_COMMIT_BRANCH == "alpha"
        - if: $CI_COMMIT_BRANCH == "beta"
    id_tokens:
        NPM_ID_TOKEN:
            aud: npm:registry.npmjs.org
    variables:
        # `glab` honours these natively
        GITLAB_TOKEN: $CI_JOB_TOKEN
        GITLAB_HOST: $CI_SERVER_HOST
    script:
        - pnpm exec vis release ci release
```

For MR-equivalent snapshot previews, gate on `$CI_PIPELINE_SOURCE == "merge_request_event"`:

```yaml
snapshot:
    extends: .node
    stage: release
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    script:
        - pnpm exec vis release ci snapshot
```

> ⚠ &#x2A;*`--on-close` cleanup is GitHub-only.** The cleanup path enumerates the closed PR's commits via `gh api`. On GitLab, snapshots clean themselves up via the [pkg-pr-new](https://pkg-pr-new.com) TTL.

vis surfaces `glab`'s output verbatim with npm / GitHub / GitLab token patterns redacted to `[REDACTED]` in every log mode, so any GitLab-specific errors land in the job log unchanged.

### Self-hosted GitLab [#self-hosted-gitlab]

Set `release.gitlabHost` once in `vis.config.ts`, or rely on the `GITLAB_HOST` env var that GitLab CI sets via `$CI_SERVER_HOST`:

```typescript
export default {
    release: {
        provider: "gitlab",
        gitlabHost: "gitlab.acme.com",
    },
};
```

vis threads this through every `glab` invocation, so MR comments + releases land on the right instance.

## Pre-publish guards [#pre-publish-guards]

The `release.publish.guards` block runs after `pack` but before `publish` — see the [security audit guide](/docs/packages/vis/guides/security-audit) for the full menu (`packSecretScan`, `exportsExist`, `lifecycleScripts`, `audit`, `releaseAssets`). Guards are evaluated inline in every CI mode; failures abort the publish for the offending package only.

## Recovering from failures [#recovering-from-failures]

`vis release publish` pushes tags atomically and then creates a release per tag (or one aggregate release when `release.aggregateRelease.enabled`). If `git push --tags` fails or the workflow dies mid-publish, vis leaves a state file in place so the next run picks up where it left off.

Typical recovery flow:

1. **Inspect the failed job** — vis prints the offending package and step.
2. **Re-run with the same revision** — `--resume` is implicit in `vis release ci release` when a state file exists; already-published packages are skipped.
3. **If the tag exists upstream but the publish failed,** vis surfaces a `TAG_COLLISION` error pointing at the upstream tag. Delete it and re-run, or pin the existing tag's SHA if the work is salvageable.

## Troubleshooting [#troubleshooting]

**The Versioned release PR never appears.**
You're probably on `version-pr` mode without `VIS_GH_TOKEN`. Default `GITHUB_TOKEN` can read but can't trigger downstream workflows; vis aborts force-push if it detects this case. Set `VIS_GH_TOKEN` to a PAT or GitHub App token with `contents:write`.

**`vis release publish` says "nothing to publish".**
You're on a `version-pr` branch with no consumed change files yet. The publish path only runs after the version-PR has been merged. Check `vis release status` — if you see pending change files, you need to merge the version-PR first.

**OIDC auth fails with "audience mismatch".**
GitHub Actions: `aud` should be `npm:registry.npmjs.org` for npm trusted publishing. GitLab: same audience via the `id_tokens` block. Run `vis release doctor` to see the audience vis is requesting.

**Snapshot publishes succeed but the sticky comment never appears.**
The publish path doesn't require a remote token, but the comment does. Check `GH_TOKEN` (GitHub) or `GITLAB_TOKEN` (GitLab) is in the job env. vis logs a `WARN upsertStickyComment failed` line when this happens.

**Releases don't trigger on tag push.**
vis pushes tags atomically with `git push --atomic --tags` — if any single tag is rejected, the whole batch is rejected. Check the workflow log for the rejected tag (usually a collision with an existing tag).

## Where to next [#where-to-next]

* [Release guide](/docs/packages/vis/guides/release) — mental model, change files, channels
* [Commands reference](/docs/packages/vis/commands/release) — per-flag detail for every release subcommand
* [Release comparison](/docs/packages/vis/guides/release-comparison) — vs changesets / semantic-release / release-please
* [Security audit guide](/docs/packages/vis/guides/security-audit) — pre-publish gates in depth


# Release comparison (/docs/packages/vis/guides/release-comparison)



# Release comparison [#release-comparison]

`vis release` borrows the best parts of a handful of well-known tools:

* **changesets'** authoring model — hand-curated change files reviewed in PRs.
* **semantic-release's** CI integration — channels, dist-tags, automated publishing.
* **bumpy's** strict trust model for custom commands — no implicit shell injection surface.
* And adds first-class snapshot previews, in-CLI integration, NAPI sidecar support, and a workspace-wide planner.

This page lays out the tradeoffs against the four most-asked-about alternatives.

> 💡 &#x2A;*In a hurry? Skip to [When to pick what](#when-to-pick-what).**

## At a glance [#at-a-glance]

| Feature                                                  | vis release                                                                                                                                                | changesets                  | semantic-release                                                                                 | release-please            | bumpy                                                                                      |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| Authoring model                                          | Change files                                                                                                                                               | Change files                | Commit-message convention                                                                        | Commit-message convention | Change files                                                                               |
| Monorepo aware                                           | ✅ first-class (cf. semantic-release [#193](https://github.com/semantic-release/semantic-release/issues/193): 330 reactions, 157 comments, open since 2016) | ✅ first-class               | ⚠ via multi-semantic-release                                                                     | ✅                         | ✅                                                                                          |
| Independent versioning is the default (not a retrofit)   | ✅ since day 1                                                                                                                                              | ✅                           | ❌ (see [#193](https://github.com/semantic-release/semantic-release/issues/193))                  | ⚠ partial                 | ⚠ recent v22 regressions ([nx#34211](https://github.com/nrwl/nx/issues/34211) and related) |
| First-class TypeScript types (CLI + plugin API)          | ✅ TS-first; typed plugin API                                                                                                                               | ⚠ partial (DefinitelyTyped) | ❌ (see [#952](https://github.com/semantic-release/semantic-release/issues/952), open since 2018) | ⚠ partial                 | ✅ (nx release)                                                                             |
| Independent versioning                                   | ✅                                                                                                                                                          | ✅                           | ✅                                                                                                | ✅                         | ✅                                                                                          |
| Fixed / linked groups                                    | ✅                                                                                                                                                          | ✅                           | ❌                                                                                                | ❌                         | ✅                                                                                          |
| Cascade rules (cross-package)                            | ✅                                                                                                                                                          | ⚠ limited                   | ❌                                                                                                | ❌                         | ✅                                                                                          |
| Version-PR mode                                          | ✅                                                                                                                                                          | ✅                           | ❌                                                                                                | ✅                         | ✅                                                                                          |
| Auto-publish mode                                        | ✅                                                                                                                                                          | ⚠ via 3rd-party action      | ✅                                                                                                | ❌                         | ✅                                                                                          |
| Snapshot / PR-preview publishing                         | ✅ (pkg-pr-new + registry)                                                                                                                                  | ⚠ via snapshots action      | ❌                                                                                                | ❌                         | ✅                                                                                          |
| Channels (per-branch dist-tag)                           | ✅                                                                                                                                                          | ⚠ workarounds               | ✅                                                                                                | ⚠                         | ✅                                                                                          |
| Maintenance branches (`1.x`)                             | ✅ (`range: "match"`)                                                                                                                                       | ⚠ manual                    | ✅                                                                                                | ❌                         | ✅                                                                                          |
| NAPI / native sidecar packages                           | ✅ (`versionActions: "native-addon"`)                                                                                                                       | ❌                           | ⚠ custom plugin                                                                                  | ❌                         | ✅                                                                                          |
| Pre-publish guards (secrets, audit)                      | ✅ built-in                                                                                                                                                 | ⚠ external                  | ⚠ via plugins                                                                                    | ❌                         | ✅                                                                                          |
| Trust gate for custom commands                           | ✅ (`allowCustomCommands`)                                                                                                                                  | ❌                           | ❌                                                                                                | ❌                         | ✅                                                                                          |
| OIDC / trusted publishing                                | ✅                                                                                                                                                          | ✅                           | ✅                                                                                                | ✅                         | ✅                                                                                          |
| Trusted-publishing bootstrap (placeholder + `npm trust`) | ✅ (`vis release pretrust`)                                                                                                                                 | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| Implicit (heading-depth) changelogs                      | ✅                                                                                                                                                          | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| Replay changelogs (re-emit at a future milestone)        | ✅                                                                                                                                                          | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| Shared group tag + aggregate release (`syncGitTag`)      | ✅                                                                                                                                                          | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| Lifecycle plugins (`willPublish` / `afterPublish` …)     | ✅                                                                                                                                                          | ⚠ limited                   | ✅                                                                                                | ❌                         | ⚠                                                                                          |
| Git-tracked publish lock (ephemeral-runner resume)       | ✅ (`publish.lockInGit`)                                                                                                                                    | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| `await using` draft (programmatic apply-on-dispose)      | ✅                                                                                                                                                          | ❌                           | ❌                                                                                                | ❌                         | ❌                                                                                          |
| Migration tooling                                        | ✅ (`vis release init`)                                                                                                                                     | —                           | —                                                                                                | —                         | —                                                                                          |

### Inspection & dry-run [#inspection--dry-run]

How easy is it to see what *would* happen before you cut a release? semantic-release [#753](https://github.com/semantic-release/semantic-release/issues/753), [#1647](https://github.com/semantic-release/semantic-release/issues/1647), [#2232](https://github.com/semantic-release/semantic-release/issues/2232) ("dry-run shouldn't test push permissions"), [#1890](https://github.com/semantic-release/semantic-release/issues/1890) ("dry-run does nothing useful") and changesets [#614](https://github.com/changesets/changesets/issues/614) are all open issues asking for this — vis ships it out of the box.

| Capability                                       | vis release                  | changesets              | semantic-release                                                              | release-please |
| ------------------------------------------------ | ---------------------------- | ----------------------- | ----------------------------------------------------------------------------- | -------------- |
| Print next version without publishing            | ✅ `vis release next-version` | ⚠ via `status --output` | ⚠ `--dry-run` (noisy)                                                         | ⚠ from PR body |
| Render release notes / changelog preview         | ✅ `vis release changelog`    | ❌                       | ⚠ `--dry-run`                                                                 | ⚠ from PR body |
| Inspect the plan (JSON + interactive)            | ✅ `vis release plan`         | ⚠ `status`              | ❌                                                                             | ❌              |
| Human-readable status table                      | ✅ `vis release status`       | ✅ `status`              | ❌                                                                             | ❌              |
| `--dry-run` available per command                | ✅                            | ⚠ partial               | ✅                                                                             | ❌              |
| Dry-run / preview works without push credentials | ✅ read-only by design        | ✅                       | ❌ ([#2232](https://github.com/semantic-release/semantic-release/issues/2232)) | ✅              |

> 📝 &#x2A;*Note:** vis's `plan`, `next-version`, `changelog`, and `status` are read-only by design — they run from any branch (including PRs from forks) without push credentials, so contributors can preview a release locally.

### Forges [#forges]

Where can the version-PR and tag/release creation live? Tracks changesets [#879](https://github.com/changesets/changesets/issues/879) and release-please [#1021](https://github.com/googleapis/release-please/issues/1021).

| Forge             | vis release                               | changesets | semantic-release | release-please |
| ----------------- | ----------------------------------------- | ---------- | ---------------- | -------------- |
| GitHub            | ✅                                         | ✅          | ✅                | ✅              |
| GitLab            | ✅ (`provider: "gitlab"` + `glab` adapter) | ❌          | ✅                | ❌              |
| Bitbucket / Gitea | ❌                                         | ❌          | ✅ (Gitea)        | ❌              |

### Registries [#registries]

Which package registries can each tool publish to natively?

| Registry             | vis release                                          | changesets                                                            | semantic-release    | release-please |
| -------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- | ------------------- | -------------- |
| npm                  | ✅                                                    | ✅                                                                     | ✅                   | ⚠ via wiring   |
| JSR (Deno)           | ✅ (`versionActions: "jsr"`)                          | ❌ (see [#1318](https://github.com/changesets/changesets/issues/1318)) | ⚠ via custom plugin | ❌              |
| Maven (JVM packages) | ✅ ([guide](/docs/packages/vis/guides/release-maven)) | ❌                                                                     | ⚠ via custom plugin | ⚠ partial      |
| Native addons (NAPI) | ✅ (auto-detected via `napi` field)                   | ❌                                                                     | ⚠ custom plugin     | ❌              |

### Commit-history hygiene [#commit-history-hygiene]

Tracks release-please [#296](https://github.com/googleapis/release-please/issues/296) (open and `needs design` since 2020).

| Capability                                             | vis release                                                                                                                                                                                                                           | changesets              | semantic-release        | release-please |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------- | -------------- |
| Reverted commits dropped from version calc / changelog | ✅ handles `revert: <subject>`, `Revert "<subject>"`, and revert-of-revert chains ([`conventional-commits.ts`](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/release/core/generate/conventional-commits.ts)) | N/A (no commit parsing) | ⚠ relies on each plugin | ❌              |

### Lockfile sync [#lockfile-sync]

Tracks changesets [#1139](https://github.com/changesets/changesets/issues/1139) (lockfile not updated after `version`).

| Capability                                    | vis release                                                                                  | changesets | semantic-release | release-please |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- | ---------------- | -------------- |
| Automatic lockfile refresh after version bump | ✅ via [`postVersionCommand`](/docs/packages/vis/guides/release#keeping-the-lockfile-in-sync) | ❌          | ⚠ via plugin     | ❌              |

### Post-release notifications [#post-release-notifications]

Once a wave publishes, vis walks every PR / issue referenced in the changelog entries and posts a sticky "released in X.Y.Z" comment plus a `released` label. Tracks release-it [#1119](https://github.com/release-it/release-it/issues/1119) and mirrors semantic-release's `successComment` + `releasedLabels`.

| Capability                                                          | vis release                             | changesets | semantic-release | release-please |
| ------------------------------------------------------------------- | --------------------------------------- | ---------- | ---------------- | -------------- |
| Comment on every shipped issue / PR                                 | ✅ via success-walk (sticky, idempotent) | ❌          | ✅ via plugin     | ⚠ via PR body  |
| Add `released` label                                                | ✅                                       | ❌          | ✅ via plugin     | ❌              |
| Cross-repo URL guardrail (won't comment on pasted competitor links) | ✅                                       | n/a        | ❌                | n/a            |

## vs. changesets [#vs-changesets]

**Same DNA.** Change files in `.vis/release/*.md` are frontmatter-compatible with `.changeset/*.md` — `vis release init` copies the directory verbatim.

**Where vis goes further**

* **Channels.** changesets has no native concept of branch → dist-tag mapping; you wire it up with `@changesets/cli pre enter` + `pre exit`, or sidestep with a custom action. vis treats channels as a first-class config and resolves them via branch detection.
* **Snapshots.** changesets has snapshots, but they require a separate command and external action wiring. vis includes both the snapshot command and the CI driver, and supports the [pkg-pr-new](https://pkg-pr-new.com) backend natively.
* **Cascade rules.** changesets' dep-bump rules apply only to `out-of-range` updates; vis lets you configure per-dep-kind triggers (`{ trigger, bumpAs }`) and source-side `cascadeTo` blocks for cross-package fan-out.
* **Trust model for custom commands.** changesets executes whatever `publishConfig.publishCommand` you set. vis requires explicit opt-in via `allowCustomCommands` and shell-quotes every interpolated value to make injection impossible.

**Where changesets wins**

* Ecosystem maturity — more existing plugins and Stack Overflow answers.
* Public Slack + steady-state release cadence.

## vs. semantic-release [#vs-semantic-release]

**Different philosophy.** semantic-release derives bumps from commit messages (conventional-commits). vis derives bumps from change files. Both have champions; the practical difference is review surface area:

* With conventional-commits, the release is implied by the commits in the PR — there's nothing extra to review.
* With change files, the release is an artefact in the PR — explicit, diff-able, and easy to override.

vis can still derive change files from commits: `vis release generate` parses conventional-commits when present and falls back to a path-based heuristic.

**Where vis goes further**

* **Monorepo support.** `multi-semantic-release` exists, but it's a wrapper that re-runs the whole pipeline per package. vis treats the workspace as the unit and plans the whole wave in one pass.
* **Version-PR mode.** semantic-release publishes inline; there's no review gate.
* **Snapshots.** semantic-release has no built-in PR-preview pathway.
* **Pre-publish guards.** vis bakes in the secret scanner, exports-exist check, lifecycle-script gate, and `npm audit` integration. With semantic-release you assemble these from plugins.

**Where semantic-release wins**

* The "your commits are your spec" philosophy is hard to beat if you already enforce conventional-commits strictly.
* More forge integrations (GitHub, GitLab, Gitea, Bitbucket).

## vs. release-please [#vs-release-please]

**Different scope.** release-please is Google's PR-bot. It maintains a rolling release-PR (the "Release Please PR") whose body is the changelog preview, and on merge it tags + creates a GitHub release. It does **not** publish to npm — that's a separate step you wire up after.

**Where vis overlaps**

* Both maintain a rolling version-PR (vis calls it the "Versioned release" PR).
* Both write CHANGELOG entries from a deterministic source (release-please from commits; vis from change files).

**Where vis goes further**

* **Publishing is bundled.** vis's `ci release` covers the whole pipeline — version-PR maintenance, publish on merge, tag push, release creation. release-please stops at the tag.
* **Snapshots.** Not in release-please's scope.
* **Workspace-wide planning.** release-please handles monorepos via a `release-type: node-yoshi-multi` manifest; vis treats fixed / linked groups and cascade rules as primary config.

**Where release-please wins**

* Multi-language. release-please supports Java, Python, Rust, Go, Ruby, … vis is JS / TypeScript only.
* Used at massive scale by Google's OSS projects, so the edge cases are well-trodden.

## vs. bumpy [#vs-bumpy]

**Same lineage.** vis release is the in-tree successor to `bumpy` — the change-file shape, the trust gate (`allowCustomCommands`), the channels model, and the NAPI publishing strategy are all carried over. `vis release init` migrates a bumpy repo with a directory rename.

**Where vis differs**

* **First-party in the vis CLI.** No separate install / config; release is one of the verbs.
* **Updated dep bumps.** vis uses `out-of-range` semantics by default (the same as nx / changesets ≥2.27).
* **Tighter CI integration.** `vis release ci release`, `ci snapshot`, `ci check`, `ci plan`, and `ci setup` are first-party CLI commands rather than runner scripts.
* **Programmatic API.** Importing `@visulima/vis/release` exposes the full release pipeline as a TypeScript API (`releaseVersion`, `releasePublish`, `releaseSnapshot`, …).

## When to pick what [#when-to-pick-what]

| Your situation                                                                | Pick                                                                              |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Conventional-commits is the source of truth, and you like it that way**     | semantic-release — or `vis release generate` if you want change files as artefact |
| **Multi-language monorepo (JS + Python + Rust + …)**                          | release-please                                                                    |
| **JS/TS monorepo with established changesets workflow that works fine**       | changesets — no reason to switch                                                  |
| **JS/TS monorepo with cascade rules, NAPI sidecars, or PR snapshot previews** | vis release                                                                       |
| **Coming from bumpy**                                                         | vis release — same DNA, first-party in the vis CLI, `vis release init` migrates   |
| **You want one tool that does releases + tasks + caching + everything else**  | vis release (you're already on vis)                                               |

## Migration [#migration]

`vis release init` auto-detects an existing tool and previews the migration in place. Re-run with `--apply` once you're happy with the preview to actually write the files:

```bash
vis release init                                  # Auto-detect; preview only
vis release init --from-changesets                # Force changesets migration; preview
vis release init --from-semantic-release          # Force semantic-release migration; preview
vis release init --from-bumpy                     # Force bumpy migration; preview
vis release init --from-semantic-release --apply  # Actually perform the writes
vis release init --fresh                          # Skip migration; start clean
vis release init --dry-run                        # Print what would happen and exit
vis release init --workflows                      # Scaffold CI workflows too
```

Migration paths:

* **changesets** — copies `.changeset/*.md` → `.vis/release/*.md` (frontmatter-compatible).
* **semantic-release** / **multi-semantic-release** — extracts `branches` from `.releaserc` into `release.channels`, removes the dependency.
* **bumpy** — directory rename, same shape.

`init` also adds `"vis-release": { "managed": true }` to each detected publishable package's `package.json`. See the [release guide](/docs/packages/vis/guides/release) and [CI guide](/docs/packages/vis/guides/release-ci) for next steps.


# First-release & version resolver (/docs/packages/vis/guides/release-first-release-and-resolver)



# First release and current-version resolver [#first-release-and-current-version-resolver]

Every release tool needs an answer to one question: &#x2A;*what version is this package on right now?** The answer drives the diff that produces the next version. Get it wrong and you ship `1.0.0` over the top of an existing `1.5.3` — the kind of regression a registry will accept (semver does not enforce monotonicity) and your users will never forgive.

vis exposes two knobs that together answer that question precisely:

* `currentVersionResolver` — the **mode** for looking up `oldVersion`. Three options: `"disk"` (default), `"registry"`, `"git-tag"`.
* `--first-release` — the **bootstrap escape hatch** for greenfield monorepos that do not yet have any of those sources to consult.

This guide covers both, starting with the bootstrap problem and then drilling into the three resolver modes.

## The greenfield problem [#the-greenfield-problem]

Imagine the very first time you run `vis release version` on a brand-new monorepo:

* No git tags yet (you have not shipped anything).
* No published versions on npm / cargo / PyPI (likewise).
* Maybe `package.json` says `"version": "0.0.0"` from `pnpm init`, or maybe it says `"1.0.0"` because the team picked that as the first release.

In `"disk"` mode (the default), vis happily reads `package.json#version` and uses that as the baseline — no problem. But the moment you flip to `"registry"` or `"git-tag"` to align with your team's source of truth, every package falls back with a warning:

```
currentVersionResolver (registry): registry returned no version for @scope/cerebro
  (likely a 404 / not-yet-published); falling back to manifest version 1.0.0.
```

That fallback is **safe** — vis never throws on a missing baseline, it just uses the manifest — but it produces a wall of warnings the operator has to mentally suppress on every greenfield bootstrap. And the warnings hide real problems: a typo in `releaseTagPattern`, a misconfigured registry URL, an off-by-one in the workspace's package list. You want those visible. So vis ships an explicit flag:

```bash
vis release version --first-release
vis release publish --first-release
```

`--first-release` does three things:

1. **Forces `currentVersionResolver` to `"disk"`** for every package in this run, regardless of workspace or per-package config. The bootstrap path cannot query a registry / tag history that does not exist yet.
2. **Skips remote tag-collision checks** during the version phase. A `git ls-remote --tags` check that would normally refuse a tag that already exists on the remote is bypassed — on the first release, "the remote has no matching tags" is the whole point.
3. **Triggers a doctor preflight** (`first-release.repo-not-greenfield`) that refuses to proceed if the workspace is **not** actually greenfield.

That third item is the safety net. Without it, an operator could pass `--first-release` on a year-old monorepo and double-bump every package — a data-loss bug. The preflight scans for:

* Any git tag matching any configured `releaseTagPattern` (workspace-level or per-package).
* Any package that has a non-empty `readPublishedVersion()` result via its `versionActions` — npm, cargo, PyPI, Maven Central, container registries are all probed.

If either finds anything, the doctor fails hard:

```
[fail] first-release.repo-not-greenfield (error)
       --first-release is set but the workspace is NOT greenfield:
       Found 12 git tag(s) matching "{name}@{version}":
       @scope/a@1.0.0, @scope/b@2.0.0 (+10 more).
       @scope/cli is already published at version 2.1.3.
       Remove --first-release and run a normal release, or roll back
       the existing tags / unpublish before bootstrapping.
```

If neither does:

```
[pass] first-release.repo-not-greenfield (info)
       Workspace looks greenfield (no matching release tags, no
       published versions detected). Safe to use --first-release.
```

> **When to use `--first-release`:** Exactly once per monorepo, on the very first ship. After that, never again — the workspace has tags and / or registry entries, and the normal resolver path is the right answer. The flag is intentionally awkward to type so it does not become a habit.

## The `currentVersionResolver` modes [#the-currentversionresolver-modes]

`release.currentVersionResolver` decides where `oldVersion` comes from when building the release plan. Three values, with very different operational profiles:

```typescript
// vis.config.ts
export default {
    release: {
        currentVersionResolver: "disk", // default
        // or "registry"
        // or "git-tag"
    },
};
```

### `"disk"` — the default [#disk--the-default]

Read `package.json#version` (or the equivalent manifest field — `Cargo.toml`'s `[package].version`, `pyproject.toml`'s `[project].version`, `pom.xml`'s `<version>` — depending on the package's `versionActions`).

* **Fastest** — no network, no shell-outs.
* **Most predictable** — the value is exactly what you see on disk.
* **No side channels** — does not need registry credentials, does not need git history.

Use `"disk"` when:

* The version on disk is your team's canonical source of truth.
* Your release flow guarantees disk and registry stay in lock-step (every CI publish writes the bumped version back to a release branch — vis's default behaviour).
* You are migrating from changesets, bumpy, or any other tool that already maintains versions in the manifest.

This is the right answer for \~80% of workspaces. Pick it unless you have a specific reason to deviate.

### `"registry"` — query the package registry [#registry--query-the-package-registry]

Query the live version on the package's own registry via `versionActions.readPublishedVersion()`. Each package's actions decide how to ask:

* **npm** — `npm view <pkg> version` (or the `--registry` override).
* **cargo** — `GET https://crates.io/api/v1/crates/<name>`.
* **python** — PyPI's JSON API.
* **maven** — Maven Central's REST endpoint.
* **container** — `crane manifest` or registry API.
* **shell** — your configured `checkPublished` command.

Use `"registry"` when:

* The registry is your team's source of truth (`npm` is what shipped; the manifest is what *will* ship).
* You publish from multiple branches and want vis to dynamically catch up to whichever was most recent.
* You have an out-of-band publish flow (e.g. a manual `npm publish` for a hotfix) and want vis to pick up wherever you left off.

Cost: **one network request per package per `vis release version` / `vis release publish` invocation** (modulo the rate-limit + memo behaviour below). On a fresh 49-package monorepo that adds \~5–10 seconds to every release. On a hot CI runner with a populated DNS cache, much less.

### `"git-tag"` — parse the most recent matching tag [#git-tag--parse-the-most-recent-matching-tag]

Read the highest semver out of the git tags matching `releaseTagPattern`. The pattern is the **same one** vis uses for writing tags during the publish phase — there is no separate "read pattern", which avoids a historical class of bugs where the read and write patterns disagreed on the delimiter (`v{version}` vs `{name}@{version}`).

* Compiles the pattern to a `git tag --list <glob>` filter so it does not pull every tag in the repo.
* Anchors the regex (`^…$`) so partial matches are never accepted.
* Sorts the matched semvers with `semver.rcompare` and returns the highest.

Use `"git-tag"` when:

* You are migrating from **semantic-release**, which is fundamentally tag-driven. Your existing tags are the authoritative "what shipped" history; vis should respect that without you having to back-port versions into manifests.
* You ship some packages out of the registry's reach (private mirrors, OCI registries with no public read API) but always tag.
* The tag history is auditable in a way the registry is not (tag pushes are signed, the registry is not).

Cost: **one `git tag --list` per package** (workspace-local, no network) plus a small regex match. Much cheaper than `"registry"`; about as expensive as `"disk"` after the first call (git caches aggressively).

## Per-package overrides [#per-package-overrides]

Workspace-level `currentVersionResolver` is the default for every package. To override one (or a handful), set `packages.<name>.currentVersionResolver`:

```typescript
release: {
    currentVersionResolver: "registry",  // workspace default
    packages: {
        // A newly-added package that has not been published yet:
        // skip the registry probe (it would 404 and warn) and use disk.
        "@scope/new-package": {
            currentVersionResolver: "disk",
        },

        // A package we publish out-of-band and audit via tags only:
        "@scope/legacy": {
            currentVersionResolver: "git-tag",
        },
    },
},
```

Precedence is:

1. Per-package override (`packages.<name>.currentVersionResolver`).
2. Workspace-level (`release.currentVersionResolver`).
3. The built-in default `"disk"`.

`--first-release` overrides all three and forces `"disk"` for the duration of the run.

## What "fallback" means [#what-fallback-means]

Both `"registry"` and `"git-tag"` are **best-effort**. When the registry returns nothing (404, no published versions yet, empty array) or no git tag matches the pattern, the resolver falls back to the manifest version and emits a plan warning:

```
currentVersionResolver (registry): registry returned no version for @scope/foo
  (likely a 404 / not-yet-published); falling back to manifest version 0.0.1.

currentVersionResolver (git-tag): no git tag matched pattern "{name}@{version}"
  for @scope/bar; falling back to manifest version 1.0.0. (Pass --first-release
  to bootstrap.)
```

The warning is a soft signal — "I tried the source you configured and could not find an answer". It never throws, never blocks the release, and the resulting `oldVersion` is the same one `"disk"` mode would have produced. Operators see it in:

* `vis release plan` output (under `Warnings`).
* The PR sticky comment (under "Release plan warnings").
* CI logs (`::warning::` annotations on GitHub Actions).

If the warning shows up on the **same package on every release**, that is a config smell — usually a `releaseTagPattern` typo or a wrong registry URL. Fix the config; don't suppress the warning.

## Performance: rate-limiting and memoisation [#performance-rate-limiting-and-memoisation]

Two subtleties of the `"registry"` mode worth knowing about.

**Concurrency cap.** Registry-mode resolution caps in-flight HTTP requests at **4** to avoid tripping crates.io's documented 1-request-per-second unauthenticated rate limit and PyPI's per-IP throttle:

```typescript
export const REGISTRY_LOOKUP_CONCURRENCY = 4;
```

The cap is workspace-wide, not per-registry. A 49-package workspace in `"registry"` mode resolves in roughly `ceil(49 / 4) × p99-registry-latency` seconds — the deliberate choice over "fast but rate-limited".

**Per-process memo.** Within a single Node process, every `(name, mode, manifest-version)` triple is looked up at most once. Two places this matters:

* A `vis release version` followed by `vis release publish` in the **same** Node process (e.g. via `vis release ci release`) shares the memo, so the publish does not re-probe the registry for every package.
* The manifest version is part of the memo key, so the `version` apply mutating `pkg.json` mid-process correctly **invalidates** the entry — the follow-up `publish` resolves the new value, not a stale cached one.

The memo does not persist across processes. A new `vis release` invocation starts empty.

## `skipRegistryLookup`: read-only command paths [#skipregistrylookup-read-only-command-paths]

There is one more knob most operators never need to touch directly. The internal `skipRegistryLookup: true` option, set by **read-only commands** (`vis release plan`, `vis release status`, `vis release add`, `vis release doctor`, `vis release generate`), forces every package's resolver to `"disk"` for the duration of that invocation.

The reasoning: those commands do not actually need the upstream value. `vis release add` is writing a change file — the registry has no opinion on that. `vis release plan` is showing the operator what *would* ship; it surfaces the warning text but the registry answer is not load-bearing. Probing the registry on every `vis release add` invocation would make the most common command take 5+ seconds for no reason.

**Operators do not need to do anything.** The flag is set automatically by the command handlers; you cannot pass it on the command line and you should not need to. It is documented here only so the absence of registry probes on read-only commands does not look mysterious.

The mutation-side commands — `vis release version`, `vis release publish`, `vis release ci release` — still honour the configured resolver mode. That is where the live registry / tag answer matters, so that is where vis pays the lookup cost.

## Worked example 1: migrating from semantic-release [#worked-example-1-migrating-from-semantic-release]

semantic-release is tag-driven by design. Every shipped version produces a git tag (`v1.2.3` or `<pkg>-v1.2.3`); the next release's baseline is "the latest tag matching the configured `tagFormat`". When you migrate to vis, you have two options:

**Option A — keep the existing tag history, switch reads to `"git-tag"` mode.** Your tags are the authoritative log; your manifests may not be (semantic-release usually does not commit version bumps back). The right configuration:

```typescript
// vis.config.ts
export default {
    release: {
        currentVersionResolver: "git-tag",

        // Match whatever semantic-release was writing. The defaults:
        //   single-package repo:  "v{version}"        (semantic-release default)
        //   monorepo (multi-pkg): "{name}@{version}"  (vis default; also semantic-release-monorepo default)
        releaseTagPattern: "v{version}", // or "{name}@{version}", or your custom pattern
    },
};
```

Then run `vis release version` for the next release. vis reads the latest matching tag (e.g. `v1.2.3`), computes the bump from the pending change files, and produces `v1.3.0`. No manual baseline configuration; no manifest backfill.

> **If you used semantic-release-monorepo** with `tagFormat: "${name}@${version}"`, set `releaseTagPattern: "{name}@{version}"`. vis's token syntax (`{name}` not `${name}`) differs by one character — easy mistake.

**Option B — backfill the manifests once, then live in `"disk"` mode.** Bring `package.json#version` into alignment with the latest tag for each package, commit it, and from then on use the default `"disk"` mode. This is more work upfront (one commit) but simpler ongoing — no git history to keep clean.

If your team is happy with semantic-release's tag-as-source-of-truth model, **pick option A**. If you find the floating-manifest situation confusing (especially when developers `npm install` from a fresh clone and see `0.0.0-development`), pick option B.

## Worked example 2: migrating from a manual flow [#worked-example-2-migrating-from-a-manual-flow]

You ship out-of-band: a developer runs `npm publish` from their machine, then bumps `package.json` in a follow-up commit. There are no tags, sometimes the manifest version is ahead of the registry, sometimes behind.

The cleanest path:

1. Audit each package: is the manifest version ahead, behind, or in sync with the registry?
2. For packages where they disagree, decide which value is authoritative. Usually the registry — that is what your users see.
3. Run a one-time backfill commit to align manifests with the registry.
4. Configure `currentVersionResolver: "disk"` (the default — no config needed).
5. Run `vis release version --first-release` *only if* none of those packages were ever git-tagged with a matching `releaseTagPattern` (run `vis release doctor --first-release` first to confirm).

After that one bootstrap release, you are on the normal flow. `--first-release` is gone. The manifest is in sync. The default resolver does the right thing.

If you cannot do the manifest backfill (the team is mid-migration and cannot stop publishing), use `"registry"` mode instead:

```typescript
release: { currentVersionResolver: "registry" },
```

The manifest stays floating, vis catches up to whatever the registry shows on every release. Slower (one HTTP request per package per release) but no commit churn.

## Worked example 3: greenfield bootstrap [#worked-example-3-greenfield-bootstrap]

You have a fresh monorepo, three packages, no tags, nothing published. From zero to first ship:

```bash
# 1. (Optional) Verify the workspace really is greenfield.
vis release doctor --first-release

# 2. Write a change file describing the initial release.
vis release add --packages '@scope/a:minor,@scope/b:minor,@scope/c:minor' \
                --message 'Initial release'

# 3. Bump versions on disk (no tag-collision check; no registry probe).
vis release version --first-release

# 4. Publish (creates the first tags + first npm publishes).
vis release publish --first-release
```

After step 4, every subsequent release drops the `--first-release` flag. You now have tags, registry entries, and a baseline.

Common variant: &#x2A;*first release of an existing-on-npm package that was migrated into a new monorepo.** In that case the workspace is **not** greenfield from the registry's perspective — `--first-release` will fail the doctor preflight. Set `currentVersionResolver: "registry"` (or "disk" with an accurate manifest) and run a normal release.

## Reference: configuration recap [#reference-configuration-recap]

```typescript
// vis.config.ts
export default {
    release: {
        // Workspace-level default. Three valid values.
        currentVersionResolver: "disk", // or "registry", or "git-tag"

        // Optional — the pattern vis uses for BOTH tag-writing (publish phase)
        // and tag-reading (git-tag resolver mode). Tokens: {name}, {unscopedName},
        // {version}, {major}, {minor}, {patch}, {date}, {channel}.
        releaseTagPattern: "{name}@{version}",

        // Per-package overrides — same set of modes, different value.
        packages: {
            "@scope/legacy": { currentVersionResolver: "git-tag" },
            "@scope/new": { currentVersionResolver: "disk" },
        },
    },
};
```

```bash
# Bootstrap only. Forces disk mode, skips tag-collision checks. One-shot.
vis release version --first-release
vis release publish --first-release

# Confirm a workspace is greenfield before using the flag.
vis release doctor --first-release
```

## Cross-references [#cross-references]

* [Release manager guide](/docs/packages/vis/guides/release) — the overall mental model.
* [Release CI guide](/docs/packages/vis/guides/release-ci) — wiring versions into version-PR / auto-publish channels.
* [Release comparison](/docs/packages/vis/guides/release-comparison) — how the resolver modes map onto changesets / semantic-release / release-please equivalents.
* Source: `src/release/core/version-resolver.ts`, `src/release/types.ts` (`VisReleaseConfig.currentVersionResolver`, `PerPackageReleaseConfig.currentVersionResolver`), `src/commands/release/doctor/handler.ts` (`first-release.repo-not-greenfield`).


# Releasing Maven artifacts (/docs/packages/vis/guides/release-maven)



# Releasing Maven artifacts [#releasing-maven-artifacts]

Use this when you ship a JVM artifact alongside the JS / TS packages in your monorepo and want `vis release` to drive the version bump and the publish decision.

vis ships partial Maven support today: it bumps `<version>` in `pom.xml` and probes Maven Central to skip a publish that's already live. &#x2A;*Native publishing via the Sonatype Central Portal upload API is not yet implemented.** For now, delegate to `mvn deploy` via the generic shell-publish path. This page walks through both halves end-to-end.

## What works today [#what-works-today]

When a package opts into the `maven` `versionActions` (either explicitly
or by being declared via the `pomXml({...})` preset, which defaults
`versionActions: "maven"`), vis will:

1. Read the current project version from `pom.xml`. The parser looks at
   the first `<version>` directly under `<project>`, skipping anything
   inside `<parent>`, `<dependencies>`, or `<build>`.
2. Detect multi-module reactor builds (`<modules>` present) and emit a
   warning that vis treats the package as a single artifact. For full
   reactor handling, see the [reactor workaround](#multi-module-reactor-projects)
   below.
3. Fetch `https://repo1.maven.org/maven2/<groupId>/<artifactId>/maven-metadata.xml`
   and parse `<latest>` (falling back to the last `<version>` in
   `<versions>`). A 404 means the artifact is new; the publish proceeds.

The version bump itself flows through the existing extra-files engine
— `pomXml({ pomDir })` registers a regex that swaps the first
`<version>...</version>` in the pom for the new value when
`vis release version` runs.

## What's not implemented [#whats-not-implemented]

Native publishing — vis running the Sonatype Central Portal upload flow directly — is not yet wired up. The flow Sonatype expects (GPG-sign every artifact, bundle into a deployment `.zip`, `POST /api/v1/publisher/upload`, poll status, trigger publish) is non-trivial and deferred until the rest of vis's JVM story catches up.

Calling `vis release publish` on a Maven package today throws a `CONFIG_INVALID` error pointing at the shell-path workaround below.

## The shell-path workaround [#the-shell-path-workaround]

Drop to the generic shell publisher and delegate to `mvn deploy`. The
shell path runs vis's idempotency guard (`checkPublished`) before
invoking the publish command, so re-running after a transient failure
is safe.

### 1. Configure `pom.xml` with the Central Portal publishing plugin [#1-configure-pomxml-with-the-central-portal-publishing-plugin]

The recommended plugin since the OSSRH sunset is
`central-publishing-maven-plugin`:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.sonatype.central</groupId>
            <artifactId>central-publishing-maven-plugin</artifactId>
            <version>0.5.0</version>
            <extensions>true</extensions>
            <configuration>
                <publishingServerId>central</publishingServerId>
                <autoPublish>true</autoPublish>
                <waitUntil>published</waitUntil>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-gpg-plugin</artifactId>
            <version>3.2.4</version>
            <executions>
                <execution>
                    <id>sign-artifacts</id>
                    <phase>verify</phase>
                    <goals><goal>sign</goal></goals>
                </execution>
            </executions>
        </plugin>
        <!-- maven-source-plugin + maven-javadoc-plugin emit the
             sources + javadoc jars Maven Central requires. -->
    </plugins>
</build>
```

If you still publish through the legacy OSSRH staging service, use
`nexus-staging-maven-plugin` instead. Either way, the rest of this
guide applies.

### 2. Configure credentials in `~/.m2/settings.xml` [#2-configure-credentials-in-m2settingsxml]

Maven Central does **not** support OIDC trusted publishing as of late
2024 — static credentials are required. Use env-substitution to keep
secrets out of the repo:

```xml
<settings>
    <servers>
        <server>
            <id>central</id>
            <username>${env.MAVEN_CENTRAL_USERNAME}</username>
            <password>${env.MAVEN_CENTRAL_TOKEN}</password>
        </server>
    </servers>
    <profiles>
        <profile>
            <id>gpg</id>
            <activation><activeByDefault>true</activeByDefault></activation>
            <properties>
                <gpg.keyname>${env.GPG_KEY_ID}</gpg.keyname>
                <gpg.passphrase>${env.GPG_PASSPHRASE}</gpg.passphrase>
            </properties>
        </profile>
    </profiles>
</settings>
```

In CI, populate `MAVEN_CENTRAL_USERNAME` / `MAVEN_CENTRAL_TOKEN` from
the Central Portal user token (generated at
`https://central.sonatype.com/account`) and `GPG_KEY_ID` /
`GPG_PASSPHRASE` from the signing key you uploaded to the public
keyserver pool.

### 3. Wire the shell path in `vis.config.ts` [#3-wire-the-shell-path-in-visconfigts]

```typescript
import { pomXml } from "@visulima/vis/release/presets";

export default {
    release: {
        // The trust gate — required for every shell-publish package.
        allowCustomCommands: ["@scope/jvm-sdk"],
        packages: {
            "@scope/jvm-sdk": {
                ...pomXml({ pomDir: "jvm/sdk" }),
                // Override the maven default with the shell publisher.
                versionActions: "shell",
                publishCommand: "mvn -B -ntp -DskipTests deploy",
                // Disable maven-metadata.xml lookup — the publishCommand
                // is idempotent (Central rejects a re-publish of the same
                // (groupId:artifactId:version)).
                checkPublished: "",
            },
        },
    },
};
```

Run `vis release publish` from CI as usual — the shell publisher will
interpolate `{{version}}` / `{{name}}` / `{{tag}}` / `{{registry}}` and
invoke `mvn deploy`. Failed publishes throw `PUBLISH_FAILED` with the
mvn stderr captured for diagnostics; the orchestrator still creates +
pushes the git tag so subsequent runs can `--resume`.

## Multi-module reactor projects [#multi-module-reactor-projects]

When vis detects a `<modules>` section in your `pom.xml`, it warns to
stderr but still treats the package as a single artifact for
version-bumping + already-published detection. For real reactor
behaviour:

1. Set the root pom's `<version>` via the standard `pomXml` preset on
   the root package.
2. Use a custom `extraFiles` rule (or one preset per submodule) to bump
   every child `pom.xml` to the new version — Maven doesn't propagate
   the root version automatically when a child declares its own.
3. Publish via `mvn -pl <module-list> -am deploy` so the reactor
   resolves dependencies across modules.

For the truly hairy case (versions diverging across submodules), vis is
the wrong tool; reach for `mvn versions:set` driven from a custom
`buildCommand` instead.

## When the native client lands [#when-the-native-client-lands]

The per-package config shape stays the same — the `pomXml({...})` preset already returns `versionActions: "maven"` by default. Removing the `versionActions: "shell"` override and the `publishCommand` switches you onto the native path. The shell-path config keeps working as the generic escape hatch.

## OIDC trusted publishing [#oidc-trusted-publishing]

Maven Central does not support OIDC trusted publishing. PyPI, npm, and Crates.io all do; Sonatype has acknowledged the gap publicly but has not committed a ship date. For now, store the Central Portal token as a CI secret and rotate it as you would any long-lived publishing credential.

## Cross-references [#cross-references]

* [Release guide](/docs/packages/vis/guides/release) — mental model and change files
* [Release CI guide](/docs/packages/vis/guides/release-ci) — wiring publishes into CI
* Source: `packages/tooling/vis/src/release/core/version-actions/maven.ts`


# Release notifications (/docs/packages/vis/guides/release-notifications)



# Release notifications [#release-notifications]

Once a release wave finishes — tags pushed, GitHub releases created, workspace `CHANGELOG.md` committed — most teams want to tell **somebody** about it. A Slack channel, a Discord server, a Teams room, an internal dashboard. Historically that has meant either curl in `postPublishCommand` (ugly, error-prone, no token redaction, no idempotency) or a userland semantic-release plugin (correct, but every team writes the same 90% of the code).

`release.notifications` is vis's bundled answer: three first-class channels (Slack, Discord, generic webhook), a typed `NotificationChannel` plugin surface for the rest, parallel dispatch, per-channel soft-fail, and `--resume` dedup so a retry after a partial publish does not re-fire the same Slack ping.

> The notifications subsystem is modelled on the semantic-release plugin ecosystem (`semantic-release-slack-bot`, `semantic-release-discord-notifier`, …) — but first-party so the most common cases require zero userland code.

## When notifications fire [#when-notifications-fire]

Notifications are dispatched **after** every other post-publish step finishes. Specifically: after tags are pushed, after the per-package and aggregate GitHub / GitLab releases land, and after the workspace-level `CHANGELOG.md` wave entry is committed. Chat pings reflect the **final** state of the release, not an in-progress snapshot.

```mermaid
sequenceDiagram
    autonumber
    participant CI as CI runner
    participant Pub as vis release publish
    participant Reg as registry (npm / cargo / …)
    participant Git as git remote
    participant GH as GitHub / GitLab
    participant N as dispatchNotifications
    participant Slack as Slack webhook
    participant Discord as Discord webhook
    participant Hook as generic webhook

    CI->>Pub: vis release publish
    Pub->>Reg: publish each package (in dep order)
    Reg-->>Pub: ok / stage-pending / already-published
    Pub->>Git: push tags
    Pub->>GH: create per-package + aggregate releases
    GH-->>Pub: release URLs
    Pub->>Pub: workspace CHANGELOG.md wave entry
    Pub->>N: dispatchNotifications(context)
    par fan-out
        N->>Slack: POST Block Kit body
        Slack-->>N: 200 OK
    and
        N->>Discord: POST embed body
        Discord-->>N: 204 No Content
    and
        N->>Hook: POST custom body
        Hook-->>N: 200 OK
    end
    N->>Pub: { succeeded, failed }
    Pub->>Pub: persist state.notified[]
    Pub-->>CI: exit 0
```

Three things matter about this ordering:

* **Every channel runs in parallel.** A slow webhook does not stall the others.
* **Per-channel failure is isolated.** A Slack webhook outage logs a warning; it never fails the publish. The release already shipped — chat tooling outages should not cascade into "the package is on npm but CI is red".
* **State is persisted after dispatch.** The `state.notified[]` array in `.vis/release/.state.json` records every `name@version` for which at least one channel succeeded, so `--resume` after a partial publish does not re-send duplicates.

## The configuration shape [#the-configuration-shape]

Add a `notifications` block under `release` in `vis.config.ts`:

```typescript
// vis.config.ts
export default {
    release: {
        notifications: {
            // Built-in channels — single object or an array. See sections below.
            slack: { webhook: "${SLACK_WEBHOOK_URL}" },
            discord: { webhook: "${DISCORD_WEBHOOK_URL}" },
            webhook: {
                url: "https://hooks.example.com/release",
                headers: { "X-Auth": "Bearer ${WEBHOOK_TOKEN}" },
            },

            // Custom channels — paths to your own NotificationChannel modules.
            plugins: ["./.vis/release/teams-channel.ts"],

            // Default: true (no chat noise from alpha / beta / canary waves).
            skipPrerelease: true,
        },
    },
};
```

Three workspace-wide knobs and three (or four) channel slots. The full picture:

* `slack` / `discord` / `webhook` — each accepts **either** a single config object **or** an array of them. The array form fans out to multiple instances of the same channel kind (e.g. one Slack webhook for `#engineering`, another for `#releases`).
* `plugins` — array of paths (or `[path, options]` tuples) to custom `NotificationChannel` implementations. See [Plugin authoring → custom NotificationChannel](/docs/packages/vis/guides/release-plugin-authoring#custom-notificationchannel) for the full contract.
* `skipPrerelease` — default `true`. When every published version in the wave has a `-…` suffix (e.g. `1.2.0-alpha.0`), the dispatcher returns immediately without firing any channel. Most teams want Slack noise only on stable releases.

Env-var substitution (`${SLACK_WEBHOOK_URL}`) is resolved by the standard visulima config loader, so webhook URLs never need to live inline in your repo.

## The Slack channel [#the-slack-channel]

Slack uses **incoming webhooks** — workspace+channel-scoped URLs you create once and paste. No OAuth, no bot token, no rotating credentials. To wire one up:

1. Visit [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**.
2. Pick a workspace, give the app a name (`vis release notifier` works).
3. Sidebar → **Incoming Webhooks** → toggle on.
4. **Add New Webhook to Workspace** → pick the destination channel.
5. Copy the URL (looks like `https://hooks.slack.com/services/T.../B.../...`). Treat it as a bearer secret.

Then in `vis.config.ts`:

```typescript
release: {
    notifications: {
        slack: { webhook: "${SLACK_WEBHOOK_URL}" },
    },
},
```

Set `SLACK_WEBHOOK_URL` in your CI runner's secret store and you are done. The default message is a Block Kit payload with three sections:

```
┌───────────────────────────────────────────────┐
│ 🚀 Released 2 packages                        │  ← header block
├───────────────────────────────────────────────┤
│ • @scope/cerebro@1.5.0   (links to GH release)│  ← section block
│ • @scope/cli@2.1.0       (links to GH release)│
├───────────────────────────────────────────────┤
│ channel: `latest`  •  foo/bar  •  May 22, 2:00│  ← context block
└───────────────────────────────────────────────┘
```

If the wave skipped any packages (stage-rejected, stage-timeout, already-published), a divider + `Skipped (N):` section is appended automatically.

Want to override the look?

```typescript
slack: {
    webhook: "${SLACK_WEBHOOK_URL}",
    title: "📦 {repo} shipped {count} packages on {channel}",
    username: "Release Bot",
    iconEmoji: ":rocket:",
    includeSkipped: false, // suppress the Skipped block
}
```

The `title` field accepts every [template token](#template-tokens) listed below. Heavier customisation (different block layouts, attachments, threading) is what the [custom channel plugin surface](/docs/packages/vis/guides/release-plugin-authoring#custom-notificationchannel) is for — the built-in is intentionally opinionated.

## The Discord channel [#the-discord-channel]

Discord uses **server+channel webhooks** — paste the URL the same way you would for Slack. To create one: in your Discord server, **Server Settings → Integrations → Webhooks → New Webhook**. Pick a channel, name the bot, copy the URL.

```typescript
release: {
    notifications: {
        discord: { webhook: "${DISCORD_WEBHOOK_URL}" },
    },
},
```

The default message is a single embed with a title, a bulleted description of every released package (linked to its GH release where available), and two inline fields for `Channel` and `Repository`. Skipped packages are listed in an additional field when present.

The embed colour is configurable as an integer RGB value:

```typescript
discord: {
    webhook: "${DISCORD_WEBHOOK_URL}",
    color: 0x10B981, // emerald-500
    username: "Release Bot",
    avatarUrl: "https://example.com/bot-avatar.png",
}
```

For very large waves (more than \~25 packages), the description is truncated with a `… +N more` footer to stay under Discord's hard 4096-character embed-description limit. If you regularly ship more than that in one wave, point a [custom channel](/docs/packages/vis/guides/release-plugin-authoring#custom-notificationchannel) at Discord's API and paginate yourself.

## The generic webhook channel [#the-generic-webhook-channel]

For everything that isn't Slack or Discord — Microsoft Teams, Mattermost, Alertmanager, internal dashboards, Zapier — the `webhook` channel POSTs a JSON body of your choosing to a URL of your choosing.

The simplest form:

```typescript
release: {
    notifications: {
        webhook: { url: "https://hooks.example.com/release" },
    },
},
```

With no `body` template configured, vis sends the **full `NotificationContext` verbatim** as the request body. That gives your receiver every field — package list, URLs, channel, repo, skipped reasons — without you having to author a schema. Great for prototyping.

When you want to control the shape (typical for Teams or Mattermost's "MessageCard" / "block" formats), provide a `body` template:

```typescript
webhook: {
    url: "https://outlook.office.com/webhook/...",
    headers: { "X-Auth": "Bearer ${WEBHOOK_TOKEN}" },
    body: {
        "@type": "MessageCard",
        "@context": "https://schema.org/extensions",
        themeColor: "0078D7",
        summary: "Released {count} packages",
        sections: [
            {
                activityTitle: "🚀 {repo} — {count} packages shipped",
                activitySubtitle: "{date} on {channel}",
                text: "Packages: {packages}",
            },
        ],
    },
},
```

The body is **deeply interpolated**: every string leaf flows through the template engine; arrays and nested objects preserve their structure; numbers and booleans pass through untouched. Header values are also interpolated, so `"X-Release-Pkg": "{firstName}@{firstVersion}"` works.

> If your endpoint is a Slack-style or Discord-style webhook (e.g. Mattermost has Slack-compatible incoming webhooks), use the dedicated `slack` / `discord` channel — they already produce the right body shape. The generic webhook is for everything else.

### Microsoft Teams [#microsoft-teams]

Teams accepts both the legacy **Office 365 Connector** card format and the newer **Adaptive Cards** format via incoming webhooks. The example above uses the connector format; for adaptive cards, swap the body:

```typescript
webhook: {
    url: "${TEAMS_WEBHOOK_URL}",
    body: {
        type: "message",
        attachments: [{
            contentType: "application/vnd.microsoft.card.adaptive",
            content: {
                type: "AdaptiveCard",
                version: "1.4",
                body: [
                    { type: "TextBlock", size: "Large", weight: "Bolder", text: "Released {count} packages" },
                    { type: "TextBlock", text: "{packages}", wrap: true },
                ],
            },
        }],
    },
},
```

### Mattermost [#mattermost]

Mattermost's incoming webhook is Slack-compatible — use the `slack` channel:

```typescript
slack: { webhook: "${MATTERMOST_WEBHOOK_URL}" },
```

## Template tokens [#template-tokens]

Every string field that runs through the template engine (`title`, header values, every string leaf in a webhook `body`) supports these tokens.

| Token            | Expands to                                        | Example                          |
| ---------------- | ------------------------------------------------- | -------------------------------- |
| `{count}`        | Number of published packages                      | `2`                              |
| `{packages}`     | Comma-separated `name@version` list               | `@scope/a@1.0.0, @scope/b@2.1.0` |
| `{firstName}`    | First package's name (handy for single-pkg waves) | `@scope/a`                       |
| `{firstVersion}` | First package's version                           | `1.0.0`                          |
| `{channel}`      | Active channel name (`latest`, `alpha`, …)        | `latest`                         |
| `{repo}`         | Repo slug (`owner/name`)                          | `foo/bar`                        |
| `{date}`         | ISO date (`YYYY-MM-DD`) of the wave completion    | `2026-05-22`                     |

Unset optional fields (`{channel}` / `{repo}` when not detected) expand to the empty string. Non-string values passed by misconfiguration (a number, a boolean) are coerced via `String()` rather than throwing.

So a template like:

```
"Released {count} ({packages}) on {channel} via {repo} on {date} — first {firstName}@{firstVersion}"
```

…against a two-package wave on `latest` from `foo/bar`, produces:

```
Released 2 (@scope/a@1.0.0, @scope/b@2.1.0) on latest via foo/bar on 2026-05-22 — first @scope/a@1.0.0
```

## Skipping prereleases (the default) [#skipping-prereleases-the-default]

By default, **alpha / beta / canary waves never notify**. The dispatcher checks every published version in the wave for a prerelease component (the `-` segment in semver — `1.2.0-alpha.0`, `2.0.0-next.1`, etc.); when **all** of them have one, the wave is treated as a prerelease and the dispatcher returns early.

This is almost always the right default — most teams broadcast stables to chat and let prereleases ship silently to the registry. To turn it off (notify on every wave):

```typescript
notifications: {
    skipPrerelease: false,
    slack: { webhook: "${SLACK_WEBHOOK_URL}" },
}
```

> **Mixed waves still notify.** A wave that contains one alpha + four stables is **not** considered a prerelease wave (the rule is `every`, not `some`). Those are rare and almost always deliberate — the chat ping is the right behaviour.

## Multi-channel fan-out [#multi-channel-fan-out]

The array form lets you fire the same channel kind multiple times — different webhooks, different audiences:

```typescript
notifications: {
    slack: [
        {
            id: "engineering",
            webhook: "${SLACK_ENG_WEBHOOK_URL}",
            title: "🚀 {count} packages shipped on {channel}",
        },
        {
            id: "releases",
            webhook: "${SLACK_RELEASES_WEBHOOK_URL}",
            title: "[release] {repo} → {packages}",
            includeSkipped: false,
        },
    ],
    discord: [
        { id: "community", webhook: "${DISCORD_COMMUNITY_WEBHOOK_URL}" },
        { id: "internal", webhook: "${DISCORD_INTERNAL_WEBHOOK_URL}", color: 0xEF4444 },
    ],
},
```

The `id` field is an operator-supplied disambiguator that surfaces in log lines (`[notifications:slack:engineering]`), in `result.failed[].id`, and in the `state.notified` ledger. Without an `id`, both Slack channels would log as `[notifications:slack]` and you would not know which one rejected.

All entries across all channel kinds run in **parallel**. There is no ordering guarantee — and your channel implementations should not depend on one.

## `--resume` and the `state.notified` ledger [#--resume-and-the-statenotified-ledger]

Notifications are the only post-publish step with **no server-side idempotency** — chat webhooks happily accept the same payload twice and render two messages. Tags are idempotent (`git push --tags` skips ones that already exist). GitHub release creation is idempotent (the per-package release walks check before creating). But `POST https://hooks.slack.com/services/...` will gladly duplicate.

To prevent a `vis release publish --resume` after a partial failure from re-pinging Slack for releases that already shipped, the orchestrator maintains a `state.notified` array in `.vis/release/.state.json`. Pseudocode of the contract:

```typescript
// Build the dedup set from the persisted ledger.
const alreadyNotified = new Set(state.notified ?? []);

// Filter this wave's published[] down to only the entries that have not
// been notified yet (keyed by `name@version`).
const notifiable = result.published.filter((p) => !alreadyNotified.has(`${p.name}@${p.version}`));

if (notifiable.length === 0) {
    // Everything in this wave was notified on a prior run. Skip dispatch entirely.
    return;
}

const dispatchResult = await dispatchNotifications(config, { ...context, published: notifiable });

// Persist ONLY when at least one channel succeeded. A total dispatch failure
// (all channels down) can retry next wave instead of being silently skipped.
if (dispatchResult.succeeded.length > 0) {
    state.notified = [...(state.notified ?? []), ...notifiable.map((p) => `${p.name}@${p.version}`)];
    await writeState(cwd, changesDir, state);
}
```

Three rules fall out of this:

* **Dedup is per `name@version`.** A re-run on the same wave never re-fires. A new release of the same package re-fires (new version → new key).
* **Persist only on at least one success.** A total dispatch failure (Slack + Discord both 502) leaves the ledger untouched so the next wave retries the same pings. This is intentional — silent permanent skip would be worse than an occasional retry.
* **No partial dedup across channels.** If Slack succeeded but Discord failed in run 1, the version is marked notified, and run 2 will **not** retry Discord. The trade-off is "no Slack duplicates" vs "no Discord-only retries"; we picked the former because chat duplicates are highly visible and annoying. Custom retry logic belongs in the channel implementation (see plugin authoring).

If you need to force a re-notification (e.g. you fixed a typo in the Slack template and want to re-send), edit `.vis/release/.state.json` and drop the relevant `name@version` entries.

## Custom channels (plugin pointer) [#custom-channels-plugin-pointer]

Anything more bespoke than the three built-ins — PagerDuty incidents, Linear status updates, an internal bot with custom routing — wires up via `notifications.plugins`. A plugin module exports either a `NotificationChannel` object directly or a factory function returning one:

```typescript
// .vis/release/teams-channel.ts
import { defineNotificationChannel, type NotificationContext } from "@visulima/vis/release/plugin-sdk";

export default defineNotificationChannel({
    id: "teams",
    async send(context: NotificationContext) {
        // Your HTTP / SDK call here.
    },
});
```

Reference it from config:

```typescript
notifications: {
    plugins: [
        "./.vis/release/teams-channel.ts",
        // Or with options:
        ["./.vis/release/incident-channel.ts", { severity: "info" }],
    ],
},
```

The full authoring guide — soft-fail contract, factory shape, error redaction, doctor preflight — lives in [Plugin authoring → custom NotificationChannel](/docs/packages/vis/guides/release-plugin-authoring#custom-notificationchannel).

## Testing your configuration [#testing-your-configuration]

Before relying on a channel for a real release, dry-run it with `vis release notifications test`. The command builds a synthetic single-package release context and dispatches to every configured channel:

```bash
vis release notifications test                              # All channels
vis release notifications test --channel=slack              # Only Slack
vis release notifications test --channel=slack:engineering  # One id'd Slack hook
vis release notifications test --custom-context=./fake.json # Use your own context
vis release notifications test --json                       # Machine-readable
```

Exits 0 only when every dispatched channel succeeds. Use this in a one-off CI job after wiring a new webhook, or locally after editing a `body` template.

## Doctor checks [#doctor-checks]

`vis release doctor` runs a preflight on your notification config: webhook URLs are syntactically valid, env-var references resolve, plugin paths load. The full notification dispatch path itself runs at the end of `vis release publish` — failures there surface as plan warnings, not preflight errors, because they happen **after** the release is immutable.

## When NOT to use notifications [#when-not-to-use-notifications]

* **You want to gate the release on chat approval.** Notifications fire *after* publish. They cannot block. For human-in-the-loop approval, see [staged publishing](/docs/packages/vis/guides/release-staged-publishing).
* **You need delivery guarantees.** Webhooks are best-effort. A 502 from Slack is logged and dropped (after the per-channel try/catch). If your audit requirements demand a durable record, write a custom channel that persists to your own datastore before returning success.
* **You want PR-time previews of what would ship.** Use the `vis release plan` command and the [PR sticky-comment workflow](/docs/packages/vis/guides/release-ci#workflow-c-pr-sticky-comment) — those fire **before** publish, not after.


# Release plugin authoring (/docs/packages/vis/guides/release-plugin-authoring)



# Plugin authoring for `vis release` [#plugin-authoring-for-vis-release]

`vis release` ships with batteries-included built-ins for the 80% case: npm / cargo / python / maven / container publishing, default / github / keep-a-changelog formatters, slack / discord / generic-webhook notifications. The other 20% has too much variety to bundle — your internal chat tool, your private registry, your house style guide — so vis exposes three typed plugin surfaces that you load from the workspace config.

| Surface               | What it controls                                 | Where it loads from                                         |
| --------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
| `NotificationChannel` | Post-publish chat / webhook fan-out              | `release.notifications.plugins: ["./my-channel.ts"]`        |
| `VersionActions`      | Per-package read-published + publish steps       | `release.packages.<name>.versionActions: "./my-actions.ts"` |
| `ChangelogFormatter`  | Per-release changelog rendering (file + GH body) | `release.changelog: "./my-formatter.ts"`                    |
| `ReleasePlugin`       | Arbitrary version/publish **lifecycle** hooks    | `release.plugins: [defineReleasePlugin({ … })]`             |

All four plugin surfaces — types, identity wrappers, abstract base classes — are re-exported from `@visulima/vis/release/plugin-sdk` (`defineReleasePlugin` is also re-exported from `@visulima/vis/release`). Always import from there in your plugin modules; the deeper sub-paths (`/core/notifications/interface`, etc.) are internal and not covered by the stability contract.

This guide covers the three single-purpose surfaces in depth; the lifecycle-plugin surface is summarised below. Each single-purpose section ends with a complete worked example you can paste into `.vis/release/` and adapt.

> **Trust gate.** Anything that runs shell commands you control (the `shell` version actions, `preReleaseCommand`, `publishCommand`) is gated by `release.allowCustomCommands` — either a workspace-wide boolean or an allow-list of package names. Plugin module loading itself is **not** gated, on the assumption that anything you commit to your repo is implicitly trusted. If you load plugins from outside the workspace (e.g. an npm package), audit them like any other dependency.

## Lifecycle plugins (`ReleasePlugin`) [#lifecycle-plugins-releaseplugin]

The three surfaces above each own one well-defined job. A **lifecycle plugin** is the general escape hatch: it hooks arbitrary points of the version/publish flow — run a build before publishing, push docs after, gate a package, notify on completion. Register it inline in `release.plugins`:

```typescript
// vis.config.ts
import { defineReleasePlugin } from "@visulima/vis/release";

export default defineConfig({
    release: {
        plugins: [
            defineReleasePlugin({
                name: "build-before-publish",
                async willPublish({ package: pkg }) {
                    await runBuild(pkg.name); // return `false` to skip this package
                },
                async afterPublishAll({ result }) {
                    await pingDeployHook(result.published);
                },
            }),
        ],
    },
});
```

Every hook is optional:

| Hook                          | When it runs                                                           | Return / effect                                                     |
| ----------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `applyDraft({ plan })`        | After versions + changelogs are written, **before** the version commit | Inspect the computed plan; throw to abort before committing         |
| `willPublish({ package })`    | Before each package is published                                       | Return `false` to skip it (its in-wave dependents are skipped too)  |
| `afterPublish({ package })`   | After each successful publish                                          | Side effects (docs, cache warm, …)                                  |
| `afterPublishAll({ result })` | Once the whole wave finishes                                           | Side effects with the full `{ published, skipped, failed }` summary |

**Error policy.** `applyDraft` and `willPublish` **gate** the release — a throw propagates and aborts (fail fast). `applyDraft` runs after the draft is written but before the version commit, so a throw aborts before anything is committed, and edits a plugin makes to the already-written files (`package.json` bumps, `CHANGELOG.md`) are picked up by that commit — brand-new files a plugin creates must be staged by the plugin itself. `afterPublish` and `afterPublishAll` are **post-effect** — a throw is logged to stderr and swallowed, because a docs-push hiccup must never "unpublish" a package that already shipped. A `willPublish` veto is treated like a non-publish, so any package depending on the vetoed one is skipped rather than published against a version that never reached the registry.

## Custom `NotificationChannel` [#custom-notificationchannel]

Use this when the three built-in channels (slack / discord / webhook) cannot model your destination — typically because the destination needs typed SDK access (PagerDuty, Linear, Statuspage), bespoke retry logic, durable persistence, or a routing decision that the operator does not want encoded in workspace config.

### The interface [#the-interface]

```typescript
import type { NotificationChannel, NotificationContext, NotificationPackage } from "@visulima/vis/release/plugin-sdk";

interface NotificationChannel {
    /** Stable id used in log messages: `"slack"`, `"discord"`, `"teams"`, …. */
    readonly id: string;

    /**
     * Send the notification. Throw on hard failure (HTTP non-2xx,
     * network error). The dispatcher catches and logs as a warn-level
     * message; it does NOT propagate.
     */
    send(context: NotificationContext): Promise<void>;
}

interface NotificationContext {
    /** Active channel name (`main`, `alpha`, …). */
    channel?: string;
    /** ISO-8601 wave-completion timestamp. */
    completedAt: string;
    /** Workspace name pulled from root `package.json#name`. */
    monorepoName?: string;
    /** Packages that successfully published in this wave. */
    published: ReadonlyArray<NotificationPackage>;
    /** Repo slug (`owner/name`). */
    repo?: string;
    /** Packages skipped at the publish gate. */
    skipped: ReadonlyArray<{ name: string; reason: string }>;
}

interface NotificationPackage {
    name: string;
    version: string;
    /** Release URL when known (`undefined` for packages with no canonical URL). */
    url?: string;
    /** dist-tag / channel name (`latest`, `alpha`, …). */
    tag?: string;
}
```

Two methods, four context fields. The interface is intentionally minimal — anything richer (multi-step delivery, ACK handshakes, message threading) lives inside your `send` implementation.

### Where it loads from [#where-it-loads-from]

```typescript
// vis.config.ts
export default {
    release: {
        notifications: {
            plugins: [
                "./.vis/release/teams-channel.ts",
                // Or with options (factory form):
                ["./.vis/release/incident-channel.ts", { severity: "info" }],
            ],
        },
    },
};
```

Two shapes accepted:

* `string` — path to a module whose `default` export is either a `NotificationChannel` object or a zero-arg factory `() => NotificationChannel`.
* `[string, Record<string, unknown>]` — path + options. The module's `default` export must be a factory `(options) => NotificationChannel`.

Paths starting with `.` resolve relative to the workspace cwd. Absolute paths and `file://` URLs are passed through unchanged. The loader uses `dynamicEsmImport`, which means both `.ts` and `.mts` / `.mjs` modules work (vis transpiles on the fly via `unbuild` / `tsx`).

### The soft-fail contract [#the-soft-fail-contract]

Per-channel failures are isolated. When your `send` throws, the dispatcher:

1. Catches the error.
2. Pushes the (token-redacted) message onto `result.failed[]`.
3. Logs a `[notifications:<id>] <message>` warning to stderr.
4. Continues fanning out to every other channel.
5. Returns control to the orchestrator, which surfaces the warning on `plan.warnings`.

The publish itself is **not** failed. The release already shipped — your chat plugin's outage is not load-bearing for the package being on npm.

Two implications for your implementation:

* **Throw freely on hard failures.** A 502 from your endpoint should throw. A network unreachable error should throw. You do not need to catch and swallow — the dispatcher does that.
* **Do not log the URL on failure.** Webhook URLs often contain bearer secrets in the path (Slack and Discord both do this). The dispatcher routes your thrown error message through `redactTokens` before logging, but the safest pattern is to never include the URL in the message in the first place. Wrap your `fetch` errors so the URL never escapes the function.

### Worked example: Microsoft Teams channel [#worked-example-microsoft-teams-channel]

Teams has Slack-compatible incoming webhooks (use the built-in `slack` channel for that path) **and** a native Adaptive Card / Office 365 Connector format (which the built-in `webhook` channel handles via a `body` template). So when would you want a custom Teams channel?

Two scenarios:

* Your Teams instance routes through the **Power Automate / Logic Apps** API rather than incoming webhooks, requiring OAuth.
* You want per-package message threading, mention parsing, or attachment uploads — anything that needs more than a single POST.

Below is a minimal Teams channel that uses an OAuth Bearer token and the Microsoft Graph chat-message endpoint. It is intentionally short — the structure is what matters, not the API specifics.

```typescript
// .vis/release/teams-channel.ts
import { defineNotificationChannel, type NotificationChannel, type NotificationContext } from "@visulima/vis/release/plugin-sdk";

export interface TeamsChannelOptions {
    /** Microsoft Graph endpoint — your tenant + chat id baked in. */
    endpoint: string;
    /** OAuth bearer token (env-substituted in vis.config.ts). */
    token: string;
    /** Optional title template. Defaults to "Released {count} packages". */
    titleTemplate?: string;
}

/**
 * Factory form — receives the options object from the
 * `["./teams-channel.ts", { ...options }]` config tuple.
 */
export default (options: TeamsChannelOptions): NotificationChannel =>
    defineNotificationChannel({
        id: "teams",

        async send(context: NotificationContext) {
            const title = (options.titleTemplate ?? "Released {count} packages")
                .replaceAll("{count}", String(context.published.length))
                .replaceAll("{repo}", context.repo ?? "")
                .replaceAll("{channel}", context.channel ?? "");

            const packageList = context.published
                .map((p) => (p.url ? `<li><a href="${p.url}">${p.name}@${p.version}</a></li>` : `<li>${p.name}@${p.version}</li>`))
                .join("");

            const body = {
                body: {
                    contentType: "html",
                    content: `<h2>${title}</h2><ul>${packageList}</ul>`,
                },
            };

            let response: Response;

            try {
                response = await fetch(options.endpoint, {
                    method: "POST",
                    headers: {
                        Authorization: `Bearer ${options.token}`,
                        "Content-Type": "application/json",
                    },
                    body: JSON.stringify(body),
                });
            } catch (error) {
                // Wrap the underlying error so neither the token (in
                // Authorization) nor any URL fragments leak into the log line.
                const reason = error instanceof Error ? error.name : "NetworkError";

                throw new Error(`Teams channel fetch failed (${reason})`);
            }

            if (!response.ok) {
                const errorBody = await response.text().catch(() => "");

                throw new Error(`Teams channel returned ${response.status} ${response.statusText}${errorBody ? `: ${errorBody.slice(0, 200)}` : ""}`);
            }
        },
    });
```

Wire it up:

```typescript
// vis.config.ts
export default {
    release: {
        notifications: {
            plugins: [
                [
                    "./.vis/release/teams-channel.ts",
                    {
                        endpoint: "https://graph.microsoft.com/v1.0/chats/19:.../messages",
                        token: "${TEAMS_BOT_TOKEN}",
                        titleTemplate: "🚀 {repo} shipped {count} packages",
                    },
                ],
            ],
        },
    },
};
```

Three things worth pointing out about the example:

* **Factory form.** The default export is a function taking the options, returning the channel. The tuple form `[path, options]` in config is what passes the options through.
* **Stable id.** `id: "teams"` shows up in log lines as `[notifications:teams]`. If you wire two instances of this channel (e.g. `internal-teams` and `customer-teams`), give them distinct ids — that is how operators tell them apart in failure logs.
* **Error wrapping.** Every `fetch` call site wraps the rejection so the token and endpoint never leak. The dispatcher does redact via `redactTokens`, but defence in depth.

For the **full template-substitution surface** (every `{token}` listed in the [notifications guide](/docs/packages/vis/guides/release-notifications#template-tokens)), you can implement the substitution manually or copy the built-in pattern: walk every string leaf, `replaceAll` each `{token}`, coerce non-string values via `String()`. The same logic backs every built-in channel, so emitting consistent tokens keeps your channel feeling first-class.

## Custom `VersionActions` [#custom-versionactions]

Use this when your package ships to a registry vis does not have a first-class adapter for: a private Verdaccio mirror, an internal Artifactory instance, a vendored Gemfury feed, a custom OCI registry workflow, a Helm chart museum. The generic `shell` actions handle most of these via a `publishCommand` string template — but that path is gated by `allowCustomCommands` (every operator running release has to opt in). For trusted, repo-local custom logic, the typed `VersionActions` plugin is cleaner.

### The interface [#the-interface-1]

```typescript
import { VersionActions, type PublishContext, type PublishResult } from "@visulima/vis/release/plugin-sdk";

abstract class VersionActions {
    /** Stable id (`"npm"`, `"cargo"`, `"shell"`, or a path for custom). */
    public abstract readonly id: string;

    /**
     * Read the current published version of this package from the registry.
     * Returns `undefined` for packages never published / not yet live.
     */
    public abstract readPublishedVersion(context: { pkg: WorkspacePackage; pm: PackageManagerAdapter }): Promise<string | undefined>;

    /**
     * Publish this package. Responsible for: protocol resolution, catalog
     * rewriting, clean-package-json, pack-then-publish via the adapter.
     */
    public abstract publish(context: PublishContext): Promise<PublishResult>;
}
```

`PublishContext` is the heavy one — it carries the workspace config, the per-package config, the planned release entry (with `newVersion`), the dist-tag, the dry-run flag, the OTP if applicable, the resolved registry URL, and a map of every other manifest being released in the same wave (so your `workspace:` / `catalog:` rewrites can resolve against the *bumped* versions, not the on-disk values).

Two abstract methods. Two return shapes. The minimum bar is "produce a value from a registry, push a tarball / artefact to that registry".

### Where it loads from [#where-it-loads-from-1]

Per-package config — `versionActions` accepts either a built-in id or a path:

```typescript
// vis.config.ts
export default {
    release: {
        packages: {
            "@scope/internal-package": {
                versionActions: "./.vis/release/verdaccio-actions.ts",
                // Per-package config your actions can read off
                // PublishContext.perPackageConfig:
                registry: "https://verdaccio.internal.example.com/",
            },
        },
    },
};
```

The path resolves relative to the workspace cwd; the module's `default` export must be a class extending `VersionActions` **or** a zero-arg factory returning an instance of one.

### What "publish" actually has to do [#what-publish-actually-has-to-do]

A typical implementation walks these steps:

1. **Read configuration off `context.perPackageConfig` / `context.workspaceConfig`.** Registry URL, auth env vars, OIDC settings.
2. **Pack the package** via `context.pm.pack(context.pkg.dir, ...)`. The active package manager (npm, pnpm, yarn, bun) handles workspace-aware packing.
3. **Strip non-publishable fields** from the manifest if `cleanPackageJsonConfig` is set. Helper: `cleanPackageJsonForPublish`.
4. **Rewrite `workspace:` / `catalog:` protocols** to concrete semver. Helpers: `rewriteRangeForVersion`, `rewriteCatalogRefs`.
5. **Push the tarball** to your registry. This is the part that varies.
6. **Return a `PublishResult`** — `{ published: boolean, output: string, ... }`.

For the full set of helpers, study `src/release/core/version-actions/npm.ts` (the canonical workhorse) and `src/release/core/version-actions/cargo.ts` (which uses an HTTP API for `readPublishedVersion` instead of shelling out — a good pattern to copy).

### The `allowCustomCommands` trust gate [#the-allowcustomcommands-trust-gate]

If your custom actions shell out (via `context.pm.runner.run("npm", ...)` or `child_process` directly), that is fine — actions code is repo-local and trusted. The trust gate (`release.allowCustomCommands`) applies only to **operator-configured shell strings** (`publishCommand`, `preReleaseCommand`, `checkPublished`) consumed by the generic `shell` actions. Your typed `VersionActions` plugin can shell out at will; you wrote it, you trust it.

For the **inverse** — if your actions plugin wants to *use* an operator-supplied `publishCommand` — copy the trust-gate evaluation pattern from the built-in `shell` actions (`packages/tooling/vis/src/release/core/version-actions/shell.ts`). It calls the workspace's `allowCustomCommands` check before evaluating any operator-supplied command string.

### Worked example: private Verdaccio actions [#worked-example-private-verdaccio-actions]

Imagine your team runs a private Verdaccio instance for internal-only packages. You do not want to use the default `npm` actions because:

* The auth flow is different (a long-lived token in `~/.npmrc` rather than `NPM_TOKEN` env).
* You want to GC the previous version's tarball after a successful publish.
* The `readPublishedVersion` path needs to query Verdaccio's HTTP API directly (npm CLI's `npm view` adds noisy timing overhead on a small registry).

A skeleton:

```typescript
// .vis/release/verdaccio-actions.ts
import { VersionActions, type PublishContext, type PublishResult } from "@visulima/vis/release/plugin-sdk";

export default class VerdaccioVersionActions extends VersionActions {
    public readonly id = "verdaccio" as const;

    /**
     * Query the Verdaccio HTTP API directly. Cheaper than `npm view`
     * (no subprocess), and lets us distinguish "404 / never published"
     * from "503 / registry unreachable" without parsing npm CLI output.
     */
    public async readPublishedVersion(context: Parameters<VersionActions["readPublishedVersion"]>[0]): Promise<string | undefined> {
        const registry = process.env.VERDACCIO_URL ?? "https://verdaccio.internal.example.com/";
        const url = `${registry.replace(/\/$/, "")}/${encodeURIComponent(context.pkg.name)}`;

        let response: Response;

        try {
            response = await fetch(url, {
                headers: { Authorization: `Bearer ${process.env.VERDACCIO_TOKEN ?? ""}` },
            });
        } catch {
            // Network failure — treat as "unknown" so the orchestrator
            // falls back to the manifest version. Do not throw —
            // readPublishedVersion is a probe, not a gate.
            return undefined;
        }

        if (response.status === 404) {
            return undefined; // package not in registry yet
        }

        if (!response.ok) {
            return undefined; // soft-fail; orchestrator handles fallback
        }

        const body = (await response.json()) as { "dist-tags"?: Record<string, string> };

        return body["dist-tags"]?.latest;
    }

    /**
     * Pack + publish to Verdaccio. Reuses the active adapter for the
     * pack step (so workspace: protocols resolve correctly) and shells
     * out for the upload (Verdaccio accepts the npm publish protocol).
     */
    public async publish(context: PublishContext): Promise<PublishResult> {
        const registry = context.registry ?? process.env.VERDACCIO_URL ?? "https://verdaccio.internal.example.com/";

        if (context.dryRun) {
            return {
                output: `[verdaccio:dry-run] would publish ${context.pkg.name}@${context.release.newVersion} to ${registry}`,
                published: false,
            };
        }

        // 1. Pack via the active adapter — npm/pnpm/yarn/bun all work.
        const packResult = await context.pm.pack(context.pkg.dir, {
            registry,
            tag: context.tag,
        });

        // 2. Push the tarball. `npm publish <tarball> --registry=...` works
        //    against any npm-protocol-compatible registry, Verdaccio included.
        const publishResult = await context.pm.runner.run(
            "npm",
            ["publish", packResult.tarballPath, `--registry=${registry}`, `--tag=${context.tag ?? "latest"}`],
            { cwd: context.pkg.dir, silent: false },
        );

        if (publishResult.exitCode !== 0) {
            throw new Error(`Verdaccio publish for ${context.pkg.name} failed (exit ${publishResult.exitCode}): ${publishResult.stderr.slice(0, 200)}`);
        }

        return {
            output: publishResult.stdout,
            published: true,
        };
    }
}
```

Wire it up per-package:

```typescript
// vis.config.ts
export default {
    release: {
        packages: {
            "@scope/internal-tools": {
                versionActions: "./.vis/release/verdaccio-actions.ts",
            },
            "@scope/internal-cli": {
                versionActions: "./.vis/release/verdaccio-actions.ts",
            },
        },
    },
};
```

The actions instance is constructed once per package per release wave — there is no shared state, so storing the registry URL in the instance is safe.

For the **full publish path** with catalog rewriting, clean-package-json, provenance flags, OTP handling, and stage-publish support, study `npm.ts` and `cargo.ts` — they implement the same interface and are dense with the corner-case handling a production-grade actions plugin needs. The skeleton above is the minimum bar; a real registry plugin will be three to five times longer.

## Custom `ChangelogFormatter` [#custom-changelogformatter]

Use this when neither the `default` formatter (plain Markdown), the `github` formatter (PR / commit / author links), nor the `keep-a-changelog` formatter (the [keepachangelog.com](https://keepachangelog.com) 1.1.0 layout) match your house style. Common reasons:

* You want emoji prefixes per change type (`✨ Features`, `🐛 Bug Fixes`).
* You ship to docs (Mintlify, Docusaurus) and need MDX-compatible output.
* You aggregate change-file metadata your tool reads downstream.

### The interface [#the-interface-2]

```typescript
import { defineChangelogFormatter, type ChangelogContext, type ChangelogFormatter, type ChangelogTarget } from "@visulima/vis/release/plugin-sdk";

type ChangelogTarget = "changelog" | "github-release";

interface ChangelogContext {
    /** All change files contributing to this release (may be empty for pure dep bumps). */
    changeFiles: ChangeFile[];
    /** ISO date string `YYYY-MM-DD`. */
    date: string;
    /** The release entry being rendered. */
    release: PlannedRelease;
    /** Where the rendered output is going. */
    target: ChangelogTarget;
}

type ChangelogFormatter = (context: ChangelogContext) => string | Promise<string>;
```

`defineChangelogFormatter` is an identity wrapper that gives your default export a typed signature; the source also exposes the same helper as `defineFormatter` from the deeper module for backwards compatibility.

A single function. Input: a `ChangelogContext`. Output: a Markdown string. The same formatter is invoked twice per release:

* `target: "changelog"` — output gets prepended to `packages/<name>/CHANGELOG.md` (and the workspace-level `CHANGELOG.md` aggregate).
* `target: "github-release"` — output becomes the body of the GitHub / GitLab release.

The convention: for `"github-release"`, **omit the version heading** (`## 1.2.3`). The release's own UI already shows the version above the body; a duplicate heading looks broken. The built-in `default` formatter does this; copy that pattern.

### Where it loads from [#where-it-loads-from-2]

```typescript
// vis.config.ts
export default {
    release: {
        // Built-in id — `"default"`, `"github"`, or `"keep-a-changelog"`:
        changelog: "github",
        // Or false — no-op formatter (writes nothing):
        // changelog: false,
        // Or string path to a custom module:
        // changelog: "./.vis/release/my-formatter.ts",
        // Or tuple — path + options for a factory:
        // changelog: ["./.vis/release/my-formatter.ts", { authorCredit: true }],
    },
};
```

For a custom module, the path resolves relative to the workspace cwd. The module's `default` export is either:

* A `ChangelogFormatter` function directly (string form, or tuple-but-not-a-factory).
* A factory `(options) => ChangelogFormatter` (tuple form).

The resolver detects which by probing — it calls the export with the options first; if the call returns a function, that is treated as the formatter; otherwise the export itself is the formatter. Both patterns work. Use `defineChangelogFormatter` for the typed wrapper:

```typescript
import { defineChangelogFormatter } from "@visulima/vis/release/plugin-sdk";

export default defineChangelogFormatter((context) => {
    return `## ${context.release.newVersion}\n…`;
});
```

### Worked example: emoji-prefixed Keep-a-Changelog hybrid [#worked-example-emoji-prefixed-keep-a-changelog-hybrid]

Suppose you want the Keep-a-Changelog layout — `### Added | Changed | Fixed | Security` — but with an emoji prefix per section (`### ✨ Added`, `### 🔧 Changed`, …) and a small Conventional-Commits bucketing rule on top: anything that starts with `feat:` goes to Added, `fix:` to Fixed, `security:` to Security, `deprecate:` to Deprecated, `refactor:` / `perf:` / `chore:` to Changed.

```typescript
// .vis/release/emoji-keep-a-changelog.ts
import { defineChangelogFormatter, type ChangelogContext, type ChangelogFormatter } from "@visulima/vis/release/plugin-sdk";

export interface EmojiFormatterOptions {
    /** Owner/repo for the trailing comparison link. */
    repo?: string;
    /** Section-emoji overrides. Defaults below. */
    emoji?: Partial<Record<Section, string>>;
}

type Section = "Added" | "Changed" | "Deprecated" | "Removed" | "Fixed" | "Security";

const SECTIONS_IN_ORDER: ReadonlyArray<Section> = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"];

const DEFAULT_EMOJI: Record<Section, string> = {
    Added: "✨",
    Changed: "🔧",
    Deprecated: "⚠️",
    Removed: "🗑️",
    Fixed: "🐛",
    Security: "🔒",
};

const PREFIX_MAP: Record<string, Section> = {
    feat: "Added",
    feature: "Added",
    fix: "Fixed",
    bugfix: "Fixed",
    perf: "Changed",
    refactor: "Changed",
    chore: "Changed",
    deprecate: "Deprecated",
    deprecated: "Deprecated",
    remove: "Removed",
    removed: "Removed",
    security: "Security",
    sec: "Security",
};

const CONVENTIONAL_RE = /^([a-z]+)(?:\([^)]+\))?!?:\s+(.*)$/i;

const classify = (line: string, bumpLevel: "major" | "minor" | "patch"): { section: Section; text: string } => {
    const stripped = line.replace(/^[-*]\s+/, "").trim();
    const match = CONVENTIONAL_RE.exec(stripped);

    if (match) {
        const [, type, rest] = match;
        const section = PREFIX_MAP[type!.toLowerCase()];

        if (section) {
            return { section, text: rest! };
        }
    }

    // Fall back to bump level: major → Changed (likely breaking), minor → Added, patch → Fixed.
    const fallback: Section = bumpLevel === "major" ? "Changed" : bumpLevel === "minor" ? "Added" : "Fixed";

    return { section: fallback, text: stripped };
};

/**
 * Default export is a FACTORY. The config tuple `[path, options]` passes
 * the options through. Plain `path` (no tuple) invokes the factory with
 * no arguments — handled by the `?? {}` fallback below.
 */
export default (options: EmojiFormatterOptions = {}): ChangelogFormatter =>
    defineChangelogFormatter((context: ChangelogContext): string => {
        const { changeFiles, date, release, target } = context;
        const buckets: Record<Section, string[]> = {
            Added: [],
            Changed: [],
            Deprecated: [],
            Removed: [],
            Fixed: [],
            Security: [],
        };

        const bumpLevel = release.bumpLevel ?? "patch";

        for (const file of changeFiles) {
            for (const rawLine of file.body.split(/\r?\n/)) {
                const line = rawLine.trim();

                if (!line) {
                    continue;
                }

                const { section, text } = classify(line, bumpLevel as "major" | "minor" | "patch");

                buckets[section].push(`- ${text}`);
            }
        }

        const emoji = { ...DEFAULT_EMOJI, ...(options.emoji ?? {}) };
        const lines: string[] = [];

        // Version heading — only for the CHANGELOG.md target. The github-release
        // target omits it because the release UI already shows the version.
        if (target !== "github-release") {
            lines.push(`## [${release.newVersion}] - ${date}`);
            lines.push("");
        }

        for (const section of SECTIONS_IN_ORDER) {
            if (buckets[section].length === 0) {
                continue;
            }

            lines.push(`### ${emoji[section]} ${section}`);
            lines.push("");
            lines.push(...buckets[section]);
            lines.push("");
        }

        if (release.isCascadeBump || release.isGroupBump) {
            for (const source of release.sources) {
                const verb = release.isCascadeBump ? "Cascade from" : "Group bump with";

                lines.push(`- ${verb} \`${source.name}@${source.newVersion}\``);
            }
        } else if (release.isDependencyBump && changeFiles.length === 0) {
            for (const source of release.sources) {
                lines.push(`- Updated dependency \`${source.name}@${source.newVersion}\``);
            }
        }

        // Optional comparison link footer — Keep-a-Changelog convention.
        if (options.repo && target !== "github-release") {
            lines.push("");
            lines.push(`[${release.newVersion}]: https://github.com/${options.repo}/compare/v${release.oldVersion}...v${release.newVersion}`);
        }

        return lines
            .join("\n")
            .replace(/\n{3,}/g, "\n\n")
            .trim();
    });
```

Wire it up:

```typescript
// vis.config.ts
export default {
    release: {
        changelog: [
            "./.vis/release/emoji-keep-a-changelog.ts",
            {
                repo: "foo/bar",
                emoji: {
                    Added: "🎁", // override the default ✨
                },
            },
        ],
    },
};
```

A few observations:

* **`defineFormatter` is the typed wrapper.** It does nothing at runtime — just preserves the function reference under the typed name so editors infer the parameter and return types. Optional but recommended.
* **The factory pattern is cleanest for options.** Plain default-export-as-formatter works too, but the factory form gets you typed options and lets the formatter close over them without polluting the global scope.
* **The `target` field disambiguates `CHANGELOG.md` from the GH release body.** Always check it before emitting a top-level version heading — otherwise your GH releases will look like they have a duplicate title.
* **The same formatter runs for cascade / group / dependency-only bumps.** When `release.changeFiles` is empty, the synthetic source-package list at the bottom is your only output; do not skip the function early on empty change files.

### Re-using built-in formatters [#re-using-built-in-formatters]

To layer a small tweak on top of a built-in — e.g. the github formatter with a footer — set `release.changelog` to the built-in id in your config and wrap the rendered output with a post-process step in your CI. For deeper composition (calling `createGithubFormatter` directly), copy the formatter logic into your own module: the built-in factories live at `packages/tooling/vis/src/release/core/changelog/{default,github,keep-a-changelog}.ts` and are not re-exported from the plugin SDK.

## Cross-references [#cross-references]

* **Plugin SDK** — `@visulima/vis/release/plugin-sdk`. All three surfaces (`NotificationChannel`, `VersionActions`, `ChangelogFormatter`) plus their `define*` identity wrappers re-export from one path.
* **Notifications behaviour** — see [Release notifications](/docs/packages/vis/guides/release-notifications) for the dispatch flow, template tokens, and `--resume` dedup contract.
* **Version-resolver modes** — see [First-release & version resolver](/docs/packages/vis/guides/release-first-release-and-resolver) for `currentVersionResolver` (which routes through `versionActions.readPublishedVersion()` in `registry` mode).
* **Built-in source** — `packages/tooling/vis/src/release/core/{notifications,version-actions,changelog}/`. Each directory has a small set of reference implementations (`npm.ts`, `cargo.ts`, `slack.ts`, …) worth reading before authoring your own.

## Common pitfalls [#common-pitfalls]

* **Forgetting the `id` field.** Every `NotificationChannel` and every `VersionActions` instance needs a stable `id`. It surfaces in log lines, in `result.failed[].id`, and in the `state.notified` ledger. Two channels with the same `id` are indistinguishable to operators reading CI logs.
* **Logging the URL on failure.** Webhook URLs frequently contain bearer secrets. Wrap your `fetch` rejection and emit a message that never includes the URL. The dispatcher's `redactTokens` is defence-in-depth, not a primary defence.
* **Mutating `context.published` / `context.release`.** Both objects are `Readonly` by convention (the types use `ReadonlyArray<…>`). Some channel implementations would otherwise sort the package list in place, breaking the next channel that runs in parallel. Treat the context as immutable input.
* **Throwing from `readPublishedVersion`.** This method is a probe — the orchestrator treats `undefined` as "not yet published" and falls back gracefully. A thrown error from your implementation propagates and fails the release. Always wrap network calls in try/catch and return `undefined` on transport failure; let the publish path surface real auth / network errors separately.
* **Skipping the `dry-run` branch in `publish`.** Every `VersionActions.publish` implementation must respect `context.dryRun` — return a no-op `PublishResult` with `published: false`. `vis release version --dry-run` and `vis release publish --dry-run` rely on this; an actions plugin that ignores the flag will accidentally publish from a preview run.
* **Emitting the `## <version>` heading in `target: "github-release"`.** The release UI prepends its own version label; your `##` heading duplicates it. Always branch on `target` before writing the version line.


# Staged publishing (human-approved npm releases) (/docs/packages/vis/guides/release-staged-publishing)



# Staged publishing [#staged-publishing]

Use this when a maintainer must approve every npm publish with 2FA before the version becomes installable — typically for high-trust packages, SOX-style separation-of-duties, or OIDC-without-2FA pipelines.

npm 11.15.0 introduced **staged publishing**: instead of `npm publish` landing a version directly on the registry, it uploads a tarball into a holding area and waits for a maintainer to approve it with 2FA. Until approval, the version is **not installable**; it just exists as a stage record.

vis turns this into a release-manager feature. Opt into staging, and every publish wave blocks until a maintainer approves. CI stays green on rejection or timeout. The workflow self-heals when approvals happen out-of-band. A tracked file in your repo (`.vis/release/staged.json`) is the single source of truth for what's still pending.

> ⚠ &#x2A;*Requirements:*&#x2A; npm CLI **≥ 11.15.0**, registry **registry.npmjs.org** (staging is an npm Inc. feature — Verdaccio, GitHub Packages, Artifactory don't implement it). `vis release doctor` surfaces both prereqs.

## Why use staging [#why-use-staging]

A typical release pipeline gives reviewers exactly **one** synchronous gate: "did this PR pass CI?". Everything else — version bump, changelog, tag push, npm publish — is automated. That works until you ship a version that shouldn't have shipped: a leaked credential, a missed `.npmignore`, a typo in the entry point. By then the tarball is on the registry, immutable, indexed by every mirror.

Staging adds a **second** gate, scoped to the moment the tarball is uploaded but **before** anyone can `npm install` it. A maintainer reviews the staged tarball on npmjs.com (or via `npm stage view <id>`), confirms identity with 2FA, and only then is the version promoted to "installable". Rejection costs nothing — the staged tarball gets garbage-collected.

## Enable it [#enable-it]

In `vis.config.ts`:

```typescript
export default {
    release: {
        publish: {
            stage: true,
        },
    },
};
```

That's it for the defaults: 30-minute approval timeout, 15-second poll interval. The full shape:

```typescript
release: {
    publish: {
        stage: {
            // Hard deadline for the approval wait. Past this, the publish
            // gives up with a `::warning::` and CI exits 0. Default: 30m.
            timeoutMs: 30 * 60 * 1000,
            // How often vis polls `npm stage view <id>` to detect a
            // decision. Lower → faster pickup; higher → gentler on npm's
            // API. Default: 15s.
            pollIntervalMs: 15 * 1000,
        },
    },
},
```

> 💡 &#x2A;*Per-package opt-in?** Not currently — `publish.stage` is workspace-wide. Either every managed package stages or none do.

## The happy path [#the-happy-path]

```mermaid
sequenceDiagram
    autonumber
    actor Dev as Developer
    participant PR as GitHub PR
    participant CI as CI runner
    participant npm as registry.npmjs.org
    actor Maint as Maintainer
    participant Git as git remote

    Dev->>PR: merge change-file + code
    PR->>CI: trigger release workflow
    CI->>CI: vis release version<br/>(bump + changelog)
    CI->>Git: push version commit
    CI->>CI: vis release publish
    CI->>npm: npm publish --stage
    npm-->>CI: stage-xyz (pending)
    Note over CI: heartbeat every 5m<br/>poll every 15s
    Maint->>npm: review staged tarball
    Maint->>npm: approve + 2FA
    CI->>npm: poll stage view → 404
    CI->>npm: npm view pkg@1.2.0 dist.tarball
    npm-->>CI: tarball URL (= approved)
    CI->>Git: git tag pkg@1.2.0
    CI->>Git: git push --tags
    CI->>Git: create GitHub/GitLab release
    CI-->>PR: ✅ exit 0
```

That's the whole story when approvals happen within the timeout. The maintainer sees "this release is waiting for me" on npmjs.com, clicks approve with 2FA, and the pipeline finishes itself.

## What happens when things don't go smoothly [#what-happens-when-things-dont-go-smoothly]

This is the part that matters. Every failure mode is recoverable, none of them fail CI.

### The stage lifecycle [#the-stage-lifecycle]

A stage record on npm transitions between four states. The CI side of vis tracks the **decision** vis observed (which may lag the registry state) and routes per-package outcomes accordingly.

```mermaid
stateDiagram-v2
    [*] --> Staged: npm publish --stage
    Staged --> Approved: maintainer + 2FA<br/>(via npmjs.com or<br/>vis release stage approve)
    Staged --> Rejected: maintainer + 2FA<br/>(via npmjs.com or<br/>vis release stage reject)
    Staged --> TimedOut: timeoutMs elapsed<br/>(CI side only —<br/>npm still considers it Staged)
    TimedOut --> Approved: operator approves later<br/>(self-heal on next wave)
    TimedOut --> Rejected: operator rejects later
    Approved --> [*]: tag + GitHub release + clean registry
    Rejected --> [*]: drop from staged.json,<br/>fix the bug, ship next version
    note right of TimedOut
        npm has no documented TTL.
        Stages persist until the
        operator resolves them.
    end note
```

The boundary between **Staged** and **TimedOut** is vis's invention — npm itself just keeps the record sitting in the holding area. vis introduces the timeout so CI doesn't pin a runner indefinitely; the actual stage outlives the timeout and can still be approved.

### Failure mode 1: approval takes longer than `timeoutMs` [#failure-mode-1-approval-takes-longer-than-timeoutms]

Past the deadline (30 minutes by default), `waitForStageDecision` returns `"timeout"`. The publish step writes:

```
::warning::Stage stage-xyz timed out waiting for approval (30m).
            Approve via npm 2FA or `vis release stage approve stage-xyz`.

  [stage]   @scope/pkg  (stage-timeout — re-run `vis release publish` once approved)
```

* **CI exits 0** (not failure)
* **No git tag** is created
* **No GitHub/GitLab release** is created
* The stage **stays pending on npm's side** — npm has no documented TTL on staged versions (verified empirically: a stage sat for 4h30m without npm touching it)
* **`stage-xyz` is appended to `.vis/release/staged.json`** with `reason: "timeout"`
* The publish flow then &#x2A;*commits `staged.json`** with message `chore(release): record 1 pending stage [skip ci]` and pushes it, so the next CI run (and any local clone) sees the pending state

Three ways back to a successful publish:

```bash
# A — operator approves locally with 2FA
vis release stage approve stage-xyz
# This calls `npm stage approve`, then drains stage-xyz from staged.json,
# commits the registry, and pushes. The next CI run picks up where we left off.

# B — drain everything pending from a single command
vis release stage approve --all

# C — approve via the npmjs.com UI directly
# Then re-run the workflow. The publish step's preflight self-heals:
# it calls `npm view pkg@1.2.0 dist.tarball`, sees the version is live,
# silently drains the entry from staged.json, and proceeds. No manual edit
# needed.
```

If 30 minutes is too tight for your review schedule, bump it workspace-wide:

```typescript
release: {
    publish: { stage: { timeoutMs: 4 * 60 * 60 * 1000 } },   // 4 hours
},
```

The poll interval (`pollIntervalMs`) is also tunable if you want to be gentler on npm's API for very long waits.

### Failure mode 2: a maintainer rejects the stage [#failure-mode-2-a-maintainer-rejects-the-stage]

`npm stage view <id>` returns 404 (stage record gone), but `npm view <pkg>@<version> dist.tarball` returns empty — meaning the version was **rejected**, not promoted. The publish step writes:

```
::warning::Stage rejected for @scope/pkg@1.2.0 (id stage-xyz).
            Re-stage by re-running the release once the review feedback is addressed.

  [stage]   @scope/pkg  (stage-rejected — re-run `vis release publish` once approved)
```

Same outcome as timeout: CI exits 0, no tag, no GH release, registry entry recorded with `reason: "rejected"`, `staged.json` committed + pushed.

Recovery is different though — a rejection means the version **shouldn't ship** as-is. The standard path is:

```bash
# 1. Address the feedback (new commit fixes the issue)
git commit -am "fix(pkg): address review feedback"

# 2. Add a new change file describing the fix
vis release add --packages '@scope/pkg:patch' --message 'Address staging review feedback'

# 3. Drop the rejected entry from staged.json (the published 1.2.0 will never exist)
vis release stage reject stage-xyz   # if not already auto-cleaned by npm
# or just edit .vis/release/staged.json directly and commit

# 4. Push — CI bumps to 1.2.1 (skipping 1.2.0) and stages again
```

> 💡 &#x2A;*The orphan CHANGELOG section (per-package).** Per-package `CHANGELOG.md` sections are written during the **version** phase — they reflect INTENT, not what actually shipped. If wave N wrote a `## 1.2.0` section to `packages/pkg/CHANGELOG.md` and that version then got rejected at the stage gate, the section references a version that never installed. The `vis release stage reject <id>` command prints an edit hint pointing at the affected files — open each one and remove (or merge into the next release section) the orphan `## 1.2.0` block before the next wave ships.
>
> 💡 &#x2A;*Workspace `CHANGELOG.md` is safe.** The root `CHANGELOG.md` wave entry is written from the **publish** phase using `result.published[]`, so rejected stages never produce a workspace-level orphan. The wave entry is appended by `vis release publish` after tag-push and committed with `chore(release): record wave [skip ci]`. No manual cleanup needed for the workspace aggregate.
>
> *Why not auto-edit per-package CHANGELOGs on reject?* It's too risky: the operator may have already amended the section with extra context (review feedback, security advisory), and clobbering that work to "fix" the orphan would lose information. The CLI prints the path and leaves the file alone — operator drives the cleanup.

### Failure mode 3: a new commit triggers a release while a stage is pending [#failure-mode-3-a-new-commit-triggers-a-release-while-a-stage-is-pending]

This is the case the **guardrail** is designed for. Imagine:

```
T+0min   pkg@1.2.0 staged. Stage-xyz pending. CI timed out.
T+10min  Someone merges a small fix. CI fires `vis release version`.
```

**Without the guardrail** — vis would happily bump `package.json` to `1.2.1`, write a new changelog entry, publish a fresh `pkg@1.2.1` stage, and now you have **two parallel pending tarballs** for the same package. Maintainers see two "approve" buttons. If both get approved, npm publishes them out of order (1.2.0 lands after 1.2.1 if your maintainer clicks them that way). If only 1.2.1 gets approved, 1.2.0 is orphaned with a changelog section referencing it.

**With the guardrail**, `vis release version` and `vis release publish` both refuse:

```
Refusing to version — 1 package(s) have a pending stage from a prior wave:
  • @scope/pkg@1.2.0 — stage stage-xyz (timeout, recorded 2026-05-22T14:00:00.000Z)

Next steps: Resolve via `vis release stage approve <id>` / `--all` or
            `vis release stage reject <id>`, commit the updated staged.json,
            then retry.

Exit code 1.
```

The guard reads `.vis/release/staged.json` (the same file the publish step writes) and refuses any operation on a package with a pending entry. Self-healing kicks in **before** the throw: it runs `npm view <pkg>@<version> dist.tarball` for each conflicting entry; if the version is live (operator approved out-of-band), the entry is silently drained and the operation proceeds.

So the actual decision tree at the start of every wave is:

```mermaid
flowchart TD
    A[vis release version<br/>or vis release publish] --> B{staged.json<br/>has entries?}
    B -- no --> Z[proceed]
    B -- yes --> C{any entry's<br/>package in the<br/>current plan?}
    C -- no --> Z
    C -- yes --> D{same version<br/>as the plan?}
    D -- "yes — RESUME case" --> Z
    D -- "no — orphan risk" --> E[run npm view pkg@version<br/>dist.tarball for each<br/>still-pending entry]
    E --> F{tarball URL<br/>returned?}
    F -- "yes — approved<br/>out-of-band" --> G[drain entry from<br/>staged.json]
    G --> H{any entries<br/>still pending?}
    H -- no --> Z
    H -- yes --> X[throw STAGE_PENDING<br/>exit 1]
    F -- "no — still pending<br/>or rejected" --> X

    classDef block fill:#fee,stroke:#c33,stroke-width:2px
    classDef pass fill:#efe,stroke:#393,stroke-width:2px
    class X block
    class Z pass
```

> 🔧 &#x2A;*Why does the guard refine by version?**
>
> * **Same `(name, version)` is the resume case** — `vis release publish --resume` after a timed-out wave needs to re-attempt the SAME version. Blocking would break resume entirely.
> * **Different version is the orphan-risk case** — a re-version to `1.2.1` while `1.2.0` is still staged would either leave 1.2.0 orphaned (changelog references it but it never installs) or land both out of order if both eventually get approved.

### Failure mode 4: mixed waves (some approved, some rejected/timed-out) [#failure-mode-4-mixed-waves-some-approved-some-rejectedtimed-out]

A release wave of 5 packages where 3 get approved and 2 hit the timeout works **as intended**:

```
Published:  3   (got tags + GH releases + workspace changelog wave entry)
Skipped:    2   (stage-timeout / stage-rejected, recorded in staged.json)
Failed:     0

Tags created: 3 (pushed)
```

Exit code: **0** — a partial publish with no failures isn't a failure. The 3 approved packages are live and tagged; the 2 pending sit in `staged.json` waiting for the operator.

The next release wave will refuse to touch those 2 packages until they're resolved — but the other 47 packages in your workspace can release independently. Granularity is per-package.

### Failure mode 5: registry / network hiccup mid-poll [#failure-mode-5-registry--network-hiccup-mid-poll]

`waitForStageDecision` polls `npm stage view <id>` every `pollIntervalMs`. A transient network blip returns a non-zero exit code that looks identical to "stage no longer exists" (decision made). The disambiguation step (`npm view <pkg>@<version> dist.tarball`) catches this:

* Tarball URL on stdout → version is live → **approved**
* 404 / empty output → version isn't live → **rejected** (or never staged at all, which we treat as rejection)
* npm itself isn't on PATH (e.g. CI runner stripped it mid-job) → **timeout** path eventually trips after `timeoutMs`

A *truly* unrecoverable polling error (e.g. npm CLI segfaults) would bubble up as a hard publish failure → `result.failed[]` → CI exits non-zero. That's the right behaviour — something is broken with the runtime, not with the release.

## The state files [#the-state-files]

vis maintains two files in `.vis/release/`. They serve different purposes:

| File          | Tracked in git?     | Lifecycle                                      | Purpose                                           |
| ------------- | ------------------- | ---------------------------------------------- | ------------------------------------------------- |
| `.state.json` | **No** (gitignored) | Per-wave; deleted on full success              | Resume-from-failure within a single release wave  |
| `staged.json` | **Yes** (committed) | Long-lived; only entries for unresolved stages | Pending-stage registry — survives CI runner churn |

The two files have distinct timelines — `.state.json` lives only as long as one wave is in flight; `staged.json` is the long-lived record:

```mermaid
flowchart LR
    subgraph Wave1[Wave 1 — timed out]
        direction TB
        W1A[publish starts:<br/>.state.json created] --> W1B[stage uploaded:<br/>staged.json gets entry]
        W1B --> W1C[timeout fires:<br/>commit + push staged.json,<br/>.state.json kept for --resume]
    end

    subgraph Approve[Operator approves]
        direction TB
        OP[vis release stage approve stage-id<br/>or out-of-band on npmjs.com]
    end

    subgraph Wave2[Wave 2 — success]
        direction TB
        W2A[publish starts:<br/>fresh .state.json] --> W2B[guard self-heals,<br/>drains staged.json entry]
        W2B --> W2C[tag + GH release created]
        W2C --> W2D[.state.json deleted,<br/>staged.json committed as empty<br/>then removed]
    end

    Wave1 --> Approve --> Wave2

    classDef gone fill:#fef,stroke:#999
    classDef live fill:#efe,stroke:#393
    class W2D gone
    class W1C live
```

### `.vis/release/staged.json` [#visreleasestagedjson]

The committed source of truth. Schema:

```json
{
    "version": 1,
    "updatedAt": "2026-05-22T14:30:00.000Z",
    "pending": [
        {
            "id": "stage-xyz",
            "name": "@scope/pkg",
            "version": "1.2.0",
            "tag": "latest",
            "reason": "timeout",
            "stagedAt": "2026-05-22T14:00:00.000Z"
        }
    ]
}
```

vis writes it after every publish wave. If the wave produced new pending entries, the file is created/updated with a commit:

```
chore(release): record 1 pending stage [skip ci]
```

If the wave drained the last pending entry (everything approved), the file is **deleted** with a commit:

```
chore(release): clear pending stage registry [skip ci]
```

The `[skip ci]` tag is recognised by GitHub Actions and GitLab CI — it prevents the chore commit from triggering another release cycle, which would otherwise create a noise loop.

> 💡 **Don't edit `staged.json` by hand** unless you really mean it. Stale entries cause confusing guard failures; bogus entries can block a release for a package that doesn't have a real pending stage. Use the `vis release stage` commands.

### `.vis/release/.state.json` [#visreleasestatejson]

Per-wave resume state — exits with the wave. Holds `published`, `applied`, `tagged`, `pushed` arrays so a partial-failure wave can resume via `vis release publish --resume`. **Not** related to staging — the staged-publish registry is intentionally separated so the long-lived pending state isn't tied to the short-lived per-wave state.

## Operator workflow [#operator-workflow]

### Recovery overview [#recovery-overview]

When you find yourself with a pending stage that needs attention, the three recovery paths are:

```mermaid
flowchart LR
    Start[Pending stage in<br/>staged.json] --> Q1{Is the change<br/>still good?}

    Q1 -- "yes — ship it" --> A1[vis release stage<br/>approve stage-id]
    A1 --> A2[2FA prompt<br/>in terminal]
    A2 --> A3[staged.json drained,<br/>committed, pushed]
    A3 --> A4[Re-run workflow:<br/>tag + GH release created]

    Q1 -- "yes, multiple<br/>stages stuck" --> B1[vis release stage<br/>approve --all]
    B1 --> A2

    Q1 -- "no — review failed" --> C1[vis release stage<br/>reject stage-id]
    C1 --> C2[staged.json drained,<br/>committed, pushed]
    C2 --> C3[Fix the issue,<br/>add new change file,<br/>ship next version]

    Q1 -- "approved on<br/>npmjs.com already" --> D1[Re-run workflow]
    D1 --> D2[Guard self-heals,<br/>tag + GH release created]

    classDef good fill:#efe,stroke:#393
    classDef bad fill:#fef
    class A4,D2,C3 good
```

### Day-to-day: nothing changes [#day-to-day-nothing-changes]

If approvals happen within the timeout, every operator interaction is on npmjs.com (or via `vis release stage approve <id>`). The CI workflow is unchanged from non-staged publishing.

### Workflow for a timed-out stage [#workflow-for-a-timed-out-stage]

```bash
# 1. See what's pending
vis release stage list
#   stage-xyz  @scope/pkg@1.2.0  → latest

# 2. Approve (2FA prompt opens in terminal)
vis release stage approve stage-xyz
#   ✓ Approved stage-xyz
#   Updated .vis/release/staged.json and committed + pushed.

# 3. Re-run the workflow to create the tag + GH release
#    (or wait for the next CI run — `--resume` picks up automatically)
```

### Workflow for an out-of-band approval [#workflow-for-an-out-of-band-approval]

If you approved on npmjs.com directly (maybe you were already there reviewing) and didn't run `vis release stage approve`:

```bash
# Re-run the workflow. The publish preflight detects the version is live,
# drains the registry entry, and proceeds. CI exits 0 with the tag + GH
# release in place.
```

No manual `staged.json` edit needed. Just retry.

### Workflow for a rejected stage [#workflow-for-a-rejected-stage]

```bash
# 1. Drain the registry entry locally (npm has already auto-removed the stage)
vis release stage reject stage-xyz

# 2. Address the review feedback
#    (fix the issue, write a new change file, push)

# 3. CI runs again — fresh stage for the next version (e.g. 1.2.1)
```

### Workflow when the timeout fires repeatedly [#workflow-when-the-timeout-fires-repeatedly]

If your team's review cadence is longer than 30 minutes, the timeout fires every CI run, the workflow exits 0, and the operator approves later. Working as designed — but if it's persistent noise, just bump `timeoutMs`:

```typescript
release: {
    publish: { stage: { timeoutMs: 8 * 60 * 60 * 1000 } },   // 8 hours
},
```

## CLI reference [#cli-reference]

### `vis release stage list` [#vis-release-stage-list]

Lists pending stages from both sources — npm's `stage list` and the local `staged.json`. Entries get a tag indicating where they came from:

```
$ vis release stage list

  stage-xyz  @scope/pkg@1.2.0  → latest
  stage-abc  @scope/other@2.0.1  → next  [registry-only, timeout]
  stage-def  @other/dep@0.5.0  → latest  [npm-only]
```

* **No tag** → both sources agree (the common case)
* **`[npm-only]`** → npm sees the stage but vis didn't record it (manual `npm stage publish` outside vis)
* **`[registry-only, <reason>]`** → vis recorded it but npm's view doesn't return it (different auth scope, OIDC token without stage:read permission, or stale registry entry)

### `vis release stage approve <stage-id>...` [#vis-release-stage-approve-stage-id]

Calls `npm stage approve` (2FA-interactive), then drains successful ids from `staged.json`, commits the registry with `chore(release): approve <n> stage(s) [skip ci]`, and pushes.

Flags:

* `--all` — approve every entry in `staged.json` sequentially (one 2FA prompt per stage; terminal-friendly)
* `--no-commit` — update the registry on disk but skip the commit (useful for local triage)
* `--no-push` — commit but don't push (useful for batched ops)

### `vis release stage reject <stage-id>...` [#vis-release-stage-reject-stage-id]

Same flow as approve, but calls `npm stage reject` and uses commit message `chore(release): reject <n> stage(s) [skip ci]`.

### `vis release doctor` [#vis-release-doctor]

Surfaces pending stages as a warning:

```
[warn]  publish-stage.pending — 1 pending stage(s) recorded in .vis/release/staged.json:
        @scope/pkg@1.2.0 (timeout). Approve / reject before the next release:
        vis release stage approve --all
```

Also checks npm version (≥ 11.15.0) and registry (must be npmjs.com).

## Concurrency model [#concurrency-model]

The release flow needs to be serialised — two parallel `vis release publish` invocations on the same branch could both stage tarballs for the same versions, both append to `staged.json`, and one's push would fail non-fast-forward. vis enforces serialisation at two layers:

* **Per-machine** — a `.vis/release/.lock` file (1h staleness check) prevents two `vis release publish` invocations on the same machine. `vis release stage approve|reject` acquires the same lock so a local approval doesn't race with an in-progress CI publish.
* **Per-CI-branch** — the generated workflows ship with native concurrency primitives:
  * GitHub Actions: `concurrency: { group: vis-release-${{ github.ref }}, cancel-in-progress: false }` — queues a second push behind the first.
  * GitLab CI: `resource_group: vis-release-$CI_COMMIT_BRANCH` — only one job per resource group runs at a time.

> ⚠ &#x2A;*Cross-machine local races aren't guarded.** Two developers running `vis release publish` on different machines against the same branch can't see each other's lockfile. The remote-side guard is the git push: only one branch update succeeds, the other gets `non-fast-forward` and re-runs.

## Limitations [#limitations]

Some are inherent to npm's stage API; others are vis's current scope.

* **Per-package opt-in is not supported.** `publish.stage: true` enables staging for every managed package in the workspace.
* **OIDC trusted publishing + `publishConfig.access: "restricted"` is refused at preflight.** OIDC tokens don't have read scope on restricted packages, so the disambiguation step (`npm view <pkg>@<version> dist.tarball`) can't authenticate. Use `NPM_TOKEN` for restricted-access packages.
* **No push notifications.** vis polls `npm stage view <id>` because npm doesn't surface webhooks or any kind of "stage decided" event. The polling overhead is bounded by `pollIntervalMs` (default 15s).
* **No registry-side TTL surfaced.** npm doesn't document how long a stage record lives. Empirically, stages persist indefinitely until approved/rejected. vis's `timeoutMs` is purely a CI-side patience limit — it has no effect on npm.

## Comparison with non-staged publish [#comparison-with-non-staged-publish]

|                                      | Without staging                    | With staging                                        |
| ------------------------------------ | ---------------------------------- | --------------------------------------------------- |
| Publish takes                        | Seconds                            | Minutes (wait for human)                            |
| 2FA required at publish time         | Configurable (`npm publish --otp`) | Always (`npm stage approve`)                        |
| Rollback if bad publish              | Mostly impossible (immutable)      | Free — reject the stage                             |
| CI green on rejection                | N/A                                | ✅                                                   |
| Resume after CI runner restart       | Via `.state.json`                  | Via committed `staged.json`                         |
| Webhook on publish                   | npmjs.com webhooks                 | npmjs.com webhooks (after promotion)                |
| Out-of-order risk for parallel waves | Low (no human gate)                | **Mitigated by the guardrail** — see Failure Mode 3 |

## Related [#related]

* [Release manager guide](/docs/packages/vis/guides/release) — overall release subsystem
* [Release CI integration](/docs/packages/vis/guides/release-ci) — running releases from GitHub Actions / GitLab CI
* [`vis release stage`](/docs/packages/vis/commands/release#release-stage) — full CLI reference


# Release manager (/docs/packages/vis/guides/release)



# Release manager [#release-manager]

`vis release` is a release tool for JavaScript and TypeScript monorepos. You write a small markdown file when you change a package, commit it, and CI does the rest: bumps versions, writes changelogs, pushes git tags, and publishes to npm.

It is the workspace-aware successor to [bumpy](https://github.com/anolilab/bumpy) and a drop-in replacement for [changesets](https://github.com/changesets/changesets), [semantic-release](https://github.com/semantic-release/semantic-release), and [release-please](https://github.com/googleapis/release-please) — see the [comparison page](/docs/packages/vis/guides/release-comparison).

> ⚠ &#x2A;*Unstable.** The public API may break across minor versions until the subsystem clears its stability bar (≥3 months without breaking changes, all visulima packages migrated, ≥1 external adopter). Set `release.acknowledgeUnstable: true` in `vis.config.ts` (or export `VIS_RELEASE_SUPPRESS_UNSTABLE=1`) to silence the startup warning.

## Quick start [#quick-start]

From zero to your first shipped version in five minutes.

### 1. Initialise [#1-initialise]

```bash
vis release init --workflows
```

This scaffolds `.vis/release/` (where change files live), writes the CI workflow for your provider (GitHub Actions or GitLab CI), and — if it spots an existing setup — points you at the migration path for changesets, semantic-release, or bumpy.

### 2. Write a change file [#2-write-a-change-file]

After making a change to a package, drop a change file alongside it:

```bash
vis release add
```

The prompt asks which packages changed and at what level (`major` / `minor` / `patch`), then opens an editor for the changelog body. Or skip the prompts entirely:

```bash
vis release add \
  --packages '@scope/cerebro:minor' \
  --message 'Add tab completion for nested commands'
```

The file lands in `.vis/release/` as plain markdown — commit it with your code change. It looks like this:

```markdown
---
"@scope/cerebro": minor
---

Add tab completion for nested commands.
```

> 💡 &#x2A;*Tip:** Don't want to write change files by hand? `vis release generate` derives them from your branch commits — it understands [conventional commits](https://www.conventionalcommits.org) and falls back to a path heuristic when you haven't enforced them.

### 3. Open a PR [#3-open-a-pr]

When you push, the **Release check** workflow comments on your PR with the release plan:

```text
📦 Release preview
@scope/cerebro 1.4.2 → 1.5.0 (minor)
```

Reviewers see exactly what's about to ship. Merge the PR and CI opens (or updates) a rolling **"Versioned release" PR** with the version bumps applied. Merging *that* ships it: tags pushed, npm publishes done, GitHub release created.

That's it. The rest of this page covers the concepts and recipes you'll want next.

## How releases flow [#how-releases-flow]

Every release follows the same cycle:

```text
   you write              CI opens             you merge
   a change file    →     a release PR    →    it ships
   (.vis/release/)        (versions +          (publish + tag +
                          changelog diff)       GH release)
```

The release PR is the human review gate. It collects every pending change file into one batch, shows the version diff, runs your guards, and only ships when you merge it. If you'd rather skip the PR (typical for prerelease branches like `alpha`), set the channel to `auto-publish` and every push ships inline.

## Recipes [#recipes]

### Ship a patch fix [#ship-a-patch-fix]

```bash
vis release add --packages '@scope/cerebro:patch' --message 'Fix tab completion crash'
git add . && git commit -m 'fix(cerebro): tab completion crash'
git push
# CI opens / updates the Versioned release PR — merge to ship
```

### Ship a prerelease [#ship-a-prerelease]

Push to a branch configured as a prerelease channel and CI publishes inline:

```typescript
// vis.config.ts
import { defineConfig } from "@visulima/vis";

export default defineConfig({
    release: {
        channels: {
            alpha: { tag: "alpha", prerelease: "alpha", mode: "auto-publish" },
        },
    },
});
```

```bash
git checkout -b alpha
git push -u origin alpha
# Every push to alpha publishes @scope/pkg@<next>-alpha.<n>
```

Install your prerelease with `pnpm add @scope/pkg@alpha`.

### Preview a PR before merging [#preview-a-pr-before-merging]

Open a PR and CI automatically publishes a snapshot. The PR gets a sticky comment with copy-paste install commands:

```sh
pnpm add @scope/cerebro@pr-1234
```

Snapshots use the [pkg-pr-new](https://pkg-pr-new.com) backend by default — no extra setup. Override the host via `release.snapshot.backend` or `release.snapshot.registry` if you want them on npm or a private registry.

### Bootstrap trusted publishing for a new package [#bootstrap-trusted-publishing-for-a-new-package]

npm won't let you configure a Trusted Publisher (OIDC) for a package that doesn't exist yet, so the first OIDC publish of a brand-new package fails. Run this once (locally, where you can clear the npm 2FA prompt):

```sh
vis release pretrust
```

It publishes a non-functional placeholder for each not-yet-published package, then runs `npm trust` to configure the Trusted Publisher. After it finishes, `vis release publish` (and CI) can publish those packages over OIDC. See [`vis release pretrust`](/docs/packages/vis/commands/release#vis-release-pretrust) for the flags.

### Maintain a 1.x line after shipping 2.0 [#maintain-a-1x-line-after-shipping-20]

Add a maintenance channel using a glob:

```typescript
channels: {
    "[0-9]*.x": { tag: "branch-name", range: "match", mode: "version-pr" },
}
```

Now any branch matching `1.x`, `2.3.x`, etc. publishes under a dist-tag that mirrors the branch name, and `range: "match"` prevents accidentally shipping a 2.x from the `1.x` branch.

### Pin a specific version [#pin-a-specific-version]

For one-off "ship exactly 2.0.0 now" scenarios, use the nested change-file shape with `releaseAs`:

```markdown
---
package: "@scope/cerebro"
bump: minor
releaseAs: "2.0.0"
---

Ship 2.0.0 to align with the major release announcement.
```

The computed bump is ignored; the package versions to `releaseAs` literally. Maps to release-please's `Release-As:` PR footer.

### Keeping the lockfile in sync [#keeping-the-lockfile-in-sync]

When CI bumps versions, the lockfile (`pnpm-lock.yaml`, `package-lock.json`, …) goes stale because the new versions aren't pinned yet. Most teams notice when the next install on a teammate's machine produces a diff. Wire `postVersionCommand` so the lockfile is refreshed in the same commit as the version bump — deterministic across machines, no surprise diffs:

```typescript
// vis.config.ts
export default {
    release: {
        postVersionCommand: "pnpm install --lockfile-only",
        // Or for npm:   "npm install --package-lock-only"
        // Or for yarn:  "yarn install --mode=update-lockfile"
        // Or for bun:   "bun install --frozen-lockfile=false"
    },
};
```

Runs after `vis release version` rewrites the manifests and before the changes are staged for commit, so the refreshed lockfile lands in the same version-PR. Tracks the long-standing changesets [#1139](https://github.com/changesets/changesets/issues/1139).

### Migrate from changesets / semantic-release / bumpy [#migrate-from-changesets--semantic-release--bumpy]

```bash
vis release init
```

Auto-detects which tool you're using and prints a migration plan. Force a specific source if detection fails:

```bash
vis release init --from-changesets
vis release init --from-semantic-release
vis release init --from-bumpy
```

By default `init` runs in **plan mode** — it prints what would change without writing files. Add `--apply` to perform the writes (currently wired for `--from-semantic-release`: writes the suggested `vis.config.ts` block, opts every detected package into `vis-release.managed: true`, and deletes migrated `.releaserc.*` files):

```bash
vis release init --from-semantic-release --apply
```

See the [comparison page](/docs/packages/vis/guides/release-comparison#migration) for what carries over and what doesn't.

## Core concepts [#core-concepts]

### Change files [#change-files]

A change file is markdown with YAML frontmatter. The frontmatter says which packages bump and by how much; the body becomes the changelog entry.

```markdown
---
"@scope/cerebro": minor
"@scope/string": patch
---

Add tab completion. The string formatter picked up a patch via cascade.
```

There's a longer shape for explicit cross-package cascades:

```markdown
---
package: "@scope/cerebro"
bump: minor
cascade:
    "@scope/string": patch
---

Add tab completion. The string formatter picked up a patch via cascade.
```

Inline meta on the first lines of the body (`pr: 42`, `commit: abc1234`, `author: @user`) gets picked up by the `github` changelog formatter for PR / commit / contributor links.

You can also leave the bump level off and let the **deepest markdown heading** in the body decide it — `#` → major, `##` → minor, `###` → patch (the highest level found wins). Headings inside fenced code blocks are ignored, so a shell `# comment` can't inflate a release. Explicit and infer-me entries can mix in one file:

```markdown
---
"@scope/cerebro":
"@scope/string": patch
---

## Add tab completion

`@scope/cerebro` bumps `minor` (from the H2); `@scope/string` keeps its explicit `patch`.
```

**Replay files** keep a changelog note around to re-emit at a future milestone instead of bumping now. They are changelog-only (no version bump — setting both `bump` and `replay` is rejected) and are retained until their conditions fire:

```markdown
---
"@scope/cerebro":
    replay:
        - "@scope/cerebro@1.0.0" # when it reaches this exact version
        - "exit-prerelease:@scope/cerebro" # when it leaves a prerelease line
---

Stability note replayed into the changelog at each milestone above.
```

Each run, every matching condition injects the body once (de-duplicated per package); the file is deleted once **all** its conditions fire within a single run. Keep one milestone per file if you want automatic cleanup.

> 💡 &#x2A;*Tip:** Change files are the artefact reviewers care about. They make the release explicit in the PR diff. If you'd rather derive bumps from commit messages, see `vis release generate` — it produces the same file from your branch history.

### Channels [#channels]

A **channel** is the mapping between a git branch and how releases are published from it. vis ships **no default channels** — you declare every branch you want to release from:

```typescript
// vis.config.ts
channels: {
    main:  { tag: "latest", mode: "version-pr" },
    next:  { tag: "next",   prerelease: "next",  mode: "version-pr" },
    alpha: { tag: "alpha",  prerelease: "alpha", mode: "auto-publish" },
    beta:  { tag: "beta",   prerelease: "beta",  mode: "auto-publish" },
}
```

Three settings you'll touch:

* **`tag`** — npm dist-tag for the publish. Use `"branch-name"` to mirror the branch.
* **`prerelease`** — semver pre-id (`alpha`, `beta`, `rc`). Omit for stable channels.
* **`mode`** — `version-pr` (review gate) or `auto-publish` (ship every push). Default: `auto-publish`.

Channel keys can be exact branch names or globs (`[0-9]*.x`, `release/*`). Exact names win over globs; among globs, the first listed wins. Globs use [zeptomatch](https://github.com/fabiospampinato/zeptomatch) — `*`, `?`, `[...]`, and `{a,b}` alternations work; extglob syntax (`+([0-9])`) does not.

### Modes: version-PR vs auto-publish [#modes-version-pr-vs-auto-publish]

| You want…                                       | Pick           |
| ----------------------------------------------- | -------------- |
| Review what ships before it ships               | `version-pr`   |
| Ship every push, no PR gate (alpha/beta/canary) | `auto-publish` |
| Maintenance branches (`1.x`, `2.3.x`)           | `version-pr`   |
| Trunk-based development with strict CI gates    | `auto-publish` |

**`version-pr`*&#x2A; maintains a rolling **"Versioned release" PR** containing the next batch of version bumps. Push code → the PR updates. Merge the PR → CI publishes. Skip the PR if you'd rather hand-merge.

**`auto-publish`** skips the PR and publishes inline on every push that has pending change files. Best for prereleases where the cadence is "anything I push should be installable".

> ⚠ &#x2A;*Version-PR mode on GitHub needs `VIS_GH_TOKEN`.** GitHub Actions' default `GITHUB_TOKEN` is locked against triggering downstream workflows on its own pushes, which means the version-PR would never run CI. Use a fine-grained PAT or a GitHub App token with `contents:write`. See the [CI guide](/docs/packages/vis/guides/release-ci#secrets-and-tokens).

### Per-package opt-in [#per-package-opt-in]

Releases are **opt-in per package**. A package joins the release flow when one of these is true:

1. `package.json` has `"vis-release": { "managed": true }`.
2. `vis.config.ts` lists it under `release.packages.<name>: { managed: true }`.
3. `vis.config.ts` sets `release.defaultManaged: true` (rare — flips the default to opt-out).
4. The package name matches a glob in `release.include`.

Explicit `managed: false` always wins. Private packages (`"private": true`) are excluded by default unless `release.privatePackages.version` is `true`.

> **Workspace-level config lives under `release` in `vis.config.ts`. Per-package overrides live under `vis-release` in the package's `package.json`** (or `release.packages.<name>` in `vis.config.ts`). The two field names are intentionally different so a search for either tells you which scope it lives at.

## Commands [#commands]

| Command                          | What it does                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `vis release init`               | Scaffold the subsystem; auto-detect migration source. `--apply` writes                                        |
| `vis release add`                | Author a change file (interactive or `--packages '@a:minor,@b:patch'`)                                        |
| `vis release generate`           | Derive a change file from branch commits                                                                      |
| `vis release status`             | Human-readable pending plan (table)                                                                           |
| `vis release plan`               | JSON plan; `--interactive` walks you through overrides                                                        |
| `vis release next-version`       | Print `<pkg> <old> -> <new>` for every package in the plan                                                    |
| `vis release changelog`          | Render the would-be changelog entries without writing                                                         |
| `vis release check`              | Verify change files cover every changed package (husky / CI gate)                                             |
| `vis release doctor`             | Preflight diagnostics                                                                                         |
| `vis release version`            | Apply the plan to disk                                                                                        |
| `vis release publish`            | Pack + publish + tag + push                                                                                   |
| `vis release snapshot`           | Ephemeral `0.0.0-<tag>-<sha>` PR previews                                                                     |
| `vis release pre enter/exit`     | Toggle changesets-compatible pre-mode (every `version` is a prerelease)                                       |
| `vis release stage list/approve` | Manage `npm stage publish` records ([staged publishing](/docs/packages/vis/guides/release-staged-publishing)) |
| `vis release notifications test` | Dry-run configured Slack / Discord / webhook destinations                                                     |
| `vis release ci release`         | The CI driver — opens / updates the version-PR (or `--auto-publish` to skip)                                  |
| `vis release ci snapshot`        | CI snapshot publish + sticky PR comment                                                                       |
| `vis release ci check`           | Sticky-comment the pending plan on the PR                                                                     |
| `vis release ci plan`            | Emit JSON plan + write to `$GITHUB_OUTPUT` for workflow gating                                                |
| `vis release ci rebase-pr`       | Rebase the version-PR onto base — wire to a cron when `versionPr.autoRebase` is on                            |
| `vis release ci setup`           | Print the recommended secrets / permissions checklist                                                         |

See [the commands reference](/docs/packages/vis/commands/release) for per-flag detail.

## Configuration [#configuration]

Most projects only need this much:

```typescript
// vis.config.ts
import { defineConfig } from "@visulima/vis";

export default defineConfig({
    release: {
        channels: {
            main: { tag: "latest", mode: "version-pr" },
            alpha: { tag: "alpha", prerelease: "alpha", mode: "auto-publish" },
        },
        acknowledgeUnstable: true,
    },
});
```

Everything else has sensible defaults. Reach for the options below when you need them.

### Bumping internal dependents [#bumping-internal-dependents]

By default, when `@scope/lib` bumps, any other workspace package that depends on it gets a patch bump if the new version falls outside the depending package's range. Tighten or loosen this:

```typescript
updateInternalDependencies: "out-of-range", // patch | minor | out-of-range (default)
dependencyBumpRules: {
    dependencies:     { trigger: "patch", bumpAs: "patch" },
    peerDependencies: { trigger: "major", bumpAs: "match" },
    devDependencies:  false, // never bump dev-only consumers (the default)
},
```

By default, `devDependencies` cascades are off — most consumers don't care about a devDep moving. Flip `bumpDevDependencies: true` (or pass a string-array allow-list of source package names) to opt in.

### Grouping packages [#grouping-packages]

```typescript
fixed:  [["@scope/a", "@scope/b"]],  // share version; both bump when either changes
linked: [["@scope/x", "@scope/y"]],  // share bump level; only changed members publish
```

The object form opts into a shared changelog file for the group — see `ReleaseGroupConfig` in [types.ts](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/release/types.ts).

Set `syncGitTag: true` on a group to collapse it to **one shared git tag and one aggregate release** for the whole group instead of one tag + release per member:

```typescript
fixed: [{ name: "acme", packages: ["@acme/*"], syncGitTag: true }],
```

This tags the wave once as `acme@<version>` (the highest member version; override the format with `tagPattern`, tokens `{name}`/`{version}`) and publishes one release listing every member. Members in a `syncGitTag` group are skipped in the per-package tag/release loop.

### Per-package overrides [#per-package-overrides]

Inline in `package.json`:

```json
{
    "name": "@scope/cerebro",
    "vis-release": {
        "managed": true,
        "versionActions": "npm",
        "releaseTagPattern": "{unscopedName}-v{version}",
        "cascadeTo": {
            "@scope/cerebro-*": { "trigger": "minor", "bumpAs": "patch" }
        }
    }
}
```

Or in `vis.config.ts`:

```typescript
packages: {
    "@scope/private-pkg": { managed: false },
    "@scope/native":      { versionActions: "native-addon" },
}
```

### Publish guards [#publish-guards]

`release.publish.guards` runs after `npm pack` but before `npm publish`:

```typescript
publish: {
    cleanPackageJson: true,
    guards: {
        packSecretScan:   true,
        exportsExist:     true,
        lifecycleScripts: "strict",
        audit:            "high",
    },
}
```

See the [security audit guide](/docs/packages/vis/guides/security-audit) for the full menu.

### Hooks [#hooks]

```typescript
preVersionCommand:   "pnpm run lint:packages",
postVersionCommand:  "pnpm run sort-package-json",
prePublishCommand:   "pnpm run build:packages:prod",
postPublishCommand:  "pnpm run notify:internal",
```

All four hooks are shell commands executed in the workspace root.

### Custom per-package commands [#custom-per-package-commands]

Per-package `publishCommand` / `buildCommand` / `checkPublished` overrides are off by default — vis requires explicit opt-in:

```typescript
allowCustomCommands: true,                    // every package
// or
allowCustomCommands: ["@scope/native-*"],     // glob allow-list
```

Inside a custom command, interpolation tokens are `{{name}}`, `{{version}}`, `{{tag}}`, `{{registry}}`. Every interpolated value is shell-quoted so injection is impossible. See [`PerPackageReleaseConfig`](https://github.com/visulima/visulima/blob/main/packages/tooling/vis/src/release/types.ts) for the full surface.

### Floating major tags [#floating-major-tags]

For GitHub Action consumers (`uses: acme/action@<tag>`), vis can maintain a "floating" major tag that always points at the latest release of that major line. Enable per-package or workspace-wide:

```typescript
// vis.config.ts
release: {
    floatingMajorTag: true, // workspace default
    packages: {
        "@scope/action": { floatingMajorTag: true },
    },
}
```

The tag format is &#x2A;*`<safe-name>-v<major>`** — the package name with leading `@` stripped and `/` flattened to `-`, then `-v` and the major version:

| Package           | Floating tag        |
| ----------------- | ------------------- |
| `acme-action`     | `acme-action-v1`    |
| `@scope/action`   | `scope-action-v1`   |
| `@scope/cli-tool` | `scope-cli-tool-v2` |

Consumers pin like this:

```yaml
- uses: acme/acme-action@acme-action-v1 # always latest 1.x
```

This namespacing means multiple actions in one monorepo never collide on a shared `v1` tag. The float is **skipped** on prereleases, on packages whose `releaseTagPattern` already includes `{major}`, on private packages, and when `skipNpmPublish: true`.

#### Migrating from `v<major>` [#migrating-from-vmajor]

Earlier versions of vis (and most other release tools) used a flat `v<major>` (e.g. `v1`). If you have consumers pinned to `acme/action@v1`, `vis release doctor` flags it:

> Legacy floating tag `v1` detected. vis now writes namespaced floating tags as `<safe-name>-v<major>` (e.g. `acme-action-v1`). Either re-tag `v1` → `acme-action-v1` and update consumers, or sunset the old tag and announce the new pin.

Two paths:

1. **Re-tag in place.** Push the new namespaced tag, then announce the old one is frozen at its current SHA. Consumers update at their own pace.
2. **Sunset + new pin.** Delete the old tag, publish a release note pointing consumers at the new format. Cleaner long-term, but breaks anyone still pinned to `v1` until they update.

There is no opt-out to the flat `v<major>` format — even single-package monorepos use the namespaced form.

#### Floating tags + sigstore [#floating-tags--sigstore]

If you enable floating tags **and** sigstore signing (see [Signing modes](#signing-modes)), doctor emits a warning: re-pointing a floating tag does not re-sign it, so a stale signature can persist on the moved ref. Either re-sign the floating tag in your workflow, or skip signing for floating refs and rely on the per-version tag signature.

### Protected content in CHANGELOG / release bodies [#protected-content-in-changelog--release-bodies]

When vis re-renders a changelog or release body, it preserves any region you've wrapped in protected-content markers:

```markdown
<!-- vis:user-content -->

Custom notes from the release engineer. Vis will not touch this block on
subsequent renders — edit it freely.

<!-- /vis:user-content -->
```

The merger walks open/close markers in document order and replaces only the auto-generated regions outside them.

**Safety net for unbalanced markers.** If your changelog body contains a documentation code fence that shows the marker syntax (this page is an example), a naive counter would see those occurrences as real markers and miscount. The merger strips fenced code blocks before counting so docs-as-content doesn't break the parse.

If the counter still sees an imbalance after stripping fences (open without close, or vice versa), the merger **skips body overwrite entirely** for that file and logs a warning rather than risk clobbering user content. Fix the markup and re-run — vis will resume managing the file on the next release.

### Release-note templates [#release-note-templates]

Wrap each per-package release body with operator-supplied header/footer text:

```typescript
publish: {
    releaseNoteTemplate: {
        header: "## {name} {version}\n\nReleased {date} from {repo}.\n",
        footer: "\n— previous: {previousVersion}",
    },
},
```

Tokens (single-pass — your token values won't be re-interpolated even if they contain `{...}` themselves):

| Token               | What                                                                       |
| ------------------- | -------------------------------------------------------------------------- |
| `{name}`            | Full package name (`@scope/pkg`)                                           |
| `{version}`         | Version being released                                                     |
| `{previousVersion}` | Last published version on this channel                                     |
| `{date}`            | ISO date of the release                                                    |
| `{repo}`            | `owner/repo` slug                                                          |
| `{contributors}`    | Bullet-list of authors from this wave's change files (release-please #292) |

The `{contributors}` token expands to a `- @handle` bullet list (one per line) collected from every change file in the wave, so cascade and dependency-only bumps still credit the upstream author. Authors are de-duplicated case-insensitively, markdown-escaped, and filtered through the github formatter's `internalAuthors` list when that formatter is configured. If no change file in the wave declares an author, the token renders as the empty string and the surrounding header / footer line is dropped — a templated `## Contributors\n{contributors}` block collapses cleanly to nothing. (A git-log fallback for waves with no `author:` metadata is tracked as a follow-up — see `collectContributors` in `release-note-template.ts`.)

**Block-only.** Keep `{contributors}` on its own line — typically under a heading. Inline use like `"Thanks {contributors}!"` produces broken markdown because the token always expands to a multi-line bullet list:

```typescript
// ✅ correct — token on its own line, heading above it
publish: {
    releaseNoteTemplate: {
        header: "## Contributors\n\n{contributors}",
    },
},

// ❌ broken — inline use produces "Thanks - @alice\n- @bob!" (no list)
publish: {
    releaseNoteTemplate: {
        header: "Thanks {contributors}!",
    },
},
```

Multiple handles on one frontmatter line work — write `author: @alice, @bob` and both are credited.

Not applied in `aggregateRelease` mode — override `aggregateRelease.title` instead.

### Cross-package attribution with `additionalPaths` [#cross-package-attribution-with-additionalpaths]

Some packages logically own files outside their own directory — a shared `docs/cli/` for a CLI package, or `examples/cli/` for runnable demos. Tell `vis release check --strict` to attribute those paths back to the package via the per-package `additionalPaths` field:

```typescript
// vis.config.ts
release: {
    packages: {
        "@scope/cli": {
            additionalPaths: ["docs/cli/**", "examples/cli/**"],
        },
    },
}
```

Now a PR that touches `docs/cli/` without a covering change file for `@scope/cli` fails `vis release check --strict`. Paths are workspace-root-relative; a file can only be claimed by one package (multi-claim invariant — `release check` fails with the conflict so you can decide which owns it).

### pnpm catalog change detection [#pnpm-catalog-change-detection]

When you bump a version in `pnpm-workspace.yaml`'s `catalog:` / `catalogs:` blocks, consumers pull the new version on their next install but their own `package.json` doesn't change — so vis would normally skip them on the next release. Opt in to detection:

```typescript
release: {
    detectCatalogChanges: true,
}
```

Now every consumer that references the moved catalog entry gets a `patch` bump, attributed as `CATALOG_CHANGED` in the plan. The detector bails early when no catalogs are configured (zero overhead for non-catalog repos).

### Signing modes [#signing-modes]

vis can sign git tags with `gpg`, `ssh`, or `sigstore` (gitsign). Pick per-workspace:

```typescript
release: {
    signing: {
        mode: "sigstore", // "gpg" | "ssh" | "sigstore"
    },
    gitSignCommits: true,  // also pass -S to release-flow commits
}
```

* **`gpg`** — classic detached signature. Requires `gpg` on PATH and a configured signing key.
* **`ssh`** — newer git native SSH signing. Requires `git` ≥ 2.34 and `gpg.format=ssh` + `user.signingkey` pointing at an SSH key.
* **`sigstore`** (preview) — keyless via [gitsign](https://github.com/sigstore/gitsign). Doctor probes for `gitsign` on PATH; if missing, vis falls back to GPG with a warning. The probe is cached (60s TTL) so repeated invocations during one release flow don't re-shell out.

If you enable sigstore + floating major tags, doctor warns about the re-point/re-sign gap (see [Floating tags + sigstore](#floating-tags--sigstore)).

### Notifications [#notifications]

Post-release fan-out to Slack, Discord, generic webhooks, or your own plugin:

```typescript
notifications: {
    slack:   { webhook: process.env.SLACK_RELEASE_WEBHOOK },
    discord: { webhook: process.env.DISCORD_RELEASE_WEBHOOK },
    webhook: { url: "https://hooks.acme.com/release", method: "POST" },
},
```

Per-channel failures log a warning and never fail the release. Webhook URLs and tokens are masked before any error is logged, so it's safe to forward CI logs.

Dry-run channels before relying on them in production:

```bash
vis release notifications test --channel=slack
```

See the [notifications guide](/docs/packages/vis/guides/release-notifications) for templating tokens, multi-channel ids, and writing custom channel plugins.

### Skipping the GitHub release [#skipping-the-github-release]

```typescript
publish: {
    noRelease: true,
}
```

Skips the GitHub / GitLab release-creation step while still pushing the git tag, publishing to the registry, and running notifications + the post-release walk. Useful when release notes live elsewhere (a docs site, in-product changelog) or when the GitHub release is created by a downstream workflow.

### Conventional commits + gitmoji [#conventional-commits--gitmoji]

`vis release generate` accepts conventional-commits with a leading [gitmoji](https://gitmoji.dev) prefix:

```text
:sparkles: feat(cerebro): add tab completion
✨ feat(cerebro): add tab completion
```

Both forms parse identically. The gitmoji is stripped from the changelog entry; type/scope/subject parsing is unchanged.

### Bootstrapping the first release [#bootstrapping-the-first-release]

For brand-new packages with no published history, vis doesn't know what "previous" looks like. Use `--first-release` to bootstrap:

```bash
vis release version --first-release
vis release publish --first-release
vis release next-version --first-release
vis release doctor --first-release
vis release ci release --first-release
```

This skips previous-version lookup, starts the changelog from scratch, and stamps the package at its current `package.json` version (rather than computing a bump). See [First release & resolver](/docs/packages/vis/guides/release-first-release-and-resolver) for the underlying `currentVersionResolver` knob (`disk` / `registry` / `git-tag`).

### Native addons (NAPI) [#native-addons-napi]

NAPI parents (packages with a `napi` field in `package.json`) are **auto-detected** and routed through the `native-addon` versionActions — vis publishes the platform-specific child packages alongside the parent in one wave. No explicit `versionActions` needed:

```json
{
    "name": "@scope/parser",
    "napi": { "name": "parser" }
}
```

Override per-package with `vis-release.versionActions: "native-addon"` if auto-detection misses your case. Platform packages under `npm/<target>/` should NOT opt into vis (`"release": { "managed": false }`); the parent publishes them.

### Maven publishing [#maven-publishing]

For JVM artifacts published alongside npm packages, vis has a `maven` versionActions. See [Maven publishing](/docs/packages/vis/guides/release-maven).

### Lifecycle plugins [#lifecycle-plugins]

Beyond the single-purpose `define*` extension points, a **lifecycle plugin** can hook arbitrary points of the version/publish flow. Register via `release.plugins`:

```typescript
import { defineReleasePlugin } from "@visulima/vis/release";

plugins: [
    defineReleasePlugin({
        name: "build-before-publish",
        async willPublish({ package: pkg }) {
            await runBuild(pkg.name); // return false to skip this package
        },
        async afterPublishAll({ result }) {
            await pingDeployHook(result.published);
        },
    }),
],
```

Hooks (all optional): `applyDraft({ plan })` after versions + changelogs are written, `willPublish({ package })` before each publish (return `false` to skip — its dependents are skipped too), `afterPublish({ package })` after each successful publish, `afterPublishAll({ result })` once the wave completes. `applyDraft` / `willPublish` throw-propagate (they gate the release — fail fast); `afterPublish` / `afterPublishAll` are post-effect, so a throw is logged and swallowed.

### Plugin authoring [#plugin-authoring]

Want a custom versionActions, notification channel, or changelog formatter? See [Plugin authoring](/docs/packages/vis/guides/release-plugin-authoring).

### Doctor [#doctor]

`vis release doctor` runs preflight diagnostics before a release: tool availability, token presence, host reachability, signing key probes, channel coherence, and a growing set of audit warnings. Notable checks:

* **gitsign probe** (cached 60s) — surfaces missing binary before publish time.
* **floating + sigstore interaction** — warns about the re-point/re-sign signature gap.
* **legacy `v<major>` tag migration** — flags existing flat floating tags and points at the namespaced replacement.
* **`gh` on PATH for GitHub Enterprise hosts** — warns when `githubHost` is set but the CLI is missing.

Run it locally before pushing release config changes, or wire it into your pre-merge gate. See the [release commands reference](/docs/packages/vis/commands/release) for the full list.

### Full reference [#full-reference]

<details>
  <summary>
    All workspace-level options
  </summary>

  | Option                                                                                                            | Default                          | What it controls                                                                                                                                                                              |
  | ----------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `baseBranch`                                                                                                      | `"main"`                         | Baseline ref for `status` / `generate` / merge-base detection                                                                                                                                 |
  | `changesDir`                                                                                                      | `".vis/release"`                 | Where change files live                                                                                                                                                                       |
  | `access`                                                                                                          | `"public"`                       | Default npm `--access`                                                                                                                                                                        |
  | `defaultManaged`                                                                                                  | `false`                          | Whether unconfigured packages are released by default                                                                                                                                         |
  | `channels`                                                                                                        | —                                | Branch → publish profile. No built-in defaults — you declare every branch                                                                                                                     |
  | `notifications`                                                                                                   | —                                | Post-release fan-out: Slack / Discord / generic webhook / plugins. Per-channel failures log a warning, never fail CI                                                                          |
  | `updateInternalDependencies`                                                                                      | `"out-of-range"`                 | When to bump internal dependents: `"patch"` / `"minor"` / `"out-of-range"`                                                                                                                    |
  | `dependencyBumpRules`                                                                                             | sensible defaults                | Per-dep-kind `{ trigger, bumpAs }`. Disable a kind with `false`                                                                                                                               |
  | `bumpDevDependencies`                                                                                             | `false`                          | Opt-in cascade for devDep bumps. `true` for all, or `string[]` allow-list of source pkgs                                                                                                      |
  | `detectCatalogChanges`                                                                                            | `false`                          | Treat consumers of changed `pnpm-workspace.yaml` catalog entries as bumped                                                                                                                    |
  | `fixed` / `linked`                                                                                                | `[]`                             | Group rules (locked versions / locked bump levels). Object form opts into a shared changelog                                                                                                  |
  | `ignore` / `include`                                                                                              | `[]`                             | Globs that opt-out / force-include packages                                                                                                                                                   |
  | `privatePackages`                                                                                                 | `{ version: false, tag: false }` | Whether to version / tag `private: true` packages                                                                                                                                             |
  | `changelog`                                                                                                       | `"default"`                      | `false` / `"default"` / `"github"` / `"keep-a-changelog"` / `[path, options]` / `[builtin, options]`                                                                                          |
  | `publish.cleanPackageJson`                                                                                        | `true`                           | Strip `scripts`, `devDependencies`, etc. from the published manifest                                                                                                                          |
  | `publish.guards`                                                                                                  | conservative defaults            | Pre-publish gates — see [security audit](/docs/packages/vis/guides/security-audit)                                                                                                            |
  | `publish.releaseAssets`                                                                                           | `{}`                             | Post-publish: stamp tarball hashes into the release body and/or upload the tarball                                                                                                            |
  | `publish.draftRelease`                                                                                            | `false`                          | Create the GitHub / GitLab release as a draft (human-published from the UI)                                                                                                                   |
  | `publish.discussionCategory`                                                                                      | —                                | GitHub: link each release to a Discussion in the named category                                                                                                                               |
  | `publish.addReleases`                                                                                             | `false`                          | `"top"` / `"bottom"` prepends or appends a "Related releases" block linking the previous 3-5 releases of the same package (GitHub only; GitLab logs a warning)                                |
  | `publish.extraFiles`                                                                                              | `[]`                             | Workspace-level regex or annotation-comment rules — keep version strings in README badges, Cargo.toml, Dockerfiles, etc. in sync                                                              |
  | `publish.releaseNoteTemplate`                                                                                     | —                                | `{ header?, footer? }` — wrap each per-package release body. Tokens: `{name}`, `{version}`, `{previousVersion}`, `{date}`, `{repo}`, `{contributors}`. NOT applied in `aggregateRelease` mode |
  | `publish.noRelease`                                                                                               | `false`                          | Skip GitHub/GitLab release creation but still tag + publish + notify                                                                                                                          |
  | `publish.stage`                                                                                                   | `false`                          | Use `npm stage publish` for human-approved npm releases — see [staged publishing](/docs/packages/vis/guides/release-staged-publishing)                                                        |
  | `publish.lockInGit`                                                                                               | `false`                          | Persist in-progress publish state to a git-tracked `publish-lock.json` (committed + pushed) so an ephemeral CI runner can resume a partially-failed publish from a fresh checkout             |
  | `plugins`                                                                                                         | `[]`                             | Lifecycle plugins (`applyDraft` / `willPublish` / `afterPublish` / `afterPublishAll`) — see [Lifecycle plugins](#lifecycle-plugins)                                                           |
  | `releaseTagPattern`                                                                                               | `"{name}@{version}"`             | Tag template. Tokens: `{name}`, `{unscopedName}`, `{version}`, `{major}`, `{minor}`, `{patch}`, `{date}`, `{channel}`                                                                         |
  | `aggregateRelease`                                                                                                | `false`                          | One GitHub release per wave vs per-package                                                                                                                                                    |
  | `versionPr.{title,branch,preamble,commentMarker,labels,reviewers,assignees,autoMerge,autoMergeMethod,autoRebase}` | —                                | Cosmetics + lifecycle metadata for the rolling version-PR (auto-merge needs `repo settings → allow auto-merge`; auto-rebase needs a cron running `vis release ci rebase-pr`)                  |
  | `gitUser`                                                                                                         | —                                | `{ name, email }` used for CI commits                                                                                                                                                         |
  | `gitSignCommits`                                                                                                  | `false`                          | Pass `git commit -S` to release-flow commits                                                                                                                                                  |
  | `signing`                                                                                                         | —                                | `{ mode: "gpg" \| "ssh" \| "sigstore", key? }` — sign release tags                                                                                                                            |
  | `floatingMajorTag`                                                                                                | `false`                          | Maintain a `<safe-name>-v<major>` tag that always points at the latest non-prerelease of that major line                                                                                      |
  | `bumpMinorPreMajor`                                                                                               | `false`                          | For pre-1.0 versions, demote major → minor (avoids leaping to 2.0 on first breaking change)                                                                                                   |
  | `bumpPatchForMinorPreMajor`                                                                                       | `false`                          | Companion: also demote minor → patch when pre-1.0. No-op without `bumpMinorPreMajor`                                                                                                          |
  | `preVersionCommand` / `postVersionCommand` / `prePublishCommand` / `postPublishCommand`                           | —                                | Shell hooks at version / publish stage boundaries                                                                                                                                             |
  | `allowCustomCommands`                                                                                             | `false`                          | Trust gate for per-package `publishCommand` / `buildCommand` / `checkPublished`. `true` for all, or `string[]` allow-list                                                                     |
  | `provider`                                                                                                        | `"auto"`                         | `"github"` / `"gitlab"` / `"auto"`                                                                                                                                                            |
  | `gitlabHost`                                                                                                      | —                                | Self-hosted GitLab base (e.g. `gitlab.acme.com`). Maps to `GITLAB_HOST` for `glab`                                                                                                            |
  | `githubHost`                                                                                                      | —                                | Self-hosted GitHub Enterprise host (e.g. `github.acme.com`). Maps to `GH_HOST` for `gh`. Doctor warns if `gh` isn't on PATH                                                                   |
  | `httpProxy`                                                                                                       | —                                | HTTPS proxy URL — sets `HTTPS_PROXY`/`HTTP_PROXY` on `gh`/`glab` subprocesses AND routes internal `fetch()` calls through an undici `ProxyAgent`                                              |
  | `workspaceChangelog`                                                                                              | `false`                          | Write one root-level `CHANGELOG.md` aggregating each wave                                                                                                                                     |
  | `successWalk`                                                                                                     | —                                | Post-release walk that posts sticky comments + adds a `released` label on every PR/issue referenced in changelog bodies. Off when undefined — set `{}` to opt in                              |
  | `currentVersionResolver`                                                                                          | `"disk"`                         | `"disk"` / `"registry"` / `"git-tag"` — see [first release & resolver](/docs/packages/vis/guides/release-first-release-and-resolver)                                                          |
  | `acknowledgeUnstable`                                                                                             | `false`                          | Suppress the unstable-subsystem warning                                                                                                                                                       |
</details>

## What's next [#whats-next]

* **[Set up CI](/docs/packages/vis/guides/release-ci)** — GitHub Actions and GitLab CI workflows, OIDC trusted publishing, secrets and tokens
* **[Staged publishing](/docs/packages/vis/guides/release-staged-publishing)** — human-approved npm releases with `npm stage publish`, including timeout / rejection / out-of-band recovery
* **[First release & version resolver](/docs/packages/vis/guides/release-first-release-and-resolver)** — bootstrapping greenfield monorepos, `--first-release`, and the `currentVersionResolver` modes
* **[Notifications](/docs/packages/vis/guides/release-notifications)** — Slack / Discord / webhook configuration, templating, and custom channel plugins
* **[Maven publishing](/docs/packages/vis/guides/release-maven)** — JVM artifacts alongside npm
* **[Plugin authoring](/docs/packages/vis/guides/release-plugin-authoring)** — custom versionActions, notification channels, changelog formatters
* **[Per-command reference](/docs/packages/vis/commands/release)** — every flag, when to use each command
* **[How vis release compares](/docs/packages/vis/guides/release-comparison)** — vs changesets, semantic-release, release-please, bumpy
* **[Configuration model](/docs/packages/vis/guides/config-model)** — how `vis.config.ts` loads and merges
* **[Security audit guide](/docs/packages/vis/guides/security-audit)** — pre-publish gates in depth

[pkg-pr-new]: https://pkg-pr-new.com


# Security audit (/docs/packages/vis/guides/security-audit)



# Security audit [#security-audit]

`vis audit` is an offline-first vulnerability scanner. It walks the installed package set (resolved from the lockfile, no `node_modules` traversal) and matches every entry against an OSV advisory database held locally. When the local cache is present, no network access is required at scan time — making it suitable for hermetic CI, airgapped environments, and pre-release gates.

This guide covers:

1. Populating the offline cache.
2. Running an audit and choosing an output format.
3. Apply loops — patching direct and transitive vulnerabilities.
4. CI integration.
5. Accepted-risk workflow.

## 1. Populate the offline cache [#1-populate-the-offline-cache]

The cache lives at `<workspace>/node_modules/.cache/vis/advisories/db.sqlite` (resolved via `@visulima/find-cache-dir`). Run sync once at install time:

```bash
vis advisories sync
```

This downloads the OSV `all.zip` dump for the npm ecosystem (\~5 MB compressed) and ingests it into a SQLite cache (\~12 MB on disk). The next sync short-circuits via the upstream `ETag` header if the file hasn't changed.

```bash
# CI / scheduled refresh
vis advisories sync           # ETag-aware; no work if unchanged
vis advisories sync --force   # force re-download

# Verify freshness in CI
vis advisories status --format json | jq -e '.ecosystems[0].lastSyncIso'
```

See [`vis advisories`](/docs/packages/vis/commands/advisories) for full reference.

## 2. Run an audit [#2-run-an-audit]

```bash
vis audit                       # human-readable table
vis audit --severity high       # only show high/critical
vis audit --prod-only           # skip devDependencies
vis audit --usage               # reachability filter — only statically-imported packages

# For non-human consumers
vis audit --format json
vis audit --format sarif         # GitHub / GitLab code-scanning uploads
vis audit --format csaf          # CSAF 2.0 csaf_vex profile
vis audit --format cyclonedx-vex # CycloneDX 1.7 SBOM + VEX
vis audit --format gitlab        # GitLab dependency-scanning report (Secure stage)
vis audit --format junit         # JUnit XML (Surefire-compatible)
vis audit --report ./report.html # self-contained HTML
```

### Reachability [#reachability]

`--usage` (or `security.policies.vulnerability.usage.enabled` in config) filters findings to only those packages that are statically imported somewhere in your source tree. Dynamic `require()` calls behind variable names are conservatively treated as reachable.

This is a noise reducer — vulnerabilities in unused devDependencies stay out of your dashboard.

## 3. Fix loops [#3-fix-loops]

`vis audit` ships two fix loops. Both default to a dry-run preview and prompt before changing anything.

### `--fix` — direct-dep upgrades [#--fix--direct-dep-upgrades]

When the vulnerable package is declared in your `package.json` (or any workspace `package.json`), `--fix` upgrades it by calling the active package manager's update command.

```bash
vis audit --fix                    # interactive preview + prompt
vis audit --fix --yes              # CI — skip prompt
vis audit --fix --allow-major      # permit major-version bumps
```

The planner classifies each fix as **in-range** (caret bump that satisfies the existing range) or **major** (the fix is outside the range — requires `--allow-major`). Findings that don't match any manifest are reported under "Transitive only" — those belong to the second loop.

### `--fix-transitive` — PM-specific overrides [#--fix-transitive--pm-specific-overrides]

For transitive vulnerabilities (the vulnerable package isn't in your manifest — it's pulled in by something else), `--fix-transitive` writes a pinned override into the appropriate surface for your package manager:

| Package manager | Surface                         |
| --------------- | ------------------------------- |
| pnpm v10+       | `pnpm-workspace.yaml#overrides` |
| pnpm v9         | `package.json#pnpm.overrides`   |
| npm             | `package.json#overrides`        |
| Bun             | `package.json#overrides`        |
| Yarn            | `package.json#resolutions`      |

The writer is atomic (`.tmp` sibling + `renameSync`) and idempotent — re-running with the same plan is a no-op.

In CI, `--fix-transitive` is gated by **two** locks:

1. `--yes` on the CLI.
2. `security.audit.apply.transitive.enabled = true` in `vis.config.ts`.

This intentional friction prevents a misconfigured pipeline from rewriting your override surface every PR.

```bash
vis audit --fix-transitive         # interactive preview
vis audit --fix-transitive --yes   # CI — requires config flag too
```

## 4. CI integration [#4-ci-integration]

A typical pipeline:

```yaml
# .github/workflows/audit.yml
- run: pnpm install --frozen-lockfile
- run: pnpm exec vis advisories sync
- run: pnpm exec vis audit --offline --format sarif > audit.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
      sarif_file: audit.sarif

# Hard gate the build on high+ findings
- run: pnpm exec vis audit --offline --fail-on high
```

### GitLab CI [#gitlab-ci]

The `gitlab` and `junit` formats land artifacts that GitLab's Secure stage and merge-request widgets pick up natively:

```yaml
# .gitlab-ci.yml
audit:
    image: node:24
    script:
        - pnpm install --frozen-lockfile
        - pnpm exec vis advisories sync
        - pnpm exec vis audit --offline --format gitlab > gl-dependency-scanning.json
        - pnpm exec vis audit --offline --format junit  > junit.xml
        - pnpm exec vis audit --offline --fail-on high # hard gate
    artifacts:
        reports:
            dependency_scanning: gl-dependency-scanning.json
            junit: junit.xml
```

The `--severity` flag is the equivalent of `osv2gitlab`'s `--threshold`: `vis audit --severity high --format gitlab` keeps only `high`/`critical` findings in the GitLab report.

### Exit-code semantics [#exit-code-semantics]

| Flag                | Exit behaviour                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| *none*              | Always exit 0. Audit is informational by default.                                              |
| `--exit-code`       | Exit 1 if any actionable finding is present **or** the policy engine emits a `block` decision. |
| `--fail-on <level>` | Exit 1 when a vulnerability meets `<level>` or higher, **or** when a `block` policy fires.     |

Acknowledged risks are excluded from the gate unless `--show-accepted` is set.

## 5. Supply-chain policy engine [#5-supply-chain-policy-engine]

Beyond vulnerability findings, `vis audit` runs a configurable supply-chain
policy engine inspired by [Socket.dev](https://socket.dev). Each policy maps
to a `security.policies.<name>` field in `vis.config.ts`; leaving a field
unset disables the policy entirely.

This release ships four offline-clean policies:

* **`license`** — SPDX allow / deny lists. Deny wins on any sub-expression
  match in an SPDX expression (`(MIT OR GPL-3.0)` is blocked when
  `GPL-3.0` is on the deny list).
* **`installScripts`** — surfaces packages declaring lifecycle scripts
  (`preinstall`, `install`, `postinstall`, `prepare`, or an implicit
  `node-gyp rebuild` from a `binding.gyp`). `strict: true` turns
  unapproved scripts into block-severity decisions.
* **`vulnerability`** — OSV findings, gated by the existing `failOn` /
  `usage` knobs. Findings now also flow through the unified policy
  report and the JSON / SARIF / HTML formatters.
* **`unexpectedDeps`** — flags packages that aren't on a static
  allow-list, or that didn't exist in a saved baseline lockfile.

Network-bound policies (`malware`, `firstSeen`, `publisherChange`,
`score`) plug into the same engine in a follow-up commit; until then
they're surfaced via the existing Socket-direct integration.

### CLI surface [#cli-surface]

| Flag                | Behaviour                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `--policies <list>` | Narrow this run to a subset of policies. Comma list. Accepts camelCase or snake\_case names. |
| `--policies all`    | Force every known policy regardless of config.                                               |
| `--policies none`   | Skip the engine entirely.                                                                    |
| *no flag*           | Evaluate every policy that has a configured `security.policies.<name>` entry.                |

### Accepted risks per policy [#accepted-risks-per-policy]

`security.acceptedRisks` is shared by every policy. Use the optional
`policies` array to scope an acceptance to a specific gate, and
`expiresAt` to set a sunset date:

```ts
acceptedRisks: {
    "legacy-thing": {
        reason: "Vendor refuses to relicense; replacing in Q3",
        acceptedAt: "2026-01-01",
        expiresAt: "2026-09-30",
        policies: ["license"],
    },
}
```

## 5. Accepted-risk workflow [#5-accepted-risk-workflow]

Some vulnerabilities are unfixable, vendor-disputed, or out of scope. Document them in `vis.config.ts`:

```ts
export default defineConfig({
    security: {
        socket: {
            acceptedRisks: [
                {
                    name: "left-pad",
                    reason: "Vendored fork — upstream advisory does not apply",
                    expiresAt: "2026-12-31",
                },
            ],
        },
    },
});
```

The acceptance is workspace-local. To mirror it into the native package-manager config (so other tooling — Snyk, Renovate, Dependabot — picks it up), run:

```bash
vis audit --sync
```

This writes the accepted risks into the appropriate PM config (`pnpm-workspace.yaml`'s `auditConfig`, or Yarn's `.yarnrc.yml`).

`--show-accepted` re-includes them in audit output so you can review what's been silenced.

## 6. Security providers [#6-security-providers]

`vis` ships a pluggable provider interface for the network-bound supply-chain signals that complement the offline OSV audit. Each provider returns a per-package report (score axes + alerts); when more than one is enabled, results are **merged** rather than replaced.

| Provider                         | Auth                              | Strengths                                                                                                                                                                    |
| -------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Socket.dev** (`socket`)        | Public token / `VIS_SOCKET_TOKEN` | Five-axis package score (quality, maintenance, supply chain, license, vulnerability), curated alerts (malware, install scripts, telemetry, typosquats), version-scoped data. |
| **Google deps.dev** (`deps-dev`) | None                              | OpenSSF Scorecard signals (16 automated checks) + GHSA advisories, no API token, generous rate limits, completely free.                                                      |

```ts
// vis.config.ts
import { defineConfig } from "@visulima/vis/config";

export default defineConfig({
    security: {
        socket: { enabled: true }, // requires VIS_SOCKET_TOKEN
        depsDev: { enabled: true }, // no auth — safe to enable in CI

        // Which provider's `score` wins on conflict. Alerts from the other
        // provider are still appended and deduped by `key`.
        primaryProvider: "socket",
    },
});
```

### Provider merge semantics [#provider-merge-semantics]

When both providers return data for the same package:

* **Score** — the **primary provider**'s score axes win wholesale. The secondary's score is discarded (it's a different rubric and averaging the two would be meaningless).
* **Alerts** — concatenated and deduped by `key`. Cross-provider duplicates collapse to the first occurrence.
* **License / author / size** — primary wins; secondary fills in only when primary is missing the field.
* **Failures are isolated** — a provider that times out or errors contributes an empty map. The remaining providers still report.

### Per-run escape hatches [#per-run-escape-hatches]

| Env var                       | Effect                                                 |
| ----------------------------- | ------------------------------------------------------ |
| `MARSHALL_DISABLE_SOCKET=1`   | Skip the Socket.dev provider for the current process.  |
| `MARSHALL_DISABLE_DEPS_DEV=1` | Skip the deps.dev provider for the current process.    |
| `MARSHALL_DISABLE_ALL=1`      | Skip every marshall-gated check (including providers). |
| `--offline` on `vis audit`    | Disables both providers for this command only.         |

### Cache locations [#cache-locations]

Each provider writes a JSON-on-disk cache under `~/.vis/cache/`:

* `socket-security/` — Socket.dev reports (default TTL: 1 hour)
* `deps-dev/` — deps.dev version + project + advisory entries (default TTL: 24h for project data, 7d for version and advisory data — those are immutable once published)

Clear with `vis cache clean --type=socket` or `vis cache clean --type=deps-dev`. `vis cache clean` (no flag) clears every store.

## Reference [#reference]

* [`vis audit`](/docs/packages/vis/commands/audit) — full flag reference.
* [`vis advisories`](/docs/packages/vis/commands/advisories) — cache management.
* [vis MCP tools](https://www.npmjs.com/package/@visulima/vis-mcp) — `audit` and `advisory_status` are exposed for AI agents.


# Wrap your package manager (/docs/packages/vis/guides/shell-alias)



# Wrap your package manager [#wrap-your-package-manager]

`vis install` and `vis add` pass unknown subcommands straight through to the detected package manager (npm, pnpm, yarn, bun) but run the marshall pipeline first — typosquats, downloads, archived repos, expired domains, dist signatures, provenance, the s1ngularity compromised-publish shape, new bin scripts, metadata, and author/publisher heuristics. The cleanest way to get that protection on every install is to alias your package manager to vis.

## Bash / Zsh [#bash--zsh]

Add to `~/.bashrc` or `~/.zshrc`:

```bash
alias npm='vis'
alias pnpm='vis'
alias yarn='vis'
alias bun='vis'
```

Reload (`source ~/.bashrc`) and your existing muscle memory keeps working — `npm install`, `pnpm add foo`, `yarn upgrade`, etc., all flow through vis.

## Fish [#fish]

`~/.config/fish/config.fish`:

```fish
alias npm 'vis'
alias pnpm 'vis'
alias yarn 'vis'
alias bun 'vis'
```

## Per-project (mise / direnv / nix-shell) [#per-project-mise--direnv--nix-shell]

Drop a one-line wrapper script into a tools directory you already shim onto `PATH`. For [mise](https://mise.jdx.dev):

```toml
# .mise.toml
[hooks]
enter = "alias npm='vis' && alias pnpm='vis' && alias yarn='vis' && alias bun='vis'"
```

For [direnv](https://direnv.net):

```bash
# .envrc
alias npm='vis'
alias pnpm='vis'
alias yarn='vis'
alias bun='vis'
```

## What passes through [#what-passes-through]

`vis install <args…>` and `vis add <args…>` are the integration points:

* **Marshalls fire first.** Each pre-install marshall (see below) runs against the named packages. Errors abort the install; warnings show a 15-second countdown you can cancel with Ctrl-C.
* **Then vis hands off** to the detected package manager with the original args. `vis install --frozen-lockfile --prod` becomes `pnpm install --frozen-lockfile --prod` (or `npm ci --omit=dev`, etc.) when `pnpm` is the detected PM.

The detection cascades: explicit `packageManager` field in `package.json` → lockfile → corepack → `$PATH`. Override with `--pm`.

## Skipping checks [#skipping-checks]

Per-invocation:

```bash
vis add lodash --no-typosquat-check          # skip the typosquat marshall only
VIS_DISABLE_AUTO_CONTINUE=1 vis add lodash   # require explicit y/N on warnings
MARSHALL_DISABLE_ALL=1 vis add lodash         # disable every marshall (emergency escape hatch)
```

Per-marshall, by environment variable:

| Marshall        | Env var                               |
| --------------- | ------------------------------------- |
| typosquats      | `MARSHALL_DISABLE_TYPOSQUATS=1`       |
| installScripts  | `MARSHALL_DISABLE_INSTALL_SCRIPTS=1`  |
| firstSeen       | `MARSHALL_DISABLE_FIRST_SEEN=1`       |
| publisherChange | `MARSHALL_DISABLE_PUBLISHER_CHANGE=1` |
| score           | `MARSHALL_DISABLE_SCORE=1`            |
| malware         | `MARSHALL_DISABLE_MALWARE=1`          |
| vulnerability   | `MARSHALL_DISABLE_VULNERABILITY=1`    |
| license         | `MARSHALL_DISABLE_LICENSE=1`          |
| unexpectedDeps  | `MARSHALL_DISABLE_UNEXPECTED_DEPS=1`  |
| author          | `MARSHALL_DISABLE_AUTHOR=1`           |
| expiredDomains  | `MARSHALL_DISABLE_EXPIRED_DOMAINS=1`  |
| signatures      | `MARSHALL_DISABLE_SIGNATURES=1`       |
| provenance      | `MARSHALL_DISABLE_PROVENANCE=1`       |
| s1ngularity     | `MARSHALL_DISABLE_S1NGULARITY=1`      |
| newBin          | `MARSHALL_DISABLE_NEW_BIN=1`          |
| downloads       | `MARSHALL_DISABLE_DOWNLOADS=1`        |
| metadata        | `MARSHALL_DISABLE_METADATA=1`         |
| archivedRepo    | `MARSHALL_DISABLE_ARCHIVED_REPO=1`    |

Per-project, in `vis.config.ts`:

```ts
export default {
    security: {
        author: { enabled: false },
        expiredDomains: { allowDomains: ["legacy-corp.example"] },
        downloads: { allowlist: ["@myorg/private-pkg"], warnThreshold: 1000 },
    },
};
```

## Pre-flight without installing [#pre-flight-without-installing]

For one-off vetting, `vis inspect` runs the marshall pipeline against a package without touching the lockfile:

```bash
vis inspect express
vis inspect lodash@4.17.21
vis inspect express --json | jq '.findings[]'
vis inspect express --strict      # exit non-zero on warnings too
vis inspect express --only author,downloads
```

Use it in code review (`vis inspect <new-dep>` before merging a PR that adds a dependency) or in CI for vetting third-party additions.

## Verifying the alias [#verifying-the-alias]

```bash
which npm           # → alias to vis
vis --version
vis inspect lodash  # smoke test that the pipeline runs
```

If `which npm` still shows the real npm binary, your alias wasn't sourced — check the alias is in the correct shell config and that you've re-opened your shell.


# Why vis vs. Vite Task / Turbo / Nx / moon (/docs/packages/vis/guides/why-vis)



# Why vis vs. Vite Task / Turbo / Nx / moon [#why-vis-vs-vite-task--turbo--nx--moon]

Every monorepo task runner caches builds and schedules dependencies. The differences live a layer deeper — in remote-cache backends, AI-agent integration, cross-invocation services, and operational ergonomics. This page is a fast read on where vis pulls ahead.

## At a glance [#at-a-glance]

|                                                                   |                                                  vis                                                 |           Vite Task           |  Turbo 2.6 |   Nx 22 (no Cloud)   |               moon 2.0               |
| ----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------: | :---------------------------: | :--------: | :------------------: | :----------------------------------: |
| Local content-addressed cache                                     |                                                   ✅                                                  |               ✅               |      ✅     |           ✅          |                   ✅                  |
| Affected detection                                                |                                                   ✅                                                  |               ❌               |      ✅     |           ✅          |                   ✅                  |
| HTTP remote cache (Turbo-compat)                                  |                                                   ✅                                                  |               ❌               |      ✅     |   community plugins  |                   ✅                  |
| **REAPI gRPC remote cache** (bazel-remote / BuildBuddy / EngFlow) |                                                   ✅                                                  |               ❌               |      ❌     |           ❌          |                   ✅                  |
| **HMAC-signed cache artifacts**                                   |                                                   ✅                                                  |               ❌               |  ✅ (HMAC)  |           ❌          |                   ❌                  |
| **`cache why <task>` hash diff**                                  |                                                   ✅                                                  |               ❌               |      ❌     |           ❌          |                   ❌                  |
| **Cache restoration fidelity** (mtime / perms)                    |                                                   ✅                                                  |         ⚠ open issues         |   partial  |        partial       |                partial               |
| Cache retention (`--keep-last` / `--max-age` / `--max-size`)      |                                                   ✅                                                  |             ❌ open            |      ❌     |           ❌          |           `--lifetime` only          |
| Worktree-aware shared cache                                       |                                                   ✅                                                  |               ❌               |      ❌     |       ✅ (22.7+)      |                   ❌                  |
| **MCP server for AI agents**                                      |                                              ✅ (8 tools)                                             |               ❌               | skill only | ✅ (docs + workspace) |          ✅ (7 tools, v1.37+)         |
| **`ai heal` self-healing CI**                                     |                                          ✅ (GH/GL/Buildkite)                                         |               ❌               |      ❌     |     ✅ Cloud-only     |                   ❌                  |
| **`vis service` cross-invocation registry**                       |                                                   ✅                                                  |               ❌               |      ❌     |           ❌          |                   ❌                  |
| Watch mode                                                        |                                                   ✅                                                  |             ❌ open            |      ✅     |           ✅          |                   ❌                  |
| Conditional + finally / always tasks                              |                                          `when:` + `always:`                                         |               ❌               |      ❌     |        partial       | partial (`os`/`runInCI`, no finally) |
| Plugin / fingerprint hooks                                        |                                             ✅ (14 hooks)                                             |               ❌               |      ❌     |           ✅          |       ❌ (WASM toolchains only)       |
| Strict env mode                                                   |                                                   ✅                                                  |               ❌               |      ✅     |           ❌          |                   ❌                  |
| Lockfile preflight                                                |                                             ✅ (warn/fail)                                            |               ❌               |      ❌     |           ❌          |         auto-install on drift        |
| Inferred targets (Project Crystal)                                |                                             ✅ (36 tools)                                             |               ❌               |      ❌     |           ✅          |                   ❌                  |
| Docker scaffold w/ lockfile prune                                 |                                                   ✅                                                  |               ❌               |      ✅     |           ❌          |                   ✅                  |
| Run replay (no re-execution)                                      |                                                   ✅                                                  |   partial (`--last-details`)  |      ❌     |           ❌          |                   ❌                  |
| Output styles (quiet-on-success)                                  |                                                   ✅                                                  |               ❌               |      ❌     |           ❌          |           ✅ (`outputStyle`)          |
| Auto syscall input tracing                                        | ❌ ([roadmap](https://github.com/visulima/visulima/blob/alpha/packages/tooling/vis/priority-roadmap)) |            ✅ (fspy)           |      ❌     |           ❌          |                   ❌                  |
| Bundled linter / formatter / bundler                              |                                           ❌ (orchestrator)                                           | ✅ (Oxlint / Oxfmt / Rolldown) |      ❌     |        partial       |                   ❌                  |
| Catalog management (pnpm / bun)                                   |                                                   ✅                                                  |            wraps PM           |      ❌     |           ❌          |                   ❌                  |
| Built-in secret scanner                                           |                                       ✅ (gitleaks engine, Rust)                                      |               ❌               |      ❌     |           ❌          |                   ❌                  |
| OSV vulnerability scan                                            |                                                   ✅                                                  |               ❌               |      ❌     |           ❌          |                   ❌                  |

Status sources: [Vite Task open issues](https://github.com/voidzero-dev/vite-task/issues), [Turborepo docs](https://turborepo.dev/docs), [Turborepo AI integration](https://turborepo.dev/docs/guides/ai), [Nx docs](https://nx.dev) + [Nx MCP reference](https://nx.dev/docs/reference/nx-mcp), [moon docs](https://moonrepo.dev/docs) + [moon MCP guide](https://moonrepo.dev/docs/guides/mcp), [moon 2.0 release notes](https://moonrepo.dev/blog/moon-v2.0), and [monorepo.tools comparison](https://monorepo.tools/compare). vis state mirrors `priority-roadmap.md` in the same directory.

## When to pick vis [#when-to-pick-vis]

**You're running AI coding agents against the workspace.** vis ships an MCP server (`@visulima/vis-mcp`) with eight read-only introspection tools — projects, targets, templates, run logs, `cache why`, `cache hash` — plus a paired Claude Skill. moon (v1.37+) ships seven tools; Nx ships docs + workspace analysis but gates CI / self-healing behind Nx Cloud. vis adds `vis ai heal`: propose patch → validate → comment to PR/MR (GitHub, GitLab, Buildkite) → land as a signed commit on `/vis heal accept` from an allow-listed maintainer. Self-healing is the differentiator — neither moon nor open-source Nx ships it; Nx requires Cloud.

**Your remote cache is bazel-remote, BuildBuddy, BuildBarn, or EngFlow.** vis speaks REAPI over gRPC natively. Turbo and Nx (without paid Cloud / a custom plugin) only do their proprietary HTTP wire format.

**You hate restarting Postgres between every test run.** `vis service start postgres` registers a long-lived service in `~/.vis-services/`. Targets that declare `service: { id: "postgres" }` auto-attach when alive, error with a useful diagnostic when dead. The service survives across `vis run` calls within your shell session — and across them.

**You debug cache misses for a living.** `vis cache why <task>` reads the prior run's `hashDetails` and tells you which bucket (`command` / `nodes` / `runtime` / `implicitDeps`) rotated the hash. `vis cache verify` flags drift between the cached archive and the live workspace. `vis replay <runId>` renders any past summary without re-executing.

**You signed up for Turbo's promise but want HMAC-signed cache without Vercel.** vis's HMAC-SHA256 signing is config-only (no CLI flag — typos can't disable it on a production cache); `verifyOnDownload` rejects tampered or unsigned artifacts.

**You want `lint-staged` + git hooks + secret scanning + OSV audit + Docker lockfile pruning + catalog management, all without composing six tools.** vis ships them in-box.

## When to pick something else [#when-to-pick-something-else]

**Your monorepo is Vite-centric and you want the toolchain unified.** [Vite+ alpha](https://viteplus.dev) bundles Vite + Vitest + Oxlint + Oxfmt + Rolldown + tsdown + Vite Task in one binary. The Oxc-speed defaults (\~50–100× ESLint, \~30× Prettier) are real. vis is the orchestrator; you'd still wire each tool yourself.

**You need real-time distributed agents at PR scale.** Nx Cloud's Agents auto-scale based on PR size. vis's "shared cache + Redis lock" Cobuilds-style pattern handles the same load for most teams, but if you need the auto-scaling and per-PR resource telemetry, Nx Cloud is the answer.

**Your shop is Bazel/Buck2/Pants and you want first-class polyglot.** vis is JS-first (Rust-augmented). For Gradle / Maven / .NET / Python parity, Bazel-family tools or Nx (with the polyglot plugins) fit better.

**You want zero-config caching with no declared `inputs`.** Vite Task's syscall-traced inputs (via `fspy`) are qualitatively different from declared-inputs hashing. vis hashes declared `inputs` (or Project Crystal-inferred ones); a syscall-trace alternative hash mode is on the priority roadmap (item 32) but not shipped.

## Migration notes [#migration-notes]

* **From Turbo:** vis's HTTP backend honours `TURBO_API` / `TURBO_TOKEN` / `TURBO_TEAM` as fallbacks when `taskRunner.remoteCache.{url,token,teamId}` is unset, so an existing Turbo CI environment keeps working unchanged. `vis migrate turbo` (when shipped) will rewrite `turbo.json` into `vis-config.ts` + per-package `vis.task.ts`. Today, declare targets in `vis-config.ts` and keep the Turbo cache running side-by-side during cutover.
* **From Nx:** `project.json` is read directly — no migration needed for the project graph. Targets defined in `project.json` work as-is; vis adds `vis.task.ts` overlay for per-package tweaks.
* **From moon:** Moon's `tasks.yml` syntax is close enough that hand-porting a project takes minutes. `vis generate buildkite-ci` and friends already use moon's template format (Tera + frontmatter), so generators carry over.
* **From `lint-staged` + `husky` + `gitleaks` + `secretlint`:** `vis migrate gitleaks`, `vis migrate secretlint`, and `vis hook install` collapse all four into vis. `vis staged` is a drop-in for `lint-staged`'s config shape.

## Honest gaps [#honest-gaps]

vis isn't ahead on everything:

* **Auto-tracked inputs.** Vite Task's fspy approach eliminates the "I forgot to add this to inputs" pain. vis requires declared inputs (or `inferTargets` Crystal inference). Roadmap item 32 covers it.
* **Compound-command sub-task splitting.** Vite Task auto-splits `cmd1 && cmd2` so each segment caches independently. vis caches the whole script. Roadmap item 33 covers it.
* **Single-config-everything.** Vite+ keeps Vite + Vitest + lint + fmt + run + staged config in one `vite.config.ts`. vis already supports a single `vis-config.ts`, but it's an orchestrator — the linter, formatter, and bundler stay separate tools you wire yourself.
* **Distributed real-time agents.** vis ships shared-cache cobuilds, not Nx-Cloud-style auto-scaling agents.

## Further reading [#further-reading]

* [REAPI remote caching guide](/docs/packages/task-runner/concepts/remote-caching) (in `@visulima/task-runner`)
* [`vis cache` command reference](/docs/packages/vis/commands/cache)
* [`vis service` command reference](/docs/packages/vis/commands/service)
* [`vis ai heal` flow](/docs/packages/vis/guides/ai-integration)
* [Plugin API](/docs/packages/vis/guides/plugins)
* [CI/CD presets](/docs/packages/vis/guides/ci-cd)


# Introduction (/docs/packages/vis)



# Visulima Vis [#visulima-vis]

**One CLI for everything your monorepo needs** — task running, caching, dependency management, releases, security audits, and AI-agent integration. Powered by [@visulima/task-runner](https://www.npmjs.com/package/@visulima/task-runner) and [@visulima/cerebro](https://www.npmjs.com/package/@visulima/cerebro).

```bash
vis run build              # Run a target across the workspace
vis affected test          # Test only what changed
vis release ci release     # Ship versions, changelogs, tags
vis ai heal                # Let Claude / Cursor fix failing tasks
```

Drop-in for Turbo and Vite Task; the breadth of Nx without the platform lock-in. See [Why vis vs. the alternatives](/docs/packages/vis/guides/why-vis) for the side-by-side capability matrix.

## Key Features [#key-features]

**Built for AI agents*&#x2A; &#x2A;(unique vs. Turbo / Nx-without-Cloud / moon / Vite Task)*

* **MCP server** — `@visulima/vis-mcp` exposes 8 read-only introspection tools to Claude / Cursor / Copilot, plus a paired Claude Skill
* **`vis ai heal`** — propose-validate-comment loop on the failing task; `/vis heal accept` lands the patch as a signed commit (GitHub Actions, GitLab CI, Buildkite)
* **Worktree-aware shared cache** — N parallel agents in N sibling git worktrees share one cache automatically

**Release management*&#x2A; &#x2A;(matches changesets / semantic-release / release-please feature-for-feature)*

* **`vis release`** — change-file authoring, channel routing, version-PR mode, auto-publish for prereleases, snapshot previews, NAPI sidecar support
* **One-command migration** — `vis release init` detects changesets / semantic-release / bumpy and migrates in place
* **CI drivers built-in** — `vis release ci release / snapshot / check / plan` for GitHub Actions and GitLab CI
* See the [release guide](/docs/packages/vis/guides/release) for the 5-minute quickstart

**Production-grade caching**

* **REAPI gRPC + HTTP backends** — drop-in support for bazel-remote, BuildBuddy, BuildBarn, EngFlow alongside Turbo-compatible HTTP; `vis cache doctor` for CI gating
* **`vis cache why <task>`** — diff hash buckets vs. the previous run to pinpoint what rotated
* **HMAC-SHA256 signed artifacts** — `verifyOnDownload` locks production caches against tampering
* **Cache restoration fidelity** — preserves mtime + perms + colors; `vis cache verify` flags drift
* **Retention controls** — `vis cache prune --keep-last/--max-age-days/--max-size`

**Cross-invocation devloop**

* **`vis service`** — long-lived DB / mock / devserver lifecycle that survives across `vis run` calls; auto-attached when targets declare `service:`
* **`vis run --watch`** — Vitest-style keybinds, Windows-clean SIGINT
* **`vis run --output-style=quiet`** — swallow stdout from successful tasks, keep failures visible

**Workspace orchestration**

* Workspace-aware (pnpm, npm, yarn, bun); topological scheduling with configurable parallelism
* Affected detection with `${affected.files}` / `$AFFECTED_FILES` token forwarding
* Conditional (`when:`) and finally (`always:`) tasks
* Per-package `vis.task.ts` overlay + root `extends` chain
* Inferred targets (Project Crystal-style) for 36 tools — opt-in via `inferTargets: true`
* Plugin / fingerprint hooks via `definePlugin`
* Strict env mode + lockfile preflight
* Project graph in ASCII / DOT / JSON / HTML

**Adjacent tooling that ships in-box**

* `vis catalog check / update` — pnpm + bun catalog management
* `vis secrets` — Rust-native secret scanning (gitleaks engine)
* `vis audit` — OSV.dev vulnerability scanning
* `vis docker scaffold` — lockfile pruning for pnpm / npm / yarn classic+berry / bun
* `vis hook install / migrate` — git hooks (husky migration supported)
* `vis staged` — built-in `lint-staged` replacement
* `vis replay` — re-render past run summaries without re-execution

**Toolchain & runtime**

* Pluggable installer (aube auto-detection or pinned PM)
* Cold-start one-liner (Linux/macOS/PowerShell)
* `vis toolchain` delegates to proto / mise / fnm / volta
* Built on Cerebro for help / version / shell completion

## A typical day with vis [#a-typical-day-with-vis]

```bash
# Morning: pull, install, see what changed
git pull
vis install
vis affected lint test --base=main

# Build only what's affected, watch tests
vis run build --watch

# Record a version bump for the change you just made
vis release add --packages '@scope/cerebro:minor' --message 'Add tab completion'

# Push — CI handles tagging, changelogs, npm publish
git push
```

## Next Steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/packages/vis/installation">
    Set up vis in your workspace
  </Card>

  <Card title="Quick Start" href="/docs/packages/vis/quick-start">
    The 10-minute walkthrough
  </Card>

  <Card title="Release Manager" href="/docs/packages/vis/guides/release">
    Ship versions, changelogs, and tags from change files
  </Card>

  <Card title="Commands" href="/docs/packages/vis/commands/run">
    Full command reference
  </Card>

  <Card title="Best Practices" href="/docs/packages/vis/guides/best-practices">
    Team workflows, security, and CI/CD patterns
  </Card>
</Cards>


# Installation (/docs/packages/vis/installation)



# Installation [#installation]

Install vis using your preferred package manager:

```bash npm2yarn
npm install @visulima/vis
```

> 💡 &#x2A;*In a new repo?** vis works in single-package repos too, but it shines on monorepos. If you're starting fresh, scaffold the workspace first (`pnpm init`, add `pnpm-workspace.yaml`, then install vis).

## Requirements [#requirements]

* **Node.js**: 20.19 or higher
* **Workspace**: A monorepo using pnpm, npm, yarn, bun, deno, or [aube](https://github.com/endevco/aube) workspaces

## Optional: aube as the installer backend [#optional-aube-as-the-installer-backend]

`vis install` (and the rest of the PM commands) can use [aube](https://github.com/endevco/aube) — a Rust-native package manager that reads and writes pnpm/npm/yarn/bun lockfiles in place — instead of the lockfile-detected PM. Aube supports pnpm catalogs, including walk-up resolution from subpackages, so visulima-style monorepos work transparently.

`vis` does not bundle aube. Install it separately:

```bash
npm install -g @endevco/aube
# or
mise use -g aube
# or
brew install endevco/tap/aube
```

By default, `vis` auto-detects aube on `PATH` and uses it; pass `--no-aube` to bypass it for one run, or set `install.backend` in `vis.config.ts` to pin the choice across the team. See [Configuration → Installer Backend](/docs/packages/vis/configuration#installer-backend) for the full resolution chain and the lockfile-drift caveat.

## Binary Commands [#binary-commands]

After installation, two binary commands are available:

* `vis` — Full command name
* `v` — Short alias

Both point to the same CLI entry point.

## Verification [#verification]

Verify your installation by running:

```bash
vis --help
```

You should see the list of available commands — `run`, `affected`, `graph`, `check`, `update`, `hook`, `release`, and more.

## Next steps [#next-steps]

* **[Quick Start](/docs/packages/vis/quick-start)** — the 10-minute walkthrough of everyday commands
* **[Configuration](/docs/packages/vis/configuration)** — set up `vis.config.ts` for your workspace
* **[Release manager](/docs/packages/vis/guides/release)** — wire up automated releases with change files


# Quick Start (/docs/packages/vis/quick-start)



# Quick Start [#quick-start]

This guide walks you through the workflows you'll touch every day. Stops at "you can ship code with vis"; for the deeper picture, follow the links at each section's end.

> 💡 &#x2A;*Already installed?** Skip to [Running Tasks](#running-tasks). New here? Start with [Installation](/docs/packages/vis/installation).

## Running Tasks [#running-tasks]

Run a target across all workspace projects in dependency order:

```bash
vis run build
```

Run with increased parallelism:

```bash
vis run build --parallel=5
```

Run only specific projects:

```bash
vis run test --projects=@my/app,@my/lib
```

Preview what would run without executing:

```bash
vis run build --dry-run
```

## Affected Detection [#affected-detection]

Only run tasks for projects changed since a git ref:

```bash
vis affected test --base=main
```

Compare specific git refs:

```bash
vis affected lint --base=HEAD~5 --head=HEAD
```

## Checking for Outdated Dependencies [#checking-for-outdated-dependencies]

For pnpm or bun workspaces with catalogs, check which dependencies are outdated:

```bash
vis check
```

Check only specific packages:

```bash
vis check react typescript
```

Only show minor and patch updates:

```bash
vis check --target minor
```

## Updating Dependencies [#updating-dependencies]

Update catalog dependencies interactively:

```bash
vis update --interactive
```

Update only patch versions (safe for production):

```bash
vis update --target patch
```

Preview changes without applying:

```bash
vis update --dry-run
```

Rollback if something goes wrong:

```bash
vis update --rollback
```

## Visualizing the Dependency Graph [#visualizing-the-dependency-graph]

View your project dependency graph:

```bash
vis graph
```

Export as DOT format for Graphviz:

```bash
vis graph --format=dot --output=graph.dot
```

## Managing Git Hooks [#managing-git-hooks]

Install git hooks:

```bash
vis hook install
```

Migrate from husky:

```bash
vis hook migrate
```

## Releasing a version [#releasing-a-version]

Set up the release subsystem and migrate from an existing tool if you have one:

```bash
vis release init --workflows
```

Record a version bump for the change you just made:

```bash
vis release add --packages '@scope/cerebro:minor' --message 'Add tab completion'
```

Commit the resulting `.vis/release/<slug>.md&#x60; alongside your code and push. CI takes care of opening the **"Versioned release" PR**, publishing on merge, tagging, and creating GitHub / GitLab releases.

See the [release guide](/docs/packages/vis/guides/release) for the full walkthrough — change files, channels, snapshots, and CI setup.

## Configuration [#configuration]

Create a `vis.json` in your workspace root for persistent configuration:

```json
{
    "tasks": {
        "build": {
            "dependsOn": ["^build"],
            "outputs": ["{projectRoot}/dist/**"],
            "cache": true
        }
    },
    "update": {
        "target": "minor",
        "exclude": ["legacy-*"]
    }
}
```

See the [Configuration](/docs/packages/vis/configuration) page for all available options.

## Where to next [#where-to-next]

* **[Release manager](/docs/packages/vis/guides/release)** — ship versions, changelogs, and tags from change files
* **[Why vis](/docs/packages/vis/guides/why-vis)** — side-by-side capability matrix vs. Turbo / Nx / moon / Vite Task
* **[Best practices](/docs/packages/vis/guides/best-practices)** — team workflows, security, CI/CD patterns
* **[Commands](/docs/packages/vis/commands/run)** — full per-command reference


# API Reference (/docs/packages/vite-overlay/api)



# API Reference [#api-reference]

## `errorOverlayPlugin(options?)` [#erroroverlaypluginoptions]

The default export. A Vite plugin that intercepts and enhances error display.

```typescript
import errorOverlayPlugin from "@visulima/vite-overlay";

// vite.config.ts
export default defineConfig({
    plugins: [errorOverlayPlugin(options)],
});
```

### Options [#options]

| Option                    | Type               | Default     | Description                                           |
| ------------------------- | ------------------ | ----------- | ----------------------------------------------------- |
| `forwardConsole`          | `boolean`          | `true`      | Forward client runtime errors to the terminal         |
| `forwardedConsoleMethods` | `string[]`         | `["error"]` | Console methods to intercept                          |
| `logClientRuntimeError`   | `boolean`          | —           | **Deprecated.** Use `forwardConsole` instead          |
| `overlay`                 | `OverlayConfig`    | —           | Overlay UI configuration                              |
| `reactPluginName`         | `string`           | —           | Custom React plugin name for detection                |
| `vuePluginName`           | `string`           | —           | Custom Vue plugin name for detection                  |
| `showBallonButton`        | `boolean`          | —           | **Deprecated.** Use `overlay.balloon.enabled` instead |
| `solutionFinders`         | `SolutionFinder[]` | `[]`        | Custom solution finder handlers                       |

## Types [#types]

### `OverlayConfig` [#overlayconfig]

```typescript
interface OverlayConfig {
    balloon?: BalloonConfig;
    /** Custom CSS injected into the shadow DOM */
    customCSS?: string | CSSProperties;
}
```

### `BalloonConfig` [#balloonconfig]

```typescript
interface BalloonConfig {
    /** Show/hide the floating balloon button (default: true) */
    enabled?: boolean;
    /** Custom SVG icon for the balloon */
    icon?: string;
    /** Position of the balloon (default: "bottom-right") */
    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
    /** Custom styles for the balloon */
    style?: string | CSSProperties;
}
```

### `VisulimaViteOverlayErrorPayload` [#visulimaviteoverlayerrorpayload]

The error payload sent to the client over WebSocket.

```typescript
interface VisulimaViteOverlayErrorPayload {
    errors: ExtendedError[];
    errorType: "client" | "server";
    rootPath: string;
    solution?: Solution;
}
```

## Client API [#client-api]

The plugin injects a `window.__visulima_overlay__` object for programmatic control:

```typescript
window.__visulima_overlay__.open();         // Show the overlay panel
window.__visulima_overlay__.close();        // Close/dismiss the overlay
window.__visulima_overlay__.getInstance();  // Get the current overlay instance (or null)
window.__visulima_overlay__.sendError(error: Error, loc?: ErrorLocation); // Report an error manually
```

### `ExtendedError` [#extendederror]

```typescript
interface ExtendedError {
    message: string;
    name: string;
    stack: string;
    hint?: string;
    originalFilePath: string;
    originalFileLine: number;
    originalFileColumn: number;
    originalSnippet: string;
    originalStack?: string;
    originalCodeFrameContent?: string;
    compiledFilePath?: string;
    compiledLine?: number;
    compiledColumn?: number;
    compiledStack?: string;
    compiledCodeFrameContent?: string;
    fixPrompt: string;
    plugin?: string;
    errorCount?: number;
}
```


# Introduction (/docs/packages/vite-overlay)



# @visulima/vite-overlay [#visulimavite-overlay]

Enhanced error overlay for Vite with beautiful stack traces, source map support, and better error formatting.

## Key Features [#key-features]

* **Enhanced Stack Traces** - Clear, readable error stacks with source map resolution
* **Source Map Support** - Accurate file locations pointing to your original source files
* **Cause Chain Display** - Full error cause chains rendered in the overlay
* **Solution Suggestions** - Actionable hints to help resolve common errors
* **Balloon Notification** - Compact floating badge when the overlay is dismissed
* **SSR Error Enhancement** - Improved server-side error display with file context
* **Framework Detection** - Automatic React and Vue error formatting
* **Dark/Light Mode** - Follows system theme preference

## Installation [#installation]

```bash npm2yarn
npm install @visulima/vite-overlay
```

## Basic Usage [#basic-usage]

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import visulimaViteOverlay from "@visulima/vite-overlay";

export default defineConfig({
    plugins: [visulimaViteOverlay()],
});
```

## Configuration [#configuration]

```typescript
visulimaViteOverlay({
    // Forward client runtime errors to the terminal (default: true)
    forwardConsole: true,

    // Console methods to intercept (default: ["error"])
    forwardedConsoleMethods: ["error", "warn"],

    // Overlay UI customization
    overlay: {
        balloon: {
            // Show/hide the floating balloon button (default: true)
            enabled: true,
            // Balloon position (default: "bottom-right")
            position: "bottom-right",
            // Custom inline style for the balloon
            style: "",
            // Custom SVG icon for the balloon
            icon: "",
        },
        // Inject custom CSS into the overlay
        customCSS: "",
    },

    // Custom solution finders
    solutionFinders: [],
});
```


# Usage (/docs/packages/vite-overlay/usage)



# Usage Guide [#usage-guide]

## Vite Plugin [#vite-plugin]

```typescript
// vite.config.ts
import { viteOverlay } from "@visulima/vite-overlay";

export default {
    plugins: [viteOverlay()],
};
```

## Custom Error Display [#custom-error-display]

```typescript
import { showError } from "@visulima/vite-overlay";

try {
    // code
} catch (error) {
    showError(error);
}
```


# Concurrency & exactly-once (/docs/packages/workflow/concurrency)



# Concurrency & exactly-once [#concurrency--exactly-once]

`ctx.step` runs a side effect **exactly once per run — as long as activations of that run don't overlap**. This page
explains what enforces that, the difference between *mutual exclusion* and *exactly-once*, and how to close the
remaining gap.

## Three levels of protection [#three-levels-of-protection]

### 1. In-process serialisation (always on) [#1-in-process-serialisation-always-on]

Within a single process, the runtime serialises overlapping `resume` / `signal` / `sweep` calls for the same run with a
per-run mutex. Two `sweep` ticks that overlap, or a `sweep` racing an inbound `signal`, can't both drive the same run at
once. This needs no configuration and no store support.

### 2. Cross-process lease (opt-in via the store) [#2-cross-process-lease-opt-in-via-the-store]

The in-process mutex does **not** span processes. If you run several runtime instances against one shared store
(multiple workers, multiple regions), two of them can each `load` the same pre-resume state and both drive it.

To extend exclusion across instances, implement the optional `acquire` / `release` on your
[store](/docs/packages/workflow/stores). The runtime calls `acquire` before driving a run and `release` after; if the
lease is held elsewhere it returns the run's current state instead of driving it.

```typescript
const runtime = createRuntime({ store, leaseTtlMs: 30_000 }); // default 30s
```

`leaseTtlMs` must exceed the longest expected single activation. `MemoryStore` implements the lease exactly;
`UnstorageStore` implements it **best-effort** — its read-check-write is not atomic, so two callers racing on a non-CAS
driver can both win.

For race-free cross-process exclusion you need a store backed by an **atomic primitive**:

* **Redis** — `SET key token NX PX ttl`.
* **SQL (Postgres/MySQL)** — a row lock (`SELECT … FOR UPDATE`) or advisory lock.
* **Durable Object** — execution inside a DO is already serialised, so `acquire` is a plain in-object check (and the
  cleanest correct implementation).

## Mutual exclusion is not crash-proof exactly-once [#mutual-exclusion-is-not-crash-proof-exactly-once]

A lease gives **mutual exclusion**: no two activations run *concurrently*. It does **not** give crash-proof
exactly-once. Consider one process that:

1. acquires the lease,
2. runs a `ctx.step` side effect (sends an email),
3. **crashes before persisting the step record.**

The lease eventually expires, another worker acquires it, replays the run, finds no record for that step, and runs it
again — the email is sent twice. This is fundamental: a lock cannot make a side effect and its durable record commit
atomically when the effect lives in a different system from the store.

```
acquire ── step.fn() runs (email sent) ── ✗ crash ── lease expires ── re-acquire ── step.fn() runs again
                                          ↑ record never persisted, so replay re-runs it
```

So the precise guarantees are:

| Mechanism                         | Guarantee                                         |
| --------------------------------- | ------------------------------------------------- |
| In-process mutex                  | No concurrent double-exec within one process      |
| Store lease (`acquire`/`release`) | No concurrent double-exec across processes        |
| Idempotent effects                | The only path to true exactly-once across crashes |

## Closing the crash window [#closing-the-crash-window]

Make the effect itself idempotent, keyed on the stable, replay-deterministic id `runId:stepId`:

```typescript
run: async (ctx) => {
    await ctx.step("charge", () =>
        // the same idempotency key on replay → the provider dedupes the retry
        stripe.charges.create({ amount, currency }, { idempotencyKey: `${ctx.runId}:charge` }),
    );
};
```

With idempotent effects you get end-to-end exactly-once even across crashes; without them, treat delivery as
**at-least-once** and design the downstream to tolerate a retry.

## Why not optimistic concurrency (CAS on save)? [#why-not-optimistic-concurrency-cas-on-save]

Compare-and-swap on the persisted record prevents the *history* from diverging, but the losing activation has **already
executed** the side effect before its save is rejected — so CAS alone yields at-least-once effects. To prevent the
*execution* (not just the write) you must take the lock **before** driving, which is why the lease is pessimistic.


# Durability & replay (/docs/packages/workflow/durability)



# Durability & replay [#durability--replay]

`@visulima/workflow` uses a **replay** model (the same approach as Temporal, Inngest and TanStack Workflow): there is no
serialised continuation of your function — instead the body is re-run from the top on every activation, and already-done
work is short-circuited from a recorded history.

## The execution loop [#the-execution-loop]

1. **Trigger.** The payload is validated, a run id is generated, and the body runs from the top.
2. **Steps record.** Each `ctx.step(id, fn)` runs `fn` once and appends `{ id, output }` to an append-only history.
3. **Suspend.** The first `ctx.sleep` / `ctx.waitForEvent` that is not yet satisfied throws an internal signal that
   unwinds the body. The engine persists the run (lifecycle snapshot + history + what it is waiting on).
4. **Resume.** On `sweep` (a due sleep/timeout) or `signal` (an awaited event), the engine appends the resolution to the
   history and **re-runs the body from the top**. This time every prior `ctx.step` finds its recorded output and returns
   it without executing `fn`; the previously-suspended `sleep`/`wait` is now satisfied and execution continues to the
   next durable point.
5. **Complete / fail.** When the body returns, the run is `completed` with its output; if it throws, the run is `failed`
   with the serialised error.

## Why "the one rule" matters [#why-the-one-rule-matters]

Because the body is re-run on every activation, **only** work wrapped in `ctx.step` is guarded against re-execution.
A bare side effect runs again on each replay:

```typescript
run: async (ctx) => {
    sendEmail(); // ❌ runs on every replay — once per activation
    await ctx.step("welcome", () => sendEmail()); // ✅ runs exactly once
    await ctx.sleep("wait", { amount: 1, unit: "days" });
    await ctx.step("nudge", () => sendNudge()); // ✅ runs once, after the sleep
};
```

## Determinism [#determinism]

The replay short-circuit means recorded steps return instantly and identically, and `Date.now()` is read only when a
*new* sleep/wait first suspends — never on the replay path — so resuming an existing run is deterministic. Keep your
own logic deterministic too: branch on `ctx.payload` and recorded step outputs, not on ambient state that can change
between activations.

## What gets persisted [#what-gets-persisted]

The unit a [store](/docs/packages/workflow/stores) keeps is JSON-serialisable: the lifecycle snapshot, the step history
(so step outputs must be JSON-safe), and denormalised `status` / `wakeAt` / `eventName` fields so the store can answer
"what is due" and route signals without parsing the snapshot.

## Lifecycle [#lifecycle]

A run is modelled as an [XState](https://stately.ai/docs) state machine — `running → suspended | waiting → running →
completed | failed` — which owns the legal transitions and produces the snapshot that the store persists. `running` is
transient and never observed at an API boundary; `getRun`/results report `suspended`, `waiting`, `completed` or
`failed`.


# Getting started (/docs/packages/workflow/getting-started)



# Getting started [#getting-started]

## 1. Define a workflow [#1-define-a-workflow]

A workflow is an id, an optional payload schema, and a `run` function driven by the run context (`ctx`).

```typescript
import { defineWorkflow } from "@visulima/workflow";
import { z } from "zod";

const order = defineWorkflow({
    id: "order-fulfilment",
    payload: z.object({ orderId: z.string() }),
    run: async (ctx) => {
        await ctx.step("charge", () => charge(ctx.payload.orderId));
        await ctx.sleep("settle", { amount: 1, unit: "hours" });
        await ctx.step("ship", () => ship(ctx.payload.orderId));
    },
});
```

The `payload` schema may be any [Standard Schema](https://standardschema.dev) validator; it is validated on `trigger`
and the result is typed inside `run` as `ctx.payload`.

## 2. Create a runtime and trigger a run [#2-create-a-runtime-and-trigger-a-run]

```typescript
import { createRuntime } from "@visulima/workflow";

const runtime = createRuntime({ workflows: [order] });

const result = await runtime.trigger(order, { orderId: "o_1" });
// result.status is "suspended" (sleeping), "completed", or "failed".
// result.runId identifies this run for later resume / inspection.
```

`trigger` returns as soon as the run first **suspends** (or completes). The default store is in-memory; pass your own
via `createRuntime({ store })` for durability — see [Stores](/docs/packages/workflow/stores).

You can also register workflows **after** the runtime is created with `register()` — useful for dynamic or
lazily-loaded workflows, and required so a worker can resume runs of a workflow it didn't define at startup:

```typescript
const runtime = createRuntime();

runtime.register(order);

await runtime.trigger("order-fulfilment", { orderId: "o_1" }); // trigger by id once registered
```

## 3. Resume due runs [#3-resume-due-runs]

Sleeps and timeouts are advanced by **sweeping**. Call `sweep()` from a cron job, a Cloudflare alarm, or any timer; it
resumes every run whose wake-at has passed:

```typescript
// e.g. once a minute
const resumed = await runtime.sweep();
```

## 4. Deliver external events [#4-deliver-external-events]

`ctx.waitForEvent` suspends a run until you deliver a matching signal:

```typescript
const review = defineWorkflow({
    id: "publish",
    run: async (ctx) => {
        const decision = await ctx.waitForEvent<{ approved: boolean }>("review", "review-decision", {
            timeout: { amount: 2, unit: "days" }, // resolves to undefined if nobody decides
        });

        if (decision?.approved) {
            await ctx.step("publish", () => publish());
        }
    },
});

const { runId } = await runtime.trigger(review, {});
// later, when a reviewer acts:
await runtime.signal(runId, "review-decision", { approved: true });
```

## 5. Inspect a run [#5-inspect-a-run]

```typescript
const info = await runtime.getRun(runId);
// { runId, status, output?, error?, pending?, history }
```

## After a restart [#after-a-restart]

Re-create the runtime with the **same store** and re-register the workflows, then `sweep`/`signal` as usual — runs
resume from where they left off:

```typescript
const runtime = createRuntime({ store, workflows: [order, review] });
await runtime.sweep();
```


# Introduction (/docs/packages/workflow)



# Workflow [#workflow]

**Reusable, ESM-only, edge-ready durable execution**

`@visulima/workflow` lets you write a long-running process as a plain async function and makes it **resumable**: it
survives process restarts, hour-long delays and waits for external events, replaying deterministically from an
append-only history. It is the generic engine that powers higher-level features such as
[`@visulima/notification`](/docs/packages/notification)'s workflow steps, but it has no notification dependency and is
useful on its own.

## Why @visulima/workflow? [#why-visulimaworkflow]

* **Infra-free** - No dashboard, no SaaS account, no separate server process. Bring any store you already run.
* **Edge-ready** - The engine core and the in-memory / unstorage stores are `fetch` + Web Crypto only, with zero Node
  built-ins, so they run unmodified on Cloudflare Workers, Vercel Edge, Deno and Bun.
* **Code-first** - Workflows are ordinary async functions; durability comes from `ctx.step` / `ctx.sleep` /
  `ctx.waitForEvent`, not a YAML DSL or a visual editor.
* **Type-safe** - Payloads are validated and typed via any [Standard Schema](https://standardschema.dev) validator
  (Zod, Valibot, ArkType).
* **Pluggable durability** - A small `WorkflowStore` contract; an in-memory and an
  [unstorage](https://unstorage.unjs.io) store ship in the box, and you can back runs with Redis, Postgres or a Durable
  Object.

## How it works [#how-it-works]

You define a workflow and drive it through a runtime:

```typescript
import { createRuntime, defineWorkflow } from "@visulima/workflow";
import { z } from "zod";

const onSignup = defineWorkflow({
    id: "welcome",
    payload: z.object({ userId: z.string(), email: z.string() }),
    run: async (ctx) => {
        await ctx.step("send-welcome", () => sendEmail(ctx.payload.email, "Welcome!"));
        await ctx.sleep("wait-a-day", { amount: 1, unit: "days" });

        const activated = await ctx.step("check-activation", () => isActivated(ctx.payload.userId));

        if (!activated) {
            await ctx.step("send-nudge", () => sendEmail(ctx.payload.email, "Need a hand?"));
        }
    },
});

const runtime = createRuntime({ workflows: [onSignup] });

const { runId, status } = await runtime.trigger(onSignup, { userId: "u_1", email: "a@b.com" });
// status === "suspended" — the run is sleeping for a day.
```

The engine re-runs the workflow body from the top on every activation; already-completed steps short-circuit to their
recorded result, and the first unsatisfied `sleep`/`waitForEvent` suspends the run. See
[Durability & replay](/docs/packages/workflow/durability) for the model.

## Next steps [#next-steps]

* [Installation](/docs/packages/workflow/installation)
* [Getting started](/docs/packages/workflow/getting-started)
* [Steps: the `ctx` contract](/docs/packages/workflow/steps)
* [Durability & replay](/docs/packages/workflow/durability)
* [Stores](/docs/packages/workflow/stores)
* [Concurrency & exactly-once](/docs/packages/workflow/concurrency)


# Installation (/docs/packages/workflow/installation)



# Installation [#installation]

```sh
npm install @visulima/workflow
```

```sh
yarn add @visulima/workflow
```

```sh
pnpm add @visulima/workflow
```

## Dependencies [#dependencies]

The engine ships with a small, fixed dependency set:

* [`xstate`](https://stately.ai/docs) — models the run lifecycle and produces the persisted snapshot.
* [`croner`](https://github.com/hexagon/croner) — cron/interval math for delays (zero-dependency, edge-safe).
* [`@standard-schema/spec`](https://standardschema.dev) — the types-only payload-validation contract.

[`unstorage`](https://unstorage.unjs.io) is an **optional** peer, needed only if you use the `UnstorageStore`.

## Runtime support [#runtime-support]

The engine core and the in-memory / unstorage stores are `fetch` + Web Crypto only — no `node:*` — so they run on:

| Runtime            | Core + MemoryStore / UnstorageStore | Notes                                          |
| ------------------ | ----------------------------------- | ---------------------------------------------- |
| Node.js            | ✅                                   | `^22.14.0 \|\| >=24.10.0`                      |
| Cloudflare Workers | ✅                                   | back the store with KV / D1 / a Durable Object |
| Vercel Edge        | ✅                                   | back the store with a KV/SQL driver            |
| Deno               | ✅                                   |                                                |
| Bun                | ✅                                   |                                                |

Node-only durability (Postgres, Redis) lives entirely behind your own
[`WorkflowStore`](/docs/packages/workflow/stores) adapter — the engine itself stays edge-pure.


# Steps (/docs/packages/workflow/steps)



# Steps: the `ctx` contract [#steps-the-ctx-contract]

Every durable operation goes through the run context (`ctx`) so the engine can record, skip and resume it
deterministically.

| Method                              | What it does                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ctx.step(id, fn)`                  | Runs `fn` **exactly once**; records the result. On replay the recorded value is returned without re-running. |
| `ctx.sleep(id, duration)`           | Durably pauses until the duration elapses.                                                                   |
| `ctx.waitForEvent(id, name, opts?)` | Durably suspends until a matching `runtime.signal(...)` arrives, or the optional `timeout` elapses.          |
| `ctx.payload`                       | The validated trigger payload (typed via your Standard Schema).                                              |
| `ctx.runId`                         | The id of the current run.                                                                                   |

> **The one rule:** anything that must happen exactly once **must** be wrapped in `ctx.step`. Code outside
> `step` / `sleep` / `waitForEvent` re-executes on every replay, by design.

## `ctx.step(id, fn)` [#ctxstepid-fn]

```typescript
const userId = await ctx.step("create-user", () => db.users.insert(ctx.payload));
```

Each `id` must be stable and unique within the workflow. The recorded output must be JSON-serialisable, because it is
persisted in the run's history and read back on replay.

## `ctx.sleep(id, duration)` [#ctxsleepid-duration]

`duration` is one of:

* a number of milliseconds — `ctx.sleep("a", 5000)`
* a structured amount — `ctx.sleep("a", { amount: 2, unit: "hours" })`
  (`unit`: `ms` / `milliseconds`, `seconds`, `minutes`, `hours`, `days`, `weeks`)
* a cron expression — `ctx.sleep("a", { cron: "0 9 * * *", tz: "Europe/Berlin" })`

A cron sleep resolves to the **next occurrence from the moment the run suspends** (not from when it was triggered).

## `ctx.waitForEvent(id, name, opts?)` [#ctxwaitforeventid-name-opts]

```typescript
const payload = await ctx.waitForEvent<MyEvent>("await-approval", "approval", {
    timeout: { amount: 1, unit: "days" },
});
```

The run suspends until `runtime.signal(runId, "approval", payload)` is called. The call returns the signalled payload, or
`undefined` if the optional `timeout` elapses first. A wait **without** a timeout is only ever advanced by `signal` — it
is never swept.

## Failures [#failures]

If the `run` function (or a step's `fn`) throws, the run transitions to `failed` and the serialised error is available
on the result and via `getRun`. Failures are terminal; there is no automatic retry — wrap a step in your own
retry/back-off if you need one, keeping it inside a single `ctx.step` so the whole retry is recorded as one unit.


# Stores (/docs/packages/workflow/stores)



# Stores [#stores]

Durability is delegated to a small `WorkflowStore` contract; the engine stays storage-agnostic. Five stores ship in the
box (memory, unstorage, SQL, Redis, Durable Object), and you can implement the contract over anything else.

## Built-in stores [#built-in-stores]

### MemoryStore (default) [#memorystore-default]

In-process, ideal for tests and single-instance apps. Used automatically when you don't pass a `store`.

```typescript
import { createRuntime, MemoryStore } from "@visulima/workflow";

const runtime = createRuntime({ store: new MemoryStore() });
```

### UnstorageStore [#unstoragestore]

Durable, edge-friendly persistence over any [unstorage](https://unstorage.unjs.io) driver (Cloudflare KV, D1, Redis,
filesystem, memory…).

```typescript
import { createRuntime, UnstorageStore } from "@visulima/workflow";
import { createStorage } from "unstorage";
import cloudflareKVBindingDriver from "unstorage/drivers/cloudflare-kv-binding";

const runtime = createRuntime({
    store: new UnstorageStore(createStorage({ driver: cloudflareKVBindingDriver({ binding: env.RUNS }) })),
});
```

A small due-index document tracks wake-at times so `sweep` does not scan every run. Operations are not transactional; its
optional lease is **best-effort** on non-atomic drivers (see [Concurrency](/docs/packages/workflow/concurrency)).

### SqlStore (PostgreSQL / MySQL) [#sqlstore-postgresql--mysql]

Durable persistence in a SQL database, with a **genuinely-atomic** cross-process lease (a single conditional `UPDATE`),
so it is safe for many runtime instances against one database. Driver-agnostic: adapt any client (node-postgres,
postgres.js, mysql2, pglite…) to the structural `SqlClient` — a single `query(sql, params) => { rows, rowCount }`.

```typescript
import { createRuntime, SqlStore } from "@visulima/workflow";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const store = new SqlStore(
    { query: (sql, parameters) => pool.query(sql, parameters as unknown[]) }, // pg returns { rows, rowCount }
    { dialect: "postgres" },
);

await store.init(); // create the table (also runs lazily on first use)
const runtime = createRuntime({ store });
```

For MySQL pass `{ dialect: "mysql" }` and connect with the `FOUND_ROWS` client flag (so the lease's affected-rows check
counts matched, not changed, rows). Run state is stored as JSON text, so no JSON column type is required.

### RedisStore [#redisstore]

Durable persistence in Redis, with an **atomic** Lua `acquire`/`release` lease and a sorted-set wake index — safe across
instances. [ioredis](https://github.com/redis/ioredis) satisfies the structural `RedisLike` directly.

```typescript
import { createRuntime, RedisStore } from "@visulima/workflow";
import Redis from "ioredis";

const store = new RedisStore(new Redis(process.env.REDIS_URL));
const runtime = createRuntime({ store });
```

### DurableObjectStore (Cloudflare) [#durableobjectstore-cloudflare]

Persistence in a [Cloudflare Durable Object](https://developers.cloudflare.com/durable-objects/)'s storage. Because a
Durable Object processes requests **serially**, the lease is race-free by construction — the cleanest correct
cross-process store. It also uses DO **alarms**: the store arms an alarm at the earliest wake-at, so the object wakes
itself to `sweep` — **no external cron needed** (the push model the `due` contract was designed for). The adapter takes a
structural storage object, so it needs no `@cloudflare/workers-types` dependency.

```typescript
import { createRuntime } from "@visulima/workflow";
import { DurableObjectStore } from "@visulima/workflow/store/durable-object";

export class WorkflowDurableObject {
    #runtime;

    constructor(state: DurableObjectState) {
        this.#runtime = createRuntime({ store: new DurableObjectStore(state.storage), workflows });
    }

    async fetch(request: Request) {
        // route trigger() / signal() calls into this.#runtime
    }

    async alarm() {
        await this.#runtime.sweep(); // the store re-arms the next alarm after each save
    }
}
```

One Durable Object instance is one runtime, so there is no cross-instance contention to coordinate — the DO *is* the
single owner. Completed runs are retained in storage (for `getRun`); `delete(runId)` to evict them.

## The contract [#the-contract]

```typescript
interface WorkflowStore {
    save(run: StoredRun): Promise<void>;
    load(runId: string): Promise<StoredRun | undefined>;
    delete(runId: string): Promise<void>;
    due(now: number, limit: number): Promise<string[]>; // runs whose wakeAt has passed

    // Optional cross-process lease (omit to rely on in-process locking only):
    acquire?(runId: string, token: string, ttlMs: number): Promise<boolean>;
    release?(runId: string, token: string): Promise<void>;
}
```

* `due(now, limit)` is the poll the `sweep` entrypoint uses. The contract is deliberately poll-based so it works on plain
  KV/SQL, but it is shaped so a **push-based** adapter (e.g. Durable Object alarms) can implement `due` as a no-op and
  schedule wake-ups inside `save`.
* `acquire` / `release` are the optional cross-process lease. Implement them with an atomic primitive (Redis `SET NX`, a
  SQL row lock, a Durable Object) for race-free exclusion across instances. See
  [Concurrency & exactly-once](/docs/packages/workflow/concurrency).

## Writing your own [#writing-your-own]

A minimal store needs only the four required methods. `StoredRun` carries the JSON-serialisable snapshot plus
denormalised `status`, `wakeAt` and `eventName` so you can implement `due` and signal-routing without parsing the
snapshot. Keep `save` ordering-safe: if your backend isn't transactional, persist the wake index **before** the run so a
crash yields at worst a harmless spurious wake (which `resume` re-validates and ignores) rather than a lost wake-up.