How to contribute

This section documents the day-to-day mechanics of working in the tldraw repo. The ground rules live in AGENTS.md at the repo root; this page distills them and points to the deeper sub-pages.

External contributions are currently paused

CONTRIBUTING.md is explicit: "We are currently not accepting pull requests from external contributors. Pull requests will be automatically closed." The note links to https://github.com/tldraw/tldraw/issues/7695 and explains it is a temporary policy. If you are an external contributor, the right channel today is issues, not PRs.

For internal contributors and forks, the rest of this section still applies.

The cardinal rules

From AGENTS.md:

1. Use Yarn 4, not npm. The repo is a Yarn workspace. Many scripts (lazy run, tsx internal/scripts/*) assume Yarn.
2. Run from the repo root. Unless a command says "run from a workspace", run it from the root via yarn <thing>.
3. Never run bare tsc. Use yarn typecheck. The repo has internal/scripts/typecheck.ts that refreshes generated assets first.
4. Prefer targeted checks. Don't run yarn vitest (the whole repo) when cd packages/tldraw && yarn vitest run --grep "<pattern>" will do.
5. Keep changes scoped. Don't refactor unrelated code while you're in there.
6. Sentence case in headings, titles, labels, and docs.

What "done" looks like

• Code change is scoped to one package (or a small set when crossing boundaries).
• Tests for the changed behavior pass: yarn vitest run in the affected workspace.
• If types or migrations crossed packages: yarn typecheck from the repo root.
• If a public API moved: yarn api-check (and the regenerated api-report.api.md is committed).
• If translations changed: yarn build-i18n.
• If shape/binding/migration changed: a migration test is added in packages/tlschema/src/migrations.test.ts (or the equivalent).
• Lint clean: yarn lint-current and yarn format-current.

PR conventions

• Title format: <type>(<scope>): <description>. Examples from recent history:
  • fix(dotcom): wait for migrations before starting zero-cache in dev (#8681)
  • refactor(overlays): clean up overlay rendering paths (#8721)
  • chore: remove unused type exports (#8720)
• Common types: feat, fix, chore, refactor, docs, revert.
• Common scopes: editor, tldraw, store, tlschema, sync, dotcom, docs, vscode, arrows, notes, shapes, toolbar, release.
• Do not add yourself or an AI tool as a co-author.
• Do not include AI attribution in commit messages, PR descriptions, or issues.

Sub-pages

• Development workflow — the concrete edit/test/PR loop.
• Testing — Vitest patterns, Playwright, where tests live.
• Debugging — common errors, dev tools, troubleshooting.
• Patterns and conventions — reactive state, side effects, ShapeUtil, naming.
• Tooling — lazyrepo, oxlint/oxfmt, api-extractor, Husky, lint-staged.