Installation Guide

This comprehensive guide covers all requirements, dependencies, environment configuration, and troubleshooting for running Guigolo locally or deploying to production.

System Requirements

Node.js Version

Guigolo requires Node.js 20 or higher to run Next.js 16 and React 19.

node --version
# Should output v20.x.x or higher

React 19 and Next.js 16 require Node.js 20+. Using older Node versions will cause installation and runtime errors.

Package Manager Options

Guigolo works with any modern package manager:

Package Manager	Version	Notes
npm	9.0+	Included with Node.js
yarn	1.22+ or 3.0+	Faster installs, workspace support
pnpm	8.0+	Disk space efficient, strict dependencies

The project includes a package-lock.json file, indicating npm was used for development. However, you can use any package manager you prefer.

Core Dependencies

Framework & Runtime

From package.json (package.json:11-17):

"dependencies": {
  "next": "16.1.1",
  "react": "19.2.3",
  "react-dom": "19.2.3"
}

Next.js 16.1.1 - App Router with React Server Components, built-in optimization
React 19.2.3 - Latest React with improved compiler and hooks
React DOM 19.2.3 - DOM rendering for React 19

UI & Interaction Libraries

"dependencies": {
  "embla-carousel-react": "^8.6.0",
  "embla-carousel-autoplay": "^8.6.0"
}

Embla Carousel - Lightweight, extensible carousel for project galleries
Autoplay plugin - Automatic slideshow functionality

Embla Carousel is used in the Projects section to showcase case studies with smooth transitions and touch support.

Analytics & Monitoring

"dependencies": {
  "@vercel/analytics": "^1.6.1"
}

Vercel Analytics - Privacy-friendly analytics with Web Vitals tracking (app/layout.tsx:135)

Additional analytics are configured via environment variables:

Google Analytics - GA4 tracking (production only)
Hotjar - Heatmaps and session recordings (production only)

Development Dependencies

From package.json (package.json:19-30):

"devDependencies": {
  "@types/node": "^20",
  "@types/react": "^19",
  "@types/react-dom": "^19",
  "typescript": "^5",
  "eslint": "^9",
  "eslint-config-next": "16.1.1",
  "tailwindcss": "^3.4.17",
  "autoprefixer": "^10.4.23",
  "postcss": "^8.5.6"
}

TypeScript 5 - Type safety and IntelliSense
ESLint 9 - Code linting with Next.js preset
Tailwind CSS 3.4.17 - Utility-first styling
PostCSS & Autoprefixer - CSS processing and vendor prefixes

Environment Variables

Guigolo uses environment variables for analytics and feature flags. While the repository doesn’t include .env files (no .env files found in source), you can create them for local development or production deployment.

Optional Analytics Configuration

Create a .env.local file in the project root:

.env.local

# Vercel Environment (automatic on Vercel)
VERCEL_ENV=production

# Google Analytics (optional)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# Hotjar (optional)
NEXT_PUBLIC_HJ_ID=1234567
NEXT_PUBLIC_HJ_SV=6

Environment Variable Reference

From app/layout.tsx (app/layout.tsx:81-85):

VERCEL_ENV - Set to "production" to enable analytics in production only
NEXT_PUBLIC_GA_ID - Google Analytics 4 Measurement ID (format: G-XXXXXXXXXX)
NEXT_PUBLIC_HJ_ID - Hotjar Site ID (numeric)
NEXT_PUBLIC_HJ_SV - Hotjar Snippet Version (default: "6")

All analytics scripts are conditionally loaded based on VERCEL_ENV === "production" (app/layout.tsx:94-133). This prevents analytics from running during local development.

None of these environment variables are required for local development. The app runs fine without them - you just won’t have analytics tracking.

Formspree Configuration

The contact form uses a hardcoded Formspree endpoint (components/Contact.tsx:14):

const FORMSPREE_ENDPOINT = "https://formspree.io/f/xpqqzvro";

If you’re forking this project, you’ll want to:

Create your own Formspree account at https://formspree.io
Set up a new form and get your unique endpoint
Replace the endpoint in components/Contact.tsx

Formspree’s free tier allows 50 submissions per month, which is perfect for personal portfolios.

Installation Steps

1. Clone the Repository

git clone https://github.com/yourusername/guigolo.git
cd guigolo

2. Install Dependencies

npm install

3. (Optional) Configure Environment Variables

If you want analytics in development:

cp .env.example .env.local
# Edit .env.local with your credentials

4. Run Development Server

npm run dev

5. Build for Production

Test the production build locally:

npm run build
npm run start

The build process will:

Compile TypeScript to JavaScript
Generate optimized React bundles
Process and minify CSS with Tailwind
Optimize images and static assets
Generate static pages where possible

Tailwind CSS Configuration

Guigolo uses a custom Tailwind configuration with design tokens (tailwind.config.js:1):

Custom Color Palette

colors: {
  "neutral-black-900": "#101010",
  "neutral-black-800": "#161616",
  "neutral-white": "#ededed",
  "neutral-gray-600": "#3c3c3c",
  "neutral-gray-500": "#4c4c4c",
  "accent-lilac": "#6900ea",
  "accent-cyan-10": "rgba(20,177,255,0.10)",
  "accent-lime": "#C6FF00",
}

Custom Typography Scale

fontSize: {
  "heading-xl": ["36px", { lineHeight: "125%" }],
  "heading-lg": ["24px", { lineHeight: "28.8px" }],
  "heading-md": ["16px", { lineHeight: "19.2px" }],
  "body-lg": ["14px", { lineHeight: "15px" }],
  "body-md": ["12px", { lineHeight: "13.75px" }],
  "body-sm": ["11px", { lineHeight: "12.5px" }],
}

