Monorepo TypeScript Web App (Site 8)

This skill provides AI coding agents with instructions for working in a monorepo-style web application with three main parts: the frontend (`client/`), the API service (`server1/`), and shared types/utilities (`shared/`).

Goal

Help AI coding agents make productive, small, high-confidence changes while preserving existing patterns, build scripts, and conventions.

Guiding Principles

1. **Prioritize minimal, focused edits** that preserve existing patterns and build/test scripts

2. **Follow repository conventions**: TypeScript strict mode, local `@site8/shared` package, existing ESLint/Prettier/Husky hooks

3. **Ask the user when in doubt** about breaking cross-package types or changing API route behavior

Quick Architecture Summary

**Frontend (`client/`):**

**Server (`server1/`):**

**Shared (`shared/`):**

Developer Workflows (Explicit Commands)

**Run frontend dev:**

```bash

cd client && npm install && npm run dev

```

**Build frontend:**

```bash

cd client && npm run build

```

(runs `tsc` type-check then `vite build`)

**Run server (production build):**

```bash

cd server1 && npm install && npm run build && npm start

```

**Lint & format:**

Run from the package workspace you modify (`client/` or `server1/`):

```bash

npm run lint

npm run format

```

Project-Specific Patterns & Conventions

1. **Strict TypeScript**: Both `client/tsconfig.json` and `server1/tsconfig.json` enable `strict` and many strict flags — prefer explicit types and avoid `any`

2. **Local shared package**: `@site8/shared` is a `file:../shared` dependency — modify shared types carefully and rebuild consumers

3. **Error handling**: Frontend initializes `createRoot` with custom error hooks (`client/src/main.tsx`) — preserve `logError` usage

4. **Server routing**: `server1/src/server.ts` wires many small routers under `/api/*` — add routes under `app/routes/*` and register them in `server.ts`

5. **Security & ops**: Server uses `helmet`, `compression`, and rate limiting — respect these configs when adding endpoints

Files to Inspect Before Changing Code

Testing & CI Notes

Step-by-Step Instructions

When Making Changes

1. **Read the relevant entry files** listed above to understand the current architecture

2. **Make the smallest reproducible edit** that accomplishes the goal

3. **Preserve existing patterns** (strict types, error handling, routing structure)

4. **Run lint/format** in the affected workspace

5. **Test the build** in the affected workspace

Adding a New Server Route

1. Create `server1/src/app/routes/newRoute.ts`

2. Export router from the new file

3. Register router in `server1/src/server.ts` under `/api/new`

4. Run `cd server1 && npm run build` to verify

5. Respect existing security middleware (helmet, rate limiting)

Adding a Shared Type

1. Add type to `shared/src/index.ts`

2. Run `cd shared && npm run build`

3. Update imports in `client`/`server1`

4. Run builds in both consumers to verify

5. Include a note about required rebuild steps if this is part of a PR

Modifying Frontend Components

1. Make changes in `client/src`

2. Preserve `logError` usage for error boundaries

3. Run `cd client && npm run lint && npm run format`

4. Run `cd client && npm run build` to verify types

5. Test with `npm run dev` or `npm run test` as appropriate

When a Public API Change Affects Both Client and Server

1. Update `shared/` type(s) first

2. Rebuild shared: `cd shared && npm run build`

3. Update server implementation in `server1/src/app/routes/*`

4. Update client usage in `client/src`

5. Build both to verify: `cd server1 && npm run build` and `cd client && npm run build`

6. Include rebuild steps in PR description

Constraints

Examples

**Example 1: Add a new API endpoint**

```typescript

// server1/src/app/routes/newRoute.ts

import { Router } from 'express';

const router = Router();

router.get('/hello', (req, res) => {

res.json({ message: 'Hello' });

});

export default router;

// Then in server1/src/server.ts:

import newRoute from './app/routes/newRoute';

app.use('/api/new', newRoute);

```

**Example 2: Add a shared type**

```typescript

// shared/src/index.ts

export interface NewType {

id: string;

name: string;

}

// Then rebuild:

// cd shared && npm run build

// cd client && npm install

// cd server1 && npm install

```