Gatsby Theme Chronogrove Development
Development guidelines and architecture patterns for gatsby-theme-chronogrove, a Gatsby theme monorepo that powers personal websites with a social dashboard home page.
Project Architecture
This is a Gatsby theme monorepo using Yarn workspaces:
**Root**: Workspace configuration and shared tooling**`theme/`**: The Gatsby theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: Example website content and configuration**Backend API**: `metrics.chrisvogt.me` (separate repo: chrisvogt/metrics) - Firebase-based API for widget dataCurrent Development Goal
Decouple all personal information from the `/theme` directory to make it fully generic and reusable.
Technology Stack
**Gatsby 5.x**: Static site generator**React 18.x**: UI framework**Theme UI**: Design system and CSS-in-JS styling**Redux Toolkit**: State management for widgets**Jest + React Testing Library**: Comprehensive testing**Yarn v4 Workspaces**: Monorepo management**MDX**: Content authoring with React components**FontAwesome**: Icon libraryDevelopment Environment
1. **Prerequisites**: Node.js >=20 (see `.node_version`), Yarn >=4.0.0
2. **HTTPS Requirement**: Local development requires HTTPS
3. **Commands**:
- `yarn develop` - Start HTTPS development server
- `yarn test` - Run all tests
- `yarn test:watch` - Watch mode for tests
- `yarn test:coverage` - Coverage report
- `yarn format` - Format with Prettier
- `yarn lint` - Lint with ESLint
4. **Workspace Commands**: Use `yarn workspace [package] [command]` for package-specific operations
Widget System Architecture
The theme includes a sophisticated dashboard widget system with these widgets:
**Recent Posts**: Latest blog posts from MDX content**GitHub**: Profile data, pinned repos, PR activity**Goodreads**: Reading activity and book lists**Instagram**: Posts and metrics**Spotify**: Playlists and top tracks**Steam**: Gaming activity with AI summaries**Flickr**: Photo galleries and collectionsWidget Data Flow
1. **Data Sources**: Fetch from Metrics API at `metrics.chrisvogt.me`
2. **Actions** (`fetchDataSource.js`): Handle API calls with deduplication
3. **Reducers**: Process and store data with loading states (INIT, SUCCESS, FAILURE)
4. **Selectors**: Transform data for component consumption
5. **Components**: Display with loading/error states
Adding New Widgets
Follow this pattern when creating widgets:
1. Create widget component in `src/components/widgets/[name]/`
2. Add Redux actions in `src/state/actions/`
3. Create reducer in `src/state/reducers/`
4. Add selectors in `src/state/selectors/`
5. Create mock data in `__mocks__/`
6. Write tests covering all states (loading, success, error)
7. Update documentation
Configuration Strategy
Make the theme configurable through:
**Site Metadata**: Core information (title, description, author)**Widget Configuration**: API endpoints and usernames per widget**Social Profiles**: Configurable social media links**Personal Information**: Name, location, bio (via selectors, not hardcoded)**Theme Options**: Styling and behavior customization**Gatsby Plugins**: Content source configurationEnvironment Variables
```bash
GATSBY_METRICS_API_URL=https://metrics.chrisvogt.me
GATSBY_GITHUB_TOKEN=your_token
GATSBY_SPOTIFY_CLIENT_ID=your_client_id
GATSBY_INSTAGRAM_ACCESS_TOKEN=your_token
GATSBY_GOODREADS_API_KEY=your_key
GATSBY_STEAM_API_KEY=your_key
```
Decoupling Personal Information
High Priority Files (Hardcoded Personal Data)
`theme/src/components/h-card.js` - Personal details, email, location`theme/src/components/home-header-content.js` - Name, description`theme/src/data/social-profiles.json` - Social media links`theme/gatsby-config.js` - Default site metadataDecoupling Process
1. Move hardcoded values to site metadata configuration
2. Create selectors for accessing personal data
3. Update components to use selectors instead of literals
4. Provide sensible defaults in theme configuration
5. Update tests with mock data
6. Document all configuration options
Development Patterns
Follow these conventions:
**Components**: Functional components with hooks**Props**: Consistent prop interfaces with PropTypes**State Management**: Redux actions for API calls**Loading States**: Always handle loading, success, error states**Styling**: Theme UI components with dark/light mode support**Content**: MDX for rich content with React components**Performance**: Lazy loading and code splitting**Accessibility**: Semantic HTML, ARIA attributes, keyboard navigation**Testing**: Unit tests with React Testing Library, snapshot testsTesting Strategy
Comprehensive test setup includes:
**Jest**: Unit testing framework**React Testing Library**: DOM queries and user interactions**React Test Renderer**: Snapshot testing for visual regression**Redux Mock Store**: State management testing**Jest Canvas Mock**: Canvas API mocking**Mock Data**: Comprehensive API mocks in `__mocks__/`**File Mocks**: Static asset mocking (images, fonts)Always test:
Component rendering (snapshots)Loading statesSuccess states with dataError statesUser interactionsRedux action dispatchSelector outputsCode Quality Standards
**ESLint**: React and accessibility rules enforced**Prettier**: Consistent code formatting**Husky**: Pre-commit hooks for linting/formatting**JSDoc**: Type annotations for better IntelliSense**EditorConfig**: Consistent editor settingsPerformance Considerations
Lazy load components with React.lazy()Optimize images with Sharp pluginUse code splitting for large dependenciesMinimize bundle size - evaluate before adding dependenciesImplement responsive images via gatsby-plugin-imageFont optimization (preload, subset)CDN-ready static buildsBuild and Deployment
**Static Generation**: Gatsby builds optimized static files**Image Optimization**: Sharp for responsive images**SEO**: Structured data and meta tags configured**Performance**: Automatic code splitting**CDN Ready**: Optimized for edge deploymentImportant Guidelines
Follow existing patterns for consistencyMaintain backward compatibilityUpdate tests and mocks when modifying widgetsStore API keys in environment variables onlyPrioritize accessibility in all featuresUse semantic HTML throughoutTest across browsers and devicesConsider bundle size impactDocument all configuration optionsUse HTTPS for local developmentKeep dependencies updated for securityResources
**Repository**: https://github.com/chrisvogt/gatsby-theme-chronogrove**Backend API**: https://github.com/chrisvogt/metrics**Live Site**: https://www.chrisvogt.me**Gatsby Documentation**: https://www.gatsbyjs.com/docs**Theme UI**: https://theme-ui.com