Skip to content

Theatre.js Grid Notes

Keyframe timeline engine and visual studio overlay for choreographing Three.js / React Three Fiber cameras, lights and DOM properties.

Grid NotesVersion 0.7.2MotionChecked 2026-11-04
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install @theatre/core && npm install -D @theatre/studio
Packages:@theatre/core@theatre/studio

Install @theatre/core (Apache-2.0) as a runtime dependency and @theatre/studio (AGPL-3.0) as a development-only dependency.

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

Production-safe sheet playback with dev-only Studio

Load exported state JSON into getProject() for production, and initialize @theatre/studio behind a process.env.NODE_ENV === 'development' dynamic import.

lib/theatre-project.ts
import { getProject, types } from "@theatre/core";
import projectState from "./theatre-state.json";

if (process.env.NODE_ENV === "development" && typeof window !== "undefined") {
  void import("@theatre/studio").then((studio) => studio.default.initialize());
}

export const project = getProject("HeroScene", { state: projectState });
export const sheet = project.sheet("Main");

export const cameraRig = sheet.object("Camera", {
  x: types.number(0, { range: [-10, 10] }),
  y: types.number(2, { range: [0, 10] }),
  opacity: types.number(1, { range: [0, 1] }),
});

Gotchas for agents

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. AGPL-3.0 licence on @theatre/studio

    @theatre/core is Apache-2.0, but `@theatre/studio` is AGPL-3.0. Never import @theatre/studio unconditionally in production code: guard it behind process.env.NODE_ENV === "development" so bundlers strip it from production builds.

  2. Development pause and React 19 peer warnings

    Public npm releases paused at 0.7.2 (2024) while the team works on 1.0 privately. Expect peer-dependency warnings on React 19; @theatre/core works without React, whereas @theatre/r3f may need version overrides.

  3. Wait for project.ready before playing sequences

    Calling sheet.sequence.play() before await project.ready resolves silently fails to use the exported JSON state.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-reduced-motion.

Reduced motion

When prefers-reduced-motion: reduce matches, skip sheet.sequence.play() and set sheet.sequence.position directly to the final keyframe timestamp (sheet.sequence.position = 2.5).

Keyboard and screen readers

In development, @theatre/studio mounts a fixed overlay that captures keyboard shortcuts (such as Space). Never ship Studio to end users, and provide a pause button if a sequence loops.