Gatsby Theme Chronogrove Development

Expert assistant for developing gatsby-theme-chronogrove, a Gatsby 5 theme powering www.chrisvogt.me with a social dashboard home page and blog.

Project Structure

This is a Yarn v4 workspace monorepo:

Tech Stack

Development Workflow

Setup Commands

```bash

Install dependencies

yarn install

Start HTTPS development server (required)

yarn develop

Run tests

yarn test

yarn test:watch

yarn test:coverage

Code quality

yarn format

yarn lint

Workspace-specific commands

yarn workspace gatsby-theme-chronogrove [command]

yarn workspace www.chrisvogt.me [command]

```

Environment Variables

Create `.env.development` with:

```

GATSBY_METRICS_API_URL=https://metrics.chrisvogt.me

GATSBY_GITHUB_TOKEN=<optional>

GATSBY_SPOTIFY_CLIENT_ID=<optional>

GATSBY_INSTAGRAM_ACCESS_TOKEN=<optional>

GATSBY_GOODREADS_API_KEY=<optional>

GATSBY_STEAM_API_KEY=<optional>

```

Widget System Architecture

The theme includes a sophisticated widget system for the home page dashboard:

Available Widgets

Data Flow Pattern

1. **API Calls**: `fetchDataSource.js` with deduplication

2. **Redux Actions**: Dispatch INIT → SUCCESS/FAILURE

3. **Reducers**: Store data with loading states

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

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

Adding New Widgets

When adding a new widget:

1. **Create component structure**:

```

theme/src/components/widgets/[name]/

├── index.js # Main component

├── [name].js # Widget logic

└── __tests__/

└── [name].test.js # Tests

```

2. **Add Redux state**:

```javascript

// theme/src/state/actions/[name].js

export const fetchWidgetData = () => dispatch => {

dispatch({ type: 'WIDGET_INIT' });

return fetchDataSource('widget-endpoint')

.then(data => dispatch({ type: 'WIDGET_SUCCESS', payload: data }))

.catch(error => dispatch({ type: 'WIDGET_FAILURE', payload: error }));

};

// theme/src/state/reducers/[name].js

const initialState = { data: null, loading: false, error: null };

export default (state = initialState, action) => {

switch (action.type) {

case 'WIDGET_INIT': return { ...state, loading: true };

case 'WIDGET_SUCCESS': return { data: action.payload, loading: false, error: null };

case 'WIDGET_FAILURE': return { ...state, loading: false, error: action.payload };

default: return state;

}

};

```

3. **Create selectors**:

```javascript

// theme/src/state/selectors/[name].js

export const getWidgetData = state => state.widget.data;

export const isWidgetLoading = state => state.widget.loading;

```

4. **Add mock data**:

```javascript

// theme/__mocks__/[name]-data.js

export default { /* mock response */ };

```

5. **Write tests**:

```javascript

// Use React Testing Library + Redux Mock Store

import { render, screen } from '@testing-library/react';

import configureStore from 'redux-mock-store';

import Widget from '../index';

const mockStore = configureStore([]);

test('renders loading state', () => {

const store = mockStore({ widget: { loading: true } });

render(<Provider store={store}><Widget /></Provider>);

expect(screen.getByText(/loading/i)).toBeInTheDocument();

});

```

6. **Update documentation**: Add widget configuration to README

Decoupling Personal Information

**Current Goal**: Make the theme generic and reusable by moving hardcoded personal information to configuration.

High Priority Files (Core Theme)

Decoupling Pattern

1. **Move hardcoded values to siteMetadata**:

```javascript

// gatsby-config.js

module.exports = {

siteMetadata: {

author: {

name: 'Your Name',

email: '[email protected]',

location: 'City, State'

}

}

};

```

2. **Create selector**:

```javascript

// theme/src/state/selectors/site.js

export const getAuthorName = state => state.site?.siteMetadata?.author?.name || 'Author';

```

3. **Update component**:

```javascript

import { useStaticQuery, graphql } from 'gatsby';

const Component = () => {

const { site } = useStaticQuery(graphql`

query {

site { siteMetadata { author { name } } }

}

`);

return <div>{site.siteMetadata.author.name}</div>;

};

```

4. **Update tests with mocks**:

```javascript

const mockSiteMetadata = { author: { name: 'Test Author' } };

```

5. **Document configuration options** in theme README

Configuration Strategy

The theme should support configuration through:

Testing Requirements

Testing Stack

Test Patterns

```javascript

// Component with Redux state

import { render, screen } from '@testing-library/react';

import { Provider } from 'react-redux';

import configureStore from 'redux-mock-store';

const mockStore = configureStore([]);

test('renders widget with data', () => {

const store = mockStore({ widget: { data: mockData } });

render(<Provider store={store}><Widget /></Provider>);

expect(screen.getByText('Expected Content')).toBeInTheDocument();

});

// Async actions

import thunk from 'redux-thunk';

const mockStore = configureStore([thunk]);

test('fetches data successfully', async () => {

const store = mockStore({});

await store.dispatch(fetchData());

const actions = store.getActions();

expect(actions[0].type).toBe('DATA_INIT');

expect(actions[1].type).toBe('DATA_SUCCESS');

});

// Snapshot testing

import renderer from 'react-test-renderer';

test('matches snapshot', () => {

const tree = renderer.create(<Component />).toJSON();

expect(tree).toMatchSnapshot();

});

```

Mock Data Location

Development Patterns

Component Standards

Redux Patterns

Styling with Theme UI

```javascript

/** @jsx jsx */

import { jsx } from 'theme-ui';

const Component = () => (

<div sx={{

color: 'text',

bg: 'background',

p: 3,

borderRadius: 4

}}>

Content

</div>

);

```

MDX Integration

Code Quality Standards

Performance Considerations

When making changes, consider:

Build and Deployment

Important Notes

Common Tasks Reference

Run workspace commands

```bash

yarn workspace gatsby-theme-chronogrove test

yarn workspace www.chrisvogt.me develop

```

Update dependencies

```bash

yarn upgrade-interactive

```

Generate test coverage

```bash

yarn test:coverage

```

Format all code

```bash

yarn format

```

Lint with autofix

```bash

yarn lint --fix

```