Skip to content
Localidraw Localidraw Localidraw

Getting started

You need Node.js 22 or later. Nothing else: Localidraw has no runtime dependencies, and the editor and its fonts are in the package.

Terminal window
npx localidraw            # the current folder
npx localidraw ~/notes    # or any folder

Then open http://localhost:3729. It prints the address, the folder and how many canvases it found, and what it listens on:

Localidraw 0.4.0: http://localhost:3729/
  /Users/you/notes (4 canvases)
  listening on 127.0.0.1:3729 (this machine only)
  answering to localhost
  watching for changes by file events

To keep it around rather than download it each time, install it globally:

Terminal window
npm install -g localidraw
localidraw ~/notes

Options

Section titled “Options”
localidraw [folder] [--port <n>] [--open] [--host <addr> --allowed-host <name>] [--poll [ms]]
Option What it does
folder Where the canvases are. The default is the current folder. node_modules and dot-folders (.git and the like) are skipped.
--port <n> The port. The default is 3729, which spells “DRAW” on a phone keypad, or $PORT if that’s set.
--open Opens it in your browser.
-v, --version Prints the version.
-h, --help Prints the options.

These are for hosting it, on a server or in Docker, behind a reverse proxy:

Option What it does
--host <addr> The address to listen on. The default is 127.0.0.1, or $LOCALIDRAW_HOST if that’s set. Anything that isn’t loopback (0.0.0.0, a LAN address) needs at least one --allowed-host, or it won’t start.
--allowed-host <name> A host name to answer to besides localhost, such as draw.example.com: the name alone, without https:// or a port. Repeat it for more, or set $LOCALIDRAW_ALLOWED_HOSTS to a comma-separated list. Requests for any other name are refused.
--poll [ms] Finds changes by checking the files every ms milliseconds (2000 if you leave it out) instead of by file events. For a folder on a network mount (NFS, SMB) or a Docker Desktop bind mount on macOS, where the writes send no events. $LOCALIDRAW_POLL takes the milliseconds, or true.

A flag wins over its environment variable, and --allowed-host flags replace $LOCALIDRAW_ALLOWED_HOSTS rather than adding to it.

If the port is taken, it says so and stops; run it with --port and another number. One Localidraw per folder: two servers on the same folder would each save without knowing about the other’s page.

What it remembers, and where

Section titled “What it remembers, and where”
  • The drawings are the files. Nothing else is written into them: no viewport, no theme, no sidebar state.
  • The browser keeps your preferences: the viewport per canvas, the theme and whether the sidebar is docked, in localStorage. They follow the browser, not the folder. So does Excalidraw’s Library, unless the folder has a library.excalidrawlib to share it in.
  • The open canvas is in the URL, as ?canvas=path/in/folder.excalidraw, so you can bookmark one.

Safety

Section titled “Safety”

Localidraw listens on 127.0.0.1, so nothing else on your network can reach it. It refuses requests whose Host or Origin isn’t localhost, so a web page you visit can’t read or write your canvases through it. Hosting it is something you turn on, by name: see Self-hosting.

It only touches .excalidraw files inside the folder you gave it, outside dot-folders and node_modules, and the folder’s library.excalidrawlib if you made one. It creates, saves, renames and moves canvases, never over another file, and never deletes one: deleting from the sidebar moves the file into .localidraw/trash/ in the folder.

Next

Section titled “Next”