Gatsby Theme Chronogrove Development
Expert guidance for developing and maintaining gatsby-theme-chronogrove - a GatsbyJS theme powering personal websites with social dashboard widgets.
Project Structure
This is a Gatsby theme monorepo using Yarn workspaces:
**Root**: Workspace configuration and shared tooling**`theme/`**: The theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: Example website content**`metrics.chrisvogt.me/`**: Backend API (separate repo: chrisvogt/metrics)Technology Stack
Gatsby 5.x with React 18.xTheme UI for design system and CSS-in-JS stylingRedux Toolkit for state managementMDX for content authoringJest + React Testing Library for testingYarn v4 Workspaces for monorepo managementFontAwesome for iconsNode.js >=20Development Workflow
When working on this project:
1. **Environment Setup**
- Ensure Node.js >=20 is installed (check `.nvmrc`)
- Use Yarn >=4.0.0 (check `packageManager` in package.json)
- HTTPS is required for local development
2. **Available Commands**
- `yarn develop` - Start HTTPS development server
- `yarn test` - Run all tests
- `yarn test:watch` - Watch mode for tests
- `yarn test:coverage` - Generate coverage report
- `yarn format` - Format with Prettier
- `yarn lint` - Lint with ESLint
- `yarn workspace [package] [command]` - Run package-specific commands
3. **Code Quality Standards**
- Use functional components with hooks
- Follow existing patterns for consistency
- Write comprehensive tests for all changes
- Include loading and error states
- Consider accessibility (ARIA, semantic HTML)
- Maintain responsive design principles
- Use JSDoc comments for type safety
- Keep bundle size in mind when adding dependencies
Widget System Architecture
The theme features a sophisticated widget system for the dashboard home page:
**Available Widgets:**
Recent Posts (blog)GitHub (profile, repos, PRs)Goodreads (reading activity)Instagram (posts, metrics)Spotify (playlists, tracks)Steam (gaming activity)Flickr (photo galleries)**Data Flow:**
1. Metrics API provides data (metrics.chrisvogt.me)
2. `fetchDataSource.js` actions handle API calls with deduplication
3. Redux reducers process and store data (INIT, SUCCESS, FAILURE states)
4. Selectors transform data for components
5. Components render with proper loading/error handling
Adding New Widgets
When creating a new widget:
1. Create component in `src/components/widgets/[name]/`
2. Add Redux actions and reducers for data fetching
3. Create selectors for data access
4. Add comprehensive mock data in `__mocks__/`
5. Write tests covering all states (loading, success, error)
6. Update documentation
Environment Variables
Configure these as needed:
`GATSBY_METRICS_API_URL` - Metrics API endpoint`GATSBY_GITHUB_TOKEN` - GitHub API token`GATSBY_SPOTIFY_CLIENT_ID` - Spotify client ID`GATSBY_INSTAGRAM_ACCESS_TOKEN` - Instagram token`GATSBY_GOODREADS_API_KEY` - Goodreads key`GATSBY_STEAM_API_KEY` - Steam keyDecoupling Personal Information
**Current Goal**: Make the theme generic and reusable by removing hardcoded personal information.
**High Priority Files:**
`theme/src/components/h-card.js` - Personal details`theme/src/components/home-header-content.js` - Name, description`theme/src/data/social-profiles.json` - Social links`theme/gatsby-config.js` - Site metadata**Strategy:**
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 config
5. Update tests with mock data
6. Document all configuration options
**Configuration should support:**
Site metadata (title, description)Widget configuration (API endpoints, usernames)Social profiles (configurable links)Personal information (name, location, bio)Theme options (styling, behavior)Plugin options (content sources)Testing Strategy
The project uses comprehensive testing:
**Jest**: Unit testing framework**React Testing Library**: Component testing with DOM queries**React Test Renderer**: Snapshot testing**Redux Mock Store**: Mock Redux for component testing**Jest Canvas Mock**: Canvas API mocking**Identity Object Proxy**: CSS/SCSS module mocking**File Mock**: Static asset mocking**When writing tests:**
Cover all component states (loading, success, error)Use mock data from `__mocks__/` directoryTest user interactions with Testing LibraryInclude snapshot tests for visual regressionMock external dependencies and APIsAim for high coverage while keeping tests maintainableDevelopment Patterns
Follow these established patterns:
Functional components with hooks (no class components)Consistent prop interfaces across similar componentsAlways handle loading and error statesUse Theme UI components for stylingSupport dark/light modeLazy load components for performanceUse MDX for content with React component integrationRedux actions for all API callsProper error handling with retry logicAccessibility-first approachPerformance Considerations
Use lazy loading for widgets and heavy componentsOptimize images with Sharp pluginMinimize bundle size (code splitting)Consider CDN deployment optimizationsFont loading optimizationMonitor and reduce bundle size impact of dependenciesBuild and Deployment
Gatsby generates static filesImages optimized with SharpSEO via structured data and meta tagsCode splitting and lazy loading enabledCDN-ready static outputImportant Guidelines
Maintain backward compatibility when making changesUpdate tests and mocks when modifying widgetsStore API keys in environment variables onlyUse HTTPS for local developmentPrioritize accessibility in all featuresTest across multiple browsers and devicesKeep dependencies updated for securityFollow responsive design principlesConsider bundle size with every changeDocument all configuration optionsCommon Issues
**HTTPS Required**: Local development needs HTTPS setup**API Rate Limits**: Use tokens where available (GitHub)**Widget Loading**: Always implement loading/error states**Mock Data**: Keep mocks in sync with real API responses**Workspace Commands**: Use `yarn workspace` for package-specific tasks