Installation Guide

This comprehensive guide covers everything you need to install and configure CV Builder for development or production use.

Prerequisites

Before you begin, ensure your development environment meets these requirements:

Required

Node.js

Version 18.17 or laterCheck your version:

node --version

Download from nodejs.org

Package Manager

pnpm (recommended), npm, or yarnCheck if installed:

pnpm --version

Install pnpm:

npm install -g pnpm

Optional

Firebase Project

Required for cloud sync, authentication, and version control features.Create at console.firebase.google.com

Git

For version control and cloning the repository.Download from git-scm.com

System Requirements

Component	Minimum	Recommended
Node.js	18.17.x	20.x or later
RAM	4 GB	8 GB or more
Disk Space	500 MB	1 GB
OS	Windows 10, macOS 10.15, Ubuntu 20.04	Latest versions

Installation Steps

Clone the Repository

Get the source code from GitHub:

git clone https://github.com/tariqahmaad/CV-Builder.git
cd CV-Builder

Alternative: Download ZIPIf you don’t have Git installed:

Visit github.com/tariqahmaad/CV-Builder
Click Code → Download ZIP
Extract the archive
Navigate to the extracted folder in your terminal

The repository uses the main branch by default. No need to checkout specific branches for stable releases.

Install Dependencies

Install all required npm packages:

pnpm install

This command installs dependencies from package.json:

package.json (excerpt)

{
  "dependencies": {
    "next": "16.1.6",
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "typescript": "^5",
    "firebase": "^12.8.0",
    "tailwindcss": "^4",
    "@react-pdf/renderer": "^4.3.2",
    "react-hook-form": "^7.71.1",
    "zod": "^4.3.6",
    "framer-motion": "^12.29.2",
    "@google/generative-ai": "^0.24.1",
    "lucide-react": "^0.563.0"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4",
    "@types/node": "^20",
    "@types/react": "^19",
    "eslint": "^9",
    "eslint-config-next": "16.1.6"
  }
}

What gets installed:

Core Framework: Next.js 16.1.6 with React 19.2.3
Backend: Firebase 12.8.0 for auth and database
Forms: React Hook Form + Zod validation
PDF: @react-pdf/renderer for exports
Styling: Tailwind CSS 4.x
AI: Google Generative AI for assistance
Animations: Framer Motion
Icons: Lucide React

Installation may take 2-5 minutes depending on your internet speed and system performance.

Configure Environment Variables (Optional)

To enable Firebase features, create a .env.local file:

touch .env.local

Add your Firebase configuration:

.env.local

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key_here
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

Where to find these values:

Go to Firebase Console
Select or create your project
Click the gear icon → Project settings
Scroll to Your apps section
Click the web app icon (</>) or create a new web app
Copy the config values from the firebaseConfig object

These environment variables are loaded in lib/firebase.ts:

lib/firebase.ts

import { initializeApp, getApps, getApp } from "firebase/app";
import { getAuth } from "firebase/auth";
import { getFirestore } from "firebase/firestore";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
  measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
};

const app = getApps().length === 0 ? initializeApp(firebaseConfig) : getApp();

export const auth = getAuth(app);
export const db = getFirestore(app);
export default app;

Without Firebase configuration, the app runs in Guest Mode only. All features work except authentication and cloud sync.

Set Up Firebase (Optional)

If you’re using Firebase, configure the required services:

Authentication Setup

In Firebase Console, go to Build → Authentication
Click Get started
Enable Email/Password sign-in method
(Optional) Enable Password reset emails

Firestore Database Setup

Go to Build → Firestore Database
Click Create database
Select Start in production mode
Choose your preferred location (select closest to your users)
Click Enable

Firestore Security Rules:After creating the database, update the security rules:

firestore.rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // CV documents - users can only access their own
    match /cvs/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    
    // CV versions - users can only access their own
    match /versions/{versionId} {
      allow read, write: if request.auth != null && 
        resource.data.userId == request.auth.uid;
    }
    
    // CV backups - users can only access their own
    match /backups/{backupId} {
      allow read, write: if request.auth != null && 
        resource.data.userId == request.auth.uid;
    }
  }
}

Storage Setup (for profile images)

Go to Build → Storage
Click Get started
Start in production mode
Click Done

