Skip to content

Getting started

This chapter covers the minimum needed to run SciFlow locally, install the packages, and embed the web components in any page.

1. Prerequisites

  • Node.js 22 or newer (matches CI).
  • npm 9+ (workspace-aware).
  • Optional: Python 3.11 + MkDocs if you plan to preview these docs locally.

Quick environment check

node --version   # expect v22.x
npm --version    # expect 9.x or newer

2. Registry

The packages this chapter installs — @sciflow/editor-start, @sciflow/editor-core and @sciflow/schema-prosemirror — are published to the public npm registry, along with @sciflow/schema-core. No .npmrc entry, scope mapping, or credential is required; npm install resolves them like any other public package.

One @sciflow package is not on public npm yet

@sciflow/pandoc-ast and @sciflow/pandoc-web publish to the public registry as of 0.1.0 — npm install resolves them like the packages above. @sciflow/reader does not: npm install returns a 404 for it.

3. Install the packages

npm install @sciflow/editor-start
# optional lower-level APIs
npm install @sciflow/editor-core @sciflow/schema-prosemirror
  • @sciflow/editor-start ships the <sciflow-editor> and <sciflow-formatbar> web components plus the demo bundle.
  • @sciflow/editor-core exposes the Editor class, command runner, and sync strategy contracts for framework-specific integrations.
  • @sciflow/schema-prosemirror exports the authoring schema and JSON helpers.

4. Build once locally (repository contributors)

If you’re developing inside the SciFlow repo (cloned from Git), install once and bundle locally:

npm install
npx nx bundle @sciflow/editor-start

This command creates packages/editor/start/dist/bundle/sciflow-editor.js, which demos and downstream applications can load. Skip this step when using the published package in another project because the installed package includes the bundle.

5. Open the demo

Online demo available

You can try the editor in your browser without cloning the repo or running any local tooling.

For a local build, any static server works:

npx http-server .

Open http://localhost:8080/packages/editor/start/demo/index.html. The page registers <sciflow-editor> from the new bundle and loads a placeholder manuscript.

Fast rebuild loop

Run npx nx bundle @sciflow/editor-start --watch in one terminal and refresh the demo page after each save.

6. Embed the web component

<!-- Local repo bundle (after running nx bundle) -->
<script type="module" src="/packages/editor/start/dist/bundle/sciflow-editor.js"></script>

<!-- OR in a bundler (Vite, Webpack, etc.): -->
<!-- import '@sciflow/editor-start/bundle'; -->

<!-- OR: installed package bundle via script tag -->
<!-- <script type="module" src="/node_modules/@sciflow/editor-start/dist/bundle/sciflow-editor.js"></script> -->

<sciflow-formatbar for="editor"></sciflow-formatbar>
<sciflow-editor id="editor"></sciflow-editor>

<script type="module">
  const editor = document.getElementById('editor');

  editor.doc = {
    doc: {
      type: 'doc',
      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello SciFlow!' }] }],
    },
    files: [],
    references: [],
  };

  editor.addEventListener('editor-change', (event) => {
    const { doc, files, references } = event.detail;
    // Persist doc/files/references to your backend or local storage
    console.debug('Updated doc', { doc, files, references });
  });
</script>

7. Enable equation rendering (optional)

The math feature (insert equations, TeX) and the footnote feature are included in the default feature set. To render equations as SVG in the editor, add the MathJax script to your page:

<!-- Add before or with your other scripts -->
<script defer src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-svg.js"></script>

Without this script, math nodes show a placeholder and the raw TeX; the document still saves and loads correctly. See Troubleshooting if equations do not render.

8. Next steps