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

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

<script type="module" src="/packages/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 = {
    type: 'doc',
    content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello SciFlow!' }] }],
  };

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

7. Next Steps