Storage Security Rules:

storage.rules

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /profile-images/{userId}/{imageId} {
      allow read: if true;
      allow write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Always use proper security rules in production to prevent unauthorized access to user data.

Start Development Server

Launch the Next.js development server:

pnpm dev
# or npm run dev / yarn dev

Expected output:

▲ Next.js 16.1.6
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.1s

Available Scripts:

package.json (scripts)

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

Command	Description
`pnpm dev`	Start development server with hot reload
`pnpm build`	Create production build
`pnpm start`	Start production server (after build)
`pnpm lint`	Run ESLint to check code quality

Verify Installation

Test that everything works:

Basic Features
Firebase Features
Template System

Navigate to http://localhost:3000
Click “Start Building”
Fill in the personal information form
Verify the preview updates in real-time
Try exporting a PDF

Directory Structure

After installation, your project structure should look like this:

CV-Builder/
├── .git/                   # Git version control
├── .next/                  # Next.js build output (generated)
├── node_modules/           # Installed dependencies (generated)
├── app/                    # Next.js App Router pages
│   ├── api/                # API routes
│   ├── editor/             # Resume editor page
│   │   └── page.tsx        # Main editor component
│   ├── resumes/            # Resume list page
│   ├── templates/          # Template preview page
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Landing page
│   └── globals.css         # Global styles
├── components/             # React components
│   ├── forms/              # Form section components
│   ├── home/               # Landing page sections
│   ├── preview/            # Live preview & PDF components
│   ├── templates/          # Template implementations
│   │   ├── nexus/          # Nexus template
│   │   ├── rhyhorn/        # Rhyhorn template
│   │   └── types.ts        # Template type definitions
│   ├── ui/                 # Reusable UI primitives
│   └── cv-builder.tsx      # Main CV builder component
├── hooks/                  # Custom React hooks
├── lib/                    # Core library & utilities
│   ├── backend/            # Backend service modules
│   │   ├── cvRepository.ts # Firestore operations
│   │   ├── cvService.ts    # Business logic
│   │   ├── cvValidation.ts # Zod schemas
│   │   ├── cvDraftStorage.ts # LocalStorage management
│   │   └── cvThreeWayMerge.ts # Conflict resolution
│   ├── AuthContext.tsx     # Auth state management
│   ├── firebase.ts         # Firebase initialization
│   ├── types.ts            # TypeScript definitions
│   └── utils.ts            # Utility functions
├── public/                 # Static assets
│   ├── icon.svg            # App icon
│   └── apple-icon.svg      # Apple touch icon
├── .env.local              # Environment variables (you create this)
├── .gitignore              # Git ignore rules
├── eslint.config.mjs       # ESLint configuration
├── next.config.ts          # Next.js configuration
├── package.json            # Project dependencies
├── pnpm-lock.yaml          # Lock file (pnpm)
├── postcss.config.mjs      # PostCSS configuration
├── README.md               # Project documentation
└── tsconfig.json           # TypeScript configuration

The .next/ and node_modules/ directories are automatically generated and should never be committed to version control.

Configuration Files

next.config.ts

Next.js configuration with React Compiler enabled:

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true, // Enable React Compiler for optimization
};

export default nextConfig;

tsconfig.json

TypeScript configuration for strict type checking:

tsconfig.json (excerpt)

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "paths": {
      "@/*": ["./*"]
    }
  }
}

