Quickstart

This guide walks you through setting up the full Vezta development environment on your local machine.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js 22 or later
pnpm (package manager for all subprojects)
Docker and Docker Compose (for PostgreSQL and Redis)
PostgreSQL 17 (runs via Docker)
Redis (runs via Docker)

Clone the Repository

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

Start Infrastructure Services

Launch PostgreSQL and Redis using Docker:

cd vezta-be
docker compose up -d

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

Set Up the Backend

Install dependencies, configure environment variables, and run database migrations:

cd vezta-be
pnpm install
cp .env.example .env

Edit .env with your local values. Required variables:

Variable	Example	Description
`DATABASE_URL`	`postgresql://vezta:vezta@localhost:5432/vezta`	PostgreSQL connection string
`DIRECT_URL`	Same as `DATABASE_URL`	Used by Prisma for migrations (no pgbouncer)
`JWT_SECRET`	Any random string	Signs access tokens
`JWT_REFRESH_SECRET`	Any random string	Signs refresh tokens

Optional variables: REDIS_URL, RESEND_API_KEY, ENCRYPTION_KEY, FRONTEND_URL.

Run migrations and generate the Prisma client:

pnpm prisma:migrate
pnpm prisma:generate

Start the backend dev server:

pnpm start:dev

The backend runs on port 3001. Swagger docs are available at http://localhost:3001/docs.

Set Up the Frontend

In a new terminal:

cd vezta-fe
pnpm install

Create a .env.local file:

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

Generate the API client from the backend's OpenAPI spec:

pnpm generate

Start the frontend dev server:

pnpm dev

The frontend runs on port 3000. Open http://localhost:3000 in your browser.

pnpm dev uses the --webpack flag for WASM compatibility with wallet libraries. pnpm build uses Turbopack without this flag. Do not mix them up.

Set Up the Mobile App (Optional)

In a new terminal:

cd vezta-mobile
pnpm install

Set environment variables:

API_URL=http://localhost:3001/api/v1
WS_URL=ws://localhost:3001

Start on iOS Simulator or Android Emulator:

pnpm ios      # iOS Simulator
pnpm android  # Android Emulator

Verify Everything Works

With all services running, verify the setup:

Backend: Visit http://localhost:3001/docs -- you should see the Swagger UI
Frontend: Visit http://localhost:3000 -- you should see the Vezta landing page
WebSocket: The frontend should connect to the backend's /ws namespace automatically when authenticated
Database: Run pnpm prisma:studio in vezta-be/ to browse the database

Common Commands Reference

Frontend

cd vezta-fe && pnpm dev          # Dev server (port 3000)
cd vezta-fe && pnpm build        # Production build
cd vezta-fe && pnpm test         # Run Vitest unit tests
cd vezta-fe && pnpm generate     # Regenerate API client from OpenAPI
cd vezta-fe && pnpm lint         # ESLint

Backend

cd vezta-be && pnpm start:dev    # Dev server with hot-reload (port 3001)
cd vezta-be && pnpm build        # Compile TypeScript
cd vezta-be && pnpm test         # Jest unit tests
cd vezta-be && pnpm test:e2e     # E2E tests (requires --runInBand)
cd vezta-be && pnpm prisma:migrate   # Run database migrations
cd vezta-be && pnpm prisma:generate  # Regenerate Prisma client
cd vezta-be && pnpm export:openapi   # Export OpenAPI spec

Mobile

cd vezta-mobile && pnpm ios      # iOS Simulator
cd vezta-mobile && pnpm android  # Android Emulator
cd vezta-mobile && pnpm test     # Jest + RNTL
cd vezta-mobile && pnpm tsc      # TypeScript type check

Running a Single Test

# Frontend (Vitest)
cd vezta-fe && pnpm test -- --testPathPattern=navbar

# Backend (Jest)
cd vezta-be && pnpm test -- --testPathPattern=auth

On this page