Gatsby Theme Development Assistant

Expert guidance for developing and maintaining gatsby-theme-chronogrove, a sophisticated Gatsby theme monorepo that powers personal websites with social dashboard functionality.

Project Context

This is a Gatsby theme monorepo with a widget-based architecture. The theme is separated from content using Yarn workspaces, featuring a social dashboard home page with integrations for GitHub, Spotify, Goodreads, Instagram, Steam, and Flickr.

**Primary Objective**: Decouple all personal information from the `/theme` directory to make it generic and reusable.

Architecture Understanding

Workspace Structure

Technology Stack

Development Requirements

Widget System Architecture

Data Flow Pattern

1. **Data Sources**: Fetch from Metrics API (`metrics.chrisvogt.me`)

2. **Actions**: `fetchDataSource.js` with deduplication

3. **Reducers**: Process data with loading states (INIT, SUCCESS, FAILURE)

4. **Selectors**: Transform data for components

5. **Components**: Display with loading/error states

Available Widgets

Development Workflow

Common Scripts

```bash

Development

yarn develop # Start HTTPS dev server

yarn workspace theme develop

Testing

yarn test # Run all tests

yarn test:watch # Watch mode

yarn test:coverage # With coverage

Code Quality

yarn format # Prettier formatting

yarn lint # ESLint linting

```

Adding New Widgets

Follow this pattern:

1. **Create Component Structure**

- Place in `src/components/widgets/[name]/`

- Include main component, subcomponents, and styles

2. **Implement Redux Layer**

- Add actions in `src/state/actions/`

- Create reducer in `src/state/reducers/`

- Build selectors in `src/state/selectors/`

3. **Add Mock Data**

- Create mocks in `__mocks__/` directory

- Follow existing patterns for API responses

4. **Write Tests**

- Component tests with React Testing Library

- Snapshot tests with React Test Renderer

- Redux action/reducer tests

- Selector tests

5. **Document Configuration**

- Update environment variable docs

- Add widget configuration options

- Update README with usage instructions

Decoupling Personal Information

**Priority Files to Address:**

**High Priority:**

**Medium Priority:**

**Strategy:**

1. Move hardcoded values to site metadata/theme options

2. Create selectors for accessing configuration

3. Update components to use selectors

4. Provide sensible defaults

5. Update tests with mock data

6. Document all configuration options

Testing Strategy

Test Infrastructure

Testing Patterns

Development Patterns

Component Design

State Management

Content Authoring

Environment Variables

```bash

Required for full functionality

GATSBY_METRICS_API_URL=metrics.chrisvogt.me

GATSBY_GITHUB_TOKEN=<token>

GATSBY_SPOTIFY_CLIENT_ID=<id>

GATSBY_INSTAGRAM_ACCESS_TOKEN=<token>

GATSBY_GOODREADS_API_KEY=<key>

GATSBY_STEAM_API_KEY=<key>

```

Configuration Strategy

Make theme configurable through:

1. **Site Metadata**: Core site information

2. **Widget Configuration**: API endpoints, usernames

3. **Social Profiles**: Social media links

4. **Personal Information**: Name, location, bio

5. **Theme Options**: Styling, behavior customization

6. **Gatsby Plugins**: Content source configuration

Code Quality Standards

Linting & Formatting

Best Practices

Build & Deployment

Optimization

Performance Considerations

Important Constraints

1. **HTTPS Required**: Local development must use HTTPS

2. **API Dependencies**: Widgets rely on metrics API availability

3. **Node Version**: Must use Node.js >=20

4. **Yarn Version**: Workspace features require Yarn >=4

5. **Backward Compatibility**: Maintain compatibility when refactoring

6. **Security**: Never commit API keys; use environment variables

7. **Accessibility**: All features must meet WCAG standards

8. **Test Coverage**: Maintain comprehensive test coverage

Common Pitfalls

Additional Resources