Local Development

Get the full Vezta stack running on your machine. The monorepo contains three independent subprojects, each with its own dependencies and dev server.

Prerequisites

Before starting, ensure you have the following installed:

Tool	Version	Purpose
Node.js	22+	Runtime for all subprojects
pnpm	10+	Package manager (used across all subprojects)
Docker	Latest	PostgreSQL and Redis containers for the backend
PostgreSQL	17	Primary database (runs in Docker)
Redis	Latest	Caching, BullMQ job queues, WebSocket adapter

You will also need an iOS Simulator (Xcode) or Android Emulator (Android Studio) if you plan to work on the mobile app.

Setup

Clone the Repository

git clone git@github.com:your-org/vezta.git
cd vezta

The repository contains three subprojects: vezta-be/ (backend), vezta-fe/ (frontend), and vezta-mobile/ (mobile app).

Install Dependencies

Run pnpm install in each subproject you plan to work on:

cd vezta-be && pnpm install
cd ../vezta-fe && pnpm install
cd ../vezta-mobile && pnpm install

Configure Environment Variables

Each subproject has a .env.example file. Copy it to .env and fill in the required values.

Backend (vezta-be/.env):

cp .env.example .env

Required variables:

DATABASE_URL=postgresql://vezta:vezta@localhost:5432/vezta
DIRECT_URL=postgresql://vezta:vezta@localhost:5432/vezta
JWT_SECRET=your-jwt-secret-here
JWT_REFRESH_SECRET=your-refresh-secret-here
REDIS_HOST=localhost
REDIS_PORT=6379
FRONTEND_URL=http://localhost:3000

Frontend (vezta-fe/.env):

NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
NEXT_PUBLIC_WS_URL=ws://localhost:3001
OPENAPI_PATH=http://localhost:3001/docs-json

Start Docker Services

Start PostgreSQL and Redis containers:

docker compose up -d

This starts vezta-postgres (port 5432) and vezta-redis (port 6379).

Run Database Migrations

Generate the Prisma client and apply migrations:

cd vezta-be
pnpm prisma:generate
pnpm prisma:migrate

Optionally seed the database with test data:

pnpm prisma:seed

Start the Backend

cd vezta-be && pnpm start:dev

The backend starts on port 3001 with hot-reload. Swagger docs are available at http://localhost:3001/docs. On startup, the backend also exports openapi.json to the project root.

Start the Frontend

cd vezta-fe && pnpm dev

The frontend starts on port 3000. Note that pnpm dev uses the --webpack flag for WASM compatibility with wallet libraries. Production builds (pnpm build) use Turbopack without this flag.

Start the Mobile App (Optional)

cd vezta-mobile && pnpm ios      # iOS Simulator
cd vezta-mobile && pnpm android  # Android Emulator

Verifying the Setup

Once all services are running:

Backend API: http://localhost:3001/api/v1/health
Swagger docs: http://localhost:3001/docs
Frontend: http://localhost:3000
Prisma Studio: cd vezta-be && pnpm prisma:studio

The backend must be running before starting the frontend. The frontend's API client, WebSocket connection, and Kubb code generation all depend on the backend being available at localhost:3001.

Quick Reference

# Backend
cd vezta-be && pnpm start:dev       # Dev server (port 3001)
cd vezta-be && pnpm test            # Unit tests
cd vezta-be && pnpm prisma:studio   # Database GUI

# Frontend
cd vezta-fe && pnpm dev             # Dev server (port 3000)
cd vezta-fe && pnpm test            # Vitest
cd vezta-fe && pnpm generate        # Regenerate API client from OpenAPI

# Mobile
cd vezta-mobile && pnpm ios         # iOS Simulator
cd vezta-mobile && pnpm android     # Android Emulator
cd vezta-mobile && pnpm test        # Jest + RNTL

On this page