Development Setup Guide

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.)

Note

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:

Automated Setup (Recommended)

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

Quick Start

1. Clone the Repository

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

2. Run the Installation Script

   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

3. Configure Environment

   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)

Manual Setup

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

Step-by-Step Manual Setup

1. Clone and Navigate

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

2. Install Node.js Dependencies

   npm install

   Caution

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

3. Environment Configuration

   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

4. Database Setup

   Generate Prisma client and deploy migrations:

   npm run db:generate
   npm run db:deploy

   Note

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

5. Start Development Server

   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

1. Build Development Image

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

   This builds a local Docker image with your current code.

2. Start Development Environment

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

   Note

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

3. View Logs

   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 Scripts

• npm run dev:server - Start development server with hot reloading
• npm run start - Start server without building (development mode)
• npm run build - Build the project for production
• npm run start:prod - Start production server

Database Scripts

• npm run db:generate - Generate Prisma client
• npm run db:deploy - Deploy database migrations
• npm run db:studio - Open Prisma Studio (database GUI)
• npm run db:migrate:dev - Create and apply new migration

Code Quality Scripts

• npm run lint - Run ESLint and fix issues
• npm run lint:check - Check for linting issues without fixing
• npm run test - Run test suite

Development Workflow

Typical Development Session

1. Start Services

   # 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

2. Make Changes

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

3. Test 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}'

4. Debug Issues

   • 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:

1. Check the logs: Look for error messages in the console output
2. Review the documentation: Ensure you’re following the correct procedures
3. Search existing issues: Check the GitHub issues
4. 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!