Skip to content

Commit f4fb430

Browse files
good3ngood3n
committed
Migrate from Gatsby to Astro
- Replace Gatsby v4 with Astro v5 for static site generation - Convert static components (Header, Footer, PageTitle, Sidebar, DataList, Resource) to Astro with scoped CSS - Keep Nav and ThemeToggle as React islands (client:load) for interactivity - Replace styled-components with global CSS and Astro scoped styles - Replace React Context with nanostores for theme state - Add mobile sidebar dropdown using details/summary - Add FOUC prevention via inline theme script - Update netlify.toml for Astro (dist output) - Remove all Gatsby dependencies and config files
1 parent 22ea0bc commit f4fb430

79 files changed

Lines changed: 7328 additions & 33368 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/launch.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"version": "0.0.1",
3+
"configurations": [
4+
{
5+
"name": "dev",
6+
"runtimeExecutable": "/Users/tom/.nvm/versions/node/v24.13.0/bin/node",
7+
"runtimeArgs": ["node_modules/.bin/astro", "dev"],
8+
"port": 4321
9+
},
10+
{
11+
"name": "preview",
12+
"runtimeExecutable": "/Users/tom/.nvm/versions/node/v24.13.0/bin/node",
13+
"runtimeArgs": ["node_modules/.bin/astro", "preview"],
14+
"port": 4321
15+
}
16+
]
17+
}

‎.gitignore‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,9 @@ typings/
5454
# dotenv environment variable files
5555
.env*
5656

57-
# gatsby files
58-
.cache/
59-
public
57+
# astro build output
58+
dist/
59+
.astro/
6060

6161
# Mac files
6262
.DS_Store

