OWID Grapher Development Assistant

Expert coding assistant for the Our World In Data Grapher platform - a monorepo for interactive data visualizations and the OWID website.

Overview

This skill provides specialized assistance for the owid/owid-grapher codebase, which includes:

Key Technologies

Codebase Structure

Understanding the dependency chain is critical:

1. **`./packages/types`** - Shared type definitions

2. **`./packages/utils`** - Utility functions

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

4. **`./packages/components`** - Shared React components

5. **`./packages/grapher`** - Data visualization component (MobX 6)

6. **`./packages/explorer`** - Data explorer wrapping Grapher

7. **`./db`** - MySQL access + ArchieML/Google Docs business logic

8. **`./site`** - Website code (React + ArchieML rendering, hooks-based)

9. **`./baker`** - Static HTML generation from React

10. **`./adminSiteServer`** - Internal API

11. **`./adminSiteClient`** - Admin UI

12. **`./devTools`** - Development utilities

13. **`./functions`** - CloudFlare Functions (dynamic thumbnails, data downloads at `/grapher/*`)

Development Commands

Quality Checks

```bash

yarn typecheck # Run TypeScript type checker

yarn testLintChanged # ESLint on changed files

yarn testPrettierChanged # Prettier check on changed files

yarn fixPrettierChanged # Auto-fix Prettier issues

yarn test run --reporter dot # Run unit tests (Vitest)

```

Database Operations

```bash

make migrate # Apply migrations

make dbtest # Run database and API tests

yarn query "SELECT ..." # Run read-only query on production DB

yarn query -s "SELECT ..." # Query staging DB for current branch

```

Pre-Commit Validation

After completing major changes:

```bash

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

```

Code Style Guidelines

General TypeScript

MobX 6 Pattern (Grapher & Admin)

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

```typescript

class MyComponent {

@computed get derivedValue() { ... }

@action updateState() { ... }

constructor() {

// Observable props NOT marked with @observable decorator

// Instead, list them in makeObservable:

makeObservable(this, {

observableProp1: observable,

observableProp2: observable,

// DO NOT list @computed or @action props here

})

}

}

```

CSS/SCSS

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

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

Database Workflow

Before Writing Queries or Migrations

1. **List available tables**:

```bash

ls db/docs/

```

2. **Read table documentation**:

- `db/docs/README.md` - Database overview

- `db/docs/TABLE-NAME.yml` - Detailed table schema and description

3. **Explore data** (read-only):

```bash

# Production DB

yarn query "SELECT COUNT(*) FROM table_name"

# Staging DB (branch-specific)

yarn query -s "SELECT * FROM table_name LIMIT 10"

```

Database Documentation Pattern

Google Docs / ArchieML Pipeline

Before working on Google Docs-related features, read these documents:

1. **`./docs/agent-guidelines/gdocs-cms-pipeline.md`**

Detailed overview of ArchieML pipeline from Google Docs to database

2. **`./docs/agent-guidelines/gdocs-class-hierarchy.md`**

Document types, inheritance, and how to create new types

3. **`./docs/agent-guidelines/gdocs-attachments.md`**

Attachments mechanism for providing context to React components

Commit Message Guidelines

When creating git commits, follow the guidelines in:

```

docs/agent-guidelines/commit-messages.md

```

Testing Strategy

CloudFlare Functions

Dynamic functionality for static site:

Staging Environment

Branch-specific staging databases follow naming convention:

Query staging with `-s` flag: `yarn query -s "..."`

Common Workflows

Adding a New Feature

1. Understand dependency chain (packages flow from types → utils → core-table → components → grapher → site)

2. Check if types need to be added/updated in `./packages/types`

3. Write implementation following code style guidelines

4. Add/update tests

5. Run quality checks: `yarn fixPrettierChanged && yarn typecheck`

6. Follow commit message guidelines

Modifying Database Schema

1. Read `db/docs/README.md` and relevant table `.yml` files

2. Write migration in `./db/migration/`

3. Test with `make migrate && make dbtest`

4. Update table documentation in `db/docs/`

Working with Google Docs Pipeline

1. Review `gdocs-cms-pipeline.md`, `gdocs-class-hierarchy.md`, and `gdocs-attachments.md`

2. Understand ArchieML parsing and attachment mechanism

3. Test changes through full pipeline (Docs → DB → React rendering)

Important Notes