Development Setup

Setting up your local development environment for Smart Shelf contributions.

Development Setup

This guide will help you set up your local development environment to contribute to Smart Shelf.

Prerequisites

Ensure you have the following installed on your development machine:

Required Software

Node.js 18.0 or higher - JavaScript runtime
pnpm 8.0 or higher - Recommended package manager (faster than npm)
Git - Version control system
Modern code editor - VS Code recommended

Optional but Recommended

Docker - For local database setup (if not using Supabase cloud)
Supabase CLI - For database management and migrations

Local Development Setup

1. Fork and Clone the Repository

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/your-username/smart-shelf.git
cd smart-shelf

2. Install Dependencies

# Install all project dependencies
pnpm install

# If you don't have pnpm installed globally:
npm install -g pnpm
pnpm install

3. Environment Configuration

# Copy the example environment file
cp .env.example .env.local

# Edit the environment file with your configuration
nano .env.local  # or use your preferred editor

4. Environment Variables

Configure your .env.local file with the following variables:

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_NAME=Smart Shelf

# Supabase Configuration
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

# Security
JWT_SECRET=your-super-secure-jwt-secret-here
ENCRYPTION_KEY=your-32-character-encryption-key

# Development
NODE_ENV=development

5. Database Setup

Option A: Using Supabase Cloud (Recommended)

Create a new project at supabase.com
Copy your project URL and anon key to .env.local
Run the database migrations:

# Install Supabase CLI if not already installed
npm install -g supabase

# Login to Supabase
supabase login

# Link your project
supabase link --project-ref your-project-ref

# Push database schema
supabase db push

Option B: Local Supabase (Advanced)

# Start local Supabase stack
supabase start

# This will start:
# - PostgreSQL database
# - Supabase Studio (dashboard)
# - Edge Functions runtime
# - Storage server

6. Start Development Server

# Start the Next.js development server
pnpm dev

# Server will be available at http://localhost:3000

VS Code Setup

Recommended Extensions

Install these VS Code extensions for the best development experience:

// .vscode/extensions.json
{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-typescript-next",
    "unifiedjs.vscode-mdx",
    "supabase.supabase-vscode",
    "ms-vscode.vscode-json",
    "bradlc.vscode-tailwindcss"
  ]
}

Editor Configuration

Configure VS Code settings for consistent formatting:

// .vscode/settings.json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "tailwindCSS.includeLanguages": {
    "typescript": "typescript",
    "typescriptreact": "typescriptreact"
  },
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],
  "emmet.includeLanguages": {
    "typescript": "html",
    "typescriptreact": "html"
  }
}

Development Scripts

The project includes several useful scripts for development:

# Development
pnpm dev          # Start development server
pnpm dev:turbo    # Start development server with Turbopack (faster)

# Building
pnpm build        # Build production version
pnpm start        # Start production server

# Code Quality
pnpm lint         # Run ESLint
pnpm lint:fix     # Fix ESLint issues automatically
pnpm type-check   # Run TypeScript type checking
pnpm format       # Format code with Prettier

# Testing
pnpm test         # Run tests
pnpm test:watch   # Run tests in watch mode
pnpm test:ci      # Run tests for CI environment
pnpm test:e2e     # Run end-to-end tests

# Database
pnpm db:generate  # Generate database types
pnpm db:push      # Push schema changes
pnpm db:reset     # Reset database (development only)

# Analysis
pnpm analyze      # Analyze bundle size

Project Structure Overview

Understanding the project structure will help you navigate and contribute effectively:

smart-shelf/
├── app/                     # Next.js App Router
│   ├── (app)/              # Protected routes group
│   ├── api/                # API routes
│   ├── auth/               # Authentication pages
│   └── globals.css         # Global styles
├── components/             # React components
│   ├── ui/                 # Base UI components
│   ├── forms/              # Form components
│   └── features/           # Feature-specific components
├── lib/                    # Utility libraries
│   ├── actions/            # Server actions
│   ├── hooks/              # Custom React hooks
│   ├── services/           # Business logic
│   ├── types/              # TypeScript definitions
│   └── utils/              # Helper functions
├── public/                 # Static assets
├── supabase/              # Database schema and migrations
└── tests/                 # Test files

Common Development Tasks

Adding a New Feature

Create a new branch:

git checkout -b feature/your-feature-name

Create necessary files:
- Components in components/
- API routes in app/api/
- Types in lib/types/
- Tests in __tests__/

Test your changes:

pnpm type-check
pnpm lint
pnpm test
pnpm build

Database Changes

Create migration:

supabase migration new your_migration_name

Edit the migration file in supabase/migrations/
Apply migration:
```
supabase db push
```
Generate types:
```
pnpm db:generate
```

Debugging

Development Tools

React Developer Tools - Browser extension for React debugging
Supabase Studio - Database management interface
Network tab - Browser dev tools for API debugging
VS Code Debugger - Built-in debugging support

Common Issues

Dependencies issues:

# Clear node_modules and reinstall
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Environment variables not loading:

Ensure .env.local exists and has correct values
Restart development server after changes
Check that variables start with NEXT_PUBLIC_ for client-side access

TypeScript errors:

# Regenerate database types
pnpm db:generate

# Clear Next.js cache
rm -rf .next
pnpm dev

Build errors:

# Check for type errors
pnpm type-check

# Check for linting issues
pnpm lint

# Clear cache and rebuild
rm -rf .next
pnpm build

Performance Tips

Development Server

Use pnpm dev:turbo for faster hot reloads (Next.js 13+)
Close unnecessary browser tabs to reduce memory usage
Use --max-old-space-size=8192 Node.js flag for large projects

Code Editing

Enable TypeScript strict mode for better error detection
Use auto-imports and organize imports on save
Leverage IntelliSense for better autocomplete

Next Steps

Once your development environment is set up:

Read the Code Standards for coding guidelines
Check the Development Workflow for branch and commit conventions
Review Testing Guidelines for writing tests
Explore the codebase to understand the architecture

Getting Help

If you encounter issues during setup:

Check the troubleshooting section
Search existing GitHub issues
Create a new issue with detailed information about your problem
Join our community discussions

Happy coding! Your local development environment is now ready for contributing to Smart Shelf.

Contributing

Code Standards