‎CLAUDE.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**CodeHelp** is a Gatsby v4-based static site generator serving as a community-driven resource portal (codehelp.io). It aggregates curated links for developers, designers, and marketers across learning materials and development tools.
8+
9+
- **Framework**: Gatsby v4.5.2
10+
- **Language**: JavaScript/React v17
11+
- **Styling**: styled-components (CSS-in-JS)
12+
- **Deployment**: Netlify (automatic on git push)
13+
- **State Management**: React Context API (theme/dark mode)
14+
15+
## Common Development Commands
16+
17+
| Command | Purpose |
18+
|---------|---------|
19+
| `npm start` or `npm run develop` | Start dev server on localhost:8000 with hot reload |
20+
| `npm run build` | Build production-optimized site to `/public` |
21+
| `npm run serve` | Serve the built site locally for testing |
22+
| `npm run clean` | Clear Gatsby cache and build artifacts |
23+
| `npm run format` | Format all code with Prettier (2-space, single quotes) |
24+
| `npm run test` | Currently not implemented—echo stub only |
25+
26+
## Architecture & Code Structure
27+
28+
### Directory Layout
29+
30+
```
31+
src/
32+
├── pages/ # File-based routing (auto-creates routes)
33+
│ ├── index.js # Homepage (/)
34+
│ ├── learning.js # /learning resources page
35+
│ ├── resources.js # /resources development tools page
36+
│ └── 404.js # Not found page
37+
│
38+
├── components/ # Reusable React components
39+
│ ├── Layout.js # Main wrapper (contains globalContext Provider via gatsby-browser.js)
40+
│ ├── Header/ # Logo and navigation
41+
│ ├── Nav/ # Main nav links + Discord popup modal
42+
│ ├── Footer/ # Footer with links
43+
│ ├── Sidebar/ # Category navigation with anchor links
44+
│ ├── DataList/ # Maps data array → Resource cards
45+
│ ├── Resource/ # Individual resource card component
46+
│ ├── ThemeToggle/ # Dark/light mode switcher
47+
│ └── Seo.js # react-helmet wrapper for head management
48+
│
49+
├── context/ # React Context for state
50+
│ └── globalContext.js # Theme state (dark/light), persists to localStorage
51+
│
52+
├── hooks/
53+
│ └── useWindowSize.js # Track window dimensions for responsive design
54+
│
55+
├── data/ # Static JSON data (no database)
56+
│ ├── resources.json # Development tools/frameworks organized by category
57+
│ └── learning.json # Learning materials organized by category
58+
│
59+
├── assets/ # Static files
60+
│ ├── styles/ # Global + component-level styles
61+
│ ├── fonts/ # Custom fonts (Apercu-Mono-Pro)
62+
│ └── images/ # PNG, SVG assets
63+
│
64+
└── pages/ + components/ → Rendered via Layout wrapper → Theme provider
65+
```
66+
67+
### Data Flow & Structure
68+
69+
**Page rendering**:
70+
1. Pages (`resources.js`, `learning.js`) import static JSON from `src/data/`
71+
2. Pass data to `Sidebar` (category filters) and `DataList` (resource cards)
72+
3. Sidebar renders anchor links for category navigation
73+
4. DataList maps array → Resource components (individual cards)
74+
5. All styled with styled-components, theme-aware via Context
75+
76+
**Data shape** (JSON structure):
77+
```javascript
78+
{
79+
"resources": [
80+
{
81+
"label": {
82+
"id": "guides-info",
83+
"name": "General Guides & Information",
84+
"categories": [
85+
{
86+
"category": {
87+
"id": "web-development",
88+
"name": "Web Development",
89+
"resources": [
90+
{
91+
"name": "MDN Web Docs",
92+
"description": "...",
93+
"url": "https://..."
94+
}
95+
]
96+
}
97+
}
98+
]
99+
}
100+
}
101+
]
102+
}
103+
```
104+
105+
### Styling Architecture
106+
107+
- **CSS-in-JS** via styled-components
108+
- **Theme variables** defined in `src/assets/styles/` (e.g., `--color__background`, `--color__text`)
109+
- **Global styles** wrap all components with theme-aware colors
110+
- **Component styles**: Each component has a `.styles.js` file (e.g., `Header.styles.js`)
111+
- **Responsive design**: CSS media queries in component styles
112+
113+
### State Management
114+
115+
**Global Theme**:
116+
- Stored in `src/context/globalContext.js` (React Context)
117+
- Wrapped around entire app in `gatsby-browser.js`
118+
- Persists theme choice to localStorage
119+
- Switch via ThemeToggle component
120+
121+
### Key Plugins & Features
122+
123+
| Plugin | Purpose |
124+
|--------|---------|
125+
| gatsby-plugin-google-analytics | Google Analytics tracking (trackEvent on Discord clicks) |
126+
| gatsby-plugin-image/sharp | Optimized image handling and processing |
127+
| gatsby-plugin-styled-components | styled-components integration |
128+
| gatsby-plugin-anchor-links | Smooth anchor navigation for sidebar categories |
129+
| gatsby-plugin-manifest | PWA manifest for installability |
130+
| gatsby-plugin-offline | Service worker for offline PWA support |
131+
| gatsby-plugin-react-helmet | Head tag management via react-helmet |
132+
133+
## Important Config Files
134+
135+
| File | Notes |
136+
|------|-------|
137+
| `gatsby-config.js` | Plugin setup, site metadata, Google Analytics ID, PWA manifest |
138+
| `gatsby-browser.js` | Wraps app with globalContext Provider for theme state |
139+
| `.prettierrc` | Enforce 2-space indentation, single quotes, no semicolons, trailing commas |
140+
| `.eslintrc` | Airbnb config + React/JSX/a11y plugins |
141+
| `netlify.toml` | Netlify deployment (auto-builds on git push) |
142+
| `.env.development/.env.production` | Google Analytics ID (GOOGLE_ANALYTICS_ID) |
143+
144+
## Code Patterns & Conventions
145+
146+
### Component Structure
147+
- Functional components with hooks
148+
- styled-components for component styles
149+
- PropTypes for prop validation
150+
- File structure: `ComponentName.js` + `ComponentName.styles.js`
151+
152+
### Comments
153+
154+
- Always use **lowercase** unless referencing case-sensitive items (component names, file paths, variable names, etc.)
155+
- Write comments declaratively and directly, like a commit message
156+
- Focus on the "why" rather than obvious "what"
157+
- Examples:
158+
- ✓ `// toggle dark mode theme in localStorage`
159+
- ✗ `// This toggles the dark mode theme in localStorage`
160+
- ✓ `// map categories to sidebar navigation links`
161+
- ✗ `// Map categories to sidebar navigation links`
162+
163+
### Adding a New Resource/Learning Item
164+
1. Edit `src/data/resources.json` or `src/data/learning.json`
165+
2. Follow existing category/resource structure
166+
3. Run `npm start` to see changes (hot reload works)
167+
4. No build or deployment needed for local testing
168+
169+
### Adding a New Page
170+
1. Create `.js` file in `src/pages/` (Gatsby auto-routes)
171+
2. Export React component with Layout wrapper
172+
3. Use Seo component for head metadata
173+
4. Styling via styled-components
174+
175+
### Theme-Aware Styling
176+
```javascript
177+
import { useContext } from 'react'
178+
import { GlobalContext } from '../context/globalContext'
179+
180+
const MyComponent = () => {
181+
const { theme } = useContext(GlobalContext)
182+
183+
return styled.div`
184+
background: var(--color__background);
185+
color: var(--color__text);
186+
`
187+
}
188+
```
189+
190+
## Deployment & Build Process
191+
192+
- **Dev**: `npm start` → localhost:8000
193+
- **Production**: `npm run build` → outputs `/public/` with optimized assets
194+
- **Netlify**: Auto-detects gatsby-config.js, builds and deploys on git push to master
195+
- **Live site**: https://codehelp.io
196+
197+
## Linting & Formatting
198+
199+
- **ESLint**: Airbnb config enforces style rules
200+
- **Prettier**: Auto-format with `npm run format`
201+
- Pre-commit hooks: None currently configured (consider adding)
202+
203+
## Notes for Future Development
204+
205+
- Data is static JSON—no database or API backend
206+
- Theme switching is client-side only (Context + localStorage)
207+
- Analytics tracked on Discord link clicks (see Nav component)
208+
- Accessibility plugins enabled (jsx-a11y, manifest)
209+
- PWA support enabled (installable, offline fallback)
210+
- No automated tests currently—test suite commented in package.json

‎astro.config.mjs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { defineConfig } from 'astro/config';
2+
import react from '@astrojs/react';
3+
import sitemap from '@astrojs/sitemap';
4+
import partytown from '@astrojs/partytown';
5+
6+
export default defineConfig({
7+
site: 'https://codehelp.io',
8+
integrations: [
9+
react(),
10+
sitemap(),
11+
partytown({
12+
config: {
13+
forward: ['dataLayer.push', 'gtag']
14+
}
15+
})
16+
],
17+
image: {
18+
service: {
19+
entrypoint: 'astro/assets/services/noop'
20+
}
21+
},
22+
output: 'static'
23+
});

‎gatsby-browser.js‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎gatsby-config.js‎

Lines changed: 0 additions & 50 deletions
This file was deleted.

‎gatsby-node.js‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎gatsby-ssr.js‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎netlify.toml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,11 @@
1-
[[plugins]]
2-
package = "@netlify/plugin-gatsby"
1+
[build]
2+
command = "npm run build"
3+
publish = "dist"
4+
5+
[build.environment]
6+
NODE_VERSION = "20"
7+
8+
[[redirects]]
9+
from = "/*"
10+
to = "/404.html"
11+
status = 404

0 commit comments

Comments
 (0)