Integration Guide

How to integrate weblet into your app or platform.

Installation

Install weblet as a dependency:

bun add weblet
# or
npm install weblet

Quick Example

Here's a complete example of validating a weblet, serving it, and capturing screenshots:

import {
  validateWeblet,
  getWebletInfo,
  serveWeblet,
  captureScreenshots,
} from 'weblet';

// 1. Validate the weblet
const validation = await validateWeblet('./my-app');
if (!validation.valid) {
  console.error('Invalid weblet:', validation.errors);
  process.exit(1);
}

// 2. Get manifest info
const manifest = await getWebletInfo('./my-app');
console.log(`Loaded: ${manifest.name}`);

// 3. Start the server
const server = await serveWeblet('./my-app', { port: 3000 });
console.log(`Running at ${server.url}`);

// 4. Capture screenshots
const screenshots = await captureScreenshots('./my-app', {
  output: './previews',
  sizes: ['desktop', 'mobile'],
});
console.log('Saved:', screenshots.files);

// 5. Clean up
await server.stop();

API Reference

validateWeblet(path)

Parse and validate a weblet's APP.md manifest.

const result = await validateWeblet('./my-app');

// result.valid: boolean
// result.errors: string[]
// result.warnings: string[]
// result.manifest?: ParsedManifest (if valid)

getWebletInfo(path)

Get the parsed manifest for a weblet. Throws if invalid.

const manifest = await getWebletInfo('./my-app');

// manifest.name: string
// manifest.description?: string
// manifest.version?: string
// manifest.runtime: 'browser' | 'bun' | 'node' | 'deno'
// manifest.agent?: { ... }

serveWeblet(path, options?)

Start a weblet server. Returns a handle to control it.

const server = await serveWeblet('./my-app', {
  port: 3000,        // default: 3000
  hostname: 'localhost',
  open: false,       // open browser?
});

// server.url: string (e.g., 'http://localhost:3000')
// server.stop(): Promise<void>
// server.isRunning(): boolean

captureScreenshots(path, options?)

Capture screenshots of a weblet at various viewport sizes.

const result = await captureScreenshots('./my-app', {
  output: './screenshots',  // default: ~/.weblet/screenshots/<name>/
  sizes: ['desktop', 'mobile'],  // viewport presets or WxH
  animated: false,           // capture GIF?
  duration: 5,               // GIF duration in seconds
  fps: 10,                   // GIF frame rate
  wait: 1000,                // ms to wait after page load
  route: '/',               // route to capture
});

// result.files: string[] (paths to screenshots)
// result.outputDir: string
// result.appName: string

Screenshot Options

Viewport Presets

You can also use custom dimensions: '800x600'

Animated GIFs

To capture animated previews:

const result = await captureScreenshots('./my-app', {
  animated: true,
  duration: 5,     // 5 second GIF
  fps: 10,         // 10 frames per second
});

Use Cases

App Builder Platform

A platform that lets users describe apps, generates weblets, and shows previews:

// User describes what they want...
// AI generates the weblet...

// Validate it worked
const { valid, errors } = await validateWeblet(outputPath);
if (!valid) {
  return { success: false, errors };
}

// Get preview images
const { files } = await captureScreenshots(outputPath, {
  output: `./previews/${userId}`,
  sizes: ['desktop', 'mobile'],
});

return {
  success: true,
  previews: files,
};

Weblet Marketplace

A registry that indexes and showcases weblets:

// On weblet submission...
const manifest = await getWebletInfo(submittedPath);

// Index it
await db.weblets.create({
  name: manifest.name,
  description: manifest.description,
  version: manifest.version,
  runtime: manifest.runtime,
  triggers: manifest.agent?.triggers,
});

// Generate listing images
await captureScreenshots(submittedPath, {
  output: `./cdn/weblets/${manifest.name}`,
  sizes: ['desktop'],
  animated: true,
  duration: 3,
});

CI/CD Pipeline

Validate weblets in your build process:

// In your test/build script
import { validateWeblet } from 'weblet';

const result = await validateWeblet('./dist');

if (!result.valid) {
  console.error('Weblet validation failed:');
  result.errors.forEach(e => console.error(`  - ${e}`));
  process.exit(1);
}

if (result.warnings.length > 0) {
  console.warn('Warnings:');
  result.warnings.forEach(w => console.warn(`  - ${w}`));
}

console.log('Weblet is valid!');

TypeScript Types

All types are exported for TypeScript users:

import type {
  ServeOptions,
  ScreenshotOptions,
  ScreenshotResult,
  ValidationResult,
  WebletServerHandle,
  ParsedManifest,
} from 'weblet';