visual-json splits a JSON editor into a headless tree model and framework UI packs

A core library that knows nothing about React

The package table in the README is the clearest statement of what this project is. `@visual-json/core` is described as a headless tree model, operations and schema types. That word headless does the heavy lifting. The core holds the document as a tree, the operations that mutate it, and the types describing schemas, and it renders nothing.

Everything else is a rendering layer on top of that. `@visual-json/react` provides React UI components, `@visual-json/svelte` provides Svelte 5 components, and `@visual-json/vue` provides Vue components, each described as containing a TreeView, a FormView, a DiffView and more. The same three views in all three frameworks is the detail worth noting: the view set is the product, and the framework bindings are the distribution.

For a team choosing between them, that means the decision is not which editor to use but which framework you already write in. If your application is Svelte 5, the Svelte package is the one you install, and the core sits underneath it. The alternative approach, embedding a JSON editor as an iframe or a prebuilt script, would give you no access to the document model, no way to run your own operations against it, and no way to restyle the interface to match your product. That is the trade this architecture is built to avoid.

Three views over one document, not one text area

The view names hint at the interaction model. A tree view is the classic hierarchical browser for JSON, the form view is a schema-driven editor that renders a document as fields instead of raw text, and a diff view compares two documents side by side.

The form view is where schema awareness pays off, and the README describes the whole project as schema-aware. With a schema in hand, an editor can validate as you type, show the right type of control for a given value, and flag problems without the user needing to read a validation message. That is a completely different experience from a textarea with a JSON.parse call on save, and it is the reason a team might adopt a dedicated editor library rather than rolling a text area.

The diff view is the other one that pulls in users outside the developer population. Showing a structured difference between two versions of a configuration or a saved payload is something a text diff does badly, because the interesting change is often a moved key or a changed type rather than a changed line. The README does not document how the diff is computed or whether it is character-level, key-path-level or both, so that detail would need checking in the core package before you rely on it.

YAML and JSONC come in as separate packages and a VS Code extension

Two adjacent formats are handled without polluting the core. `@visual-json/yaml` is described as YAML support, covering parse, serialize and schema-detect for YAML files, and it is a distinct package rather than a built-in mode. `@visual-json/vscode` is a VS Code extension described as a visual editor with a tree sidebar, schema support, JSONC and YAML.

The JSONC mention in the extension is worth a note, since JSON with comments is what most configuration files actually are, and a strict JSON parser rejects them. Whether the core treats JSONC as a first-class format or the extension handles the comment stripping is not spelled out in the README, and that distinction determines whether a commented config survives a round trip through the editor. It is the kind of thing to test with a real file before shipping the extension to a team.

The extension also demonstrates the architecture working as intended. A VS Code extension is not a browser application, so the fact that the same views serve both the embedded web components and the editor sidebar is direct evidence that the headless core is genuinely separate from the rendering layer.

A pnpm monorepo built on turbo and vitest

The repository is a pnpm workspace with turbo driving the build. The root `package.json` gives the pipeline away: build, dev and lint all run as `turbo run` across packages, type checking runs `turbo run check-types`, and the test script is a single `vitest run` at the root. There is a `pnpm-workspace.yaml`, a `turbo.json`, a `vitest.config.ts` and a `tsconfig.json` at the top level, plus a `scripts/` directory that holds a `sync-version.mjs` script wired to a `version:sync` npm script.

pnpm install
pnpm build
pnpm dev

Those are the development commands the README gives, and they are development commands for working on the project itself, not for consuming it. The `packageManager` field pins pnpm to 10.30.1 and the `engines` field requires Node 18 or newer, with TypeScript pinned to 5.9.3. Husky is installed through a `prepare` script and `lint-staged` runs Prettier on staged TypeScript, Svelte and Vue files, so the formatting rules are enforced by a commit hook rather than by convention.

The `examples/` directory holds a `react/`, a `svelte/` and a `vue/` example, which is the fastest way to see the intended integration shape for each framework before writing your own.

The 0.x version line is the main risk to plan around

The release list is short and stays below 1.0. v0.3.0 and v0.3.1 both landed on 2026-03-03, and v0.4.0 followed on 2026-04-08. The last push to the repository was on 2026-09-16, so work has continued since the last tag, and the CHANGELOG.md at the top level is where those unreleased changes are described.

That gap between the latest release and the latest commit is the thing to factor in. A consumer pinning to a published version gets code from April, while the branch has moved on since. Depending on whether the project publishes prerelease tags, you may be able to track the branch more closely, but the README does not say, and the `version:sync` script in `scripts/` suggests versioning is coordinated across the packages in the workspace rather than per package.

The Apache-2.0 licence is the other thing to settle early. It is a permissive licence covering modification, redistribution and commercial use, with the requirement to preserve notices and state changes. That is a reading of the identifier rather than legal advice, but it does matter for one specific decision here: if you embed the editor inside a commercial product, the Apache-2.0 patent grant and the notice obligations are the parts to look at properly, and they differ from the MIT terms a team might assume from a Vercel Labs experiment.

Where this is the wrong choice

There are two situations where visual-json is the wrong tool, and both are about scope rather than quality.

The first is when you need a working editor this week. This is a set of libraries, not an application. You assemble the tree view, form view and diff view yourself, you decide how the schema is supplied, you own the layout and the styling, and you own the save path. If the requirement is one field in an admin panel, that is a lot of integration for the outcome. A schema-driven form widget, or even a textarea with a validator, will serve that case with far less surface area.

The second is when the document model is not JSON-shaped. The core is a tree model for JSON, and the YAML package extends that with parsing and serialization for YAML files, including schema detection. It does not describe support for other structured formats, and it does not describe round-trip preservation of formatting or comments in the core itself. If your users edit TOML, INI, or a proprietary config, the assumption that this library covers it does not hold.

A third, milder point: the README is a package index, not documentation. The full documentation lives at visual-json.dev, and the API details you need to evaluate a headless tree model, the operation set, or how a schema is passed in, are not in the repository readme. Budget time to read the docs before committing to it, because the interesting questions are exactly the ones the readme leaves open.

Editorial conclusion

visual-json fits a product team that needs to let users edit structured JSON in the browser, wants schema awareness, and would rather ship their own components than a fixed opinionated editor UI. It does not fit a team that wants a single install-and-go widget, since the work is in assembling the tree view, form view and diff view yourself, and the version numbers stay below 1.0. Before adopting it, install the packages with pnpm, read the `packages/@visual-json/core` tree model and operation API to confirm it matches your document shape, and check the CHANGELOG.md for breaking changes, since the last release was v0.4.0 on 2026-04-08 while the last push was on 2026-09-16.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. vercel-labs/visual-json on GitHub