Responsive Breakpoints

screens: {
  sm: "640px",
  md: "768px",
  lg: "1024px",
  xl: "1280px",
  "2xl": "1536px",
  "3xl": "1920px",
  "4xl": "2560px",
}

The extended breakpoints (3xl, 4xl) ensure the portfolio looks great on ultra-wide monitors and 4K displays.

Troubleshooting

Common Installation Issues

npm ERR! peer dependencies

React 19 and Next.js 16 may show peer dependency warnings with some packages. These are usually safe to ignore if using npm 7+:

npm install --legacy-peer-deps

Or upgrade to the latest npm:

npm install -g npm@latest

Type errors with React 19

Ensure you have the correct TypeScript definitions:

npm install --save-dev @types/react@^19 @types/react-dom@^19

If errors persist, delete the .next build folder:

rm -rf .next
npm run dev

Tailwind styles not applying

Ensure globals.css is imported in app/layout.tsx and that your PostCSS config is valid:

# Verify PostCSS config
cat postcss.config.mjs

Expected output:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

'use client' directive errors

Next.js 16 uses React Server Components by default. Components with client-side features (useState, useEffect, event handlers) must have 'use client' at the top:

'use client';

import { useState } from 'react';
// ...

Most interactive components in components/ already have this directive.

Embla Carousel not working

Ensure both carousel packages are installed:

npm list embla-carousel-react embla-carousel-autoplay

If missing:

npm install embla-carousel-react embla-carousel-autoplay

Analytics not tracking in development

This is intentional! Analytics only load when VERCEL_ENV === "production" (app/layout.tsx:81-133).To test analytics locally, temporarily modify the condition:

const isProd = true; // Force enable for testing

Remember to revert this change before committing.

Build Errors

Module parse failed: Unexpected token

This usually indicates a syntax error in TypeScript/JSX. Check:

All imports are correct
JSX is in .tsx files, not .ts
No mixing of CommonJS (require) and ESM (import)

Run TypeScript compiler to see detailed errors:

npx tsc --noEmit

Image optimization errors

Next.js optimizes images automatically. If you encounter errors:

Ensure images are in public/ directory
Use relative paths from public/ (e.g., /og/cover-social.png)
Images must be valid formats (JPEG, PNG, WebP, AVIF, SVG)

Large SVGs should be placed in public/ and imported as strings, not optimized.

Out of memory during build

Increase Node.js memory limit:

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

Or add to package.json scripts:

"build": "NODE_OPTIONS='--max-old-space-size=4096' next build"

Deployment

Vercel (Recommended)

Guigolo is optimized for Vercel deployment:

Push your code to GitHub
Import the repository in Vercel dashboard
Configure environment variables (GA_ID, HJ_ID, etc.)
Deploy

Vercel automatically detects Next.js and configures:

Build command: next build
Output directory: .next
Install command: npm install

The VERCEL_ENV variable is automatically set by Vercel, so analytics will work in production without manual configuration.

Other Platforms

For platforms like Netlify, Railway, or DigitalOcean:

Build command: npm run build
Start command: npm run start
Node version: 20+
Environment variables: Set VERCEL_ENV=production and any analytics keys

Some redirects in next.config.ts use Next.js-specific features. Ensure your platform supports Next.js middleware and redirects.

Next Steps

With Guigolo installed and running:

Explore the component architecture in components/
Customize the gamification system in components/gamification/
Update project data in components/projects/project.data.ts
Modify color schemes in tailwind.config.js
Add new routes in the app/ directory

For a quick overview of the project structure and main features, refer back to the Introduction.

Get Started

Core Concepts

Components

Guides

Installation

Installation Guide

System Requirements

Node.js Version

Package Manager Options

Core Dependencies

Framework & Runtime

UI & Interaction Libraries

Analytics & Monitoring

Development Dependencies

Environment Variables

Optional Analytics Configuration

Formspree Configuration

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. (Optional) Configure Environment Variables

4. Run Development Server

5. Build for Production

Tailwind CSS Configuration

Custom Color Palette

Custom Typography Scale

Responsive Breakpoints

Troubleshooting

Common Installation Issues

Build Errors

Deployment

Vercel (Recommended)

Other Platforms

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Components

Guides

​Installation Guide

​System Requirements

​Node.js Version

​Package Manager Options

​Core Dependencies

​Framework & Runtime

​UI & Interaction Libraries

​Analytics & Monitoring

​Development Dependencies

​Environment Variables

​Optional Analytics Configuration

​Formspree Configuration

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​3. (Optional) Configure Environment Variables

​4. Run Development Server

​5. Build for Production

​Tailwind CSS Configuration

​Custom Color Palette

​Custom Typography Scale

​Responsive Breakpoints

​Troubleshooting

​Common Installation Issues

​Build Errors

​Deployment

​Vercel (Recommended)

​Other Platforms

​Next Steps

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Node.js Version

Package Manager Options

Core Dependencies

Framework & Runtime

UI & Interaction Libraries

Analytics & Monitoring

Development Dependencies

Environment Variables

Optional Analytics Configuration

Formspree Configuration

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. (Optional) Configure Environment Variables

4. Run Development Server

5. Build for Production

Tailwind CSS Configuration

Custom Color Palette

Custom Typography Scale

Responsive Breakpoints

Troubleshooting

Common Installation Issues

Build Errors

Deployment

Vercel (Recommended)

Other Platforms

Next Steps