pnpm, lerna and nx in the same repository

Three build orchestrators in one repository

The root package.json is named baklavajs-monorepo, is private, and declares type module. It declares a workspaces array pointing at packages/*, and there is a pnpm-workspace.yaml at the root doing the same job for pnpm, with [email protected] pinned as the packageManager. So the workspace is described twice, once for the general case and once for the tool actually in use. Then the scripts are driven by a different tool: build and test are lerna run build and lerna run test, with lerna 9 in the dev dependencies, and an nx.json sits at the root as well. Three orchestration layers for one set of packages is unusual, and nothing in the README explains which is load-bearing. For a consumer it does not matter, because published packages are the interface, but for anyone extending the project the answer is in the configuration rather than in the documentation.

Six packages, one of which is a bundle

The package table is the clearest description of the design. There are six entries: baklavajs and then five scoped packages under @baklavajs. The scoped ones are core, engine, interface-types, renderer-vue and themes. Core is where the functionality ships, and the README is explicit that anything else can be added a la carte by installing the plugins you want. The unscopeed baklavajs package is the exception and the convenience: it contains the core package as well as all the plugins, so it is the bundle for people who do not want to choose. That split is what makes the plugin system real rather than nominal. If the editor only worked as a whole package, the plugin story would be marketing; with core separated from each capability, you install the renderer without the themes, or the interface types without the engine, and the dependency graph reflects it.

Interface Types decides which nodes may connect

Of the four plugins, one is the reason the project is written in TypeScript. The Interface Types plugin adds types to node interfaces and allows connections only between the types you want to permit, and it can also automatically convert values from one type to another. That is a small sentence carrying the most design weight on the page. In most node editors, connection validity is something the application checks at runtime and reports as an error after the fact. Here it is expressed in the node interface, so an incompatible connection is a type error rather than a warning, and the conversion capability means two nodes with different types can still connect if a conversion is declared. That is the difference between a graph editor that renders a diagram and one that enforces a schema. It is also the plugin that changes how you model your nodes, which is why it is worth deciding early whether it belongs in your graph.

Engine, renderer and themes are separate concerns

The other three plugins split along lines that map to three separate questions. The Engine plugin provides functions to run calculations with the graph, which is the execution half as opposed to the editing half; without it you have an editor and no way to evaluate what you drew. The Vue Renderer plugin displays the editor in the browser using Vue, and it is the reason the whole ecosystem is Vue-shaped: a project on another framework would be using the core and engine without a renderer, which is possible but means writing the view layer. Themes is a collection of pre-built themes, the most cosmetic of the four and the easiest to replace. The introduction describes the editor as easy to use together with the ability to create custom nodes, and says it puts a strong emphasis on extensibility which leads to a versatile plugin system. Between the four plugins, a project decides at install time how much of the editor it wants. The build and test scripts run through lerna across the workspace, and the playground script changes into packages/renderer-vue before starting its dev server.

Type safety is stated as an ecosystem-wide commitment

One sentence in the introduction explains the implementation choice: to guarantee type safety, the entirety of the BaklavaJS ecosystem is written in TypeScript. That is a stronger claim than most libraries make, because it covers the plugins and the renderer and not only the core, and it is what makes the Interface Types plugin possible in the first place. If the renderer were JavaScript, the types a node declares would stop being trustworthy at the boundary where the graph is drawn. The repository supports the claim with tooling rather than assertion: eslint and typescript-eslint with eslint-plugin-vue and vue-eslint-parser for linting TypeScript and Vue sources together, prettier with a .prettierrc, typedoc with its own tsconfig for API documentation, and vitepress for the documentation site with docs:dev and docs:build scripts. The docs are generated and the code is checked, which is a more reliable combination than a promise in a README.

The v1 line is still linked from the front page

There is a short section between the documentation link and the sponsors that points at the previous version: the old BaklavaJS can be found on a v1 branch of the same repository. That is worth noting for two reasons. It tells you the project has crossed a major boundary recently and that the v2 line is what the packages table and the demo describe, so a tutorial or example you find elsewhere may be showing v1 behavior. And it means the v1 code is still in the repository rather than in a separate one, so the history is continuous and the tags for both lines are in the same place. The documentation site is at newcat.github.io/baklavajs, and the online demo runs in a CodeSandbox rather than being hosted by the project, which is a reasonable choice for something that has to boot in a browser.

Where BaklavaJS is the wrong choice

Four cases. The first is a React project. The renderer is the Vue plugin, so without it you have core and engine and no editor, which means writing the entire view layer yourself and losing the package that makes adoption fast. The second is a team wanting to execute the graph. The Engine plugin provides functions to run calculations with the graph, and nothing in the README describes scheduling, error handling inside a node, persistence of runs or resumability, so if your nodes do real work with side effects this is the editor half of a system you still have to build. The third is a project that has already standardized on another node editor. Graph editors accumulate data formats, and migrating a saved graph from one library's serialization to another is real work that the plugin story does not address. The fourth is a library consumer expecting a stable API across major versions. The v1 branch is still linked from the front page of v2, which is normal and also a reminder that a v3 would present the same way.

Editorial conclusion

BaklavaJS suits a Vue team building a visual editor, a dataflow tool or a node-based configuration screen that needs typed connections between nodes and an execution engine for the graph. It does not suit a React project, since the renderer is the Vue package, and it is only the editing half of a system if your nodes have side effects. Before adopting, install either the full baklavajs bundle or core plus the plugins you need, decide whether Interface Types belongs in your model, and run the playground script to see the editor before wiring your own nodes to it.

Frequently asked questions

Official sources

1. License: MIT
2. newcat/baklavajs on GitHub
3. Project website
4. README
5. Releases