Installation & Setup

This comprehensive guide walks you through installing and configuring BudgetView on your local machine for development or self-hosting.

Overview

BudgetView is a modern full-stack application that requires:

Node.js runtime for the Next.js server
Supabase account for authentication and PostgreSQL database
Environment variables to connect to your Supabase project

Installation takes approximately 10-15 minutes, including Supabase project setup.

Prerequisites

Before you begin, ensure your system meets these requirements:

System Requirements

Node.js

Version: 18.x or higher (25.x recommended)Verify installation:

node -v

npm

Version: Automatically installed with Node.jsVerify installation:

npm -v

Git

Required for: Cloning the repositoryVerify installation:

git --version

Text Editor

Recommended: VS Code, Cursor, or any code editorFor editing .env.local configuration

Operating System Support

macOS
Windows
Linux

Supported Versions: macOS 10.15 (Catalina) or laterInstall Node.js via Homebrew:

brew install node

Supported Distributions: Ubuntu 20.04+, Debian 11+, Fedora 35+Install Node.js via package manager:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

Internet connection required for downloading dependencies and connecting to Supabase cloud services.

Step 1: Clone the Repository

Get the BudgetView source code from GitHub:

git clone https://github.com/Rolando0408/BudgetView-MonySaver-Cheap-Version

Navigate to the project directory:

cd BudgetView-MonySaver-Cheap-Version

If you don’t have Git installed, you can download the repository as a ZIP file from GitHub and extract it.

Step 2: Install Dependencies

BudgetView uses npm to manage its dependencies. Install all required packages:

npm install

This command installs the following key dependencies:

Frontend Dependencies

next (16.0.3) - React framework with App Router
react (19.2.0) - UI library
react-dom (19.2.0) - React DOM rendering
tailwindcss (4.x) - Utility-first CSS framework
lucide-react (0.553.0) - Icon library

UI Component Libraries

@radix-ui/react-dialog - Accessible dialog components
@radix-ui/react-dropdown-menu - Dropdown menus
@radix-ui/react-popover - Popover components
@radix-ui/react-select - Select dropdowns
react-day-picker (9.11.3) - Date picker

Backend & Database

@supabase/supabase-js (2.81.1) - Supabase client for authentication and database

Data Visualization

recharts (3.4.1) - Chart library for dashboard analytics

Utilities

date-fns (4.1.0) - Date manipulation
jspdf (3.0.4) - PDF generation for exports
clsx & tailwind-merge - Conditional CSS class merging

The installation typically takes 2-5 minutes depending on your internet connection.

{
  "dependencies": {
    "@supabase/supabase-js": "^2.81.1",
    "next": "16.0.3",
    "react": "19.2.0",
    "react-dom": "19.2.0",
    "tailwindcss": "^4",
    "recharts": "^3.4.1",
    "date-fns": "^4.1.0",
    "jspdf": "^3.0.4"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19",
    "eslint": "^9",
    "eslint-config-next": "16.0.3"
  }
}

Step 3: Set Up Supabase

BudgetView uses Supabase for:

User authentication (email/password and OAuth)
PostgreSQL database storage
Row Level Security (RLS) for data privacy

Create a Supabase Account

Go to supabase.com
Click “Start your project”
Sign up with GitHub, Google, or email
Verify your email if required

Create a New Project

Click “New Project” in your Supabase dashboard
Fill in the project details:
- Name: BudgetView (or your preferred name)
- Database Password: Generate a strong password and save it securely
- Region: Choose the closest region to your users
- Pricing Plan: Free tier is sufficient for development
Click “Create new project”

Project creation takes 1-2 minutes. You’ll see a loading screen while Supabase provisions your database.

Get Your API Credentials

Once your project is ready:

Navigate to Project Settings (gear icon in the sidebar)
Click “API” under Configuration
Locate these two values:

Project URL:

https://your-project-id.supabase.co

anon/public key (under “Project API keys”):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Keep your service_role key private! Never commit it to version control or expose it in client-side code. BudgetView only uses the anon public key.

Configure Database Tables

BudgetView requires specific database tables and RLS policies. You have two options:

Option A: SQL Editor (Recommended)
Option B: Automatic Migration

Execute the schema creation script in Supabase SQL Editor:

Go to SQL Editor in your Supabase dashboard
Click “New query”
Run the following SQL to create required tables:

