OWID Grapher Development
GitHub Copilot instructions for developing the Our World In Data Grapher platform - a monorepo for interactive data visualizations and the OWID website.
Commands
Execute these yarn commands for development workflows:
`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 test filenames to run subsets`make migrate` - Apply database migrations`make dbtest` - Run database and API tests`yarn query "QUERY TEXT"` - Run read-only queries against the database`yarn query -s "QUERY TEXT"` - Query staging database for current git branchAfter implementing large changes, run:
```bash
yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck
```
Code Style Guidelines
Follow these conventions when writing code:
TypeScript Standards
Use **double quotes** for string literals (not single quotes)Add type definitions for function parameters and return valuesReuse existing shared type definitions where possible**Avoid `any` type** - only use with explicit permission when absolutely necessaryMobX 6 Usage (Grapher & Admin)
Use class-based components with TC-39 stage 3 decoratorsOnly use decorators for `@computed` and `@action` propertiesObservable props are **not** marked with `@observable`List observable props in constructor's `makeObservable` callThe `makeObservable` call includes only observable props (not `@computed` or `@action`)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 companion `.scss` file with same nameEntry points: - Site styles: `/site/owid.scss`
- Grapher styles: `/packages/@ourworldindata/grapher/src/core/grapher.scss`
Codebase Structure
Monorepo for OWID website built with TypeScript, React 19, and Node 22.
Key Directories (Dependency Chain Order)
1. `./packages/types` - Shared type definitions
2. `./packages/utils` - Utility functions
3. `./packages/core-table` - Custom dataframe classes used by Grapher
4. `./packages/components` - Shared React components
5. `./packages/grapher` - Data visualization component (MobX 6 state management)
6. `./packages/explorer` - Data explorer wrapping Grapher with additional controls
7. `./db` - MySQL 8 database access + business logic for ArchieML/Google Docs
8. `./site` - Website code (React rendering ArchieML, uses React hooks not MobX)
9. `./baker` - Static HTML generation by rendering React
10. `./adminSiteServer` - Internal API for admin
11. `./adminSiteClient` - Admin UI client
12. `./devTools` - Various utilities
13. `./functions` - CloudFlare Functions for dynamic content (charts at `ourworldindata.org/grapher/*`)
Database Guidelines
The main datastore is **MySQL 8**.
Database Documentation
Overview: `db/docs/README.md` - start hereTable details: `db/docs/TABLE-NAME.yml` - one file per table**Before constructing queries or writing migrations:**
1. List `db/docs/` directory to see available tables
2. Read relevant table description files
Querying
Production (read-only): `yarn query "QUERY TEXT"`Staging for current branch: `yarn query -s "QUERY TEXT"` - Example: On branch `images-pageviews`, connects to `staging-site-images-pageviews`
Google Docs Pipeline Documentation
For Google Docs/ArchieML work, reference these files:
`./docs/agent-guidelines/gdocs-cms-pipeline.md` - Detailed ArchieML pipeline from Google Docs to database`./docs/agent-guidelines/gdocs-class-hierarchy.md` - Different Google Docs types and how to create new types`./docs/agent-guidelines/gdocs-attachments.md` - Attachments mechanism providing context to React componentsGit Commit Messages
When creating commits, refer to `docs/agent-guidelines/commit-messages.md` for commit message conventions.
Important Constraints
Always read database documentation before queries or migrationsNever use `any` type without explicit permissionFollow MobX 6 decorator patterns for Grapher/Admin componentsUse BEM CSS conventions in separate `.scss` filesUnderstand the dependency chain when adding cross-package imports