);
}
```
## Building and Bundling Widgets
### Vite Configuration
```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { resolve } from "path";
import { readdirSync } from "fs";
// Auto-discover all widget entry points
const widgets = readdirSync("src").filter(dir =>
!dir.startsWith("use-") && !dir.includes(".")
);
const input = Object.fromEntries(
widgets.map(widget => [widget, resolve(__dirname, `src/${widget}/index.tsx`)])
);
export default defineConfig({
plugins: [react()],
build: {
outDir: "assets",
rollupOptions: {
input,
output: {
entryFileNames: "[name]-[hash].js",
chunkFileNames: "[name]-[hash].js",
assetFileNames: "[name]-[hash].[ext]"
}
}
}
});
```
### Build Script
```typescript
// build-all.mts
import { build } from "vite";
import { writeFileSync } from "fs";
async function buildAll() {
// Build all widgets
await build();
// Generate HTML wrappers with hashed asset references
const widgets = ["pizza-map", "pizza-carousel", "pizza-video"];
for (const widget of widgets) {
const hash = "abc123"; // Extract from build output
const html = `
`.trim();
writeFileSync(`assets/${widget}-${hash}.html`, html);
}
}
buildAll();
```
## Best Practices
### 1. Tool Design
**DO:**
- Use clear, descriptive tool names (e.g., `find_pizza_places` not `search`)
- Write detailed docstrings - they become tool descriptions
- Keep tool focused on one clear action
- Mark read-only tools with `openai/readOnlyHint`
- Return both human-readable text AND structured data
**DON'T:**
- Use generic names like `process` or `handle`
- Create tools that do multiple unrelated things
- Rely on `_meta` fields for authorization
- Expose sensitive data in `structuredContent`
### 2. Widget Development
**DO:**
- Use `text/html+skybridge` MIME type for all widget resources
- Handle theme changes (light/dark mode)
- Support all display modes (inline, fullscreen, PiP)
- Keep widget state small (<4k tokens)
- Use semantic HTML and WCAG AA contrast ratios
- Test on mobile, tablet, and desktop
**DON'T:**
- Use HTML `