owid-grapher: Local Setup and Reuse Boundaries

Why Our World in Data Built owid-grapher

owid-grapher addresses a publication workflow problem rather than a generic chart-drawing problem. According to the README, Our World in Data previously prepared spreadsheets for individual visualizations and then wrote separate HTML and JavaScript for each one. That process could take hours even for one chart. Grapher replaces much of that repetition with a common codebase, a shared MySQL database, and an interface for selecting variables and chart settings.

The intended users are developers, editors, and data teams operating close to Our World in Data's publishing infrastructure. The system is aimed at organizations that repeatedly create many evidence-based charts from a common data catalog. It is not presented as an independent package for embedding a React chart in an unrelated application.

That distinction matters. A team that only needs a line chart, bar chart, or scatterplot may find the repository much heavier than its requirements. The value documented by the project comes from integrating chart configuration, imported values, administrative editing, and site generation in one database-centered system. The README specifically contrasts this approach with preparing a separate dataset and custom front-end implementation for every visualization.

Grapher, Explorer, Admin, and Baker Data Flow

The repository is a monorepo containing several cooperating projects rather than one isolated library. Grapher is the client-side interactive visualization layer used by most Our World in Data charts. Its chart configuration is stored as JSON, while chart values are ingested into the same MySQL database. This allows an editor to choose variables and a chart type through Grapher Admin rather than encode every data binding in a standalone page.

Explorer builds more complex interfaces on top of Grapher. Its README section states that each Explorer can be configured through a panel in `explorerAdminServer/`. That makes Explorer more than a chart variant. It is a configured composition of chart and interface behavior for publishing multi-panel or parameterized experiences.

The administrative path runs through `adminSiteClient/` and `adminSiteServer/`. The client provides interfaces for configuring graphers and explorers and for managing and uploading data. The server manages the MySQL database behind those graphers. The static publishing side is handled by `baker/`, a PM2 project that merges content authored in Gdocs with charts created through Grapher Admin. Finally, `site/` contains React code used to render site content in pages and by the Admin and Baker applications.

This division makes the data flow understandable: authors and editors enter or select chart data, configuration is persisted with values in MySQL, Grapher renders interactive views, and Baker produces a static copy of the wider site. The README does not describe the REST API shape, authentication configuration, or every deployment dependency, so those details cannot be inferred from the project overview.

Local Grapher Development Through Docker Compose

For a first local use, the README directs developers to `docs/docker-compose-mysql.md`. It describes that guide as the recommended path for running a version of the site while developing Grapher features. The repository also links `docs/setup-options-overview.md` for additional setups, but the excerpt does not reproduce the individual installation commands or expected service output. Consequently, there is no justified command to invent for launching the stack.

The root `package.json` establishes two concrete toolchain requirements. It declares a private package, sets the package manager to Yarn 4.17.1, and requires Node.js >=24.0. The Yarn configuration is represented by `.yarnrc.yml`, while a `.nvmrc` file is also present at repository root. Check those repository files and the local development guide before cloning or building the monorepo.

The root package exposes build and maintenance scripts such as `buildVite`, `buildLocalBake`, and `buildGrapherSchema`. These names show that local operation spans more than the Grapher browser component. A developer may need the Admin client, site renderer, schema tooling, database services, and Baker depending on the task. The `Makefile` contains setup and service targets, but its truncated listing does not provide a complete safe sequence to reproduce here.

One documented optional action can be run after the repository is prepared. The README says pre-commit hooks can be enabled with this exact command:

yarn husky

That command configures repository hooks; it does not install dependencies, start MySQL, build a chart, or publish content. The local setup guide remains the authoritative starting point for those tasks.

React, MobX, TypeScript, and the Monorepo Boundary

The user-facing implementation is based on React and Mobx. The README characterizes this as reactive programming, with React providing the rendering layer and Mobx managing reactive state. All code is written in TypeScript. This stack is relevant to engineers who intend to modify chart behavior or the administrative interfaces, but the repository description does not state that Mobx can be used independently of the rest of the system.

The source layout reinforces that Grapher is embedded in a larger application. `adminShared/` contains code shared around administration, `adminSiteClient/` and `adminSiteServer/` split browser and database-facing concerns, `baker/` handles static output, and `packages/@ourworldindata/grapher/` contains the core Grapher package. There are also queue, database, Playwright, schema, routing, and deployment-related entries. This is application infrastructure rather than a minimal package designed to be copied into another React project.

The TypeScript requirement can aid static analysis, especially because the README recommends Visual Studio Code for autocompletion and editor analysis. However, type safety does not remove the operational coupling. A successful import of Grapher code would not establish that another application's database schema, content model, chart configuration format, or publishing process matches this repository. The README is explicit that the tools remain tightly coupled to Our World in Data's database structure.

