Skip to main content

​
Prerequisites

Before installing the portfolio, ensure your development environment meets these requirements:

​
Required Software

Node.js

Version 20 or later requiredCheck your version:
node --version
Download from nodejs.org

Package Manager

npm, yarn, or pnpmnpm comes with Node.js. Alternatives:
  • Yarn: npm install -g yarn
  • pnpm: npm install -g pnpm

Git

For cloning the repositoryCheck installation:
git --version
Download from git-scm.com

Code Editor

VS Code recommendedInstall from code.visualstudio.comRecommended extensions:
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense

​
System Requirements

  • Operating System: Windows 10+, macOS 10.15+, or Linux
  • RAM: 4GB minimum, 8GB recommended
  • Disk Space: 500MB for dependencies
  • Browser: Modern browser (Chrome, Firefox, Safari, Edge)

​
Detailed Installation Steps

1

Verify Prerequisites

Before starting, verify all prerequisites are installed:
# Check Node.js version (should be 20+)
node --version

# Check npm version
npm --version

# Check Git installation
git --version
If Node.js version is below 20, you’ll need to upgrade. The portfolio uses features that require Node.js 20 or later.
2

Clone the Repository

Clone the portfolio repository from GitHub:
# Clone via HTTPS
git clone https://github.com/ThalysonRibeiro/my-portfolio-fullstack.git

# Or clone via SSH (if you have SSH keys set up)
git clone [email protected]:ThalysonRibeiro/my-portfolio-fullstack.git

# Navigate into the project directory
cd my-portfolio-fullstack
Creating Your Own Version? Fork the repository on GitHub first, then clone your fork:
git clone https://github.com/YOUR-USERNAME/my-portfolio-fullstack.git
3

Install Dependencies

Install all required packages. Choose your preferred package manager:
# Install with npm
npm install

# Alternative: Clean install (recommended for production)
npm ci
This installs all dependencies from package.json:Core Dependencies:
  • next@^16.1.5 - Next.js framework
  • react@^19.2.3 - React library
  • react-dom@^19.2.3 - React DOM
  • typescript@^5 - TypeScript
