Monorepo Project

A full-stack monorepo with backend (Express.js) and frontend (Vue 3 + Vite + Element Plus) applications.

Project Overview

This monorepo contains two main applications:

• Backend: RESTful API built with Express.js
• Frontend: Web UI built with Vue 3, Vite, and Element Plus UI library

Both applications are organized in a single repository with shared tooling and npm workspaces configuration for streamlined development.

Prerequisites

Before you begin, ensure you have installed:

• Node.js (v18.x or higher)
• npm (v9.x or higher) or yarn (v3.x or higher)
• MySQL (v5.7 or higher) - optional, if you plan to use database features

Project Structure

.
├── backend/                 # Express.js backend API
│   ├── src/
│   │   └── index.js        # Main server file
│   ├── dist/               # Built files (generated)
│   ├── tests/              # CI-ready test directory
│   ├── package.json
│   ├── .env.example
│   └── README.md
├── frontend/               # Vue 3 + Vite frontend
│   ├── src/
│   │   ├── main.js         # Entry point
│   │   └── App.vue         # Root component
│   ├── dist/               # Built files (generated)
│   ├── tests/              # CI-ready test directory
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   ├── .env.example
│   └── README.md
├── package.json            # Root workspace configuration
├── .editorconfig
├── .eslintrc.json
├── .prettierrc
├── .prettierignore
├── .gitignore
└── README.md

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd monorepo

2. Install Dependencies

Using npm:

npm install

Using yarn:

yarn install

3. Environment Configuration

Backend Environment

Copy the example environment file and update with your settings:

cp backend/.env.example backend/.env

Key environment variables:

• PORT - Server port (default: 3000)
• NODE_ENV - Environment mode (development/production)
• DB_HOST - MySQL host
• DB_PORT - MySQL port
• DB_USER - MySQL username
• DB_PASSWORD - MySQL password
• DB_NAME - Database name
• JWT_SECRET - JWT signing secret
• CORS_ORIGIN - CORS allowed origin (frontend URL)

Frontend Environment

Copy the example environment file and update with your settings:

cp frontend/.env.example frontend/.env.local

Key environment variables:

• VITE_API_BASE_URL - Backend API base URL (default: http://localhost:3000)

4. Start Development Servers

Option A: Run Both Applications Concurrently

npm run dev

This will start:

• Backend server on http://localhost:3000
• Frontend application on http://localhost:5173

Option B: Run Individual Applications

Backend only:

npm run dev --workspace=backend

Frontend only:

npm run dev --workspace=frontend

5. Verify Installation

• Open http://localhost:5173 in your browser
• The landing page should display
• Click "Check Backend Health" to verify backend connectivity

Available Commands

Root Workspace Commands

# Start development servers for both backend and frontend
npm run dev

# Build both applications
npm run build

# Lint all code
npm run lint

# Format code with Prettier
npm run format

Backend-Specific Commands

# Start development server with file watching
npm run dev --workspace=backend

# Build backend
npm run build --workspace=backend

# Start production server
npm run start --workspace=backend

# Lint backend code
npm run lint --workspace=backend

Frontend-Specific Commands

# Start development server
npm run dev --workspace=frontend

# Build for production
npm run build --workspace=frontend

# Preview production build
npm run preview --workspace=frontend

# Lint frontend code
npm run lint --workspace=frontend

Development Workflow

Local Development

1. Start both development servers:

   npm run dev

2. The backend server will be available at http://localhost:3000

3. The frontend application will be available at http://localhost:5173

4. Make changes to code - both applications support hot module reloading

Code Quality

Before committing code, ensure it passes linting and formatting checks:

# Check for linting errors
npm run lint

# Format code
npm run format

API Endpoints

Health Check

GET /api/health

Returns:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "message": "Backend is running"
}

Welcome Endpoint

GET /api

Returns:

{
  "message": "Welcome to the API",
  "version": "1.0.0"
}

Workspace Configuration

This project uses npm/yarn workspaces for efficient dependency management. Both backend and frontend are configured as workspaces in the root package.json.

Benefits

• Shared development tools (ESLint, Prettier)
• Unified dependency management
• Convenient workspace scripts
• Simplified development workflow

Using Workspaces

Run commands in specific workspace:

npm run <script> --workspace=<workspace-name>

Example:

npm run dev --workspace=backend
npm run build --workspace=frontend

Shared Tooling

ESLint

Configuration files:

• Root: .eslintrc.json (base configuration)
• Backend: backend/.eslintrc.json (Node.js specific)
• Frontend: frontend/.eslintrc.json (Vue 3 specific)

Prettier

Configuration files:

• Root: .prettierrc (shared formatting rules)
• Root: .prettierignore (ignore patterns)

Editor Config

• Root: .editorconfig (editor settings across IDEs)

CI/CD Ready Structure

Both applications have tests/ directories prepared for future CI/CD integration:

backend/tests/        # CI-ready for backend tests
frontend/tests/       # CI-ready for frontend tests

Troubleshooting

Port Already in Use

If you get a "port already in use" error:

Backend (port 3000):

# Change PORT in backend/.env
PORT=3001 npm run dev --workspace=backend

Frontend (port 5173):

# Vite will automatically use the next available port
npm run dev --workspace=frontend

Module Not Found

If you encounter "module not found" errors:

1. Ensure all dependencies are installed:

   npm install

2. Clear node_modules and reinstall:

   rm -rf node_modules backend/node_modules frontend/node_modules
   npm install

CORS Issues

If frontend cannot reach backend, ensure:

1. Backend is running on the correct port
2. CORS_ORIGIN in backend/.env matches your frontend URL
3. VITE_API_BASE_URL in frontend/.env.local matches your backend URL

Contributing

1. Create a feature branch
2. Make your changes
3. Run linting and formatting:

   npm run lint
   npm run format

4. Submit a pull request

License

This project is proprietary.

Support

For issues or questions, please contact the development team.