Bijou

Bijou is a TypeScript toolkit for building delightful terminal software.

The public stack has two main UI/runtime layers, plus Node and localization support packages:

• @flyingrobots/bijou for prompts, output helpers, themes, and mode-aware components
• @flyingrobots/bijou-tui for surface-based interactive apps, layout, motion, overlays, and framed shells

The philosophy is practical over ornamental: local TTY apps should feel great, while the same codebase gracefully degrades in CI, pipes, and accessibility-focused environments.

What's New in v4.1.0

Bijou v4.1.0 is the current release.

Compared to v4.0.0, it moves Bijou from the pure-surface release line toward a more coherent terminal application platform.

Key changes:

• the runtime-engine story now reaches through RE-006, giving @flyingrobots/bijou-tui explicit state/view stacks, retained layouts, layout-driven input routing, buffered commands/effects, and component-level interaction contracts
• the humane shell and DOGFOOD surface matured together, with layered shell routing, calmer settings/search/notification/quit behavior, and complete 35/35 DOGFOOD component-family coverage
• localization is now a real package line with @flyingrobots/bijou-i18n, @flyingrobots/bijou-i18n-tools, @flyingrobots/bijou-i18n-tools-node, and @flyingrobots/bijou-i18n-tools-xlsx
• the repo's release and engineering doctrine is much more explicit, with METHOD signposts, long-form release docs, and a tighter automated release path

In short: v4.1.0 is the release where Bijou stops feeling like a surface toolkit plus demos and starts feeling like a real terminal application platform.

Read the short-form changelog, the long-form What's New guide, and the migration guide.

Package Map

Package	Role
@flyingrobots/bijou	Core toolkit: prompts, components, themes, output modes, surfaces, ports
@flyingrobots/bijou-tui	Interactive runtime: TEA loop, layout, overlays, motion, diffed rendering
@flyingrobots/bijou-node	Node adapters: runtime, IO, style ports, recorder and worker helpers
@flyingrobots/bijou-tui-app	Opinionated app shell with tabs, drawers, help, and status areas
create-bijou-tui-app	Scaffolder for a runnable Bijou TUI app
@flyingrobots/bijou-i18n	In-memory localization runtime: catalogs, direction, and runtime-safe lookups
@flyingrobots/bijou-i18n-tools	Localization workflow tooling: authoring, stale detection, exchange, compilation
@flyingrobots/bijou-i18n-tools-node	Node filesystem helpers for localization exchange workflows
@flyingrobots/bijou-i18n-tools-xlsx	XLSX workbook adapters for localization exchange workflows

All published packages are versioned in lock-step.

What Bijou Is Good At

• building prompt-driven CLIs that still lower cleanly in pipes and CI
• building full-screen terminal apps with a real update/view/runtime model
• keeping tests close to user-visible behavior through surfaces, smoke suites, and scaffolding canaries
• giving you a documented design-system track instead of leaving component choice entirely to improvisation

DOGFOOD

DOGFOOD is the canonical Bijou docs surface and proving app.

It is not just an example. It is where the repo now proves:

• the framed shell and interactive runtime in a real full-screen product surface
• the component-family field guide and design-language track in one living docs app
• shell concerns like search, settings, help, quit, and layout behavior under real usage

If you are learning Bijou, start with DOGFOOD. The examples/ tree is now secondary reference material, not the public docs front door.

Run it locally:

npm run dogfood

Quick Start

Core CLI Flow

import { group, headerBox, input, select } from '@flyingrobots/bijou';
import { initDefaultContext } from '@flyingrobots/bijou-node';

initDefaultContext();

const answers = await group({
  project: () => input({ title: 'Project name', required: true }),
  template: () =>
    select({
      title: 'Template',
      options: [
        { label: 'TypeScript', value: 'ts' },
        { label: 'Go', value: 'go' },
      ],
    }),
});

console.log(
  headerBox('Scaffold', {
    detail: `${answers.project} (${answers.template})`,
  }),
);

Interactive Runtime

import { type App, quit, run, vstackSurface } from '@flyingrobots/bijou-tui';
import { badge, boxSurface } from '@flyingrobots/bijou';
import { initDefaultContext } from '@flyingrobots/bijou-node';

const ctx = initDefaultContext();

type Model = { count: number };

const app: App<Model> = {
  init: () => [{ count: 0 }, []],
  update: (msg, model) => {
    if (msg.type === 'key' && msg.key === 'q') return [model, [quit()]];
    if (msg.type === 'key' && msg.key === 'k') return [{ count: model.count + 1 }, []];
    if (msg.type === 'key' && msg.key === 'j') return [{ count: model.count - 1 }, []];
    return [model, []];
  },
  view: (model) =>
    boxSurface(
      vstackSurface(
        `Current count: ${model.count}`,
        badge(model.count > 10 ? 'HIGH' : 'LOW', { variant: 'info', ctx }),
      ),
      { title: 'Counter', padding: 1, ctx },
    ),
};

await run(app);

Scaffold A New App

npm create bijou-tui-app@latest my-app

Output Modes

Bijou is designed to adapt to the environment instead of assuming every run is a full local TTY.

Mode	Typical trigger	What happens
interactive	Local TTY	Full runtime, input loop, color, motion, shell chrome
static	CI with TTY stdout	Single-frame render, no interactive loop
pipe	Non-TTY stdout, NO_COLOR, or TERM=dumb	Plain-text-safe output
accessible	BIJOU_ACCESSIBLE=1	Linearized, screen-reader-friendly output

Example:

import { alert } from '@flyingrobots/bijou';
import { initDefaultContext } from '@flyingrobots/bijou-node';

const ctx = initDefaultContext();

console.log(
  alert('Connection refused on port 5432.', {
    variant: 'error',
    ctx,
  }),
);

That same call lowers differently depending on the interaction profile:

interactive / static
┌─────────────────────────────────────┐
│ ✗ Connection refused on port 5432. │
└─────────────────────────────────────┘

pipe
[ERROR] Connection refused on port 5432.

accessible
Error: Connection refused on port 5432.

Design System

Bijou ships a design-system documentation track in addition to API docs, and DOGFOOD is the primary living surface for that work.

Start here:

• Design System Overview
• Foundations
• Patterns
• Component Families
• Data Visualization Policy

Those docs are meant to answer:

• what a component is for
• when to use it
• when not to use it
• how it lowers across interaction profiles
• what the nearest related family is

Documentation Map

• Docs Index
• METHOD
• BEARING
• VISION
• DOGFOOD
• System-Style JavaScript
• Current Plan
• Architecture
• Migration Guide
• Release Docs
• Release Guide
• Changelog
• Roadmap

Roadmap

These are directions we are actively interested in, but they are not being presented as shipped 4.0.0 features:

• browser and Wasm adapters
• a Bijou-native docs TUI
• a story/studio workflow for isolated component and pattern work
• replay artifacts, richer scenario tooling, and time-travel debugging
• deeper BCSS/devtools work beyond the currently shipped scoped runtime styling

See docs/METHOD.md for the repo work doctrine, docs/BEARING.md for the current direction, docs/system-style-javascript.md for the engineering doctrine, docs/PLAN.md for the short queue summary, and docs/ROADMAP.md for the broader legacy/reference backlog.

License

Apache-2.0 (LICENSE)

---

Built with terminal ambition by FLYING ROBOTS