Vega: a JSON visualization grammar whose docs and benchmarks live elsewhere

Vega is a grammar, not a set of chart helper functions

The unit of work in Vega is a JSON specification rather than a function call. You describe a visualization as a declarative format for creating, saving, and sharing interactive designs, and the runtime turns that description into an interactive view drawn with HTML5 Canvas or SVG. The choice has real consequences for how a team works. Specs are serializable artifacts, so a chart can be stored in a repository, reviewed in a diff, and shipped to a browser without any server side rendering code. The other side of that is that there is no bar_chart() helper to reach for, only a grammar to satisfy, so every mark, encoding, and interaction you want has to be expressed inside that JSON rather than assembled from prebuilt chart functions.

type module and lerna publish from-package decide how the package arrives

The root package.json names the package vega, marks private true so the root itself is never published, records the BSD-3-Clause license, and sets type module. The release path is npm run license followed by lerna publish from-package, which means each package under packages/ publishes on its own version rather than as one combined bundle. The docsbuild step copies vega.js, vega.min.js, vega-core.js, vega-core.min.js, and vega-schema.json out of packages/vega/build, so the file a browser loads is the rollup output with terser minification applied.

vega-schema.json is a build product, not an editor convenience

Validation is treated as a shipped artifact rather than an internal detail. The docsbuild step copies vega-schema.json next to the compiled bundles into docs/, and ajv at ^8.20.0 with ajv-formats at ^3.0.1 sits in devDependencies, which is the JSON Schema validation pair the project uses. What you get from that is a machine checkable definition of the grammar you can point an editor or a CI step at, which is the cheapest way to catch a malformed spec before anything is rendered. The catch is where the schema lives. It is produced from the build output, so a CI job cannot validate specs against this repository alone; it has to install the published package and read the schema out of node_modules, or run the build first.

The docs script needs Ruby, Jekyll, and an already built packages/vega/build

Documentation and build output are coupled inside this repository. The docs script is cd docs && bundle exec jekyll serve -I -l, so serving the site locally needs Ruby with bundler and a Jekyll install on your machine, not just Node. The build script is lerna run build && npm run docsbuild, and docsbuild copies out of packages/vega/build, which means the docs site ships compiled JavaScript rather than compiling anything itself. Example data arrives by rsync from node_modules/vega-datasets/data into docs/data, so even the datasets assume a completed install. If your work touches the examples in docs/ or you want to see whether a change broke the documentation pages, you are queuing Ruby, Jekyll, and a finished package build in that order.

Version jumps are the upgrade cost, and the Porting Guide is where you find out

The release line moves quickly and crosses major boundaries: v5.33.1 shipped 2026-01-06, v6.3.0 on 2026-07-21, and v6.4.0 on 2026-08-14, and the last push to the repository was on 2026-10-29. Two things follow for anyone holding saved specs. The README links a Vega Porting Guide describing changes between Vega 2 and later versions. And nothing in the repository maps a spec to the minimum Vega version that renders it, so a team maintaining a library of saved visualizations has to record that pairing in its own lockfile.

The README points outward and never states an install command

This README is a pointer document by design, and everything it tells you to do happens somewhere else. It links documentation, tutorials, and examples on the Vega website, sends you to the online Vega Editor with a bar chart example already loaded in the URL, and points at Observable notebooks for more examples. What it does not contain is an npm install line, a version number, an import snippet, or a browser support statement. That is fine for evaluating a grammar inside a browser in five minutes and unhelpful when you need to pin a dependency, which means the first place you look for the install command is the one place it does not exist. Support routes outward the same way, through a discussion forum, a Slack organization, and the code of conduct that accompanies CONTRIBUTING.md.

Benchmarks are hosted notebooks, so no versioned baseline sits in the repo

The repository points at performance material without storing it. The in-browser benchmarks are published as Observable notebooks under the vega Observable organization, and future plans sit in a GitHub projects roadmap, so there is no benchmark file in this tree that you can run, diff, or pin to a release. What the checkout does give you is a correctness oriented script set: npm test runs test:no-lint and then lint, test:no-lint runs lerna run test while first excluding vega-typings and then running it on its own, typecheck is tsc, and lint is eslint against eslint.config.js. If your decision to adopt hinges on render performance, you have to measure it yourself on your own data, because nothing here offers a baseline to compare a regression against.

Editorial conclusion

Vega fits teams that want visualizations as reviewable JSON artifacts and can commit to a major version, because the grammar plus the shipped vega-schema.json make specs checkable and diffable. It does not fit a team expecting a batteries included chart API, an install command in the repository, or performance figures pinned to a release, since those live on the project website, in Observable notebooks, and in the release cadence. Before adopting, read the Vega Porting Guide for the version you start from, confirm your build handles an ES module and a Jekyll docs site, and pin both the Vega version and the individual packages under packages/.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. vega/vega on GitHub