JOYCO Lab — Experiment Isolation & Publication
Automates the full workflow of extracting a self-contained experiment from any codebase, scaffolding it with the right JOYCO template, installing dependencies, deploying to Vercel, and publishing to the JOYCO Lab registry.
Prerequisites checklist
Before starting, confirm these are available in the user's environment:
joycoCLI installed (joyco --version)vercelCLI installed (vercel --version)- GitHub auth configured (used by
joyco labto open PRs) - User is logged into Vercel (
vercel whoami)
If any are missing, tell the user and stop — the workflow depends on all of them.
Step 1 — Understand the experiment
Read the code the user is pointing at. Identify:
- What it does — one-sentence description (you'll use this for the Lab entry)
- What type it is — use the table below to pick a template
- What dependencies it needs — scan imports, note any that aren't in the template baseline
Template selection guide
| Signals in the code | Template to use |
|---|---|
three, @react-three/fiber, @react-three/drei, WebGLRenderer, OrbitControls, canvas 3D | 3d |
gsap, ScrollTrigger, @studio-freight/lenis, framer-motion, CSS keyframes, SVG animation, canvas 2D drawing | motion |
If the experiment mixes both (e.g. GSAP animating a Three.js scene), prefer 3d and note the GSAP dependency.
If genuinely ambiguous, ask the user before proceeding.
Step 2 — Name the experiment
Derive a human-readable name from what the experiment does. Rules:
- Natural title casing, no slugifying needed (the CLI handles that)
- Short (2–4 words max)
- Descriptive, not generic (❌
Cool Animation✅Magnetic Cursor Trail)
Suggest a name and confirm with the user before running any commands.
Step 3 — Scaffold with JOYCO CLI
joyco create --template <template-value> <experiment-name>Example:
joyco create --template motion "Magnetic Cursor Trail"This creates a new directory <experiment-name>/ with the template scaffolded inside. cd into it before the next steps.
Step 4 — Port the experiment code
- Identify the minimal set of files needed — entry point, shaders, helpers, assets
- Copy them into the scaffolded project, respecting the template's file structure (typically
src/orapp/) - Wire the experiment into the template's entry point (usually
src/main.ts,src/index.tsx, orapp/page.tsx— check the template) - Do not bring over unrelated code, global state, routing, or backend dependencies
Step 5 — Install missing dependencies
Compare the experiment's imports against what the template already includes.
Detect the package manager
Check which lockfile the scaffolded template contains and use the matching package manager:
| Lockfile found | Package manager |
|---|---|
bun.lockb or bun.lock | bun |
pnpm-lock.yaml | pnpm |
yarn.lock | yarn |
package-lock.json | npm |
If multiple lockfiles exist, prefer the first match in the table above. If none exist, default to npm.
Install and verify
For each missing package, install with the detected package manager:
cd <experiment-name> && <pm> install <package>
# e.g. bun add three, pnpm add three, yarn add three, npm install threeThen run the dev server to confirm no import errors:
<pm> run devFix any issues before proceeding. Common ones:
- Missing type packages (
@types/three, etc.) - Peer dependency mismatches
- Template assumes a bundler feature the experiment uses differently
Step 6 — Deploy to Vercel
Ask the user if they want to deploy to Vercel now. If they decline, skip to Step 7 — they can deploy later and provide the URL manually when running joyco lab.
If they confirm, run from inside the experiment directory:
vercel --prodFollow prompts if it's a first-time deploy (link to org, set project name = experiment slug). Copy the production URL — you'll need it for the Lab entry.
Step 7 — Publish to JOYCO Lab
Run the publish command and follow the interactive prompts:
joyco labThe CLI will ask for:
| Field | What to provide |
|---|---|
| Name | Human-readable title (e.g. "Magnetic Cursor Trail") |
| Description | One or two sentences about what it is and what's interesting technically |
| Tags | Comma-separated (e.g. gsap, cursor, magnetic, interaction) — see tag guide below |
| Preview link | The Vercel production URL from Step 6 |
| Preview image | Optional — URL to an OG/screenshot image if one was generated |
The CLI will open a PR in joyco-studio/lab adding the entry to experiments.json. Review the PR URL it outputs and share it with the user.
Tag guide
Use these consistently:
- By type:
3d,animation,interaction,shader,canvas,scroll,physics,generative - By library:
three,gsap,r3f,framer-motion,lenis,matter-js - By visual style:
typography,cursor,particles,geometry,noise,fluid
Pick 3–6 tags. Don't over-tag.
Step 8 — Wrap up
Tell the user:
- The experiment directory location
- The live Vercel URL
- The GitHub PR URL for the Lab registry entry
- Any follow-up they might want: merging the PR, adding a preview image, promoting on socials
Edge cases
Experiment uses a private/internal package: Stop and tell the user. Either the dependency needs to be made public, inlined, or replaced before the experiment can be a standalone public repo.
Experiment requires a backend/API: Scope it down to the frontend-only visual part, or ask the user if they want to mock the data. Lab experiments should be fully static/client-side.
User wants to skip Vercel deploy: They can provide a different href to joyco lab — just note that the Hub will render it in an iframe so it must be a publicly accessible URL.
No clear template match: Ask the user. Don't guess if it's truly ambiguous — a wrong template wastes setup time.