elizaos--eliza/packages/examples/react

elizaOS React Example

A React chat client powered by elizaOS, running a full AgentRuntime in the browser with a retro CRT terminal interface. Inference is handled by a real LLM provider selected from whichever API key environment variable is set.

Overview

This example demonstrates:

• elizaOS Integration: Full AgentRuntime with plugin architecture
• Provider auto-selection: Picks an LLM provider from the API key env var that is set (OpenAI → OpenRouter → Anthropic → Eliza Cloud)
• PGLite Database: In-browser PostgreSQL-compatible storage (WASM)
• Retro CRT aesthetic: Phosphor green text, scanlines, and glow effects

Quick Start

# From the repository root, install all dependencies
bun install

# Navigate to this example
cd packages/examples/react

# Provide an inference provider key (any ONE of these), then start the dev server
OPENAI_API_KEY=sk-... bun dev
# or OPENROUTER_API_KEY=... / ANTHROPIC_API_KEY=... / ELIZA_API_KEY=...

The app will open at http://localhost:5173

The selected key is injected into the client bundle at build time so the in-browser runtime can call the provider. If no key is set, the runtime throws a clear error at boot.

Architecture

This example uses the full elizaOS agent framework:

┌─────────────────────────────────────────────────────────────┐
│                     React Application                        │
│                         (App.tsx)                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    eliza-runtime.ts                          │
│              (AgentRuntime singleton manager)                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     AgentRuntime                             │
│                    (@elizaos/core)                           │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌──────────────────────────┐    ┌──────────────────────────┐
│     plugin-sql           │    │   inference provider     │
│    (PGLite adapter)      │    │  (openai / openrouter /  │
│                          │    │   anthropic / elizacloud)│
│  In-browser PostgreSQL   │    │                          │
│  with persistent storage │    │  TEXT_LARGE / TEXT_SMALL │
└──────────────────────────┘    └──────────────────────────┘

Plugins Used

1. @elizaos/plugin-sql: Provides the PGLite database adapter for in-browser persistence.
2. One inference provider plugin, chosen at runtime from the available API key:
   • @elizaos/plugin-openai (OPENAI_API_KEY)
   • @elizaos/plugin-openrouter (OPENROUTER_API_KEY)
   • @elizaos/plugin-anthropic (ANTHROPIC_API_KEY)
   • @elizaos/plugin-elizacloud (ELIZA_API_KEY)

How It Works

Provider selection (eliza-runtime.ts)

At initialization the runtime checks the environment in priority order and lazily imports the matching provider plugin:

if (process.env.OPENAI_API_KEY) {
  const { openaiPlugin } = await import("@elizaos/plugin-openai");
  // ... register openaiPlugin, set the OPENAI_API_KEY character secret
}
// ... then OPENROUTER_API_KEY, ANTHROPIC_API_KEY, ELIZA_API_KEY

The selected provider's API key is set as the character secret the plugin reads at init (the Eliza Cloud plugin reads ELIZAOS_CLOUD_API_KEY, mapped from ELIZA_API_KEY). If none of the keys are set, the runtime throws:

No inference provider configured. Set one of OPENAI_API_KEY,
OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or ELIZA_API_KEY.

elizaOS Integration

When the runtime processes a user message via runtime.messageService.handleMessage(...), it routes the model calls (TEXT_LARGE / TEXT_SMALL) to the selected provider plugin. The chat persona (a Rogerian-style listener) is defined by the character system prompt.

Project Structure

examples/react/
├── src/
│   ├── main.tsx               # React entry point
│   ├── App.tsx                # Main chat component
│   ├── App.css                # Terminal styling
│   ├── index.css              # Global styles
│   ├── eliza-runtime.ts       # AgentRuntime singleton + provider selection
│   └── pglite-browser.ts      # Browser PGLite asset loader
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

Styling

The UI features:

• VT323 and Fira Code fonts
• Phosphor green (#39ff14) color scheme
• CRT monitor bezel with LED indicators
• Animated scanlines and screen glow
• Boot sequence animation
• Typing indicators

Building for Production

bun run test
bun run typecheck
bun run build

The local smoke test checks the Vite mount point, the lazy browser runtime import, the provider-selection wiring, and the PGlite storage setup. Production output will be in the dist/ directory. The provider key is read from the build environment, so set it before running bun run build.

Extending This Example

Swapping providers

Set a different API key env var and restart — the runtime selects the highest priority provider whose key is present. To change the priority or add a new provider, edit selectInferenceProvider in src/eliza-runtime.ts.

Adding Bootstrap Actions

The bootstrap plugin (actions, providers, services) is automatically included in the elizaOS core runtime. No need to manually import or configure it — it is built-in and auto-registered during initialization.

License

MIT