Setup & Environment

Development environment setup, tech stack overview, and essential commands for getting started.

Setup & Environment

Tech Stack Overview

This project uses a modern full-stack TypeScript setup with the following core technologies:

Frontend Technologies

Next.js 15 with App Router

// Server components for data fetching
import { NextRequest, NextResponse } from 'next/server'
import { cookies } from 'next/headers'

// React 19 with Server Components
import { Suspense } from 'react'

export default function ServerComponent() {
  // Server-side logic here
  return <div>Server-rendered content</div>
}

TypeScript for Type Safety

// Strong typing for all data structures
interface Product {
  id: string
  name: string
  sku: string
  price: number
  category_id: string
  created_at: string
  updated_at: string
}

// Utility types for API responses
type ApiResponse<T> = {
  data: T | null
  error: string | null
  success: boolean
}

Styling & UI Framework

Tailwind CSS with shadcn/ui

// Utility-first CSS framework
import { cn } from '@/lib/utils'
import { Button } from '@/components/ui/button'

export function MyComponent() {
  return (
    <div className="flex items-center justify-between p-4 bg-white rounded-lg shadow-md">
      <h2 className="text-lg font-semibold text-gray-900">Title</h2>
      <Button variant="outline" size="lg" className={cn('hover:bg-blue-50')}>
        Click me
      </Button>
    </div>
  )
}

Component Library

// Pre-built components from shadcn/ui
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card'
import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'

Data Visualization

Recharts for Analytics

import { 
  LineChart, 
  Line, 
  XAxis, 
  YAxis, 
  CartesianGrid, 
  Tooltip, 
  ResponsiveContainer 
} from 'recharts'

export function SalesChart({ data }: { data: any[] }) {
  return (
    <ResponsiveContainer width="100%" height={300}>
      <LineChart data={data}>
        <CartesianGrid strokeDasharray="3 3" />
        <XAxis dataKey="month" />
        <YAxis />
        <Tooltip />
        <Line 
          type="monotone" 
          dataKey="sales" 
          stroke="#3b82f6" 
          strokeWidth={2}
        />
      </LineChart>
    </ResponsiveContainer>
  )
}

Development Commands

Essential Commands

Development Server

# Start development server
pnpm dev

# Start development server with HTTPS (required for barcode scanning)
pnpm dev:https

# Start development server on specific port
pnpm dev -- --port 3001

Building

# Production build
pnpm build

# Build with bundle analysis
pnpm build:analyze

# Start production server locally
pnpm start

Code Quality

# Run ESLint
pnpm lint

# Fix linting issues automatically
pnpm lint --fix

# Run TypeScript type checking
pnpm type-check

# Format code with Prettier
pnpm format

Testing

# Run unit tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run E2E tests
pnpm test:e2e

Analysis & Debugging

# Analyze bundle size
pnpm analyze

# Check for unused dependencies
pnpm depcheck

# Check for security vulnerabilities
pnpm audit

Environment Setup

Prerequisites

Node.js 18+

node --version  # Should be v18 or higher

pnpm Package Manager
```
npm install -g pnpm
pnpm --version
```
Git
```
git --version
```

Installation

Clone Repository

git clone https://github.com/your-username/your-project.git
cd your-project

Install Dependencies
```
pnpm install
```

Environment Variables

# Copy environment template
cp .env.example .env.local

# Edit environment variables
nano .env.local

Database Setup

# Run database migrations
pnpm db:migrate

# Seed development data
pnpm db:seed

Environment Variables

Required Variables

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/database"

# Authentication
NEXTAUTH_SECRET="your-secret-key-32-characters-long"
NEXTAUTH_URL="http://localhost:3000"

# Supabase
NEXT_PUBLIC_SUPABASE_URL="your-supabase-project-url"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-supabase-service-role-key"

Optional Variables

# Analytics
NEXT_PUBLIC_GA_ID="GA_MEASUREMENT_ID"

# File Storage
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloudinary-name"

# Email
EMAIL_SERVER_HOST="smtp.example.com"
EMAIL_SERVER_PORT=587
EMAIL_FROM="noreply@example.com"

Development Workflow

Daily Development

Start Development Server
```
pnpm dev
```

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes
- Write code
- Add tests
- Update documentation
Quality Checks
```
pnpm lint
pnpm type-check
pnpm test
```

Commit Changes

git add .
git commit -m "feat: add new feature"

IDE Setup

VS Code Extensions

{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "ms-playwright.playwright"
  ]
}

VS Code Settings

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative",
  "tailwindCSS.experimental.classRegex": [
    ["cn\\(([^)]*)\\)", "'([^']*)'"]
  ]
}

Troubleshooting

Common Issues

Port Already in Use

# Kill process using port 3000
npx kill-port 3000

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

Module Resolution Errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript Errors

# Restart TypeScript server
# In VS Code: Cmd+Shift+P -> "TypeScript: Restart TS Server"

# Check TypeScript version
pnpm tsc --version

Database Connection Issues

# Check database connection
pnpm db:status

# Reset database
pnpm db:reset

Get your development environment set up quickly with these essential tools and commands for productive development.

Dev Guide

Architecture