OWID Grapher Development
Expert development assistant for the Our World In Data (OWID) Grapher platform - a TypeScript/React monorepo for creating interactive data visualizations with a custom CMS pipeline.
Core Commands
Use these commands during development:
**Type checking and linting:**
`yarn typecheck` - Run TypeScript type checker across all files`yarn testLintChanged` - Run ESLint on changed files`yarn testPrettierChanged` - Check Prettier formatting on changed files`yarn fixPrettierChanged` - Auto-fix Prettier issues on changed files**Testing:**
`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**Database queries:**
`yarn query "QUERY TEXT"` - Run read-only queries against production database`yarn query -s "QUERY TEXT"` - Query staging database for current git branch**Pre-commit validation:**
After implementing major changes, run:
```bash
yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck
```
Fix any errors before committing.
Code Style Guidelines
String Literals
Use **double quotes** for string literals, not single quotesExample: `const message = "Hello world"` ✓ not `'Hello world'` ✗Type Definitions
Always provide type definitions for function parameters and return valuesReuse existing shared type definitions from `./packages/types` where possibleAvoid the `any` type - only use when absolutely necessary and ask for permissionMobX 6 Setup (Grapher & Admin)
The project uses a non-standard MobX setup:
Use class-based components with TC-39 stage 3 decoratorsOnly use `@computed` and `@action` decoratorsObservable props are NOT marked with `@observable`Instead, list observable props in constructor's `makeObservable` callThe `makeObservable` call must mention all observable props, but none of the `@computed` or `@action` onesExample:
```typescript
class MyComponent {
observableProp: string
constructor() {
makeObservable(this, {
observableProp: observable,
// Don't list @computed or @action props here
})
}
@computed get derivedValue() { ... }
@action updateValue() { ... }
}
```
CSS/Styling
Use named style classes following **BEM conventions** in separate `.scss` filesAvoid inline styles unless the component already uses them for similar casesComponents typically have a companion `.scss` file with the same nameEntry points: - Site styles: `/site/owid.scss`
- Grapher styles: `/packages/@ourworldindata/grapher/src/core/grapher.scss`
Codebase Structure
TypeScript monorepo using React 19 and Node 22. Key directories (in dependency order):
Core Packages
**`./packages/types`** - Shared type definitions**`./packages/utils`** - Utility functions**`./packages/core-table`** - Custom dataframe classes used by Grapher**`./packages/components`** - Shared React componentsMain Applications
**`./packages/grapher`** - Data visualization component (MobX 6 state management)**`./packages/explorer`** - Data explorer wrapping Grapher with additional controlsBackend & CMS
**`./db`** - MySQL 8 database access + business logic for ArchieML from Google Docs**`./site`** - Website code (React rendering ArchieML, uses React hooks not MobX)**`./baker`** - Static site generator (renders React to HTML)**`./adminSiteServer`** - Internal admin API**`./adminSiteClient`** - Admin UI clientInfrastructure
**`./devTools`** - Development utilities**`./functions`** - CloudFlare Functions for dynamic features (thumbnails, data downloads at `/grapher/*`)Database Access
The main datastore is **MySQL 8**. Always consult database documentation before queries or migrations.
Documentation Location
**`db/docs/README.md`** - Overview and starting point**`db/docs/TABLE-NAME.yml`** - Detailed table descriptionsWorkflow
1. **Always list** `db/docs/` directory to understand available tables
2. **Read relevant table** description files before constructing queries
3. **Use `yarn query`** to explore table contents and cardinality
4. For staging database, use **`yarn query -s`** (connects to branch-specific staging DB)
Gdocs CMS Pipeline
Additional documentation for the Google Docs to website pipeline:
**`./docs/agent-guidelines/gdocs-cms-pipeline.md`** - Detailed ArchieML pipeline overview (gdocs → database). Read before working on gdocs features**`./docs/agent-guidelines/gdocs-class-hierarchy.md`** - Different gdocs types, their differences, and how to create new types**`./docs/agent-guidelines/gdocs-attachments.md`** - Attachments mechanism for providing context to React componentsCommit Messages
When creating git commits, refer to **`docs/agent-guidelines/commit-messages.md`** for commit message conventions.
Best Practices
1. **Before starting work:** Read relevant documentation in `db/docs/` and `docs/agent-guidelines/`
2. **During development:** Follow code style guidelines strictly (double quotes, types, MobX patterns)
3. **Before committing:** Run `yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck`
4. **For database work:** Always check `db/docs/` first, use read-only queries to explore
5. **For gdocs features:** Review the three gdocs documentation files before implementing