Skip to main content

​
Prerequisites

Before installing Kraken TUI, ensure you have the following tools installed:

​
Required

  • Bun >= 1.0.0 — JavaScript runtime with native FFI support
    • Install: curl -fsSL https://bun.sh/install | bash
    • Verify: bun --version
  • Rust >= 1.70.0 — For building the native core
    • Install: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    • Verify: rustc --version && cargo --version

​
Optional (for development)

  • Git — For cloning the repository
  • Make — For convenient build commands (optional)
Why Bun? Kraken TUI uses Bun’s bun:ffi for zero-overhead native bindings. While the architecture could support other runtimes, Bun provides the best DX and performance for FFI-heavy libraries.

​
Installation Methods

​
Method 1: NPM Package (Coming Soon)

NPM package distribution is not yet available. Use Method 2 (source build) for now.
bun add kraken-tui

​
Method 2: Build from Source

This is the current recommended method during pre-GA development.
1

Clone the repository

git clone https://github.com/example/kraken-tui.git
cd kraken-tui
2

Build the native core

The Rust shared library must be compiled before using the TypeScript API:
cargo build --manifest-path native/Cargo.toml --release
This creates native/target/release/libkraken_tui.so (Linux), libkraken_tui.dylib (macOS), or kraken_tui.dll (Windows).
Build time: First build takes 2-5 minutes depending on your system. Subsequent builds are incremental and much faster.
3

Install TypeScript dependencies

cd ts
bun install
Core dependencies:
  • @preact/signals-core — For JSX reconciler (optional, only if using JSX API)
4

Verify installation

Run the test suite to confirm everything works:
# From repository root
bun test ts/test-ffi.test.ts
bun test ts/test-jsx.test.ts
All tests should pass ✓
5

Run the demo

Try the interactive demo to see Kraken TUI in action:
bun run examples/demo.ts
Use Tab to cycle focus, Esc to quit, Arrow keys to navigate.

​
Project Setup

​
Using in Your Project

Once installed, import Kraken TUI in your TypeScript files: 
import { Kraken, Box, Text, Input, KeyCode } from "kraken-tui";

const app = Kraken.init();
const root = new Box({ width: "100%", height: "100%" });
const label = new Text({ content: "Hello, Kraken!", fg: "#00FF00" });
root.append(label);
app.setRoot(root);

​
TypeScript Configuration

For JSX support, add to your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "kraken-tui",
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ESNext"
  }
}

​
Package.json Scripts

Add convenient scripts to your package.json:
package.json
{
  "scripts": {
    "dev": "bun run --watch src/index.ts",
    "build": "bun build src/index.ts --outdir dist",
    "start": "bun run src/index.ts"
  }
}

​
Building the Native Core

​
Build Modes

# Optimized build with full optimizations (~2-5 min)
cargo build --manifest-path native/Cargo.toml --release

# Binary location:
# Linux:   native/target/release/libkraken_tui.so
# macOS:   native/target/release/libkraken_tui.dylib
# Windows: native/target/release/kraken_tui.dll
Important: The TypeScript layer loads the native library from ../native/target/release/ by default. If you use debug builds, you’ll need to adjust the path in ts/src/ffi.ts or create a symlink.

​
Native Dependencies

The Rust core uses these dependencies (installed automatically by Cargo):
Cargo.toml
[dependencies]
taffy = "0.9"              # Flexbox layout engine
crossterm = "0.29"         # Cross-platform terminal I/O
pulldown-cmark = "0.13"    # Markdown parsing
syntect = "5.3"            # Syntax highlighting
bitflags = "2"             # Cell attribute flags
unicode-width = "0.2"      # Display width calculation
unicode-segmentation = "1.12"  # Grapheme cluster support

​
Troubleshooting

​
Build Failures

Solution: Install a C compiler.
Solution: Ensure you’ve built the native core with cargo build --release before running TypeScript code.The TypeScript layer requires the compiled shared library at runtime.
Solution: Verify the library path in ts/src/ffi.ts matches your build output location.Default path: ../native/target/release/libkraken_tui.{so|dylib|dll}
Solution: Consider using cargo build (debug) for development iteration. Use --release only for testing performance or final builds.You can also use sccache to cache Rust build artifacts:
cargo install sccache
export RUSTC_WRAPPER=sccache

​
Runtime Issues

Solution: Your terminal may not support required features. Try:
  • Modern terminal: iTerm2, Alacritty, Windows Terminal, or GNOME Terminal
  • Check color support: echo $COLORTERM should show truecolor or 24bit
Kraken TUI degrades gracefully but works best in modern terminals.
Solution: Ensure you’re calling app.readInput() in your event loop before draining events.
while (running) {
  app.readInput(16);  // Required to capture input
  for (const event of app.drainEvents()) {
    // Handle events
  }
  app.render();
}

​
Next Steps

Now that you have Kraken TUI installed, let’s build your first application:

Quickstart Tutorial

Create a working terminal application in under 10 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us