Skip to content

Created onboarding document for excalidraw project #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paulsamtsov wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Created onboarding document for excalidraw project #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions Onboarding_document.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Onboarding Document

Welcome to the Excalidraw project! This document is designed to help new team members get up to speed quickly. It covers the general overview, key features, technology stack, architecture, and instructions for running the application locally.

## 1. General Description

**What is it?**
Excalidraw is an open-source, virtual, hand-drawn style whiteboard application. It is highly collaborative and end-to-end encrypted.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix hyphenation in compound adjective.

When "hand-drawn style" is used as a compound adjective modifying "whiteboard application," it should be hyphenated as "hand-drawn-style" per standard English grammar rules.

✏️ Proposed fix 
-Excalidraw is an open-source, virtual, hand-drawn style whiteboard application. It is highly collaborative and end-to-end encrypted.
+Excalidraw is an open-source, virtual, hand-drawn-style whiteboard application. It is highly collaborative and end-to-end encrypted.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Excalidraw is an open-source, virtual, hand-drawn style whiteboard application. It is highly collaborative and end-to-end encrypted.
Excalidraw is an open-source, virtual, hand-drawn-style whiteboard application. It is highly collaborative and end-to-end encrypted.
🧰 Tools
🪛 LanguageTool

[grammar] ~8-~8: Use a hyphen to join words.
Context: ...w is an open-source, virtual, hand-drawn style whiteboard application. It is high...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@Onboarding_document.md` at line 8, Update the sentence in
Onboarding_document.md that reads "Excalidraw is an open-source, virtual,
hand-drawn style whiteboard application." to hyphenate the compound adjective so
it reads "hand-drawn-style" when modifying "whiteboard application"; locate the
exact sentence and replace "hand-drawn style" with "hand-drawn-style" to correct
the hyphenation.


**What is it for?**
It is built for creating beautiful hand-drawn like diagrams, wireframes, architectural visualizations, brainstorming sessions, or whatever visual representations you need.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix hyphenation in compound adjective.

The phrase "hand-drawn like diagrams" should use "hand-drawn-like" with a hyphen when functioning as a compound adjective.

✏️ Proposed fix 
-It is built for creating beautiful hand-drawn like diagrams, wireframes, architectural visualizations, brainstorming sessions, or whatever visual representations you need.
+It is built for creating beautiful hand-drawn-like diagrams, wireframes, architectural visualizations, brainstorming sessions, or whatever visual representations you need.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
It is built for creating beautiful hand-drawn like diagrams, wireframes, architectural visualizations, brainstorming sessions, or whatever visual representations you need.
It is built for creating beautiful hand-drawn-like diagrams, wireframes, architectural visualizations, brainstorming sessions, or whatever visual representations you need.
🧰 Tools
🪛 LanguageTool

[grammar] ~11-~11: Use a hyphen to join words.
Context: ... built for creating beautiful hand-drawn like diagrams, wireframes, architectural...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@Onboarding_document.md` at line 11, Replace the incorrect unhyphenated
compound adjective "hand-drawn like diagrams" with the hyphenated form
"hand-drawn-like diagrams" in the sentence "It is built for creating beautiful
hand-drawn like diagrams, wireframes, architectural visualizations,
brainstorming sessions, or whatever visual representations you need." to correct
hyphenation.


**What tasks does it solve?**
Excalidraw provides a frictionless, intuitive drawing interface that focuses on speed and simplicity over pixel-perfect alignment. It allows individuals and teams to quickly externalize their thoughts, collaborate in real-time securely, and easily export or embed their diagrams into other tools and platforms.

## 2. Key Features

- **Infinite Canvas:** Unrestricted drawing space.
- **Hand-drawn Aesthetic:** Elements look sketched by hand, focusing attention on the concepts rather than the exact styling.
- **Rich Toolset:** Rectangle, circle, diamond, arrow, line, free-draw, eraser, text, and more.
- **Smart Connections:** Arrow-binding and labeled arrows for diagramming.
- **Customization & Libraries:** Dark mode, customizable styles, and support for extensive custom shape libraries.
- **Export & Integration:** Export to PNG, SVG, and clipboard. Drawings can be saved in an open `.excalidraw` JSON format.
- **Collaboration & Security:** Real-time collaboration via shareable links with robust end-to-end encryption.
- **Offline First:** PWA support allows the app to work offline, with autosaving directly to the browser.

## 3. Technology Stack

The project relies on a modern frontend stack:
- **Language:** TypeScript and JavaScript
- **UI Framework:** React
- **Build & Development Tool:** Vite
- **Package Manager:** Yarn (v1.22.x) leveraging Yarn Workspaces for a monorepo setup
- **Testing:** Vitest (for unit/component tests)
- **Linting & Formatting:** ESLint, Prettier

## 4. Architecture and Key Components

The codebase is organized as a monorepo containing multiple packages and applications. The primary directory of interest is `excalidraw/`, which houses the core project:

