Getting started

This page walks through cloning the repo, installing dependencies, and running the most common workflows.

Prerequisites

• Node ^20.0.0
• Yarn 4 (managed via Corepack)
• A POSIX-ish shell (macOS or Linux). Windows works through WSL2.

npm i -g corepack

The repo's package manager is pinned in package.json ("packageManager": "yarn@4.12.0"). Do not use npm; the lockfile is yarn-shaped and many scripts assume Yarn workspaces.

Install

From the repo root:

yarn

The postinstall step runs husky install && yarn refresh-assets, which wires the git hooks under .husky/ and regenerates the asset modules under packages/assets/.

Common commands

These come from the root package.json and are documented in AGENTS.md.

Develop

Command	What it does
yarn dev	Starts the examples app at http://localhost:5420. This is the canonical SDK dev loop.
yarn dev-app	Starts the tldraw.com client and its workers.
yarn dev-docs	Starts the docs site at apps/docs.
yarn dev-vscode	Opens the VS Code extension folder and starts its dev tasks.
yarn dev-template <name>	Runs one of the templates under templates/.

Build

Command	What it does
yarn build	Incremental build of every changed package via lazyrepo.
yarn build-package	Builds only the SDK packages (packages/*).
yarn build-app	Builds apps/dotcom/client.
yarn build-docs	Builds the docs site.
yarn build-api	Regenerates the api-extractor reports for public APIs.
yarn build-i18n	Builds translation bundles.

Test

Command	What it does
yarn test	Runs Vitest in watch mode across the whole repo (slow; prefer per-workspace).
yarn vitest run (in a workspace)	One-shot test run for that workspace.
yarn vitest run --grep "<pattern>"	Filter tests by name.
yarn e2e	Playwright e2e for the examples app.
yarn e2e-dotcom	Playwright e2e for tldraw.com.
yarn test-coverage	Coverage report; opens the HTML output.

Lint, format, typecheck

Command	What it does
yarn typecheck	Refreshes assets, then runs the repo-wide TypeScript check via internal/scripts/typecheck.ts.
yarn lint	Runs internal/scripts/lint.ts (oxlint + eslint).
yarn lint-current	Lints only files changed against main.
yarn format / yarn format-current	Same with --fix.
yarn api-check	Validates the public API reports for the SDK packages.

Other

• yarn refresh-assets — regenerates the modules under packages/assets/ from assets/.
• yarn check-packages — sanity-checks package.json files across the workspace.
• yarn check-circular-deps — internal/scripts/check-circular-deps.ts.
• yarn clean — internal/scripts/clean.sh.

Your first edit

To make a small change to the SDK and see it in the browser:

1. yarn dev (this runs apps/examples, packages/tldraw, apps/bemo-worker, and apps/dotcom/image-resize-worker in parallel through lazyrepo).
2. Edit something in packages/tldraw/src/lib/... or packages/editor/src/lib/....
3. Watch the change reload at http://localhost:5420.
4. Run a focused test: cd packages/tldraw && yarn vitest run --grep "<thing you touched>".
5. If you touched cross-package types, run yarn typecheck from the repo root.
6. If you touched a public export, run yarn api-check.

Cloning starter templates

To bootstrap a new app outside the monorepo:

npx create-tldraw@latest

This is implemented in packages/create-tldraw/ and pulls from templates/.