excalidraw-vscode makes a drawing a file you can commit next to the code

A file extension is the entire entry point

The README explains the whole interaction in one sentence. This extension integrates Excalidraw into VS Code, and to use it you create an empty file with a .excalidraw, .excalidraw.json, .excalidraw.svg or .excalidraw.png extension and open it in Visual Studio Code.

There is no command palette entry to open a canvas, no new file wizard for a drawing. You create a file with the right name and the editor appears. That is a deliberate design, and the reason is visible in the package manifest, where the activation event is a workspace contains pattern rather than an onCommand trigger.

The consequence is that the extension wakes up when a workspace contains a drawing, not when you ask for one. A repository with an architecture diagram in it will offer to open that diagram, and a repository without one will leave the extension dormant.

The commands that do exist are registered under the Excalidraw category and are the small set of editor affordances: excalidraw.updateTheme for the colour theme, excalidraw.newFile and excalidraw.newSceneFile for creating drawings, excalidraw.preventDefault, and excalidraw.showSource for switching to the raw scene.

The package is published to the marketplace as pomdtr.excalidraw-editor, the engine requirement is VS Code 1.63 or newer, and the extension is categorised under Visualization. The source tree is TypeScript, with the extension entry at dist/extension.js and a webview/ directory for the editor itself.

The editor is a webview, which is why it runs in the browser too

The package manifest marks the extension as browser based, and the README points at a consequence of that: you can install the extension in github.dev or vscode.dev, and the claim is that editing an Excalidraw schema stored in a GitHub repository has never been easier.

That is the feature that distinguishes this extension from a desktop only drawing tool. github.dev and vscode.dev are the browser based versions of VS Code that open a repository from GitHub, so a team can open a repository, find the diagram, and edit it without installing anything locally. The diagram lives in the repository as a file, and the review flow is the one you already use for code.

The editor itself runs in a webview, and the theme handling is a good illustration of how that choice shows up in the interface. There are three theme options, light as the default, dark, and auto, which syncs with the VS Code theme.

The contribution note explains what that means in practice, and it is a revealing sentence. The only goal of the extension is to integrate Excalidraw into the Visual Studio Code ecosystem, and users should be able to use both the website and the extension with a minimum of friction. There are exceptions, and it names one: the switch theme icon was moved to the Visual Studio Code editor toolbar to allow better integration.

So the extension is not a fork of the Excalidraw application with a VS Code skin. It is the Excalidraw application running in an editor host, with the host's own toolbar used where the integration is better.

A drawing that is also a PNG or an SVG

The feature that makes this more than a canvas is the image format, and the README describes it as Edit Images.

The source of the drawing can be embedded directly in a PNG or SVG image. You create a new .excalidraw.png or .excalidraw.svg file and the drawing is editable, and you can switch between the text and image formats by updating the file extension, for example by renaming a .excalidraw file to .excalidraw.png.

That is a neat trick, and the reason it works is that a PNG can carry arbitrary metadata and an SVG can carry elements a reader can ignore. The scene travels with the image, and the image still opens in every other tool that knows the format.

The export defaults are controlled by the excalidraw.image setting.

{
  "excalidraw.image": {
    "exportScale": 1,
    "exportWithBackground": true,
    "exportWithDarkMode": false
  }
}

The three options are the scale factor of the export, whether the exported image carries an opaque background, and whether a dark mode variant is written alongside the light one.

Two more capabilities come from the same webview. You can import a public library from libraries.excalidraw.com, the community catalogue, and you can switch between the editor and the source, whether text or image, using a dedicated toolbar button. The second of those is the one that matters for a repository, because the source view is how you review what actually changed in a diagram.

Editor associations, and the honest limit on SVG editing

By default the extension only handles the three drawing extensions, and the README explains how to widen that.

Adding this to your VS Code settings.json associates additional file extensions with the Excalidraw editor.

{
  "workbench.editorAssociations": {
    "*.svg": "editor.excalidraw"
  }
}

The next sentence is the important one, and the README states it without hedging. You won't be able to edit arbitrary SVG files though, only those that have been created with Excalidraw or with this extension.

That is a sensible boundary, since the extension expects to find an Excalidraw scene inside the file, but it is worth understanding before you map every SVG in the repository to the editor, because the failure mode is a file that opens in a drawing editor and cannot be edited as a drawing.