For contributors, `CONTRIBUTING.md` and `CONTRIBUTOR_AGREEMENT.md` are the relevant repository files. The README says contributions are welcome and accepted under the Contributor Agreement. That statement addresses contribution through the project's process, not permission to reuse source code in a separate product.

Database Coupling and Production-System Limits

The clearest limitation appears in the README's own disclaimer: the repository is not well designed for reuse as a visualization library and does not reproduce the full Our World in Data production environment. The tools are tightly coupled to the project's database structure, and project-specific needs may take priority over general reuse.

This creates several practical boundaries. A team cannot assume that Grapher can accept an arbitrary local data object and render it without adapting it to the expected configuration and database model. Nor can it assume that running the chart package alone will reproduce Explorer, Admin, Baker, Gdocs integration, MySQL management, or the rest of the site's behavior. The relevant test surface is wider than a conventional chart component library.

MySQL is not an incidental development choice in the documented architecture. The database stores both per-chart JSON configuration and ingested chart values. Explorer configuration also has an administrative path, and Baker consumes chart output when creating static site files. Changes to schemas, migrations, import scripts, configuration formats, and site generation may therefore need coordinated review. The root package includes database-related tooling, including a `createDbMigration` script, which confirms that schema evolution belongs to the project workflow, although the complete migration procedure is not documented in the excerpt.

The repository also has no GitHub releases. Recent change history must therefore be assessed through commits and repository files rather than a release cadence. The last push was on 2026-10-15, which indicates current repository activity for assessment purposes, but it does not promise stable compatibility for external consumers.

Custom Licence Versus Ordinary Open Source Adoption

owid-grapher is publicly available for transparency and educational reference, but the README says it is no longer available under the MIT licence. It permits viewing and studying the source code. It does not permit copying, modifying, distributing, sublicensing, adapting, or otherwise using any part of the codebase in another project, product, or service without prior written permission from Our World in Data.

This licence is the first adoption constraint, ahead of installation. Forking a package to alter its chart renderer, incorporating source into an internal application, or running a modified copy for another service falls within the area the README restricts. Public availability should not be interpreted as conventional open source reuse permission. `LICENSE.md` contains the full terms and contact details, while `CONTRIBUTOR_AGREEMENT.md` governs contributions under the stated process.

This article does not interpret the legal effect of those files. Operationally, an engineer should distinguish two possible uses before changing code. Work performed through the accepted contribution process is one route. Reuse, adaptation, or incorporation into another product or service requires direct permission under the terms summarized in the README. An organization that requires a permissive licence, unrestricted modification rights, or self-hosting rights without an additional agreement will not find that model here.

The custom licence also raises upgrade planning. A team that receives permission may have permission for a particular use rather than an unrestricted right to distribute derivatives. Any upgrade plan should therefore track the exact written permission and review changes across the full monorepo, rather than treating updates like routine dependency upgrades.

Where Grapher Differs from Datawrapper, Tableau, and Plotly

The README names Datawrapper, Tableau, Plotly, and d3-based libraries as alternatives considered before Grapher was built. The important difference is not chart styling. Grapher is designed around a common database that contains chart values and JSON configuration for many visualizations. A chart can then be created by choosing the relevant variables and configuration through the administrative interface instead of receiving a separately prepared dataset and custom implementation.

Datawrapper, Tableau, and Plotly are not characterized here as incapable of interactive charts. The README instead argues that none provided the same fit for Our World in Data's database, publishing, and system-wide update requirements. Grapher can apply changes across a large collection of charts because its charts participate in a shared application and data structure. It can also publish interactive graphers as part of the same site-building workflow.

That model is a poor match when the main requirement is chart portability. Importing a CSV into an independent visualization and embedding the result through that service is not the workflow described here. Nor does the README document a stable package installation path, compatibility promise for external datasets, or self-contained browser API intended for third-party use.

A fair comparison must therefore include the administrative system, database assumptions, static publishing path, licence, and operational requirements. Choosing Grapher only because it produces interactive charts would miss the reason it exists and the constraints that come with that design.

Editorial conclusion

Adopt owid-grapher when your team can work within Our World in Data's MySQL-backed publishing architecture and has written permission for any reuse. Do not adopt it as a drop-in charting dependency without that permission. Verify the terms in LICENSE.md, then follow docs/docker-compose-mysql.md and confirm the local environment matches the Node.js >=24.0 and Yarn 4.17.1 requirements before estimating integration work.

Frequently asked questions

Official sources

1. Issues
2. owid/owid-grapher on GitHub
3. Project website
4. README