Development Environment Setup

Comprehensive instructions for establishing a local development environment for CoW Protocol’s Backend For Frontend (BFF) services, which uses an NX monorepo architecture.

Prerequisites

The setup requires three foundational tools:

Node.js 20.x - Install via nvm:
nvm install 20 nvm use 20
Yarn - Install globally as the package manager:
npm install -g yarn
Docker - Required for running databases, message queues, and other containerized services

Initial Setup

Clone and Install

# Clone the repository
git clone <repository-url>
cd bff

# Install dependencies
yarn install

The installation automatically generates TypeScript types through a postinstall hook.

Environment Configuration

# Copy the example environment file
cp .env.example .env
cp .env.example .env.docker

Configure the following in your .env file:

RPC URLs for blockchain networks (Ethereum mainnet, Gnosis Chain, Arbitrum)
Database credentials for PostgreSQL
Optional: Redis and RabbitMQ settings

Use .env for running services locally via NX commands, and .env.docker when running services through Docker Compose.

Infrastructure Services

Docker Compose manages the project’s infrastructure:

# Start all infrastructure services
yarn compose:up

# Or start individual components
docker-compose up -d db      # PostgreSQL
docker-compose up -d redis   # Redis cache
docker-compose up -d queue   # RabbitMQ

Database Migrations

After the database service starts, run migrations:

yarn migration:run

Development Workflow

Starting Services

# API server (localhost:1500)
yarn start

# Notification producer
yarn producer

# Telegram consumer
yarn telegram

NX enables running specific services:

nx run <app-name>:start

Project Architecture

The monorepo organizes code into:

Applications (`/apps/`)

API - Main HTTP API server
Telegram - Telegram bot consumer
TWAP - Time-weighted average price service
Notification Producer - Blockchain event monitor

Shared Libraries (`/libs/`)

Repositories - Data access layer
Services - Business logic
Shared - Common utilities and types
Notifications - Notification templates
Smart Contract ABIs - Contract interfaces

TypeScript Path Aliases

The project uses TypeScript path aliases for module imports:

import { logger } from '@cowprotocol/shared';
import { UsdRepository } from '@cowprotocol/repositories';
import { SlippageService } from '@cowprotocol/services';

Common Issues

TypeORM Driver Error

If you encounter pg package resolution errors:

yarn add pg

Port Conflicts

Check for existing processes on the required ports:

lsof -i :5432  # PostgreSQL
lsof -i :5672  # RabbitMQ
lsof -i :6379  # Redis

Docker Container Failures

For persistent Docker issues, perform a full reset:

docker-compose down -v
docker-compose up -d

Useful Commands

# Run tests
yarn test

# Run linter
yarn lint

# Build a specific service
yarn build api

# Run NX tasks for a project
nx run api:test
nx run api:lint
nx run api:build

​Development Environment Setup

​Prerequisites

​Initial Setup

​Clone and Install

​Environment Configuration

​Infrastructure Services

​Database Migrations

​Development Workflow

​Starting Services

​Project Architecture

​Applications (/apps/)

​Shared Libraries (/libs/)

​TypeScript Path Aliases

​Common Issues

​TypeORM Driver Error

​Port Conflicts

​Docker Container Failures

​Useful Commands