ContextQMD
Back to Activepieces

Piece syncing & versioning

docs/install/architecture/piece-syncing.mdx

0.83.02.5 KB
Original Source

Pieces are standard npm packages. Two facts follow from that:

  • No server upgrade is needed for new pieces — a sync job pulls fresh versions on its own.
  • Each step is pinned to an exact version — flows never auto-upgrade. Bumps are explicit, through the builder.
mermaid
flowchart LR
    REG["npm registry
(@activepieces/piece-*)"]
    CAT["Local piece catalog"]
    STEP["Flow step
pieceVersion: 0.5.3"]
    UI["Builder version dialog"]

    REG -- "hourly sync
(OFFICIAL_AUTO)" --> CAT
    CAT -- "exact version on add" --> STEP
    UI -- "explicit upgrade" --> STEP

    classDef src fill:#eef,stroke:#88a
    classDef catalog fill:#efe,stroke:#7a7
    classDef flow fill:#fee,stroke:#a77
    class REG src
    class CAT catalog
    class STEP,UI flow

Packaging

TypeSourceInstalled by
OfficialActivepieces cloud registryAuto-sync
Custom (npm)npm registry, scoped to one platformPlatform admin
Private (archive).tgz uploadPlatform admin

Custom and private pieces are managed manually — see Manage pieces.

Auto-sync

AP_PIECES_SYNC_MODEBehavior
OFFICIAL_AUTOHourly reconcile against the cloud registry. Default for all deployments.

Custom and private pieces are never touched by the sync job.

Server compatibility

Every piece declares a minimumSupportedRelease (and optional maximumSupportedRelease) in its definition — the range of Activepieces server releases it works on. The catalog filters pieces against the running server's release, so an out-of-range piece is never listed in the builder and never served from the registry.

<Warning> **Self-hosted: upgrade to `0.82.0` or newer.** Every new piece now declares `minimumSupportedRelease ≥ 0.82.0`, the floor that came in with the latest piece-context version. Servers below `0.82.0` will not pick up any newly published pieces or bug fixes. Cloud is always on the latest release. </Warning>

Version pinning

Adding a step records the exact piece version at that moment (e.g. 0.5.3). The pin stays until a human changes it. To upgrade, open the step in the builder, click the version next to its name, and pick a new one. The dialog warns when the change crosses a minor or major boundary.