blooby

What it is

A Blooby mascot is a sphere seen from the front, with features placed on its surface by angle, not by pixel. Drag an eye sideways and it arcs across the face and narrows near the rim, the way it would on a real ball. On top of that rig sit freeform layers (shapes, SVG, text, drawn curves, rubber-hose hands and legs), a clip timeline with keyframes, a dotLottie state machine, and a Copilot that edits through the same functions the UI uses.

The editor, renderer and exporters run entirely in the browser. apps/api adds accounts, cloud projects, a community preset catalogue, admin tooling and the MCP server. Without it, the editor still runs offline on the built-in presets.

What you can make

Characters	Several mascots per project, each a body, a face layer, eyes and rubber-hose hands and legs that keep their length. Pin a foot or a hand in the world and the limb bends around it. One-click poses, saved mascot templates, roles for any layer
Motion	Keyframes on every property with Bézier easing and a value graph, squash & stretch, anchor points, procedural shake / float / pendulum / walk cycle / follow-through / jelly
Layers & looks	Shapes, pasted SVG, Google Fonts text on an arc or along a path, pen curves with draw-on trim and taper. Glow, blur, shadow, RGB split, slices, scanlines, flicker, jitter, echo and goo, blend modes, masks, gradients
Space	Layer depth with parallax, card turns, a mascot spinning round its sphere, camera pan / zoom / shake, particle bursts that gather into a word
States	Each timeline is a state. Rules like "when mood == 2, play Dance" from any state, in a node graph, exported as a real dotLottie state machine
Presets	72 built-ins: moods and idles, text, app screens, the app mascot kit, and cinematic ones (Portal Entrance, Full Body Morph, Glitch Materialize, 3D Card Flip, a 20-second showreel). Every part of one is an ordinary layer, key or effect
Copilot	An agent that inspects, searches presets, edits in small batches, previews and verifies. Every run can be reverted or reapplied
Admin	Moderation, users, projects, official presets and a splashscreen builder on the editor's own renderer

Ship it

Format	Notes
Lottie JSON	Baked per frame from the same scene the canvas draws. Guides are left out. Blend modes, trim offset, flicker, jitter, echo, depth, camera, particles and per-letter motion bake exactly. Glow, blur, shadow, RGB split, slices, scanlines, goo, gradients and masks have no Lottie equivalent here: they are drawn in the editor, GIF, MP4 and PNG, and the export lists which layers lost them
.lottie	Every state in one composition, with markers and the state machine (s/<id>.json)
React Native pack	The .lottie, blooby.machine.json and a generated Mascot.tsx for @lottiefiles/dotlottie-react-native
GIF / MP4 / WebM / PNG	Rasterised in the browser. The video container depends on MediaRecorder support

Showcase

Twelve of the built-in presets, played straight off the renderer. Under each: the systems it is built from and every property it keys. Open one in the editor and each of these is an ordinary layer, effect, modifier or keyframe track you can select and change. Nothing in the engine is special-cased for them.

Use it from Claude, ChatGPT or Cursor

Blooby is an MCP server. Copy your link from the editor's AI → Connect AI apps tab, add it to your AI app as a connector, approve on the Blooby page it opens, and ask it to animate. Each edit it makes is saved as it lands and shows up in your open editor. See docs/mcp.

Quick start

Needs Node.js 22 and pnpm 10 (corepack enable picks up the pinned version).

git clone https://github.com/divyanshu-patil/blooby.git
cd blooby
pnpm install
pnpm dev:web      # the editor, offline on the built-in presets: http://localhost:5173

pnpm dev          # web (5173), admin (5174) and api (3000) through Turborepo
pnpm run ci       # lint + typecheck + test: run it before a pull request

The backend needs a Supabase project, a Postgres connection string and an S3 bucket.

Environment variables

Each app has its own .env.example. Copy it to .env in the same folder. Frontend values are shipped in the browser bundle, so put only publishable keys in them.

App	Variable	Required	Purpose
apps/web, apps/admin	VITE_SUPABASE_URL	no*	Supabase project URL
	VITE_SUPABASE_PUBLISHABLE_KEY	no*	Supabase publishable key
	VITE_API_URL	no*	Where apps/api runs, e.g. http://localhost:3000
apps/api	NODE_ENV, PORT	yes	Runtime mode and port (default 3000)
	APP_URL, ADMIN_URL	yes	Web and admin origins (CORS)
	SUPABASE_URL, SUPABASE_SECRET_KEY, SUPABASE_JWKS_URL	yes	Auth and data. The secret key is server-only
	DATABASE_URL	yes	Prisma connection. Use the Supabase transaction pooler (:6543, pgbouncer=true&connection_limit=10). Not connection_limit=1 — that serialises every query in the process onto one connection
	AWS_REGION, AWS_S3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	yes	Project JSON storage (private bucket)
	S3_CORS_ORIGINS	no	Extra origins for the bucket's CORS rules, beyond APP_URL / ADMIN_URL. The bucket needs them — see below
	ALLOWED_MEDIA_TYPES, MAX_PROJECT_BYTES	yes	Upload limits
	REDIS_URL	no	Shared rate limits, cache invalidation and MCP state across instances. Unset is fine on one instance — see docker compose up -d redis. Needed when a host runs several (Vercel)
	OLLAMA_URL	no	Upstream for cloud Copilot requests

This is the beginning of the README. Read the rest at the original. Read the full README ↗