UI & Styling:
  • tailwindcss@^4 - Tailwind CSS
  • @radix-ui/* - UI component primitives
  • framer-motion@^12.17.0 - Animations
  • lucide-react@^0.514.0 - Icons
Forms & Validation:
  • react-hook-form@^7.57.0 - Form handling
  • zod@^3.25.58 - Schema validation
  • @hookform/resolvers@^5.1.1 - Form resolvers
State & Utilities:
  • zustand@^5.0.11 - State management
  • sonner@^2.0.5 - Toast notifications
  • clsx@^2.1.1 - Class utilities
Installation time varies by package manager:
  • npm: 2-4 minutes
  • yarn: 1-3 minutes
  • pnpm: 30 seconds - 2 minutes (uses shared cache)
4

Environment Configuration

The portfolio uses environment variables for configuration. While the portfolio can run without environment variables, some features require them:Optional Environment Variables:Create a .env.local file in the project root:
# Create environment file
touch .env.local
Add the following variables (all optional):
# Site URL (for SEO and metadata)
NEXT_PUBLIC_URL=http://localhost:3000

# Google Analytics (optional - for analytics tracking)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# Bundle Analyzer (optional - set to 'true' to analyze bundle)
ANALYZE=false
For Production: Replace http://localhost:3000 with your actual domain when deploying.

​
Environment Variable Details

NEXT_PUBLIC_URL
  • Used in metadata and OpenGraph tags
  • Default: http://localhost:3000 (from layout.tsx:21)
  • Set this to your production URL when deploying
NEXT_PUBLIC_GA_ID
  • Google Analytics measurement ID
  • Optional: Only needed if using Google Analytics
  • Format: G-XXXXXXXXXX
ANALYZE
  • Bundle analyzer configuration (from next.config.ts:4)
  • Set to true to analyze bundle size
  • Run build to see analyzer: ANALYZE=true npm run build
Never commit .env.local to version control. It’s already in .gitignore by default.
5

Verify Installation

Verify everything is set up correctly before starting development:
# Check if all dependencies are installed
npm list --depth=0

# Verify TypeScript configuration
npx tsc --noEmit

# Run linter to check for issues
npm run lint
All commands should complete without errors.
6

Start Development Server

Launch the development server with Turbopack:
npm run dev
You should see:
▲ Next.js 16.1.5
- Local:        http://localhost:3000
- Turbopack:    enabled

✓ Starting...
✓ Ready in 1.2s
The portfolio uses Turbopack by default (--turbopack flag in package.json:6) for faster development experience.

​
Troubleshooting Installation Issues

​
Common Issues and Solutions

Error: error: The engine "node" is incompatible with this moduleSolution: Upgrade Node.js to version 20 or later.
# Check current version
node --version

# Upgrade using nvm (recommended)
nvm install 20
nvm use 20

# Or download from nodejs.org
Consider using nvm (Node Version Manager) to manage multiple Node.js versions.
Error: EACCES: permission denied or EPERM: operation not permittedSolution: Fix npm permissions (avoid using sudo):
# Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH in your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH=~/.npm-global/bin:$PATH

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc
Windows: Run terminal as Administrator or check Windows Defender settings.
Error: Various npm/yarn errors during installationSolution: Clear cache and reinstall:
# Clear npm cache
npm cache clean --force

# Remove existing modules
rm -rf node_modules package-lock.json

# Reinstall
npm install
Error: Error: listen EADDRINUSE: address already in use :::3000Solution: Use a different port or stop the process using port 3000:
# Use different port
PORT=3001 npm run dev

# Or kill process on port 3000 (macOS/Linux)
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
Error: Error: Cannot find module 'xyz' or Module not found: Can't resolve 'xyz'Solution: Ensure all dependencies are installed and TypeScript paths are configured:
# Reinstall dependencies
npm install

# Check TypeScript configuration
cat tsconfig.json | grep paths

# Should show: "@/*": ["./src/*"]

# Clear Next.js cache
rm -rf .next

# Restart dev server
npm run dev
Error: Various TypeScript compilation errorsSolution: Verify TypeScript configuration and dependencies:
# Check TypeScript version (should be 5.x)
npx tsc --version

# Verify configuration
npx tsc --showConfig

# Check for type errors without emitting
npx tsc --noEmit

# Install missing type definitions
npm install --save-dev @types/node @types/react @types/react-dom
Error: Issues with Turbopack or slow compilationSolution: Disable Turbopack temporarily:
// In package.json, change:
"dev": "next dev --turbopack",
// to:
"dev": "next dev",
Or run directly:
npx next dev
Report Turbopack issues to the Next.js team as it’s still in active development.
Error: Production build fails with various errorsSolution: Identify and fix build-time issues:
# Run build in verbose mode
npm run build -- --debug

# Check for ESLint errors
npm run lint

# Type check
npx tsc --noEmit

# Clear all caches
rm -rf .next node_modules package-lock.json
npm install
npm run build

​
Verification Steps

After installation, verify everything works correctly:
1

Visual Verification

Open http://localhost:3000 in your browser and verify:
  • ✅ Page loads without errors
  • ✅ Hero section displays with animations
  • ✅ Navigation menu works
  • ✅ Images load correctly (may show placeholder if Cloudinary isn’t configured)
  • ✅ Smooth scrolling between sections
  • ✅ Contact form renders properly
  • ✅ Footer displays correctly
2

Console Verification

Open browser DevTools (F12) and check:
  • ✅ No red errors in Console tab
  • ✅ No 404 errors in Network tab
  • ✅ No hydration warnings
  • ✅ React DevTools shows component tree (install React DevTools extension)
3

Hot Reload Test

Test that hot reload works:
  1. Open src/app/page.tsx in your editor
  2. Make a visible change (e.g., change some text)
  3. Save the file
  4. Browser should update automatically without refresh
Changes should appear in under 1 second with Turbopack enabled.
4

Build Verification

Verify production build works:
# Create production build
npm run build

# Should complete without errors and show:
# ✓ Compiled successfully
# ✓ Collecting page data
# ✓ Generating static pages
# ✓ Finalizing page optimization

# Test production build locally
npm start
Visit http://localhost:3000 to test the production build.

​
Post-Installation Configuration

Install these extensions for the best development experience: 
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense",
    "dsznajder.es7-react-js-snippets"
  ]
}

​
Configure Prettier (Optional)

The project includes Prettier configuration (.prettierrc). Configure your editor to format on save: 
// In VS Code settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

​
Configure ESLint (Optional)

ESLint configuration is in eslint.config.mjs. It’s already set up with Next.js and Prettier rules.

​
Next Steps

Quick Start

Return to the Quick Start guide for a streamlined workflow

Project Structure

Learn about the codebase organization

Customization

Start customizing the portfolio for your needs

Deployment

Deploy your portfolio to production

​
Getting Additional Help

If you’re still experiencing issues:
  1. Check Documentation: Review relevant sections in this documentation
  2. Next.js Docs: Visit nextjs.org/docs for framework-specific issues
  3. GitHub Issues: Check existing issues or create a new one
  4. Community Support: Ask in Next.js Discord or React communities
  5. Dependency Issues: Check individual package documentation for specific errors
When seeking help, include:
  • Your Node.js version (node --version)
  • Your package manager and version
  • Full error messages
  • Steps to reproduce the issue

Build docs developers (and LLMs) love

Get started for freeTalk to us