OWID Grapher Development Assistant

This skill provides expert guidance for working on the Our World In Data (OWID) Grapher platform—a monorepo containing a custom data visualization component, website, and admin tools.

Codebase Structure

The project is a TypeScript monorepo using React 19 and Node 22. Key directories (ordered by dependency):

Development Workflow

Essential Commands

```bash

Type checking

yarn typecheck

Linting & formatting

yarn testLintChanged

yarn testPrettierChanged

yarn fixPrettierChanged

Testing

yarn test run --reporter dot # Add filenames to run subset

Database

make migrate # Apply migrations

make dbtest # Run database and API tests

After major changes

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

```

Database Queries

```bash

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 LIMIT 10"

```

**Before writing queries or migrations:**

1. Run `ls db/docs/` to see available tables

2. Read `db/docs/README.md` for database overview

3. Read relevant `db/docs/TABLE-NAME.yml` files for table details

Code Style Guidelines

TypeScript

MobX 6 (Grapher & Admin)

**Non-standard setup using TC-39 stage 3 decorators:**

```typescript

class ChartComponent {

constructor() {

makeObservable(this, {

// List observable props here (NOT decorated with @observable)

data: observable,

selectedYear: observable,

// Do NOT list @computed or @action props

})

}

data: ChartData

selectedYear: number

@computed get filteredData() {

return this.data.filter(d => d.year === this.selectedYear)

}

@action setYear(year: number) {

this.selectedYear = year

}

}

```

**Rules:**

CSS

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

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

React

Git Commits

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

Google Docs / ArchieML Pipeline

**Before working on Google Docs features, read:**

1. `./docs/agent-guidelines/gdocs-cms-pipeline.md` — Detailed ArchieML pipeline overview

2. `./docs/agent-guidelines/gdocs-class-hierarchy.md` — Types of documents and inheritance

3. `./docs/agent-guidelines/gdocs-attachments.md` — Attachment mechanism for React component context

Implementation Steps

When implementing features:

1. **Understand the context:**

- Identify which package(s) are affected

- Check if working with Grapher (MobX) or Site (hooks)

- Review existing similar implementations

2. **For database work:**

- List `db/docs/` directory

- Read `db/docs/README.md`

- Read relevant table documentation files

- Test queries with `yarn query` before writing code

3. **Follow code style:**

- Use double quotes

- Add type definitions

- Follow MobX patterns for Grapher/Admin

- Use BEM CSS conventions

- Avoid `any` type

4. **Before completion:**

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

- Fix all errors

- Run relevant tests

- Follow commit message guidelines

Important Constraints