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:

• joyco CLI installed (joyco --version )

• vercel CLI installed (vercel --version )

• GitHub auth configured (used by joyco lab to 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/ or app/ )

• Wire the experiment into the template's entry point (usually src/main.ts , src/index.tsx , or app/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 three

Then run the dev server to confirm no import errors:

<pm> run dev

Fix 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 --prod

Follow 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 lab

The 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.