Learning Objectives

By the end of this lesson, you will have:

Node.js and npm/pnpm installed
VS Code configured with essential extensions
Your first Next.js 16 project created
Understanding of the project structure

1. Prerequisites Installation

Before you can start building Next.js applications, you need to have Node.js installed on your machine. Node.js is the JavaScript runtime that powers the development server and build tools.

Node.js

Next.js requires Node.js 18.18 or later.

These commands check if Node.js and npm are already installed on your system and display their version numbers.

Check if Node.js is installed:

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

npm --version
# Should output 9.x.x or higher

Install Node.js:

Visit nodejs.org
Download the LTS (Long Term Support) version
Follow installation instructions for your OS

Recommended: Use Node Version Manager (nvm)

Node Version Manager allows you to install and switch between multiple Node.js versions, which is useful when working on different projects that require different versions.

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

# Then install Node.js
nvm install 20
nvm use 20

# Windows - use nvm-windows
# https://github.com/coreybutler/nvm-windows

Package Manager (pnpm recommended)

pnpm is a fast, disk-efficient package manager that we recommend for this course. This command installs it globally so you can use it for all your projects.

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Why pnpm?

Faster than npm
Saves disk space
Strict dependency resolution
Works great with monorepos

2. VS Code Setup

Install VS Code

Download from code.visualstudio.com

Essential Extensions

Install these extensions for the best development experience:

Extension	Purpose
ESLint	JavaScript/TypeScript linting
Prettier	Code formatting
Tailwind CSS IntelliSense	Tailwind autocomplete & linting
TypeScript Vue Plugin (Volar)	Better TS support
Error Lens	Inline error display
Auto Rename Tag	Rename paired HTML/JSX tags
GitLens	Enhanced Git integration

These commands install VS Code extensions from the command line, which is faster than searching for them in the Extensions panel.

Install via command line:

code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension usernamehw.errorlens
code --install-extension formulahendry.auto-rename-tag

VS Code Settings

This configuration enables automatic formatting on save, uses ESLint to fix issues automatically, and configures Tailwind CSS IntelliSense to recognize custom class patterns.

Create or update .vscode/settings.json in your project:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ],
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

3. Create Your Next.js Project

Using create-next-app

The create-next-app tool scaffolds a new Next.js project with all the necessary configuration files and dependencies pre-configured.

# Navigate to your projects folder
cd ~/projects

# Create a new Next.js project
pnpm create next-app@latest rizpay-clone

# Or with npm
npx create-next-app@latest rizpay-clone

Configuration Prompts

When prompted, select these options:

✔ Would you like to use TypeScript? → Yes
✔ Would you like to use ESLint? → Yes
✔ Would you like to use Tailwind CSS? → Yes
✔ Would you like your code inside a `src/` directory? → Yes
✔ Would you like to use App Router? (recommended) → Yes
✔ Would you like to use Turbopack for `next dev`? → Yes
✔ Would you like to customize the import alias? → Yes
  What import alias would you like configured? → @/*

Start the Development Server

After creating the project, navigate into the project directory and start the development server to see your application running.

cd rizpay-clone
pnpm dev

Open http://localhost:3000 in your browser.

4. Project Structure

After creation, your project structure will look like this:

rizpay-clone/
├── src/
│   └── app/                    # App Router directory
│       ├── layout.tsx          # Root layout
│       ├── page.tsx            # Home page (/)
│       ├── globals.css         # Global styles
│       └── favicon.ico
├── public/                     # Static files
│   └── (images, fonts, etc.)
├── .eslintrc.json             # ESLint configuration
├── .gitignore
├── next.config.ts             # Next.js configuration
├── package.json
├── postcss.config.mjs         # PostCSS config (for Tailwind)
├── tailwind.config.ts         # Tailwind configuration
└── tsconfig.json              # TypeScript configuration

Key Files Explained

The root layout wraps all pages in your application. It defines the HTML structure and is where you include global elements like navigation and footer.

src/app/layout.tsx - Root layout wrapping all pages:

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

The page component defines the content for a specific route. This file renders the home page when users visit the root URL.

src/app/page.tsx - Home page component:

export default function Home() {
  return (
    <main>
      <h1>Welcome to RizPay Clone</h1>
    </main>
  )
}

The Next.js configuration file allows you to customize build settings, environment variables, and other framework-specific options.

next.config.ts - Next.js configuration:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Configuration options
}

export default nextConfig

5. Configure Tailwind CSS v4

Next.js 16 with Tailwind CSS v4 uses the new CSS-first configuration.

Update `src/app/globals.css`

This CSS file imports Tailwind CSS and defines custom theme variables using the new CSS-based configuration approach. The @theme block defines design tokens that can be used throughout your application.

@import "tailwindcss";

/* Custom theme variables */
@theme {
  --color-primary: #4F46E5;
  --color-primary-dark: #4338CA;
  --color-secondary: #06B6D4;
  --color-success: #10B981;
  --color-warning: #F59E0B;
  --color-danger: #EF4444;

  --font-sans: 'Inter', system-ui, sans-serif;
}

