docs: improve README with setup instructions and contribution guide - #133
docs: improve README with setup instructions and contribution guide#133anktiwari053 wants to merge 3 commits into
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request overhauls the project documentation in README.md and updates the package-lock.json to version 3. The review feedback identifies several critical inaccuracies in the new documentation: setup instructions incorrectly suggest running backend commands from a subdirectory, the environment variable file path and required keys are incomplete, and the documented API endpoints lack the mandatory /api/v1 prefix found in the source code. Suggestions were also provided to fix broken internal links in the Table of Contents and to include cross-platform commands for legacy OpenSSL support.
| cd your-repo | ||
| 🖥 Backend Setup | ||
| Step 1: Move to backend | ||
| cd backend |
There was a problem hiding this comment.
The root package.json contains the backend dependencies and scripts (like dev). Navigating into the backend/ directory before running npm install or npm run dev will cause these commands to fail, as there is no package.json in that subdirectory. You should stay in the root directory for backend operations.
| cd backend | |
| # Stay in the root directory |
| Create .env file: | ||
|
|
||
| **Essential Variables** | ||
| PORT= | ||
| DB_URI = | ||
| STRIPE_API_KEY= | ||
| STRIPE_SECRET_KEY= | ||
| JWT_SECRET= | ||
| JWT_EXPIRE= | ||
| COOKIE_EXPIRE= | ||
| SMPT_SERVICE = | ||
| SMPT_MAIL= | ||
| SMPT_PASSWORD= | ||
| SMPT_HOST= | ||
| SMPT_PORT= | ||
| CLOUDINARY_NAME | ||
| CLOUDINARY_API_KEY | ||
| CLOUDINARY_API_SECRET | ||
| _fill each filed with your info respectively_ | ||
| PORT=5000 | ||
| MONGO_URI=your_mongodb_connection_string | ||
| JWT_SECRET=your_jwt_secret |
There was a problem hiding this comment.
There are two critical issues here:
- File Path/Name: The application code (see
backend/server.jsline 14) specifically expects the configuration file atbackend/config/config.env. Creating a.envfile in thebackend/root will result in the environment variables not being loaded. - Missing Variables: Essential variables for Cloudinary, Stripe, and Mail services (which are used in the code) are missing from this example. The application will fail to initialize or crash without them.
| Create .env file: | |
| **Essential Variables** | |
| PORT= | |
| DB_URI = | |
| STRIPE_API_KEY= | |
| STRIPE_SECRET_KEY= | |
| JWT_SECRET= | |
| JWT_EXPIRE= | |
| COOKIE_EXPIRE= | |
| SMPT_SERVICE = | |
| SMPT_MAIL= | |
| SMPT_PASSWORD= | |
| SMPT_HOST= | |
| SMPT_PORT= | |
| CLOUDINARY_NAME | |
| CLOUDINARY_API_KEY | |
| CLOUDINARY_API_SECRET | |
| _fill each filed with your info respectively_ | |
| PORT=5000 | |
| MONGO_URI=your_mongodb_connection_string | |
| JWT_SECRET=your_jwt_secret | |
| Create `config.env` inside `backend/config/` directory: | |
| PORT=5000 | |
| DB_URI=your_mongodb_connection_string | |
| JWT_SECRET=your_jwt_secret | |
| JWT_EXPIRE=5d | |
| COOKIE_EXPIRE=5 | |
| CLOUDINARY_NAME=your_cloudinary_name | |
| CLOUDINARY_API_KEY=your_cloudinary_api_key | |
| CLOUDINARY_API_SECRET=your_cloudinary_api_secret | |
| STRIPE_API_KEY=your_stripe_api_key | |
| STRIPE_SECRET_KEY=your_stripe_secret_key |
| npm run dev | ||
| 🎨 Frontend Setup | ||
| Step 1: Move to frontend | ||
| cd ../frontend |
There was a problem hiding this comment.
If the user stays in the root directory for the backend setup (as recommended), they should navigate to the frontend/ directory using cd frontend instead of cd ../frontend.
| cd ../frontend | |
| cd frontend |
| POST /api/auth/register | ||
| POST /api/auth/login | ||
| Product APIs | ||
| GET /api/products | ||
| POST /api/products (admin) | ||
| Cart APIs | ||
| POST /api/cart | ||
| GET /api/cart |
There was a problem hiding this comment.
The API routes listed here do not match the implementation in backend/app.js (lines 26-29), which uses the /api/v1 prefix for all routes. Additionally, the sub-paths (like /auth) should be verified against the actual router definitions to ensure accuracy for contributors.
| POST /api/auth/register | |
| POST /api/auth/login | |
| Product APIs | |
| GET /api/products | |
| POST /api/products (admin) | |
| Cart APIs | |
| POST /api/cart | |
| GET /api/cart | |
| POST /api/v1/register | |
| POST /api/v1/login | |
| GET /api/v1/products | |
| POST /api/v1/admin/products | |
| POST /api/v1/order/new | |
| GET /api/v1/orders/me |
| About Project | ||
| Features | ||
| Tech Stack | ||
| Project Structure | ||
| Prerequisites | ||
| Installation | ||
| Environment Setup | ||
| Backend Setup | ||
| Frontend Setup | ||
| Running Project | ||
| API Overview | ||
| Contribution Guide | ||
| Coding Standards | ||
| Troubleshooting | ||
| Future Improvements | ||
| License | ||
| Support |
There was a problem hiding this comment.
The Table of Contents contains several items that do not match the actual section headers in the document (e.g., "Running Project", "Troubleshooting", "License", "Support"). Additionally, it should use Markdown internal links to allow users to navigate the document easily.
| About Project | |
| Features | |
| Tech Stack | |
| Project Structure | |
| Prerequisites | |
| Installation | |
| Environment Setup | |
| Backend Setup | |
| Frontend Setup | |
| Running Project | |
| API Overview | |
| Contribution Guide | |
| Coding Standards | |
| Troubleshooting | |
| Future Improvements | |
| License | |
| Support | |
| - [About Project](#-about-project) | |
| - [Features](#-features) | |
| - [Tech Stack](#-tech-stack) | |
| - [Project Structure](#-project-structure) | |
| - [Prerequisites](#-prerequisites) | |
| - [Installation Guide](#-installation-guide) | |
| - [Backend Setup](#-backend-setup) | |
| - [Frontend Setup](#-frontend-setup) | |
| - [Application URLs](#-application-urls) | |
| - [API Overview](#-api-overview) | |
| - [Environment Variables](#-environment-variables) | |
| - [Contribution Guide](#-contribution-guide) | |
| - [Coding Standards](#-coding-standards) | |
| - [Testing](#-testing) | |
| - [Common Issues](#-common-issues) | |
| - [Future Improvements](#-future-improvements) |
|
|
||
| Fix: | ||
|
|
||
| set NODE_OPTIONS=--openssl-legacy-provider |
There was a problem hiding this comment.
The set command is specific to Windows Command Prompt. Providing instructions for Unix-based systems (Linux/macOS) using export ensures the guide is helpful for all developers regardless of their operating system.
| set NODE_OPTIONS=--openssl-legacy-provider | |
| # For Windows (CMD) | |
| set NODE_OPTIONS=--openssl-legacy-provider | |
| # For Unix (Linux/macOS) | |
| export NODE_OPTIONS=--openssl-legacy-provider |
1 participant
📘 Documentation Update: README Improvements #120
📌 Summary
This PR improves the project README to make it more beginner-friendly and contributor-friendly. It provides clear setup instructions and better structure for understanding the project.
✨ Changes Made
🚀 Why this change is needed
Previously, new contributors faced difficulty in setting up the project. This update makes onboarding easier and reduces confusion during local setup.
📌 Type of change
✅ Result
The README is now more structured, professional, and aligned with open-source best practices, making it easier for contributors to start working on the project.
🔥 Note
No functional code changes were made. This PR only improves documentation clarity and developer experience.