OWID Grapher Development

Development assistant for the Our World In Data Grapher platform - a TypeScript monorepo for creating interactive data visualizations with React 19, Node 22, and MySQL 8.

Common Commands

Run these yarn/make commands for development workflow:

`yarn typecheck` - Run TypeScript type checker across all files

`yarn testLintChanged` - Run ESLint on changed files

`yarn testPrettierChanged` - Run Prettier on changed files

`yarn fixPrettierChanged` - Auto-fix Prettier issues on changed files

`yarn test run --reporter dot` - Run unit tests (vitest, accepts filenames to run subset)

`make migrate` - Apply database migrations

`make dbtest` - Run database and API tests

**Pre-commit validation:**

```bash

yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck

```

Fix any errors before committing.

**Database queries:**

```bash

yarn query "QUERY TEXT" # Query production database (read-only)

yarn query -s "QUERY TEXT" # Query staging database for current branch

```

Code Style Guidelines

General TypeScript

Use **double quotes** for string literals (not single quotes)

Add type definitions for all function params and return values

Reuse existing shared type definitions where possible

**Avoid `any` type** - only use with explicit permission and justification

MobX 6 Pattern (Grapher/Admin)

Use class-based components with TC-39 stage 3 decorators:

Mark computed properties and actions with `@computed` and `@action`

**Do NOT** use `@observable` decorator on properties

List all observable props in constructor's `makeObservable()` call

The `makeObservable()` call must mention observables only (not @computed or @action)

CSS Conventions

Use **BEM naming conventions** in separate `.scss` files

Avoid inline styles unless the component already uses them for similar cases

Component SCSS files match component name (e.g., `MyComponent.tsx` → `MyComponent.scss`)

Entry points:

- Site styles: `/site/owid.scss`

- Grapher styles: `/packages/@ourworldindata/grapher/src/core/grapher.scss`

Codebase Structure

Monorepo organized by dependency chain (low to high):

| Directory | Purpose |

|-----------|---------|

| `./packages/types` | Shared TypeScript type definitions |

| `./packages/utils` | Utility functions |

| `./packages/core-table` | Custom dataframe classes for Grapher |

| `./packages/components` | Shared React components |

| `./packages/grapher` | Data visualization component (MobX 6 state management) |

| `./packages/explorer` | Data explorer wrapper with dropdowns for complex datasets |

| `./db` | MySQL 8 database access + ArchieML Google Docs business logic |

| `./site` | Website code (React hooks, no MobX, renders ArchieML) |

| `./baker` | Static HTML generator (renders React to HTML) |

| `./adminSiteServer` | Internal admin API |

| `./adminSiteClient` | Admin client UI |

| `./devTools` | Development utilities |

| `./functions` | CloudFlare Functions for dynamic features (thumbnails, data downloads at `/grapher/*`) |

Database Documentation

Primary datastore: **MySQL 8**

**ALWAYS** read database documentation before writing queries or migrations:

1. Start with `db/docs/README.md` for overview

2. List available tables: `db/docs/` directory

3. Read relevant `TABLE-NAME.yml` files for detailed schema

Use `yarn query` to explore table contents and cardinality.

Additional Documentation

Read these files before working on related features:

`./docs/agent-guidelines/gdocs-cms-pipeline.md` - ArchieML pipeline from Google Docs to database (required reading for gdocs work)

`./docs/agent-guidelines/gdocs-class-hierarchy.md` - Types of gdocs and how to create new types

`./docs/agent-guidelines/gdocs-attachments.md` - Attachments mechanism for providing React components with context

`./docs/agent-guidelines/commit-messages.md` - Git commit message guidelines

Development Workflow

1. **Before implementing**: Read relevant database documentation (`db/docs/`)

2. **During development**: Follow code style guidelines (double quotes, types, avoid `any`)

3. **After changes**: Run validation command (`yarn fixPrettierChanged && yarn typecheck`)

4. **Before commit**: Follow commit message guidelines in `docs/agent-guidelines/commit-messages.md`

5. **For database work**: Use `yarn query` to explore, then write migrations with `make migrate`

Technology Stack

**Runtime**: Node 22

**Language**: TypeScript

**UI**: React 19

**State** (Grapher/Admin): MobX 6 with class components

**State** (Site): React hooks (no MobX)

**Database**: MySQL 8

**Testing**: Vitest

**CSS**: SCSS with BEM conventions

**Deployment**: CloudFlare Functions (dynamic routes)

OWID Grapher Development

OWID Grapher Development

Common Commands

Code Style Guidelines

General TypeScript

MobX 6 Pattern (Grapher/Admin)

CSS Conventions

Codebase Structure

Database Documentation

Additional Documentation

Development Workflow

Technology Stack

Reviews (0)