Installation & Prerequisites

This guide covers everything you need to install and configure for Portfolio OS development.

System Requirements

Required Software

Recommended Tools

• Code Editor: VS Code with extensions:
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • TypeScript and JavaScript Language Features
• Terminal: iTerm2 (macOS), Windows Terminal (Windows), or your preferred terminal
• Browser: Chrome/Edge with React DevTools extension

Installing Prerequisites

Node.js Installation

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

# Install Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

# Install nvm-windows from https://github.com/coreybutler/nvm-windows/releases
# Then run:
nvm install 18
nvm use 18

PNPM Installation

PNPM is faster and more disk-efficient than npm. Portfolio OS requires PNPM for workspace management.

npm install -g pnpm

# Verify installation
pnpm --version

Git Installation

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Installing Portfolio OS

Once all prerequisites are installed, follow these steps:

git clone https://github.com/jschibelli/portfolio-os.git
cd portfolio-os

pnpm install

# Check that all packages are installed
pnpm list --depth=0

# Verify Turbo can see all workspaces
pnpm turbo run build --dry-run

Post-Installation Setup

Editor Configuration

VS Code Users: Install the recommended extensions by opening the command palette (Cmd/Ctrl + Shift + P) and running:

Extensions: Show Recommended Extensions

Environment Variables

You'll need to configure environment variables before running the apps. See the Environment Configuration guide for details.

Troubleshooting Installation Issues

PNPM Command Not Found

Problem: pnpm: command not found after installation

Solutions:

1. Restart your terminal
2. Check if PNPM is in your PATH: echo $PATH (macOS/Linux) or $env:Path (Windows)
3. Reinstall PNPM using a different method

Module Not Found Errors

Problem: Import errors after installation

Solutions:

# Clean install
rm -rf node_modules
pnpm install

# Clear PNPM cache if issues persist
pnpm store prune
pnpm install

Prisma Generation Fails

Problem: Prisma client generation errors

Solutions:

# Regenerate Prisma client manually
cd apps/dashboard
pnpm prisma generate

# If still failing, clean and reinstall
cd ../..
rm -rf apps/dashboard/node_modules
pnpm install

Port Conflicts

Problem: EADDRINUSE: address already in use :::3000

Solutions:

1. Stop the conflicting process
2. Or change the port in apps/site/next.config.js (for site) or apps/dashboard/next.config.js (for dashboard)

Next Steps

Once installation is complete:

1. Configure Environment Variables - Set up API keys and configuration
2. First Steps Tutorial - Build your first feature
3. Developer Guide - Learn the architecture

Version Compatibility