- **`excalidraw-app/` (The Application):** This is the web application hosted at excalidraw.com. It acts as a showcase, integrating the core editor with added features like real-time collaboration, PWA support, local-first autosaving, and shareable links.
- **`packages/excalidraw/` (The Core Package):** This is the core Excalidraw editor logic packaged for npm (`@excalidraw/excalidraw`). It is designed as a drop-in React component so that other applications can embed Excalidraw's functionality.
- **`packages/math/`, `packages/element/`, `packages/common/`, `packages/utils/`:** These are internal supporting libraries and modular utilities used by the core editor and the main application.
- **`examples/`:** Contains reference implementations on how to integrate the Excalidraw npm package in various environments (e.g., Next.js, standalone scripts).

## 5. Technical Prerequisites

Before contributing or running the project locally, ensure your development environment meets the following requirements:
- **Node.js:** Version 18.0.0 or higher.
- **Yarn:** The classic version (1.22.x).
- **Git:** For version control.
- **Editor:** VSCode is recommended with the ESLint and Prettier extensions installed for a seamless development experience.

## 6. How to Run the Application Locally

Follow these steps to set up and start the application on your local machine:

1. **Install Dependencies**
Navigate to the `excalidraw` folder (or the root if the monorepo handles it top-level) and run:
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify the installation directory.

The instruction "Navigate to the excalidraw folder (or the root if the monorepo handles it top-level)" is confusing and could lead new contributors to the wrong location. Provide a clear, unambiguous path.

📝 Suggested clarification 
-   Navigate to the `excalidraw` folder (or the root if the monorepo handles it top-level) and run:
+   Navigate to the repository root and run:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Navigate to the `excalidraw` folder (or the root if the monorepo handles it top-level) and run:
Navigate to the repository root and run:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@Onboarding_document.md` at line 59, Replace the ambiguous instruction
"Navigate to the `excalidraw` folder (or the root if the monorepo handles it
top-level)" with a clear path: explicitly tell contributors to cd into the
package (e.g., "packages/excalidraw") and only use the repository root when this
project lives at the top level; locate the exact sentence in
Onboarding_document.md and change it to something like: "Navigate to the
excalidraw package at packages/excalidraw (or to the repository root only if
this project is top-level in your monorepo)."

```bash
yarn install
```
*(Note: If you encounter dependency issues, you can run `yarn clean-install` to wipe `node_modules` and start fresh).*
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if clean-install script exists in package.json files

fd -t f 'package.json' -x jq -r 'select(.scripts["clean-install"] != null) | {file: input_filename, script: .scripts["clean-install"]}'

Repository: koldovsky/is-01-docs

Length of output: 46

🏁 Script executed:

#!/bin/bash
# First, find all package.json files
fd -t f 'package.json' | head -20 | while read file; do
  echo "=== $file ==="
  cat "$file" | jq '.scripts | keys' 2>/dev/null || echo "Failed to parse $file"
done

Repository: koldovsky/is-01-docs

Length of output: 46

🏁 Script executed:

#!/bin/bash
# Simple check for package.json
ls -la package.json 2>/dev/null || echo "No package.json in root"

# Check if it exists anywhere
find . -name "package.json" -type f 2>/dev/null | head -10

# If found, show the scripts section
if [ -f "package.json" ]; then
  echo "=== Scripts in package.json ==="
  jq '.scripts // {}' package.json
fi

Repository: koldovsky/is-01-docs

Length of output: 87

🏁 Script executed:

#!/bin/bash
# List files in root directory
ls -la | head -30

# Check git ls-files for project structure overview
git ls-files | head -30

Repository: koldovsky/is-01-docs

Length of output: 557

Update the documentation to use standard Yarn commands.

The yarn clean-install command is not a standard Yarn v1 (classic) command and is not defined as a custom script in this project. Update the note to use standard commands:

Suggested change 
-   *(Note: If you encounter dependency issues, you can run `yarn clean-install` to wipe `node_modules` and start fresh).*
+   *(Note: If you encounter dependency issues, you can remove `node_modules` and `yarn.lock`, then run `yarn install` to start fresh).*
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
*(Note: If you encounter dependency issues, you can run `yarn clean-install` to wipe `node_modules` and start fresh).*
*(Note: If you encounter dependency issues, you can remove `node_modules` and `yarn.lock`, then run `yarn install` to start fresh).*
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@Onboarding_document.md` at line 63, Replace the non-standard command "yarn
clean-install" in the onboarding note with standard Yarn alternatives; update
the note to suggest either removing node_modules and reinstalling (e.g., "rm -rf
node_modules && yarn install" or using a cross-platform tool like "rimraf
node_modules && yarn install") or using "yarn install --force" to refresh
dependencies, and ensure the note mentions which option is cross-platform if you
include rimraf.


2. **Start the Development Server**
To start the main `excalidraw-app` with live reloading:
```bash
yarn start
```
This will run the Vite development server. Check your terminal output for the local URL (usually `http://localhost:3000` or similar).

3. **Running Tests & Quality Checks**
Ensure your changes adhere to project standards:
```bash
# Run Vitest test suites
yarn test

# Run formatting and linting
yarn test:code
yarn test:other

# Run all checks (typecheck, linting, tests)
yarn test:all
```

4. **Building for Production**
To verify the production build completes successfully:
```bash
yarn build
```

Welcome to the team, and happy drawing!