Setup Development Environment

Get your local environment ready for building pieces

Prerequisites

Before you start, ensure you have:

• Node.js 18.x or higher
• Bun 1.3.3 or higher (package manager)
• Git for version control
• A code editor (VS Code recommended)

Fork and Clone the Repository

1. Fork the Repository

   Go to the Activepieces GitHub repository and click the “Fork” button in the top right corner.

2. Clone Your Fork

   git clone https://github.com/YOUR_USERNAME/activepieces.git
   cd activepieces
   
3. Add Upstream Remote

   git remote add upstream https://github.com/activepieces/activepieces.git
   

   This allows you to sync with the main repository later.

Install Dependencies

Activepieces uses Bun as the package manager. The setup script will install it automatically:

npm run start

This command will:

1. Install Bun if not already installed
2. Install all project dependencies
3. Start the development environment

The first run may take several minutes as it installs dependencies for all packages.

Development Environment

Once dependencies are installed, you can start the development servers:

Full Stack

Start frontend, backend, and engine together:

npm run dev

This runs:

• GUI: Angular frontend on http://localhost:4200
• API: Backend server on http://localhost:3000
• ENG: Flow execution engine

Frontend Only

Start just the frontend (with API and engine):

npm run dev:frontend

Backend Only

Start just backend and engine (no frontend):

npm run dev:backend

Hot Reloading for Pieces

One of the best features of Activepieces development is hot reloading for pieces. When you make changes to piece code, they’re immediately reflected without restarting the server.

How It Works

1. Start Development Environment

   npm run dev
   
2. Navigate to a Piece

   Pieces are located in packages/pieces/community/ or packages/pieces/core/:

   cd packages/pieces/community/slack
   
3. Edit Piece Code

   Make changes to any file in src/ directory. The changes will be detected automatically.

4. Test in Browser

   • Go to http://localhost:4200
   • Create or edit a flow
   • Your updated piece will be available immediately

Hot reloading works for actions, triggers, properties, and authentication changes. You don’t need to rebuild or restart!

Project Structure

Understanding the project structure helps you navigate the codebase:

activepieces/
├── packages/
│   ├── pieces/
│   │   ├── framework/          # Piece framework core
│   │   ├── common/             # Shared utilities
│   │   ├── community/          # Community pieces
│   │   │   ├── slack/
│   │   │   ├── github/
│   │   │   └── ... (600+ pieces)
│   │   └── core/               # Core pieces (HTTP, Code, etc.)
│   ├── web/                    # Frontend application
│   ├── server/
│   │   ├── api/                # Backend API
│   │   └── engine/             # Flow execution engine
│   └── shared/                 # Shared types and utilities
├── package.json                # Root package configuration
└── turbo.json                  # Monorepo build configuration

Useful Commands

Here are the most common commands you’ll use:

Create a New Piece

npm run create-piece

Environment Variables

For local development, you may need to configure environment variables:

.env

# API Configuration
AP_API_KEY=your-api-key
AP_ENCRYPTION_KEY=your-encryption-key
AP_JWT_SECRET=your-jwt-secret

# Database
AP_POSTGRES_DATABASE=activepieces
AP_POSTGRES_HOST=localhost
AP_POSTGRES_PORT=5432
AP_POSTGRES_USERNAME=postgres
AP_POSTGRES_PASSWORD=password

# Frontend
AP_FRONTEND_URL=http://localhost:4200

# Execution Mode
AP_EXECUTION_MODE=UNSANDBOXED

Never commit .env files to version control. They’re already in .gitignore.

IDE Setup (VS Code)

For the best development experience with VS Code:

Recommended Extensions

• ESLint - Linting and code quality
• Prettier - Code formatting
• TypeScript and JavaScript Language Features - Enhanced TS support
• GitLens - Git integration

Workspace Settings

Create .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Troubleshooting

Bun installation fails

If automatic Bun installation fails:

# Install Bun manually
curl -fsSL https://bun.sh/install | bash

# Then run setup again
npm run start

Port already in use

If ports 3000 or 4200 are already in use:

# Kill processes using these ports
lsof -ti:3000 | xargs kill -9
lsof -ti:4200 | xargs kill -9

Hot reload not working

If changes aren’t being detected:

1. Ensure you’re in dev mode: npm run dev
2. Check file watcher limits (Linux):
   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   
3. Restart the dev server

TypeScript errors

If you see TypeScript errors after pulling changes:

# Clean and reinstall
bun install

# Restart TypeScript server in VS Code
# CMD/CTRL + Shift + P -> "TypeScript: Restart TS Server"

Next Steps

Create Your First Piece

Now that your environment is set up, create your first piece!