PiggyBack
Deploy Now

Contributing

Thanks for your interest in contributing to PiggyBack! This guide will help you get started.

Getting Started

1

Fork & Clone

terminal
git clone https://github.com/<your-username>/PiggyBack.git
cd PiggyBack
npm install
2

Set Up Environment Variables

terminal
cp .env.local.example .env.local

Fill in your Supabase project URL, anon key, and a 32-character encryption key. See the README for details.

3

Set Up the Database

Apply the migrations in supabase/migrations/ to your Supabase project using the SQL editor or the Supabase CLI.

4

Enable Git Hooks

terminal
git config core.hooksPath .githooks
This enables the pre-commit hook that uses gitleaks to prevent accidentally committing secrets. Install it with brew install gitleaks.
5

Start the Dev Server

terminal
npm run dev

The app runs at http://localhost:3005.

Development Workflow

  1. Create a feature branch from main: git checkout -b feature/your-feature
  2. Make your changes
  3. Run linting and tests: npm run lint and npm run test:run
  4. Commit with a descriptive message
  5. Push and open a Pull Request against main

Code Standards

  • •TypeScript — strict mode, no any unless unavoidable
  • •Server Components by default — only use "use client" when interactivity is needed
  • •Naming — PascalCase for components, camelCase for functions/variables, kebab-case for files
  • •Tests required — new features and bug fixes should include tests (Vitest)
  • •RLS for new tables — every user-facing table must have Row Level Security policies
  • •No hardcoded secrets — use environment variables for all credentials

Project Structure

project
src/
  app/           # Next.js App Router (34 pages, 54 API routes)
  components/    # React components by feature domain (205 files)
  lib/           # Utilities and business logic
  lib/__tests__/ # Vitest test files (43 files, 722+ tests)
  hooks/         # Custom React hooks
  types/         # TypeScript type definitions
  utils/         # Supabase client setup
supabase/
  migrations/    # SQL migration files

Database Changes

  • •Create a new migration file in supabase/migrations/ with the next sequential number
  • •Include both the schema change and any necessary RLS policies
  • •Test the migration against a fresh Supabase project if possible

Testing

terminal
npm test          # Watch mode
npm run test:run  # Single run

Tests use Vitest (43 test files, 722+ tests). Test files live in src/lib/__tests__/ and cover:

  • •Budget calculations (zero-based, shared budgets, period helpers, income frequency)
  • •Investment logic (price APIs, portfolio aggregation, FIRE calculations)
  • •Expense projections and matching
  • •AI tool definitions
When adding new pure utility functions, create corresponding test files in src/lib/__tests__/.

Up Bank API

This app integrates with the Up Bank API. Per Up's acceptable use policy, the API is for personal use only. Each contributor should use their own personal access token for development.

Questions?

Open an issue — happy to help!