Quickstart

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js 18+ - Download Node.js
pnpm 8.6+ - Fast package manager (install with npm install -g pnpm)
MySQL 8.0+ - Database server Download MySQL
Git - Version control system

Khedma Market uses pnpm as its package manager. While npm and yarn may work, pnpm is recommended for consistency with the project configuration.

Setup Guide

Follow these steps to get Khedma Market running on your local machine:

Clone the repository

Clone the Khedma Market repository from GitHub:

git clone https://github.com/elguarir/khedma-market.git
cd khedma-market

This downloads the complete source code to your local machine.

Install dependencies

Install all required packages using pnpm:

pnpm install

This command:

Installs all dependencies from package.json
Automatically runs prisma generate via the postinstall script
Creates the Prisma Client for database access

The installation may take 2-3 minutes depending on your internet connection.

Setup MySQL database

Create a new MySQL database for Khedma Market:

# Start MySQL (if not already running)
sudo systemctl start mysql  # Linux
# or
brew services start mysql   # macOS

# Connect to MySQL
mysql -u root -p

Make sure your MySQL server is running before proceeding to the next step.

Using the provided start-database.sh script

The repository includes a start-database.sh script that can help you set up a database quickly:

chmod +x start-database.sh
./start-database.sh

This script automates MySQL setup for local development.

Configure environment variables

Create a .env file in the root directory by copying the example file:

cp .env.example .env

Edit the .env file with your configuration:

.env

# Database Connection
DATABASE_URL="mysql://root:password@localhost:3306/khedma-market"

# NextAuth Configuration
# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET="your-super-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# OAuth Providers (Optional)
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Email Service (Optional)
RESEND_API_KEY="your-resend-api-key"
FROM_EMAIL="[email protected]"

Environment variable details

Required:

DATABASE_URL - MySQL connection string (update username/password if different)
NEXTAUTH_SECRET - Secret key for NextAuth.js session encryption
NEXTAUTH_URL - Base URL of your application

Optional (for full functionality):

GITHUB_CLIENT_ID & GITHUB_CLIENT_SECRET - Enable GitHub OAuth login
GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET - Enable Google OAuth login
RESEND_API_KEY - Email service for verification emails
FROM_EMAIL - Sender email address for transactional emails

Generate NEXTAUTH_SECRET

Generate a secure secret key using OpenSSL:

openssl rand -base64 32

Copy the output and paste it as your NEXTAUTH_SECRET value.

Setup OAuth providers (Optional)

To enable social login:GitHub OAuth:

Go to GitHub Developer Settings
Create a new OAuth App
Set Authorization callback URL to: http://localhost:3000/api/auth/callback/github
Copy Client ID and Client Secret to your .env

Google OAuth:

Go to Google Cloud Console
Create a new project and enable OAuth
Set Authorized redirect URI to: http://localhost:3000/api/auth/callback/google
Copy Client ID and Client Secret to your .env

Run database migrations

Apply all database migrations to create the schema:

pnpm db:migrate

This command:

Creates all tables in your MySQL database
Sets up relationships and indexes
Applies any pending migrations

You should see output indicating successful migration of tables like users, gigs, orders, conversations, etc.

Alternative: Push schema directly

For rapid development without migrations:

pnpm db:push

This pushes the Prisma schema directly to the database without creating migration files.

Seed the database (Optional)

Populate your database with sample data:

pnpm db:seed

This runs the seed script at prisma/seed.ts which can create:

Sample users with different roles
Example gigs and packages
Test categories and skills
Demo conversations and messages

Start the development server

Launch the Next.js development server:

pnpm dev

The application will start with:

Next.js server running on http://localhost:3000
Turbopack enabled for faster builds
Hot Module Replacement for instant updates

The first build may take 30-60 seconds. Subsequent builds will be much faster thanks to Turbopack.

Access the application

Open your browser and navigate to:

http://localhost:3000

You should see the Khedma Market homepage!

Key pages to explore

/ - Homepage with marketplace overview
/auth/sign-in - Login page with credentials and OAuth options
/auth/sign-up - Registration page for new users
/dashboard - User dashboard (after authentication)
/gigs - Browse available gigs/services
/jobs - Job postings from companies

Available Scripts

Here are the most useful npm scripts for development:

