Skip to content

Packages & APIs

SciFlow publishes a small set of npm packages. Use this page to decide which one to consume and how they fit together.

Package Description When to use
@sciflow/editor-start Web components (<sciflow-editor>, <sciflow-formatbar>) plus the browser-ready bundle. Fastest way to embed the editor without wiring ProseMirror manually.
@sciflow/editor-core Editor runtime, command system, sync strategy contracts, and helper types. Framework integrations that need full control over rendering, storage, or collaboration.
@sciflow/schema-core Snapshot and JSON-schema generators with no ProseMirror dependency. Validating or generating SciFlow JSON snapshots outside an editor.
@sciflow/pandoc-ast Pandoc AST → ProseMirror document import. Turning Pandoc output (DOCX, Markdown, LaTeX, …) into a SciFlow document, when the AST already exists.
@sciflow/pandoc-web Browser Pandoc-WASM wrapper plus the <sciflow-pandoc-drop> element. Running Pandoc in the browser and feeding @sciflow/pandoc-ast without a server. The usual entry point for import.
@sciflow/reader Prebuilt SciFlow reader custom-element bundle (<sfo-reader>). Embedding a read-only rendering of a manuscript. Not published to npm — the @sciflow/reader-* libraries it is built from are private support packages, not for direct consumption.
@sciflow/schema-prosemirror Manuscript schema definition compatible with ProseMirror and SciFlow JSON snapshots. Validating or transforming content outside the editor, building import/export pipelines.

@sciflow/editor-start

  • Registers custom elements automatically when the bundle loads.
  • Ships a fully themed editor surface, formatter toolbar, and demo helpers (outline, references).
  • Provides reference implementations for sidebars so you can copy/paste patterns into your app.
  • Exposes setSciFlowThemeStyles() for global theme injection across all components.

@sciflow/editor-core

import { Editor } from '@sciflow/editor-core';

const editor = await Editor.create({
  docId: 'draft-42',
  sync: mySyncStrategy,
  initialDoc,
  initialVersion: 0,
});

editor.mount(document.querySelector('#editor-root'));

Key APIs:

  • editor.getCommands() → immediate, flow, and availability checks.
  • editor.onDoc(handler) / editor.onSelection(handler) → push-style subscriptions.
  • SyncStrategy interface → plug your persistence/collaboration layer.

Sharing commands between runtimes

Both the web component and the core editor expose the same command runner. Recipes in the User Guide work in either environment — the only difference is how you access the runner (element.commands vs. editor.getCommands()).

@sciflow/schema-prosemirror

  • Exports the manuscript schema itself, plus generateJsonSchema() / generateSnapshotSchema() (JSON Schema for a document or a whole snapshot) and generateJatsBody().
  • Rehydrating snapshot JSON into a live node is ProseMirror's own API: Node.fromJSON(manuscript, json) from prosemirror-model. This package ships no wrapper for it.
  • Useful when validating documents on the server, writing migration scripts, or generating previews outside the editor.

@sciflow/schema-core

  • texToHeadingText(tex: string): string — reduces a TeX string to a plain-text approximation for surfaces that can't render math (a TOC entry, a PDF bookmark, an OJS title field). No ProseMirror dependency.

@sciflow/pandoc-web

import { convertFile } from '@sciflow/pandoc-web';

const { parseResult, media } = await convertFile(docxFile);

// A parse result is not an editor snapshot: check `doc`, then hand document and
// bibliography over together through the element's `doc` property.
if (parseResult.doc) {
  editor.doc = {
    doc: parseResult.doc,
    references: parseResult.references.map((reference) => ({
      id: reference.id,
      rawReference: reference.label ?? String(reference.csl?.title ?? reference.id),
      csl: reference.csl,
      mimeType: 'application/vnd.citationstyles.csl+json',
    })),
  };
}

<sciflow-editor>'s references is a read-only getter; the way in is the doc property, which accepts either bare document JSON or { doc, references?, files?, selection?, version? }. See Importing documents for the full normalization, including what happens to extracted media.

Key APIs:

  • <sciflow-pandoc-drop> — drop-zone element, emits sciflow-document / sciflow-status / sciflow-error.
  • convertFile(input, options) — DOCX / Markdown / LaTeX → { ast, parseResult, media, timings, … } in one call.
  • loadPandoc() — the raw PandocWasm instance for formats outside those three.
  • convertAstToBlob(ast, options) — the other direction: a Pandoc AST → a downloadable DOCX, ODT, EPUB, HTML, Markdown or LaTeX blob.

The Pandoc binary is ~58 MB and is fetched lazily on the first conversion, never on page load. See Importing documents for the full API, bundler configuration, and licensing notes.

@sciflow/pandoc-ast

  • parsePandocAST(pandocDocument, opts?, schemaOverride?) — Pandoc JSON AST → a fully JSON-serializable ParsePandocAstResult. No DOM, no filesystem, no network.
  • pandocRenderers, render, renderContent, ImportError — the renderer surface, for translating fragments or overriding how a Pandoc node type is handled.
  • SfNodeType, SfMarkType — string enums for the manuscript schema's node and mark names.
  • Re-exports manuscript from @sciflow/schema-prosemirror, so an importer needs only this one dependency.

Depend on it directly when the AST comes from somewhere other than the browser — a server-side pandoc -t json, a stored AST, or a worker. @sciflow/pandoc-web already depends on it.

Where to go next