Development workflow

The minimal loop for changing SDK code.

1. Set up

Install Corepack and dependencies:

npm i -g corepack
yarn

postinstall runs husky install and yarn refresh-assets, which populates the generated modules under packages/assets/ from the source files in assets/.

2. Pick a target

You're changing…	Run this
The SDK (packages/editor, packages/tldraw)	yarn dev (Examples app at localhost:5420)
The tldraw.com client	yarn dev-app
The docs	yarn dev-docs
The VS Code extension	yarn dev-vscode
A starter template	yarn dev-template <name>

yarn dev is the canonical loop. It runs apps/examples, packages/tldraw, apps/bemo-worker, and apps/dotcom/image-resize-worker in parallel through lazyrepo.

3. Edit

• SDK code lives under packages/<name>/src/lib/. Public exports go in packages/<name>/src/index.ts.
• Default shapes/tools/UI live in packages/tldraw/src/lib/.
• Examples live under apps/examples/src/examples/<kebab-case-name>/.
• Docs articles live under apps/docs/content/.

When editing, follow AGENTS.md:

• Match existing file-local style.
• Use named-object/enum options instead of bare boolean parameters in new APIs.
• Don't hand-edit generated files (api-report.api.md, asset modules, schema reports).

4. Verify

Run the smallest meaningful check:

# In the changed workspace
cd packages/tldraw
yarn vitest run --grep "SelectTool"

Promote to broader checks based on what changed:

Change scope	Add this check
Cross-package types or schema	yarn typecheck (from repo root)
Public exports	yarn api-check
Translations	yarn build-i18n
Asset additions	yarn refresh-assets
User-facing dotcom behavior	yarn e2e-dotcom (small subset)
Examples e2e	yarn e2e

The repo's CI gate is in .github/workflows/checks.yml; that file is the source of truth for what is required.

5. Format and lint

yarn lint-current     # only files changed against main
yarn format-current   # same with --fix

Husky (.husky/) runs lint-staged on commit, which runs oxfmt --no-error-on-unmatched-pattern on every staged JS/TS/CSS/MD file (see the lint-staged block in package.json).

6. Commit and PR

• Commit message format: <type>(<scope>): <description>.
• One logical change per PR.
• Use the PR template at .github/pull_request_template.md.
• Link to an issue when the change has user-visible behavior.

The skills/pr/ skill (visible to agent CLIs) automates PR creation; the skills/commit-changes/ skill writes commits.

7. After merge

• Release notes for the next SDK version live in apps/docs/content/releases/next.mdx and are updated continuously. The update-release-notes skill and the update-release-notes.yml workflow keep them current.
• Versions are bumped through the publishing workflows (.github/workflows/publish-*.yml).