Skip to Content
ContributingDevelopment

Development

Prerequisites

  • Node.js 20 or newer
  • pnpm 9 (the repository pins pnpm@9.15.9)
  • git
git clone https://github.com/zschiller/screenplay.git cd screenplay pnpm install

The monorepo

    • app
    • desktop
    • docs
    • homepage
    • screenplay-knobs
    • screenplay-state
    • skill-templates
    • smart-quotes
    • ui
    • eslint-config
    • typescript-config
PathWhat it isDev port
apps/appThe product: canvas, agent runtime, API routes3000
apps/homepageThe marketing site3001
apps/docsThis site (Nextra)3002
apps/desktopThe Tauri shell that packages apps/app as the desktop app—
packages/screenplay-knobs, packages/screenplay-stateThe npm packages apps use to declare knobs and shared state—
packages/skill-templatesPage templates the built-in design skills use—
packages/smart-quotesThe curly-quote check (and --fix) for copy—
packages/uiShared shadcn/ui components—

apps/app/CONTEXT.md is the glossary for the product’s domain language. Design decisions are recorded as ADRs in apps/app/docs/adr/. Read both before a larger change.

Running the product

There are two ways to run apps/app locally.

The same build switches the desktop app uses let you run the full product with no external services: embedded Postgres, a local Yjs server, and each chat’s code as a git worktree. You need a coding CLI such as Claude Code installed for the agent.

cd apps/app NEXT_PUBLIC_SCREENPLAY_PROFILE=desktop NEXT_PUBLIC_YJS_HOST=local NEXT_PUBLIC_BASE_PATH= \ SANDBOX_BACKEND=local SCREENPLAY_DB=pglite BLOB_STORE=local-fs AGENT_ENGINE=external \ ENCRYPTION_KEY=$(openssl rand -hex 32) TERMINAL_AUTH_SECRET=$(openssl rand -hex 32) \ pnpm dev

Open http://localhost:3000. Data lives under apps/app (.pglite/, .data/yjs/, .screenplay/blobs/), and worktrees go under ~/.screenplay/.

pnpm dev at the repository root starts every app through Turborepo. Run it inside apps/app to start just the product.

Commands

From the repository root (runs across all packages via Turborepo):

pnpm dev # dev servers pnpm build # production builds (apps/app runs its migrations first) pnpm lint # ESLint pnpm typecheck # tsc --noEmit pnpm format # Prettier pnpm format:check # Prettier, checking only pnpm test # Vitest

CI runs pnpm lint, pnpm format:check, pnpm typecheck and pnpm test on every pull request. A lint error or an unformatted file fails it; lint warnings don’t. Besides React’s rules, lint checks the design rules a machine can judge (packages/eslint-config/design-rules.js): JSX text keeps its space after an {expression}, Buttons use only the sm, icon-sm, default and lg sizes, and status colours are never /NN tints.

In apps/app, pnpm test:watch runs Vitest in watch mode. Database helpers:

pnpm db:generate # generate a migration from schema changes (commit it) pnpm db:migrate # apply migrations to $DATABASE_URL pnpm db:push # sync the schema without a migration (throwaway dev only) pnpm db:studio # open Drizzle Studio

See Database for the migration workflow.

When local dev misbehaves

  • The dev indicator pulses nonstop, or Turbopack panics with “EcmascriptMergedChunkVersion … no longer exists” or “[Server HMR] Subscription error”. Turbopack rebuilds on every change to a file under apps/app that git doesn’t ignore, even one no module imports. Something is writing there: any folder the app writes state to during next dev belongs in .gitignore (.pglite/, .data/ and .screenplay/ already are).
  • next dev hangs at “Compiling /[roomId] …”, or a build complains that build-manifest.json is missing after you switch between the hosted and local screenshot harness. Turbopack’s on-disk cache in apps/app/.next is stale: rm -rf apps/app/.next and start again.
  • “Could not find the Next.js package” from the docs screenshot harness. Next skips pnpm-workspace.yaml when $HOME sits inside the repository, which the harness does on purpose, so apps/app/next.config.mjs pins turbopack.root to the repository root. Check that the pin is still there.

Testing

pnpm test at the root runs every package’s tests through Turborepo, which replays cached results when a package’s inputs haven’t changed. After a dependency or config change, add --force so the tests really run:

pnpm turbo run test --filter=app --force

Besides lint and typecheck, CI runs the package tests, the app’s unit tests in three shards, and a browser job with Chrome, Xvfb and ffmpeg installed. A test that needs that browser stack must be named *.browser.test.ts: the unit shards skip that name, and apps/app/test/browser-tests.test.ts fails a test that mentions Xvfb under any other name. In the browser job, SCREENPLAY_REQUIRE_BROWSER_STACK=1 turns a missing stack into a failure instead of a skip, so copy that check into a new browser test after its own stack gate.

A pull request that changes only a workflow file changes no package’s inputs, so CI replays main’s cached test results and the browser tests never really run. Its green check doesn’t show that the workflow change works.

To try an OpenCode chat without a model provider, run a scripted OpenAI-compatible mock server and add it as provider.mock in the JSON you pass in OPENCODE_CONFIG_CONTENT. Screenplay adds its own settings to a config already in that variable rather than replacing it (opencodeDirectoriesEnv in apps/app/lib/agent/harnesses/opencode.ts).

