# Migration

> Fabric.js migration without a rewrite: open canvas.toJSON output from Fabric 5, move to Fabric.js v6 or Fabric.js 7, and upgrade old documents on load.

Source: https://fabricjs-document-engine.jscrate.dev/docs/guides/migration
Last updated: 2026-09-28

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:

```ts
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:

```ts
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](https://fabricjs-document-engine.jscrate.dev/docs/production/compatibility) for tested versions.