Build a FreeBeez applet

Quickstart#

Scaffold a project, install, and start the live sandbox. You'll have a running applet in under a minute.

# 1. Scaffold a new applet
npm create freebeez-applet@latest my-applet

# 2. Install dependencies
cd my-applet
npm install

# 3. Start the live sandbox (http://localhost:4321)
npm run dev

The sandbox is the exact runtime your applet gets in production, with device and theme toggles. Edit any file and the preview reloads instantly.

Project structure#

The scaffold gives you a tiny, self-explanatory project:

my-applet/
├─ applet.json          # manifest: id, name, entry, …
├─ src/
│  ├─ Applet.tsx        # your applet (default-exported component)
│  └─ components/
│     └─ icon.tsx       # catalog icon (plain SVG)
├─ package.json         # scripts + dev dependencies
├─ tsconfig.json
└─ README.md

Build with AI#

Every scaffolded project is agent-ready. Open it in your AI coding tool and just describe what you want to build — the agent already knows the platform rules, the SDK, and the best practices on this page, so you don't have to explain them.

The full agent guide lives in .agents/freebeez-applet.md. Each supported tool ships with an entry point that points to it:

Using a different tool? Point it at .agents/freebeez-applet.md and it has everything it needs.

The manifest#

applet.json describes your applet to the platform. Only id, name, and entry are required.

{
  "id": "unit-converter",
  "name": "Unit Converter",
  "description": "Convert length, weight, and temperature",
  "color": "#4A18D8",
  "version": "1.0.0",
  "entry": "src/Applet.tsx"
}

Writing your applet#

Export a React component as the default export. That's the entire contract.

import { useState } from "react"

export default function Applet() {
  const [count, setCount] = useState(0)
  return (
    <div className="flex min-h-[100dvh] items-center justify-center bg-white dark:bg-[#0f1115]">
      <button
        onClick={() => setCount((c) => c + 1)}
        className="rounded-2xl bg-[#4A18D8] px-6 py-3 font-bold text-white active:scale-95"
      >
        Clicked {count} times
      </button>
    </div>
  )
}

Importing packages

Import anything from npm — it's loaded from esm.sh at runtime. No install, no bundler config.

import { format } from "date-fns"
import confetti from "canvas-confetti"

Styling & dark mode

Tailwind utility classes are available, including the dark: variant. The host toggles the theme for you — apply dark: styles and they just work.

Choosing a React version

By default your applet shares the platform's React. To pin a specific version, set react in the manifest (e.g. "react": "19.2.4").

Using the SDK#

@free-beez/applet-sdk (already a dependency in the scaffold) gives you a typed contract with the host: theme awareness and a way to close your applet.

import { useTheme, close } from "@free-beez/applet-sdk"

export default function Applet() {
  const theme = useTheme() // "light" | "dark", updates live

  return (
    <div className="p-6">
      <p>Current theme: {theme}</p>
      <button onClick={close}>Close</button>
    </div>
  )
}

Local development#

The CLI gives you three commands, available as npm scripts:

You can also call the CLI directly with npx freebeez dev, npx freebeez build, or npx freebeez pack.

Publishing#

Shipping an applet is a short, predictable loop:

• Run npm run pack to produce your .zip package.
• Open the Submit page in the developer portal and drop in the .zip.
• Pre-flight checks run automatically — valid archive, manifest, id availability, a clean build, and a fresh version.
• An interactive preview shows your applet exactly as users will see it. Try it before you submit.
• Pick a category and submit. It goes live instantly.

Publishing updates

To update a live applet, bump version in applet.json and submit again. The id stays the same; re-using an existing version is rejected.

Rules#

A few hard requirements keep the catalog safe and consistent. Submissions that break these are rejected at pre-flight.

• The entry must default-export a component. FreeBeez mounts your default export — nothing renders without it.
• ids are unique and permanent. An id taken by another developer is blocked, and you can't change yours later.
• Bump the version to update. Each published version of your applet must be new.
• The icon is plain SVG. src/components/icon.tsx is rendered to static markup on the server, so it may only import React — no hooks, no other packages.
• Applets are client-only. There is no server, no Node APIs, and no filesystem. Everything you ship runs in the user's browser.

Dos & Don'ts#

Best practices#

Responsive by default

Applets run on phones and desktops. Build mobile-first and use the sandbox's device toggle to check both before you ship.

Respect the theme

Pair every light style with a dark: counterpart, or read useTheme() when you need the value in logic. Avoid hard-coded backgrounds that only look right in one theme.

Stay lean

Dependencies download from esm.sh on first load, so fewer and smaller packages mean a snappier applet. Prefer the platform and small, focused libraries.

Be accessible

Use semantic elements, label your controls, and make sure everything works with the keyboard. It's good for everyone.

SDK reference#

Everything exported from @free-beez/applet-sdk.

Helpers

Types

Troubleshooting#

My applet renders blank

Confirm your entry file has a default export, and that every package you import actually exists on esm.sh at the version you requested. Remember the first load downloads dependencies and can take a few seconds.

Pre-flight says the build failed

Run npm run build locally to see the exact compiler error, fix it, then re-pack.

"Version already exists"

You're re-submitting a version that's already live. Bump version in applet.json.

A package won't load

Double-check the exact npm name and that the version is published. Visit https://esm.sh/<package> in your browser to confirm it resolves.