Pintora: a text-to-diagrams library where the plugin API is the point

What Pintora is, and who it is aimed at

Pintora is an extensible JavaScript text-to-diagrams library that works in both browser and Node.js. The name is Spanish for female painter, which is the sort of detail that tells you the project has a personality, and the description of the goal is that expressing your thoughts in a diagram is better than a thousand words, so with the help of pintora.js you can create diagrams with intuitive text.

The lineage is declared: heavily inspired by Mermaid.js and PlantUML. The roadmap shows the PlantUML influence directly, with entries for a PlantUML style Component diagram and a PlantUML style Activity Diagram.

The output targets are what makes it a library rather than a script. On the browser side it outputs SVG or Canvas. On the Node.js side it outputs PNG, JPG or SVG files. So the same source can be rendered into a live preview in a page and into a file in a build pipeline, and the browser and Node paths are the same codebase rather than two implementations.

One property is called out specifically: outputs are clean and self contained, and won't pollute the page with global style. That is a real design constraint for a browser diagram library, because the naive approach of injecting a style tag with a global selector breaks the host page, and a library that has to be embedded in someone else's documentation site cannot do that.

The homepage is pintorajs.vercel.app, which hosts both the documentation and a live editor. The primary language is TypeScript, the licence is MIT, and the topic tags are diagram, diagram-as-code and mermaidjs. The repository is not archived, with the last push on 2026-10-14 and the most recent release v0.8.2 on 2026-02-13.

Eight diagram types, and the ones that came from which inspiration

The diagram type list is the concrete answer to what you can actually draw.

Sequence Diagram and Entity Relationship Diagram are the two that carry the checkmarks at the top of the roadmap, alongside the Node.js CLI, which tells you these were the first two and the CLI was the first infrastructure piece. The PlantUML style Component diagram and PlantUML style Activity Diagram follow, then Mind Map, Gantt Diagram and Class Diagram, and finally DOT Diagram.

The DOT entry is the interesting one because it is a different kind of thing. DOT Diagram is one of the eight listed types, and it is the outlier in the set. That is an unusual inclusion for a text-to-diagrams library, and it reads as a deliberate way to cover the graph layouts the other types do not, without having to implement graph layout itself.

Mind Map and Gantt Diagram are the two that go beyond the UML and sequence diagram conventions, and both are the kind of thing people want for planning documents rather than for design documentation.

The Class Diagram entry is worth noting given the type's reach. Class diagrams are usually associated with statically typed languages, and this library is TypeScript, so a class diagram type fits the ecosystem it comes from.

Eight types is a compact catalogue, and larger than the number of diagram kinds most people actually use, which is usually two or three. The trade-off is visible in the roadmap, where the first eight are checked and the remaining two are not.

The two unchecked items are Universal style customization solution, and Load diagram implementation and canvas renderer only when needed. Both matter for a library that renders diagrams on a page. The first is about the ability to restyle the output consistently across diagram types, which is the classic problem with this family of tools, where each diagram type grows its own theme. The second is about bundle size, deferring the diagram implementation and the canvas renderer until they are actually needed, which is a tree shaking and code splitting concern that only matters once you are embedding it in a page.

The plugin system is the feature, not an extra

The modular and highly extensible entry in the features list is the one that distinguishes Pintora from a fixed diagram library. It provides a plugin system for diagram developers to write and distribute their own diagrams, and there is a tutorial for it at the documentation site, Write a custom diagram.

The distinction that matters is between being extensible and being forkable. A library you can fork is a library where adding a diagram type means copying the whole codebase, maintaining a divergent fork and re-merging every upstream change. A library with a plugin API means adding a diagram type means writing one module and publishing it, while the core keeps moving.

The related projects list shows the library already being picked up by other tooling. gatsby-remark-pintora is a Gatsby remark plugin for converting pintora code blocks into diagrams in markdown files. pintora-stencil is a web component for showing a pintora diagram preview, added to a website simply by importing some script tags. obsidian-pintora, created by someone else, is an Obsidian plugin based on Pintora that lets users create diagrams using Pintora syntax directly in the Obsidian editor, and the description of it claims it is local, secure, fast and easy to use.

The Obsidian case is the clearest demonstration. An Obsidian plugin, a Gatsby remark plugin and a stencil web component are three different host environments, and all three are built on the same library rather than on a fork of it.

There is also an Observable notebook entry, which uses pintora in an interactive notebook, and a VSCode extension, pintora-vscode, providing syntax highlight and preview support for.pintora files and for markdown code fences.

