The practical goal is simple: keep the current drawing visible, explain why the next document could not open, and let the user fix the missing asset.

This guide uses React and the public API in fabricjs-document-engine 1.0.2, checked on October 1, 2026. The native Fabric.js behavior discussed below is version-specific, with Fabric.js 7.4.0 as the concrete example. The engine supports Fabric.js 6 and 7. The quick-start guide covers installation and engine setup.

Does a failed image always leave Fabric.js partially loaded?

No. A failed image is not a universal explanation for every blank or incomplete canvas, and Fabric.js versions do not all handle failed object creation identically.

Fabric.js 7.4.0 creates objects before loadFromJSON clears and replaces the canvas. Its object-enlivening code collects failed object results and calls the reviver with the error. If the reviver supplies no replacement and throws no error, a failed object can be omitted while successful objects are installed.

That can produce a document which looks partly restored: text and shapes appear, but an image is gone. By contrast, Fabric.js 6 uses a different object-enlivening failure path; do not assume a Fabric 7 example describes every Fabric 6 failure.

The relevant primary sources are Fabric.js's loadFromJSON API, canvas implementation, and object-enlivening implementation. These two source links are pinned to the commit recorded for Fabric.js 7.4.0. Compare that implementation with the version installed in your app.

The document engine adds two relevant checks:

• Check external assets. Fail with a missing-image report before invoking the canvas loader.

• Refuse dropped objects. Use a strict reviver when Fabric.js creates document objects.

The package's Fabric adapter source shows the strict reviver. Its asset preparation source shows where missing-image checks run.

Why can a valid canvas JSON file still fail to reopen?

Valid JSON describes the document. It does not guarantee that every dependency still exists.

An image object may contain a src pointing to a deleted file, an expired signed URL, an unavailable host, or a blob: URL from a previous browser session. The JSON can parse successfully while the browser cannot load that image.

A missing image and a tainted canvas need different fixes. A missing image cannot be loaded. A tainted canvas may display an image while the browser blocks reading the canvas pixels for export.

The package's images and fonts guide separates asset loading, font fallback, and CORS/export problems. The troubleshooting guide covers related editor symptoms.

Why does clearing the canvas before loading make failures worse?

This code discards the current drawing before the next document has opened:

// Fragile app code: the old drawing is removed before the load succeeds.
canvas.clear();
await canvas.loadFromJSON(savedJson);
canvas.requestRenderAll();

If loading fails, the app has already removed the old objects. Catching the error afterward does not reconstruct those objects.

Do not clear the canvas before asking the engine to open a document. Let the engine validate and prepare the incoming content first:

await engine.loadDocument(savedDocument);

If a storage adapter is configured, open a saved record by its document ID:

await engine.load("design-42");

loadDocument accepts a document value. load(id) first asks the storage adapter for that value. Both use the engine's document-loading path.

See the save and load guide and document engine API for the method signatures.

What happens before the engine mutates the canvas content?

The engine prepares the incoming document before passing it to Fabric.js. With image checks enabled, the loading path does the following:

1. Check the input. Apply content limits, migrate supported formats, and validate the document.

2. Check object types. Refuse classes that have not been registered.

3. Resolve asset URLs. Run an optional assets.resolveUrl handler.

4. Check dependencies. Check external images and font availability.

5. Try replacements. Run an optional assets.replaceMissingImage handler for missing images.

6. Reject missing images. Throw MISSING_ASSETS if unresolved images remain.

7. Load the content. Invoke Fabric.js with the engine's strict reviver.

For the MISSING_ASSETS failure in step 6, the canvas content has not been replaced. The error carries a list shaped like this:

error.missingAssets;
// [
//   { url: "/uploads/deleted-logo.png", objectIds: ["logo-image"] }
// ]

This guarantee is specific to failures detected before canvas loading. It is not a claim that every possible exception, custom-class side effect, or later Fabric.js failure can be rolled back. Embedded data: images are not fetched by the external-image preflight; malformed embedded data can fail during object creation instead.

Keep image checks enabled when you want this preflight behavior. Setting assets.checkImages: false skips the external-image check and removes the early missing-asset report.

The exact order is visible in the engine loading source and the asset preparation source. The images and fonts documentation explains the public behavior.

How do you prove that a failed image leaves the current drawing intact?

Use a controlled missing-image document and compare the canvas objects before and after the rejected load. Serve the app locally and ensure the test image address returns a real failure; a development server that substitutes a valid image would defeat the test.

import { Canvas, Textbox } from "fabric";
import {
  createDocumentEngine,
  isDocumentEngineError,
  type FabricDocument,
} from "fabricjs-document-engine";

export async function demonstrateMissingImage(element: HTMLCanvasElement) {
  const canvas = new Canvas(element, { width: 800, height: 500 });
  // No storage is configured in this isolated loading demonstration.
  const engine = createDocumentEngine({ canvas });
  canvas.add(new Textbox("Keep the current drawing", { left: 40, top: 40 }));

  const currentObjects = canvas.getObjects().slice();
  const timestamp = new Date().toISOString();
  const incoming: FabricDocument = {
    schemaVersion: 1,
    id: "broken-design",
    createdAt: timestamp,
    updatedAt: timestamp,
    revision: 1,
    canvas: { width: 800, height: 500 },
    objects: [{
      type: "Image",
      id: "logo-image",
      src: "/uploads/intentionally-missing-logo.png",
      width: 120,
      height: 120,
    }],
    metadata: {},
  };

  try {
    await engine.loadDocument(incoming);
    throw new Error("The test URL unexpectedly loaded.");
  } catch (error) {
    if (!isDocumentEngineError(error) || error.code !== "MISSING_ASSETS") {
      throw error;
    }
    const after = canvas.getObjects();
    if (after.length !== currentObjects.length ||
        after.some((object, index) => object !== currentObjects[index])) {
      throw new Error("The current drawing was changed.");
    }
    return { code: error.code, missingAssets: error.missingAssets };
  } finally {
    engine.destroy();
    await canvas.dispose();
  }
}

Use a dedicated canvas element for this helper. It creates and disposes its own canvas; do not pass the DOM element of an editor that already owns a Fabric.js instance.

