Cursor Rules for gatsby-theme-chronogrove
Project Overview
This is a Gatsby theme monorepo that powers www.chrisvogt.me - a personal website and blog with a social dashboard home page. The project uses Yarn workspaces to separate the theme code from the content.
Current Goal: Decouple all personal information and www.chrisvogt.me content from the /theme directory to make the theme more generic and reusable.
Architecture
- Root: Contains workspace configuration and shared tooling
theme/: The Gatsby theme package (gatsby-theme-chronogrove)www.chrisvogt.me/: The actual website content and configuration
Back-end API
metrics.chrisvogt.me/: Backend API for widgets, uses Firebase, Firestore and scheduled Firebase Functions to sync and cache third-party data- Code is at https://github.com/chrisvogt/metrics
Key Technologies
- Gatsby 5.x: Static site generator
- React 18.x: UI framework
- Theme UI: Design system and styling (CSS-in-JS)
- Redux Toolkit: State management
- Jest: Testing framework with comprehensive setup
- Yarn v4 Workspaces: Monorepo management
- MDX: Content authoring with React components
- FontAwesome: Icon library
Development Setup
- Node.js: >=20 (see
.node_version and .nvmrc)
- Yarn: >=4.0.0 (see
packageManager in package.json)
- HTTPS: Local development requires HTTPS (see
develop:https script)
- Workspace Commands: Use
yarn workspace [package] [command] for package-specific operations
Available Scripts
yarn develop - Start development server with HTTPSyarn test - Run all testsyarn test:watch - Run tests in watch modeyarn test:coverage - Run tests with coverage reportyarn format - Format code with Prettieryarn lint - Lint code with ESLint
The theme includes a sophisticated widget system for the home page dashboard:
- Recent Posts: Latest blog posts
- GitHub: GitHub profile data, pinned repos, PRs
- Goodreads: Reading activity and book lists
- Instagram: Instagram posts and metrics
- Spotify: Music playlists and top tracks
- Steam: Gaming activity
- Flickr: Photo galleries and image collections
Data Flow
- Data Sources: Metrics API at
metrics.chrisvogt.me (backed by chrisvogt/metrics GitHub repo)
- Actions:
fetchDataSource.js handles API calls with deduplication
- Reducers: Process and store data with loading states (INIT, SUCCESS, FAILURE)
- Selectors: Transform data for components
- Components: Display data with loading states and error handling
Environment Variables
The following environment variables may be required for full functionality:
GATSBY_METRICS_API_URL - Metrics API endpoint (defaults to metrics.chrisvogt.me)GATSBY_GITHUB_TOKEN - GitHub API token for enhanced rate limitsGATSBY_SPOTIFY_CLIENT_ID - Spotify API client IDGATSBY_INSTAGRAM_ACCESS_TOKEN - Instagram API access tokenGATSBY_GOODREADS_API_KEY - Goodreads API keyGATSBY_STEAM_API_KEY - Steam API key
The following files contain hardcoded personal information that needs to be made configurable:
High Priority (Core Theme Files)
theme/src/components/h-card.js - Personal details, email, locationtheme/src/components/home-header-content.js - Name, personal descriptiontheme/src/data/social-profiles.json - Social media links and usernamestheme/gatsby-config.js - Default site metadata with personal info
Medium Priority (Configuration)
theme/src/templates/home.js - SEO metadata with personal detailstheme/src/components/footer/footer.js - GitHub source linkscripts/postinstall-banner.js - Personal branding (root level)index.js - Personal branding (root level)
Low Priority (Content)
www.chrisvogt.me/ directory - All content should remain as-is
Testing Strategy
- Jest: Unit testing framework with comprehensive configuration
- React Testing Library: Component testing with DOM queries and user interactions
- React Test Renderer: Snapshot testing for visual regression testing
- Redux Mock Store: Mock Redux store for testing components with state
- Jest Canvas Mock: Canvas API mocking for visual components
- Identity Object Proxy: CSS/SCSS module mocking
- File Mock: Static asset mocking (images, fonts, etc.)
- Mock Data: Comprehensive mocks for external APIs in
__mocks__/ directory
Development Patterns
- Functional components with hooks
- Consistent prop interfaces
- Loading and error states
- Accessibility considerations
- Responsive design
- Redux actions for API calls
- Error handling and retry logic
- Theme UI components with dark/light mode support
- MDX for content with React component integration
- Lazy loading for performance optimization
External Dependencies
- Backing Service: Metrics API at metrics.chrisvogt.me
- Image Hosting: Cloudinary and Imagix for external CDNs
- Static Assets: Local images in
static/ directory
- Font Loading: Google Fonts and FontAwesome
- Analytics: (Configured in site-specific gatsby-config.js)
Code Quality
- ESLint: Code linting with React and accessibility rules
- Prettier: Code formatting with consistent configuration
- Husky: Git hooks for pre-commit linting and formatting
- TypeScript-like: JSDoc comments for type safety
- EditorConfig: Consistent editor settings
Recent Development Priorities (Based on Git History)
- Performance: Lazy loading, font optimization, bundle size reduction
- Accessibility: Skip links, contrast improvements, keyboard navigation
- Widget Features: New Steam AI summary, Spotify iframe support
- Testing: Jest upgrades, improved test coverage, warning resolution
- Content Management: Better SEO, structured data, content organization
Common Development Tasks
When adding new widgets:
- Create widget component in
src/components/widgets/[name]/
- Add Redux actions and reducers
- Create selectors for data access
- Add mock data
- Write comprehensive tests
- Update documentation
When decoupling personal information:
- Move hardcoded values to site metadata configuration
- Create selectors for accessing personal data
- Update components to use selectors instead of hardcoded values
- Provide sensible defaults in theme configuration
- Update tests to use mock data
- Document configuration options
Configuration Strategy
The theme should support configuration through:
- Site Metadata: Core site information (title, description, etc.)
- Widget Configuration: API endpoints and usernames for each widget
- Social Profiles: Configurable social media links
- Personal Information: Name, location, bio, etc.
- Theme Options: Customizable styling and behavior
- Gatsby Plugins: Configurable plugin options for content sources
Build and Deployment
- Static Generation: Gatsby builds static files for deployment
- Image Optimization: Sharp plugin for responsive images
- SEO: Structured data and meta tags
- Performance: Code splitting and lazy loading
- CDN Ready: Optimized for CDN deployment
Important Notes
- Follow existing patterns and maintain backward compatibility
- Update tests and mocks when modifying existing widgets
- Consider performance implications
- Use HTTPS for local development
- Store API keys in environment variables
- Regular security updates for dependencies
- Prioritize accessibility in all new features
- Maintain comprehensive test coverage
- Use semantic HTML and ARIA attributes
- Follow responsive design principles
- Test with multiple browsers and devices
- Consider bundle size impact when adding dependencies