Skip to main content

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

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

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

# Then run setup again
npm run start
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
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
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!