Quickstart Guide

Get Your Finance App up and running on your local machine in just a few steps. This guide will take you from zero to a fully functioning API.

Estimated time: 10-15 minutes

Prerequisites

Before you begin, make sure you have:

Node.js v18+ installed (download here)
Git installed
A Supabase account (free tier is fine - sign up here)
A terminal/command line interface

Check Node.js version

Verify you have Node.js v18 or higher installed:

node --version
# Should output v18.0.0 or higher

If you need to install or update Node.js, visit nodejs.org

Install pnpm

Install pnpm globally - it’s a faster, more efficient package manager:

npm install -g pnpm

Verify the installation:

pnpm --version
# Should output 8.x.x or higher

Why pnpm? It’s faster than npm, saves disk space, and has built-in monorepo support.

Clone the repository

Clone the project to your local machine:

git clone https://github.com/RoAriel/your-finance-app.git
cd your-finance-app

Explore the project structure:

ls -la
# You should see: apps/, docs/, package.json, pnpm-workspace.yaml

Set up Supabase

Supabase provides free PostgreSQL hosting. Set it up:

Go to supabase.com and sign in
Click “New Project”
Fill in the details:
- Name: your-finance-app
- Database Password: Choose a strong password and save it
- Region: Select the closest to you
- Plan: Free
Click “Create new project” and wait ~2 minutes

Once created, get your connection strings:

Go to Settings → Database
Find Connection string section
Select URI mode
Copy both connection strings:
- Transaction mode (port 6543) - for application queries
- Session mode (port 5432) - for migrations

Keep your database password secure! Never commit it to version control.

Configure environment variables

Copy the example environment file and edit it:

cp apps/backend/.env.example apps/backend/.env

Open apps/backend/.env in your editor and update these values:

# Transaction mode (port 6543) - for queries
DATABASE_URL="postgresql://postgres.xxxxx:[email protected]:6543/postgres?pgbouncer=true"

# Session mode (port 5432) - for migrations
DIRECT_URL="postgresql://postgres.xxxxx:[email protected]:5432/postgres"

# Generate a secure JWT secret
JWT_SECRET="your-secret-key-change-this"

# Token expiration time
JWT_EXPIRES_IN="7d"

Generate a secure JWT secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Copy the output and use it as your JWT_SECRET.

Replace xxxxx with your Supabase project ID and YOUR_PASSWORD with your database password.

Install dependencies

Install all project dependencies:

pnpm install

This will install dependencies for the entire monorepo. It typically takes 1-3 minutes depending on your internet connection.

pnpm creates symlinks between workspace packages, making installation faster and more efficient.

Run database migrations

Set up your database schema by running migrations:

cd apps/backend
npx prisma generate
npx prisma migrate deploy

What this does:

prisma generate creates the TypeScript Prisma Client
prisma migrate deploy creates the database tables

You should see output like:

Applying migration `20260104185727_init`
Applying migration `20260109000725_add_transactions_and_categories`

The following migration(s) have been applied:

migrations/
  └─ 20260104185727_init/
  └─ 20260109000725_add_transactions_and_categories/

Verify in Supabase:

Go to your Supabase project → Table Editor
You should see tables: users, transactions, categories

Start the development server

Launch the application:

# From the backend directory:
pnpm run start:dev

# Or from the project root:
cd ../..
pnpm dev:backend

You should see:

[Nest] LOG [NestFactory] Starting Nest application...
[Nest] LOG [InstanceLoader] PrismaModule dependencies initialized
[Nest] LOG [InstanceLoader] AuthModule dependencies initialized
[Nest] LOG [InstanceLoader] TransactionsModule dependencies initialized
[Nest] LOG [RoutesResolver] AuthController {/auth}:
[Nest] LOG [RouterExplorer] Mapped {/auth/register, POST} route
[Nest] LOG [RouterExplorer] Mapped {/auth/login, POST} route
[Nest] LOG [NestApplication] Nest application successfully started

The server is now running at http://localhost:3000

Test the API

Verify everything works by testing the endpoints.

Test the health check:

Open your browser and visit:

http://localhost:3000

