Development Setup Skill

This skill guides you through setting up the complete development environment for the To-Do List WebApp project.

Prerequisites

• •Node.js >= 20.19.0
• •npm >= 9.0.0
• •Docker Desktop installed and running
• •Git installed

Setup Steps

1. Verify Prerequisites

First, verify that all required tools are installed:

node --version
npm --version
docker --version
git --version

2. Clone Repository (if needed)

If starting fresh:

git clone <repository-url>
cd To-DoList_WebApp

3. Install Dependencies

Install all dependencies for the monorepo (root, backend, and frontend):

npm run install:all

This command will:

• •Install root dependencies
• •Install backend dependencies
• •Install frontend dependencies

4. Set Up Environment Variables

Backend Environment Variables

Create backend/.env from the example:

cp backend/.env.example backend/.env

Edit backend/.env and configure:

• •MONGODB_URI - MongoDB connection string (default: mongodb://mongodb:27017/todolist)
• •JWT_SECRET - Secret key for JWT tokens (generate a secure random string)
• •PORT - Backend port (default: 5000)
• •FRONTEND_URL - Frontend URL for CORS (default: http://localhost:5173)

Frontend Environment Variables

Create frontend/.env from the example:

cp frontend/.env.example frontend/.env

Edit frontend/.env and configure:

• •VITE_API_URL - Backend API URL (default: http://localhost:5000/api)

5. Start Development Environment

Start all services using Docker Compose:

npm run dev

This will start:

• •MongoDB on port 27017
• •Backend on port 5000
• •Frontend on port 5173

6. Verify Setup

Run the verification script to check that all services are running:

node .agent/skills/dev-setup/scripts/verify-setup.js

Or manually verify:

1. •Frontend: Open http://localhost:5173 in your browser
2. •Backend API: Check http://localhost:5000/api/health
3. •MongoDB: Check Docker containers with docker ps

7. Alternative: Run Services Separately

If you prefer not to use Docker, you can run services separately:

# Terminal 1 - Start MongoDB (requires local MongoDB installation)
mongod

# Terminal 2 - Start Backend
npm run dev:backend

# Terminal 3 - Start Frontend
npm run dev:frontend

Common Issues and Solutions

Port Already in Use

If ports 5000 or 5173 are already in use:

1. •Stop the conflicting process
2. •Or change the port in the respective .env file

Docker Not Starting

1. •Ensure Docker Desktop is running
2. •Check Docker logs: docker-compose logs
3. •Restart Docker Desktop
4. •Try rebuilding: docker-compose up --build

Dependencies Installation Fails

1. •Clear npm cache: npm cache clean --force
2. •Delete node_modules and lock files: npm run clean:modules
3. •Reinstall: npm run install:all

MongoDB Connection Issues

1. •Check Docker container status: docker ps
2. •Check MongoDB logs: docker-compose logs mongodb
3. •Verify MONGODB_URI in backend/.env
4. •Restart containers: npm run restart

Next Steps

After setup is complete:

1. •Run Tests: Use the run-tests skill to verify everything works
2. •Check Code Quality: Use the lint-fix skill to ensure code quality
3. •Start Development: Begin working on features using add-api-endpoint or add-react-component skills

Useful Commands

# View all running containers
docker ps

# View logs from all services
npm run logs

# View logs from specific service
npm run logs:backend
npm run logs:frontend

# Stop all services
npm run stop

# Restart all services
npm run restart

# Clean everything (including volumes)
npm run clean

Development Workflow

1. •Make changes to code
2. •Backend auto-reloads on file changes (nodemon)
3. •Frontend auto-reloads on file changes (Vite HMR)
4. •MongoDB data persists in Docker volume

Testing the Setup

Create a test todo item to verify the full stack is working:

1. •Open http://localhost:5173
2. •Register a new account
3. •Create a new todo item
4. •Verify it appears in the list
5. •Check backend logs to see API requests
6. •Check MongoDB using: docker exec -it <mongodb-container-id> mongosh