# Bundling Pieces

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

Sydekyks builds every piece into a self-contained bundle. Instead of shipping a piece that depends on @activepieces/shared, @activepieces/pieces-framework, @activepieces/pieces-common, and the @activepieces/core-* packages at install time, the build inlines all of that code into a single artifact.

This is what lets the engine provision a piece by downloading one artifact, with no bun install / npm install of a dependency tree at runtime.

### ​What gets bundled

When a piece is built for publishing, the bundler:

- Inlines all @activepieces/* workspace libraries (shared, pieces-framework, pieces-common, core-utils, core-piece-types, …) directly into the bundle. These libraries are never published to npm; they only exist as part of each piece’s bundle.

- Inlines third-party dependencies (e.g. an SDK the piece imports) into the same bundle.

- Keeps a small allow-list of deps external only when they genuinely cannot be inlined: native addons or packages that use dynamic require. These remain in the published dependencies so the runtime installer resolves them.

The result is typically ~2-3× smaller than the raw inputs, and the published package.json lists only the few unavoidable external deps (e.g. tslib).

### ​The published manifest

After bundling, the piece’s dist/package.json is rewritten:

```
{
  "name": "@activepieces/piece-json",
  "version": "0.1.7",
  "main": "./src/index.js",      // the self-contained bundle
  "dependencies": {
    "tslib": "2.6.2"             // only genuinely-external deps remain
  },
  "files": ["src/index.js", "package.json", "src/i18n"]
}

```

No @activepieces/* dependency appears, so installing the piece never requires those packages to exist on the registry.

### ​Forcing a dependency to stay external

If a dependency must not be inlined (for example a native module), add it to a bundleDeps array in the piece’s package.json. The bundler will keep it external and preserve it in the published dependencies.

```
{
  "name": "@activepieces/piece-example",
  "bundleDeps": ["some-native-addon"]
}

```

### ​Files loaded at runtime (forked processes)

A file your piece loads by path at runtime (for example child_process.fork(path.join(__dirname, 'runner.js'))) is invisible to the bundler’s import graph, so by default it would not exist in the published package. Declare it in bundleForkedEntries:

```
{
  "name": "@activepieces/piece-oracle-database",
  "bundleForkedEntries": ["src/lib/common/oracle-runner.ts"]
}

```

Each declared entry is bundled on its own and emitted next to the main bundle at src/<name>.js, which is where path.join(__dirname, '<name>.js') resolves at runtime, since the bundled parent code lives at src/index.js. Dependencies that only the forked file imports (e.g. oracledb) are still captured into the published dependencies.

The bundler fails the build if piece code uses __dirname without declaring any bundleForkedEntries, because such code breaks silently after publishing.

### ​Building and publishing

Bundling happens automatically when you build or publish a piece:

- npm run build-piece <name>: builds and packs the bundle into a .tgz (see Build Custom Pieces (https://docs.sydekyks.com/build-pieces/misc/build-piece)).

- For public npm distribution, follow Public npm (https://docs.sydekyks.com/build-pieces/sharing-pieces/community) after testing the packed artifact. Native API-key upload is excluded from this Community guide.

You don’t need to configure anything for bundling; it is the default behavior.