The expected result is MISSING_ASSETS, the failed URL, and logo-image. The object-reference check confirms that the existing drawing survived the rejected load. The package repository contains a related browser test for missing images before canvas mutation.

This helper was run in Chromium against package 1.0.2 and Fabric.js 7.4.0. It returned MISSING_ASSETS with the expected URL and object ID, and the original canvas object references remained unchanged. A separate native Fabric.js load with one rectangle and one unavailable image restored the rectangle and omitted the image. The complete TypeScript examples in this article also passed type checking.

The example intentionally has no storage adapter so it tests image preflight directly. A persistent editor should also protect unsaved changes, as the React example below does.

How do you show the engine error in a React editor?

Catch the rejected operation and branch on the stable error code. Show missingAssets to the user instead of silently logging a generic failure.

Install the packages:

npm install fabric fabricjs-document-engine

This component is a complete local demonstration. It uses the built-in memory adapter, so saved records last only while that adapter remains in memory. Add text, save it, and try opening the broken document.

"use client";

import { Canvas, Textbox } from "fabric";
import {
  isDocumentEngineError,
  type DocumentEngineError,
  type FabricDocument,
} from "fabricjs-document-engine";
import { createMemoryStorage } from "fabricjs-document-engine/storage";
import {
  useDocumentEngine,
  useDocumentState,
} from "fabricjs-document-engine/react";
import { useEffect, useRef, useState } from "react";

const storage = createMemoryStorage();
const timestamp = new Date().toISOString();
const brokenDocument: FabricDocument = {
  schemaVersion: 1,
  id: "broken-design",
  createdAt: timestamp,
  updatedAt: timestamp,
  revision: 1,
  canvas: { width: 800, height: 500 },
  objects: [{
    type: "Image",
    id: "logo-image",
    src: "/uploads/intentionally-missing-logo.png",
    width: 120,
    height: 120,
  }],
  metadata: {},
};

export function SafeLoadEditor() {
  const elementRef = useRef<HTMLCanvasElement>(null);
  const [canvas, setCanvas] = useState<Canvas | null>(null);
  const [problem, setProblem] = useState<DocumentEngineError | null>(null);
  const [message, setMessage] = useState("");
  const [busy, setBusy] = useState(false);

  useEffect(() => {
    if (!elementRef.current) return;
    const created = new Canvas(elementRef.current, { width: 800, height: 500 });
    setCanvas(created);
    return () => { void created.dispose().catch(() => undefined); };
  }, []);

  const engine = useDocumentEngine(canvas, {
    storage,
    document: { id: "working-design" },
  });
  const state = useDocumentState(engine);

  async function run(action: () => Promise<unknown>, success: string) {
    setBusy(true);
    setProblem(null);
    setMessage("");
    try {
      await action();
      setMessage(success);
    } catch (error) {
      if (isDocumentEngineError(error)) {
        if (error.code === "LOAD_ABORTED") return;
        setProblem(error);
      } else {
        setMessage(error instanceof Error ? error.message : "Opening failed.");
      }
    } finally {
      setBusy(false);
    }
  }

  const disabled = !engine || busy || Boolean(state?.isSaving || state?.isLoading);

  return (
    <section>
      <button disabled={disabled} onClick={() => canvas?.add(
        new Textbox("Keep the current drawing", { left: 40, top: 40 })
      )}>Add text</button>
      <button disabled={disabled} onClick={() => {
        if (engine) void run(() => engine.save(), "Current drawing saved.");
      }}>Save current drawing</button>
      <button disabled={disabled} onClick={() => {
        if (engine) void run(
          () => engine.loadDocument(brokenDocument),
          "Document opened."
        );
      }}>Try opening the broken document</button>

      {problem?.code === "MISSING_ASSETS" ? (
        <div role="alert">
          <p>The document could not open. These images are unavailable:</p>
          <ul>
            {problem.missingAssets.map((asset) => (
              <li key={asset.url}>
                <code>{asset.url}</code>
                {" — Objects: "}{asset.objectIds.join(", ")}
              </li>
            ))}
          </ul>
          <p>Your current drawing is still visible.</p>
        </div>
      ) : problem?.code === "UNSAVED_CHANGES" ? (
        <p role="alert">Save the current drawing before opening another document.</p>
      ) : problem ? (
        <p role="alert">{problem.code}: {problem.message}</p>
      ) : null}

      <p role="status">{message}</p>
      <p aria-live="polite">{state?.saveStatus ?? "Preparing editor"}</p>
      <canvas ref={elementRef} aria-label="Drawing preserved after a failed load" />
    </section>
  );
}

Clicking Try opening the broken document before saving an edit should show UNSAVED_CHANGES. After saving, the same operation reaches image preflight and should show MISSING_ASSETS. The app never passes discardUnsavedChanges: true automatically.

For an API-backed editor, replace the memory adapter with your HTTP adapter and call engine.load(documentId) inside the same handler. The companion guide, Save Fabric.js Canvas JSON to an API and Open It by Document ID, includes the adapter and app-owned endpoint.

The React guide, React hooks reference, and error code reference document the hooks and error fields used here.

Should you catch errors or subscribe to load:error?

Use the operation's catch when the result belongs to a particular button, route, or document selection. Use load:error when a shared panel or logging system needs to observe engine loading failures.

import { useDocumentEvent } from "fabricjs-document-engine/react";

// Inside a React component that already has an engine.
useDocumentEvent(engine, "load:error", ({ error }) => {
  if (error.code === "LOAD_ABORTED") return;
  console.error("Document loading failed", error.code, error);
});

The event observes an error; it does not consume the promise rejection. Still handle the promise returned by engine.load() or engine.loadDocument(). If both paths show notifications, one failure can produce duplicate messages.

An unsaved-change guard can reject before the loading sequence starts. Catching the requested operation also covers that case. useDocumentState(engine) exposes loadError for failures tracked by the state store, but a persistent guard message should not depend only on that field.

The event payload is { error }, not the error directly. See the events API for the exact contract.

How do you repair a missing image without removing the object?

Use assets.replaceMissingImage when your app has a known replacement. The hook receives the missing URL and the object IDs that refer to it.

