Setup Guide

Complete guide to setting up the Constellation front-end development environment.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Link
Node.js	18.x or higher	nodejs.org
Bun	Latest	bun.sh
Git	Latest	git-scm.com

Verify Installation

# Check Node.js
node --version

# Check Bun
bun --version

# Check Git
git --version

---

Step 1: Clone Repository

git clone https://github.com/your-org/constellation.git
cd constellation

---

Step 2: Install Dependencies

# Using Bun (recommended)
bun install

# Or using npm
npm install

📌 Important: This project uses Bun as the package manager. Prefer bun over npm or yarn.

---

Step 3: Environment Configuration

Create .env.local File

Create a .env.local file in the project root:

cp .env.example .env.local

Or manually create .env.local:

touch .env.local

Environment Variables

Add the following variables to .env.local:

Backend Services

# Neo4j Graph Database
NEXT_PUBLIC_NEO4J_URL=http://localhost:8000

# Main API Server
NEXT_PUBLIC_API_URL=http://localhost:8001

# Server-Sent Events (Real-time Updates)
NEXT_PUBLIC_SSE_URL=http://localhost:8002

# Hocuspocus (Collaborative Editing via CRDT)
NEXT_PUBLIC_CRDT_HOCUSPOCUS_URL=ws://localhost:8003

# AI/ML API
NEXT_PUBLIC_AI_API_URL=http://localhost:8004

Google OAuth Configuration

# Get from https://console.cloud.google.com/
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:8001/auth/google/callback
GOOGLE_TOKEN_URI=https://oauth2.googleapis.com/token

Polar Configuration

# Polar payment integration
POLAR_ACCESS_TOKEN=your_polar_token_here
POLAR_SUCCESS_URL=http://localhost:3000/success?checkout_id={CHECKOUT_ID}

Optional Services

# Hotjar Analytics
NEXT_PUBLIC_HOTJAR_ID=your_hotjar_id

# Sentry Error Tracking
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn

Environment Variables Reference

Variable	Required	Type	Description
NEXT_PUBLIC_API_URL	✅	URL	Main backend API endpoint
NEXT_PUBLIC_NEO4J_URL	✅	URL	Neo4j database API
NEXT_PUBLIC_SSE_URL	✅	URL	Server-Sent Events endpoint
NEXT_PUBLIC_CRDT_HOCUSPOCUS_URL	✅	WebSocket	CRDT sync server
NEXT_PUBLIC_AI_API_URL	✅	URL	AI service endpoint
GOOGLE_CLIENT_ID	✅	String	OAuth client ID
GOOGLE_CLIENT_SECRET	✅	String	OAuth client secret
GOOGLE_REDIRECT_URI	✅	URL	OAuth redirect URL
NEXT_PUBLIC_HOTJAR_ID	❌	Number	Analytics ID

🔒 Security Note: Never commit .env.local to version control. Add it to .gitignore.

---

Step 4: Verify Backend Services

Ensure all required backend services are running:

# Check Neo4j
curl http://localhost:8000/health

# Check API Server
curl http://localhost:8001/health

# Check SSE Service
curl http://localhost:8002/health

# Check Hocuspocus
curl http://localhost:8003/health

# Check AI API
curl http://localhost:8004/health

Expected response: 200 OK or similar health check response.

⚠️ Warning: The development server won't start properly if backend services aren't running.

---

Step 5: Start Development Server

# Start development server
bun dev

# Server will run on http://localhost:3000

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

---

Step 6: Verify Setup

Check Installation

1. Open Application: Navigate to http://localhost:3000
2. Check Console: Look for no errors in browser console
3. Test API Connection: Navigate to dashboard (if authenticated)

Run Tests

# Run tests once
bun run test:run

# Expected output: All tests pass with no errors

Run Linter

# Check code quality
bun lint

# Expected output: No linting errors

---

IDE Setup (VSCode Recommended)

Recommended Extensions

{
  "recommendations": [
    "GitHub.copilot",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "unifiedjs.vscode-mdx",
    "ms-vscode.vscode-typescript-next"
  ]
}

VSCode Settings

Create .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[tsx]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

---

Docker Setup (Optional)

Build Docker Image

docker build -t constellation-front:latest .

Run in Docker

docker run -p 3000:3000 \
  --env-file .env.local \
  constellation-front:latest

---

Common Setup Issues

Issue: Port 3000 Already in Use

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

Issue: Dependencies Won't Install

# Clear cache
bun pm cache
rm -rf node_modules bun.lockb

# Reinstall
bun install

Issue: Environment Variables Not Loading

# Verify .env.local exists in root
ls -la .env.local

# Restart dev server
bun dev

Issue: Backend Services Unreachable

# Check backend service status
curl -v http://localhost:8001/health

# Check firewall/network
ping localhost

Issue: TypeScript Errors

# Regenerate types
bun run build

# Clear cache
rm -rf .next
bun dev

---

Development Tools

Useful Commands

# Development
bun dev                       # Start dev server with HMR
bun build                     # Build for production
bun start                     # Start production server

# Testing
bun test                      # Run tests in watch mode
bun test:ui                   # Open Vitest UI
bun test:run                  # Run tests once
bun test:coverage             # Generate coverage report
bun test:coverage-all         # Coverage for all files

# Code Quality
bun lint                      # Run ESLint
bun lint --fix                # Auto-fix linting issues

# Database
bun db:setup                  # Setup database (if available)
bun db:seed                   # Seed sample data (if available)

Development Workflow

# 1. Terminal 1 - Dev Server
bun dev

# 2. Terminal 2 - Tests (Optional)
bun test

# 3. Terminal 3 - Linter (Optional)
bun lint --watch

---

Environment-Specific Setup

Local Development

Already configured in steps above.

Staging Environment

Update .env.staging:

NEXT_PUBLIC_API_URL=https://staging-api.constellation.dev
NEXT_PUBLIC_NEO4J_URL=https://staging-graph.constellation.dev
# ... etc

Deploy:

bun run build:staging
bun start:staging

Production Environment

Update .env.production:

NEXT_PUBLIC_API_URL=https://api.constellation.app
NEXT_PUBLIC_NEO4J_URL=https://graph.constellation.app
# ... etc

---

Troubleshooting

Can't Connect to Backend

1. Verify .env.local URLs are correct
2. Check backend services are running: curl http://localhost:8001/health
3. Check firewall isn't blocking localhost connections
4. Restart dev server: bun dev

Tests Failing

1. Verify all backend services running
2. Clear test cache: rm -rf .vitest
3. Reinstall dependencies: bun install
4. Run with verbose output: bun test --reporter=verbose

Build Errors

1. Clear Next.js cache: rm -rf .next
2. Check TypeScript: bun run build
3. Check no syntax errors: bun lint
4. Verify environment variables: cat .env.local

---

Next Steps

After setup:

1. 📖 Read QUICK_START.md for first project walkthrough
2. 🏗️ Review ARCHITECTURE.md to understand codebase
3. 📝 Check CODE_STYLE_GUIDE.md for coding standards
4. 🧪 Learn TESTING.md for test patterns

---

Getting Help

• 📚 See TROUBLESHOOTING.md for common issues
• ❓ Check FAQ.md for quick answers
• 💬 Ask team members or create an issue

---

Version: 1.0
Last Updated: January 2026