@fiduswriter/editor

The ProseMirror-based editor component of Fidus Writer

This package is part of the Fidus Writer ecosystem. It provides the main browser-based collaborative editor: real-time collaboration, comments, tracked changes, footnotes, citations, end-to-end encryption, menus, dialogs, and clipboard import/export.

Key features

• Real-time collaboration — WebSocket-based collaborative editing with participant carets, diffs, and versioning.
• Track changes — Accept/reject individual changes with full change history.
• Comments — Threaded commenting with annotation marks and resolution.
• Footnotes — Inline footnote editing with proper layout.
• Citations — Citeproc-js based citation rendering with bibliography generation.
• E2EE — End-to-end encryption with key management and passphrase support.
• Clipboard — Paste from Word, LibreOffice, Google Docs with format preservation.
• Tables, figures & equations, code blocks — Full editing support.

Demo

Try the standalone browser demo that runs without a backend server:

Installation

npm install @fiduswriter/editor

Exports

Usage

The library can be used in two modes: static (no backend server, like the standalone demo) or server-backed (the classic Fidus Writer Django setup).

Static usage

For a statically served editor, use createStaticEditor. It sets up the runtime globals, loads locale strings, creates the in-memory app shell, and initializes the editor.

import {createStaticEditor} from "@fiduswriter/editor/static_editor"
import {ExportFidusFile} from "@fiduswriter/editor/exporter/native/file"

const editor = await createStaticEditor({
    locale: "en",
    username: "Demo User",
    documentData: async () => ({
        doc: {
            v: 0,
            content: { /* ProseMirror document JSON */ },
            comments: {},
            bibliography: {},
            images: {}
        },
        doc_info: {
            id: 1,
            rights: "write",
            is_owner: true,
            path: "",
            updated: new Date(),
            dir: "ltr",
            access_rights: "write",
            e2ee: false,
            owner: {id: 1, name: "Demo User", type: "user", contacts: []}
        },
        time: Date.now()
    }),
    documentStyles: [
        {
            title: "Standard article",
            slug: "standard-article",
            contents: "",
            documentstylefile_set: []
        }
    ],
    exportTemplates: [
        {
            title: "Fidus Writer",
            file_type: "fidus",
            template_file: "/static/export-templates/template.fidus"
        }
    ],
    documentTemplates: {
        "1": {title: "Standard article"}
    }
})

// Download the document as a .fidus file.
const doc = editor.getDoc({use_current_view: true})
new ExportFidusFile(
    editor.app,
    doc,
    editor.mod.db.bibDB,
    editor.mod.db.imageDB,
    false
)

createStaticEditor accepts a StaticEditorConfig. The most important options are:

• locale — locale code, e.g. "en".
• username / user — either a display name or a complete EditorUser object.
• documentData — async function returning {doc, doc_info, time}.
• documentStyles, exportTemplates, documentTemplates — template/style fixtures used by the document template and export dialogs.
• initialImages — optional map of image entries to prime the image database.
• getDocContent — optional callback returning the current document content; used to derive the correct document template for downloads.
• onSaveDocument — optional callback invoked when the editor tries to save.
• staticBasePath — base URL for resolving CSS and static assets.
• plugins — extra editor plugins, e.g. [["demo", {MyPlugin}]].
• userPreferences — optional map of user preferences that enable inline editing helpers. Recognized keys are inline_references (type @ to insert a citation/cross-reference) and inline_math (type $ to insert an equation).

loader: { ".gz": "file" }

For more control, build the app shell manually with createStaticApp and then instantiate the Editor class yourself:

import {Editor, createStaticApp} from "@fiduswriter/editor"

const app = await createStaticApp({
    locale: "en",
    gettext: msgid => msgid,
    csl,
    documentData: async () => ({doc, doc_info, time: Date.now()})
})

const editor = new Editor({app, user}, "", "1", [])
await editor.init()

Server-backed usage

When a backend server is available, construct Editor directly with an EditorApp object that provides API connectors, settings, and the CSL engine. This is how the main Fidus Writer Django application uses the library.

import {Editor} from "@fiduswriter/editor"

const editor = new Editor(
    {app, user},
    "/documents/123",
    "123",
    [["my-plugin", {MyPlugin}]]
)
await editor.init()

The app object must satisfy the EditorApp interface:

• name — application name.
• routes — route table used by the editor router.
• goTo(url) — navigate to a different route.
• isOffline() — return whether the browser is offline.
• settings — editor settings such as EDITOR_SAVE_MODE, LANGUAGE, E2EE_MODE, and APPS.
• csl — a CSL engine instance.
• apiConnectors — connectors for document, documentImport, image, bibliography, and contacts APIs.
• bibDB and imageDB — database instances for bibliography and images.

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm run typecheck    # Check types without emitting
npm run lint         # Lint with ESLint
npm run format:check # Check formatting with Prettier
npm test             # Run the test suite