Skip to content

Excalidraw onboarding docs#23

Open
SashaBru wants to merge 1 commit intokoldovsky:mainfrom
SashaBru:main
Open

Excalidraw onboarding docs#23
SashaBru wants to merge 1 commit intokoldovsky:mainfrom
SashaBru:main

Conversation

@SashaBru
Copy link
Copy Markdown

@SashaBru SashaBru commented Mar 26, 2026

Summary by CodeRabbit

  • Documentation
    • Added comprehensive onboarding guide documenting repository structure, development setup, local development workflows, build system details, core architectural concepts, and contribution guidelines for new contributors.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 26, 2026

📝 Walkthrough

Walkthrough

A new ONBOARDING.md documentation file has been added containing comprehensive onboarding guidance for the Excalidraw project. The guide covers repository structure, architecture, prerequisites, development workflows, testing, code quality standards, build systems, core concepts, and contribution guidelines.

Changes

Cohort / File(s) Summary
Onboarding Documentation
ONBOARDING.md
Added comprehensive onboarding guide including project overview, Yarn monorepo structure, architecture diagrams, local development commands, directory structure explanation, development workflows and scripts, testing organization, code quality enforcement, build system details, core concepts reference, PR checklist, and branch strategy.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Hops of joy through docs so new,
A roadmap clear for me and you,
With yarn and scripts and paths so bright,
Excalidraw welcomes coders right!
Let's build and draw with guided light!

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Excalidraw onboarding docs' accurately and concisely describes the main change: addition of a comprehensive onboarding documentation file.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🧹 Nitpick comments (12)
ONBOARDING.md (12)

208-227: Add language specification for package structure.

The packages/excalidraw/ directory structure should specify a language (e.g., text).

📝 Suggested fix
-```
+```text
 packages/excalidraw/
 ├── index.tsx                 ← Library entry point / public exports
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@ONBOARDING.md` around lines 208 - 227, The fenced code block showing the
packages/excalidraw/ directory tree lacks a language specifier; update the
opening fence from ``` to ```text so the snippet is marked as plain text (i.e.,
alter the code block that begins before "packages/excalidraw/" to start with
"```text") to satisfy the documentation lint rule.

55-73: Specify language for directory structure block.

The directory structure listing should have a language specification (e.g., text or plaintext) for consistent rendering across different Markdown viewers.

📝 Suggested fix
-```
+```text
 excalidraw/                    ← repo root
 ├── excalidraw-app/            ← The web application (excalidraw.com)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@ONBOARDING.md` around lines 55 - 73, The fenced code block showing the repo
tree in ONBOARDING.md lacks a language tag, which can cause inconsistent
rendering; update the opening fence for that block from ``` to a
language-specified fence like ```text (or ```plaintext) so the directory
structure is rendered consistently across markdown viewers and remains
preformatted; locate the code block that begins with the repo tree (the block
containing "excalidraw/ ← repo root" and the nested package list) and replace
its opening fence accordingly.

288-302: Add language specification for dependency graph.

The package dependency ASCII diagram should specify text as the language.

📝 Suggested fix
-```
+```text
          `@excalidraw/common`
                ▲   ▲   ▲
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@ONBOARDING.md` around lines 288 - 302, The ASCII dependency graph block (the
triple-backtick fenced code containing lines like "@excalidraw/common",
"@excalidraw/excalidraw", "excalidraw-app", etc.) should declare its language as
text; update the opening fence from ``` to ```text so the diagram is
rendered/treated as plain text (e.g., change the fence immediately before the
line starting with "         `@excalidraw/common`" to "```text").

79-112: Specify language for architecture diagram.

The ASCII architecture diagram should specify text as the language for proper rendering.

📝 Suggested fix
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                        MONOREPO (Yarn Workspaces)                   │
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@ONBOARDING.md` around lines 79 - 112, Update the ASCII architecture diagram
code fence in ONBOARDING.md to explicitly declare the language as text by
changing the opening triple-backtick for the diagram block to ```text so the
diagram (the MONOREPO (Yarn Workspaces) ASCII art block) renders correctly;
leave the closing triple-backticks unchanged.

35-47: Add language specifications to fenced code blocks for better rendering.

