Gatsby Theme Chronogrove Development
Development guidelines for gatsby-theme-chronogrove - a Gatsby theme monorepo powering personal websites with a social dashboard home page.
Project Architecture
This is a Yarn v4 workspaces monorepo with the following structure:
**Root**: Workspace configuration and shared tooling**`theme/`**: The reusable Gatsby theme package (`gatsby-theme-chronogrove`)**`www.chrisvogt.me/`**: Example website content and configuration**Backend API**: `metrics.chrisvogt.me` - Firebase/Firestore backend for widget data (separate repo: chrisvogt/metrics)Technology Stack
**Gatsby 5.x**: Static site generator**React 18.x**: UI framework with functional components and hooks**Theme UI**: CSS-in-JS design system with dark/light mode support**Redux Toolkit**: State management for widget data**Jest + React Testing Library**: Testing framework with comprehensive mocks**MDX**: Content authoring with React components**Yarn v4 Workspaces**: Monorepo management**FontAwesome**: Icon libraryDevelopment Setup
1. **Node.js**: >=20 (check `.node_version` and `.nvmrc`)
2. **Yarn**: >=4.0.0 (enforced via `packageManager` in package.json)
3. **HTTPS Required**: Local development requires HTTPS
4. **Workspace Commands**: `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 # Generate coverage report
yarn format # Format code with Prettier
yarn lint # Lint code with ESLint
```
Widget System Architecture
The theme features a dashboard widget system for displaying external data:
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**Flickr**: Photo galleriesData Flow Pattern
1. **Data Sources**: Metrics API at `metrics.chrisvogt.me`
2. **Actions**: `fetchDataSource.js` handles API calls with deduplication
3. **Reducers**: Process data with loading states (INIT, SUCCESS, FAILURE)
4. **Selectors**: Transform data for components
5. **Components**: Display data with loading/error states
Adding New Widgets
When creating a new widget:
1. Create component directory: `src/components/widgets/[name]/`
2. Add Redux actions and reducers for data fetching
3. Create selectors for data access
4. Add comprehensive mock data for testing
5. Write unit tests with React Testing Library
6. Update documentation
Environment Variables
Configure these variables for full widget functionality:
```bash
GATSBY_METRICS_API_URL # Metrics API endpoint (defaults to metrics.chrisvogt.me)
GATSBY_GITHUB_TOKEN # GitHub API token
GATSBY_SPOTIFY_CLIENT_ID # Spotify API credentials
GATSBY_INSTAGRAM_ACCESS_TOKEN # Instagram API token
GATSBY_GOODREADS_API_KEY # Goodreads API key
GATSBY_STEAM_API_KEY # Steam API key
```
Store these in `.env.development` (gitignored).
Current Priority: Decoupling Personal Information
**Goal**: Remove all hardcoded personal information from `/theme` directory to make the theme reusable.
High Priority Files (Core Theme)
`theme/src/components/h-card.js` - Personal details, email, location`theme/src/components/home-header-content.js` - Name, bio`theme/src/data/social-profiles.json` - Social media usernames`theme/gatsby-config.js` - Default site metadataMedium Priority Files (Configuration)
`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 brandingDecoupling Strategy
When removing hardcoded personal information:
1. Move hardcoded values to site metadata configuration
2. Create selectors for accessing configurable 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 new configuration options in README
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**Theme Options**: Styling and behavior customization**Gatsby Plugins**: Content source configurationTesting Strategy
**Jest**: Unit testing with comprehensive configuration**React Testing Library**: Component testing with DOM queries and user interactions**React Test Renderer**: Snapshot testing for visual regression**Redux Mock Store**: Mock 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)**Mock Data**: Comprehensive API mocks in `__mocks__/` directoryAlways update tests when modifying widgets or data flow.
Development Patterns
Use functional components with hooksMaintain consistent prop interfacesAlways handle loading and error statesConsider accessibility (ARIA attributes, semantic HTML, keyboard navigation)Design responsively for all screen sizesUse Redux actions for API callsImplement error handling and retry logicLeverage Theme UI components with dark/light mode supportWrite content in MDX with React component integrationOptimize performance with lazy loadingCode Quality Tools
**ESLint**: React and accessibility rules**Prettier**: Consistent code formatting**Husky**: Pre-commit hooks for linting and formatting**JSDoc**: Type safety documentation**EditorConfig**: Consistent editor settingsExternal Dependencies
**Metrics API**: Backend at metrics.chrisvogt.me (chrisvogt/metrics repo)**Image CDNs**: Cloudinary and Imagix**Static Assets**: Local `static/` directory**Fonts**: Google Fonts and FontAwesome**Analytics**: Configured per-site in gatsby-config.jsBuild and Deployment
**Static Generation**: Gatsby builds optimized static files**Image Optimization**: Sharp plugin for responsive images**SEO**: Structured data and meta tags**Performance**: Code splitting and lazy loading**CDN Ready**: Optimized for CDN deploymentImportant Development Guidelines
Follow existing patterns and maintain backward compatibilityUpdate tests and mocks when modifying widgetsConsider performance implications (bundle size, lazy loading)**Always use HTTPS** for local developmentStore all API keys in environment variables (never commit)Prioritize accessibility in all featuresMaintain comprehensive test coverageTest across multiple browsers and devicesUse semantic HTML and ARIA attributesFollow responsive design principlesRegular security updates for dependenciesRecent Development Focus
Based on git history, recent priorities include:
**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 organizationQuick Reference
```bash
Install dependencies
yarn install
Start development server (HTTPS)
yarn develop
Run tests
yarn test
Run tests in watch mode
yarn test:watch
Format and lint
yarn format && yarn lint
Workspace-specific command
yarn workspace gatsby-theme-chronogrove [command]
yarn workspace www.chrisvogt.me [command]
```
Key Files Reference
**Theme Entry**: `theme/gatsby-config.js`**Widget Components**: `theme/src/components/widgets/`**Redux Setup**: `theme/src/state/`**Mock Data**: `theme/__mocks__/`**Test Setup**: `theme/jest.config.js`, `theme/jest.setup.js`**Social Profiles**: `theme/src/data/social-profiles.json`**Content**: `www.chrisvogt.me/content/`