CodeVetter · Repo Unpack · Extension points
excalidraw/excalidraw
New editor commands are actions registered through register() and ActionManager, or at runtime via the imperative registerAction. Hosts extend rendering and behavior through Excalidraw props (UI slots, embeddables, tools, initial data) rather than forks. Persistence of libraries is an adapter interface. AI diagram-to-code is a setPlugins hook. Locale files and the library URL allowlist are data extension points.
- register(action) in packages/excalidraw/actions/register.ts appends to a module-level actions array and returns the action. Action files such as actionDeleteSelected.tsx call it at export time. App.tsx imports those modules for their side effects, then actionManager.registerAll(actions) plus undo/redo. The public API also exposes api.registerAction so hosts can add actions after mount.
- Action objects carry name (ActionName union), perform, keyTest, keyPriority, PanelComponent, trackEvent, and an optional navigation flag. Adding a command requires extending the ActionName union in actions/types.ts or TypeScript will reject the register call. Key collisions are not merged: handleKeyDown warns and cancels when more than one keyTest matches.
- Host integration props on Excalidraw include onChange, onIncrement, onPointerDown/Up, onPaste, onDuplicate, onLibraryChange, onLinkOpen, onScrollChange, onUserFollow, renderTopLeftUI, renderTopRightUI, renderCustomStats, renderEmbeddable, validateEmbeddable, renderScrollbars, initialData, UIOptions, activeTool, interaction, and aiEnabled. aiEnabled defaults to on unless passed false.
- interaction and ui config objects are compared semantically inside areEqual so hosts can inline them. Supported interaction.enabled keys include links, embeds, interactiveContent, navigation, browserZoom, and tools.laser / tools.custom. When interaction is false or a partial object, isInteractionEnabled returns false and the editor forces viewModeEnabled.
- Custom tools use activeTool.type === 'custom' (plus customType in the memo comparator). The pointer-down branch only applies the cursor; the host is expected to subscribe through onPointerDown. props.activeTool cannot force the image tool — the constructor console.warns and ignores it.
- LibraryPersistenceAdapter requires load({source}) and save(libraryData). The editor also has LibraryMigrationAdapter for one-shot legacy reads. useHandleLibrary and parseLibraryTokensFromUrl are public exports for hosts that supply library tokens on the URL.
- DiagramToCodePlugin is the AI extension slot: it calls app.setPlugins({ diagramToCode: { generate } }) in a layout effect. The package does not implement the network call; excalidraw-app/components/AI.tsx supplies generate. TTD chat storage is a separate adapter (TTDIndexedDBAdapter) rather than this plugin map.
- Imperative ExcalidrawImperativeAPI methods created in createExcalidrawAPI include updateScene, applyDeltas, mutateElement, updateLibrary, addFiles, resetScene, setViewport, setElementRenderOverrides, setActiveTool, toggleSidebar, updateFrameRendering, onChange, onIncrement, onPointerDown, onPointerUp, onScrollChange, onUserFollow, onStateChange, and onEvent. history on the API currently only exposes clear.
- CaptureUpdateAction is the extension contract for programmatic scene writes. IMMEDIATELY pushes undo, NEVER is required for remote or init updates, EVENTUALLY batches multi-step async edits. It is re-exported from the package entry so hosts can pass it to updateScene.
- Feature flags are a localStorage map under excalidraw-feature-flags, read by getFeatureFlag and written by setFeatureFlag. The only flag today is COMPLEX_BINDINGS, default false. Pointer-up consults it to decide whether to reset delayed bind mode. Sentry also calls getFeatureFlag and enables featureFlagsIntegration.
- New locales are a data plug-in: add packages/excalidraw/locales/<code>.json (Crowdin writes these from en.json) and an entry in the languages array in i18n.ts, including rtl when needed. Vite already chunks every locale file except en.json and percentages.json.
- WorkerPool.create(workerUrl) is the hook for short-lived module workers (font subsetting). Callers must pass a URL that is not the main bundle. Idle workers are terminated after ttl milliseconds, default 1000, and the pool does not cap concurrency — the comment says the caller must.
- UI composition components are exported for hosts: Sidebar, Button, Footer, MainMenu, WelcomeScreen, LiveCollaborationTrigger, Stats, plus useExcalidrawAPI and ExcalidrawAPIProvider so the API can be read outside the editor tree. Tunnels for slot rendering live in packages/excalidraw/context/tunnels.ts.
- Examples are the supported embed templates: examples/with-nextjs (App Router page plus a Pages Router route, client-only dynamic import) and examples/with-script-in-browser (Vite, ExampleApp, CustomFooter). yarn start:example builds packages then starts the script example. dev-docs is a separate Docusaurus site and is not a yarn workspace of the root package.json.