Lines 35-47 contain fenced code blocks without language specifications. While the ASCII diagram could use text, the installation command block (lines 45-47) should specify bash for proper syntax highlighting.

📝 Suggested fix for installation command block
 
 The library can also be embedded in any React application:
+```bash
 npm install `@excalidraw/excalidraw`
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 35 - 47, Fenced code blocks in the snippet (the
ASCII diagram block and the installation command block containing "npm install
@excalidraw/excalidraw") lack language specifiers; update the first ASCII
diagram block to use text and the installation command block to use bash
so the diagram and the npm command are rendered with appropriate syntax
highlighting.


</details>

---

`141-175`: **Add bash language specification to command blocks.**

Multiple command blocks in this section lack language specifications. Adding `bash` will enable syntax highlighting.

<details>
<summary>📝 Suggested fixes</summary>

For the verification commands (lines 141-145):
```diff
-```bash
+```bash
 node --version   # should print v18.x.x or higher
 yarn --version   # should print 1.22.x
 git --version
 ```
```

For clone commands (lines 153-157):
```diff
-```bash
+```bash
 git clone https://github.com/excalidraw/excalidraw.git
 cd excalidraw
 yarn install
 ```
```

For start commands (lines 163-165 and 171-173):
```diff
-```bash
+```bash
 yarn start
 ```
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 141 - 175, Add the bash language tag to the
markdown fenced code blocks containing shell commands so they render with syntax
highlighting: update the blocks containing "node --version ... git --version",
the clone/install block with "git clone
https://github.com/excalidraw/excalidraw.git / cd excalidraw / yarn install",
and the run blocks with "yarn start" and "yarn start:example" to use ```bash
fenced code blocks.


</details>

---

`312-317`: **Add language specification for workflow diagram.**

The development workflow ASCII diagram should specify `text` as the language.

<details>
<summary>📝 Suggested fix</summary>

```diff
-```
+```text
 ┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌─────────────┐
 │  yarn start │────►│  Edit code   │────►│ yarn test:   │────►│  yarn fix   │
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 312 - 317, The fenced ASCII workflow block
currently lacks a language tag; update the triple-backtick fence that opens the
diagram (the block starting with "┌─────────────┐ ┌──────────────┐") to
include the language spec "text" (i.e., change the opening totext) and
keep the closing ``` unchanged so the diagram is treated as text in Markdown
rendering.


</details>

---

`454-482`: **Add language specifications to build process diagrams.**

The build process tree diagrams and build order list should specify language (e.g., `text`) for consistent rendering.

<details>
<summary>📝 Suggested fixes</summary>

For app build (line 454):
```diff
-```
+```text
 yarn build
   └── yarn build:app          (vite build → excalidraw-app/dist/)
```

For package build (line 464):
```diff
-```
+```text
 yarn build:excalidraw
   └── rimraf dist
```

For build order (line 477):
```diff
-```
+```text
 1. `@excalidraw/common`    (yarn build:common)
 2. `@excalidraw/math`      (yarn build:math)
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 454 - 482, The code blocks showing the build
process diagrams (the yarn build tree, the yarn build:excalidraw package build
snippet, and the Build Order list) lack a language spec and should include one
for consistent rendering; edit the fenced code blocks containing the yarn build
diagram, the yarn build:excalidraw snippet, and the numbered build order so the
opening fence is text (e.g., change to ```text) while keeping the exact
block content (lines showing "yarn build" tree, "yarn build:excalidraw" steps,
and the numbered list of packages) unchanged.


</details>

---

`185-200`: **Add language specification for directory structure.**

The `excalidraw-app/` directory structure should specify `text` or `plaintext` as the language.

<details>
<summary>📝 Suggested fix</summary>

