Migration

Most editors already have saved projects in plain Fabric.js JSON. A Fabric.js migration usually means writing a converter. Here, old files open directly and are upgraded on the way in.

Open plain Fabric.js JSON

Plain canvas.toJSON() output from Fabric 5, Fabric.js v6 or Fabric.js 7 opens as it is:

await engine.importFabricJson(savedJsonText, {
  id: "plan-42",
  metadata: { source: "old editor" },
});

loadDocument and load(id) recognize plain Fabric.js JSON too, so projects stored by your existing app open without a separate import step. A document opened with load(id) keeps that id, and its next save stores it in the new format.

Moving from Fabric 5 to Fabric.js v6 or 7

This package needs Fabric.js 6 or 7. The saved data does not block the upgrade:

• JSON saved by Fabric 5 opens through the migration step. Fabric.js 6 and 7 still accept Fabric 5's legacy type names.
• Fabric 6 and Fabric.js 7 use different default origins. Documents always store originX and originY, so a file saved with one opens correctly with the other.

Upgrade your own code with the official Fabric.js upgrade guide. Your stored files need no Fabric.js migration script.

Schema versions

Every document records its schemaVersion. When the format changes in a future major release, older documents are upgraded step by step when they are opened.

• load:success reports migratedFrom when an upgrade happened.
• A failed step rejects with MIGRATION_FAILED, and error.migrationFrom names the version it started from.
• A document from a newer version of the package is refused with UNSUPPORTED_SCHEMA, rather than being misread.

Upgrade files on the server

migrateDocument and detectSchemaVersion work in Node without a canvas, for batch jobs:

import { detectSchemaVersion, migrateDocument } from "fabricjs-document-engine";
 
if (detectSchemaVersion(stored) === 0) {
  const { document } = migrateDocument(stored, {
    canvasWidth: 1200,
    canvasHeight: 800,
  });
  await saveUpgraded(document);
}

detectSchemaVersion returns 1 for a document, 0 for plain Fabric.js JSON, and undefined for anything else. See compatibility for tested versions.