Skip to content

Commit 383d05a

Browse files
rdonigianrdonigian
committed
create ai guidelines files
1 parent ba7fa31 commit 383d05a

File tree

2 files changed

+479
-110
lines changed

2 files changed

+479
-110
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 232 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,237 @@
1-
# Copilot Instructions
1+
# CORD Front-End Development Guidelines
22

3-
This project is a web application built with React 18, Material-UI (MUI), and GraphQL, using Yarn as the package manager and Razzle for the custom build process. Follow these guidelines to ensure consistent, high-quality code aligned with our coding standards.
3+
This document provides guidelines for developers working on the CORD Field front-end project, a UI built with React, Material-UI (MUI) v5, and GraphQL, using Yarn and Razzle. The front-end connects to the CORD API v3.
44

5-
## Coding Standards
5+
## Overview
66

7-
- Use camelCase for variables, functions, and methods.
7+
The CORD Field front-end enables [describe functionality briefly, e.g., field data management; replace with specific details if available]. It connects to the CORD API v3 by default at `http://localhost:3000`. For a complete setup guide, see the [cord-docs wiki](https://github.com/SeedCompany/cord-docs/wiki#new-hire-on-boarding).
8+
9+
## Build/Configuration Instructions
10+
11+
### Prerequisites
12+
13+
1. NodeJS (current version or LTS recommended, >= 18.x as per `package.json`).
14+
- Check version with `node -v`. If compilation errors occur (e.g., `Buffer` object missing `blob` property), upgrade NodeJS.
15+
2. Corepack enabled (`corepack enable`).
16+
3. Yarn (managed via Corepack).
17+
4. Local CORD API v3 server running (see [Connecting to the API Server](https://github.com/SeedCompany/cord-api-v3)).
18+
19+
### Setup
20+
21+
1. Install dependencies:
22+
23+
```bash
24+
yarn install
25+
```
26+
27+
2. Generate GraphQL schema and TypeScript types:
28+
29+
```bash
30+
yarn gql-gen
31+
```
32+
33+
### Development
34+
35+
1. Start the development server:
36+
37+
```bash
38+
yarn start
39+
```
40+
41+
### Connecting to the API Server
42+
43+
By default, the front-end connects to the local CORD API v3 server at `http://localhost:3000`. To use a different API server, create an `.env.local` file:
44+
45+
```dotenv
46+
RAZZLE_API_BASE_URL=http://your-api-server-host.com:3000
47+
```
48+
49+
### Running Tests
50+
51+
1. Run unit tests:
52+
53+
```bash
54+
yarn test
55+
```
56+
57+
## Additional Development Information
58+
59+
### Code Style
60+
61+
The project uses ESLint:
62+
63+
- Run `yarn lint` to check and fix linting issues.
64+
65+
### GraphQL
66+
67+
The project uses Apollo Client for GraphQL:
68+
69+
- Queries, mutations, and fragments are defined in correlated folders af (e.g., `*.ts` or `*.graphql`).
70+
- Use `yarn gql-gen` to generate TypeScript types for queries/mutations.
71+
- Only access properties defined in generated types or `src/api/schema.graphql`.
72+
73+
### Project Structure
74+
75+
- `src/`: Source code
76+
- `src/api/`: GraphQL queries, mutations, Apollo Client setup, and API-related files.
77+
- `src/common/`: Utility TypeScript files (types, interfaces, Yup validation schemas).
78+
- `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components).
79+
- `src/hooks/`: Custom React hooks (TypeScript).
80+
- `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders.
81+
- `src/server/`: Razzle server configuration files.
82+
- `src/theme/`: MUI theme configuration files.
83+
84+
### Coding Standards
85+
86+
- Use camelCase for variables, functions, and methods; ensure names are descriptive.
887
- Use PascalCase for React components, classes, and enums.
988
- Use kebab-case for new folders and files.
10-
- Use single quotes for strings.
11-
- Use 2 spaces for indentation.
12-
- Prefer arrow functions for callbacks.
13-
- Use async/await for GraphQL queries and mutations.
14-
- Use const for constants, let for reassignable variables.
15-
- Use destructuring for objects and arrays.
16-
- Use template literals for dynamic strings.
17-
- Follow SOLID principles for modular, reusable, and maintainable code.
18-
- Avoid code duplication, deeply nested statements, and hard-coded values (e.g., file paths, usernames).
19-
- Use constants or enums instead of magic numbers/strings for readability and memory efficiency.
20-
21-
## Project Preferences
22-
23-
- Use React with functional components and hooks.
24-
- Use Material-UI (MUI) v5 for UI components and styling:
25-
- Use the `sx` prop as the primary styling method.
26-
- Avoid `useStyles` or `makeStyles` (MUI v4 patterns).
27-
- Reference `src/theme` for custom MUI theme configurations in `sx` (e.g., `sx={{ color: theme.palette.primary.main }}`).
28-
- Use Apollo Client for GraphQL:
29-
- Write type-safe queries and mutations with generated TypeScript types.
30-
- Store queries, mutations, and fragments in `src/api`.
31-
- Use Yarn for package management:
32-
- Run `yarn add` for dependencies, checking for vulnerabilities with Snyk.
33-
- Use `yarn start`, `yarn build`, and `yarn test` for Razzle scripts.
34-
- Custom build process with Razzle:
35-
- Configure Razzle in `razzle.config.js` for build settings.
36-
- Optimize for production with code splitting and server-side rendering (SSR).
37-
- Use `src/server` for Razzle server configurations.
38-
- Use TypeScript for all code:
39-
- Enforce strict mode.
40-
- Define interfaces and types in `src/common`.
41-
- Follow folder structure:
42-
- `src/api`: GraphQL queries, mutations, Apollo Client setup, and API-related files.
43-
- `src/common`: Utility TypeScript files (types, interfaces, general-use TS).
44-
- `src/components`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders.
45-
- `src/hooks`: Custom React hooks (TypeScript).
46-
- `src/scenes`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders.
47-
- `src/server`: Razzle server configuration files.
48-
- `src/theme`: MUI theme configuration files.
49-
50-
## Version Control
51-
52-
- Create branches with format: `type/MondayTicketID-description` (e.g., `enhancement/1234-new-profile-page`).
53-
- Write commit messages:
54-
- First line: `[TicketID] - [Short Title] - Imperative verb` (e.g., `0654 - IRP - Remove/move Impact Report Date`).
55-
- Optional body: Briefly explain why the change is needed or the problem addressed.
56-
- Create PRs for single, specific changes (one user story per PR unless deployable in isolation):
57-
- Link the Monday ticket in the PR description.
58-
- Break changes into bite-sized, logical commits for easier review and potential reversion.
59-
- Demo functionality to reviewers when needed.
60-
61-
## Security Practices
62-
63-
- Sanitize all user inputs to prevent XSS.
64-
- Use Apollo Client’s error handling for GraphQL responses in `src/api`.
65-
- Implement role-based access control (RBAC) via GraphQL context.
66-
- Configure secure cookies (`HttpOnly`, `Secure`, `SameSite=Strict`) in `src/server`.
67-
- Enforce Content Security Policy (CSP) in Razzle’s server configuration in `src/server`.
68-
- Validate data from external sources (APIs, databases) for expected formats.
69-
- Check new dependencies with Snyk for vulnerabilities before adding via Yarn.
70-
71-
## Form Development
72-
73-
- Use custom form components built with Final Form and react-final-form in `src/components/form`:
74-
- Use components like `Form`, `Field`, and custom inputs for consistent behavior.
75-
- Define TypeScript interfaces in `src/common` for form data and props.
76-
- Use `react-final-form` hooks (e.g., `useForm`, `useField`) for form state management.
77-
- Integrate MUI v5 components (`TextField`, `Select`, etc.) within form components:
78-
- Apply `sx` prop, referencing `src/theme` for consistency.
79-
- Use `yup` for validation:
80-
- Store schemas in `src/common/validation`.
81-
- Ensure TypeScript compatibility.
82-
- Integrate with react-final-form for user-friendly error messages.
83-
84-
## General Guidelines
85-
86-
- Write clear, concise code with single-responsibility modules.
87-
- Add JSDoc comments for public functions and components (optional: include purpose and description).
88-
- Optimize performance:
89-
- Use `React.memo`, `useCallback`, `useMemo` for React components.
90-
- Minimize loop iterations, redundant operations, and memory allocations.
91-
- Process data in chunks for large datasets.
92-
- Optimize GraphQL queries in `src/api` for efficient data retrieval.
93-
- Avoid changing code outside the task scope; create separate PRs for refactors.
94-
- Keep responses friendly, informal, and under 1000 characters.
95-
- Reference `styleguide.md` in `docs/` for additional styling rules.
96-
97-
## Testing
98-
99-
- Use Jest and React Testing Library for unit tests:
100-
- Place tests in `__tests__` folders in `src/components` and `src/scenes`.
101-
- Mock GraphQL queries with `@apollo/client/testing` for `src/api` files.
102-
- Mock react-final-form for form tests using `react-final-form` testing utilities.
103-
- Write descriptive tests focusing on user interactions.
104-
- Ensure functional quality:
105-
- Unit testing in development.
106-
- Regression and smoke testing in production or development as needed.
107-
- Validate all acceptance criteria in PR reviews.
108-
109-
## Additional Notes
110-
111-
- Reference GraphQL schemas in `src/api/schema.graphql`.
112-
- Avoid external resource references unless specified.
113-
- If instructions seem ignored, remind Copilot to check this file.- Use tagged comments (`// cp tag`) to mark code for reference:
89+
- Use single quotes for strings, 2 spaces for indentation.
90+
- Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations.
91+
- Use `const` for constants, minimize `let` usage (e.g., except in try/catch).
92+
- Use destructuring for objects/arrays, template literals for strings.
93+
- Follow SOLID principles for modular, reusable, maintainable code.
94+
- Avoid code duplication, deeply nested statements, hard-coded values.
95+
- Use constants/enums instead of magic numbers/strings.
96+
- Avoid mutations (non-GraphQL):
97+
- Prefer `const` over `let`.
98+
- Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects.
99+
- Use strict TypeScript:
100+
- Define all object shapes in `src/common` or generated GraphQL types in `src/api`.
101+
- Use optional chaining (`?.`) or type guards for safe property access.
102+
103+
### React Guidelines
104+
105+
- Use `key` attribute only for dynamic lists (e.g., `Array.map`).
106+
- Minimize `useEffect`; prefer other hooks/patterns.
107+
- Avoid `event.preventDefault()` unless necessary.
108+
- For new small components:
109+
- Pass most props to wrapping components for reusability.
110+
- Match designs or comment stop-gap versions.
111+
- Avoid unnecessary HTML elements for styling (e.g., `<MyCard sx={{ m: 1 }} />` instead of `<Box sx={{ m: 1 }}><MyCard /></Box>`).
112+
- Use optional chaining (`?.`) or type guards for object properties.
113+
114+
### Form Development
115+
116+
- Use custom form components with Final Form and react-final-form in `src/components/form`:
117+
118+
### CSS Guidelines
119+
120+
- Use `sx` prop for styling; avoid StyledComponents or `makeStyles`.
121+
- Reference `src/theme` for spacing (1-8), palette colors, typography variants.
122+
- Comment if using magic numbers/colors/fonts.
123+
- Ensure styles are minimal, necessary, and responsive across screen sizes.
124+
- Use `// ai edge-case` for justified deviations (e.g., non-theme colors).
125+
- **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability.
126+
- Example (Correct):
127+
```tsx
128+
// ai example Parent-owned centering
129+
// src/components/CenteredCard.tsx
130+
import { Box, Card } from '@mui/material';
131+
export const CenteredCard = () => (
132+
<Box sx={{ display: 'flex', justifyContent: 'center', p: 2 }}>
133+
<Card sx={{ width: 300 }}>Content</Card>
134+
</Box>
135+
);
136+
```
137+
_Why_: Parent `<Box>` controls centering, keeping `<Card>` reusable.
138+
- Example (Incorrect):
139+
```tsx
140+
// ai anti-pattern Child-owned centering
141+
// src/components/CenteredCard.tsx
142+
import { Box, Card } from '@mui/material';
143+
export const CenteredCard = () => (
144+
<Box sx={{ p: 2 }}>
145+
<Card sx={{ margin: 'auto', width: 300 }}>Content</Card>
146+
</Box>
147+
);
148+
```
149+
_Why_: `<Card>` assumes parent’s layout, reducing reusability.
150+
- **Order control styles before appearance styles**: In `sx` prop declarations, list control styles (e.g., `display`, `padding`, `width`) before appearance styles (e.g., `color`, `background`, `fontSize`) for readability.
151+
- Example (Correct):
152+
```tsx
153+
// ai example Ordered sx styles
154+
// src/components/StyledBox.tsx
155+
import { Box } from '@mui/material';
156+
export const StyledBox = () => (
157+
<Box
158+
sx={{
159+
display: 'flex',
160+
justifyContent: 'center',
161+
padding: 2,
162+
width: '100%',
163+
backgroundColor: 'primary.main',
164+
color: 'white',
165+
borderRadius: 1,
166+
fontSize: 16,
167+
}}
168+
>
169+
Content
170+
</Box>
171+
);
172+
```
173+
_Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability.
174+
- Example (Incorrect):
175+
```tsx
176+
// ai anti-pattern Disordered sx styles
177+
// src/components/StyledBox.tsx
178+
import { Box } from '@mui/material';
179+
export const StyledBox = () => (
180+
<Box
181+
sx={{
182+
color: 'white',
183+
display: 'flex',
184+
backgroundColor: 'primary.main',
185+
padding: 2,
186+
fontSize: 16,
187+
justifyContent: 'center',
188+
borderRadius: 1,
189+
width: '100%',
190+
}}
191+
>
192+
Content
193+
</Box>
194+
);
195+
```
196+
_Why_: Mixed style order reduces readability and maintainability.
197+
198+
### API Guidelines
199+
200+
- Avoid over-simplification in queries; consider second-order consequences.
201+
- Ensure `src/api` components have consistent interfaces matching designs.
202+
- Only access properties in generated GraphQL types; use type guards for dynamic data.
203+
204+
### Common Errors to Avoid
205+
206+
- **Accessing Non-Existent Properties**:
207+
- Never assume properties exist without type verification.
208+
- Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`.
209+
- Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`).
210+
- Example (Correct):
211+
```tsx
212+
// ai type-safety Safe property access with optional chaining
213+
interface User {
214+
name?: string;
215+
}
216+
const user: User = {};
217+
const name = user?.name ?? 'Unknown';
218+
```
219+
_Why_: Prevents runtime errors by checking property existence.
220+
- Example (Incorrect):
221+
```tsx
222+
// ai anti-pattern Assumes non-existent property
223+
const user = {};
224+
const name = user.name; // Error: Property 'name' does not exist
225+
```
226+
_Why_: Causes runtime errors due to unverified property access.
227+
228+
### Type Checking
229+
230+
Run `yarn type-check` to check for TypeScript errors without compiling the code.
231+
232+
### Tagged Comments
233+
234+
- Use `// ai tag` to mark code for reference:
114235
- `example`: Best practice or model code.
115236
- `edge-case`: Necessary deviation from standards.
116237
- `best-practice`: Adherence to coding standards.
@@ -121,5 +242,6 @@ This project is a web application built with React 18, Material-UI (MUI), and Gr
121242
- `security`: Security-critical code.
122243
- `test`: Exemplary test case.
123244
- `design-alignment`: Matches or deviates from design specs.
124-
- After the tag, optionally add notes to explain the context (e.g., `// cp example Reusable form with theme-based styling`).
125-
- Search for tags with `git grep "cp "` to collect examples for this document.
245+
- `type-safety`: Safe property access.
246+
- Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`).
247+
- Search tags with `git grep "ai "` to collect examples.

0 commit comments

Comments
 (0)