Source: ocean/docs/DEVELOPER_GUIDE.md | ✏️ Edit on GitHub

Developer Guide

🚀 Quick Start

# Clone the repository
git clone https://github.com/goldfish-inc/ocean.git
cd ocean

# Install dependencies
pnpm install

# Start development server
pnpm run dev

🔄 Development Workflow

Daily Development Flow

1. Pull latest changes

   git pull origin main
   pnpm install  # In case dependencies changed

2. Create feature branch

   git checkout -b feature/your-feature-name

3. Make changes and test locally

   pnpm run dev  # Start dev server at http://localhost:3000

4. Stage and commit

   git add .
   git commit -m "feat: your feature description"
   # ✅ Automatic validation runs here!
   #    - TypeScript type checking
   #    - Test suite execution

5. Push and create PR

   git push origin feature/your-feature-name
   # GitHub Actions will validate your code

🛡️ Validation Tools

Automatic Validations (No action needed)

When	What Runs	Can Skip?
On git commit	TypeScript check + Tests	git commit --no-verify
On git push	GitHub Actions CI/CD	No
On PR to main	Full CI + Vercel preview	No

Manual Validations (Run when needed)

# Quick validation (TypeScript + Tests)
make validate
# or
pnpm run validate

# Test in Docker (production-like)
make docker-test

# Full pre-deployment check
make pre-deploy

# Just TypeScript checking
pnpm run typecheck

# Just run tests
pnpm run test

📁 Project Structure

ocean/
├── src/
│   ├── components/      # React components
│   ├── routes/         # TanStack Router pages
│   ├── services/       # Business logic
│   ├── contexts/       # React contexts
│   ├── hooks/          # Custom hooks
│   └── lib/            # Utilities
├── public/             # Static assets
├── .github/            # GitHub Actions
├── .husky/             # Git hooks
├── scripts/            # Build scripts
└── docs/               # Documentation

🔧 Available Scripts

Command	Description
pnpm run dev	Start development server
pnpm run build	Build for production
pnpm run test	Run test suite
pnpm run test:watch	Run tests in watch mode
pnpm run typecheck	Check TypeScript types
pnpm run validate	Run all validations
pnpm run docker:test	Test in Docker container
pnpm run docker:prod	Preview production build

🐳 Docker Development

Testing Your Build

# Test if your code builds in Docker (like Vercel)
make docker-test

# Run development server in Docker
docker-compose up dev

# Preview production build
docker-compose up prod
# Visit http://localhost:8080

When to Use Docker

• Before deploying major changes
• When debugging build issues
• Testing with different Node versions
• Reproducing CI/CD environment locally

🚨 Common Issues & Solutions

Build Fails on Commit

# If TypeScript errors:
pnpm run typecheck  # See all errors
pnpm run dev       # Fix with hot reload

# If tests fail:
pnpm run test:watch  # Debug interactively

Emergency Commit (Use Sparingly!)

git commit --no-verify -m "hotfix: critical bug"
# ⚠️ Only for emergencies! Fix validation after.

Clean Rebuild

# Nuclear option - clean everything
rm -rf node_modules dist .vercel
pnpm install
pnpm run build

Docker Issues

# Rebuild without cache
docker-compose build --no-cache

# Clean Docker system
docker system prune -a

🏗️ Architecture Decisions

Tech Stack

• Framework: React 19 + Vite
• Routing: TanStack Router (file-based)
• Forms: TanStack Form + Zod validation
• UI: shadcn/ui + Tailwind CSS v4
• Auth: Supabase (passwordless OTP)
• Deployment: Vercel

Key Patterns

1. File-based routing - Routes in src/routes/
2. Passwordless auth - No passwords, only OTP codes
3. Type safety - Strict TypeScript throughout
4. Component library - shadcn/ui components in src/components/ui/

🔐 Environment Variables

Local Development

# Copy example env
cp .env.example .env

# Required variables:
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_anon_key

Production Secrets

Managed via Vercel CLI:

vercel env add VITE_SUPABASE_URL
vercel env add VITE_SUPABASE_ANON_KEY

📝 Commit Convention

Follow conventional commits:

feat: add new feature
fix: resolve bug
docs: update documentation
style: formatting changes
refactor: code restructuring
test: add/update tests
chore: maintenance tasks

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes with tests
4. Ensure all validations pass
5. Submit PR with clear description

📚 Additional Resources

• BUILD_VALIDATION.md - Detailed validation guide
• PASSWORDLESS_AUTH.md - Authentication flow
• SUPABASE_PRODUCTION_SETUP.md - Production config

💡 Pro Tips

1. Always run make validate before pushing big changes
2. Use pnpm run test:watch for TDD
3. Check docker-compose logs for container issues
4. Keep PR scope small and focused
5. Write tests for new features

---

Questions? Check existing docs or open an issue!