Finn Logo
Docs

Developer Setup Guide

Get the Finnance development environment running on your machine.

This guide assumes you're setting up for local development. For production deployment, see the Deployment Guide.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (version 20 or higher)
  • Yarn (version 1.22.22 or higher)
  • Python (version 3.11 or higher)
  • Docker (for local Supabase)
  • Git

Optional Tools

  • Expo CLI for mobile development
  • VS Code with recommended extensions
  • ngrok for webhook testing

Quick Start

Get up and running with just four commands:

# 1. Clone the repository
git clone git@github.com:finnance/mono.git
cd mono

# 2. Install all dependencies
yarn install

# 3. Start the Supabase backend (in one terminal)
cd backend/supabase && supabase start

# 4. Start the Next.js web app (in another terminal)
yarn next:dev

The Next.js app will be available at http://localhost:3000

The Supabase dashboard will be available at http://localhost:54323

Detailed Setup

1. Clone and Install

# Clone the repository
git clone git@github.com:finnance/mono.git
cd mono

# Install all workspace dependencies
yarn install

This will install dependencies for all packages in the monorepo.

2. Environment Configuration

Create environment files for each app:

# Next.js app
cp frontend/apps/next/.env.example frontend/apps/next/.env.local

# Expo app
cp frontend/apps/expo/.env.example frontend/apps/expo/.env

# FastAPI
cp backend/fast-api/.env.example backend/fast-api/.env

3. Local Supabase Setup

Start the local Supabase instance:

cd backend/supabase
supabase start

After startup, you'll see credentials like:

API URL: http://127.0.0.1:54321
GraphQL URL: http://127.0.0.1:54321/graphql/v1
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
Studio URL: http://127.0.0.1:54323
Inbucket URL: http://127.0.0.1:54324
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The local credentials are already configured in .env.development.

Supabase Commands

# Start Supabase
supabase start

# Stop Supabase
supabase stop

# Reset database (applies all migrations)
supabase db reset

# View status
supabase status

Running Applications

Next.js Web App

yarn next:dev

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

Expo Mobile App

# Start the Expo development server
yarn expo:start

# Or run on specific platforms
yarn expo:ios      # iOS simulator
yarn expo:android  # Android emulator
yarn expo:web      # Web browser

Scan the QR code with Expo Go on your mobile device.

FastAPI Backend

cd backend/fast-api

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn app.main:app --reload

API available at http://localhost:8000

API docs at http://localhost:8000/docs

Storybook

View and develop components in isolation:

# Next.js Storybook
yarn next:storybook

# Expo Storybook
yarn expo:storybook-web    # Web version
yarn expo:storybook-ios    # iOS version
yarn expo:storybook-android # Android version

Testing

Run All Tests

# Lint all packages
yarn lint

# Format code
yarn format

Next.js Tests

cd frontend/apps/next
yarn test

FastAPI Tests

cd backend/fast-api
pytest

Building for Production

Next.js

yarn next:build

Expo

# Development builds
yarn expo:android-dev-build
yarn expo:ios-dev-build

# Production builds (requires EAS)
eas build --platform ios
eas build --platform android

Webhook Development (Loop Integration)

For local development with Loop messaging, use ngrok:

# Install ngrok
brew install ngrok

# Configure ngrok
ngrok config add-authtoken YOUR_AUTH_TOKEN

# Start ngrok tunnel
ngrok http --domain=your-domain.ngrok-free.app 8000

This exposes your local FastAPI server for webhook testing.

Troubleshooting

Dependency Issues

# Clean yarn cache and reinstall
yarn cache clean
rm -rf node_modules
yarn install

Next.js Issues

If you encounter errors with GlueStack UI adapter:

  1. Check compatibility between Next.js version and GlueStack UI
  2. Update the Next.js configuration in frontend/apps/next/next.config.mjs

Expo Issues

# Clear Metro bundler cache
expo start -c

Supabase Issues

# Reset and restart
supabase stop
supabase start

# Full database reset
supabase db reset

Project Structure

mono/
├── frontend/
│   ├── apps/
│   │   ├── next/          # Next.js web application
│   │   ├── expo/          # Expo mobile application
│   │   ├── admin/         # Admin dashboard
│   │   └── docs/          # Documentation site
│   ├── packages/
│   │   ├── assets/        # Shared assets
│   │   ├── components/    # Shared UI components
│   │   │   ├── common/    # Cross-platform components
│   │   │   └── primitives/ # Base UI components
│   │   ├── modules/       # Feature-based modules
│   │   ├── hooks/         # Shared React hooks
│   │   ├── utils/         # Utility functions
│   │   └── config/        # Configuration files
│   └── package.json       # Workspace configuration
├── backend/
│   ├── fast-api/          # Python FastAPI server
│   ├── supabase/          # Database & Edge Functions
│   └── express-js/        # Express.js (legacy)
└── README.md

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-python.python",
    "ms-python.vscode-pylance"
  ]
}

Next Steps

Was this page helpful?