Local Development

Get the Vezta stack running on your machine.

Vezta does not run a local Postgres or Redis by default. The frontend is developed locally and points at the staging backend (staging.vezta.io) for full data. Backend code changes are deployed to the staging VM via CI/CD; running a local backend is rare and usually only needed for unit/E2E tests.

Prerequisites

Tool	Version	Purpose
Node.js	20+	Runtime for all subprojects (CI uses 20)
pnpm	10+	Package manager (no root workspace -- each subproject is independent)
Git	Latest	Source control
Docker	Optional	Only needed if you spin up a local backend

Repo Layout

The root is not a pnpm workspace. Each subproject has its own node_modules and pnpm-lock.yaml.

vezta/
├── vezta-fe/      # Frontend (Next.js 16) — port 3000
├── vezta-be/      # Backend (NestJS) — port 3001
├── vezta-mobile/  # Mobile (Expo) — designs only, not yet implemented
├── vezta-docs/    # This documentation site
└── plans/         # Implementation plans

Frontend Setup (most common)

Clone the repo

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

Install dependencies

pnpm install

Configure environment

Create .env.local:

# Point at staging backend so you have full data
NEXT_PUBLIC_API_URL=https://staging.vezta.io/api/v1
NEXT_PUBLIC_WS_URL=wss://staging.vezta.io
BACKEND_URL=https://staging.vezta.io

NEXT_PUBLIC_GOOGLE_CLIENT_ID=<your-client-id>

NEXT_PUBLIC_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
NEXT_PUBLIC_SOLANA_NETWORK=mainnet-beta

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=<your-id>

Run dev server

pnpm dev

Frontend on port 3000. pnpm dev uses Turbopack. pnpm build uses webpack (required for WASM wallet-lib compatibility) -- do not mix them.

Backend Setup (rare)

Most backend changes are made on the staging VM via CI/CD. Run a local backend only when you really need it (unit/E2E test development, debugging an API change before pushing).

Bring your own Postgres + Redis

docker run -d --name vezta-pg \
  -e POSTGRES_USER=vezta \
  -e POSTGRES_PASSWORD=vezta \
  -e POSTGRES_DB=vezta \
  -p 5432:5432 postgres:17

docker run -d --name vezta-redis \
  -p 6379:6379 redis:7

Configure `.env`

DATABASE_URL=postgresql://vezta:vezta@localhost:5432/vezta
DIRECT_URL=postgresql://vezta:vezta@localhost:5432/vezta
JWT_SECRET=local-dev-secret
JWT_REFRESH_SECRET=local-dev-refresh-secret
REDIS_HOST=localhost
REDIS_PORT=6379
FRONTEND_URL=http://localhost:3000
NODE_ENV=development

NODE_ENV config validation only accepts development or production. Using staging will fail at startup.

Migrate + run

cd vezta-be
pnpm install
pnpm prisma:generate
pnpm prisma:migrate
pnpm start:dev

Backend on port 3001. Swagger UI at http://localhost:3001/docs (disabled in production via NODE_ENV=production). The startup hook also writes openapi.json to the project root.

Never run prisma migrate dev against staging or production. Migrations are run via CI/CD on the VM. Locally, prisma migrate dev only touches your local DB.

Verifying the Setup

Frontend: http://localhost:3000
Frontend → staging API: open the network tab, verify requests go to staging.vezta.io/api/v1
Local backend (if running): http://localhost:3001/api/v1/health
Local Swagger: http://localhost:3001/docs
Local Prisma Studio: cd vezta-be && pnpm prisma:studio

Quick Reference

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

# Backend (only when running locally)
cd vezta-be && pnpm start:dev       # Dev server (port 3001)
cd vezta-be && pnpm test            # Jest unit
cd vezta-be && pnpm test:e2e        # E2E (--runInBand, needs DB+Redis)
cd vezta-be && pnpm prisma:migrate
cd vezta-be && pnpm prisma:studio
cd vezta-be && pnpm export:openapi

On this page