Skip to main content

​
What are Pieces?

Pieces are integrations in Activepieces - modular, reusable components that connect your automation flows to external services and APIs. Each piece can contain actions (things you can do) and triggers (events that start flows). Activepieces has 600+ open-source pieces, with over 95% contributed by the community. All pieces are:
  • Written in TypeScript
  • Published to npmjs.com
  • Versioned independently
  • Available as MCP servers for use with LLMs

​
Piece Framework Overview

The piece framework (@activepieces/pieces-framework) provides a type-safe, developer-friendly way to build integrations.

​
Core Concepts

Actions are operations that can be performed in a flow. They take inputs, execute logic, and return outputs.Examples:
  • Send a message to Slack
  • Create an issue in GitHub
  • Update a record in Airtable
Triggers start flows when specific events occur. They can be:
  • Polling: Check for changes periodically
  • Webhook: Receive real-time notifications
  • App Webhook: Use platform-level webhooks
Examples:
  • New email received
  • File uploaded to cloud storage
  • Form submission
Pieces support multiple authentication methods:
  • OAuth2
  • API Keys (Secret Text)
  • Custom Authentication (multiple fields)
  • Basic Auth
Properties define the inputs for actions and triggers:
  • ShortText, LongText
  • Number, Checkbox
  • Dropdown (static or dynamic)
  • File, JSON, DateTime
  • Dynamic properties that change based on other inputs

​
Framework Structure

The framework is located at packages/pieces/framework/ in the repository: 
packages/pieces/framework/
├── src/
│   ├── lib/
│   │   ├── action/          # Action definitions
│   │   ├── trigger/         # Trigger definitions
│   │   ├── property/        # Property types
│   │   │   ├── authentication/  # Auth types
│   │   │   └── input/          # Input property types
│   │   ├── piece.ts         # Piece creation
│   │   └── context.ts       # Execution context
│   └── index.ts
└── package.json

​
Example: Simple Piece

Here’s what a minimal piece looks like: 
import { createPiece, PieceAuth } from '@activepieces/pieces-framework';
import { PieceCategory } from '@activepieces/shared';

export const myPiece = createPiece({
  displayName: 'My Service',
  description: 'Integration with My Service',
  auth: PieceAuth.SecretText({
    displayName: 'API Key',
    required: true,
  }),
  minimumSupportedRelease: '0.30.0',
  logoUrl: 'https://cdn.activepieces.com/pieces/my-service.png',
  categories: [PieceCategory.PRODUCTIVITY],
  authors: ['your-github-username'],
  actions: [],
  triggers: [],
});

​
Why Build Pieces?

Extend Activepieces

Add integrations for services you use that aren’t available yet

Type Safety

Full TypeScript support with autocomplete and type checking

Hot Reloading

Test changes instantly during local development

Share with Community

Contribute to the open-source ecosystem and help others

​
Next Steps

Setup Development

Set up your local development environment

Create a Piece

Learn how to create your first piece

Authentication

Add authentication to your piece

Create Actions

Build actions that perform operations