This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/web/annotations/annotation-saving-mechanism.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Auto save PDF annotations using JavaScript | Nutrient SDK

Auto saving annotations

Markdown version of this page, suitable for AI agents and automation

Nutrient Web SDK supports auto saving the changes that occur to annotations. Autosave behavior is dependent on the operational mode used and the configuration of Configuration#autoSaveMode.

Standalone

In standalone mode of Nutrient Web SDK, changes stay in memory until you export them. Standalone mode still distinguishes saved changes from unsaved ones, using the same persisting logic as other modes. The exported Instant JSON includes only saved changes. See the guide on importing and exporting for more information.

Server-backed

In server-backed operational mode, Nutrient Web SDK always synchronizes local changes to the Document Engine backend by default. This means you can always use the backend API to interact with these objects. Set the autosave behavior with the Configuration#autoSaveMode configuration option.

Before a change reaches Document Engine, it receives a stable ID, a universally unique lexicographically sortable identifier (ULID(opens in a new tab)). Document Engine also uses this ID, and the ID enables you to track updates that happen before Document Engine responds. If you need to confirm that Document Engine saved a local change, use the Instance#ensureChangesSaved method:

NutrientViewer.load(configuration).then(async (instance) => {
  const createdAnnotations = await instance.create(newAnnotation);
  const [savedAnnotation] = await instance.ensureChangesSaved(
    createdAnnotations
  );
  console.log(savedAnnotation.id);
});

Configuration#autoSaveMode

If you configure nothing else, Nutrient Web SDK enables autosave and synchronizes local changes automatically. Use Configuration#autoSaveMode to configure exactly when saving occurs.

Save modeUse case
defaultIn standalone mode, autoSaveMode defaults to NutrientViewer.AutoSaveMode.IMMEDIATE. In server-backed mode, it defaults to NutrientViewer.AutoSaveMode.IMMEDIATE when Configuration#instant is true, and to NutrientViewer.AutoSaveMode.INTELLIGENT otherwise.
NutrientViewer.AutoSaveMode.IMMEDIATEChanges are saved whenever something changes, as long as they’re in a valid state. This is useful for real-time updates but increases server load.
NutrientViewer.AutoSaveMode.INTELLIGENTChanges are saved whenever a complete operation is detected. This merges multiple operations into one server request and saves, for example, on deselect.
NutrientViewer.AutoSaveMode.DISABLEDChanges are saved only when Instance#save runs. An Instance#exportPDF export doesn’t include unsaved annotations. In standalone mode, unsaved form field values may already be present, because NutrientViewer.Options.PDF_JAVASCRIPT is enabled by default.

Exports can omit unsaved annotations in other modes too. Under NutrientViewer.AutoSaveMode.INTELLIGENT, an undo, redo, or paste queues an annotation change without saving it, and Instance#exportPDF doesn’t flush that queue. Call Instance#save before you export, or Instance#ensureChangesSaved to wait for specific changes.

DWS Viewer API sessions use Nutrient Instant. In Nutrient Web SDK 1.22 and later, sessions loaded with NutrientViewer.load({ container, session }) use AutoSaveMode.IMMEDIATE by default. Pass instant: false or an explicit autoSaveMode to override this default.

Here’s an example of how to set the autoSaveMode in the configuration object passed to NutrientViewer.load():

NutrientViewer.load({ autoSaveMode: NutrientViewer.AutoSaveMode.INTELLIGENT });