Linux isn’t a Mac

The desktop app renders in the Mac’s WKWebView, and nothing on Linux paints the way it does. Headless Chromium and the screenshot harness are right for layout, copy and behaviour, but not for pixel-level rendering:

  • Text snaps to whole pixels on Linux. Headless Chromium rounds text to whole CSS pixels, so a half-pixel offset never shows in a capture, while the Mac’s fractional font metrics can tip it into a visible 1px jump. To show one on Linux, nudge the parent by 0.6px.
  • WebKitGTK’s compositor isn’t Core Animation. WebKitGTK under Xvfb reproduces some WebKit layout bugs, and Playwright’s WebKit repaints its screenshots in software. Neither composites or rasters layers the way the Mac does: a label change that looked crisper in WebKitGTK went blurry on a Mac (PR #1775, reverted in PR #1776).
  • Only a real WKWebView capture proves a Mac raster or compositing fix. Capture a system WKWebView window on a Mac (screencapture), before and after. That is how the off-centre spinner was found: WebKit gives an animated <svg> its own layer and pivots it off the pixel grid, so spinners rotate their <path> instead (PR #1783).

To check a layout or JavaScript fix in WebKit from a Linux container, where Playwright’s WebKit may not download, run WebKitGTK under Xvfb. Install xvfb python3-gi gir1.2-webkit2-4.1 gir1.2-gtk-3.0 imagemagick with apt, start Xvfb :99, and open the page in a short Python GTK WebView script (use a Python that can import gi: in the cloud container that’s python3.12, not the default 3.13). Have the script poll a file for JavaScript to evaluate, so you can control the page, for example the fixture world’s camera with window.__canvasCamera.setTransform(x, y, zoom), and shoot the screen with import -window root. It shows layout, never proof of a raster fix.

Zoomed frames blur on the Mac by choice; see ADR 0034 before trying again.

Desktop app

pnpm --filter desktop build:sidecar # build apps/app as the bundled sidecar pnpm --filter desktop dev # run the Tauri app pnpm --filter desktop build # package Screenplay.app

This needs the Rust and Tauri toolchains. See Desktop app.

Releasing the desktop app

Releases are cut on a Mac with one command:

pnpm --filter desktop release patch # or minor, major, or an exact X.Y.Z

It bumps the version, builds a signed and notarized .dmg, checks it with Gatekeeper, then commits the bump, tags desktop-v<version> and publishes a GitHub Release with the .dmg attached, once under its version and once as Screenplay.dmg, the name the homepage’s Download buttons link to. Nothing is tagged or published unless the build verifies.

The Release’s notes are a short changelog for people using the app, not a list of commits. Before the build, the script collects the pull requests merged since the last release that change the app (skipping the homepage, docs, tests and CI), and asks claude -p to write them up as New, Improved and Fixed. It shows the draft so you can accept it, edit it in $EDITOR, or stop. Without Claude Code installed, the draft lists the pull request titles. To write the notes yourself, pass a Markdown file with --notes notes.md.

Releasing needs Node 23 or later, the gh CLI signed in, a clean working tree, and the Apple signing keys in apps/desktop/.env.release (copy .env.release.example).

Screenshots for design review

Design-polish tickets ship before/after screenshots on the PR. The screenshot harness boots the local build against a seeded fixture world and captures a named list of screens in light and dark:

pnpm --filter app screenshots:boot # a browsable, fully-populated local build pnpm --filter app screenshots:shots --screens canvas # named screens, both themes

The harness README covers the before/after workflow, how to add a screen, and what the local build leaves out.

Writing docs

These docs live in apps/docs/content as MDX. Run the site with pnpm --filter docs dev, then open http://localhost:3002/docs.

Screenshots are framed WebP images in apps/docs/public/screenshots, in a light and a dark variant (name.light.webp, name.dark.webp). Embed one with:

<Screenshot name="hero" alt="Describe what the screenshot shows" />

The component shows the variant that matches the reader’s theme. Put two related shots side by side (they stack on a phone) with:

<ScreenshotRow> <Screenshot name="frame-ask" caption="Just drawn" alt="…" /> <Screenshot name="frame-unanswered" caption="Skipped" alt="…" /> </ScreenshotRow>

Keep full-window shots for the Introduction and Core concepts, where the whole layout is the point. Everywhere else, crop to the part the section is about. Every screenshot is generated: run pnpm --filter docs screenshots to regenerate them after a UI change, and see Docs screenshots to add one.

Pull requests

  • Open a pull request ready for review, not as a draft.
  • Before you push, merge main in and run the app’s full suite (pnpm --filter app test), pnpm typecheck and pnpm lint. A pull request can be merged as soon as its review looks right, before CI finishes, so a red check found only by CI lands on main.
  • A pull request that changes what a user sees or configures updates the page here that describes it, or says why not on a Docs: line in its description.

Dependencies lists the versions held back on purpose, and Publishing covers the npm packages and preview deploys.

Issues

Bugs and feature requests are tracked in GitHub issues.

Last updated on