The @/* path alias allows you to import from project root, e.g., import { CVData } from '@/lib/types'

Troubleshooting

Error: Node version too old

Problem:

error: The engine "node" is incompatible with this module.
Expected version ">=18.17.0". Got "16.14.0"

Solution:Upgrade Node.js to version 18.17 or later:

Download from nodejs.org
Or use a version manager like nvm:

nvm install 20
nvm use 20

Verify the version:

node --version
# Should show v18.17.0 or higher

Error: pnpm not found

Problem:

bash: pnpm: command not found

Solution:Install pnpm globally:

npm install -g pnpm

Or use npm/yarn instead:

npm install
npm run dev

Error: Port 3000 already in use

Problem:

Error: listen EADDRINUSE: address already in use :::3000

Solution:Either kill the process using port 3000:

lsof -ti:3000 | xargs kill -9

Or run on a different port:

pnpm dev -- -p 3001

Error: Firebase configuration missing

Problem:Sign-in button doesn’t work, or you see Firebase errors in console.Solution:

Ensure .env.local exists with all Firebase variables
Restart the dev server after creating/modifying .env.local
Verify all 7 environment variables are set (not empty strings)
Check for typos in variable names (must be exactly as shown)

# Check if variables are loaded
cat .env.local

Remember: Changes to .env.local require a server restart to take effect.

Error: Module not found during build

Problem:

Module not found: Can't resolve '@/components/...''

Solution:

Delete node_modules and lock file:

rm -rf node_modules pnpm-lock.yaml

Clear Next.js cache:

rm -rf .next

Reinstall dependencies:

pnpm install

Restart dev server:

pnpm dev

PDF export not working

Problem:PDF export button doesn’t download a file, or shows an error.Solution:

Check browser console for errors
Ensure @react-pdf/renderer is installed:

pnpm list @react-pdf/renderer
# Should show @react-pdf/renderer 4.3.2

If missing, reinstall:

pnpm install @react-pdf/renderer@^4.3.2

Clear browser cache and try again
Try in an incognito/private window to rule out extensions

Firestore permission denied

Problem:

FirebaseError: Missing or insufficient permissions

Solution:

Check Firebase Console → Firestore Database → Rules
Ensure rules allow authenticated users to access their own data
Verify you’re signed in (check auth state)
Update security rules if needed (see Step 4 above)

Temporary test rules (development only):

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

Never use test rules in production! Always restrict access to user-owned documents.

TypeScript errors in IDE

Problem:Red squiggly lines everywhere, or “Cannot find module” errors.Solution:

Ensure TypeScript is installed:

pnpm list typescript

Reload your IDE/editor window:
- VSCode: Ctrl+Shift+P → “Reload Window”
- WebStorm: File → Invalidate Caches / Restart
Check tsconfig.json exists and is valid
Install missing type definitions:

pnpm install -D @types/node @types/react @types/react-dom

Production Build

Before deploying, test the production build locally:

Create Production Build

pnpm build

This command:

Compiles TypeScript
Bundles JavaScript/CSS
Optimizes images and assets
Generates static pages where possible

Expected output:

✓ Compiled successfully
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    1.2 kB          120 kB
├ ○ /editor                              892 B           135 kB
└ ○ /resumes                             456 B           118 kB

○  (Static)  prerendered as static content

Start Production Server

pnpm start

Test the production build at http://localhost:3000

Deploy

For production deployment, refer to Next.js documentation for deploying to:

Vercel (recommended)
Netlify
Docker
Self-hosted VPS

Next Steps

Quickstart

Build your first resume in 5 minutes

Templates

Learn about available templates

API Reference

Explore the CV service API

Contributing

Contribute to the project

Getting Help

If you encounter issues not covered here:

GitHub Issues: github.com/tariqahmaad/CV-Builder/issues
Discussions: github.com/tariqahmaad/CV-Builder/discussions
Email: Contact the maintainer via GitHub profile

Get Started

Core Features

User Guide

Advanced

Installation

Installation Guide

Prerequisites

Required

Node.js

Package Manager

Optional

Firebase Project

Git

System Requirements

Installation Steps

Authentication Setup

Firestore Database Setup

Storage Setup (for profile images)

Directory Structure

Configuration Files

next.config.ts

tsconfig.json

Troubleshooting

Production Build

Next Steps

Quickstart

Templates

API Reference

Contributing

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

Advanced

​Installation Guide

​Prerequisites

​Required

Node.js

Package Manager

​Optional

Firebase Project

Git

​System Requirements

​Installation Steps

​Authentication Setup

​Firestore Database Setup

​Storage Setup (for profile images)

​Directory Structure

​Configuration Files

​next.config.ts

​tsconfig.json

​Troubleshooting

​Production Build

​Next Steps

Quickstart

Templates

API Reference

Contributing

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required

Optional

System Requirements

Installation Steps

Authentication Setup

Firestore Database Setup

Storage Setup (for profile images)

Directory Structure

Configuration Files

next.config.ts

tsconfig.json

Troubleshooting

Production Build

Next Steps

Getting Help