Astro + React Documentation Site

Help AI coding agents be productive editing this Astro-based documentation site with React/TypeScript interactive features.

Quick Start Commands

Run from project root using `pnpm` (preferred) or `npm`:

```bash

pnpm run dev # Local dev server

pnpm run build # Production build → dist/

pnpm run preview # Preview production build

pnpm install # Install dependencies

```

Architecture & Key Files

Site Structure

This is an Astro project using React components for interactive parts:

- `src/pages/index.astro` — Homepage

- `src/pages/blackjack/*.astro` — Documentation pages

- `src/pages/game/` — Interactive React/TS feature

Interactive Game Feature

Located in `src/pages/game/`:

Configuration Files

Step-by-Step Instructions

1. Setting Up the Environment

When starting work:

1. Check the project uses `pnpm` (look for `pnpm-lock.yaml`)

2. Run `pnpm install` to install dependencies

3. Start dev server with `pnpm run dev` (default port 4321)

4. Verify the site loads at `http://localhost:4321`

2. Adding a New Documentation Page

To create a new page:

1. Create `src/pages/<name>.astro`

2. Wrap content in `BaseLayout`:

```astro

---

import BaseLayout from '../layouts/BaseLayout.astro';

---

<BaseLayout title="Page Title">

<!-- Your content here -->

</BaseLayout>

```

3. The page will be available at `/<name>`

3. Modifying Layout or Sidebar

For site-wide changes:

4. Updating Game Logic

To modify the interactive game:

1. **Hook logic**: Edit `src/pages/game/hooks/hooks.ts`

2. **UI component**: Edit `src/pages/game/index.tsx`

3. **Important**: Keep API consistent between hook exports and component imports

**Known issue**: There's a naming mismatch:

5. Styling Changes

Follow existing patterns:

6. Building for Production

Before deploying:

1. Run `pnpm run build` to create production bundle

2. Run `pnpm run preview` to test the build locally

3. Verify all routes and interactive features work correctly

Patterns & Conventions

Astro + React Interop

File Types

Routing

Common Tasks Examples

Adding a New Section

```astro

---

// src/pages/new-section.astro

import BaseLayout from '../layouts/BaseLayout.astro';

---

<BaseLayout title="New Section">

<h1>New Section</h1>

<p>Content goes here</p>

</BaseLayout>

```

Creating an Interactive Component

```tsx

// src/components/InteractiveWidget.tsx

import { useState } from 'react';

export default function InteractiveWidget() {

const [count, setCount] = useState(0);

return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;

}

```

Using Interactive Component in Astro Page

```astro

---

import BaseLayout from '../layouts/BaseLayout.astro';

import InteractiveWidget from '../components/InteractiveWidget.tsx';

---

<BaseLayout title="Interactive Page">

<InteractiveWidget client:load />

</BaseLayout>

```

Important Constraints

What to Avoid

1. **Server-only APIs**: Don't use Node.js-only APIs in `.astro` frontmatter without checking Astro docs

2. **Client-side in Astro**: Keep client-side React code in `.tsx` files or within proper client directives

3. **Breaking TypeScript**: Project uses strict mode — maintain type safety

4. **Inconsistent naming**: Align function names between hooks and consuming components

Fix-First Suggestions

When you encounter the game feature:

1. Check if `dealHand()` is called but `onDeal()` is exported

2. Standardize naming: either update hook to export `dealHand` or update component to call `onDeal`

3. Keep hook API (`useGameEngine`) consistent with component usage

Validation Workflow

Before completing work:

1. Run `pnpm run dev` locally

2. Navigate to modified pages

3. Test interactive features (if applicable)

4. Run `pnpm run build` to check for build errors

5. Run `pnpm run preview` to test production bundle

Key Files Reference

Notes