🎇Features  •  🏠Installation  •  🚜Usage  •  💻CLI  •  ✅Requirements  •  🚸Gotchas

Export Excalidraw diagrams to SVG or PNG using a headless browser, using the exact same export process as Excalidraw itself

---

	Status	Stable	Unstable
Master
Develop

• ❔ What: Uses 🎭 playwright to run a headless firefox browser to export Excalidraw diagrams to svg/png files. Using a browser bypasses certain bugs that happen with other projects that attempt to export by emulating the DOM (without a browser).
• Why:
  • To allow automated export of Excalidraw diagrams to svg/png files via the command line.
  • Currently, Excalidraw can only be exported by a human clicking on the "Export image" button.
  • Addresses/mitigates excalidraw/excalidraw#1261 excalidraw CLI #1261 which is an open feature request on the Excalidraw project.
  • Addresses/mitigates JRJurman/excalidraw-to-svg#6 Error rendering edge-labels. #6.
  • Addresses/mitigates Timmmm/excalidraw_export#6 Error rendering edge-labels. #6.
• 🤝 Related Projects
  • ⭐⭐⭐⭐⭐ JRJurman/excalidraw-to-svg uses jsdom to simulate the DOM, then runs Excalidraw+react in nodejs, loads the diagram files and exports them.
    • Comparison: JRJurman/excalidraw-to-svg is faster and more efficient than excalidraw-brute-export-cli. However, this is a "brute force" approach to exporting Excalidraw diagrams, and in some ways might be more reliable.
  • ⭐⭐⭐⭐⭐ Timmmm/excalidraw_export similar to JRJurman/excalidraw-to-svg but simplifies the code and also embeds SVG fonts.
    • Comparison: Timmmm/excalidraw_export is faster and more efficient than excalidraw-brute-export-cli. However, this is a "brute force" approach to exporting Excalidraw diagrams, and in some ways might be more reliable.

🎇 Features

• Export Excalidraw diagrams to SVG or PNG using a headless browser, using the exact same export process as Excalidraw itself.
• Can point to any excalidraw instance.
• Ability to change timeouts.
• Debugging: Ability to take screenshots at each step.

🏠 Installation

# Install globally from npm registry.
npm install -g excalidraw-brute-export-cli

# Or install globally, direct from GitHub:
npm install -g https://github.com/realazthat/excalidraw-brute-export-cli.git#v0.3.0

# Might prompt for root.
npx playwright install-deps
npx playwright install firefox

🚜 Usage

Example:

And the resulting image (svg):

💻 Command Line Options

✅ Requirements

• Supported Node versions: >=18.0.0 <19.0.0 || >=20.0.0 <21.0.0 || >=21.0.0 <22.0.0 || >=22.0.0 <23.0.0 (See ./package.json). These versions were chosen from current supported and upcoming versions of node, from Node.js: Previous Releases.
• Tested Node versions on GitHub Actions: ["18.20.2","20.12.1","21.7.3","22.0.0"].

Tested on

• WSL2 Ubuntu 20.04, Node v20.12.1 .

🚸 Gotchas and Limitations

• Sometimes playwright times out.
  • Mitigations:
    • Increase the timeout with the --timeout option.
    • Run the command again.
  • If this is a persistent problem, please open an issue here and upload the diagram (zip it if necessary).

🤏 Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

🔑 License

This project is licensed under the MIT License - see the ./LICENSE.md file for details.

🫡 Contributions

Development environment: Linux-like

• For running pre.sh (Linux-like environment).
  • Requires nodejs (for act).
  • Requires Go (to run act).
  • docker (for act).
• For running pre.sh (Linux-like environment).
  • Requires pyenv, or an exact matching version of python as in scripts/.python-version (which is currently 3.8.0 ).
  • jq, (installation) required for yq, which is itself required for our ./README.md generation, which uses tomlq (from the yq package) to include version strings from ./scripts/pyproject.toml.
  • bash, grep, awk, sed xxd, git, xxhash, rsync (for tests/workflows).
  • Requires nodejs (for act).
  • Requires Go (to run act).
  • docker (for act).

Commit Process

1. (Optionally) Fork the develop branch.
2. If the .github/demo.gif will change, run bash ./scripts/generate-animation.sh, this will generate a new .github/demo.gif.
   • Sanity-check the animation visually!
   • Unfortunately, every run will make a unique gif, please don't stage this file unless it changes due to some feature change or somesuch.
3. Stage your files: e.g git add path/to/file.py.
4. bash ./scripts/pre.sh, this will format, lint, and test the code.
5. git status check if anything changed (generated README.md for example), if so, git add the changes, and go back to the previous step.
6. git commit -m "...".
7. Make a PR to develop (or push to develop if you have the rights).

🔄🚀 Release Process

These instructions are for maintainers of the project.

1. In the develop branch, run bash ./scripts/pre.sh to ensure everything is in order.
2. In the develop branch, bump the version in package.json, following semantic versioning principles. Run bash ./scripts/pre.sh to ensure everything is in order.
   • If anything got generated (e.g README or terminal output images), you will have to stage those.
3. In the develop branch, commit these changes with a message like "Prepare release X.Y.Z". (See the contributions section above).
4. Merge the develop branch into the master branch: git checkout master && git merge develop --no-ff.
5. master branch: Tag the release: Create a git tag for the release with git tag -a vX.Y.Z -m "Version X.Y.Z".
6. Publish to NPM: Publish the release to NPM with bash ./scripts/deploy-to-npm.sh.
7. Push to GitHub: Push the commit and tags to GitHub with git push && git push --tags.
8. The --no-ff option adds a commit to the master branch for the merge, so refork the develop branch from the master branch: git checkout develop && git merge master.
9. Push the develop branch to GitHub: git push origin develop.