DocsGuidesSaving to Database

Saving to Database

Saving on every keystroke is expensive and unstable. Use `onDebouncedUpdate` for persistence.

Why debounced save

  • Reduces database write frequency.
  • Avoids race conditions in distributed systems.
  • Preserves responsive typing experience.

Example integration

import { HybricEditor } from 'hybricmark'
 
async function saveToAPI(json: unknown) {
  const res = await fetch('/api/docs/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ document: json }),
  })
 
  if (!res.ok) {
    throw new Error('Failed to save document')
  }
}
 
export function DocumentEditor({ initialDoc }: { initialDoc: unknown }) {
  return (
    <HybricEditor
      content={initialDoc}
      debounceMs={800}
      onDebouncedUpdate={({ editor }) => {
        void saveToAPI(editor.getJSON())
      }}
    />
  )
}

Operational advice

  • Start at `debounceMs=800` and tune with real traffic.
  • Include `updatedAt` and revision/version fields in payload.
  • Keep saves idempotent (`upsert` with revision checks).
  • Add retry logic for transient network failures.

HTML vs JSON storage

FormatProsConsRecommended use
HTMLEasy direct rendering in web views.Weak block identity, hard to patch by block.Read-only rendering/export snapshots.
JSONStable structure, preserves block IDs and semantic nodes.Needs renderer/transformer for non-editor channels.Primary database format for product features.
For HybricMark products, persist JSON as source of truth, and derive HTML only when needed.
Headless DesignCustom Styling