Integration Guide

Installation

Install weblet as a dependency:

bun add weblet
# or
npm install weblet

Quick Example

Validate, serve, and capture screenshots in a few lines:

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

// 1. Validate the weblet
const validation = await validateWeblet('./my-app');
if (!validation.valid) {
  console.error('Invalid:', 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 shots = await captureScreenshots('./my-app', {
  output: './previews',
  sizes: ['desktop', 'mobile'],
});

// 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

getWebletInfo(path)

Get the parsed manifest. 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.

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

// server.url: string
// server.stop(): Promise<void>
// server.isRunning(): boolean

captureScreenshots(path, options?)

Capture screenshots at various viewport sizes.

const result = await captureScreenshots('./my-app', {
  output: './screenshots',
  sizes: ['desktop', 'mobile'],
  animated: false,
  duration: 5,
  fps: 10,
  wait: 1000,
  route: '/',
});

// result.files: string[]
// result.outputDir: string
// result.appName: string

Screenshot Options

Viewport Presets

Custom dimensions: '800x600'

Animated GIFs

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

Use Cases

App Builder Platform

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

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

return { success: true, previews: files };

CI/CD Pipeline

import { validateWeblet } from 'weblet';

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

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

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

TypeScript Types

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