BoardAPI Documentation

Appearance

Quick Start: Build Your First Component in 10 Minutes ​

This tutorial will guide you through creating, developing, and publishing your first BoardAPI component using the CLI.

Prerequisites ​

Step 1: Create Project (1 min) ​

Create a new component project:

bash
npx create-boardapi-app my-counter
cd my-counter
npm install

Or initialize in an existing directory:

bash
mkdir my-counter && cd my-counter
npx @boardapi/cli init
npm install

Choose Your Framework

The CLI supports Vanilla TypeScript, Vue 3, and React templates:

bash
npx create-boardapi-app my-counter --template vue
npx create-boardapi-app my-counter --template react

Step 2: Explore the Project Structure ​

Your project contains:

my-counter/
├── manifest.json      # Component metadata
├── package.json       # Dependencies
├── tsconfig.json      # TypeScript config
└── src/
    ├── main.ts        # Entry point
    ├── index.html     # HTML wrapper
    └── styles.css     # Styles

manifest.json ​

Defines your component's properties:

json
{
  "name": "my-counter",
  "version": "1.0.0",
  "title": "Click Counter",
  "description": "A simple click counter",
  "entry": "component.js",
  "dimensions": {
    "width": 200,
    "height": 150,
    "resizable": true
  },
  "storage": {
    "schema": {
      "count": { "type": "number", "default": 0 }
    }
  }
}

Step 3: Start Development Server (1 min) ​

Run the dev server with live reload and simulator:

bash
npm run dev

This opens:

  • Component: http://localhost:3000 - Your component in isolation
  • Simulator: http://localhost:3001 - Full testing environment

Simulator Features ​

The simulator provides:

  • Storage Inspector - View and modify shared state
  • Event Log - See all SDK events in real-time
  • Participants Panel - Simulate multiple users
  • Hot Reload - Changes apply instantly

Step 4: Write Your Component ​

Edit src/main.ts:

typescript
import { BoardAPI } from '@boardapi/sdk';
import './styles.css';

const board = new BoardAPI();

// Get DOM elements
const counterEl = document.getElementById('counter')!;
const incrementBtn = document.getElementById('increment')!;

// Initialize from shared storage
let count = board.storage.get('count', 0);

function render() {
  counterEl.textContent = String(count);
}

// Handle clicks
incrementBtn.addEventListener('click', async () => {
  count++;
  render();
  await board.storage.set('count', count);
});

// Sync with other users
board.storage.subscribe('count', (newValue: number) => {
  count = newValue;
  render();
});

render();
board.ready();

Step 5: Build for Production (1 min) ​

Validate and build your component:

bash
# Validate manifest and structure
npx boardapi validate

# Build for production
npm run build

This creates:

  • dist/ - Production-ready files
  • my-counter-1.0.0.zip - Ready to publish

Step 6: Publish to BoardAPI (2 min) ​

Set your API key and publish:

bash
# Login (one time)
npx boardapi login

# Publish (dry-run first)
npx boardapi publish --dry-run

# Actually publish
npx boardapi publish --no-dry-run

Expected output:

Published my-counter@1.0.0
URL: https://app.boardapi.io/api/v1/components/files/my-counter@1.0.0/index.html

Step 7: Test on a Board (2 min) ​

Option A: Via Web UI ​

  1. Go to app.boardapi.io
  2. Click "New Board"
  3. Open board settings, go to "Components" tab
  4. Click "Add Component" and select "my-counter@1.0.0"
  5. Add the component to canvas and test!

Option B: Via API ​

bash
# Create board with your component
curl -X POST https://app.boardapi.io/api/v1/boards \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Counter Board",
    "config": {
      "components": [{
        "type": "my-counter",
        "version": "1.0.0"
      }]
    }
  }'

Multi-user Test ​

  1. Open the board in your browser
  2. Open the Guest link in incognito mode
  3. Click the counter in one window
  4. See it update in real-time in the other!

Next Steps ​

Alternative: Manual Publishing ​

If you prefer not to use the CLI, you can publish manually:

1. Create ZIP Package ​

bash
zip -r my-counter-1.0.0.zip manifest.json dist/

2. Upload via API ​

bash
curl -X POST https://app.boardapi.io/api/v1/components/publish \
  -F "bundle=@my-counter-1.0.0.zip" \
  -F "apiKey=YOUR_API_KEY"

See Publishing Components for details.

Troubleshooting ​

CLI not found ​

bash
# Install globally
npm install -g @boardapi/cli

# Or use npx
npx @boardapi/cli <command>

Build fails ​

bash
# Check manifest is valid
npx boardapi validate --strict

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

Publish fails ​

  • Verify API key is correct
  • Check ZIP file size (max 10MB)
  • Run npx boardapi validate first

Need Help? ​