Installation Guide

Complete step-by-step instructions for setting up WI-CARPOOL on your local machine or server

Prerequisites

Before installing WI-CARPOOL, ensure you have the following software installed on your system:

System Requirements: WI-CARPOOL can run on Windows, macOS, and Linux systems with the following minimum requirements.

Required Software

Software Minimum Version Recommended Version Purpose
Node.js 16.0.0 18.x or 20.x LTS JavaScript runtime for running the application
npm 8.0.0 Latest Package manager (comes with Node.js)
Git 2.20.0 Latest Version control for cloning the repository

Optional Software

  • Yarn (v1.22.x or v3.x) - Alternative package manager
  • pnpm (v7.x+) - Fast, disk space efficient package manager
  • VS Code - Recommended IDE with excellent TypeScript support
  • Google Chrome - For development and testing PWA features

Installing Node.js

Using Node Version Manager (Recommended)

# Install nvm (Linux/macOS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal or run:
source ~/.bashrc

# Install and use Node.js LTS
nvm install --lts
nvm use --lts

# Verify installation
node --version
npm --version

Direct Installation

# Download from official website
# Visit: https://nodejs.org/

# For Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# For CentOS/RHEL/Fedora
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs npm

# For macOS with Homebrew
brew install node

# For Windows with Chocolatey
choco install nodejs

Project Setup

1. Clone the Repository

First, clone the WI-CARPOOL repository to your local machine:

Using HTTPS

# Clone the repository
git clone https://github.com/your-username/wi-carpool-frontend.git

# Navigate to the project directory
cd wi-carpool-frontend

Using SSH (if you have SSH keys set up)

# Clone the repository
git clone [email protected]:your-username/wi-carpool-frontend.git

# Navigate to the project directory
cd wi-carpool-frontend

2. Install Dependencies

Install all required packages using your preferred package manager:

Using npm (Default)

# Install dependencies
npm install

# Verify installation
npm list --depth=0

Using Yarn

# Install Yarn globally (if not already installed)
npm install -g yarn

# Install dependencies
yarn install

# Verify installation
yarn list --depth=0

Using pnpm

# Install pnpm globally (if not already installed)
npm install -g pnpm

# Install dependencies
pnpm install

# Verify installation
pnpm list --depth=0

3. Environment Configuration

WI-CARPOOL uses environment variables for configuration. While the application works with default settings, you may need to configure specific settings for your environment.

Note: This application doesn't use traditional .env files. Configuration is handled through the build process and runtime environment variables.

Environment Variables

# Development mode (automatically set by Vite)
NODE_ENV=development

# API Base URL (configure in src/api/constants.ts)
VITE_API_BASE_URL=https://pool.prattle.me/

# Google Maps API Key (if using maps functionality)
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key

# Enable PWA features
VITE_PWA_ENABLED=true

4. Verify Installation

Verify that everything is set up correctly by running the development server:

Start Development Server

# Start the development server
npm run dev

# Or with yarn
yarn dev

# Or with pnpm
pnpm dev

If successful, you should see output similar to:

Expected Output

  VITE v4.x.x  ready in xxx ms

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://192.168.x.x:8080/
  ➜  press h to show help

IDE Setup

Visual Studio Code (Recommended)

For the best development experience, we recommend using VS Code with the following extensions:

Required Extensions

  • TypeScript and JavaScript Language Features - Built-in TypeScript support
  • ES7+ React/Redux/React-Native snippets - Code snippets for React
  • Tailwind CSS IntelliSense - Autocomplete for Tailwind classes
  • Auto Rename Tag - Automatically rename paired HTML/JSX tags

Recommended Extensions

  • Prettier - Code formatter - Code formatting
  • ESLint - Linting support
  • Bracket Pair Colorizer - Color matching brackets
  • GitLens - Enhanced Git capabilities
  • Thunder Client - API testing tool
  • Live Server - Live reload for static files

VS Code Settings Configuration

# Create .vscode/settings.json
{
  "typescript.updateImportsOnFileMove.enabled": "always",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "emmet.includeLanguages": {
    "typescript": "html",
    "typescriptreact": "html"
  },
  "tailwindCSS.includeLanguages": {
    "typescript": "html",
    "typescriptreact": "html"
  }
}

Alternative IDEs

WebStorm

  • Built-in TypeScript and React support
  • Excellent debugging capabilities
  • Built-in Git integration

Sublime Text

  • Install TypeScript package
  • Install JSX package for React support
  • Install SublimeLinter for code quality

Troubleshooting

Common Installation Issues

Node.js Version Conflicts

Problem: Multiple Node.js versions causing conflicts

Solution

# Use nvm to manage Node.js versions
nvm list
nvm use 18.17.0  # or your preferred LTS version

# Set default Node.js version
nvm alias default 18.17.0

Permission Errors (npm)

Problem: EACCES permission errors when installing packages globally

Solution for Linux/macOS

# Configure npm to use a different directory for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Reload shell configuration
source ~/.bashrc

Port Already in Use

Problem: Port 8080 is already in use

Solution

# Kill process using port 8080
lsof -ti:8080 | xargs kill -9

# Or use a different port
npm run dev -- --port 3000

Build Errors

Problem: TypeScript compilation errors

Solution

# Clear node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

# If using yarn
rm -rf node_modules yarn.lock
yarn install

# Check TypeScript configuration
npx tsc --noEmit

Performance Issues

Slow npm install

Solutions

# Use npm ci for faster, reliable, reproducible builds
npm ci

# Increase npm timeout
npm config set timeout 60000

# Use different registry if default is slow
npm config set registry https://registry.npmjs.org/

# Clear npm cache
npm cache clean --force

Memory Issues

Increase Node.js memory limit

# For development server
NODE_OPTIONS="--max-old-space-size=4096" npm run dev

# For build process
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Next Steps

Now that you have WI-CARPOOL installed, here are the recommended next steps:

🚀 Quick Start Guide

Learn the basics of running and developing with WI-CARPOOL

🏗️ System Architecture

Understand how the application is structured and organized

⚙️ Environment Configuration

Configure the application for your specific needs

🌐 Deployment Guide

Deploy WI-CARPOOL to production servers

Additional Resources

Official Documentation

Development Tools

Community Resources