sprotty

library1.4.0jsnpmunverified

Sprotty is a next-generation, open-source diagramming framework built with web technologies, primarily TypeScript. It provides a robust, extensible foundation for creating interactive graphical views in web applications and rich clients. The framework excels in fast, scalable SVG rendering with built-in animations, supporting both client-side-only and distributed (client/server) runtimes. Currently at version 1.4.0, it maintains an active release cadence with several minor versions per year since reaching maturity with its 1.0.0 release. Key differentiators include its reactive client architecture, a highly configurable dependency injection system (based on InversifyJS), and seamless integration capabilities with tools and ecosystems like Xtext, Langium, the Language Server Protocol (LSP), VS Code, and Theia, enabling the development of complex graphical editors and sophisticated visualizations. It leverages JSX for declarative view definition and standard CSS for comprehensive styling.

web-framework serialization

npm install sprotty

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPROTTY

sprotty

web-frameworkjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Container

✓ import { Container, ContainerModule } from 'inversify';

✗ import { Container } from 'sprotty';

Sprotty uses InversifyJS for dependency injection; `Container` and `ContainerModule` are imported directly from `inversify`, not `sprotty` itself.

LocalModelSource

✓ import { LocalModelSource, SprottyDiagramInitializer, TYPES, loadDefaultModules } from 'sprotty';

✗ import { LocalModelSource } from 'sprotty-protocol';

`LocalModelSource` is the default client-side model source. `SprottyDiagramInitializer` orchestrates the diagram setup. `TYPES` are DI keys and `loadDefaultModules` loads core Sprotty functionality.

SGraph

✓ import { SGraph, SNode, SEdge } from 'sprotty-protocol';

✗ import { SGraph } from 'sprotty';

Core model elements like `SGraph`, `SNode`, and `SEdge` are defined in the `sprotty-protocol` package, which provides the JSON-serializable data model for diagrams.

This quickstart sets up a basic client-side Sprotty diagram using a local model source, demonstrating dependency injection configuration, model definition with a simple graph, two nodes, and an edge, and rendering it into a specified HTML element.

import 'reflect-metadata'; // Required by InversifyJS import { Container, ContainerModule } from 'inversify'; import { SGraph, SNode, SEdge } from 'sprotty-protocol'; import { ConsoleLogger, LogLevel, LocalModelSource, TYPES, SprottyDiagramInitializer, loadDefaultModules, configureModelElement, RectangularNodeView, RectangularNode, PolylineEdgeView, SLabelView } from 'sprotty'; const diagramModule = new ContainerModule((bind, unbind, isBound, rebind) => { // Bind custom types to Sprotty's DI system bind(TYPES.ILogger).to(ConsoleLogger).inSingletonScope(); rebind(TYPES.LogLevel).toConstantValue(LogLevel.warn); // Load core Sprotty modules loadDefaultModules(bind, unbind, isBound, rebind); // Configure model elements and their views configureModelElement(bind, RectangularNode.TYPE, RectangularNode, RectangularNodeView); configureModelElement(bind, SEdge.TYPE, SEdge, PolylineEdgeView); configureModelElement(bind, SLabelView.TYPE, SLabelView, SLabelView); // Bind the ModelSource for client-side diagramming bind(TYPES.ModelSource).to(LocalModelSource).inSingletonScope(); }); export function setupSprottyDiagram(containerId: string) { const diagramContainer = document.getElementById(containerId); if (!diagramContainer) { console.error(`Container element with ID '${containerId}' not found.`); return; } const container = new Container(); container.load(diagramModule); const modelSource = container.get<LocalModelSource>(TYPES.ModelSource); const initializer = new SprottyDiagramInitializer(diagramContainer, modelSource, container); initializer.initialize(); const initialModel: SGraph = { type: 'graph', id: 'graph', children: [ { type: RectangularNode.TYPE, id: 'node1', x: 100, y: 100, width: 80, height: 50, children: [{ type: SLabelView.TYPE, id: 'label1', text: 'Node 1' }] }, { type: RectangularNode.TYPE, id: 'node2', x: 300, y: 150, width: 80, height: 50, children: [{ type: SLabelView.TYPE, id: 'label2', text: 'Node 2' }] }, { type: SEdge.TYPE, id: 'edge1', sourceId: 'node1', targetId: 'node2' } ] }; modelSource.setModel(initialModel); console.log('Sprotty diagram initialized and model set.'); } // To run this, you would typically call it from an HTML page: // <div id="my-sprotty-container" style="width: 600px; height: 400px; border: 1px solid black;"></div> // <script type="module">import { setupSprottyDiagram } from './your-script-path'; setupSprottyDiagram('my-sprotty-container');</script>

