Development Environment Setup

Get your local development environment set up for contributing to Excalidraw

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

Option 1: Local Setup (Recommended)

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
   

   3. 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

• Excalidraw Repository
• Issue Tracker
• Discord Community
• Project Roadmap