createDocumentEngine options

createDocumentEngine connects the engine to an existing Fabric.js canvas and returns a DocumentEngine. Below are all createDocumentEngine options.

function createDocumentEngine(options: DocumentEngineOptions): DocumentEngine

Connects the engine to an existing Fabric.js canvas. The canvas stays yours: the engine only listens to it, and changes it when you load, undo or restore.

Usage

import { createDocumentEngine } from "fabricjs-document-engine";
import { createLocalStorage } from "fabricjs-document-engine/storage";
 
const engine = createDocumentEngine({
  canvas,
  storage: createLocalStorage(),
  autosave: true,
  history: { limit: 50 },
});

Only canvas is required. Without storage, you can still save with toDocument() and load with loadDocument(), but save(), load(id), autosave and versions are not available.

createDocumentEngine options

Name	Type	Default	Description
canvas*	StaticCanvas	—	Your Fabric.js canvas, a `Canvas` or a `StaticCanvas`.
storage	DocumentStorage	none	Where documents are saved and loaded. Needed for `load`, `save`, autosave and versions.
customObjects	CustomObjectDefinition[]	[]	Your own Fabric classes and the extra properties they need to keep.
document	NewDocumentOptions	a new id	The `id` and `metadata` of the first, empty document.
history	HistoryOptions	{ limit: 100, maxBytes: 64 MB }	How many undo steps to keep, and how much memory they may use.
autosave	boolean \| AutosaveOptions	off	Saves on its own after edits. `true` means `{ delay: 1000, maxWait: 10000 }`. Needs `storage`.
saveRetry	RetryOptions	{ attempts: 3, baseDelay: 500, maxDelay: 8000 }	How failed saves are retried.
assets	AssetOptions	{}	How images and fonts are resolved, checked and uploaded.
recovery	RecoveryOptions	off	Keeps local copies of unsaved work, so it can be restored after a crash or refresh.
versions	VersionOptions	{ autoEvery: 0, keepAuto: 20 }	Keeps an automatic version every N saves, and how many of them to keep.
limits	ContentLimits	{ maxObjects: 50000, maxDepth: 100 }	Safety limits for documents that are loaded or imported.

Nested options

Autosave

Name	Type	Default	Description
delay	number	1000	Save after this many milliseconds without an edit.
maxWait	number	10000	Save at the latest this many milliseconds after the first unsaved edit, even while the user keeps editing.

Save retries

Name	Type	Default	Description
attempts	number	3	How many times to retry.
baseDelay	number	500	The first wait, in milliseconds.
maxDelay	number	8000	The longest wait, in milliseconds.

History

The history limit and memory budget for undo:

Name	Type	Default	Description
limit	number	100	How many undo steps to keep.
maxBytes	number	64 MB	The memory undo history may use. The oldest steps are dropped first.

Assets

Name	Type	Default	Description
resolveUrl	(url: string) => string \| Promise<string>	—	Rewrites each stored image URL before loading, for example to sign it or map it to a CDN.
replaceMissingImage	(image: ImageAsset) => string \| null \| undefined \| Promise<string \| null \| undefined>	—	Supplies a replacement URL for an image that did not load. Return `null` to leave it missing.
upload	(request: UploadRequest) => Promise<string>	—	Stores `blob:` and `data:` images while saving, and returns their permanent URL.
loadFont	FontLoader	—	Loads a font before text is created.
checkImages	boolean	true	Set to `false` to skip loading images during the check.
requireFonts	boolean	false	Fail loading with `MISSING_FONTS`, and export with `MISSING_FONT`, instead of warning.

Custom objects

Name	Type	Default	Description
fabricClass*	{ type: string; fromObject?: unknown; }	—	Your Fabric class. It needs a static `type`.
properties	string[]	[]	The extra properties to save and load with the object.

Recovery

Name	Type	Default	Description
store*	RecoveryStore	—	Where copies are kept, such as `createIndexedDbRecovery()`.
interval	number	2000	Write a copy at most once every this many milliseconds while there are unsaved changes.

Versions

Name	Type	Default	Description
keepAuto	number	20	How many automatic versions to keep. Named versions are never pruned.
autoEvery	number	0 (off)	Keep an automatic version after every N successful saves.

Limits

Name	Type	Default	Description
maxObjects	number	50000	Refuse documents with more objects than this.
maxDepth	number	100	Refuse documents nested deeper than this.
isAllowedUrl	(url: string) => boolean	isSafeImageUrl	Decides which image addresses may be fetched, after `resolveUrl`.

Most createDocumentEngine options are read once, when the engine is created. To change them, create a new engine.