# Migrate Pieces to Self-Contained Bundles

Sydekyks user and operator guide. Check feature availability and release-specific installation requirements.

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.

Sydekyks builds each piece into a single self-contained bundle (see Bundling Pieces (https://docs.sydekyks.com/build-pieces/misc/bundling-pieces) 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:

```
# 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:

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

```
// 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.

```
{
  "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:

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

```

4

Build and verify

```
npm run build-piece your-piece

```

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

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.