/* Base styles */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900 antialiased;
  }
}

6. Essential Configuration

Add Path Aliases

Path aliases let you import modules using clean, absolute paths instead of relative paths with multiple dots. This configuration maps the @ symbol to the src directory.

Update tsconfig.json for cleaner imports:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/types/*": ["./src/types/*"],
      "@/hooks/*": ["./src/hooks/*"]
    }
  }
}

Create Project Folders

This command creates the directory structure for organizing your code. Separating components, utilities, types, and hooks keeps your codebase maintainable as it grows.

mkdir -p src/{components,lib,types,hooks}
mkdir -p src/components/{ui,layout,forms}

Updated structure:

src/
├── app/
├── components/
│   ├── ui/           # Reusable UI components
│   ├── layout/       # Layout components
│   └── forms/        # Form components
├── lib/              # Utility functions
├── types/            # TypeScript type definitions
└── hooks/            # Custom React hooks

7. Add Essential Types

Create src/types/index.ts:

These type definitions establish the data structures you will use throughout the application. Defining them centrally ensures consistency and makes refactoring easier.

// Common types used across the application

export interface User {
  id: string;
  name: string;
  email: string;
  phone?: string;
  createdAt: Date;
}

export interface Transaction {
  id: string;
  type: TransactionType;
  amount: number;
  status: TransactionStatus;
  userId: string;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

export type TransactionType = 'airtime' | 'data' | 'electricity' | 'cable';

export type TransactionStatus = 'pending' | 'processing' | 'completed' | 'failed';

export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  message?: string;
  errors?: Record<string, string[]>;
}

8. Create Utility Functions

Create src/lib/utils.ts:

These utility functions handle common tasks like merging CSS classes, formatting currency, and formatting dates. The cn function is especially useful for conditionally combining Tailwind classes.

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

// Merge Tailwind classes safely
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Format currency (Nigerian Naira)
export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat('en-NG', {
    style: 'currency',
    currency: 'NGN',
    minimumFractionDigits: 0,
  }).format(amount);
}

// Format date
export function formatDate(date: Date | string): string {
  return new Intl.DateTimeFormat('en-NG', {
    dateStyle: 'medium',
    timeStyle: 'short',
  }).format(new Date(date));
}

// Format phone number
export function formatPhoneNumber(phone: string): string {
  const cleaned = phone.replace(/\D/g, '');
  if (cleaned.length === 11) {
    return `${cleaned.slice(0, 4)} ${cleaned.slice(4, 7)} ${cleaned.slice(7)}`;
  }
  return phone;
}

These packages provide the class merging functionality. clsx handles conditional class names, and tailwind-merge resolves conflicts between Tailwind classes.

Install dependencies:

pnpm add clsx tailwind-merge

9. Environment Variables

Create .env.local for local development:

Environment variables store configuration that changes between environments (development, staging, production). Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_NAME=RizPay Clone

# Supabase (we'll add these later)
# NEXT_PUBLIC_SUPABASE_URL=
# NEXT_PUBLIC_SUPABASE_ANON_KEY=

# RizPay API (we'll add these later)
# RIZPAY_API_KEY=
# RIZPAY_SECRET_KEY=
# RIZPAY_API_URL=

Adding .env.local to .gitignore ensures your secret keys and local configuration are never committed to version control.

Add .env.local to .gitignore:

echo ".env.local" >> .gitignore

10. Scripts

Update package.json scripts:

These npm scripts provide shortcuts for common development tasks. The type-check script validates TypeScript without generating output files.

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "type-check": "tsc --noEmit"
  }
}

Assignment

Task: Set Up Your Development Environment

Complete the following steps:

Install Node.js 18+ and verify with node --version
Install pnpm and verify with pnpm --version
Install VS Code extensions listed above
Create a new Next.js project called rizpay-clone:
```
pnpm create next-app@latest rizpay-clone
```

Create the folder structure:

src/
├── components/ui/
├── components/layout/
├── components/forms/
├── lib/
├── types/
└── hooks/

Create initial files:
- src/types/index.ts with User and Transaction types
- src/lib/utils.ts with helper functions
Install dependencies:
```
pnpm add clsx tailwind-merge
```
Run the development server and verify it works:
```
pnpm dev
```
Take a screenshot of your running app at localhost:3000

Verification Checklist

Node.js 18+ installed
pnpm installed
VS Code with extensions
Next.js project created with TypeScript & Tailwind
Folder structure created
Type definitions created
Utility functions created
Development server running

Troubleshooting

Common Issues

Port 3000 already in use:

These commands help you identify and stop any process using port 3000, or alternatively run your application on a different port.

# Find and kill the process
lsof -i :3000
kill -9 <PID>

# Or use a different port
pnpm dev --port 3001

Module not found errors:

Clearing the cache and reinstalling dependencies often resolves mysterious module resolution errors.

# Clear cache and reinstall
rm -rf node_modules .next
pnpm install

TypeScript errors:

This command runs the TypeScript compiler without generating output, showing any type errors in your code.

# Check types
pnpm type-check

Additional Resources

Next Lesson: Next.js 16 Introduction