> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate Pieces to Self-Contained Bundles

> [!NOTE]
>
> This applies to forks with custom pieces created before pieces moved to self-contained bundles. Pieces created with `npm run cli pieces create` already use the bundle model, so there's nothing to do.

Activepieces builds each piece into a single self-contained bundle (see [Bundling Pieces](https://www.activepieces.com/docs/build-pieces/misc/bundling-pieces.md) for how that works). If you maintain custom pieces from before this change, update them so they conform to the new model.

## What changed

| | **Before** | **Now** |
| - | - | - |
| Piece dependencies | `@activepieces/shared` + framework + common | framework + common only |
| Imports in piece code | `@activepieces/shared` and `@activepieces/pieces-framework` | `@activepieces/pieces-framework` only |
| Build output | compiled files + dependency tree | one self-contained bundle |
| `@activepieces/shared` location | `packages/shared` | `packages/core/shared` (same package name) |

Pieces now import only from `@activepieces/pieces-framework` and `@activepieces/pieces-common`. The framework re-exports the foundation symbols (`isNil`, `SeekPage`, `PieceCategory`, `AppConnectionType`, and so on) that used to come from `@activepieces/shared`.

## Migrate with the CLI

The `pieces migrate` command applies every change below for you:

```bash theme={null}
# preview the changes without writing anything
npm run cli -- pieces migrate <piece-name> --dry-run

# apply them
npm run cli -- pieces migrate <piece-name>
```

* Pass `--all` to migrate every piece under `packages/pieces`.
* It is idempotent: re-running it on an already-migrated piece makes no changes.

Then build the piece to verify:

```bash theme={null}
npm run build-piece <piece-name>
```

To migrate by hand, or to see exactly what the command changes, follow the steps below.

## What it changes (or migrate by hand)

**1. Repoint imports to the framework**

Replace any `@activepieces/shared` (or `@activepieces/core-*`) import with `@activepieces/pieces-framework`:

```ts theme={null}
// Before
import { PieceCategory, ExecutionType } from '@activepieces/shared';

// After
import { PieceCategory, ExecutionType } from '@activepieces/pieces-framework';
```

If a symbol isn't re-exported by the framework, it was server-only and shouldn't be imported into a piece.

**2. Update package.json dependencies and scripts**

Remove `@activepieces/shared` and move `tslib` to `devDependencies`. Add `@activepieces/core-piece-types` and `@activepieces/core-utils`, which are build-time only (they let `tsc` emit portable type declarations; your source never imports them directly). Add the `bundle` script.

```jsonc theme={null}
{
  "dependencies": {
    "@activepieces/pieces-common": "workspace:*",
    "@activepieces/pieces-framework": "workspace:*",
    "@activepieces/core-piece-types": "workspace:*",
    "@activepieces/core-utils": "workspace:*"
  },
  "devDependencies": {
    "tslib": "2.6.2"
  },
  "scripts": {
    "build": "tsc -p tsconfig.lib.json && cp package.json dist/",
    "bundle": "node ../../../../dist/packages/cli/src/index.js pieces bundle",
    "lint": "eslint 'src/**/*.ts'"
  }
}
```

**3. Add the import-boundary lint rule**

Add a `no-restricted-imports` rule to the `*.ts`/`*.tsx` override in the piece's `.eslintrc.json` so it can't regress to importing packages that defeat bundling:

```json theme={null}
{
  "files": ["*.ts", "*.tsx"],
  "rules": {
    "no-restricted-imports": ["error", {
      "patterns": [
        "lodash",
        "lodash/*",
        "@activepieces/core-*",
        "@activepieces/server*",
        "@activepieces/engine",
        "@activepieces/shared"
      ]
    }]
  }
}
```

**4. Build and verify**

```bash theme={null}
npm run build-piece your-piece
```

The archive produced in `packages/pieces/<type>/your-piece/dist/` is now a self-contained bundle.

> [!TIP]
>
> A freshly scaffolded piece (`npm run cli pieces create`) already includes all of the above. Use one as a reference if you're unsure what a migrated piece should look like.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.