# DocumentEngine

> All DocumentEngine methods: save and load documents, undo and redo, export, versions, recovery, assets and events, with their types and behavior.

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

`createDocumentEngine` returns a `DocumentEngine`. The table below lists all DocumentEngine methods and properties. Methods that touch storage or the canvas return a promise.

## Members

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `canvas` (required) | `StaticCanvas` | — | The canvas you passed in. |
| `getDocumentInfo` (required) | `(): DocumentInfo` | — | `{ id, createdAt, updatedAt, metadata }` of the current document. |
| `updateMetadata` (required) | `(changes: Record<string, unknown>): void` | — | Merges `changes` into the metadata and marks the document as unsaved. |
| `newDocument` (required) | `(options?: NewDocumentRequest): void` | — | Clears the canvas and starts a new document. |
| `toDocument` (required) | `(): FabricDocument` | — | Serializes the canvas into a `FabricDocument`. Every object gets an id. |
| `loadDocument` (required) | `(document: unknown, options?: LoadOptions): Promise<FabricDocument>` | — | Validates, migrates and checks the assets of a document, then loads it. A failed load leaves the canvas untouched. |
| `load` (required) | `(documentId: string, options?: LoadOptions): Promise<FabricDocument>` | — | Loads a document from `storage`. It keeps `documentId` even if it was stored as plain Fabric JSON. |
| `importFabricJson` (required) | `(json: string \| Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>` | — | Opens plain Fabric JSON, such as `canvas.toJSON()` output, as text or as an object. |
| `createVersion` (required) | `(name?: string): Promise<VersionSummary>` | — | Keeps a named version of the current document. |
| `listVersions` (required) | `(documentId?: string): Promise<VersionSummary[]>` | — | Version summaries, newest first. |
| `restoreVersion` (required) | `(versionId: string): Promise<FabricDocument>` | — | Keeps an automatic `Before restoring "..."` version first, then loads the old content as a new, unsaved revision. |
| `deleteVersion` (required) | `(versionId: string): Promise<void>` | — | Deletes a version. |
| `save` (required) | `(options?: SaveOptions): Promise<FabricDocument>` | — | Saves through `storage`. Only one save runs at a time, and calls made during a save merge into one follow-up. |
| `isDirty` (required) | `(): boolean` | — | Whether there are unsaved changes. |
| `getSaveState` (required) | `(): SaveState` | — | The current `SaveState`. |
| `registerObject` (required) | `(definition: CustomObjectDefinition): void` | — | Registers a custom class after the engine was created. |
| `transaction` (required) | `<Result>(label: string, work: () => Result): Result` | — | Records everything `work` changes as one labelled undo step. Nested and async work is supported. |
| `commit` (required) | `(label?: string): boolean` | — | Records changes your code made since the last step. Returns `false` if nothing changed. |
| `undo` (required) | `(): Promise<boolean>` | — | Undoes one step. Calls run in order. A failure rejects with `HISTORY_FAILED` and keeps the step. |
| `redo` (required) | `(): Promise<boolean>` | — | Redoes one step. Calls run in order. |
| `canUndo` (required) | `(): boolean` | — | Whether there is a step to undo. |
| `canRedo` (required) | `(): boolean` | — | Whether there is a step to redo. |
| `getHistory` (required) | `(): { undo: string[]; redo: string[]; }` | — | The labels of the undo and redo steps, newest first. |
| `clearHistory` (required) | `(): void` | — | Forgets every undo and redo step. |
| `getObjectById` (required) | `(id: string): FabricObject \| undefined` | — | Finds any object by its id, including objects inside groups. |
| `getAssetManifest` (required) | `(): AssetManifest` | — | The images and fonts the current canvas uses. |
| `checkAssets` (required) | `(): Promise<AssetReport>` | — | Loads every image and font and reports `{ manifest, missingImages, unavailableFonts, warnings }`. |
| `replaceImage` (required) | `(oldUrl: string, newUrl: string): Promise<number>` | — | Replaces every image that uses `oldUrl`, keeping each one's size on the page, as one undo step. Returns how many were replaced. |
| `export` (required) | `(options: ExportOptions): Promise<ExportResult>` | — | Exports PNG, JPEG, WebP, SVG or JSON. Rejects with `EXPORT_BLOCKED` and a list of `problems` when something would break the output. |
| `preflightExport` (required) | `(options: ExportOptions): Promise<ExportPreflight>` | — | Runs the export checks without exporting: `{ ok, problems, warnings }`. |
| `flushRecovery` (required) | `(): Promise<void>` | — | Writes a recovery copy right now. |
| `getRecoverableDocuments` (required) | `(): Promise<RecoveryRecord[]>` | — | Every recovery copy, newest first. |
| `getRecovery` (required) | `(documentId?: string): Promise<RecoveryRecord \| undefined>` | — | One recovery copy. The default is the current document. |
| `restoreRecovery` (required) | `(documentId?: string, options?: LoadOptions): Promise<FabricDocument>` | — | Loads a recovery copy as unsaved work, keeping the revision it was based on. |
| `discardRecovery` (required) | `(documentId?: string): Promise<void>` | — | Deletes a recovery copy. |
| `getInterruptedLoad` (required) | `(): Promise<InterruptedLoad \| undefined>` | — | `{ documentId, startedAt }` of a load that never finished, for example because the tab crashed. |
| `on` (required) | `<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe` | — | Subscribes to an event. Returns a function that unsubscribes. |
| `destroy` (required) | `(): void` | — | Stops listening and cancels loads, saves and timers. Writes a recovery copy if there is unsaved work. Later calls throw `ENGINE_DESTROYED`. |