const engine = createDocumentEngine({
  canvas,
  storage,
  assets: {
    replaceMissingImage(image) {
      if (image.url === "/uploads/deleted-logo.png") {
        return "/assets/replacement-logo.png";
      }
      return null;
    },
  },
});

This is an engine-options fragment; canvas and storage are the instances already owned by your app, and createDocumentEngine is imported from the package.

The engine checks the replacement URL too. If the replacement is also unavailable, the load still fails. If the replacement works, loading can continue and the engine reports an IMAGE_REPLACED warning.

A replacement policy changes document content. Make that policy clear to the user. For client artwork, returning null and asking for a replacement may be preferable to inserting a generic placeholder.

Save deliberately after a repaired load if the new address should be retained. A successful load begins a saved session; do not assume the replacement alone has marked the document dirty or written a new record to your backend.

See the asset options guide and createDocumentEngine API. engine.replaceImage(oldUrl, newUrl) repairs images already present in the current canvas; it does not modify an incoming document that preflight rejected.

What if the image URL expires instead of disappearing?

Resolve the stored asset address into a currently accessible URL with assets.resolveUrl. Your app can use that handler to request a fresh signed URL from its backend before the engine checks and loads the image.

const assets = {
  async resolveUrl(url: string) {
    if (!url.startsWith("asset://")) return url;
    const assetId = url.slice("asset://".length);
    const response = await fetch(
      `/api/assets/${encodeURIComponent(assetId)}/url`
    );
    if (!response.ok) throw new Error("The asset address could not be resolved.");
    const result = (await response.json()) as { url: string };
    return result.url;
  },
};

The asset-resolution endpoint is app-owned backend code. The package does not implement asset permissions or signed-URL generation.

Also plan the return path when saving. The engine rewrites the incoming image address to the resolved URL; saving that content can persist the signed URL. Keep durable asset identity in app-managed data and normalize addresses in your storage layer if your API requires stable identifiers.

For tab-only blob: images, configure assets.upload while saving so reopening does not depend on the previous tab. Both hooks are described in the images and fonts guide.

Can you fix an image CORS failure from React alone?

The image host must permit the cross-origin request when the image is loaded with CORS enabled. Setting crossOrigin: "anonymous" in React or Fabric.js does not create permission on the remote server.

Check both the image request and response headers. For a canvas that displays correctly but cannot export, inspect whether the image was loaded in a way that tainted the canvas.

The engine's IMAGE_CROSS_ORIGIN warning helps identify risky image references. Export preflight can reject a raster export with EXPORT_BLOCKED; that is a different error from loading a document with MISSING_ASSETS.

Read the CORS guidance and export guide. The engine reports the problem; your app and image host control how the asset is served.

What should the editor do with each loading error?

Use error codes to decide what action to offer. Do not match error-message wording.

Missing fonts normally produce FONT_UNAVAILABLE warnings and fallback text. Set assets.requireFonts: true when the document must not open with fallback fonts; unavailable fonts then produce MISSING_FONTS.

The package's error code reference and custom object guide describe these cases.

Will awaiting loadFromJSON solve every loading problem?

Awaiting the load is necessary for code that depends on loaded objects. It does not make deleted images available or register a missing custom class.

For a direct Fabric.js load, a basic successful path is:

await canvas.loadFromJSON(savedJson);
canvas.requestRenderAll();

That fixes the timing of rendering after the promise settles. With Fabric.js versions that permit failed objects to be omitted, a fulfilled promise alone does not prove every expected object was restored.

When using the document engine, wait for its load method. The engine requests rendering after its successful load.

How do you keep an older load from replacing a newer document?

Use engine.load(id) for the complete storage-and-loading operation. The engine claims the load before reading storage, so a slower response for an older selection cannot replace a newer completed load. A superseded request rejects with LOAD_ABORTED.

If your app separately fetches JSON and then calls loadDocument, your app must also prevent older fetch responses from being submitted after newer ones. The engine cannot know that a later loadDocument call came from an earlier UI selection.

The loading API documents the entry points, and the engine source shows the storage-response guard. Fabric.js itself also warns about overlapping loads in its loadFromJSON reference.

Start with one deliberately missing image. Confirm that the old drawing stays visible, the error contains the image URL and object IDs, and the React UI explains the failure. Then test expired URLs, missing fonts, and overlapping document selections against your own storage. The npm package, quick start, and GitHub repository provide the source and further examples.

The package manages the document workflow around your existing Fabric.js canvas. Your app owns the API, authentication, database, and file storage. You can keep the toolbar and React components you already have.

This guide builds a React editor, a typed HTTP adapter, and an Express/PostgreSQL endpoint. The examples follow the public API in package 1.0.2, checked on October 1, 2026. The package supports Fabric.js 6 and 7. Start with the official quick-start guide if you have not created an engine before.

What should you save to reopen an editable Fabric.js canvas?

Save the document JSON. A PNG is useful for a thumbnail or download, but a PNG does not preserve independently editable text, shapes, groups, and object properties.

Fabric.js supplies serialization through canvas.toJSON() and canvas.toObject(). The document engine adds the information needed to identify, reopen, and save a document consistently:

Store the complete document body. Keeping only objects would remove the document ID, revision, and canvas dimensions that the rest of this example uses.

The document format reference describes the exact fields. The save and load guide explains how the engine serializes an existing canvas.

What is the storage adapter contract?

A basic DocumentStorage adapter has two required methods: one reads a document and one saves it. The engine does not prescribe a database, URL structure, or server framework.

import type { FabricDocument } from "fabricjs-document-engine";

// The public contract, shown here for reference.
interface DocumentStorage {
  loadDocument(id: string): Promise<unknown>;
  saveDocument(
    document: FabricDocument,
    context: {
      expectedRevision: number | null;
      signal: AbortSignal;
    }
  ): Promise<void | { revision?: number }>;
}

loadDocument returns unknown because storage is an external boundary. The engine checks the returned document before loading its content.

expectedRevision is the revision this editor last loaded or saved. A new document starts at revision 0. The outgoing document normally carries the next revision. If your server assigns the revision, return the accepted value as { revision }.

A value of null means the caller requested an overwrite. Pass the provided signal to the save request so the engine can abort the client request when the session changes. Request cancellation does not undo a write that the server has already committed.

