Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• bubus-ts/package.json
• pyproject.toml
• bubus-ts/src/optional_deps.ts
• bubus-ts/tests/ts_to_python_roundtrip.test.ts
• TODO_ts.md
• TODO_python.md
• ui/main.py

This page provides detailed instructions for setting up the bubus event bus library in both TypeScript and Python environments. The project is designed as a cross-runtime event bus supporting Node.js, Bun, Deno, and Python 3.11+.

bubus utilizes a unified runtime approach, ensuring that event schemas and delivery semantics remain consistent across different language implementations. It includes optional support for various database bridges and a FastAPI-based monitoring UI.

Sources: bubus-ts/package.json:2-10, pyproject.toml:7-10, TODO_ts.md:1-10

Python Environment Setup

The Python implementation requires Python 3.11 or higher and uses pydantic for event validation and anyio for asynchronous support.

Core Dependencies

The project uses uv as the build backend and defines dependencies in pyproject.toml.

Dependency	Version	Purpose
pydantic	>=2.11.5	Event schema validation
anyio	>=4.9.0	Asynchronous runtime
uuid7	>=0.1.0	Monotonic event IDs
portalocker	>=2.7.0	Locking mechanisms
aiofiles	>=24.1.0	Async file I/O

Sources: pyproject.toml:7-21

Optional Bridges and UI

Additional features like database bridges and the web-based event monitor require optional dependencies.

# Install with postgres support
pip install bubus[postgres]

# Install with all bridge supports (Postgres, NATS, Redis)
pip install bubus[bridges]

# Install UI requirements
pip install fastapi

Sources: pyproject.toml:22-35, ui/main.py:8-12

TypeScript/Node.js Environment Setup

The TypeScript implementation is packaged for ESM Node.js and browsers, managed primarily via pnpm.

Core Installation

The library depends on zod for schema definition and uuid for unique identifiers.

pnpm install bubus

Build Scripts

The package.json defines several scripts for building and type-checking the project:

Script	Command	Description
build	pnpm run build:esm && pnpm run build:types	Full production build
build:esm	esbuild src/index.ts --bundle --format=esm ...	Compiles to ESM
build:types	tsc -p tsconfig.json --emitDeclarationOnly	Generates .d.ts files
typecheck	tsc -p tsconfig.json --noEmit	Validates types

Sources: bubus-ts/package.json:21-25, bubus-ts/package.json:57-61

Runtime Portability

The library detects the environment (Node.js vs others) to manage optional dependencies dynamically.

Cross-Language Integration

For environments using both Python and TypeScript, a roundtrip testing suite ensures compatibility. The setup requires a valid Python environment accessible to the TypeScript test runner.

Environment Discovery

The test runner attempts to locate the Python binary through several candidate paths:

1. BUBUS_PYTHON_BIN environment variable.
2. .venv/bin/python or .venv/Scripts/python.exe.
3. System python3 or python.

Sources: bubus-ts/tests/ts_to_python_roundtrip.test.ts:133-149

Schema Consistency Flow

When events are passed between runtimes, the following flow ensures schema integrity:

Performance Testing Setup

The project includes performance harnesses for multiple runtimes (Node, Bun, Deno, and Python).

Node/Bun/Deno Harness

Run performance scenarios using the following command structure:

# General perf run
pnpm run perf

# Scenario-specific debug
node --import tsx tests/performance.runtime.ts --scenario 50k-events

Sources: bubus-ts/package.json:28-35

Python Harness

Python performance benchmarks can be executed as a module:

python -m tests.performance_runtime --scenario 50k-events

Sources: tests/performance_runtime.py:84-90

Monitoring UI Setup

The bubus monitor UI is a FastAPI application that reads from a SQLite history mirror.

1. Prerequisites: Ensure fastapi is installed.
2. Database Configuration: The UI resolves the database path using resolve_db_path() and checks for the existence of events_log and event_results_log tables.
3. Execution:

# Run the UI (requires FastAPI/Uvicorn)
uvicorn ui.main:app --reload

Sources: ui/main.py:15-30, ui/main.py:648-655

bubus is successfully installed when the core dependencies are satisfied for your chosen runtime and optional bridges are configured where cross-process or cross-server communication is required.