Publishing Components

Learn how to build, publish, version, and manage your BoardAPI components.

Publishing Workflow

mermaid

graph LR
    A[Develop] --> B[Validate]
    B --> C[Build]
    C --> D[Publish]
    D --> E[Test on Board]
    E --> F{Works?}
    F -->|Yes| G[Done]
    F -->|No| A

Method 1: CLI (Recommended)

The CLI handles building, validation, and publishing automatically.

Build and Validate

bash

# Validate manifest and structure
npx boardapi validate

# Build for production
npm run build

Publish

bash

# Login (first time only)
npx boardapi login

# Dry-run to check everything
npx boardapi publish --dry-run

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

Version Bumping

bash

npx boardapi version patch   # 1.0.0 → 1.0.1 (bug fixes)
npx boardapi version minor   # 1.0.0 → 1.1.0 (new features)
npx boardapi version major   # 1.0.0 → 2.0.0 (breaking changes)

See CLI Reference for all commands.

Method 2: Manual (API)

If you prefer not to use the CLI, you can publish manually via API.

Step 1: Prepare Files

Checklist:

[ ] manifest.json in ZIP root
[ ] Entry point file exists (referenced in manifest)
[ ] All assets bundled
[ ] No absolute paths (use relative paths)
[ ] Version number updated

Step 2: Create ZIP Package

bash

# From component directory
zip -r component-name-1.0.0.zip manifest.json dist/

# Verify contents
unzip -l component-name-1.0.0.zip

Naming Convention

Use format: {name}-{version}.zip

Include:

manifest.json (required)
Entry point file
All referenced assets (images, CSS, JS)

Exclude:

node_modules/
.git/
Source files (TypeScript, etc.)

Limits:

Maximum ZIP size: 10 MB
Individual file limit: 5 MB
Total assets: Up to 50 files

Step 3: Upload via API

IMPORTANT

API key must be sent as form field, NOT as header!

bash

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

Response:

json

{
  "status": "published",
  "component": {
    "name": "hello-card",
    "version": "1.0.0",
    "url": "https://app.boardapi.io/api/v1/components/files/hello-card@1.0.0/index.html",
    "assetsBaseUrl": "https://app.boardapi.io/api/v1/components/files/hello-card@1.0.0"
  },
  "publishedAt": "2025-11-23T10:30:00Z"
}

Versioning

BoardAPI uses Semantic Versioning.

Version Format

MAJOR.MINOR.PATCH

Example: 2.1.3
  |   |  |
  |   |  +- Patch: Bug fixes
  |   +---- Minor: New features (backward compatible)
  +-------- Major: Breaking changes

When to Bump Version

Change Type	Version Bump	Example
Bug fix	Patch (0.0.X)	1.0.0 - 1.0.1
New feature	Minor (0.X.0)	1.0.1 - 1.1.0
Breaking change	Major (X.0.0)	1.1.0 - 2.0.0

Multiple Versions

You can have multiple versions of the same component:

hello-card@1.0.0  - Old version (still accessible)
hello-card@1.1.0  - Current version
hello-card@2.0.0  - New major version

Users can pin to specific versions in board config:

json

{
  "components": [
    {
      "type": "hello-card",
      "version": "1.0.0"
    }
  ]
}

Updating Components

Via CLI

bash

# Bump version
npx boardapi version patch

# Build and publish
npm run build
npx boardapi publish --no-dry-run

Via API

bash

# Update version in manifest.json first
# Then create new ZIP and upload

curl -X POST https://app.boardapi.io/api/v1/components/publish \
  -F "bundle=@hello-card-1.0.1.zip" \
  -F "apiKey=YOUR_API_KEY"

Migration Guide

For breaking changes, document migration steps in README.md:

markdown

## Migration from v1 to v2

### Breaking Changes
- Renamed prop `text` to `message`
- Removed `color` prop (use CSS variables instead)