These behaviors come from the storage API reference and the custom backend guide. Optional version-storage methods are outside this article's two-method adapter.

How do you connect the document engine to an HTTP API?

Install Fabric.js and the document engine in your React app:

npm install fabric fabricjs-document-engine

Create api-storage.ts. This adapter uses same-origin endpoints and your app's existing session cookie.

import {
  DocumentEngineError,
  type DocumentStorage,
} from "fabricjs-document-engine";

export const apiStorage: DocumentStorage = {
  async loadDocument(id) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(id)}`,
      { cache: "no-store" }
    );

    if (response.status === 404) {
      throw new DocumentEngineError(
        "DOCUMENT_NOT_FOUND",
        "This document was not found."
      );
    }
    if (!response.ok) {
      throw new Error(`Opening the document failed (${response.status}).`);
    }
    return response.json();
  },

  async saveDocument(document, { expectedRevision, signal }) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(document.id)}`,
      {
        method: "PUT",
        signal,
        headers: {
          "Content-Type": "application/json",
          "X-Expected-Revision":
            expectedRevision === null ? "*" : String(expectedRevision),
        },
        body: JSON.stringify(document),
      }
    );

    if (response.status === 409 || response.status === 412) {
      throw new DocumentEngineError(
        "SAVE_CONFLICT",
        "Another tab or device saved this document first."
      );
    }
    if ([400, 401, 403, 404, 413, 422].includes(response.status)) {
      throw Object.assign(
        new Error(`The server refused this save (${response.status}).`),
        { retryable: false }
      );
    }
    if (!response.ok) {
      throw new Error(`Saving the document failed (${response.status}).`);
    }

    const result = (await response.json()) as { revision?: unknown };
    if (!Number.isSafeInteger(result.revision) || Number(result.revision) < 1) {
      throw Object.assign(new Error("The API returned an invalid revision."), {
        retryable: false,
      });
    }
    return { revision: Number(result.revision) };
  },
};

X-Expected-Revision is an app-defined header. In this example, 0 means create a document and * means explicitly overwrite an existing one. These are conventions shared by this adapter and the endpoint below; the package does not require this header.

The official REST storage example uses If-Match. This article uses a custom header to keep its numeric revision protocol separate from standard HTTP entity-tag semantics.

Throwing SAVE_CONFLICT tells the engine to stop retrying that save. Setting retryable: false also stops retries for errors that require a change to the request or permissions. Other save failures can follow the engine's retry policy.

How do you save and open a document in React?

First, create the Fabric.js canvas after React mounts the canvas element. Put this helper in use-fabric-canvas.ts:

import { Canvas } from "fabric";
import { useEffect, useRef, useState } from "react";

export function useFabricCanvas() {
  const elementRef = useRef<HTMLCanvasElement>(null);
  const [canvas, setCanvas] = useState<Canvas | null>(null);

  useEffect(() => {
    if (!elementRef.current) return;
    const created = new Canvas(elementRef.current, {
      width: 800,
      height: 500,
    });
    setCanvas(created);
    return () => {
      void created.dispose().catch(() => undefined);
    };
  }, []);

  return { elementRef, canvas };
}

Then create document-editor.tsx:

"use client";

import { Rect } from "fabric";
import { isDocumentEngineError } from "fabricjs-document-engine";
import {
  useDocumentEngine,
  useDocumentState,
} from "fabricjs-document-engine/react";
import { useState } from "react";
import { apiStorage } from "./api-storage";
import { useFabricCanvas } from "./use-fabric-canvas";

export function DocumentEditor() {
  const { elementRef, canvas } = useFabricCanvas();
  const engine = useDocumentEngine(canvas, {
    storage: apiStorage,
    document: { id: "design-42", metadata: { title: "First design" } },
  });
  const state = useDocumentState(engine);
  const [documentId, setDocumentId] = useState("design-42");
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState("");

  async function run(action: () => Promise<unknown>, success: string) {
    setBusy(true);
    setMessage("");
    try {
      await action();
      setMessage(success);
    } catch (error) {
      if (isDocumentEngineError(error) && error.code === "LOAD_ABORTED") return;
      if (isDocumentEngineError(error) && error.code === "UNSAVED_CHANGES") {
        setMessage("Save your current changes before opening another document.");
      } else if (isDocumentEngineError(error) && error.code === "SAVE_CONFLICT") {
        setMessage("A newer revision exists. Review the conflict before continuing.");
      } else {
        setMessage(error instanceof Error ? error.message : "The request failed.");
      }
    } finally {
      setBusy(false);
    }
  }

  const disabled = !engine || busy || Boolean(state?.isSaving || state?.isLoading);

  return (
    <section>
      <label>
        Document ID
        <input
          value={documentId}
          onChange={(event) => setDocumentId(event.target.value)}
        />
      </label>
      <button
        disabled={disabled || !documentId.trim()}
        onClick={() => {
          if (engine) void run(
            () => engine.load(documentId.trim()),
            "Document opened."
          );
        }}
      >Open</button>
      <button
        disabled={disabled}
        onClick={() => canvas?.add(new Rect({
          left: 80, top: 60, width: 160, height: 100, fill: "#6366f1",
        }))}
      >Add rectangle</button>
      <button
        disabled={disabled}
        onClick={() => {
          if (engine) void run(() => engine.save(), "Save confirmed by the API.");
        }}
      >Save</button>
      <p aria-live="polite">
        Current document: {state?.documentId ?? "Preparing editor"}
        {state ? ` · Revision ${state.revision} · ${state.saveStatus}` : ""}
      </p>
      <p role="status">{message}</p>
      <canvas ref={elementRef} aria-label="Editable design canvas" />
    </section>
  );
}

Add a rectangle and click Save. The adapter sends the full document to PUT /api/documents/design-42. Refresh the page and click Open to retrieve it through GET /api/documents/design-42.

The text field chooses the document to open. Changing the text field does not rename the current document. A save always uses the engine's current document ID, shown below the buttons.

The example uses manual saves to make the request flow visible. To add autosave, pass autosave: true when creating the engine and continue displaying state.saveStatus and state.saveError. Options are read when the hook creates the engine; changing an options object later does not reconfigure that engine.

