Set up a local development environment for Evolution API Lite with hot reloading and debugging capabilities

Development Setup Guide

This guide walks you through setting up a local development environment for Evolution API Lite. You'll learn how to run the project locally for development, testing, and contribution.

Prerequisites

Before starting, ensure you have:

Node.js v20.10.0 or higher (Download here)
npm (comes with Node.js)
Git for version control
Docker & Docker Compose (optional, for database services)
A code editor (VS Code, WebStorm, etc.)

The project includes an automated installation script that can handle Node.js setup for you, but manual installation gives you more control. For production deployment, see our Quickstart Guide using Docker.

Setup Methods

Choose your preferred setup method:

The project includes a local_install.sh script that automates the entire setup process.

Quick Start

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

chmod +x local_install.sh
./local_install.sh -dev

The script will:

Install NVM (Node Version Manager) if not present
Install Node.js v20.10.0
Install project dependencies
Set up the database
Start the development server

The script uses .env.example as a template. After the first run, customize your .env file:

cp .env.example .env
# Edit .env with your preferred settings

Script Options

Development mode: ./local_install.sh -dev (starts with hot reloading)
Production mode: ./local_install.sh (builds and starts production server)

For more control over the setup process, follow these manual steps.

Step-by-Step Manual Setup

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

npm install

If you encounter permission errors, avoid using sudo. Instead, configure npm to use a different directory or use a Node version manager like NVM.

cp .env.example .env

Edit the .env file with your development settings:

# Development server configuration
SERVER_URL=http://localhost:8080
SERVER_PORT=8080

# Database (you can use Docker or local PostgreSQL)
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://user:pass@localhost:5432/evolution?schema=public'

# Development API key
AUTHENTICATION_API_KEY=dev-api-key-12345

# Enable detailed logging for development
LOG_LEVEL=ERROR,WARN,DEBUG,INFO,LOG,VERBOSE,DARK,WEBHOOKS,WEBSOCKET
LOG_COLOR=true
LOG_BAILEYS=debug

Generate Prisma client and deploy migrations:

npm run db:generate
npm run db:deploy

The db:generate and db:deploy commands automatically detect your DATABASE_PROVIDER setting and use the appropriate schema file.

npm run dev:server

This starts the server with:

Hot reloading on file changes
TypeScript compilation
Detailed logging

Development with Docker

For a containerized development environment that closely matches production:

Using Docker Compose for Development

docker-compose -f docker-compose.dev.yaml build

This builds a local Docker image with your current code.

bash docker-compose -f docker-compose.dev.yaml up -d

The development compose file only includes the API service. You may want to add database services from the main docker-compose.yaml.

docker-compose -f docker-compose.dev.yaml logs -f api

Hybrid Development Setup

Many developers prefer running the API locally while using Docker for supporting services:

# Start only database services
docker-compose up -d postgres redis

# Run the API locally
npm run dev:server

This approach provides:

Fast local development with hot reloading
Consistent database and cache services
Easy debugging and IDE integration

Available Scripts

Understanding the available npm scripts helps with development workflow:

Development Workflow

Typical Development Session

# Option 1: Full Docker setup
docker-compose up -d

# Option 2: Hybrid (recommended for development)
docker-compose up -d postgres redis
npm run dev:server

Edit files in the src/ directory. The development server will automatically restart when you save changes.

# Create a test instance
curl -X POST http://localhost:8080/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: dev-api-key-12345" \
  -d '{"instanceName": "test", "integration": "WHATSAPP_BAILEYS", "qrcode": true}'

Check console output for errors
Use npm run db:studio to inspect database
Enable verbose logging in .env

Database Development

When working with database changes:

# Make changes to prisma/postgresql-schema.prisma or prisma/mysql-schema.prisma

# Generate new migration
npm run db:migrate:dev

# The migration will be automatically applied and copied to the appropriate migrations folder

IDE Configuration

VS Code Setup

Create .vscode/settings.json for optimal development experience:

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}

Recommended Extensions

TypeScript Importer - Auto import management
ESLint - Code linting
Prettier - Code formatting
Prisma - Database schema support
Docker - Container management

Troubleshooting

Common Development Issues

Port Already in Use

Find and fix port conflicts:

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or change the port in .env
SERVER_PORT=8081

Database Connection Errors

Troubleshoot database issues:

# Check if PostgreSQL is running
docker-compose ps postgres

# View database logs
docker-compose logs postgres

# Reset database
docker-compose down -v
docker-compose up -d postgres
npm run db:deploy

TypeScript Compilation Errors

Reset TypeScript environment:

# Clear TypeScript cache
rm -rf dist/

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Regenerate Prisma client
npm run db:generate

Hot Reloading Not Working
- Ensure you're using npm run dev:server
- Check file permissions in the project directory
- Try restarting the development server
- Verify your editor isn't interfering with file watching

Getting Help

If you encounter issues during development:

Check the logs: Look for error messages in the console output
Review the documentation: Ensure you're following the correct procedures
Search existing issues: Check the GitHub issues
Join the community: Get help in our Discord or WhatsApp group

🚀 Ready to develop! You now have a complete development environment for Evolution API Lite. Start building amazing WhatsApp integrations!

Development Setup Guide

Development Scripts

Database Scripts

Code Quality Scripts

On this page