diff --git a/docs/happy-path.md b/docs/happy-path.md new file mode 100644 index 00000000000..4e22bb37310 --- /dev/null +++ b/docs/happy-path.md @@ -0,0 +1,17 @@ +# Happy Path + +This guide walks you through creating your first Breadboard using the Visual Editor. + +## Creating a Board + +1. Open the Visual Editor +2. Create a new board +3. Add some nodes +4. Connect them +5. Save the board as a JSON file + +## Next Steps + +Now that you've created your first board, you're ready to integrate it into a production application. Boards built in the Visual Editor can be embedded directly into web applications using the Breadboard JavaScript SDK. + +The board JSON file you created in this guide can be imported directly into your application code. To learn how to load and run your board in a web app, see the [Using Boards in Apps](./using-boards-in-apps.md) guide. diff --git a/docs/nav-config.json b/docs/nav-config.json new file mode 100644 index 00000000000..8c2486fdc19 --- /dev/null +++ b/docs/nav-config.json @@ -0,0 +1,26 @@ +{ + "navigation": [ + { + "title": "Getting Started", + "items": [ + { "title": "Introduction", "path": "/" }, + { "title": "Installation", "path": "/installation" }, + { "title": "Quick Start", "path": "/quick-start" } + ] + }, + { + "title": "Guides", + "items": [ + { "title": "Happy Path", "path": "/guides/happy-path" }, + { "title": "Using Boards in Apps", "path": "/guides/using-boards-in-apps" } + ] + }, + { + "title": "Reference", + "items": [ + { "title": "API", "path": "/reference/api" }, + { "title": "CLI", "path": "/reference/cli" } + ] + } + ] +} \ No newline at end of file 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)}
+
+ )} +
+ ); +} + +export default BreadboardComponent; +``` + +## Advanced Usage + +### Handling Streams + +```javascript +const board = await Board.fromJSON(boardJson); + +for await (const chunk of board.run({ inputs: {}, stream: true })) { + if (chunk.type === "output") { + // Stream partial outputs + updateUI(chunk.data); + } +} +``` + +### Managing Secrets + +```javascript +const board = await Board.fromJSON(boardJson); + +const result = await board.runOnce({ + // Public inputs + query: "What is the weather?", + + // Secrets (in production, use environment variables) + API_KEY: process.env.API_KEY +}); +``` + +### Loading Kits + +```javascript +import { Core } from "@google-labs/core-kit"; + +const board = await Board.fromJSON(boardJson); +const core = new Core(); + +// Register kits before running +board.addKit(core); +``` + +## Error Handling and Debugging + +### Common Errors + +**Board fails to load:** +```javascript +try { + const board = await Board.load(url); +} catch (error) { + if (error.message.includes("404")) { + console.error("Board file not found. Check the URL."); + } +} +``` + +**Missing inputs:** +```javascript +try { + await board.runOnce({}); +} catch (error) { + if (error.message.includes("input")) { + console.error("Missing required input. Check board schema."); + } +} +``` + +### Debugging Tips + +1. **Enable verbose logging:** +```javascript +const board = await Board.fromJSON(boardJson, { verbose: true }); +``` + +2. **Inspect board structure:** +```javascript +console.log("Nodes:", board.nodes); +console.log("Edges:", board.edges); +``` + +3. **Validate JSON:** +Ensure your board JSON is valid before loading: +```javascript +JSON.parse(boardJsonString); // Throws if invalid +``` + +## Deployment Considerations + +### Security +- Never expose API keys in client-side code +- Use environment variables for secrets +- Consider proxying board requests through your backend + +### Performance +- Cache board JSON files +- Use CDN for production loads +- Implement loading states for better UX + +### Browser Support +Breadboard requires modern browsers with ES module support: +- Chrome/Edge 90+ +- Firefox 90+ +- Safari 14+ + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| `Board is not defined` | Ensure module script type: ` + + +``` + +This complete example works without any build step—just save and open in a browser. + +## Next Steps + +- Explore the [Breadboard API Reference](../api/) +- Learn about [Creating Custom Kits](../kits/) +- Join the [Discord community](https://discord.gg/breadboard) for support diff --git a/examples/web-integration/vanilla/README.md b/examples/web-integration/vanilla/README.md new file mode 100644 index 00000000000..b9a030146ab --- /dev/null +++ b/examples/web-integration/vanilla/README.md @@ -0,0 +1,51 @@ +# Breadboard Vanilla JS Example + +A minimal, complete example of running a Breadboard in the browser without any build tools or package management. + +## What's Included + +- `index.html` - A self-contained HTML file that loads Breadboard from a CDN and runs a simple greeting board + +## How to Run + +Simply open `index.html` in any modern web browser: + +```bash +# On macOS +open index.html + +# On Linux +xdg-open index.html + +# On Windows +start index.html +``` + +Or use a local development server (recommended for ES modules): + +```bash +npx serve . +# or +python -m http.server 8000 +``` + +Then navigate to `http://localhost:8000` (or the appropriate port). + +## What It Demonstrates + +1. **CDN Loading** - Loads `@breadboard-ai/core` directly from unpkg +2. **Board Definition** - Defines a board inline as JSON (BGL format) +3. **Node Types** - Uses `input`, `runJavascript`, and `output` nodes +4. **Execution** - Runs the board with user input and displays results +5. **Error Handling** - Catches and displays runtime errors + +## The Board + +The example board: +1. Takes a `name` input +2. Passes it to a JavaScript node that creates a greeting +3. Returns the greeting via the output node + +## Browser Compatibility + +Requires a modern browser with ES module support (Chrome 61+, Firefox 60+, Safari 10.1+, Edge 16+). \ No newline at end of file diff --git a/examples/web-integration/vanilla/index.html b/examples/web-integration/vanilla/index.html new file mode 100644 index 00000000000..34bbd31718f --- /dev/null +++ b/examples/web-integration/vanilla/index.html @@ -0,0 +1,156 @@ + + + + + + Breadboard Vanilla JS Example + + + +
+

🍞 Breadboard Vanilla JS Example

+

This example loads a Breadboard from JSON and runs it in the browser using the CDN-hosted runtime.

+ + + + + + +
Click "Run Board" to see the result...
+
+ + + + \ No newline at end of file