Coming from boxen
A boxen alternative with a drop-in path: import boxen from flagstaff/boxen, graded 84 / 84 by boxen's own test suite — then a box component whose static projection gives a pipe, an agent and a screen reader the text and title, not the border.
flagstaff is a boxen alternative you adopt by changing one import. flagstaff/boxen
is boxen 8's API, and boxen's own test suite is the grade.
Migrate from boxen in one import
- import boxen from 'boxen';
+ import boxen from 'flagstaff/boxen';Everything else stays: boxen(text, options) with borderStyle (all eight of cli-boxes'
styles, a style object of your own, or none), borderColor, backgroundColor,
dimBorder, title, titleAlignment, textAlignment, padding, margin, width,
height, float and fullscreen, plus _borderStyles and the Options,
CustomBorderStyle and Spacing types. An invalid borderColor or backgroundColor throws,
as boxen's does.
Is flagstaff compatible with boxen?
Graded, not claimed. boxen's own suite, vendored at 8.0.1 and unmodified apart from the
import specifier, runs against flagstaff/boxen beside a control that runs it against real
boxen. Every one of its cases is a snapshot of the exact characters the box comes out as:
| passing | rate | |
|---|---|---|
flagstaff/boxen | 84 / 84 | 100.0% |
| boxen itself (control) | 84 / 84 | 100.0% |
From Compatibility, which npm run compat:page generates from the
oracle's last run; that page is the authority. The same page grades flagstaff's ora,
log-update and cli-table3 paths.
What you gain over boxen
For a box the drawing is the contract, so flagstaff/boxen matches it byte for byte and
the façade alone changes the dependency tree, not the output. boxen 8.0.1 resolves to
nineteen packages; its eight direct dependencies — string-width, wrap-ansi, cli-boxes,
ansi-align, widest-line, camelcase, chalk and type-fest — are folded in here, and
the subpath reaches only linegauge and roundel/chalk, both from the burgee family.
The gain beyond that is flagstaff/box, a separate API you adopt a file at a time:
box(text, { border, padding, title, width, href }) for the string, and boxComponent() to
put the box on the frame loop:
| mode | what hoist(boxComponent(), …) writes |
|---|---|
tty | the border, padding and title |
pipe, ci, accessible | title: text — no border characters |
json | one NDJSON event per transition, on stderr |
A border is noise to a screen reader and to a log an agent parses; the title and the text
are not. That static projection is required of every flagstaff component, and which mode
runs is decided once by roundel's output policy, never by the component. A box with an
href draws its text as a terminal hyperlink where the terminal is believed to support
OSC 8, and as text (url) everywhere else. Named borders come from the plugin registry, and
fromCliBoxes() brings the cli-boxes set with you.
When to switch from boxen
- Your boxes end up in CI logs, in an agent's context or in front of a screen reader.
- You want boxen's exact drawing without its nineteen-package tree — the import swap alone does that.
The loop, the built-ins and the other drop-in paths are on flagstaff.
Coming from log-update
A log-update alternative with a drop-in path: import logUpdate from flagstaff/log-update, graded 99 / 99 by log-update's own test suite — then a frame loop whose static projection gives pipes one line per state and --json one event per transition.
Coming from cli-table3
A cli-table3 alternative with a drop-in path: import Table from flagstaff/cli-table3, graded 29 / 29 by cli-table3's own test suite — then a table component whose static projection gives a pipe and an agent one line of header: value pairs per row.