Debug

Known issues

breakingSprotty v1.0.0 removed all previously deprecated API, marking a significant transition out of the incubation phase into maturity. Codebases using pre-1.0.0 deprecated features will break.

fix

Review the `CHANGELOG.md` files for `sprotty` and `sprotty-protocol` packages to identify removed APIs and update your code to use their stable replacements. Rebuilding your project and addressing TypeScript errors is usually sufficient.

affects: >=1.0.0

gotchaSprotty relies on InversifyJS for dependency injection, and it's crucial to use a compatible version. The documentation specifically highlights that `inversify@^6.1.3` is important.

fix

Ensure your `package.json` specifies `inversify` with a compatible version, typically `^6.1.3` or as indicated by the latest Sprotty documentation. Always `npm install` or `yarn install` after changes.

affects: >=0.x

gotchaSprotty's future plans include transitioning to ECMAScript Modules (ESMs). While not a breaking change yet, it signals upcoming shifts in module resolution and bundling that may require changes to project setup.

fix

Stay informed about new major releases and changelogs. Be prepared to update build configurations (e.g., Webpack, ESBuild) and import statements when the official ESM transition occurs.

affects: >=1.x

gotchaChoosing between `LocalModelSource` and `DiagramServerProxy` is critical for diagram behavior. Using `LocalModelSource` expects a client-side model, while `DiagramServerProxy` necessitates a server connection (e.g., WebSocket) to fetch and update the model.

fix

Ensure the chosen `ModelSource` implementation (configured via InversifyJS) matches your application's architecture. For client-only diagrams, use `LocalModelSource`. For distributed diagrams, set up `DiagramServerProxy` and a corresponding server.

affects: >=0.x

Errors

Common errors & fixes

Error: No binding found for key...

This error originates from InversifyJS, indicating that a required dependency (identified by its key, often a `TYPES` constant or a class) has not been correctly bound in the DI container.

fix

Inspect your `ContainerModule` definitions. Ensure `loadDefaultModules` is called, and all custom model elements, views, and services have a corresponding `bind` statement. Check for typos in `TYPES` keys or class names. Refer to the 'Dependency Injection' section of Sprotty's documentation.

TypeError: Cannot read properties of undefined (reading 'appendChild')

This usually means the target HTML element where Sprotty is supposed to render the diagram was not found or was null when `SprottyDiagramInitializer` tried to access it.

fix

Verify that the `containerId` passed to `setupSprottyDiagram` (or similar initialization function) correctly matches the ID of an existing HTML `div` element in your DOM, and that the script runs after the DOM is fully loaded.

ReferenceError: Reflect is not defined

InversifyJS, which Sprotty uses for dependency injection, requires the `reflect-metadata` polyfill to be imported globally or at the top of your entry file.

fix

Add `import 'reflect-metadata';` at the very top of your application's entry TypeScript/JavaScript file before any other imports. Ensure `reflect-metadata` is installed (`npm install reflect-metadata`).

TS2307: Cannot find module 'sprotty' or its corresponding type declarations.

The TypeScript compiler cannot locate the Sprotty package or its type definitions, often due to incorrect installation, missing `@types` packages, or misconfigured `tsconfig.json`.

fix

Ensure `sprotty` and `sprotty-protocol` are installed. If using an older TypeScript version or complex setup, check `tsconfig.json` for `moduleResolution` and `typeRoots`. Modern setups rarely need `@types/sprotty` as types are shipped with the package.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

inversifyrequiredCore dependency injection container. Sprotty relies heavily on InversifyJS for its modular architecture and configuration. A specific version is often required to avoid compatibility issues.

reflect-metadatarequiredRequired for InversifyJS to function correctly, particularly for dependency injection decorators.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eclipse-sprotty/sprotty ↗

packagehttps://www.npmjs.com/package/sprotty ↗

homepagehttps://sprotty.org ↗