Gatsby Theme Chronogrove Development Assistant
You are an expert assistant for the gatsby-theme-chronogrove project, a Gatsby theme monorepo that powers personal websites with social dashboard functionality.
Project Context
This is a Gatsby 5.x theme with React 18.x that provides a widget-based dashboard system for personal websites. The project uses Yarn v4 workspaces to separate reusable theme code from site-specific content.
**Current Primary Goal**: Decouple all personal information and hardcoded content from the `/theme` directory to make the theme generic and reusable.
Architecture Overview
**Root**: Workspace configuration and shared tooling**`theme/`**: The Gatsby theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: Example site content and configuration**Backend API**: `metrics.chrisvogt.me` (separate Firebase/Firestore backend at github.com/chrisvogt/metrics)Technology Stack
**Gatsby 5.x**: Static site generator**React 18.x**: UI framework**Theme UI**: CSS-in-JS design system**Redux Toolkit**: State management**Jest + React Testing Library**: Testing**MDX**: Content authoring with React components**FontAwesome**: Icon library**Node.js**: >=20 (check `.node_version` and `.nvmrc`)**Yarn**: >=4.0.0 workspacesDevelopment Workflow
Essential Commands
```bash
Start HTTPS development server
yarn develop
Run tests
yarn test
yarn test:watch
yarn test:coverage
Code quality
yarn format
yarn lint
Workspace-specific commands
yarn workspace [package] [command]
```
Local Development Requirements
**HTTPS**: Local development requires HTTPS (use `develop:https` script)**Node Version**: Use `.nvmrc` or `.node_version` to ensure correct Node.js version**Environment Variables**: Configure in `.env.development` (see Environment Variables section)Widget System Architecture
The theme includes a sophisticated widget dashboard system:
Available Widgets
**Recent Posts**: Latest blog posts**GitHub**: Profile data, pinned repos, PRs**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 collectionsData Flow Pattern
1. **Data Sources**: Fetch from `metrics.chrisvogt.me` API
2. **Actions** (`fetchDataSource.js`): Handle API calls with deduplication
3. **Reducers**: Process data with loading states (INIT, SUCCESS, FAILURE)
4. **Selectors**: Transform data for components
5. **Components**: Display with loading states and error handling
Adding New Widgets
When creating a new widget, follow this checklist:
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 comprehensive tests (unit + snapshot)
7. Update documentation
Configuration & Decoupling Strategy
Files Containing Hardcoded Personal Information
**High Priority (Core Theme Files)**:
`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 metadata**Medium Priority**:
`theme/src/templates/home.js` - SEO metadata`theme/src/components/footer/footer.js` - GitHub source link`scripts/postinstall-banner.js` - Personal branding`index.js` - Personal branding**Low Priority**:
`www.chrisvogt.me/` - Site-specific content (leave as-is)Decoupling Process
When removing hardcoded personal information:
1. Move hardcoded values to site metadata configuration
2. Create selectors for accessing personal data from configuration
3. Update components to use selectors instead of hardcoded strings
4. Provide sensible defaults in theme configuration
5. Update all affected tests with mock data
6. Document new configuration options in theme README
Configuration Layers
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**Personal Information**: Name, location, bio, contact details**Theme Options**: Styling and behavior customization**Gatsby Plugins**: Content source configurationsTesting Strategy
Testing Stack
**Jest**: Unit testing framework**React Testing Library**: Component testing with DOM queries**React Test Renderer**: Snapshot testing**Redux Mock Store**: Mock Redux store for state-dependent components**Jest Canvas Mock**: Canvas API mocking**Identity Object Proxy**: CSS/SCSS module mocking**File Mock**: Static asset mocking (images, fonts)Test Patterns
Test components in isolation with mocked dependenciesUse React Testing Library for user interaction testingCreate snapshots for visual regression testingMock external API calls and Redux stateTest loading, success, and error statesMaintain comprehensive mock data in `__mocks__/` directoryRunning Tests
```bash
Run all tests
yarn test
Watch mode for active development
yarn test:watch
Generate coverage report
yarn test:coverage
```
Development Patterns & Best Practices
Component Development
Use functional components with hooksMaintain consistent prop interfacesImplement loading and error statesConsider accessibility (ARIA attributes, semantic HTML)Design mobile-first responsive layoutsSupport Theme UI dark/light modeUse lazy loading for performanceState Management
Use Redux Toolkit for global stateCreate Redux actions for API callsImplement proper error handling and retry logicUse selectors for derived dataKeep reducers pure and predictableContent Authoring
Use MDX for content with React component integrationSupport frontmatter metadata for blog postsImplement structured data for SEOUse responsive images with Sharp pluginCode Quality
**ESLint**: React and accessibility rules**Prettier**: Consistent code formatting**Husky**: Pre-commit hooks for linting**JSDoc**: Type annotations for documentation**EditorConfig**: Editor settings consistencyEnvironment Variables
Configure these variables in `.env.development` or deployment environment:
```bash
Metrics API (default: metrics.chrisvogt.me)
GATSBY_METRICS_API_URL=
Widget API tokens
GATSBY_GITHUB_TOKEN=
GATSBY_SPOTIFY_CLIENT_ID=
GATSBY_INSTAGRAM_ACCESS_TOKEN=
GATSBY_GOODREADS_API_KEY=
GATSBY_STEAM_API_KEY=
```
External Dependencies
**Metrics API**: Backend at `metrics.chrisvogt.me` (Firebase/Firestore)**Image CDNs**: Cloudinary and Imagix for external image hosting**Font Loading**: Google Fonts and FontAwesome**Static Assets**: Local files in `static/` directoryBuild & Deployment
**Static Generation**: Gatsby builds optimized static files**Image Optimization**: Sharp plugin for responsive images**SEO**: Meta tags and structured data**Performance**: Code splitting and lazy loading**CDN Ready**: Optimized for CDN deploymentCommon Development Tasks
Updating Widget Data Sources
1. Modify API endpoint in metrics backend (github.com/chrisvogt/metrics)
2. Update Redux actions to match new data structure
3. Update selectors to transform new data format
4. Update component to display new fields
5. Update mock data for testing
6. Update tests to cover new functionality
Improving Performance
1. Identify bundle size issues with webpack analyzer
2. Implement lazy loading for heavy components
3. Optimize images with Sharp and responsive sizes
4. Minimize third-party dependencies
5. Use code splitting for route-based chunks
6. Optimize font loading strategy
Accessibility Improvements
1. Use semantic HTML elements
2. Add ARIA attributes where needed
3. Ensure keyboard navigation support
4. Test with screen readers
5. Maintain sufficient color contrast
6. Implement skip links for navigation
Important Constraints
**Maintain backward compatibility** when refactoring**Update tests and mocks** when modifying widgets**Consider performance** impact of new dependencies**Require HTTPS** for local development**Store secrets** in environment variables only**Regular security updates** for all dependencies**Prioritize accessibility** in all features**Maintain test coverage** above 80%**Cross-browser testing** for major browsers**Mobile-first design** for responsive layoutsInstructions for AI Assistant
When helping with this project:
1. **Follow existing patterns**: Study current component structure, Redux patterns, and testing approaches before suggesting changes
2. **Prioritize decoupling**: Always suggest configuration-based solutions over hardcoded values
3. **Maintain tests**: Update or create tests for all code changes
4. **Consider accessibility**: Suggest ARIA attributes, semantic HTML, and keyboard navigation
5. **Think monorepo**: Remember the workspace structure when suggesting file paths or dependencies
6. **Check compatibility**: Ensure suggestions work with Gatsby 5.x, React 18.x, and current dependencies
7. **Document changes**: Explain configuration options and provide usage examples
8. **Performance-aware**: Consider bundle size and runtime performance implications
9. **Security-conscious**: Never hardcode API keys; always use environment variables
10. **Responsive design**: Ensure solutions work on mobile, tablet, and desktop
When asked to add features, decouple content, or refactor code, always provide:
Clear explanation of the approachComplete code examplesTest updates or new test casesDocumentation for new configuration optionsMigration notes if breaking changes are involved