See the React guide, React hooks API, and autosave guide. In Next.js, mount Fabric.js through the client-only setup in the Next.js guide.

What does the app-owned HTTP endpoint look like?

The following backend code belongs to your application. It is an illustrative Express 5 and PostgreSQL implementation, not an endpoint supplied by fabricjs-document-engine.

Create a table through your app's database migration:

CREATE TABLE documents (
  owner_id text NOT NULL,
  id text NOT NULL,
  body jsonb NOT NULL,
  revision integer NOT NULL CHECK (revision >= 1),
  PRIMARY KEY (owner_id, id)
);

Use your existing authentication middleware as requireUser. That middleware must verify the session, reject unauthenticated requests, and set req.auth.userId. Neither the middleware nor DATABASE_URL comes from the package.

// server.ts — app-owned backend, using Express 5.
import express from "express";
import { Pool } from "pg";
import { validateDocument, type FabricDocument } from "fabricjs-document-engine";
import { requireUser } from "./app-auth"; // Your verified-session middleware.

declare global {
  namespace Express {
    interface Request { auth: { userId: string } }
  }
}

const app = express();
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

app.use(requireUser);
app.use(express.json({ limit: "2mb" })); // An app-chosen request limit.

app.get("/api/documents/:id", async (req, res) => {
  const result = await pool.query(
    "SELECT body FROM documents WHERE owner_id = $1 AND id = $2",
    [req.auth.userId, req.params.id]
  );
  if (result.rowCount === 0) {
    res.status(404).json({ error: "DOCUMENT_NOT_FOUND" });
    return;
  }
  res.set("Cache-Control", "no-store").json(result.rows[0].body);
});

app.put("/api/documents/:id", async (req, res) => {
  const header = req.get("X-Expected-Revision");
  if (!header || (header !== "*" && !/^(0|[1-9]\d*)$/.test(header))) {
    res.status(400).json({ error: "INVALID_EXPECTED_REVISION" });
    return;
  }
  const expected = header === "*" ? null : Number(header);
  if (expected !== null && (!Number.isSafeInteger(expected) || expected > 2147483646)) {
    res.status(400).json({ error: "INVALID_EXPECTED_REVISION" });
    return;
  }

  const value: unknown = req.body;
  const issues = validateDocument(value);
  if (issues.length > 0) {
    res.status(422).json({ error: "INVALID_DOCUMENT", issues });
    return;
  }
  const document = value as FabricDocument;
  if (document.id !== req.params.id) {
    res.status(422).json({ error: "DOCUMENT_ID_MISMATCH" });
    return;
  }

  const params = [req.auth.userId, document.id, JSON.stringify(document)];
  const result = expected === 0
    ? await pool.query(
        `INSERT INTO documents (owner_id, id, body, revision)
         VALUES ($1, $2, jsonb_set($3::jsonb, '{revision}', '1'::jsonb), 1)
         ON CONFLICT (owner_id, id) DO NOTHING
         RETURNING revision`,
        params
      )
    : await pool.query(
        `UPDATE documents
         SET body = jsonb_set($3::jsonb, '{revision}', to_jsonb(revision + 1)),
             revision = revision + 1
         WHERE owner_id = $1 AND id = $2
           AND ($4::integer IS NULL OR revision = $4::integer)
         RETURNING revision`,
        [...params, expected]
      );

  if (result.rowCount === 0) {
    res.status(409).json({ error: "SAVE_CONFLICT" });
    return;
  }
  res.status(expected === 0 ? 201 : 200).json({
    revision: result.rows[0].revision,
  });
});

app.listen(3001);

Run the API behind the same origin as the React app, or configure a development proxy for /api. Apply your existing session and CSRF policy to these routes. A document ID locates a row; ownership comes from the verified session, never from metadata.owner supplied by the browser.

The endpoint assigns revisions and writes that value into both the JSON body and the revision column. This keeps the next GET consistent with the previous save response. Its overwrite branch updates an existing row; it does not recreate a deleted document. A missing row or revision mismatch returns 409.

The 2mb limit is an example application limit, not a package limit. Adjust it for your documents. validateDocument checks the document shape; enforce any additional object-count, URL, asset, or business rules in your backend too.

The SQL follows the package's atomic revision-check guidance. See PostgreSQL's UPDATE and RETURNING documentation for the database behavior. Express 5 forwards rejected async route handlers to error handling; integrate your app's normal handler using the Express error-handling guide.

How does a revision check prevent lost updates?

Suppose two tabs open revision 4 of the same document. Both tabs edit it. Without a server-side check, the second save can overwrite the first save without warning.

These numbers illustrate the protocol; they are not a performance measurement.

Check the revision and write the document in the same database operation. A separate SELECT followed by an unconditional UPDATE leaves room for another request to save between them.

The engine also serializes saves within one editor session. That does not replace a database revision check across tabs, devices, or API clients.

For conflict UI, offer to review the stored document or deliberately overwrite it. engine.save({ overwrite: true }) passes expectedRevision: null; use that only after the user chooses to overwrite. Loading a newer document can also replace unsaved work, so make that choice explicit before passing discardUnsavedChanges: true.

Read the save conflicts guide for the full decision flow.

Are image files stored inside the canvas JSON?

A normal image object stores an address for its image. Saving that address does not upload the file. In particular, a blob: URL refers to data in the current browser environment and is unsuitable for reopening on another device.

Configure assets.upload to turn tab-only images into durable URLs while the engine prepares a save:

// Add this assets option when creating the engine.
const assets = {
  async upload({ blob }: { blob: Blob }) {
    const body = new FormData();
    body.append("file", blob);
    const response = await fetch("/api/uploads", { method: "POST", body });
    if (!response.ok) throw new Error("The image could not be uploaded.");
    const result = (await response.json()) as { url: string };
    return result.url;
  },
};

/api/uploads is another app-owned endpoint. It must save the file and return an address that your readers can access. The package does not create an S3 bucket, configure a CDN, or supply the upload route.

Avoid treating an expiring signed URL as a permanent asset identity. The images and fonts guide explains assets.upload and assets.resolveUrl, including how to resolve stored asset addresses when opening a document.

If a stored image cannot be opened, see the companion article, Why Fabric.js loadFromJSON Can Leave Your Editor Half-Loaded.

