Gatsby Theme Chronogrove Development
Expert development guidance for gatsby-theme-chronogrove, a Gatsby theme monorepo powering personal websites with social dashboard home pages.
Project Architecture
This is a Yarn v4 workspace monorepo with the following structure:
**Root**: Workspace configuration and shared tooling**`theme/`**: The reusable Gatsby theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: Reference implementation with actual website content**Backend API** (`metrics.chrisvogt.me`): Firebase/Firestore backend for widgets (separate repo: chrisvogt/metrics)Technology Stack
**Gatsby 5.x** - Static site generator**React 18.x** - UI framework with functional components and hooks**Theme UI** - Design system and CSS-in-JS styling with dark/light mode**Redux Toolkit** - State management for widget data**MDX** - Content authoring with React component integration**Jest + React Testing Library** - Comprehensive testing with mocks for external APIs**Yarn v4 Workspaces** - Monorepo management**Node.js >=20** - Runtime environment (see `.node_version` and `.nvmrc`)**FontAwesome** - Icon libraryDevelopment Environment Setup
When setting up the development environment:
1. **Node Version**: Ensure Node.js >=20 is installed (check `.node_version` or `.nvmrc`)
2. **Yarn Version**: Use Yarn >=4.0.0 (specified in `packageManager` field of package.json)
3. **HTTPS Requirement**: Local development requires HTTPS (use `develop:https` script)
4. **Workspace Commands**: Use `yarn workspace [package] [command]` for package-specific operations
Available Scripts
`yarn develop` - Start development server with HTTPS`yarn test` - Run all tests`yarn test:watch` - Run tests in watch mode`yarn test:coverage` - Generate coverage report`yarn format` - Format code with Prettier`yarn lint` - Lint code with ESLintWidget System Architecture
The theme includes a sophisticated widget system for the dashboard home page:
Available Widgets
**Recent Posts** - Latest blog posts from MDX content**GitHub** - Profile data, pinned repos, PRs**Goodreads** - Reading activity and book lists**Instagram** - Posts and metrics**Spotify** - Music playlists and top tracks**Steam** - Gaming activity with AI summaries**Flickr** - Photo galleries and image collectionsData Flow Pattern
1. **Data Sources**: Metrics API at `metrics.chrisvogt.me` (configurable via `GATSBY_METRICS_API_URL`)
2. **Actions** (`fetchDataSource.js`): Handle API calls with deduplication logic
3. **Reducers**: Process and store data with loading states (INIT, SUCCESS, FAILURE)
4. **Selectors**: Transform raw data for component consumption
5. **Components**: Display data with loading states and error handling
Adding New Widgets
When creating a new widget, follow this pattern:
1. **Component Structure**: Create widget component in `src/components/widgets/[name]/`
2. **Redux Setup**: Add actions and reducers for data fetching
3. **Selectors**: Create selectors for accessing and transforming data
4. **Mock Data**: Add comprehensive mock data in `__mocks__/` directory
5. **Tests**: Write tests covering loading, success, and error states
6. **Documentation**: Document configuration options and API requirements
Example widget structure:
```
src/components/widgets/my-widget/
├── my-widget.js (component)
├── my-widget.test.js (tests)
├── my-widget-actions.js (Redux actions)
├── my-widget-reducer.js (Redux reducer)
└── my-widget-selectors.js (data selectors)
```
Environment Variables
Configure the following environment variables as needed:
`GATSBY_METRICS_API_URL` - Metrics API endpoint (defaults to metrics.chrisvogt.me)`GATSBY_GITHUB_TOKEN` - GitHub API token for enhanced rate limits`GATSBY_SPOTIFY_CLIENT_ID` - Spotify API client ID`GATSBY_INSTAGRAM_ACCESS_TOKEN` - Instagram API access token`GATSBY_GOODREADS_API_KEY` - Goodreads API key`GATSBY_STEAM_API_KEY` - Steam API key**Important**: Never commit API keys. Store them in `.env.development` (gitignored).
Testing Strategy
The project uses comprehensive testing with the following tools:
**Jest**: Unit testing framework with custom configuration**React Testing Library**: Component testing with DOM queries and user interactions**React Test Renderer**: Snapshot testing for visual regression**Redux Mock Store**: Mock Redux store for testing stateful components**Jest Canvas Mock**: Canvas API mocking for visual components**Identity Object Proxy**: CSS/SCSS module mocking**File Mock**: Static asset mocking (images, fonts, etc.)Writing Tests
When writing tests:
1. Cover all three states: loading (INIT), success (SUCCESS), and error (FAILURE)
2. Use mock data from `__mocks__/` directory
3. Test user interactions with React Testing Library
4. Add snapshot tests for components with complex rendering
5. Mock external API calls consistently
6. Test accessibility features (ARIA attributes, keyboard navigation)
Decoupling Personal Information
**Current Goal**: Make the theme reusable by moving personal information to configuration.
Files Requiring Decoupling (High Priority)
`theme/src/components/h-card.js` - Personal details, email, location`theme/src/components/home-header-content.js` - Name, personal description`theme/src/data/social-profiles.json` - Social media links and usernames`theme/gatsby-config.js` - Default site metadata with personal infoDecoupling Pattern
When decoupling personal information:
1. **Move to Configuration**: Transfer hardcoded values to site metadata or theme options
2. **Create Selectors**: Add selectors for accessing configurable data
3. **Update Components**: Replace hardcoded values with selector-based data access
4. **Provide Defaults**: Include sensible defaults in theme configuration
5. **Update Tests**: Use mock data instead of hardcoded values
6. **Document**: Add configuration options to documentation
Configuration Strategy
The theme should support configuration through:
**Site Metadata**: Core site information (title, description, author)**Widget Configuration**: API endpoints and usernames per widget**Social Profiles**: Configurable social media links and usernames**Personal Information**: Name, location, bio, contact details**Theme Options**: Customizable styling and behavior**Gatsby Plugins**: Plugin options for content sources and transformationsDevelopment Patterns
Follow these patterns for consistency:
**Functional Components**: Use React hooks instead of class components**Prop Interfaces**: Maintain consistent prop naming and structure**Loading States**: Always handle loading, success, and error states**Accessibility**: Include semantic HTML, ARIA attributes, keyboard navigation**Responsive Design**: Test on multiple screen sizes and devices**Theme UI**: Use Theme UI components for consistent styling and dark/light mode**Redux Actions**: Centralize API calls in Redux actions**Error Handling**: Implement retry logic and user-friendly error messages**Lazy Loading**: Optimize performance with lazy loading for widgets**MDX Integration**: Support React components within contentCode Quality Standards
**ESLint**: Follow React and accessibility rules**Prettier**: Maintain consistent code formatting**Husky**: Git hooks ensure pre-commit linting and formatting**JSDoc**: Add JSDoc comments for type safety and documentation**EditorConfig**: Consistent editor settings across teamExternal Dependencies
**Backing Service**: Metrics API at metrics.chrisvogt.me (Firebase/Firestore)**Image CDNs**: Cloudinary and Imagix for external image hosting**Static Assets**: Local images stored in `static/` directory**Font Loading**: Google Fonts and FontAwesome icons**Analytics**: Configured in site-specific gatsby-config.jsBuild and Deployment
**Static Generation**: Gatsby builds optimized static files**Image Optimization**: Sharp plugin for responsive images**SEO**: Structured data, meta tags, and Open Graph support**Performance**: Code splitting, lazy loading, and bundle optimization**CDN Ready**: Optimized for CDN deployment with cache headersRecent Development Priorities
Based on recent git history:
**Performance**: Lazy loading, font optimization, bundle size reduction**Accessibility**: Skip links, contrast improvements, keyboard navigation**Widget Features**: Steam AI summary, Spotify iframe support**Testing**: Jest upgrades, improved coverage, warning resolution**Content Management**: Better SEO, structured data, content organizationCommon Development Tasks
Adding New Widget
```
1. Create component in src/components/widgets/[name]/
2. Add Redux actions and reducers
3. Create selectors for data access
4. Add mock data in __mocks__/
5. Write comprehensive tests
6. Update documentation
```
Decoupling Personal Data
```
1. Move hardcoded values to site metadata configuration
2. Create selectors for accessing personal data
3. Update components to use selectors
4. Provide sensible defaults in theme configuration
5. Update tests to use mock data
6. Document configuration options in README
```
Important Constraints
**Backward Compatibility**: Maintain compatibility when refactoring**Test Coverage**: Update tests when modifying widgets or components**Performance**: Consider bundle size impact of new dependencies**HTTPS**: Always use HTTPS for local development**Security**: Store API keys in environment variables, never commit them**Accessibility**: Prioritize accessibility in all features**Responsive**: Test on multiple browsers and devices**Documentation**: Keep documentation up-to-date with changesInstructions for AI Agent
When working on this codebase:
1. **Understand Context**: Review the current goal (decoupling personal information) before making changes
2. **Follow Patterns**: Match existing code style, component structure, and Redux patterns
3. **Test Everything**: Write or update tests for all changes
4. **Check Accessibility**: Ensure new components include proper ARIA attributes and keyboard support
5. **Optimize Performance**: Use lazy loading and consider bundle size impact
6. **Document Changes**: Update README and inline documentation
7. **Use Workspace Commands**: Remember to use `yarn workspace [package]` for package-specific operations
8. **Environment Variables**: Never hardcode API keys; use environment variables
9. **Maintain Compatibility**: Ensure changes don't break existing implementations
10. **Review Priority**: Focus on high-priority decoupling tasks before medium/low priority