```diff
-```
+```text
 excalidraw-app/
 ├── App.tsx                   ← Root app component
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 185 - 200, The fenced code block showing the
directory tree for "excalidraw-app/" in ONBOARDING.md should declare its
language as text (or plaintext); update the block fence that currently begins
with to usetext (e.g., the block containing the "excalidraw-app/"
listing and entries like App.tsx, index.tsx) so the directory structure is
rendered as plain text.


</details>

---

`233-277`: **Add language specifications to package structure listings.**

The directory structures for `packages/common/`, `packages/element/`, and `packages/math/` all lack language specifications.

<details>
<summary>📝 Suggested fixes</summary>

For common (line 233), element (line 249), and math (line 267):
```diff
-```
+```text
 src/
 ├── constants.ts              ← App-wide constants
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 233 - 277, The markdown directory listing code
blocks in the ONBOARDING.md sections for packages/common, packages/element, and
packages/math are missing language specifiers; update each triple-backtick fence
that wraps the src/ tree (the blocks showing constants.ts, newElement.ts,
point.ts, etc.) to include a language tag like text so the listings render with the intended monospace formatting (add text at the opening fence for the
three directory-listing code blocks).


</details>

---

`386-390`: **Add language specification for test location structure.**

The test directory listing should specify a language (e.g., `text`).

<details>
<summary>📝 Suggested fix</summary>

```diff
-```
+```text
 packages/excalidraw/tests/    ← Library unit & integration tests
 excalidraw-app/tests/         ← App-level tests
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 386 - 390, The fenced code block showing the test
directory listing should include a language specifier for plain text; update the
opening backticks of the code block that contains the lines
"packages/excalidraw/tests/ ← Library unit & integration tests",
"excalidraw-app/tests/ ← App-level tests", and
"packages/*/src/tests/ ← Package-level tests (element, math, common)" to
use ```text so the block is explicitly marked as text.


</details>

---

`548-555`: **Add language specification for PR checklist.**

The PR checklist should have a language specification (e.g., `text` or `markdown`).

<details>
<summary>📝 Suggested fix</summary>

```diff
-```
+```text
 [ ] yarn test:update      ← tests pass and snapshots are up-to-date
 [ ] yarn test:typecheck   ← no TypeScript errors
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @ONBOARDING.md around lines 548 - 555, The fenced code block containing the
PR checklist in ONBOARDING.md lacks a language specifier; update the opening
fence (the triple backticks that wrap the checklist) to include a language tag
such as "text" or "markdown" (e.g., change totext) so the checklist
renders with the intended formatting; locate the checklist block (the
triple-backtick fence and the lines starting with "[ ] yarn test:update") and
add the language specifier to the opening fence.


</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @ONBOARDING.md:

  • Around line 559-560: Update the onboarding doc to use the repository's default
    branch name: replace instances of "master" with "main" in the branch strategy
    lines (e.g., the bullets that currently read "Work on feature branches off
    master" and "PRs target master") so they read "Work on feature branches off
    main" and "PRs target main"; run a quick search for any other occurrences of
    the symbol master in ONBOARDING.md and update them to main to keep the
    guidance consistent with the current PR target.

Nitpick comments:
In @ONBOARDING.md:

  • Around line 208-227: The fenced code block showing the packages/excalidraw/
    directory tree lacks a language specifier; update the opening fence from ``` to
