Skip to main content

​
Development Environment Setup

This guide will help you set up Excalidraw for local development and testing.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js - Version 18.0.0 or higher
  • Yarn - v1.22.22 (specified in package manager)
  • Git - For version control

​
Installation Options

1

Fork and Clone the Repository

  1. Fork the Excalidraw repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/excalidraw.git
cd excalidraw
  1. Set up the upstream remote to keep your fork in sync:
git remote add upstream https://github.com/excalidraw/excalidraw.git
git fetch upstream
git branch --set-upstream-to=upstream/master master
2

Install Dependencies

Install all project dependencies using Yarn:
yarn
This will install dependencies for all packages in the monorepo using Yarn workspaces.
3

Start the Development Server

Start the development server:
yarn start
The application will be available at http://localhost:3000.
4

Create a Feature Branch

Create a new branch for your changes:
git checkout -b your-branch-name

​
Option 2: CodeSandbox

For quick contributions without local setup:
1

Open in CodeSandbox

Go to https://codesandbox.io/p/github/excalidraw/excalidraw
2

Connect GitHub Account

Sign in with your GitHub account and reload the page if needed.
3

Fork the Sandbox

  1. Navigate to the Git tab on the left side
  2. Click “Fork Sandbox”
  3. Start coding immediately
  4. Commit and create PRs directly from CodeSandbox

​
Option 3: Docker Compose

For containerized development without Node.js setup: 
docker-compose up --build -d

​
Available Scripts

​
Development

# Start development server
yarn start

# Start production build locally
yarn start:production

# Build the application
yarn build

# Build preview version
yarn build:preview

​
Package Development

# Build all packages
yarn build:packages

# Build individual packages
yarn build:common
yarn build:element
yarn build:math
yarn build:excalidraw

# Build the app
yarn build:app

​
Testing

# Run all tests in watch mode
yarn test

# Run all tests once
yarn test:app --watch=false

# Update test snapshots
yarn test:update

# Run test coverage
yarn test:coverage

# Run tests with UI
yarn test:ui

# Run all test suites
yarn test:all

​
Code Quality

# Type check with TypeScript
yarn test:typecheck

# Lint code with ESLint
yarn test:code

# Check formatting with Prettier
yarn test:other

# Auto-fix linting issues
yarn fix:code

# Auto-fix formatting issues
yarn fix:other

# Fix all issues (formatting + linting)
yarn fix

​
Cleanup

# Remove build artifacts
yarn rm:build

# Remove node_modules
yarn rm:node_modules

# Clean install (remove node_modules and reinstall)
yarn clean-install

​
Setting Up Collaboration Features

To test real-time collaboration locally, you’ll need to set up the Excalidraw collaboration server. Follow the instructions in the collaboration server repository to run it alongside the main application.

​
Verifying Your Setup

After setup, verify everything works:
1

Check Type Safety

yarn test:typecheck
This should complete without errors.
2

Run Tests

yarn test:update
All tests should pass.
3

Check Code Style

yarn fix
This ensures your code follows the project’s style guidelines.

​
Git Hooks

Excalidraw uses Husky for Git hooks:
  • Pre-commit: Runs lint-staged to automatically lint and format staged files
  • Staged files are checked with:
    • ESLint for .js, .ts, .tsx files
    • Prettier for .css, .scss, .json, .md, .html, .yml files

​
Troubleshooting

​
Port Already in Use

If port 3000 is already in use, the dev server will try the next available port. Check your terminal for the actual URL.

​
Dependency Issues

If you encounter dependency-related errors: 
yarn clean-install

​
Type Errors

Make sure your editor is using the workspace TypeScript version: 
yarn test:typecheck

​
Test Failures

Update snapshots if your changes intentionally affect test outputs: 
yarn test:update

​
Next Steps

Now that your environment is set up:
  1. Read the Architecture Overview to understand the codebase structure
  2. Review the Contribution Guidelines before making changes
  3. Check the Testing Guide to learn how to write tests

​
Resources