From index.tsx to <App>: how the editor gets mounted and configured

Chapter III

From index.tsx to <App>: how the editor gets mounted and configured

Before App.handleCanvasPointerDown can ever run, three layers have to boot in order: excalidraw-app/index.tsx (a Vite entry that just mounts the excalidraw.com website), packages/excalidraw/index.tsx (the public <Excalidraw> component every npm consumer imports), and the providers <Excalidraw> mounts above App (an isolated jotai store plus i18n loading). This module traces that boot sequence and the props/UIOptions normalization that happens along the way, and draws the line between 'the library' (packages/excalidraw) and 'the app built on it' (excalidraw-app) that recurs throughout the codebase.

walkthrough

excalidraw-app/index.tsx: the whole website, in 17 lines

excalidraw-app/index.tsx · lines 1–17

lines 1–7

ExcalidrawApp here is imported from ./App — this repo's own excalidraw-app/App.tsx, not the App class you traced in the drawing module (that one lives at packages/excalidraw/components/App.tsx). Same word, two different components at two different layers of the stack; keeping them straight is the whole point of this module.

lines 9–12

registerSW() registers the PWA service worker for offline support — a hosting concern of excalidraw.com specifically. Nothing under packages/excalidraw needs or knows about it.

lines 13–17

Standard React 18 bootstrapping: createRoot + render instantiate the excalidraw-app component tree. This is the entire 'app' in the sense of a Vite project — everything else, including the editor, is pulled in as a dependency starting here.

1import { StrictMode } from "react";2import { createRoot } from "react-dom/client";3import { registerSW } from "virtual:pwa-register";45import "../excalidraw-app/sentry";67import ExcalidrawApp from "./App";89window.__EXCALIDRAW_SHA__ = import.meta.env.VITE_APP_GIT_SHA;10const rootElement = document.getElementById("root")!;11const root = createRoot(rootElement);12registerSW();13root.render(14  <StrictMode>15    <ExcalidrawApp />16  </StrictMode>,17);

step 1 of 3

walkthrough

ExcalidrawBase's return: providers, then App

packages/excalidraw/index.tsx · lines 185–236

lines 185–186

EditorJotaiProvider wraps everything below in editorJotaiStore — a jotai store built through jotai-scope's createIsolation(), so this editor instance's UI-state atoms are isolated from any jotai usage on the host page and from any other <Excalidraw> instance mounted alongside it.

line 187

InitializeApp only needs langCode and theme, not the full props object — it has one job (load the right language pack, show a loading screen meanwhile) and stays decoupled from everything else App is configured with.

lines 188–230

The <App> element receives the already-normalized UIOptions and normalizedImageOptions, plus handleExcalidrawAPI (a stable callback that fans a single API instance out to both the internal ExcalidrawAPISetContext setter and the caller's onExcalidrawAPI) and defaulted primitives like aiEnabled={aiEnabled !== false}. App's constructor never has to apply a single one of these defaults itself.

lines 231–236

{children} is the slot a caller's own JSX (passed as <Excalidraw>...</Excalidraw> children) lands in, still nested inside App's own context providers, before the three wrapper tags unwind and ExcalidrawBase's render finishes.

185  return (186    <EditorJotaiProvider store={editorJotaiStore}>187      <InitializeApp langCode={langCode} theme={theme}>188        <App189          onExport={onExport}190          onChange={onChange}191          onThemeChange={onThemeChange}192          onIncrement={onIncrement}193          initialData={initialData}194          initialState={initialState}195          onExcalidrawAPI={handleExcalidrawAPI}196          onMount={onMount}197          onUnmount={onUnmount}198          onInitialize={onInitialize}199          isCollaborating={isCollaborating}200          onPointerUpdate={onPointerUpdate}201          renderTopLeftUI={renderTopLeftUI}202          renderTopRightUI={renderTopRightUI}203          langCode={langCode}204          viewModeEnabled={viewModeEnabled}205          zenModeEnabled={zenModeEnabled}206          gridModeEnabled={gridModeEnabled}207          libraryReturnUrl={libraryReturnUrl}208          theme={theme}209          name={name}210          renderCustomStats={renderCustomStats}211          UIOptions={UIOptions}212          onPaste={onPaste}213          detectScroll={detectScroll}214          handleKeyboardGlobally={handleKeyboardGlobally}215          onLibraryChange={onLibraryChange}216          autoFocus={autoFocus}217          generateIdForFile={generateIdForFile}218          onLinkOpen={onLinkOpen}219          generateLinkForSelection={generateLinkForSelection}220          onPointerDown={onPointerDown}221          onPointerUp={onPointerUp}222          onScrollChange={onScrollChange}223          onDuplicate={onDuplicate}224          validateEmbeddable={validateEmbeddable}225          renderEmbeddable={renderEmbeddable}226          aiEnabled={aiEnabled !== false}227          showDeprecatedFonts={showDeprecatedFonts}228          renderScrollbars={renderScrollbars}229          imageOptions={normalizedImageOptions}230        >231          {children}232        </App>233      </InitializeApp>234    </EditorJotaiProvider>235  );236};

step 1 of 4

Why

UI-state hooks only work because a provider sits above App — Components like Sidebar.tsx call useSetAtom (from editor-jotai.ts, backed by jotai's Context API) to read or write editor UI state, and App itself exposes an ExcalidrawAPIContext.Provider once mounted so hooks like useExcalidrawAPI can resolve. Both depend on ancestors ExcalidrawBase already mounted: EditorJotaiProvider wraps everything above App in the tree, before the App class even runs, sets its own context that ExcalidrawAPIContext-based hooks read. Render App (or any of these hooks) outside that tree — e.g. in a hand-rolled test — and useSetAtom throws or useExcalidrawAPI silently returns null; the store or context it expects simply isn't there.

packages/excalidraw/editor-jotai.ts · EditorJotaiProvider :14–18packages/excalidraw/components/Sidebar/Sidebar.tsx · useSetAtom :21–21packages/excalidraw/components/App.tsx · ExcalidrawAPIContext :583–585

Connects

packages/excalidraw doesn't know excalidraw.com exists — packages/excalidraw is imported as @excalidraw/excalidraw even from inside this monorepo (see excalidraw-app/App.tsx's own imports) — it's built and versioned as a standalone package. Real-time collaboration (the Collab class, CollabError, the whole 'is-collaborating' UI) is defined only under excalidraw-app/collab and wired up entirely by excalidraw-app/App.tsx; <Excalidraw> just accepts generic props like isCollaborating and onPointerUpdate and forwards them into App without any idea what collaboration means. This is the same boundary you'll hit repeatedly: if a feature needs to reach outside the editor (auth, a backend, analytics), it almost certainly belongs in excalidraw-app, not packages/excalidraw.

excalidraw-app/App.tsx · Collab :96–100excalidraw-app/App.tsx · isCollaborating :910–915

checkpoint

Check your understanding

Answered in place — nothing is graded, everything is explained. 0 / 3 passed

Which component is directly responsible for delaying render (showing a loading screen) until the requested language pack has loaded, before the <App> element beneath it appears?

excalidraw-app's <Excalidraw> call only sets UIOptions.canvasActions.toggleTheme and .export. Why does App still see values for changeViewBackgroundColor, clearCanvas, loadScene, etc.?

Where is the real-time collaboration (Collab) code defined?