# Start development server with Turbopack
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Preview production build locally
pnpm preview

Project Structure

Understanding the codebase structure:

khedma-market/
├── prisma/
│   ├── schema.prisma          # Database schema definition
│   ├── seed.ts                # Database seeding script
│   └── migrations/            # Migration history
├── public/                    # Static assets
├── src/
│   ├── app/                   # Next.js App Router pages
│   │   ├── (public)/         # Public pages (homepage, auth)
│   │   ├── (dashboard)/      # Protected dashboard pages
│   │   └── api/              # API routes
│   ├── components/           # React components
│   ├── server/
│   │   ├── api/
│   │   │   ├── routers/      # tRPC routers
│   │   │   ├── trpc.ts       # tRPC configuration
│   │   │   └── root.ts       # Root router
│   │   ├── auth.ts           # NextAuth configuration
│   │   └── db.ts             # Prisma client instance
│   ├── trpc/                 # tRPC client setup
│   ├── lib/                  # Utility functions
│   ├── hooks/                # Custom React hooks
│   ├── schemas/              # Zod validation schemas
│   ├── styles/               # Global styles
│   └── env.js                # Environment variable validation
├── .env                      # Environment variables (create this)
├── .env.example              # Environment template
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── tailwind.config.ts        # Tailwind CSS configuration

Development Workflow

Make changes

Edit files in src/ directory. Changes will hot-reload automatically.

Update database schema

Modify prisma/schema.prisma and run migrations:

pnpm db:migrate

Add tRPC routes

Create or modify routers in src/server/api/routers/ for new API endpoints.

Test changes

Test your changes in the browser at http://localhost:3000

Troubleshooting

Database connection errors

Error: Can't reach database serverSolutions:

Verify MySQL is running: sudo systemctl status mysql
Check DATABASE_URL in .env matches your MySQL credentials
Ensure the database khedma-market exists
Try connecting manually: mysql -u root -p

Port 3000 already in use

Error: Port 3000 is already in useSolutions:

Kill the process using port 3000:

# Find process
lsof -ti:3000
# Kill it
kill -9 $(lsof -ti:3000)

Or use a different port:
```
PORT=3001 pnpm dev
```

Prisma Client errors

Error: PrismaClient is unable to be run in the browserSolutions:

Make sure you’re importing from @/server/db not @prisma/client in client components
Regenerate Prisma Client: pnpm db:generate
Restart the development server

Authentication issues

Error: [next-auth][error][NO_SECRET]Solutions:

Ensure NEXTAUTH_SECRET is set in .env
Generate a new secret: openssl rand -base64 32
Verify NEXTAUTH_URL matches your local URL

Module not found errors

Error: Cannot find module 'xyz'Solutions:

Clear node_modules and reinstall:
```
rm -rf node_modules
pnpm install
```
Clear Next.js cache:
```
rm -rf .next
pnpm dev
```

Using Prisma Studio

Prisma Studio provides a visual database browser:

pnpm db:studio

This opens a GUI at http://localhost:5555 where you can:

Browse all database tables
View, create, update, and delete records
Test relationships between models
Execute raw SQL queries

Prisma Studio is extremely helpful for debugging database issues and understanding data relationships.

Next Steps

Now that you have Khedma Market running locally:

Explore Features

Learn about freelancer profiles, gigs, orders, and messaging

API Documentation

Understand the tRPC API structure and available endpoints

Database Schema

Deep dive into the Prisma schema and data models

User Guides

Role-specific guides for using the platform

Contributing? Check out the CONTRIBUTING.md file in the repository for guidelines on submitting pull requests.

Get Started

Core Features

User Guides

Prerequisites

Setup Guide

Available Scripts

Project Structure

Development Workflow

Troubleshooting

Using Prisma Studio

Next Steps

Explore Features

API Documentation

Database Schema

User Guides

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

​Prerequisites

​Setup Guide

​Available Scripts

​Project Structure

​Development Workflow

​Troubleshooting

​Using Prisma Studio

​Next Steps

Explore Features

API Documentation

Database Schema

User Guides

Build docs developers (and LLMs) love

Prerequisites

Setup Guide

Available Scripts

Project Structure

Development Workflow

Troubleshooting

Using Prisma Studio

Next Steps