begins before "packages/excalidraw/" to start with "```text") to satisfy the
documentation lint rule.
- Around line 55-73: The fenced code block showing the repo tree in
ONBOARDING.md lacks a language tag, which can cause inconsistent rendering;
update the opening fence for that block from ``` to a language-specified fence
like ```text (or ```plaintext) so the directory structure is rendered
consistently across markdown viewers and remains preformatted; locate the code
block that begins with the repo tree (the block containing "excalidraw/ ← repo
root" and the nested package list) and replace its opening fence accordingly.
- Around line 288-302: The ASCII dependency graph block (the triple-backtick
fenced code containing lines like "@excalidraw/common",
"@excalidraw/excalidraw", "excalidraw-app", etc.) should declare its language as
text; update the opening fence from ``` to ```text so the diagram is
rendered/treated as plain text (e.g., change the fence immediately before the
line starting with "         `@excalidraw/common`" to "```text").
- Around line 79-112: Update the ASCII architecture diagram code fence in
ONBOARDING.md to explicitly declare the language as text by changing the opening
triple-backtick for the diagram block to ```text so the diagram (the MONOREPO
(Yarn Workspaces) ASCII art block) renders correctly; leave the closing
triple-backticks unchanged.
- Around line 35-47: Fenced code blocks in the snippet (the ASCII diagram block
and the installation command block containing "npm install
`@excalidraw/excalidraw`") lack language specifiers; update the first ASCII
diagram block to use ```text and the installation command block to use ```bash
so the diagram and the npm command are rendered with appropriate syntax
highlighting.
- Around line 141-175: Add the bash language tag to the markdown fenced code
blocks containing shell commands so they render with syntax highlighting: update
the blocks containing "node --version ... git --version", the clone/install
block with "git clone https://github.com/excalidraw/excalidraw.git / cd
excalidraw / yarn install", and the run blocks with "yarn start" and "yarn
start:example" to use ```bash fenced code blocks.
- Around line 312-317: The fenced ASCII workflow block currently lacks a
language tag; update the triple-backtick fence that opens the diagram (the block
starting with "┌─────────────┐     ┌──────────────┐") to include the language
spec "text" (i.e., change the opening ``` to ```text) and keep the closing ```
unchanged so the diagram is treated as text in Markdown rendering.
- Around line 454-482: The code blocks showing the build process diagrams (the
yarn build tree, the yarn build:excalidraw package build snippet, and the Build
Order list) lack a language spec and should include one for consistent
rendering; edit the fenced code blocks containing the yarn build diagram, the
yarn build:excalidraw snippet, and the numbered build order so the opening fence
is ```text (e.g., change ``` to ```text) while keeping the exact block content
(lines showing "yarn build" tree, "yarn build:excalidraw" steps, and the
numbered list of packages) unchanged.
- Around line 185-200: The fenced code block showing the directory tree for
"excalidraw-app/" in ONBOARDING.md should declare its language as text (or
plaintext); update the block fence that currently begins with ``` to use ```text
(e.g., the block containing the "excalidraw-app/" listing and entries like
App.tsx, index.tsx) so the directory structure is rendered as plain text.
- Around line 233-277: The markdown directory listing code blocks in the
ONBOARDING.md sections for packages/common, packages/element, and packages/math
are missing language specifiers; update each triple-backtick fence that wraps
the src/ tree (the blocks showing constants.ts, newElement.ts, point.ts, etc.)
to include a language tag like ```text so the listings render with the intended
monospace formatting (add ```text at the opening fence for the three
directory-listing code blocks).
- Around line 386-390: The fenced code block showing the test directory listing
should include a language specifier for plain text; update the opening backticks
of the code block that contains the lines "packages/excalidraw/tests/    ←
Library unit & integration tests", "excalidraw-app/tests/         ← App-level
tests", and "packages/*/src/__tests__/     ← Package-level tests (element, math,
common)" to use ```text so the block is explicitly marked as text.
- Around line 548-555: The fenced code block containing the PR checklist in
ONBOARDING.md lacks a language specifier; update the opening fence (the triple
backticks that wrap the checklist) to include a language tag such as "text" or
"markdown" (e.g., change ``` to ```text) so the checklist renders with the
intended formatting; locate the checklist block (the triple-backtick fence and
the lines starting with "[ ] yarn test:update") and add the language specifier
to the opening fence.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 69af6113-0535-415b-9084-130b5eb3646b

📥 Commits

Reviewing files that changed from the base of the PR and between be47f1d and 22b101c.

📒 Files selected for processing (1)
  • ONBOARDING.md

Comment on lines +559 to +560
- Work on feature branches off `master`
- PRs target `master`
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Update branch name from "master" to "main".

The branch strategy mentions "master" as the default branch, but this PR targets "main" (as shown in the PR objectives). This inconsistency could confuse new contributors.

🔧 Suggested fix
-- Work on feature branches off `master`
-- PRs target `master`
+- Work on feature branches off `main`
+- PRs target `main`
 - Keep PRs focused — one concern per PR
📝 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
- Work on feature branches off `master`
- PRs target `master`
- Work on feature branches off `main`
- PRs target `main`
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@ONBOARDING.md` around lines 559 - 560, Update the onboarding doc to use the
repository's default branch name: replace instances of "master" with "main" in
the branch strategy lines (e.g., the bullets that currently read "Work on
feature branches off `master`" and "PRs target `master`") so they read "Work on
feature branches off `main`" and "PRs target `main`"; run a quick search for any
other occurrences of the symbol `master` in ONBOARDING.md and update them to
`main` to keep the guidance consistent with the current PR target.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant