From cff22e68946280d884934acc0fa99f9f89e809c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=82n=20=C4=90o=C3=A0n?=
<33853760+andoan16@users.noreply.github.com>
Date: Sun, 19 Apr 2026 11:39:54 +0700
Subject: [PATCH 1/5] =?UTF-8?q?fix:=20resolve=20#749=20=E2=80=94=20Write?=
=?UTF-8?q?=20a=20step-by-step=20guide=20for=20using=20a=20board=20in=20an?=
=?UTF-8?q?=20app?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Fixes #749
Signed-off-by: Ân Đoàn <33853760+andoan16@users.noreply.github.com>
---
docs/using-boards-in-apps.md | 503 +++++++++++++++++++++++++++++++++++
1 file changed, 503 insertions(+)
create mode 100644 docs/using-boards-in-apps.md
diff --git a/docs/using-boards-in-apps.md b/docs/using-boards-in-apps.md
new file mode 100644
index 00000000000..68ce540b8d0
--- /dev/null
+++ b/docs/using-boards-in-apps.md
@@ -0,0 +1,503 @@
+---
+title: Using Breadboard in Web Applications
+description: A comprehensive guide to integrating Breadboard into vanilla JavaScript, Lit, and React applications.
+---
+
+# Using Breadboard in Web Applications
+
+This guide walks you through integrating an existing Breadboard into a web application. By the end, you'll have a working implementation that loads a board, handles inputs/outputs, and manages the board lifecycle.
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Node.js 18+ installed (for npm-based approaches)
+- An existing Breadboard JSON file from the [Happy Path](../happy-path/) tutorial
+- Basic knowledge of HTML, CSS, and JavaScript
+- Familiarity with your chosen framework (Lit or React) if applicable
+
+## Quick Start (5-Minute Vanilla JS)
+
+Create an `index.html` file:
+
+```html
+
+
+
+
+
+ Breadboard Integration
+
+
+
+ My Breadboard App
+
+
+
+
+
+
+```
+
+Replace the `boardJson` content with your actual board configuration.
+
+## Installation Options
+
+### Option 1: CDN (Quickest)
+```html
+
+```
+
+### Option 2: NPM
+```bash
+npm install @google-labs/breadboard
+```
+
+```javascript
+import { Board } from "@google-labs/breadboard";
+```
+
+## Loading Boards
+
+### From JSON Object
+```javascript
+const board = await Board.fromJSON(boardJson);
+```
+
+### From URL
+```javascript
+const board = await Board.load("https://example.com/my-board.json");
+```
+
+### From File (Node.js/Bundler)
+```javascript
+import boardJson from "./my-board.json" assert { type: "json" };
+const board = await Board.fromJSON(boardJson);
+```
+
+## Detailed Walkthrough
+
+### Basic Implementation
+
+```javascript
+import { Board } from "@google-labs/breadboard";
+
+async function runBoard() {
+ // Load the board
+ const board = await Board.fromJSON(boardJson);
+
+ // Run with inputs
+ const inputs = { message: "Hello, Breadboard!" };
+ const outputs = await board.runOnce(inputs);
+
+ console.log("Result:", outputs);
+}
+```
+
+### Handling Inputs and Outputs
+
+Boards may require multiple interactions. Use `run()` for full control:
+
+```javascript
+const board = await Board.fromJSON(boardJson);
+
+for await (const result of board.run({ inputs: { prompt: "Hello" } })) {
+ if (result.type === "input") {
+ // Board is requesting input
+ console.log("Input required:", result.data);
+ } else if (result.type === "output") {
+ // Board produced output
+ console.log("Output:", result.data);
+ }
+}
+```
+
+### Lifecycle Events
+
+```javascript
+const board = await Board.fromJSON(boardJson);
+
+// Listen to all events
+board.addEventListener("node", (event) => {
+ console.log("Node executed:", event.detail.node.id);
+});
+
+board.addEventListener("error", (event) => {
+ console.error("Board error:", event.detail.error);
+});
+```
+
+## Framework Integration
+
+### Lit Integration
+
+Install dependencies:
+```bash
+npm install @google-labs/breadboard lit
+```
+
+Create a component:
+
+```javascript
+import { LitElement, html, css } from "lit";
+import { Board } from "@google-labs/breadboard";
+
+export class BreadboardRunner extends LitElement {
+ static styles = css`
+ :host { display: block; padding: 1rem; }
+ .output { background: #f5f5f5; padding: 1rem; border-radius: 4px; }
+ .error { color: #d32f2f; }
+ `;
+
+ static properties = {
+ boardUrl: { type: String },
+ result: { state: true },
+ error: { state: true }
+ };
+
+ async runBoard() {
+ try {
+ const board = await Board.load(this.boardUrl);
+ this.result = await board.runOnce({});
+ this.error = null;
+ } catch (err) {
+ this.error = err.message;
+ this.result = null;
+ }
+ }
+
+ render() {
+ return html`
+
+ ${this.error ? html`${this.error}
` : ""}
+ ${this.result ? html`${JSON.stringify(this.result, null, 2)}` : ""}
+ `;
+ }
+}
+
+customElements.define("breadboard-runner", BreadboardRunner);
+```
+
+Usage:
+```html
+
+```
+
+### React Integration
+
+Install dependencies:
+```bash
+npm install @google-labs/breadboard react react-dom
+```
+
+Create a component:
+
+```jsx
+import { useState } from "react";
+import { Board } from "@google-labs/breadboard";
+
+function BreadboardComponent({ boardJson }) {
+ const [result, setResult] = useState(null);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState(null);
+
+ const runBoard = async () => {
+ setLoading(true);
+ setError(null);
+
+ try {
+ const board = await Board.fromJSON(boardJson);
+ const output = await board.runOnce({});
+ setResult(output);
+ } catch (err) {
+ setError(err.message);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ return (
+
+
+
+ {error &&
Error: {error}
}
+
+ {result && (
+
+ {JSON.stringify(result, null, 2)}
+
+ )}
+
+