-- Create users table (extends Supabase auth.users)
CREATE TABLE IF NOT EXISTS public.usuarios (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create wallets table
CREATE TABLE IF NOT EXISTS public.billeteras (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  usuario_id UUID REFERENCES public.usuarios(id) ON DELETE CASCADE,
  nombre TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create categories table
CREATE TABLE IF NOT EXISTS public.categorias (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  usuario_id UUID REFERENCES public.usuarios(id) ON DELETE CASCADE,
  nombre TEXT NOT NULL,
  tipo TEXT CHECK (tipo IN ('ingreso', 'gasto')),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create transactions table
CREATE TABLE IF NOT EXISTS public.transacciones (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  usuario_id UUID REFERENCES public.usuarios(id) ON DELETE CASCADE,
  billetera_id UUID REFERENCES public.billeteras(id) ON DELETE CASCADE,
  categoria_id UUID REFERENCES public.categorias(id) ON DELETE SET NULL,
  monto NUMERIC(12, 2) NOT NULL,
  tipo TEXT CHECK (tipo IN ('ingreso', 'gasto')),
  descripcion TEXT,
  fecha_transaccion TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create budgets table
CREATE TABLE IF NOT EXISTS public.presupuestos (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  usuario_id UUID REFERENCES public.usuarios(id) ON DELETE CASCADE,
  categoria_id UUID REFERENCES public.categorias(id) ON DELETE CASCADE,
  monto NUMERIC(12, 2) NOT NULL,
  periodo TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE public.billeteras ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.categorias ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.transacciones ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.presupuestos ENABLE ROW LEVEL SECURITY;

-- Create RLS policies
CREATE POLICY "Users can view own wallets" ON public.billeteras
  FOR SELECT USING (auth.uid() = usuario_id);

CREATE POLICY "Users can insert own wallets" ON public.billeteras
  FOR INSERT WITH CHECK (auth.uid() = usuario_id);

CREATE POLICY "Users can update own wallets" ON public.billeteras
  FOR UPDATE USING (auth.uid() = usuario_id);

CREATE POLICY "Users can delete own wallets" ON public.billeteras
  FOR DELETE USING (auth.uid() = usuario_id);

-- Repeat similar policies for categorias, transacciones, and presupuestos

Click “Run” to execute the script

For the complete database schema and RLS policies, refer to the Architecture Documentation.

Step 4: Configure Environment Variables

BudgetView requires environment variables to connect to your Supabase project.

Create .env.local File

In the root directory of your project, create a new file named .env.local:

touch .env.local

Or create it manually in your file explorer.

Add Supabase Credentials

Open .env.local in your text editor and add:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-anon-public-key-here

Replace the values with your actual credentials from Step 3.

Verify Configuration

The Supabase client initialization code:

lib/supabaseClient.ts

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!

export const supabase = createClient(supabaseUrl, supabaseKey)

This code reads your environment variables and creates an authenticated Supabase client.

Environment Variable Reference

Variable	Description	Where to Find	Required
`NEXT_PUBLIC_SUPABASE_URL`	Your Supabase project URL	Project Settings → API → Project URL	✅ Yes
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Anon/public API key	Project Settings → API → anon public key	✅ Yes

Security Best Practices:

Never commit .env.local to version control (it’s in .gitignore by default)
Use the anon public key, NOT the service_role key
Rotate keys immediately if accidentally exposed
Use Supabase RLS policies to protect data, not key secrecy

Step 5: Run the Application

Now you’re ready to start BudgetView!

Development Mode

For local development with hot-reload:

npm run dev

Expected output:

▲ Next.js 16.0.3
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.3s

The development server starts on port 3000 by default. If this port is in use, Next.js will automatically try the next available port (3001, 3002, etc.).

Production Mode

For production deployment:

Build the Application

npm run build

This command:

Compiles TypeScript to JavaScript
Optimizes React components
Generates static pages where possible
Creates production bundles

Expected output:

▲ Next.js 16.0.3

✓ Creating an optimized production build
✓ Compiled successfully
✓ Collecting page data
✓ Generating static pages (12/12)
✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    142 B          87.2 kB
├ ○ /dashboard                           8.2 kB         95.4 kB
├ ○ /dashboard/billeteras                12.1 kB        99.3 kB
└ ○ /dashboard/transacciones             15.3 kB        102.5 kB

○ (Static) prerendered as static content

Start the Production Server

npm start

The application will be available at http://localhost:3000

Custom Port Configuration

To run on a different port:

macOS/Linux
Windows (PowerShell)
Windows (CMD)

PORT=4000 npm run dev

$env:PORT=4000; npm run dev

set PORT=4000 && npm run dev

Verify Installation

Confirm everything is working correctly:

Access the Application

Open your browser and navigate to:

http://localhost:3000

You should see the BudgetView login page.

Test Authentication

Try creating a new account:

Click “Regístrate” (Sign up)
Enter an email and password
Submit the form
Check for the verification email

Or test Google OAuth:

Click “Continúa con Google”
Select your Google account
Verify you’re redirected to the dashboard

Check Database Connection

In your Supabase dashboard:

Go to Database → Tables
Select the usuarios table
Verify your user record appears after signup

If you don’t see database tables, review the SQL schema setup in Step 3.

Troubleshooting

Error: Cannot find module 'next'

Solution: Dependencies not installed.

rm -rf node_modules package-lock.json
npm install

Error: Invalid Supabase URL or key

Cause: Environment variables not set correctly.Solution:

Verify .env.local exists in the project root
Check for typos in variable names (must be exact)
Ensure values are correct from your Supabase dashboard

Restart the dev server after changes:

# Stop server (Ctrl+C), then:
npm run dev

Port 3000 already in use

Solution: Another application is using port 3000.Option A - Use a different port:

PORT=3001 npm run dev

Option B - Find and stop the conflicting process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process

TypeScript errors during build

Solution: Ensure you’re using compatible Node.js and npm versions.

node -v  # Should be 18.x or higher
npm -v   # Should be 9.x or higher

Update if necessary:

npm install -g npm@latest

Supabase connection timeout

Causes:

Network firewall blocking Supabase API
Corporate proxy interfering
Supabase project paused (free tier inactivity)

Solutions:

Check Supabase project status in dashboard
Verify internet connection

Test Supabase connectivity:

curl https://your-project-id.supabase.co

Check for proxy settings that need configuration

Database schema errors

Solution: Re-run the database migration SQL.

Go to Supabase SQL Editor

Delete existing tables (if present):

DROP TABLE IF EXISTS public.presupuestos CASCADE;
DROP TABLE IF EXISTS public.transacciones CASCADE;
DROP TABLE IF EXISTS public.categorias CASCADE;
DROP TABLE IF EXISTS public.billeteras CASCADE;

Re-run the complete schema creation SQL from Step 3

Next Steps

Now that BudgetView is running:

Quickstart Guide

Learn how to create your first wallet and transaction

Feature Documentation

Explore all BudgetView features in detail

API Reference

Understand the database schema and Supabase queries

Deployment Guide

Deploy BudgetView to Vercel, Netlify, or your own server

Additional Resources

Next.js Documentation - Learn about the framework
Supabase Documentation - Database and auth setup
BudgetView GitHub - Source code and issues
Technical Manual - Advanced configuration

Development Scripts Reference

Available npm scripts defined in package.json:

{
  "scripts": {
    "dev": "next dev",           // Start development server with hot-reload
    "build": "next build",       // Create production build
    "start": "next start",       // Start production server
    "lint": "eslint"             // Run ESLint code quality checks
  }
}

Usage examples:

# Development
npm run dev

# Production build and start
npm run build
npm start

# Code quality check
npm run lint

Use npm run dev during development for instant feedback. Only run npm run build when preparing for deployment or testing production behavior.

Get Started

Core Features

User Guide

Technical

Installation & Setup

Overview

Prerequisites

System Requirements

Node.js

npm

Git

Text Editor

Operating System Support

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Supabase

Configure Database Tables

Step 4: Configure Environment Variables

Environment Variable Reference

Step 5: Run the Application

Development Mode

Production Mode

Custom Port Configuration

Verify Installation

Troubleshooting

Next Steps

Quickstart Guide

Feature Documentation

API Reference

Deployment Guide

Additional Resources

Development Scripts Reference

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

Technical

​Overview

​Prerequisites

​System Requirements

Node.js

npm

Git

Text Editor

​Operating System Support

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Set Up Supabase

​Configure Database Tables

​Step 4: Configure Environment Variables

​Environment Variable Reference

​Step 5: Run the Application

​Development Mode

​Production Mode

​Custom Port Configuration

​Verify Installation

​Troubleshooting

​Next Steps

Quickstart Guide

Feature Documentation

API Reference

Deployment Guide

​Additional Resources

​Development Scripts Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

System Requirements

Operating System Support

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Supabase

Configure Database Tables

Step 4: Configure Environment Variables

Environment Variable Reference

Step 5: Run the Application

Development Mode

Production Mode

Custom Port Configuration

Verify Installation

Troubleshooting

Next Steps

Additional Resources

Development Scripts Reference