excalidraw-edit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wh1le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# excalidraw-edit
+
+> Edit any `.excalidraw` file straight from the terminal.
+
+[![npm version](https://img.shields.io/npm/v/excalidraw-edit)](https://www.npmjs.com/package/excalidraw-edit)
+[![license](https://img.shields.io/npm/l/excalidraw-edit)](LICENSE)
+
+## About
+
+Opens a local server, loads [Excalidraw](https://excalidraw.com) in your browser, auto-saves to disk. Works offline.
+
+## Install
+
+```bash
+npm i -g excalidraw-edit
+```
+
+## Usage
+
+```bash
+excalidraw-edit drawing.excalidraw
+```
+
+File is created if it doesn't exist. Extension is added automatically if omitted.
+
+```bash
+excalidraw-edit mydiagram                        # opens mydiagram.excalidraw
+excalidraw-edit --theme dark sketch.excalidraw   # dark mode
+excalidraw-edit --port 3000 --no-open notes      # custom port, no browser
+```
+
+### Options
+
+| Option                | Description                  | Default  |
+| --------------------- | ---------------------------- | -------- |
+| `-p, --port <port>`   | Port to listen on            | `6417`   |
+| `-t, --theme <theme>` | `dark`, `light`, or `system` | `system` |
+| `--no-open`           | Don't open browser           |          |
+| `-V, --version`       | Output version               |          |
+| `-h, --help`          | Display help                 |          |
+
+## Development
+
+```bash
+make install   # pnpm install && build
+make test      # run tests
+make start     # start dev server
+```
+
+## References
+
+- [Excalidraw](https://excalidraw.com) — the drawing tool this project wraps
+- [go-grip](https://github.com/chrishrb/go-grip) — inspiration for the CLI approach
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "excalidraw-edit",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@10.33.0",
+  "description": "Edit .excalidraw files locally in your browser. Like grip for Excalidraw.",
+  "license": "MIT",
+  "author": "wh1le (https://github.com/wh1le)",
+  "homepage": "https://github.com/wh1le/excalidraw-edit",
+  "bugs": "https://github.com/wh1le/excalidraw-edit/issues",
+  "bin": {
+    "excalidraw-edit": "./src/cli.js"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepublishOnly": "pnpm run build",
+    "test": "node --test test/*.test.js",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix ."
+  },
+  "keywords": [
+    "excalidraw",
+    "cli",
+    "editor",
+    "diagram",
+    "whiteboard",
+    "local",
+    "drawing"
+  ],
+  "files": [
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wh1le/excalidraw-edit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@excalidraw/excalidraw": "^0.18.0",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "prettier": "^3.5.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { resolve, basename } from 'node:path';
+import { createInterface } from 'node:readline';
+import { VERSION } from './const.js';
+import { addExtension, fileExists, createScene } from './filesystem.js';
+import { startServer } from './server.js';
+
+function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() !== 'n');
+    });
+  });
+}
+
+program
+  .name('excalidraw-edit')
+  .description('Edit .excalidraw files locally in your browser')
+  .version(VERSION)
+  .argument('<file>', '.excalidraw file to edit')
+  .option('-p, --port <port>', 'port to listen on', '6417')
+  .option('--no-open', "don't open browser automatically")
+  .option(
+    '-t, --theme <theme>',
+    'theme: dark, light, or system (default)',
+    'system'
+  )
+  .action(async (file, opts) => {
+    const filePath = addExtension(resolve(file));
+    const port = parseInt(opts.port, 10);
+
+    if (!(await fileExists(filePath))) {
+      const ok = await confirm(`Create ${basename(filePath)}? [Y/n] `);
+      if (!ok) process.exit(0);
+      await createScene(filePath);
+      console.log(`Created ${basename(filePath)}`);
+    }
+
+    await startServer({ filePath, port, open: opts.open, theme: opts.theme });
+  });
+
+program.parse();

package/src/client/App.jsx

@@ -0,0 +1,45 @@
+import { Excalidraw } from '@excalidraw/excalidraw';
+
+let saveTimeout = null;
+
+function save(elements, appState, files) {
+  clearTimeout(saveTimeout);
+  saveTimeout = setTimeout(() => {
+    const data = JSON.stringify(
+      {
+        type: 'excalidraw',
+        version: 2,
+        elements: elements.filter((el) => !el.isDeleted),
+        appState: {
+          viewBackgroundColor: appState.viewBackgroundColor,
+          gridSize: appState.gridSize,
+          theme: appState.theme,
+        },
+        files: files || {},
+      },
+      null,
+      2
+    );
+
+    fetch('/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: data,
+    }).catch((err) => console.error('Save failed:', err));
+  }, 500);
+}
+
+export default function App({ scene, theme }) {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Excalidraw
+        initialData={{
+          elements: scene.elements || [],
+          appState: { ...scene.appState, theme },
+          files: scene.files || {},
+        }}
+        onChange={save}
+      />
+    </div>
+  );
+}

package/src/client/main.jsx

@@ -0,0 +1,24 @@
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+
+async function main() {
+  const [metaRes, dataRes] = await Promise.all([
+    fetch('/meta'),
+    fetch('/data'),
+  ]);
+  const meta = await metaRes.json();
+  const scene = await dataRes.json();
+
+  const name = meta.fileName.replace(/\.excalidraw$/, '');
+  document.title = `${name} - excalidraw-edit`;
+
+  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+  const systemTheme = prefersDark ? 'dark' : 'light';
+  const theme =
+    meta.theme !== 'system' ? meta.theme : scene.appState?.theme || systemTheme;
+
+  const root = createRoot(document.getElementById('app'));
+  root.render(<App scene={scene} theme={theme} />);
+}
+
+main().catch(console.error);

package/src/const.js

@@ -0,0 +1,28 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const VERSION = '0.1.0';
+export const PUBLIC_DIR = join(__dirname, 'public');
+export const INDEX_HTML_PATH = join(PUBLIC_DIR, 'index.html');
+
+export const EMPTY_SCENE = {
+  type: 'excalidraw',
+  version: 2,
+  elements: [],
+  appState: {},
+  files: {},
+};
+
+export const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+  '.png': 'image/png',
+};

package/src/filesystem.js

@@ -0,0 +1,23 @@
+import { writeFile, access } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { EMPTY_SCENE } from './const.js';
+
+export function addExtension(filePath) {
+  if (extname(filePath) === '') {
+    return filePath + '.excalidraw';
+  }
+  return filePath;
+}
+
+export async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function createScene(filePath) {
+  await writeFile(filePath, JSON.stringify(EMPTY_SCENE, null, 2));
+}