AI Agent Instructions: Fullstack Vite 7 (React) + Express + TypeScript + npm

You are an expert AI fullstack software engineer specialized in Vite 7, React, Express, TypeScript, and modern web architectures. Follow these rules strictly when modifying this codebase.

1. Project Structure & Context

Frontend: React SPA powered by Vite 7.x (Entry: src/main.tsx or client folder).
Backend: Express Node.js application (Server entry: server.ts or server folder).
Package Manager: npm (package-lock.json is the strict source of truth).
TypeScript Setup: Strict Mode enabled independently across both environments.

2. Express Backend TypeScript Rules

Typed Request/Response: Explicitly type Express route handlers using native Express types:

import { Request, Response, NextFunction } from 'express';
// Example for typed request bodies/params:
interface CreateUserBody { username: string; }
app.post('/user', (req: Request<{}, {}, CreateUserBody>, res: Response) => { ... });

Async Error Catching: Always wrap async middleware/route handlers in try/catch and pass errors to next(err). Do not let unhandled promise rejections crash the Node process.
Shared Types: If frontend and backend share types (e.g., API payloads, User models), place them in a shared directory or export them cleanly from the backend to prevent duplicating code.

3. Frontend React + Vite Rules

Component Typings: Use standard type inference or explicit return types (function Component(): React.JSX.Element). Avoid the legacy React.FC.
Strict Prop Types: Every component must have an explicitly typed interface or type for its props. No implicit any.
Event Handlers: Use exact React synthetic event types (e.g., React.ChangeEvent<HTMLInputElement>) instead of generic native events.
File Extensions: Use .tsx exclusively for files containing JSX. Use .ts strictly for pure logic, hooks, or type definitions.

4. Strict Code Quality & Native Guards

No any: Never use any. Use unknown for unpredictable runtime data (like Express req.body or frontend fetch payloads).
No Validation Libraries: Do not install Zod, TypeBox, or Yup. Write explicit, manual type predicate functions (function isUser(obj: any): obj is User) to safely validate runtime data incoming to both the server and client.
No Enums: Avoid TypeScript enum. Use string-literal unions (type Status = 'active' | 'pending') or const StatusEnum = { ... } as const.

5. Verification & Workflow Commands

Before declaring a task complete, you must verify both environments compile flawlessly via npm:

Install Dependencies: npm install
Type-Check Project: Run the designated workspace or folder type-checking scripts (e.g., npm run type-check or npx tsc --noEmit across both roots).
Build Verification: Run production build scripts (e.g., npm run build) to ensure both Express asset compilation and Vite bundling pass without error.

6. How to Respond

Verify Types First: Run type-checking commands automatically after modifying files to capture compilation breaks before presenting the solution.
Targeted Diffs: Provide concise, targeted updates. Do not rewrite whole files if only a few lines change.
Self-Correct: If a build command fails, read the compiler/Vite/Node logs, fix the root cause, and re-test before asking the user for help.

3.4 KiB Raw Blame History