The plugin architecture is also what explains the output targets. A plugin has to be able to run in a browser and in Node.js, and to produce SVG or Canvas in one and PNG, JPG or SVG files in the other, and that constraint is what forces the rendering core to be environment agnostic.

The monorepo: pnpm workspaces, Turborepo and jest

The package.json in the repository root is marked private and described as the monorepo for the pintora project, and it is the clearest available picture of the internal structure.

The workspaces are the packages directory, the demo and the website. The demo directory is a separate Vite application with its own cypress.config.ts and a live-editor/ subdirectory, and the website directory is the documentation site that produces the pages at pintorajs.vercel.app. The packages/ directory holds the actual libraries.

The build is Turborepo. The compile script runs turbo run compile with a concurrency of 10, and there is a separate compile:browser script that filters out @pintora/cli. That filter is the design statement of the whole project: the CLI package pulls in Node.js specific dependencies, and the browser bundle must not include it. The watch script does the same with no-cache, and there is a watch:browser variant that additionally filters to @pintora/diagrams with --no-deps, so editing the diagram implementations does not rebuild their dependents.

Tests are jest, run through pnpm exec jest, with a jest.config.base.js and a jest.config.js at the root, and esbuild-jest in the dev dependencies, so the transform is esbuild rather than the TypeScript compiler. Coverage goes to codecov, with a ci:coverage script that adds the --ci flag and an upload-coverage script that pushes coverage-final.json.

There is a second jest configuration, the base one, which suggests the tests are split between a shared base config and a per-project one, and the harness/ directory at the top level is likely where the shared test harness lives. The demo directory has its own cypress setup, so end to end tests of the demo application run under Cypress rather than jest.

Releases are managed with changesets. The @changesets/cli and @changesets/changelog-git dev dependencies, the .changeset/ directory and the CHANGELOG.md at the root are the standard arrangement, and the recent tags follow the changesets convention with a version like v0.8.2.

Two more things in the tooling tell you where the project is going. There is an .ai/ directory and scripts/ai-sync.mjs with ai:link and ai:lint scripts, alongside an AGENTS.md, which suggests the repository has been wired up for AI-assisted development. And renovate.json means dependencies are updated automatically. The code style is enforced by eslint with a flat config in eslint.config.mjs and prettier with a .prettierrc.yml, and lint-staged runs both on every staged TypeScript and JavaScript file through a husky hook.

What the documentation does not tell you, and where to look instead

The project's own documentation is a Vercel deployment rather than a set of files in the repository, and the README points at it for details and at a live editor for trying things out. The website/ directory is the source of those docs, and the build-site script builds it.

What is not in the README is the API surface. There is no usage snippet, no function signature, no configuration example. For a library where the plugin API is the headline feature, that is a significant gap in the front page, and it means you have to go to the docs site to learn how to register a plugin, how to configure a theme, or how to call the renderer in Node.js. The tutorial link for writing a custom diagram is the most important pointer in the document, because it is the thing you would need to read before deciding whether this library is extensible in the way you need.

The configuration story is also thin in the README. The roadmap has a checked entry for Theme config, and the v0.8.0 release title is A look in the style, which suggests the theming work landed and was a visible change. But the unchecked Universal style customization solution entry tells you that a single consistent styling layer across all diagram types is not there yet, and if your use case is one diagram type in a product with a design system, that gap is the one that will bite.

The Node.js CLI is also not described in the README beyond its existence as a checked roadmap item. It is a separate package, @pintora/cli, since the browser compile script explicitly filters it out, and it is the route you would use for generating diagram files in a build.

For an evaluation, the practical reading is that Pintora is a well organised, actively developed project with a clear architectural bet, where the bet is the plugin system. If your requirement is covered by one of the eight shipped types, the risk is low and the integration is a diagram file plus a renderer call. If your requirement is a type that does not exist, then the plugin tutorial is the deciding document, and you should read it before anything else.

Editorial conclusion

Pintora fits a team that wants diagrams from text without adopting Mermaid's syntax wholesale, and especially fits a developer who wants to add a diagram type of their own through the documented plugin path rather than forking the renderer. It is the wrong choice if you need a diagram type neither library ships, unless you are willing to write the plugin, and it is the wrong choice if you need a stable 1.0 API, since the roadmap still lists work to do. Before adopting, read the write a custom diagram tutorial and the packages/ directory layout, and check the two unchecked roadmap items, a universal style customization solution and lazy loading of the diagram and canvas renderer, since both affect how your output will look and how much you ship.

Frequently asked questions

Official sources

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