{"id":14046,"library":"sprotty","title":"Sprotty Diagramming Framework","description":"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.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/eclipse-sprotty/sprotty","tags":["javascript","eclipse","graphics","diagram","modeling","visualization","svg","typescript"],"install":[{"cmd":"npm install sprotty","lang":"bash","label":"npm"},{"cmd":"yarn add sprotty","lang":"bash","label":"yarn"},{"cmd":"pnpm add sprotty","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency injection container. Sprotty relies heavily on InversifyJS for its modular architecture and configuration. A specific version is often required to avoid compatibility issues.","package":"inversify","optional":false},{"reason":"Required for InversifyJS to function correctly, particularly for dependency injection decorators.","package":"reflect-metadata","optional":false}],"imports":[{"note":"Sprotty uses InversifyJS for dependency injection; `Container` and `ContainerModule` are imported directly from `inversify`, not `sprotty` itself.","wrong":"import { Container } from 'sprotty';","symbol":"Container","correct":"import { Container, ContainerModule } from 'inversify';"},{"note":"`LocalModelSource` is the default client-side model source. `SprottyDiagramInitializer` orchestrates the diagram setup. `TYPES` are DI keys and `loadDefaultModules` loads core Sprotty functionality.","wrong":"import { LocalModelSource } from 'sprotty-protocol';","symbol":"LocalModelSource","correct":"import { LocalModelSource, SprottyDiagramInitializer, TYPES, loadDefaultModules } from 'sprotty';"},{"note":"Core model elements like `SGraph`, `SNode`, and `SEdge` are defined in the `sprotty-protocol` package, which provides the JSON-serializable data model for diagrams.","wrong":"import { SGraph } from 'sprotty';","symbol":"SGraph","correct":"import { SGraph, SNode, SEdge } from 'sprotty-protocol';"}],"quickstart":{"code":"import 'reflect-metadata'; // Required by InversifyJS\nimport { Container, ContainerModule } from 'inversify';\nimport { SGraph, SNode, SEdge } from 'sprotty-protocol';\nimport {\n  ConsoleLogger,\n  LogLevel,\n  LocalModelSource,\n  TYPES,\n  SprottyDiagramInitializer,\n  loadDefaultModules,\n  configureModelElement,\n  RectangularNodeView,\n  RectangularNode,\n  PolylineEdgeView,\n  SLabelView\n} from 'sprotty';\n\nconst diagramModule = new ContainerModule((bind, unbind, isBound, rebind) => {\n  // Bind custom types to Sprotty's DI system\n  bind(TYPES.ILogger).to(ConsoleLogger).inSingletonScope();\n  rebind(TYPES.LogLevel).toConstantValue(LogLevel.warn);\n\n  // Load core Sprotty modules\n  loadDefaultModules(bind, unbind, isBound, rebind);\n\n  // Configure model elements and their views\n  configureModelElement(bind, RectangularNode.TYPE, RectangularNode, RectangularNodeView);\n  configureModelElement(bind, SEdge.TYPE, SEdge, PolylineEdgeView);\n  configureModelElement(bind, SLabelView.TYPE, SLabelView, SLabelView);\n\n  // Bind the ModelSource for client-side diagramming\n  bind(TYPES.ModelSource).to(LocalModelSource).inSingletonScope();\n});\n\nexport function setupSprottyDiagram(containerId: string) {\n  const diagramContainer = document.getElementById(containerId);\n  if (!diagramContainer) {\n    console.error(`Container element with ID '${containerId}' not found.`);\n    return;\n  }\n\n  const container = new Container();\n  container.load(diagramModule);\n\n  const modelSource = container.get<LocalModelSource>(TYPES.ModelSource);\n  const initializer = new SprottyDiagramInitializer(diagramContainer, modelSource, container);\n\n  initializer.initialize();\n\n  const initialModel: SGraph = {\n    type: 'graph',\n    id: 'graph',\n    children: [\n      {\n        type: RectangularNode.TYPE,\n        id: 'node1',\n        x: 100, y: 100, width: 80, height: 50,\n        children: [{ type: SLabelView.TYPE, id: 'label1', text: 'Node 1' }]\n      },\n      {\n        type: RectangularNode.TYPE,\n        id: 'node2',\n        x: 300, y: 150, width: 80, height: 50,\n        children: [{ type: SLabelView.TYPE, id: 'label2', text: 'Node 2' }]\n      },\n      {\n        type: SEdge.TYPE,\n        id: 'edge1',\n        sourceId: 'node1',\n        targetId: 'node2'\n      }\n    ]\n  };\n\n  modelSource.setModel(initialModel);\n\n  console.log('Sprotty diagram initialized and model set.');\n}\n\n// To run this, you would typically call it from an HTML page:\n// <div id=\"my-sprotty-container\" style=\"width: 600px; height: 400px; border: 1px solid black;\"></div>\n// <script type=\"module\">import { setupSprottyDiagram } from './your-script-path'; setupSprottyDiagram('my-sprotty-container');</script>\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Sprotty 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"Sprotty 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.","severity":"gotcha","affected_versions":">=0.x"},{"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.","message":"Sprotty'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.","severity":"gotcha","affected_versions":">=1.x"},{"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.","message":"Choosing 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.","severity":"gotcha","affected_versions":">=0.x"}],"env_vars":null,"search_vec":"'1.0.0':82 '1.4.0':64 'activ':68 'anim':50 'applic':34 'architectur':90 'base':97 'built':15,48 'built-in':47 'cadenc':70 'capabl':103 'client':37,54,89 'client-side-on':53 'client/server':59 'code':117 'complex':124 'comprehens':141 'configur':93 'creat':28 'css':139 'current':61 'declar':134 'definit':136 'depend':94 'develop':122 'diagram':2,13,146 'differenti':85 'distribut':58 'eclips':144 'ecosystem':107 'editor':126 'enabl':120 'excel':40 'extens':25 'fast':42 'foundat':26 'framework':3,14,39 'generat':9 'graphic':30,125,145 'high':92 'includ':86 'inject':95 'integr':102 'interact':29 'inversifyj':99 'javascript':143 'jsx':132 'key':84 'langium':110 'languag':112 'leverag':131 'like':108 'lsp':115 'maintain':66 'matur':79 'minor':73 'model':147 'next':8 'next-gener':7 'open':11 'open-sourc':10 'per':75 'primarili':19 'protocol':114 'provid':22 'reach':78 'reactiv':88 'releas':69,83 'render':45 'rich':36 'robust':24 'runtim':60 'scalabl':43 'seamless':101 'server':113 'sever':72 'side':55 'sinc':77 'sophist':128 'sourc':12 'sprotti':1,4 'standard':138 'style':142 'support':51 'svg':44,149 'system':96 'technolog':18 'theia':119 'tool':105 'typescript':20,150 'version':63,74 'view':31,135 'visual':129,148 'vs':116 'web':17,33 'xtext':109 'year':76","created_at":"2026-04-20T01:57:39.010811+00:00","updated_at":"2026-04-20T01:57:39.010811+00:00","problems":[{"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.","cause":"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.","error":"Error: No binding found for key..."},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'appendChild')"},{"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`).","cause":"InversifyJS, which Sprotty uses for dependency injection, requires the `reflect-metadata` polyfill to be imported globally or at the top of your entry file.","error":"ReferenceError: Reflect is not defined"},{"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.","cause":"The TypeScript compiler cannot locate the Sprotty package or its type definitions, often due to incorrect installation, missing `@types` packages, or misconfigured `tsconfig.json`.","error":"TS2307: Cannot find module 'sprotty' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://sprotty.org","github":"https://github.com/eclipse-sprotty/sprotty","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/sprotty","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}