What should you check before shipping this save flow?

Verify the complete round trip, including failures:

• Reopen the document. Save, refresh, and open the same ID.
• Compare the content. Check object IDs, canvas dimensions, and stacking order.
• Create a conflict. Open two tabs; confirm the older revision cannot overwrite the newer save.
• Reject invalid input. Send a mismatched document ID and malformed document body.
• Check ownership. Confirm another account cannot read or write the document.
• Interrupt a request. Confirm the UI does not claim a failed save succeeded.
• Reopen uploaded images. Test from a fresh browser session.

The adapter verification guide helps check storage behavior. The production checklist covers the wider editor lifecycle.

For this article, the complete TypeScript examples passed type checking against package 1.0.2 and Fabric.js 7.4.0. A Chromium check with the built-in memory adapter confirmed that saved object IDs and canvas dimensions survived reopening, the first save produced revision 1, and an older editor's save produced SAVE_CONFLICT. The HTTP/PostgreSQL endpoint is an illustrative implementation; connect and test it with your app's actual authentication and database.

Retries need one extra decision in your API: a write can succeed even if its response is lost. Retrying with the old expected revision can then produce a conflict. This sample preserves the stored document rather than guessing. If your app needs transparent retry acknowledgments, implement request idempotency on the server.

Can you use MongoDB, MySQL, or a different backend?

Yes. The adapter sends plain JSON and returns a revision. Replace the PostgreSQL endpoint with your own backend while keeping the two storage methods and an atomic revision condition.

For MongoDB, the equivalent idea is a conditional update filtered by document ID, owner, and expected revision. The exact database code belongs to your app. The package does not ship a MongoDB model or a MySQL table.

Can you open JSON saved by an older Fabric.js editor?

The engine can recognize plain Fabric.js JSON through load, loadDocument, and importFabricJson. A document loaded by engine.load(id) retains that requested ID, and its next save uses the engine's current document format.

Check the migration guide before moving existing records. Back up the stored JSON and test your custom classes and assets. The API example above validates incoming saves in the engine's document format.

Does calling toDocument() mean the canvas has been saved?

No. engine.toDocument() produces a document object. engine.save() uses the configured storage adapter and updates the engine's save state after storage accepts the write.

Use toDocument() when you need a snapshot. Use save() for the managed persistence flow shown here.

Start with a manual save and an open-by-ID action. Once the round trip and conflicts work with your real storage, add autosave and image uploads. The npm package, quick start, and GitHub repository contain the implementation and related examples.

These are the problems fabricjs-document-engine is built to handle. It connects to a Fabric.js canvas you already own. You keep your own toolbar, storage service, and user interface. The package adds the document workflow around them.

This guide starts with the problems people actually describe, then shows what the package does and where your application still has work to do. The examples use the published 1.0.2 API with Fabric.js 7. The package also supports Fabric.js 6. For a complete first project, see the save and load tutorial.

The short answer

These are search phrases, not claims that every report is a Fabric.js core bug. Many are integration problems that appear when an application grows from a drawing canvas into an editor. The Fabric.js API already includes serialization and image export. The package coordinates them into a document lifecycle.

Start with a canvas and a document

Install the package with a supported Fabric version:

npm install fabric@^7 fabricjs-document-engine@1.0.2

Here is a small setup using the built-in browser storage adapter. The HTML page needs <canvas id="editor"></canvas>.

import { Canvas, Rect } from "fabric";
import { createDocumentEngine } from "fabricjs-document-engine";
import { createLocalStorage } from "fabricjs-document-engine/storage";

const canvas = new Canvas("editor", {
  width: 800,
  height: 500,
  backgroundColor: "#f8fafc",
});

const engine = createDocumentEngine({
  canvas,
  document: { id: "poster-42" },
  storage: createLocalStorage({ prefix: "my-editor:" }),
  autosave: { delay: 1000, maxWait: 10000 },
});

canvas.add(new Rect({
  left: 80,
  top: 70,
  width: 180,
  height: 120,
  fill: "#4f46e5",
}));

await engine.save();

The document option gives this design a known ID. createLocalStorage is useful for a prototype on one browser. For a product with accounts or multiple devices, provide a backend storage adapter. The engine does not host your files or create your API.

You can also use engine.toDocument() and engine.loadDocument(json) without any adapter. Those calls serialize and open a document you store yourself. engine.save(), engine.load(id), autosave, and versions need an adapter. See the creation options and storage guide.

1. “Fabric.js undo redo not working”

Fabric.js has no built-in document history. A developer in Fabric.js issue #10011 tried to add history to a Fabric 6 editor. The thread includes two familiar problems: older callback-style loadFromJSON code no longer matched the promise API, and objects were hard to identify after loading a prior snapshot. It is an example of the integration work a history system requires, not evidence that Fabric.js drawing is broken.

The engine records object additions and removals, pointer moves and transforms, and completed text edits. One user action becomes one history step. Your toolbar can ask whether a step is available:

In this snippet, undoButton and redoButton are your toolbar's button elements.

undoButton.disabled = !engine.canUndo();
redoButton.disabled = !engine.canRedo();

undoButton.addEventListener("click", () => void engine.undo());
redoButton.addEventListener("click", () => void engine.redo());

A detail that matters: calling object.set() in your own code does not necessarily fire a Fabric event. If your toolbar changes several properties, group them yourself:

Here card is the Fabric object your editor is changing.

engine.transaction("Move and recolor card", () => {
  card.set({ left: 200, top: 120, fill: "#f97316" });
  card.setCoords();
  canvas.requestRenderAll();
});

That whole command becomes one labelled undo step. You can also make changes first and call engine.commit("Recolor card"). Read the undo and redo guide for the automatic events, keyboard shortcuts, and history limits.

2. “Fabric.js object reference lost after undo or reload”

An undo operation or JSON load often creates new JavaScript object instances. A variable that pointed to the old rectangle may no longer point to the rectangle now on the canvas. Fabric.js issue #6799 also shows how group-relative transforms make object state harder to reason about.

The engine assigns a stable ID to each object, including children inside groups. Save the ID in your application state. After a load or undo, find the current instance:

const id = card.id;

await engine.undo();