### Migration Steps
1. Update manifest version to `2.0.0`
2. Rename `text` to `message` in your board config

Testing

Local Testing with Simulator

Use the CLI dev server:

bash

npm run dev

The simulator at http://localhost:3001 provides:

Storage Inspector
Event Log
Multi-participant simulation

Production Testing

After publishing:

Create test board
Add your component
Verify rendering
Test all interactions
Check responsive behavior
Test multi-user sync

Component Registry

List Your Components

bash

curl https://app.boardapi.io/api/v1/components \
  -H "X-API-Key: YOUR_API_KEY"

Response:

json

{
  "components": [
    {
      "name": "hello-card",
      "versions": ["1.0.0", "1.0.1", "2.0.0"],
      "latest": "2.0.0",
      "author": "Your Name"
    }
  ]
}

Access Component

bash

# Latest version
https://app.boardapi.io/api/v1/components/files/hello-card@latest/index.html

# Specific version
https://app.boardapi.io/api/v1/components/files/hello-card@1.0.0/index.html

Security

Content Scanning

All uploaded components are scanned for:

Malicious code
XSS vulnerabilities
Suspicious external links
Large file sizes

Sandboxing

Components run in iframes with restricted permissions:

html

<iframe
  src="component-url"
  sandbox="allow-scripts allow-same-origin"
  referrerpolicy="no-referrer"
></iframe>

Best Practices

Don't include secrets in component code
Validate all inputs from props
Use HTTPS for external resources
Escape user content to prevent XSS
Minimize dependencies to reduce attack surface

Unpublishing

Deprecate Version (Recommended)

Mark as deprecated without breaking existing boards:

bash

curl -X PATCH https://app.boardapi.io/api/v1/components/hello-card/1.0.0 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deprecated": true, "message": "Use v2.0.0 instead" }'

Delete Version

WARNING

Boards using this version will show an error!

bash

curl -X DELETE https://app.boardapi.io/api/v1/components/hello-card/1.0.0 \
  -H "X-API-Key: YOUR_API_KEY"

CI/CD Integration

GitHub Actions

yaml

# .github/workflows/publish.yml
name: Publish Component

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Publish
        run: npx boardapi publish --no-dry-run
        env:
          BOARDAPI_TOKEN: ${{ secrets.BOARDAPI_TOKEN }}

Next Steps

CLI Reference - All CLI commands
Examples - Real component implementations
SDK API Reference - Full SDK documentation

Publishing Components ​

Publishing Workflow ​

Method 1: CLI (Recommended) ​

Build and Validate ​

Publish ​

Version Bumping ​

Method 2: Manual (API) ​

Step 1: Prepare Files ​

Step 2: Create ZIP Package ​

Step 3: Upload via API ​

Versioning ​

Version Format ​

When to Bump Version ​

Multiple Versions ​

Updating Components ​

Via CLI ​

Via API ​

Migration Guide ​

Testing ​

Local Testing with Simulator ​

Production Testing ​

Component Registry ​

List Your Components ​

Access Component ​

Security ​

Content Scanning ​

Sandboxing ​

Best Practices ​

Unpublishing ​

Deprecate Version (Recommended) ​

Delete Version ​

CI/CD Integration ​

GitHub Actions ​

Next Steps ​

Publishing Components

Publishing Workflow

Method 1: CLI (Recommended)

Build and Validate

Publish

Version Bumping

Method 2: Manual (API)

Step 1: Prepare Files

Step 2: Create ZIP Package

Step 3: Upload via API

Versioning

Version Format

When to Bump Version

Multiple Versions

Updating Components

Via CLI

Via API

Migration Guide

Testing

Local Testing with Simulator

Production Testing

Component Registry

List Your Components

Access Component

Security

Content Scanning

Sandboxing

Best Practices

Unpublishing

Deprecate Version (Recommended)

Delete Version

CI/CD Integration

GitHub Actions

Next Steps