CLAUDE.md

1# CLAUDE.md - AI Assistant Guide for draw.io Desktop
2 
3## Project Overview
4 
5Draw.io Desktop is an Electron-based desktop application that wraps the core draw.io diagramming editor (included as a git submodule). It enables creating flowcharts, UML diagrams, and more, with a security-first design that isolates diagram data from the internet.
6 
7**Repository:** https://github.com/jgraph/drawio-desktop
8**License:** Apache 2.0
9**Version:** see `drawio/VERSION` (stamped into `package.json` by `npm run sync`)
10 
11## Quick Reference
12 
13```bash
14# Clone (MUST be recursive for submodule)
15git clone --recursive https://github.com/jgraph/drawio-desktop.git
16 
17# Install dependencies
18npm install
19 
20# Run application
21npm start
22 
23# Run with DevTools enabled
24DRAWIO_ENV=dev npm start
25 
26# Sync version before building (required)
27npm run sync
28 
29# Build for specific platforms
30npm run release-win       # Windows x64
31npm run release-linux     # Linux (AppImage, deb, rpm)
32npm run release-appx      # Windows Store
33```
34 
35## Project Structure
36 
37```
38drawio-desktop/
39├── src/main/
40│   ├── electron.js           # Main Electron process (3,700+ lines)
41│   ├── electron-preload.js   # IPC bridge with contextBridge
42│   ├── args.js               # CLI argument definitions and parser
43│   ├── progress-bar.js       # Progress bar for long-running operations
44│   └── disableUpdate.js      # Generated by sync script
45├── src/test/
46│   ├── cli-args.test.js      # CLI argument parsing tests (npm test)
47│   └── msi-project-created.test.js # MSI shortcut icon hook tests (npm test)
48├── drawio/                   # Git submodule - core draw.io editor
49│   └── src/main/webapp/      # Web application loaded in Electron
50├── build/                    # Build resources
51│   ├── notarize.mjs          # macOS Quick Look setup, signing + notarization
52│   ├── sign-trusted.mjs      # Windows signing hook (Azure Trusted Signing)
53│   ├── fuses.mjs             # Electron security fuses
54│   ├── msi-project-created.mjs # msiProjectCreated hook: MSI shortcuts use exe icon, not the C:\Windows\Installer icon cache
55│   ├── dmg-hidden-files.mjs  # beforePack hook: parks hidden DMG support files outside the installer window
56│   ├── quicklook-preview.html # Quick Look preview page (viewer-static.min.js)
57│   ├── quicklook-entitlements.plist # Sandbox entitlements for .appex
58│   └── entitlements.mac.plist
59├── doc/
60│   ├── RELEASE_PROCESS.md    # Release workflow documentation
61│   └── BUILDING_FOR_PERSONAL_USE.md # Guide for unsigned fork/personal builds
62├── electron-builder-*.json   # Platform-specific build configs
63├── sync.cjs                  # Version sync script
64└── package.json
65```
66 
67## Tech Stack
68 
69- **Runtime:** Node.js 22.12+ (`engines` in `package.json`; CI builds on Node 24)
70- **Framework:** Electron (version pinned in `package.json`)
71- **Language:** JavaScript (ES6 modules)
72- **Build Tool:** electron-builder
73- **Package Manager:** npm
74 
75## Key Files
76 
77| File | Purpose |
78|------|---------|
79| `src/main/electron.js` | Main process: window management, IPC handlers, menus, auto-update |
80| `src/main/electron-preload.js` | Secure IPC bridge between renderer and main process |
81| `src/main/args.js` | CLI option definitions and argument parser (used by CLI export) |
82| `sync.cjs` | Pre-build script that syncs version from `drawio/VERSION` |
83| `electron-builder-*.json` | Platform-specific build configurations |
84| `build/sign-trusted.mjs` | electron-builder Windows signing hook (Azure Trusted Signing) |
85 
86## Code Style
87 
88- **ES6 modules** with `import`/`export`
89- **Tab indentation**
90- **Allman brace style** (opening brace on new line)
91- **camelCase** for variables, **PascalCase** for classes
92- No ESLint/Prettier - manual style consistency
93- Sparse comments; code clarity preferred
94 
95## Git Conventions
96 
97### Branches
98- `dev` - Main development branch (PR target)
99- `release` - Production releases
100- `releases/v*.*.*` - Version-specific release branches
101 
102### Commit Messages
103- Lowercase sentence style without period
104- Issue references: `[jgraph/drawio-desktop#XXXX]`
105- Examples:
106  - `Fixes paste error`
107  - `Adds buffer as dependency [jgraph/drawio-desktop#2301]`
108  - `Prepare release v29.3.0`
109 
110### Version Tags
111Format: `v{MAJOR}.{MINOR}.{PATCH}` (e.g., `v29.3.0`)
112Tags trigger CI/CD build workflows.
113 
114## Build Process
115 
1161. **Sync version:** `npm run sync` reads `drawio/VERSION` and updates `package.json`
1172. **Install:** `npm ci` for clean install
1183. **Build:** `electron-builder` with platform-specific config
1194. **Post-build:** Security fuses applied, Quick Look extension assembled (macOS), notarization (macOS)
120 
121### Code Signing
122- **Windows:** Azure Trusted Signing via the `signtoolOptions.sign` hook `build/sign-trusted.mjs` (configured in `electron-builder-win*.json`, not CSC_LINK certificates). CI (`electron-builder-win.yml`) downloads the signing dlib, locates `signtool.exe`, and authenticates with `AZURE_TENANT_ID`/`AZURE_CLIENT_ID`/`AZURE_CLIENT_SECRET` secrets
123- **macOS:** Apple Developer certificate + notarization in `build/notarize.mjs`
124- **Unsigned builds:** `DRAWIO_UNSIGNED=true` skips signing (Windows) and notarization (macOS) for personal/fork builds
125 
126### Personal / Fork Builds
127- `doc/BUILDING_FOR_PERSONAL_USE.md` documents building unsigned from a fork (the project is closed to contributions but Apache 2.0 licensed)
128- Set `DRAWIO_UNSIGNED=true` and run `electron-builder` directly with `--publish never`; use `npm run sync -- disableUpdate` so auto-update doesn't replace the custom build
129- `.github/workflows/personal-build.yml` is a manual (`workflow_dispatch`) workflow that builds unsigned installers on a fork with no secrets and attaches them as run artifacts
130 
131> **CI override:** The release build workflows check out the private `jgraph/drawio-dev` repo at its `release` branch, copy the built `*.min.js` **and** `VERSION` into the public `drawio/` submodule tree, then run `npm run sync` as normal. This lets CI ship from an internal release that is ahead of the public `drawio` tag without any change to `sync.cjs`. Out-of-tree builders (who have no access to `drawio-dev`) fall through to the public submodule's `VERSION` as before.
132 
133### Platform Build Commands
134| Command | Target |
135|---------|--------|
136| `npm run release-win` | Windows x64 (NSIS + MSI) |
137| `npm run release-win32` | Windows 32-bit |
138| `npm run release-win-arm64` | Windows ARM64 |
139| `npm run release-linux` | Linux (AppImage, deb, rpm) |
140| `npm run release-appx` | Windows Store |
141| `npm run release-snap` | Snap package |
142 
143## Architecture Notes
144 
145### Security Model
146- **Content Security Policy** prevents remote script execution
147- **contextBridge** exposes only specific APIs to renderer
148- **validateSender()** ensures IPC calls originate from local draw.io
149- No external transmission of diagram data
150- **Built-in plugins only** - external/third-party plugins were removed (07/2026). The `isPluginsEnabled` IPC action is retained, hardcoded `false`, so an older bundled webapp degrades to the "plugins disabled" dialog rather than failing
151 
152### IPC Pattern
153The preload script uses a request/response pattern with unique IDs:
154```javascript
155// Renderer sends request
156electron.request({action: 'save', data: ...}, callbackId);
157 
158// Main process handles and responds via IPC
159ipcMain.on('request', (e, data) => { ... });
160```
161 
162### macOS Quick Look Preview
163- Pressing Space in Finder shows a rendered preview of `.drawio` files
164- Uses `quicklookjs` to embed a Quick Look App Extension (`.appex`) in the app bundle
165- The `.appex` loads `viewer-static.min.js` (with embedded shapes) in a WKWebView
166- **Build flow:** `afterPack` (fuses.mjs) applies security fuses, then `afterSign` (notarize.mjs) assembles the `.appex`, signs it with sandbox entitlements, re-signs the outer `.app`, and notarizes
167- The `.appex` is inserted in `afterSign` (not `afterPack`) so it is never present unsigned during electron-builder's signing verification
168- Quick Look extensions require `app-sandbox`, but Electron helpers must not be sandboxed — so the `.appex` gets different entitlements than `entitlementsInherit`
169- The UTI `com.jgraph.drawio` is declared via `extendInfo` in `electron-builder-linux-mac.json`
170- `viewer-static.min.js` is saved to `build/` during CI before the cleanup step removes it from the drawio submodule; for local dev, it's read from the submodule directly
171 
172### Auto-Update
173- Checks GitHub releases on startup
174- Disable via `DRAWIO_DISABLE_UPDATE=true` or `--disable-update` flag
175- Flatpak detection disables updates automatically
176 
177### Data Storage
178- **macOS:** `~/Library/Application Support/draw.io`
179- **Windows:** `%APPDATA%\draw.io\`
180- Uses `electron-store` for persistent settings
181 
182## Testing
183 
184`npm test` runs the unit tests in `src/test/` (CLI argument parsing, MSI shortcut icon hook; Node's built-in test runner). Everything else is manual testing, documented in `doc/RELEASE_PROCESS.md`:
185- Launch, create diagram, add shapes, save, open
186- Export (PNG, PDF, SVG)
187- Undo/redo functionality
188- About dialog verification
189 
190## CI/CD Workflows
191 
192| Workflow | Trigger | Purpose |
193|----------|---------|---------|
194| `electron-builder.yml` | Version tag | macOS/Linux builds |
195| `electron-builder-win.yml` | Version tag | Windows builds (Azure Trusted Signing) |
196| `prepare-release.yml` | Manual | Automated release prep |
197| `hash-gen.yml` | Manual | Generate checksums |
198| `personal-build.yml` | Manual | Unsigned fork builds, artifacts only (no secrets, no publish) |
199| `stale.yml` | Schedule | Mark stale issues/PRs |
200 
201## Important Constraints
202 
2031. **Recursive clone required** - drawio submodule must be initialized
2042. **Run `npm run sync` before building** - Updates version from submodule
2053. **Version source of truth** - `drawio/VERSION` for public builds; `drawio-dev/VERSION` is copied over `drawio/VERSION` at CI time so the internal release number wins for packaged builds
2064. **Closed to contributions** - PRs not accepted; maintained by JGraph (forks for personal use are fine, see `doc/BUILDING_FOR_PERSONAL_USE.md`)
2075. **Node 22.12+ required** - see `engines` in `package.json`
208 
209## Development Tips
210 
211- Set `DRAWIO_ENV=dev` to auto-open DevTools
212- Use `npm start --enable-logging` for verbose output
213- If using symlink instead of submodule, also symlink `node_modules`
214- Main process logs to console; check terminal for errors
215 
216## Key Dependencies
217 
218| Package | Purpose |
219|---------|---------|
220| `electron` | Desktop app framework |
221| `electron-builder` | Build/package tool |
222| `electron-updater` | Auto-update mechanism |
223| `electron-store` | Persistent storage |
224| `electron-log` | Logging |
225| `@cantoo/pdf-lib` | PDF export |
226| `quicklookjs` | macOS Quick Look preview extension (dev) |
227 
228CLI argument parsing is hand-rolled in `src/main/args.js` (no `commander`).
229