Skip to content

Getting Started

This chapter walks through the bare minimum required to run SciFlow locally, point npm at the scoped 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. Configure the Scoped Registry

All @sciflow/* packages are published to the SciFlow GitLab registry. Add the scope mapping to your project’s .npmrc:

echo @sciflow:registry=https://gitlab.com/api/v4/projects/75140004/packages/npm/ >> .npmrc

Private registry

Keep the registry URL in sync with the credentials provided for your deployment. If you use an .npmrc checked into source control, make sure it only contains non-secret information.

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 (repo 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 emits packages/editor/start/dist/bundle/sciflow-editor.js, the file you reference from demos or downstream apps. If you are consuming the published package in another project, you can skip this step because the bundle ships with the install.

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 .

Visit http://localhost:8080/packages/editor/start/demo/index.html. The page registers <sciflow-editor> from the freshly built bundle and hydrates it with 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 footnote feature are included in the default feature set. To actually 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