const currentCard = engine.getObjectById(id);
if (currentCard) {
  currentCard.set("fill", "#2563eb");
  canvas.requestRenderAll();
  engine.commit("Recolor card");
}

This solves identity across document operations. It does not calculate canvas-relative coordinates for a grouped object or fix every transform issue in #6799. For those, use Fabric.js transformation APIs. The engine's document format explains object IDs and order.

3. “Fabric.js custom properties lost after JSON load”

An editor often adds fields such as label, databaseId, or lockedBy. Fabric.js supports custom serialization, but you must configure it. The request in issue #10887 describes the repeated setup developers face when storing application metadata on objects. Its native custom properties guide is also worth reading.

For a custom class, register its type and the properties that must survive a document round trip:

import { Rect } from "fabric";
import { createDocumentEngine } from "fabricjs-document-engine";

class Sticker extends Rect {
  static type = "Sticker";
  declare label: string;
}

const engine = createDocumentEngine({
  canvas,
  customObjects: [
    { fabricClass: Sticker, properties: ["label"] },
  ],
});

Set label on a Sticker, save, and load it again. You do not have to remember to list that property on every toJSON() call. Register the class before you load a document that uses it. Otherwise, the load fails with UNKNOWN_OBJECT_TYPE instead of quietly changing it to another shape. See custom objects.

This feature is for Fabric classes and object fields. Put whole-document information such as a title or customer ID in document metadata, using engine.updateMetadata({ title: "Summer poster" }).

4. “Fabric.js loadFromJSON failed” or “the old canvas disappeared”

Loading is more than parsing JSON. A saved design can contain an unknown custom class, a malformed value, an expired image URL, or a newer schema. There may also be two loads in progress because the user quickly opened design A and then design B.

The engine validates and checks the incoming document before replacing the current canvas. An unknown type fails with UNKNOWN_OBJECT_TYPE. A missing image fails with MISSING_ASSETS. If B starts after A, A is cancelled with LOAD_ABORTED, so its late response cannot replace B. The save and load guide documents these rules.

try {
  await engine.load("poster-42");
  showMessage("Poster opened");
} catch (error) {
  if (error.code === "LOAD_ABORTED") return;
  if (error.code === "UNSAVED_CHANGES") {
    showMessage("Save or discard your current edits first");
    return;
  }
  showMessage(`Could not open the poster: ${error.message}`);
}

When storage is configured, the engine also refuses to replace unsaved work unless the user has chosen to discard it. Do not pass discardUnsavedChanges: true automatically. A failed load should leave the design people were editing on screen. The error code reference lists the cases your UI can handle.

5. “Fabric.js autosave overwrites newer changes”

Fabric.js does not decide when your app sends a document to a server. A common editor mistake is to fire a request after every change. Request A might start first but finish after request B, leaving older content in storage.

With a storage adapter, the engine keeps one save in flight. If edits happen during that save, it schedules one follow-up save with the latest content. engine.isDirty() and engine.getSaveState() let you show what is saved. Temporary failures can be retried. The exact timing and retry options are in the autosave guide.

engine.on("save:status", ({ status, isDirty, revision }) => {
  statusElement.textContent = `${status} · revision ${revision}`;
  saveButton.disabled = !isDirty;
});

One tab is only half the problem. If another tab or device has saved the same document, a correct adapter compares revisions and reports SAVE_CONFLICT. The app can offer to reload, save a copy, or deliberately overwrite. Do not choose overwrite silently. The built-in adapters check revisions; your own backend must enforce the same rule at the database write. See save conflicts and the custom backend example.

Put the same save rules on your backend

For an account-based editor, write a storage adapter around your API. This TypeScript example assumes your server returns a document on GET, and { revision: number } on a successful PUT:

import type { DocumentStorage } from "fabricjs-document-engine";

const storage: DocumentStorage = {
  async loadDocument(id) {
    const response = await fetch(`/api/documents/${encodeURIComponent(id)}`);
    if (!response.ok) throw new Error(`Load failed: ${response.status}`);
    return response.json();
  },

  async saveDocument(document, { expectedRevision, signal }) {
    const response = await fetch(
      `/api/documents/${encodeURIComponent(document.id)}`,
      {
        method: "PUT",
        headers: {
          "Content-Type": "application/json",
          "If-Match": String(expectedRevision ?? "*"),
        },
        body: JSON.stringify(document),
        signal,
      },
    );

    if (response.status === 409) {
      throw Object.assign(new Error("Saved in another tab"), {
        code: "SAVE_CONFLICT",
      });
    }
    if (!response.ok) throw new Error(`Save failed: ${response.status}`);
    return response.json(); // { revision: number }
  },
};

Your server must check expectedRevision against the stored revision as part of the write, then return the new revision. A client-side comparison alone cannot stop two devices from racing. Add authorization for each document ID and decide how your UI presents a conflict. The package's backend guide and adapter verification guide cover the full contract.

6. “Fabric.js image missing after load” and “my font changed”

The JSON can be valid while the resources it refers to are gone. An image may point to an expired signed URL. A browser-only blob: URL will disappear after refresh. A web font might not be ready when Fabric measures text.

The engine records an asset manifest with the image and font variants a document uses. It checks them before loading. MISSING_ASSETS includes the missing image URLs and object IDs; unavailable fonts can produce warnings or fail the load if you require them. You can resolve URLs, offer replacement images, load fonts, and upload temporary images through asset options.

const report = await engine.checkAssets();
console.log(report.missingImages, report.unavailableFonts);

// If a stored image URL has moved:
await engine.replaceImage("/old-logo.png", "/new-logo.png");

The package can tell you what is missing and use a replacement you provide. It cannot revive a deleted image on your server. If designs need to open on other devices, upload browser-only images to durable storage and return a portable URL. For web fonts, make the font available and load it before you rely on its measured text layout.

7. “Fabric.js canvas lost after refresh or crash”

Autosave helps, but a tab can close while edits are still unsaved or a request is in flight. Optional recovery keeps a separate local checkpoint. It uses IndexedDB while the person edits and can offer a copy after refresh or interruption.

import { createIndexedDbRecovery } from "fabricjs-document-engine/recovery";

