Skip to content

Commit 1725404

Browse files
DhananjayThombleDhananjayThomble
authored
Merge pull request #190 from DhananjayThomble/copilot/fix-189
Add comprehensive GitHub Copilot instructions for URL Shortener App
2 parents b79a0cf + 8738dfe commit 1725404

File tree

1 file changed

+231
-0
lines changed

1 file changed

+231
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# SnapURL: URL Shortener Application
2+
3+
SnapURL is a full-stack URL shortener web application with React.js frontend, Node.js/Express.js backend, MongoDB database, and a Chrome extension. The application provides URL shortening, user authentication, analytics tracking, and API documentation.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Install Dependencies
10+
- Install all dependencies (NEVER CANCEL: Takes 2-3 minutes):
11+
```bash
12+
npm install
13+
```
14+
This command automatically installs both frontend and backend dependencies via the root package.json script.
15+
16+
### Environment Setup
17+
- Create backend environment file:
18+
```bash
19+
cd backend
20+
```
21+
Create `.env` file with the following variables:
22+
```bash
23+
DB_URL=<your-mongodb-database-url>
24+
JWT_SECRET=<your-jwt-secret>
25+
SESSION_SECRET=<your-session-secret>
26+
PORT=4001
27+
BASE_URL=http://localhost:4001
28+
SHORT_URL_PREFIX=http://localhost:4001/u
29+
EMAIL_HOST=<your-email-host>
30+
EMAIL_PORT=<your-email-port>
31+
EMAIL_HOST_USER=<your-email-host-user>
32+
EMAIL_HOST_PASSWORD=<your-email-host-password>
33+
FRONTEND_URL=http://localhost:5173
34+
```
35+
36+
- Create frontend environment file:
37+
```bash
38+
cd frontend
39+
```
40+
Create `.env` file with:
41+
```bash
42+
VITE_API_ENDPOINT=http://localhost:4001
43+
```
44+
45+
### Build and Development
46+
- Build frontend (NEVER CANCEL: Takes 6-10 seconds, set timeout to 60+ seconds):
47+
```bash
48+
cd frontend && npm run build
49+
```
50+
51+
- Start development servers from root directory (NEVER CANCEL: Can take 30+ seconds to fully initialize both servers):
52+
```bash
53+
npm start
54+
```
55+
This starts both backend (port 4001) and frontend (port 5173) in parallel using npm-run-all.
56+
57+
- Start backend only (requires MongoDB connection):
58+
```bash
59+
cd backend && npm start
60+
```
61+
62+
- Start frontend only (starts in ~1 second):
63+
```bash
64+
cd frontend && npm start
65+
# or alternatively:
66+
cd frontend && npm run dev
67+
```
68+
69+
### Testing
70+
- Run backend tests (requires MongoDB connection):
71+
```bash
72+
cd backend && npm test
73+
```
74+
**Note**: Tests will fail without proper environment setup including MongoDB database.
75+
76+
- Backend tests use Mocha with Chai and test URL shortening functionality.
77+
78+
### Code Quality
79+
- Format backend code:
80+
```bash
81+
cd backend && npm run format
82+
```
83+
84+
- Format frontend code:
85+
```bash
86+
cd frontend && npm run format
87+
```
88+
89+
- Lint frontend code:
90+
```bash
91+
cd frontend && npm run lint
92+
```
93+
94+
- **CRITICAL**: Always run `npm run format` in both backend and frontend directories before committing or the CI (.github/workflows/autoFormatCode.yml) will fail.
95+
96+
## Validation
97+
98+
### Manual Testing Scenarios
99+
After making changes, ALWAYS test these complete end-to-end scenarios:
100+
101+
1. **URL Shortening Flow**:
102+
- Navigate to http://localhost:5173
103+
- Enter a valid URL in the shortening form
104+
- Verify a shortened URL is generated
105+
- Test that the shortened URL redirects to the original URL
106+
107+
2. **User Authentication Flow**:
108+
- Test user registration at /signup
109+
- Test user login at /login
110+
- Verify authenticated users can see their URL history
111+
- Test logout functionality
112+
113+
3. **API Documentation**:
114+
- Navigate to http://localhost:4001/doc
115+
- Verify Swagger UI loads and displays API endpoints
116+
117+
4. **Chrome Extension** (manual validation only):
118+
- Load the chrome-extension directory as an unpacked extension
119+
- Test URL shortening from the extension popup
120+
121+
### Build Validation
122+
- Always run formatting commands before committing changes
123+
- Frontend linting may have warnings - fix only new issues you introduce
124+
- Backend has no separate linting but uses Prettier formatting
125+
126+
## Tech Stack and Architecture
127+
128+
### Backend (Node.js/Express.js)
129+
- **Entry Point**: `backend/index.js`
130+
- **Database**: MongoDB with Mongoose ODM
131+
- **Authentication**: JWT with Passport.js
132+
- **API Documentation**: Swagger UI at `/doc` endpoint
133+
- **Rate Limiting**: Express-rate-limit configured
134+
- **Email**: Nodemailer for transactional emails
135+
- **Testing**: Mocha with Chai and Chai-HTTP
136+
137+
### Frontend (React.js)
138+
- **Build Tool**: Vite for fast development and building
139+
- **Routing**: React Router DOM
140+
- **Styling**: React Bootstrap + Material-UI components
141+
- **HTTP Client**: Axios for API calls
142+
- **State Management**: React Context API
143+
- **Notifications**: React Toastify
144+
145+
### Chrome Extension
146+
- **Manifest Version**: 3
147+
- **Files**: Located in `chrome-extension/` directory
148+
- **Permissions**: activeTab only
149+
- **No build process**: Ready to load as unpacked extension
150+
151+
### Database Schema
152+
- **Users**: Authentication and profile data
153+
- **URLs**: Original URLs, shortened URLs, analytics
154+
- **Tokens**: Password reset and email verification
155+
- **Feedback**: User feedback and reviews
156+
157+
## Common Tasks
158+
159+
### Frequently Used Commands
160+
```bash
161+
# Install all dependencies
162+
npm install
163+
164+
# Start development (both frontend and backend)
165+
npm start
166+
167+
# Format all code before committing
168+
cd backend && npm run format && cd ../frontend && npm run format
169+
170+
# Build frontend for production
171+
cd frontend && npm run build
172+
173+
# Run backend tests (requires MongoDB)
174+
cd backend && npm test
175+
```
176+
177+
### Repository Structure
178+
```
179+
├── backend/ # Node.js/Express API server
180+
│ ├── controllers/ # Route controllers
181+
│ ├── models/ # MongoDB models
182+
│ ├── routes/ # Express routes
183+
│ ├── test/ # Mocha tests
184+
│ └── swagger.yml # API documentation
185+
├── frontend/ # React.js web application
186+
│ ├── src/ # React components and pages
187+
│ └── build/ # Production build output
188+
├── chrome-extension/ # Browser extension files
189+
├── .github/workflows/ # GitHub Actions (auto-formatting)
190+
└── package.json # Root package orchestration
191+
```
192+
193+
### Key Files to Check After Changes
194+
- Always check `backend/swagger.yml` when modifying API endpoints
195+
- Review `frontend/src/components/` when updating UI components
196+
- Check `.env` files when environment variables change
197+
- Verify `package.json` scripts when adding new commands
198+
199+
### Common Issues and Solutions
200+
- **MongoDB Connection**: Ensure DB_URL is properly set in backend/.env
201+
- **CORS Issues**: Backend configured for development localhost origins
202+
- **Port Conflicts**: Backend defaults to 4001, frontend to 5173
203+
- **Build Failures**: Usually due to linting errors in frontend
204+
- **Test Failures**: Require proper environment variables and MongoDB connection
205+
206+
## Chrome Extension Development
207+
- **Location**: Extension files are in `chrome-extension/` directory
208+
- **Development**: No build process required - load directly as unpacked extension
209+
- **Manifest**: Version 3 with minimal permissions (activeTab only)
210+
- **Configuration**: Extension currently hardcoded to production API (https://dturl.live/api/url)
211+
- **Local Development**: Update `script.js` to point to http://localhost:4001/api/url for local testing
212+
- **Token**: Uses hardcoded JWT token in `script.js` - replace with local development token
213+
- **Files**:
214+
- `manifest.json` - Extension configuration
215+
- `extension.html` - Main popup interface
216+
- `script.js` - Core functionality (needs local API endpoint update)
217+
- `history.html` / `history.js` - URL history interface
218+
219+
## API Endpoints
220+
- **Base URL**: http://localhost:4001
221+
- **Documentation**: http://localhost:4001/doc (Swagger UI)
222+
- **Authentication**: JWT tokens required for most endpoints
223+
- **Rate Limiting**: 30 requests per 5 minutes per IP
224+
225+
## Development Best Practices
226+
- Always format code before committing (automatic CI formatting on main branch)
227+
- Test both authenticated and unauthenticated user flows
228+
- Verify email functionality works with test credentials
229+
- Check responsive design on different screen sizes
230+
- Validate URL shortening with various URL formats
231+
- Test Chrome extension integration when making API changes

0 commit comments

Comments
 (0)