Skip to content

Commit 475b584

Browse files
Copilotbenjuntilla
Copilot
and
benjuntilla
committed
Create comprehensive .github/copilot-instructions.md with validated commands and timings
Co-authored-by: benjuntilla <46634820+benjuntilla@users.noreply.github.com>
1 parent d097c83 commit 475b584

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# ASU SoDA Website
2+
3+
**ALWAYS follow these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
4+
5+
## Project Overview
6+
7+
The ASU Software Developers Association (SoDA) website is a React + TypeScript single-page application built with Vite. It showcases the organization, team members, events, and provides information about programs like mentorship and distinguished member points system.
8+
9+
## Working Effectively
10+
11+
### Prerequisites and Setup
12+
- **Node.js Version**: v20.19.4 (verified working)
13+
- **Package Manager**: ALWAYS use `pnpm` - npm has compatibility issues with this project
14+
- **Install pnpm**: `npm install -g pnpm`
15+
16+
### Bootstrap and Build Process
17+
1. **Install Dependencies**:
18+
```bash
19+
pnpm install
20+
```
21+
- Takes approximately 20 seconds
22+
- Downloads ~554 packages
23+
- May show warnings about build scripts - these are safe to ignore
24+
25+
2. **Build the Project**:
26+
```bash
27+
pnpm run build
28+
```
29+
- **NEVER CANCEL**: Build takes 75+ seconds. Set timeout to 120+ minutes.
30+
- Runs TypeScript compilation (`tsc`) followed by Vite build
31+
- Generates optimized production build in `dist/` directory
32+
- Includes automatic image optimization which may skip some images if optimization would increase file size
33+
- Final bundle size is ~785KB with gzip compression to ~259KB
34+
35+
3. **Development Server**:
36+
```bash
37+
pnpm run dev
38+
```
39+
- Starts Vite dev server on `http://localhost:5173/`
40+
- Hot reload enabled - changes automatically refresh the page
41+
- Typically starts in ~500ms
42+
- Press Ctrl+C to stop
43+
44+
4. **Preview Production Build**:
45+
```bash
46+
pnpm run preview
47+
```
48+
- Serves the built application from `dist/` on `http://localhost:4173/`
49+
- Use this to test production builds locally
50+
51+
### Linting and Code Quality
52+
- **Current Issue**: ESLint configuration is incompatible with ESLint v9
53+
- **Lint Command**: `pnpm run lint` - **CURRENTLY FAILS** with error: "ESLint couldn't find an eslint.config.(js|mjs|cjs) file"
54+
- **Root Cause**: Project uses .eslintrc.cjs format but ESLint v9+ requires eslint.config.js format
55+
- **Workaround**: Manual code review or migrate ESLint config if linting is critical
56+
- **DO NOT** attempt to fix ESLint issues unless specifically asked - focus on functionality over linting
57+
58+
## Validation and Testing
59+
60+
### Manual Validation Requirements
61+
**ALWAYS manually validate changes by running through these scenarios after making code changes:**
62+
63+
1. **Homepage Functionality**:
64+
- Run `pnpm run dev`
65+
- Navigate to `http://localhost:5173/`
66+
- Verify all sections load: Hero, About, Sponsors, Team, History
67+
- Test navigation menu (mobile and desktop)
68+
- Verify statistics animation works
69+
70+
2. **Multi-page Navigation**:
71+
- Test all routes: `/`, `/apply`, `/leaderboard`, `/mentorship`, `/points`, `/distinguishedMembers`
72+
- Ensure React Router navigation works (no page reloads)
73+
- Verify each page renders without errors
74+
- Test browser back/forward navigation
75+
- Check that page titles update correctly
76+
77+
3. **Responsive Design**:
78+
- Test mobile and desktop layouts (viewport sizes: 320px, 768px, 1024px, 1920px)
79+
- Verify dropdown menus work on mobile (hamburger menu)
80+
- Check image loading and optimization
81+
- Test touch interactions on mobile devices
82+
83+
4. **Production Build Validation**:
84+
- Run `pnpm run build` and `pnpm run preview`
85+
- Test the same scenarios on `http://localhost:4173/`
86+
- Verify all assets load correctly in production mode
87+
- Check that statistics animation and interactive elements work
88+
- Confirm bundled CSS and JS load properly
89+
90+
### Build Validation
91+
- **Always run** `pnpm run build` before committing changes
92+
- **Build time expectation**: 75+ seconds - NEVER CANCEL
93+
- **Watch for**: TypeScript compilation errors, missing assets, bundle size warnings
94+
95+
## Project Structure and Key Files
96+
97+
### Repository Root
98+
```
99+
.
100+
├── README.md # Project documentation
101+
├── package.json # Dependencies and scripts (uses pnpm)
102+
├── pnpm-lock.yaml # Locked dependency versions
103+
├── vite.config.ts # Vite configuration
104+
├── tsconfig.json # TypeScript configuration
105+
├── .eslintrc.cjs # ESLint config (broken with v9)
106+
├── components.json # shadcn component configuration
107+
├── deploy.sh # Production deployment script
108+
├── src/ # Source code
109+
├── public/ # Static assets
110+
├── dist/ # Build output (generated)
111+
└── .github/workflows/ # CI/CD pipeline
112+
```
113+
114+
### Source Code Structure
115+
```
116+
src/
117+
├── main.tsx # Application entry point
118+
├── App.tsx # Main application component
119+
├── app.css # Global styles and TailwindCSS
120+
├── components/ # Reusable React components
121+
│ ├── Navigation/ # Navbar and menu components
122+
│ ├── Stats/ # Statistics display
123+
│ └── ui/ # shadcn UI components
124+
└── pages/ # Route components
125+
├── Home.tsx # Homepage
126+
├── PositionOpenings.tsx # Job applications page
127+
├── LeaderBoard.tsx # Member leaderboard
128+
├── Mentorship.tsx # Mentorship program info
129+
└── PointsSystem.tsx # Distinguished member program
130+
```
131+
132+
### Technology Stack
133+
- **Frontend**: React 19.1.0 with TypeScript
134+
- **Build Tool**: Vite 6.2.4
135+
- **Styling**: TailwindCSS v4 with shadcn components
136+
- **Router**: React Router Dom v7.4.1
137+
- **Icons**: Lucide React, React Icons
138+
- **Animations**: Framer Motion, custom CSS animations
139+
- **Image Optimization**: vite-plugin-image-optimizer
140+
141+
## Common Development Tasks
142+
143+
### Adding New Pages
144+
1. Create new component in `src/pages/`
145+
2. Add route in `src/App.tsx`
146+
3. Update navigation in `src/components/Navigation/Navbar.tsx`
147+
4. Test navigation and build
148+
149+
### Updating Team Information
150+
- Edit team data in `src/components/Team/TeamList.json`
151+
- Add new headshots to `public/headshots/`
152+
- Update statistics in `src/components/Stats/Statistics.tsx`
153+
154+
### Styling Changes
155+
- Global styles: `src/app.css`
156+
- Component styles: Use TailwindCSS classes
157+
- shadcn components: Configure in `components.json`
158+
159+
### Image Assets
160+
- Static images: `public/` directory
161+
- Optimized during build automatically
162+
- Use `.webp` format for best optimization
163+
164+
## CI/CD Pipeline
165+
166+
### GitHub Actions Workflow
167+
- **File**: `.github/workflows/cd.yml`
168+
- **Trigger**: Push to any branch
169+
- **Process**: SSH to production server, pull changes, build with pnpm, restart service
170+
- **Dependencies**: Requires pnpm installation on target server
171+
- **Build Time**: Plan for 75+ seconds in CI environment
172+
173+
### Production Deployment
174+
- Uses `pnpm install` and `pnpm run build`
175+
- Serves built files with systemctl service
176+
- Runs on port 3000 in production
177+
178+
## Troubleshooting
179+
180+
### Common Issues
181+
1. **npm commands fail**: Always use `pnpm` instead - npm has dependency resolution errors
182+
2. **ESLint errors**: Known issue with v9 migration - skip linting for now
183+
3. **Build timeouts**: Set timeouts to 120+ seconds, builds take 75+ seconds
184+
4. **Image optimization warnings**: Normal - optimizer skips images that would become larger
185+
5. **Console errors about blocked API calls**: Expected in development - external API calls are blocked in sandbox environment
186+
6. **Bundle size warnings**: Expected at 500KB+ - consider code splitting for larger features
187+
188+
### Performance Notes
189+
- Bundle size warning at 500KB+ is expected
190+
- Consider code splitting for larger features
191+
- Image optimization may skip files to maintain quality
192+
193+
## Important Notes for AI Agents
194+
195+
- **NEVER CANCEL** build commands - they take 75+ seconds normally
196+
- **ALWAYS use pnpm** - npm will fail with this project
197+
- **Manual validation is required** - no automated tests exist
198+
- **Test responsive design** - mobile navigation is critical
199+
- **Verify image loading** - optimization can affect asset paths
200+
- **Check production build** - dev and prod may behave differently

0 commit comments

Comments
 (0)