Getting Started

Prerequisites

Before you begin, ensure you have the following installed on your machine:

Required Software

Verify Installation

Check your installed versions:

node --version  # Should be >= 20.12.2
pnpm --version  # Should be 9.1.0
git --version   # Any recent version

Installing Node.js

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20.12.2
nvm install 20.12.2
nvm use 20.12.2

Installing pnpm

Clone the Repository

Clone the repository from GitHub:

git clone https://github.com/venture-alaska-sierra/frontend-monorepo.git
cd frontend-monorepo

Install Dependencies

The monorepo uses pnpm workspaces for efficient dependency management:

pnpm install

This command will:

• Install all dependencies for the root workspace
• Install dependencies for all apps and packages
• Set up git hooks with Husky
• Run manypkg check to ensure workspace integrity

Environment Variables

Web Application

The main web application requires environment variables for various integrations. Create a .env.local file in apps/web/:

cd apps/web
cp .env.example .env.local

Edit .env.local with your configuration:

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_LOG_LEVEL=debug
NEXT_PUBLIC_AUTH_STRATEGY=clerk

# API Configuration
NEXT_PUBLIC_API_URL=https://api.odysee.ai

# Authentication (Clerk)
CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxx
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxx

# Supabase (if used)
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=xxxxxxxxxxxxx

# Mapbox (for map features)
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.xxxxxxxxxx

# Google Tag Manager (optional)
NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX

Environment Variable Categories

Required Variables

These are essential for the application to run:

• NEXT_PUBLIC_APP_URL: Your application URL
• NEXT_PUBLIC_API_URL: Backend API endpoint
• NEXT_PUBLIC_AUTH_STRATEGY: Authentication provider (clerk, auth0, or cognito)
• Provider-specific auth keys (Clerk, Auth0, or Cognito)

Optional Variables

These enable specific features:

• NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN: Map functionality in guest disruptions
• NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID: Analytics tracking
• NEXT_PUBLIC_SUPABASE_*: If using Supabase features

Development Variables

• NEXT_PUBLIC_LOG_LEVEL: Control console logging (debug, info, warn, error)
• TEMP_ADMIN_EMAIL / TEMP_ADMIN_PASSWORD: Development admin credentials

Start Development Server

Run All Applications

Start all applications in the monorepo simultaneously:

pnpm dev

This starts:

• Web App: http://localhost:3000
• Storybook: http://localhost:6006
• Docs: http://localhost:3001

Run Specific Application

Start only the application you're working on:

# Web application only
cd apps/web
pnpm dev

# Storybook only
cd apps/storybook
pnpm dev

# Documentation only
cd apps/docs
pnpm dev

Verify Setup

Once the development server is running, verify your setup:

1. Web Application: Open http://localhost:3000

   • You should see the login page
   • Check browser console for errors

2. Storybook: Open http://localhost:6006

   • Browse the component library
   • Verify components render correctly

3. Documentation: Open http://localhost:3001

   • You should see this documentation site

Project Structure Overview

Common Development Commands

Building

# Build all applications
pnpm build

# Build specific app
cd apps/web
pnpm build

Linting & Formatting

# Lint all workspaces
pnpm lint

# Lint and auto-fix issues
pnpm lint:fix

# Format code with Prettier
pnpm format

# Check formatting without making changes
pnpm format:check

Type Checking

# Type check all workspaces
pnpm typecheck

# Type check specific app
cd apps/web
pnpm typecheck

Testing

# Run tests (web app)
cd apps/web
pnpm test

# Run Storybook tests
cd apps/storybook
pnpm test

# Run Storybook tests with UI
cd apps/storybook
pnpm test:ui

Component Generation

Generate a new UI component using Turborepo generators:

pnpm run generate:component

You'll be prompted for:

1. Component name: e.g., "Button", "Card"
2. Component role: e.g., "inputs", "layout", "navigation"

This creates:

packages/ui/components/ui/[role]/[component-name]/
├── [component-name].tsx
└── index.tsx

Git Hooks

Husky is configured to run automatic checks:

pre-commit

• Runs ESLint on staged files
• Formats code with Prettier
• Type checks modified files

commit-msg

• Validates commit messages follow Conventional Commits

pre-push

• Runs full test suite
• Ensures builds succeed

Turborepo Remote Caching

Enable remote caching to speed up builds across your team:

# Login to Vercel
pnpm dlx turbo login

# Link the project
pnpm dlx turbo link

This allows sharing build cache across your team, significantly speeding up CI/CD and local builds.

Troubleshooting

Next Steps

Now that your environment is set up:

1. Read the Contributing Guide to understand our workflow
2. Explore the Architecture to understand the codebase
3. Browse components in Storybook
4. Start building!

Additional Resources

• Next.js Documentation
• Turborepo Documentation
• pnpm Documentation
• Material-UI Documentation

Having issues? Check the Troubleshooting section above or reach out to the engineering team.