Create a Piece

Learn how to create a new piece from scratch

Using the CLI

The easiest way to create a new piece is using the built-in CLI command:

npm run create-piece

This interactive command will prompt you for:

1. Piece Name

   Enter the name of your piece (e.g., my-service)

   • Use lowercase with hyphens
   • Must be unique across all pieces
2. Display Name

   The human-readable name shown in the UI (e.g., My Service)

3. Description

   A brief description of what your piece does

4. Category

   Choose from categories like:

   • Communication
   • Productivity
   • Marketing
   • Developer Tools
   • And more…

The CLI will:

1. Create the piece directory structure
2. Generate boilerplate code
3. Add the piece to the workspace configuration

Piece Structure

After running the CLI, your piece will have this structure:

packages/pieces/community/my-service/
├── src/
│   ├── index.ts              # Main piece definition
│   ├── lib/
│   │   ├── actions/          # Action implementations
│   │   ├── triggers/         # Trigger implementations
│   │   ├── common/           # Shared utilities
│   │   └── auth.ts           # Authentication setup
├── package.json              # Package configuration
└── tsconfig.json            # TypeScript configuration

Anatomy of a Piece

Let’s look at a real example from the GitHub piece:

packages/pieces/community/github/src/index.ts

import { createPiece, PieceAuth } from '@activepieces/pieces-framework';
import { PieceCategory } from '@activepieces/shared';
import { githubCreateIssueAction } from './lib/actions/create-issue';
import { githubTriggers } from './lib/trigger';
import { githubAuth } from './lib/auth';

export const github = createPiece({
  displayName: 'GitHub',
  description: 'Developer platform for code management',
  
  minimumSupportedRelease: '0.30.0',
  logoUrl: 'https://cdn.activepieces.com/pieces/github.png',
  categories: [PieceCategory.DEVELOPER_TOOLS],
  
  // Authentication configuration
  auth: githubAuth,
  
  // List of actions
  actions: [
    githubCreateIssueAction,
    // ... more actions
  ],
  
  // List of triggers
  triggers: githubTriggers,
  
  // Contributors
  authors: ['kishanprmr', 'abuaboud'],
});

Key Components

Metadata

{
  displayName: 'GitHub',           // Shown in UI
  description: 'Description...',    // Piece description
  logoUrl: 'https://...',           // Logo image URL
  categories: [PieceCategory.DEVELOPER_TOOLS],
  authors: ['username'],            // GitHub usernames
  minimumSupportedRelease: '0.30.0' // Min Activepieces version
}

Authentication

auth: PieceAuth.OAuth2({
  displayName: 'Connection',
  authUrl: 'https://github.com/login/oauth/authorize',
  tokenUrl: 'https://github.com/login/oauth/access_token',
  required: true,
  scope: ['repo', 'user']
})

Actions & Triggers

actions: [
  createIssueAction,
  createPullRequestAction,
  // ... more actions
],
triggers: [
  newIssuesTrigger,
  newPullRequestTrigger,
  // ... more triggers
]

Example: Building a Simple Piece

Let’s create a simple weather service piece:

1. Create the Piece

   npm run create-piece
   # Name: weather-api
   # Display Name: Weather API
   # Description: Get weather information
   # Category: PRODUCTIVITY
   
2. Define Authentication

   src/lib/auth.ts

   import { PieceAuth } from '@activepieces/pieces-framework';
   
   export const weatherAuth = PieceAuth.SecretText({
     displayName: 'API Key',
     description: 'Enter your Weather API key',
     required: true,
     validate: async ({ auth }) => {
       // Optional: Validate the API key
       return {
         valid: true,
       };
     },
   });
   
3. Create Main File

   src/index.ts

   import { createPiece } from '@activepieces/pieces-framework';
   import { PieceCategory } from '@activepieces/shared';
   import { weatherAuth } from './lib/auth';
   import { getCurrentWeather } from './lib/actions/get-current-weather';
   
   export const weatherApi = createPiece({
     displayName: 'Weather API',
     description: 'Get weather information for any location',
     auth: weatherAuth,
     minimumSupportedRelease: '0.30.0',
     logoUrl: 'https://cdn.activepieces.com/pieces/weather.png',
     categories: [PieceCategory.PRODUCTIVITY],
     authors: ['your-github-username'],
     actions: [
       getCurrentWeather,
     ],
     triggers: [],
   });
   
4. Add Package Configuration

   package.json

   {
     "name": "@activepieces/piece-weather-api",
     "version": "0.0.1",
     "dependencies": {
       "@activepieces/pieces-framework": "workspace:*",
       "@activepieces/shared": "workspace:*"
     }
   }
   

Piece Configuration Options

displayName · string · required

The name shown in the Activepieces UI

description · string

A brief description of the piece’s functionality

logoUrl · string · required

URL to the piece logo (PNG or SVG). Should be hosted on CDN: https://cdn.activepieces.com/pieces/your-piece.png

auth · PieceAuth

Authentication configuration. See Authentication

categories · PieceCategory[]

Categories for organizing pieces:

• COMMUNICATION
• PRODUCTIVITY
• MARKETING
• SALES_AND_CRM
• DEVELOPER_TOOLS
• ANALYTICS
• CONTENT_AND_FILES
• COMMERCE
• And more…

minimumSupportedRelease · string

Minimum Activepieces version required (e.g., "0.30.0")

maximumSupportedRelease · string

Maximum supported version (optional, for deprecation)

authors · string[]

GitHub usernames of piece contributors

actions · Action[] · required

Array of action definitions. See Create Action

triggers · Trigger[]

Array of trigger definitions. See Create Trigger

Real-World Examples

Look at these community pieces for inspiration:

Slack Piece

packages/pieces/community/slack/

Full-featured piece with:

• OAuth2 authentication
• 20+ actions
• Multiple webhook triggers
• Block Kit support

GitHub Piece

packages/pieces/community/github/

Complex piece with:

• OAuth2 auth
• REST API integration
• GraphQL support
• Repository operations

Google Sheets

packages/pieces/community/google-sheets/

Data-focused piece:

• OAuth2 with Google
• CRUD operations
• Bulk updates
• Dynamic dropdown

Airtable

packages/pieces/community/airtable/

Database piece with:

• API Key auth
• Record management
• Field mapping
• Attachment handling

Testing Your Piece

Once created, test your piece locally:

1. Start Dev Server

   npm run dev
   
2. Open Activepieces

   Navigate to http://localhost:4200

3. Create a Flow

   • Click “Create Flow”
   • Add a step
   • Search for your piece
   • Configure and test

Use hot reloading! Changes to your piece code are reflected immediately without restarting.

Best Practices

Naming Conventions

• Piece name: lowercase-with-hyphens (e.g., my-service)
• Display name: Title Case (e.g., My Service)
• Export name: camelCase (e.g., export const myService = createPiece(...))
• Action/Trigger names: camelCase with suffix (e.g., sendMessageAction)

Logo Guidelines

• Use official brand logos when possible
• PNG or SVG format
• Square aspect ratio (1:1)
• Upload to Activepieces CDN
• Fallback: Use a placeholder icon

Categories

• Choose the most relevant category
• Use only one primary category
• Consider how users will search for your piece

Versioning

• Start with version 0.0.1
• Follow semantic versioning (SemVer)
• Set minimumSupportedRelease appropriately
• Document breaking changes

Next Steps

Add Authentication

Configure OAuth2, API keys, or custom auth

Create Actions

Add actions that perform operations

Create Triggers

Add triggers that start flows

Properties Guide

Learn about all property types