const engine = createDocumentEngine({
  canvas,
  storage,
  recovery: { store: createIndexedDbRecovery(), interval: 2000 },
});

const recoverable = await engine.getRecoverableDocuments();
if (recoverable.length > 0 && window.confirm("Restore unsaved work?")) {
  await engine.restoreRecovery(recoverable[0].documentId);
}

The confirmation demonstrates the choice. In a real editor, show a useful preview and let the user restore or discard a copy before replacing what is currently on screen. Recovery is local to the browser; it is not a server backup or multi-device sync. Private browsing and storage clearing can remove it. Read the recovery guide for checkpoint timing and temporary images.

8. “Fabric.js tainted canvas cannot be exported”

A Fabric.js user reported that exporting after loadFromJSON hit a tainted-canvas error in issue #5429. This is a browser security rule when a remote image is drawn without the required cross-origin permission. The package cannot bypass that rule.

It can check before export and give you a useful problem list:

const check = await engine.preflightExport({ format: "png" });
if (!check.ok) {
  showProblems(check.problems);
} else {
  const result = await engine.export({
    format: "png",
    area: "content",
    scale: 2,
    background: "transparent",
  });
  // Download or upload result.blob.
}

The export API also supports JPEG, WebP, SVG, and editable JSON. You can choose the canvas, content, selection, or an explicit rectangle as the output area. A blocked raster export reports EXPORT_BLOCKED; successful export does not change the editable canvas or its undo state. See export.

To actually fix a cross-origin image, load it with appropriate crossOrigin settings and configure its server to send the correct Access-Control-Allow-Origin header. See the package troubleshooting guide. Switching packages will not remove the browser's CORS requirement.

9. “How do I keep versions of a Fabric.js design?”

Undo is for recent steps in the current editing session. A named version is a checkpoint you want to find next week. The engine can create, list, restore, and delete versions when its storage adapter supports them:

const version = await engine.createVersion("Approved by client");
const versions = await engine.listVersions();

// Later, after the user chooses to restore it:
await engine.restoreVersion(version.id);

Restoring keeps an automatic copy of the current state first, then opens the older content as a new unsaved revision. That is different from moving a history pointer backward and erasing later work. The built-in storage adapters support versions; a custom backend needs the version methods described in the versions guide.

10. “How do I open my old Fabric.js JSON?”

You may already have designs saved with canvas.toJSON(). You do not have to throw them away to use a document format. The engine can import plain Fabric JSON from supported older versions and wrap it in a document:

await engine.importFabricJson(oldJsonText, {
  id: "imported-poster-42",
  metadata: { source: "previous editor" },
});

The format records a schemaVersion, canvas dimensions and background, objects in stacking order, assets, and document metadata. The migration guide covers Fabric 5, 6, and 7 JSON and schema errors. Test your own saved fixtures, especially if your old app had custom objects or unusual properties. The document format reference lists the fields.

11. “Can I safely open JSON uploaded by another user?”

A JSON file is input from outside your app. It may have unknown classes, unsafe addresses, extreme nesting, or far more objects than your browser can handle. The engine validates the document, refuses unsafe content, and applies object-count and depth limits before loading. Its security guide explains the checks and configuration.

This is a useful boundary, but it does not replace your application's authentication, authorization, upload limits, or server-side validation. Only load documents that the current user is allowed to access. If you render remote assets, still control which hosts your product trusts.

12. “Does it work with React, Next.js, Vue, or Svelte?”

The core package is framework independent. React has optional hooks for engine creation and toolbar state. Next.js needs the Fabric canvas created in the browser, not during server rendering. Vue should keep a Fabric canvas out of deep reactive proxies. Svelte and plain JavaScript can subscribe to the state store.

The package documents each setup: React, Next.js, Vue, Svelte, and plain JavaScript. These integrations connect the document engine to your app; they do not supply an editor UI.

What the package does not solve

A dependable article should say where the boundary is:

• It does not draw or style your toolbar, selection controls, or pages. Fabric.js and your app own the canvas UI.
• It does not provide a hosted database, image bucket, or backend authentication.
• It does not make a deleted remote image available again or bypass CORS.
• It does not provide real-time multi-user collaboration or automatic merge of two people's changes. A save conflict needs a product decision.
• It does not export PDF directly. Use its image or SVG output with a separate PDF library if needed.
• It does not promise that any particular issue in the Fabric.js tracker is fixed in Fabric.js itself. The package addresses the document workflow described here.

How to decide if you need it

If you only need to draw shapes and download a one-off image, Fabric.js may already be enough. If people will return to edit a saved design, ask three questions:

1. Can I identify the same object after reopening and undoing?
2. Can a failed load or a slow save erase good work?
3. Can I tell the user exactly why an image, font, or export failed?

If those matter, a document layer is worth considering. Start with the quick start, run the live examples, and test your own documents against the production checklist. The code is on GitHub, and the released package is on npm.

Test the failure, not just the happy path

Use a saved fixture that contains a group, a custom object, an image, and text in a web font. Then check these cases in your own app:

1. Save, refresh, and compare object IDs, stacking order, background, and metadata.
2. Undo a drag and a toolbar-driven change. Confirm each takes one step and the current object can be found by ID.
3. Delay two document loads. Confirm the later choice stays on screen.
4. Break an image URL. Confirm the old canvas stays visible and the missing URL is reported.
5. Delay a save, edit again, and confirm the final stored document contains the latest edit.
6. Open the same document in two tabs. Save in one, then confirm the other shows a conflict.
7. Make an unsaved edit, refresh, and check the recovery choice.
8. Try a remote image without CORS. Confirm export preflight reports the blocker.

These tests tell you whether the package and your storage, assets, and UI work together. A feature list alone cannot answer that.

Original sources and further reading

Fabric.js problem reports and official API

• Fabric.js issue #10011: undo/redo history in Fabric 6
• Fabric.js issue #6799: object state inside groups
• Fabric.js issue #10887: application metadata and JSON serialization
• Fabric.js issue #5429: tainted canvas after JSON load
• Fabric.js Canvas API and custom properties guide

Package implementation and documentation

• fabricjs-document-engine on npm and source repository
• DocumentEngine API and error codes
• Save/load, undo/redo, autosave, and assets/fonts
• Recovery, versions, export, and document format