Gatsby Theme Chronogrove Development
You are a development assistant for **gatsby-theme-chronogrove**, a Gatsby theme monorepo that powers www.chrisvogt.me - a personal website and blog with a social dashboard home page.
Project Context
This is a Yarn workspaces monorepo with three main parts:
**Root**: Workspace configuration and shared tooling**`theme/`**: The Gatsby theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: The actual website content and configuration**Backend API**: `metrics.chrisvogt.me` (separate repo: chrisvogt/metrics) provides data for dashboard widgets**Primary Goal**: Decouple all personal information and www.chrisvogt.me content from the `/theme` directory to make the theme 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**Jest + React Testing Library** - Testing framework**Yarn v4 Workspaces** - Monorepo management**MDX** - Content authoring with React components**FontAwesome** - Icon libraryDevelopment Setup Requirements
1. **Node.js**: >=20 (check `.node_version` and `.nvmrc`)
2. **Yarn**: >=4.0.0 (check `packageManager` in package.json)
3. **HTTPS**: Local development requires HTTPS (use `develop:https` script)
4. **Workspace Commands**: Use `yarn workspace [package] [command]` for package-specific operations
Available Scripts
```bash
yarn develop # Start development server with HTTPS
yarn test # Run all tests
yarn test:watch # Run tests in watch mode
yarn test:coverage # Run tests with coverage report
yarn format # Format code with Prettier
yarn lint # Lint code with ESLint
```
Widget System Architecture
The theme includes a sophisticated widget system for the home page dashboard with these data sources:
**Recent Posts** - Latest blog posts**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`
2. **Actions**: `fetchDataSource.js` handles API calls with deduplication
3. **Reducers**: Process and store data with loading states (INIT, SUCCESS, FAILURE)
4. **Selectors**: Transform data for components
5. **Components**: Display data with loading/error states
Environment Variables
Configure these environment variables for full functionality:
```bash
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
```
Decoupling Personal Information
When working on making the theme more generic, prioritize these files:
High Priority (Core Theme Files)
`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 infoMedium Priority (Configuration)
`theme/src/templates/home.js` - SEO metadata with personal details`theme/src/components/footer/footer.js` - GitHub source link`scripts/postinstall-banner.js` - Personal branding`index.js` - Personal brandingStrategy for Decoupling
1. Move hardcoded values to site metadata configuration
2. Create selectors for accessing personal data
3. Update components to use selectors instead of hardcoded values
4. Provide sensible defaults in theme configuration
5. Update tests to use mock data
6. Document configuration options
Testing Strategy
The project uses comprehensive testing with:
**Jest** - Unit testing framework**React Testing Library** - Component testing with DOM queries**React Test Renderer** - Snapshot testing for visual regression**Redux Mock Store** - Mock Redux store for testing stateful components**Jest Canvas Mock** - Canvas API mocking**Identity Object Proxy** - CSS/SCSS module mocking**File Mock** - Static asset mocking (images, fonts, etc.)**Mock Data** - Comprehensive mocks in `__mocks__/` directoryWhen writing tests:
Use functional components with hooksTest loading and error statesConsider accessibilityMaintain high test coverageUpdate snapshots when visual changes are intentionalCommon Development Tasks
Adding a New Widget
1. Create widget component in `src/components/widgets/[name]/`
2. Add Redux actions and reducers for data fetching
3. Create selectors for data access
4. Add mock data in `__mocks__/`
5. Write comprehensive tests (unit, integration, snapshot)
6. Update documentation
Modifying Existing Widgets
1. Follow existing patterns and maintain backward compatibility
2. Update tests and mocks
3. Consider performance implications
4. Test loading and error states
5. Verify accessibility with screen readers
6. Check bundle size impact
Configuration Pattern
The theme should support configuration through:
**Site Metadata** - Core site information (title, description, etc.)**Widget Configuration** - API endpoints and usernames**Social Profiles** - Configurable social media links**Personal Information** - Name, location, bio, etc.**Theme Options** - Customizable styling and behavior**Gatsby Plugins** - Configurable plugin optionsDevelopment Patterns
Follow these patterns when writing code:
Use functional components with hooksMaintain consistent prop interfacesImplement loading and error statesConsider accessibility (ARIA attributes, semantic HTML)Design for responsive layoutsUse Redux actions for API callsImplement error handling and retry logicUse Theme UI components with dark/light mode supportAuthor content in MDX with React component integrationImplement lazy loading for performance optimizationCode Quality Standards
**ESLint** - Follow React and accessibility rules**Prettier** - Use consistent formatting**Husky** - Pre-commit linting and formatting enforced**JSDoc** - Add comments for type safety**EditorConfig** - Maintain consistent editor settingsBuild and Deployment Considerations
**Static Generation** - Gatsby builds static files**Image Optimization** - Sharp plugin for responsive images**SEO** - Include structured data and meta tags**Performance** - Use code splitting and lazy loading**CDN Ready** - Optimize for CDN deploymentExternal Dependencies
**Metrics API** - Backend at metrics.chrisvogt.me (Firebase/Firestore)**Image CDNs** - Cloudinary and Imagix for external images**Static Assets** - Local images in `static/` directory**Fonts** - Google Fonts and FontAwesome**Analytics** - Configured in site-specific gatsby-config.jsImportant Development Notes
Always use HTTPS for local developmentStore API keys in environment variables, never commit themPrioritize accessibility in all new featuresMaintain comprehensive test coverageTest with multiple browsers and devicesConsider bundle size impact when adding dependenciesUpdate security dependencies regularlyFollow responsive design principlesUse semantic HTML and ARIA attributesDocument configuration options thoroughlyWhen Assisting with Development
1. **Understand Context** - Check which workspace you're in (root, theme, or www.chrisvogt.me)
2. **Follow Patterns** - Match existing code patterns and conventions
3. **Test Coverage** - Write or update tests for all changes
4. **Accessibility** - Ensure keyboard navigation and screen reader support
5. **Performance** - Consider lazy loading and bundle size
6. **Documentation** - Update relevant documentation
7. **Backward Compatibility** - Don't break existing functionality
8. **Configuration** - Make features configurable rather than hardcoded