Local Development Setup

This guide walks you through setting up the ƒxyz Network monorepo for local development, including the Cloudflare tunnel for HTTPS access.

Prerequisites: Node.js 22+, pnpm 10+, Docker (for Neo4j), and cloudflared CLI.

Quick Start

Clone and Install

git clone https://github.com/fxyznetwork/fxyz.git fxallapp
cd fxallapp
pnpm install

Configure Environment

cp apps/app/.env.example apps/app/.env.local

Required variables in apps/app/.env.local:

Variable	Description	Where to Get
`NEXT_PUBLIC_PRIVY_APP_ID`	Privy app ID	Privy dashboard
`PRIVY_APP_ID`	Same as above (server-side)	Privy dashboard
`PRIVY_APP_SECRET`	Privy secret key	Privy dashboard
`NEXT_PUBLIC_APP_URL`	`https://dev.fxyz.network`	Fixed value
`NEXT_PUBLIC_API_URL`	`https://dev-api.fxyz.network/api/graphql`	Fixed value
`NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`	Reown project ID (mobile wallet relay)	Reown dashboard

Start Neo4j Database

docker compose -f docker/neo4j/docker-compose.yml up -d

Verify: curl http://localhost:7474

Start Dev Servers + Tunnel

# Terminal 1: Start all apps
npx turbo dev --concurrency 15 --continue

# Terminal 2: Start Cloudflare tunnel (HTTPS access)
cloudflared tunnel run fxyz-dev

Architecture

Port Mapping

App	Port	Local URL	Tunnel URL
app (dashboard)	3000	`http://localhost:3000`	`https://dev.fxyz.network`
web (marketing)	3001	`http://localhost:3001`	-
api (GraphQL)	3002	`http://localhost:3002`	`https://dev-api.fxyz.network`
docs	3004	`http://localhost:3004`	-

Use the tunnel URL for the main app (https://dev.fxyz.network), not localhost:3000. Privy authentication requires HTTPS on a trusted domain.

Cloudflare Tunnel

The tunnel maps HTTPS domains to local ports, solving the Privy HTTPS requirement:

Browser (HTTPS) → Cloudflare Edge → cloudflared tunnel → localhost

Tunnel config: ~/.cloudflared/config.yml

tunnel: fxyz-dev
credentials-file: ~/.cloudflared/[tunnel-id].json
ingress:
  - hostname: dev.fxyz.network
    service: http://localhost:3000
  - hostname: dev-api.fxyz.network
    service: http://localhost:3002
  - service: http_status:404

DNS CNAMEs for dev.fxyz.network and dev-api.fxyz.network point to [tunnel-id].cfargotunnel.com in Cloudflare (proxied).

Monorepo Structure

fxallapp/
├── apps/
│   ├── app/          # Main dashboard (Next.js 16, port 3000)
│   ├── api/          # GraphQL API (Next.js 16, port 3002)
│   ├── web/          # Marketing website (port 3001)
│   ├── docs/         # Documentation - Fumadocs (port 3004)
│   └── email/        # Email templates (React Email)
├── packages/
│   ├── auth/         # Privy v3 authentication
│   ├── design-system/ # shadcn/ui components
│   ├── graphql/      # Apollo Client + schema
│   ├── neo4j/        # Neo4j client, services, migrations
│   ├── contexts/     # React context providers
│   ├── visualization/ # 3D/graph visualization
│   ├── solana/       # Solana blockchain integration
│   ├── types/        # Shared TypeScript types
│   └── trading/      # Market-routing and engine package
├── patches/          # pnpm patches
└── docker/           # Docker Compose files

Environment Variables

Required

Variable	Description
`NEO4J_URI`	Neo4j connection (`bolt://localhost:7687`)
`NEO4J_USER`	Neo4j username
`NEO4J_PASSWORD`	Neo4j password
`PRIVY_APP_ID`	Privy application ID
`PRIVY_APP_SECRET`	Privy secret key
`NEXT_PUBLIC_PRIVY_APP_ID`	Client-side Privy app ID
`NEXT_PUBLIC_APP_URL`	`https://dev.fxyz.network`
`NEXT_PUBLIC_API_URL`	`https://dev-api.fxyz.network/api/graphql`

Optional

Variable	Description	Default
`CLUSTER_ENV`	Solana cluster	`devnet`
`HELIUS_API_KEY`	Helius RPC key	-
`BRIDGE_API_KEY`	Bridge.xyz fiat rails	-
`RWA_API_KEY`	RWA.xyz API	-
`STALWART_API_URL`	Email server URL	Gracefully skipped
`STALWART_API_TOKEN`	Email server token	Gracefully skipped

Missing optional vars (Stalwart, Bridge, RWA) will log warnings but won't crash the app.

Development Commands

# Start all apps (via Turbo)
npx turbo dev --concurrency 15 --continue

# Build all packages
pnpm build

# Run specific app
pnpm --filter @repo/app dev
pnpm --filter @repo/api dev

# Type check
pnpm typecheck

# Lint
pnpm lint

Troubleshooting

Port Conflicts

# Find what's using a port
ss -tlnp | grep :3000

# Kill stale Next.js servers
kill $(lsof -ti:3000,3002)

Privy Not Working

Ensure you're accessing via https://dev.fxyz.network (not localhost)
Verify NEXT_PUBLIC_PRIVY_APP_ID matches your Privy dashboard
Check that dev.fxyz.network is whitelisted in Privy's allowed origins

Tunnel Not Connecting

# Check tunnel status
cloudflared tunnel info fxyz-dev

# Restart tunnel
cloudflared tunnel run fxyz-dev

# Verify DNS
dig dev.fxyz.network

API Returns 500

Check Neo4j is running: curl http://localhost:7474
Check API logs in the npx turbo dev terminal output
Missing env vars show as warnings in the API startup logs

Local Development Setup

On this page