contacts-manager

Web application to manage your personal contacts with basic CRUD functionality with additional features like grouping and others

Introduction

This application uses Laravel 12 + Laravel Breeze (Vue.js 3 + Inertia).This guide shows the necessary steps to set up the project on your local environment, GitHub Codespace and, explains essential dependencies and basic usage. Check the User Manual

---

Table of Contents

1. System Requirements
2. Project Setup
   • Clone the Repository
   • Install Dependencies
3. Environment Configuration
   • Create .env File
   • Database Configuration
4. Development Server
   • Run Laravel Server
   • Run Vue.js with Inertia
   • Use in GitHub Codespace
5. Building for Production
6. Testing
7. Contributing
8. License

---

System Requirements

To run this project locally, make sure you have the following software installed:

• PHP >= 8.2 except 8.3
• Composer >= 2.x
• Node.js >= 20.x
• npm >= 8.x
• MySQL >= 5.7

---

Project Setup

Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/JimmyKurui/contacts-manager.git
cd contacts-manager

Install Dependencies

1. Backend (Laravel)

Install the PHP dependencies using Composer:

composer update && composer install

Note: If any extensions or composer require commands are required, run them, then re-run the above command.

2. Frontend (Vue.js & Inertia.js)

Install the frontend dependencies using npm or yarn:

npm install
# or
yarn install

---

Environment Configuration

Create .env File

Copy the example .env.example file to create your own .env configuration file:

cp .env.example .env

Make sure to update your .env file with the correct environment settings.

Database Configuration

Ensure your MySQL database configuration is set up properly in the .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_username
DB_PASSWORD=your_database_password

---

Development Server

Run Laravel Server

To run the Laravel backend:

php artisan serve

This will start the Laravel development server at http://127.0.0.1:8000.

Run Vue.js with Inertia

To run the Vue.js frontend with Inertia.js:

npm run dev
# or
yarn dev

This will start the development server for Vue.js at http://localhost:5173.

Use in GitHub Codespace

If you are using a GitHub Codespace for development, set up your dev container using .devcontainer settings. Your environment must have these settings:

• Vite frontend server port is public
• Your APP_URL points to your codespace URL
• Laravel proxies: trust proxies in the middleware for your Vite server

---

Building for Production

For production environments, you need to build the frontend assets. Run the following command to build the Vue.js assets:

npm run build
# or
yarn build

This will compile and minify the assets for production.

To deploy the Laravel application, make sure to set the correct environment settings, clear the cache, and migrate the database:

php artisan config:cache
php artisan route:cache
php artisan migrate

---

Testing

Run your custom tests with Pest for the backend:

php artisan test

For frontend testing, you can use Jest or any testing library you’ve set up with Vue.js. If using Jest, run:

npm run test
# or
yarn test

---

Contributing

We welcome contributions to the project! Please fork the repository, create a new branch, and submit a pull request with your changes.

1. Fork the repository
2. Create a feature branch (git checkout -b feature-name)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin feature-name)
5. Submit a pull request

---