Environment and Prerequisites

This guide covers the prerequisites and environment setup required to develop, build, and deploy GitScope.

System Requirements

GitScope requires the following software installed on your system:

Node.js

runtime

required

Minimum version: 18.xNode.js 18 or higher is required for Vite and modern JavaScript features used in the project.

npm

package-manager

required

Minimum version: 9.xnpm 9 or higher is required for package management and running build scripts. npm is included with Node.js.

Verifying Installations

Before starting development, verify that you have the correct versions installed:

node --version
# Expected output: v18.x.x or higher

If your versions are below the minimum requirements, you’ll need to update Node.js and npm before proceeding.

Installing Node.js and npm

If you don’t have Node.js installed or need to update:

macOS
Windows
Linux

Using Homebrew

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js (includes npm)
brew install node@20

Using Node Version Manager (nvm)

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

# Install Node.js 20
nvm install 20
nvm use 20

Using Official Installer

Download the Node.js installer from nodejs.org
Run the installer (LTS version recommended)
Follow the installation wizard
Restart your terminal

Using Chocolatey

# Install Chocolatey if not already installed
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Node.js
choco install nodejs-lts

Using Node Version Manager (nvm-windows)

Download nvm-windows from GitHub releases
Install and restart your terminal
Run:

nvm install 20
nvm use 20

Using Package Manager (Ubuntu/Debian)

# Update package index
sudo apt update

# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Using Node Version Manager (nvm)

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

# Restart terminal or run:
source ~/.bashrc

# Install Node.js 20
nvm install 20
nvm use 20

Initial Project Setup

Once you have Node.js and npm installed, set up the GitScope project:

Clone the Repository

git clone https://github.com/David-Andino/github-dashboard.git
cd github-dashboard

Install Dependencies

npm install

This installs all required packages defined in package.json:

react ^18.2.0 - UI framework
react-dom ^18.2.0 - React DOM rendering
recharts ^2.10.3 - Chart library for language visualization
lucide-react ^0.263.1 - Icon library
vite ^5.0.8 - Build tool and dev server
@vitejs/plugin-react ^4.2.1 - React plugin for Vite
gh-pages ^6.1.1 - GitHub Pages deployment utility

Verify Installation

npm run dev

The development server should start on http://localhost:5173. You should see output like:

VITE v5.0.8  ready in 245 ms

➜  Local:   http://localhost:5173/
➜  press h to show help

Access the Application

Open your browser and navigate to http://localhost:5173. You should see the GitScope welcome screen.

Development Server Configuration

The Vite development server runs with the following default settings:

Port

number

default:"5173"

The local development server port. Can be changed with the --port flag:

npm run dev -- --port 3000

Host

string

default:"localhost"

By default, the server only accepts connections from localhost. To expose to your network:

npm run dev -- --host

Hot Module Replacement

boolean

default:"true"

Enabled by default. Updates are reflected instantly without full page reloads.

Base Path

string

default:"/github-dashboard/"

The base URL path configured in vite.config.js. This matches the production deployment path on GitHub Pages.

Environment Variables

GitScope does not require environment variables for development or production. All configuration is handled through:

GitHub API Token: Stored in browser localStorage after user input
Build Configuration: Defined in vite.config.js and package.json
GitHub API Endpoint: Hardcoded to https://api.github.com

If you plan to add environment variables in the future:

Use the VITE_ prefix to expose them to client code
Never commit sensitive data to version control
Create .env.local and add it to .gitignore
Use .env.example to document required variables

Example Environment Setup (Optional)

If you need to add environment-specific configuration:

.env.local

# Development environment (not committed to git)
VITE_API_ENDPOINT=https://api.github.com
VITE_ENABLE_DEBUG=true

src/config.js

export const config = {
  apiEndpoint: import.meta.env.VITE_API_ENDPOINT || 'https://api.github.com',
  debug: import.meta.env.VITE_ENABLE_DEBUG === 'true'
}

Development Workflow

Once your environment is set up, follow this typical development workflow:

Start Dev Server

npm run dev

Runs on http://localhost:5173 with hot module replacement enabled.

Make Changes

Edit files in the src/ directory. Changes are reflected instantly in the browser.

Test Locally

Use the application in your browser to verify functionality.

Build for Production

npm run build

Creates optimized production build in dist/ directory.

Preview Production Build

npm run preview

Serves the production build locally on http://localhost:4173 for testing.

Deploy

npm run deploy

Builds and deploys to GitHub Pages automatically.

IDE Setup (Optional)

For the best development experience, consider using:

VS Code Extensions

ES7+ React/Redux/React-Native snippets - Code snippets for React
ESLint - JavaScript linting
Prettier - Code formatting
CSS Modules - IntelliSense for CSS Modules
Vite - Vite-specific features and syntax highlighting

VS Code Settings

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "css.lint.unknownAtRules": "ignore"
}

Troubleshooting

Port Already in Use

If port 5173 is already in use:

npm run dev -- --port 3000

Permission Errors on npm install

On Linux/macOS, avoid using sudo with npm. If you encounter permission errors:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add the export line to your ~/.bashrc or ~/.zshrc.

Module Not Found Errors

If you see “Module not found” errors:

# Clear npm cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Vite Server Not Starting

Check that:

Node.js version is 18 or higher
No other process is using port 5173
All dependencies installed successfully
vite.config.js has no syntax errors

Next Steps

Build Process

Learn about the Vite build configuration and optimization

GitHub Pages Deployment

Deploy your application to GitHub Pages

Deploy

​System Requirements

​Node.js

​npm

​Verifying Installations

​Installing Node.js and npm

​Using Homebrew

​Using Node Version Manager (nvm)

​Using Official Installer

​Using Chocolatey

​Using Node Version Manager (nvm-windows)

​Using Package Manager (Ubuntu/Debian)

​Using Node Version Manager (nvm)

​Initial Project Setup

​Development Server Configuration

​Environment Variables

​Example Environment Setup (Optional)

​Development Workflow

​IDE Setup (Optional)

​VS Code Extensions

​VS Code Settings

​Troubleshooting

​Port Already in Use

​Permission Errors on npm install

​Module Not Found Errors

​Vite Server Not Starting

​Next Steps

Build Process

GitHub Pages Deployment

Build docs developers (and LLMs) love

System Requirements

Node.js

npm

Verifying Installations

Installing Node.js and npm

Using Homebrew

Using Node Version Manager (nvm)

Using Official Installer

Using Chocolatey

Using Node Version Manager (nvm-windows)

Using Package Manager (Ubuntu/Debian)

Using Node Version Manager (nvm)

Initial Project Setup

Development Server Configuration

Environment Variables

Example Environment Setup (Optional)

Development Workflow

IDE Setup (Optional)

VS Code Extensions

VS Code Settings

Troubleshooting

Port Already in Use

Permission Errors on npm install

Module Not Found Errors

Vite Server Not Starting

Next Steps