OWID Grapher Development Assistant

Expert assistant for developing the Our World in Data (OWID) Grapher platform - a monorepo for creating interactive data visualizations with React, TypeScript, and MySQL.

Project Overview

This is a TypeScript monorepo for the Our World In Data website, including the custom data visualization component Grapher. Built with React 19, Node 22, and MySQL 8.

Key Directories (Dependency Chain)

Development Commands

Testing & Linting

```bash

Type checking

yarn typecheck

Linting

yarn testLintChanged # ESLint on changed files

yarn testPrettierChanged # Prettier on changed files

yarn fixPrettierChanged # Auto-fix prettier issues

Unit tests (vitest)

yarn test run --reporter dot

yarn test run --reporter dot path/to/test.ts # Specific test file

Complete validation before commits

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

```

Database Operations

```bash

Run migrations

make migrate

Database and API tests

make dbtest

Query production database (read-only)

yarn query "SELECT * FROM table_name LIMIT 10"

Query staging database for current branch

yarn query -s "SELECT * FROM table_name"

```

Code Style Guidelines

General TypeScript

MobX 6 Usage (Grapher & Admin)

Use a non-standard setup with class-based components and TC-39 stage 3 decorators:

```typescript

class Example {

observableProp: string = ""

constructor() {

makeObservable(this, {

observableProp: observable,

// Do NOT list @computed or @action properties here

})

}

@computed get derivedValue() {

return this.observableProp.toUpperCase()

}

@action updateProp(value: string) {

this.observableProp = value

}

}

```

CSS Styling

- Site: `/site/owid.scss`

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

Database Documentation

Accessing Documentation

**ALWAYS** read the database documentation before querying or writing migrations:

1. **Start with**: `db/docs/README.md` - overview and starting point

2. **List available tables**: `ls db/docs/` to see all `TABLE-NAME.yml` files

3. **Read table details**: Check relevant `.yml` files before constructing queries

Query Examples

```bash

Understand table contents

yarn query "DESCRIBE posts"

yarn query "SELECT COUNT(*) FROM charts"

Check cardinality

yarn query "SELECT column_name, COUNT(*) as count FROM table_name GROUP BY column_name"

Query staging branch database

yarn query -s "SELECT * FROM charts WHERE slug LIKE '%covid%' LIMIT 5"

```

Google Docs CMS Pipeline

For work involving the Google Docs to website pipeline, read these documentation files first:

Git Commit Messages

Before creating commits, refer to `docs/agent-guidelines/commit-messages.md` for commit message guidelines.

Implementation Workflow

1. **Before making changes:**

- Read relevant database documentation in `db/docs/`

- Understand existing patterns in the codebase

- Check for reusable type definitions

2. **During implementation:**

- Follow code style guidelines (double quotes, types, BEM CSS)

- Use proper MobX patterns if in Grapher/Admin

- Write unit tests for new functionality

3. **Before committing:**

- Run `yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck`

- Fix any errors

- Follow commit message guidelines

- Ensure all tests pass

Important Notes