## Method options

### Load options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `restoreCanvasSize` | `boolean` | — | Resize the canvas to the size stored in the document. |
| `discardUnsavedChanges` | `boolean` | `false` | Open the document even though the current one has unsaved changes. Without it, the call refuses with `UNSAVED_CHANGES`. |

### Import options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `a new id` | The id of the new document. |
| `metadata` | `Record<string, unknown>` | `{}` | Metadata for the new document. |
| `restoreCanvasSize` | `boolean` | — | Resize the canvas to the size stored in the document. Inherited from LoadOptions. |
| `discardUnsavedChanges` | `boolean` | `false` | Open the document even though the current one has unsaved changes. Without it, the call refuses with `UNSAVED_CHANGES`. Inherited from LoadOptions. |

### Save options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `overwrite` | `boolean` | `false` | Skip the revision check and keep this version after a `SAVE_CONFLICT`. |

### Save state

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `status` (required) | `SaveStatus` | — | One of `saved`, `unsaved`, `saving`, `error` or `conflict`. |
| `isDirty` (required) | `boolean` | — | Whether there are unsaved changes. |
| `isSaving` (required) | `boolean` | — | Whether a save is running. |
| `revision` (required) | `number` | — | The revision last saved or loaded. |
| `lastSavedAt` (required) | `string \| undefined` | — | When the last save finished, as an ISO date. |
| `error` (required) | `DocumentEngineError \| undefined` | — | The error of the last failed save. |

### Export options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `format` (required) | `ExportFormat` | — | `'png'`, `'jpeg'`, `'webp'`, `'svg'` or `'json'`. |
| `scale` | `number` | `1` | Output size multiplier, such as `2` for retina screens. |
| `quality` | `number` | `0.92` | 0 to 1, for JPEG and WebP. |
| `area` | `ExportArea` | `'canvas'` | `'canvas'`, `'content'` (every object), `'selection'`, or `{ left, top, width, height }`. |
| `padding` | `number` | `0` | Extra space around `content` or `selection`. |
| `background` | `ExportBackground` | `'keep'` | `'keep'`, `'transparent'` or any CSS color. |
| `signal` | `AbortSignal` | — | An `AbortSignal` that cancels the export. |

### Export result

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `format` (required) | `ExportFormat` | — | The format you asked for. |
| `mimeType` (required) | `string` | — | The MIME type of `blob`. |
| `blob` (required) | `Blob` | — | The file, ready to download or upload. |
| `width` (required) | `number` | — | Output width in pixels. |
| `height` (required) | `number` | — | Output height in pixels. |
| `warnings` (required) | `AssetWarning[]` | — | Asset warnings, such as a font that fell back. |
| `document` | `FabricDocument` | — | JSON exports only: the portable document. |

## Rules that apply to all DocumentEngine methods

- A failed load never clears or half-fills the canvas.
- With a storage adapter, `load`, `loadDocument`, `importFabricJson` and `newDocument` refuse with `UNSAVED_CHANGES` while there are unsaved changes, unless you pass `discardUnsavedChanges: true`.
- Only one save runs at a time. `save` calls made during a save merge into one follow-up.
- `undo` and `redo` calls run in order.
- `export` never changes the canvas, the history or the unsaved state.
- After `destroy()`, every call throws `ENGINE_DESTROYED`.

The guides explain each group in depth: [save and load](https://fabricjs-document-engine.jscrate.dev/docs/guides/save-and-load), [undo and redo](https://fabricjs-document-engine.jscrate.dev/docs/guides/undo-redo) and [export](https://fabricjs-document-engine.jscrate.dev/docs/guides/export).