There is a second, more unusual limitation in the same area. The example files in the repository show the range of formats in practice, with examples/test.excalidraw, examples/test.excalidraw.png, examples/test.excalidraw.svg, examples/test2.excalidraw, a library.excalidrawlib and a demo.md, so the extension is exercised against every format it claims to handle.

Workspace libraries and the language setting

Two settings are worth knowing about before you start sharing diagrams with a team.

The first is the library. If you want to use a workspace specific library and share it with other contributors, you set the excalidraw.workspaceLibraryPath in the workspace settings file at .vscode/settings.json.

{
  "excalidraw.workspaceLibraryPath": "path/to/library.excalidrawlib"
}

The path is relative to the workspace root, and absolute paths are also supported, but those are specific to your device. That distinction is the whole point of the setting: a relative path travels with the repository, so a shape library shared by the team is the same for everyone, while an absolute path points at one machine.

The second is the language. By default the extension uses the Visual Studio Code Display Language to decide which language to use for text in the canvas, and you can override it with the excalidraw.language setting.

{
  "excalidraw.language": "fr-FR"
}

The project also carries a note about where to report problems, and it is a division of labour rather than a redirect. Only bug reports and feature requests specific to the VS Code integration should go to the extension repository, and anything to do with Excalidraw itself should be reported directly to the Excalidraw project. The extension repository is not the place for canvas bugs.

A contribution rule that forbids divergence

The Note for Contributors section is the most unusual thing in the README, and it is a policy rather than a technical detail.

The extension's only goal is to integrate Excalidraw into the Visual Studio Code ecosystem. Users should be able to use both the website and the extension with a minimum of friction, and as a result contributions that significantly modify the user experience compared to the Excalidraw website will not be accepted.

The exception clause names a concrete case, the switch theme icon being moved to the Visual Studio Code editor toolbar for better integration, and it points at the discussions page for anything unclear.

For an adopter this matters more than it looks. An extension that tracks the upstream application and refuses to diverge is one whose behaviour will not surprise you in six months, because the drawing you get in VS Code is the drawing you get on the web. The trade is that you cannot make the embedded editor do something the site cannot do, and if your team needs a different canvas behaviour, this is the wrong place to fight that battle.

The repository structure backs the integration story up. There is a webview/ directory for the editor surface, src/ for the extension host code, assets/ for the logo and other resources, and medias/ holding the screenshots and the animated demonstrations the README embeds, including the theme switching, the image editing and the library import sequences. There is also a README_NEXT.md at the root, which suggests the README is being reorganised, and a CHANGELOG.md.

Where the extension is the wrong tool

Three situations rule it out.

The first is a team that needs to edit existing SVG artwork. The extension only opens files that contain an Excalidraw scene, so any diagram produced by another tool, and any exported asset, is out of reach. Mapping every SVG in a repository to the editor makes the confusion worse rather than better.

The second is a team that wants a different canvas. The contribution rule means the embedded editor deliberately tracks the web application, so any feature request that changes the drawing experience has to be solved in the Excalidraw project itself, and this extension will not carry it.

The third is a workflow that is not repository based. A drawing in a repository is a first class artefact that can be diffed and reviewed, which is the point, but if your diagrams live in a wiki, a design tool or a slide deck, the browser version of Excalidraw and the export options already cover that case without an editor plugin.

For the case it was built for, a team that keeps its diagrams next to the code, the extension removes the friction of leaving the editor to draw something and coming back to commit it.

Editorial conclusion

excalidraw-vscode fits a team that keeps architecture diagrams in the same repository as the code, since a drawing becomes an ordinary file you can diff, review and commit, and the same extension works in the browser based github.dev and vscode.dev. It is the wrong choice for anyone who needs to edit arbitrary SVG files, because the extension only handles drawings it recognises, and it is the wrong choice for a team that wants the editor to differ from the web version, since the contribution rules explicitly forbid that. Before adopting it, check which extension activates on your file naming, since the activation pattern covers .excalidraw, .excalidraw.svg and .excalidraw.png, and decide whether the image formats are worth enabling given the caveat in the README.

Frequently asked questions

Official sources

1. excalidraw/excalidraw-vscode on GitHub
2. License: MIT
3. Project website
4. README
5. Releases