Environment Setup

Step-by-step guide to set up your local development environment for Smart Shelf.

Repository Setup

1. Clone the Repository

# Clone the repository
git clone [your-repository-url]
cd smart-shelf

# Verify the clone
ls -la

Expected Structure:

smart-shelf/
├── app/                 # Next.js app directory
├── components/          # React components
├── lib/                # Utility functions
├── public/             # Static assets
├── styles/             # Global styles
├── .env.example        # Environment template
├── package.json        # Dependencies
├── next.config.mjs     # Next.js configuration
└── README.md           # Project documentation

2. Branch Setup (Contributors)

# Create your development branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

Dependency Installation

# Install dependencies
pnpm install

# Verify installation
pnpm list --depth=0

Using npm

# Install dependencies
npm install

# Verify installation
npm list --depth=0

Using yarn

# Install dependencies
yarn install

# Verify installation
yarn list --depth=0

Dependency Verification

Check that key dependencies are installed:

# Check Next.js
npx next --version

# Check TypeScript
npx tsc --version

# Check Tailwind CSS
npx tailwindcss --help

Environment Configuration

1. Create Environment File

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

# On Windows
copy .env.example .env.local

2. Configure Environment Variables

Edit .env.local with your configuration:

# =============================================
# SUPABASE CONFIGURATION
# =============================================
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# =============================================
# DEVELOPMENT CONFIGURATION
# =============================================
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# =============================================
# OPTIONAL FEATURES
# =============================================
# Enable bundle analyzer
ANALYZE=false

# Enable source maps in production
NEXT_PUBLIC_ENABLE_SOURCE_MAPS=false

# =============================================
# INTEGRATION SETTINGS (Optional)
# =============================================
# Stripe (for payments)
# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
# STRIPE_SECRET_KEY=sk_test_...

# Email (for notifications)
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USER=your-email@gmail.com
# SMTP_PASS=your-app-password

3. Environment Variable Validation

Create a simple validation script or use the built-in checker:

# Check if environment variables are properly set
pnpm run env:check

# Or manually verify key variables
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

Development Server

1. Start Development Server

# Using pnpm (recommended)
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

Expected Output:

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info  - automatically enabled Fast Refresh for 1 custom loader
event - compiled client and server successfully in 2.3s (173 modules)

2. Verify Development Server

  1. Open your browser and navigate to http://localhost:3000
  2. You should see the Smart Shelf welcome page
  3. Check browser console for any errors

3. Development Server Options

Standard Development:

pnpm dev

HTTPS Development (for testing camera/barcode features):

pnpm dev:https

Development with Turbopack (Next.js 13+):

pnpm dev --turbo

Custom Port:

pnpm dev -p 3001

Development Tools Setup

1. Code Formatting

# Install and configure Prettier
pnpm add -D prettier

# Run Prettier
pnpm format

# Format specific files
pnpm format src/

2. Linting

# Run ESLint
pnpm lint

# Fix linting issues automatically
pnpm lint:fix

# Lint specific directories
pnpm lint src/

3. Type Checking

# Run TypeScript compiler check
pnpm type-check

# Watch mode for continuous type checking
pnpm type-check:watch

4. Bundle Analysis

# Analyze bundle size
pnpm analyze

# This will open a browser window showing bundle composition

Git Configuration

1. Git Hooks Setup

# Install husky for git hooks
pnpm add -D husky

# Setup pre-commit hooks
npx husky install
npx husky add .husky/pre-commit "pnpm lint-staged"

2. Commit Message Format

Follow conventional commits format:

feat: add barcode scanning functionality
fix: resolve inventory count display issue
docs: update installation guide
style: format code with prettier
refactor: reorganize component structure
test: add unit tests for product management

3. Git Ignore Verification

Ensure these items are in .gitignore:

# Environment variables
.env.local
.env.development.local
.env.test.local
.env.production.local

# Dependencies
node_modules/
.pnpm-store/

# Next.js
.next/
out/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

Development Workflow

1. Daily Development Routine

# 1. Pull latest changes
git pull origin main

# 2. Install any new dependencies
pnpm install

# 3. Start development server
pnpm dev

# 4. Run tests in watch mode (optional)
pnpm test:watch

2. Before Committing

# 1. Run linting
pnpm lint

# 2. Run type checking
pnpm type-check

# 3. Run tests
pnpm test

# 4. Format code
pnpm format

# 5. Commit changes
git add .
git commit -m "feat: your descriptive commit message"

Troubleshooting Environment Setup

Common Issues

Port Already in Use

# Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or use different port
pnpm dev -p 3001

Node Version Issues

# Check Node version
node --version

# Use Node Version Manager
nvm use 18
# or
nvm install 18 && nvm use 18

Package Installation Failures

# Clear package manager cache
pnpm store prune
# or
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules
pnpm install

Environment Variables Not Loading

  • Ensure .env.local is in the project root
  • Restart development server after changes
  • Check variable names start with NEXT_PUBLIC_ for client-side access
  • Verify no spaces around = in environment file

TypeScript Errors

# Reinstall TypeScript
pnpm add -D typescript @types/node @types/react @types/react-dom

# Check TypeScript configuration
npx tsc --showConfig

Performance Issues

Slow Development Server

# Use Turbopack (experimental)
pnpm dev --turbo

# Optimize Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" pnpm dev

Bundle Size Issues

# Analyze bundle
pnpm analyze

# Check for duplicate dependencies
pnpm ls --depth=0

# Update dependencies
pnpm update

Next Steps

Once your environment is set up:

  1. Database Configuration - Set up Supabase project and schema
  2. Initial Configuration - Configure admin user and settings
  3. Development Guide - Learn about the codebase and development practices

Environment setup complete! Your Smart Shelf development environment is ready. Check the Troubleshooting Guide if you encounter any issues.