Skip to main content

​
Quickstart Guide

This guide will help you clone, install, and run the Guigolo portfolio locally on your development machine.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20+ installed on your machine
  • npm, yarn, or pnpm package manager
  • Git for cloning the repository
  • A code editor (VS Code, Cursor, or similar)
1

Clone the Repository

Clone the Guigolo source code from GitHub:
git clone https://github.com/yourusername/guigolo.git
cd guigolo
Replace yourusername/guigolo with the actual repository URL if you’re forking from a different source.
2

Install Dependencies

Install all required dependencies using your preferred package manager:
npm install
This will install all dependencies from package.json, including:
The installation typically takes 1-2 minutes depending on your internet connection and machine speed.
3

Run the Development Server

Start the Next.js development server:
npm run dev
The development server will start on http://localhost:3000 by default.
▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 2.3s
Next.js 16 features turbopack for faster builds. The first load might take a few seconds, but subsequent hot reloads are nearly instant.
4

Explore the Application

Open your browser and navigate to http://localhost:3000. You should see:
  • Hero section with animated gradient background
  • Blueprint-style navigation with SVG icons
  • Services accordion showcasing UX/UI offerings
  • Featured projects section with case studies
  • Process timeline explaining the design workflow
  • About section with personal background
  • Contact form powered by Formspree
  • FAQ section with common questions
The gamification system (achievements and missions) is active in development mode. Try scrolling through sections and interacting with forms to trigger achievements!
5

Understand the Folder Structure

Familiarize yourself with the project organization:
guigolo/
├── app/
│   ├── layout.tsx          # Root layout with fonts & analytics
│   ├── page.tsx            # Home page with all sections
│   ├── robots.ts           # SEO robots configuration
│   ├── sitemap.ts          # XML sitemap generation
│   └── what-is-guigolo/    # About page route
├── components/
│   ├── Navbar.tsx          # Main navigation component
│   ├── Hero.tsx            # Hero section
│   ├── Contact.tsx         # Contact form with Formspree
│   ├── ProjectsSection.tsx # Featured projects grid
│   ├── gamification/       # Achievement & mission system
│   ├── projects/           # Project data and components
│   └── ui/                 # Reusable UI components
├── public/
│   ├── brand/              # Logo and brand assets
│   ├── hero/               # Hero section SVGs
│   └── og/                 # Open Graph images
├── styles/
│   └── globals.css         # Global styles & Tailwind imports
├── tailwind.config.js      # Tailwind customization
├── next.config.ts          # Next.js configuration with redirects
└── package.json            # Dependencies and scripts
  • app/layout.tsx (app/layout.tsx:1) - Configures Google Fonts (Unbounded & Anta), metadata, analytics (Google Analytics, Hotjar, Vercel Analytics), and JSON-LD structured data
  • app/page.tsx (app/page.tsx:1) - Composes all homepage sections including gamification boot components
  • components/Contact.tsx (components/Contact.tsx:14) - Formspree endpoint at https://formspree.io/f/xpqqzvro with achievement unlocking on form submission
  • next.config.ts (next.config.ts:1) - Defines 30+ redirect rules for /go/* UTM tracking links
  • tailwind.config.js (tailwind.config.js:1) - Custom color palette, typography scale, and responsive breakpoints
6

Explore Key Routes

The application has the following main routes:
  • / - Homepage with all portfolio sections
  • /what-is-guigolo - About page explaining the project philosophy
  • /go/* - UTM tracking redirects (e.g., /go/github, /go/figma)
All /go/* routes redirect to the homepage with specific UTM parameters for analytics tracking (next.config.ts:4-197).
The /que-es-guigolo route permanently redirects to /what-is-guigolo (next.config.ts:6-10). This was a localization change from Spanish to English.

​
What’s Next?

Now that you have Guigolo running locally, you can:
  • Customize the content - Edit project data in components/projects/project.data.ts
  • Modify styling - Update Tailwind config or component styles
  • Add features - Extend the gamification system or add new sections
  • Configure analytics - Set up environment variables for Google Analytics and Hotjar
For detailed environment variable setup and production deployment, see the Installation guide.

​
Common Issues

If port 3000 is occupied, Next.js will automatically try port 3001. You can also specify a custom port:
npm run dev -- -p 3001
Delete node_modules and package-lock.json, then reinstall:
rm -rf node_modules package-lock.json
npm install
Next.js 16 may show TypeScript errors during the first build. These usually resolve after the initial compilation completes. If errors persist, check your TypeScript version:
npm list typescript
# Should be TypeScript 5.x

​
Need Help?

If you encounter issues not covered here, check the Installation guide for more detailed troubleshooting, or review the source code comments for implementation details.

Build docs developers (and LLMs) love

Get started for freeTalk to us