Optimization: Reduce package size by moving MCP to a separate package and using engines instead of peerDependencies for bun

[tmvc03]

Hi! First of all, thank you for creating bunqueue. It's an amazing, lightweight alternative for background jobs in Bun.

However, I noticed a significant bundle bloat after installing the package. The size of node_modules expands drastically from 75.8 MB to 223.1 MB upon adding bunqueue.

After looking into the package structure and package.json, I found two areas where we can significantly optimize this.

---

1. Separate MCP into a standalone package (e.g., @bunqueue/mcp or bunqueue-mcp)

Right now, the core bunqueue package includes Model Context Protocol (MCP) support out of the box. While this is great for AI agent workflows, it forces all standard users to install heavy dependencies that they don't actually need for basic queue functionality.

Specifically, it brings in:

• @modelcontextprotocol/sdk
• zod

Proposed Solution:
Extract the MCP server/features into a separate package, for instance, bunqueue-mcp or @bunqueue/mcp.

• Users who just need a high-performance SQLite queue can install bunqueue (keeping it extremely lightweight).
• Users building AI agent integrations can install both bunqueue and bunqueue-mcp.

---

2. Move bun from peerDependencies to engines

Currently, package.json specifies:

"peerDependencies": {
  "bun": "^1.3.9"
}

Using peerDependencies for a runtime like bun is generally considered an anti-pattern in the modern JS ecosystem. It forces package managers (especially npm/pnpm/yarn when used in mixed or transition environments) to perform unnecessary dependency resolution checks or throw warnings/errors during installation.

Proposed Solution:
The correct way to restrict or enforce the runtime environment is to use the engines field:

"engines": {
  "node": ">=... ", // if applicable
  "bun": ">=1.3.9"
}

---

Benefits

• Lightweight Footprint: Brings back the "zero-overhead / ultra-fast" promise of the SQLite-backed queue.
• Better DX: Speeds up CI/CD install times and saves disk space for thousands of developers.
• Modular Architecture: Easier to maintain and version the MCP integration separately from the core queue logic.

[egeominotti]

Thank you for the detailed report. Both items have been addressed and shipped in 2.8.1; the second point accounted for the larger share of the footprint.

Measured impact (clean bun add bunqueue):

Metric	2.7.x	2.8.1
node_modules	93 MB	8.2 MB (−91%)
Installed packages	117	7
Cold install	~6 s	~1.2 s

1. MCP footprint — addressed via an optional peer dependency rather than a separate package.

Extracting bunqueue-mcp into its own package was considered, but src/mcp/ depends on roughly ten internal modules that are not part of the public API (client/manager, client/tcpPool, client/worker/worker, infrastructure/cloud/cloudAgent, domain/types/*, among others). A standalone package would require either promoting all of those to a stable public surface or relying on fragile deep imports, in addition to versioning two packages in lockstep. The optional-peer approach achieves the same footprint reduction at considerably lower maintenance cost:

• @modelcontextprotocol/sdk moved to peerDependencies with peerDependenciesMeta.optional
• zod removed from dependencies entirely (it ships transitively with the SDK)
• src/mcp/index.ts is now a thin launcher that lazy-loads the server via dynamic import(), keeping the SDK out of the queue's import graph
• the bunqueue-mcp binary and the bunqueue/mcp export are unchanged — only the SDK download is deferred

MCP users install the SDK once with bun add @modelcontextprotocol/sdk. If it is absent, the launcher fails fast with an actionable message and exit code 1.

2. bun in peerDependencies → engines.

Declaring bun as a peer dependency caused package managers to pull the 61 MB bun runtime package into the consumer tree. It has been removed from peerDependencies and retained in engines (>=1.3.9), which is the appropriate field for a runtime constraint. This change alone accounts for roughly 61 MB of the savings; removing the SDK and zod accounts for the remaining ~24 MB.

A full write-up is available in the 2.8.1 changelog.

[egeominotti]

Follow-up: a further reduction shipped in 2.8.2.

The published package was still including *.js.map and *.d.ts.map source maps — 512 files, roughly 2.8 MB. Their sources field points at src/*.ts, which is not part of the published tarball, so they could not resolve to anything and provided no debugging value to consumers. The build now disables sourceMap and declarationMap, emitting neither the maps nor any dangling sourceMappingURL references, and the corresponding globs were removed from files[].

Cumulative impact of the three changes, measured with a clean bun add bunqueue:

Metric	Before (2.7.x)	After (2.8.2)
node_modules	93 MB	5.4 MB (−94%)
Installed packages	117	7
Cold install	~6 s	~1.2 s (~5× faster)

Breakdown of the ~88 MB removed:

Change	Saved
bun moved from peerDependencies to engines	~61 MB
MCP SDK + zod + HTTP stack made an optional peer dependency	~24 MB
Source maps no longer published	~2.8 MB

The remaining footprint is effectively the floor: two runtime dependencies (croner and msgpackr), since SQLite, S3, HTTP, and WebSocket are provided by Bun's standard library.

Thank you again for raising this — both items from the report shipped, and the package is now substantially leaner for every consumer.