You should see: "Hello World!"

Register a new user:

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "name": "Test User"
  }'

Expected response:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "Test User",
    "createdAt": "2026-03-04T10:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Create a transaction:

Save the token from the registration response:

TOKEN="your-token-here"

curl -X POST http://localhost:3000/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "type": "expense",
    "amount": 500,
    "description": "Coffee",
    "currency": "USD"
  }'

Expected response:

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "type": "expense",
  "amount": 500,
  "description": "Coffee",
  "currency": "USD",
  "createdAt": "2026-03-04T10:35:00.000Z"
}

Check your balance:

curl http://localhost:3000/transactions/balance \
  -H "Authorization: Bearer $TOKEN"

Expected response:

{
  "income": 0,
  "expense": 500,
  "balance": -500
}

You can also use tools like Postman or Thunder Client (VS Code extension) to test the API.

What’s Next?

Congratulations! You now have Your Finance App running locally. Here’s what to explore next:

Setup Guide

Learn detailed configuration and troubleshooting

API Reference

Explore all available endpoints

Architecture

Understand how the application is structured

Database Schema

Learn about the data models

Useful Commands

Here are some common commands you’ll use during development:

# From project root
pnpm dev:backend

# Or from apps/backend
pnpm run start:dev

Troubleshooting

Error: Cannot find module '@nestjs/core'

Solution: Dependencies weren’t installed properly.

cd apps/backend
pnpm install

Error: Environment variable not found: DATABASE_URL

Solution: The .env file is missing or incorrect.

Make sure .env exists in apps/backend/
Verify it contains DATABASE_URL and DIRECT_URL
Restart the server

Error: connect ECONNREFUSED or connection timeout

Solution: Database connection issue.

Verify your Supabase connection strings are correct
Check that your database password matches
Ensure there are no extra spaces in .env
Confirm your Supabase project is active

Error: Port 3000 is already in use

Solution: Another process is using port 3000.Find and kill the process:

# On Mac/Linux
lsof -i :3000
kill -9 <PID>

# On Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Or change the port in apps/backend/src/main.ts:

await app.listen(3001); // Use a different port

Quick Reference

Project Structure

your-finance-app/
├── apps/backend/          # Main application
│   ├── src/
│   │   ├── auth/          # Authentication module
│   │   ├── transactions/  # Transactions module
│   │   └── prisma/        # Database service
│   ├── prisma/
│   │   ├── schema.prisma  # Database schema
│   │   └── migrations/    # Migration files
│   └── .env               # Environment variables
└── docs/                  # Documentation

Available Scripts

Command	Description
`pnpm dev:backend`	Start development server
`pnpm run build`	Build for production
`pnpm run start:prod`	Run production build
`pnpm run format`	Format code with Prettier
`pnpm run lint`	Lint code with ESLint
`npx prisma studio`	Open database GUI
`npx prisma migrate dev`	Create new migration

Need More Help?

For detailed setup instructions, configuration options, and troubleshooting, check out the Setup Guide.

Detailed Setup Guide

Complete installation guide with advanced configuration

Get Started

Architecture

Core Features

Advanced

Quickstart

Quickstart Guide

Prerequisites

Test the health check:

Register a new user:

Create a transaction:

Check your balance:

What’s Next?

Setup Guide

API Reference

Architecture

Database Schema

Useful Commands

Troubleshooting

Quick Reference

Project Structure

Available Scripts

Need More Help?

Detailed Setup Guide

Build docs developers (and LLMs) love

Get Started

Architecture

Core Features

Advanced

​Quickstart Guide

​Prerequisites

​Test the health check:

​Register a new user:

​Create a transaction:

​Check your balance:

​What’s Next?

Setup Guide

API Reference

Architecture

Database Schema

​Useful Commands

​Troubleshooting

​Quick Reference

​Project Structure

​Available Scripts

​Need More Help?

Detailed Setup Guide

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Test the health check:

Register a new user:

Create a transaction:

Check your balance:

What’s Next?

Useful Commands

Troubleshooting

Quick Reference

Project Structure

Available Scripts

Need More Help?