# How to Use External Libraries with Cloudflare Computer Runtime Types

> Learn how to use external libraries with Cloudflare Computer. Discover which runtime backends support external libraries and optimize your development workflow for faster deployment.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Yes—you can use external libraries with Cloudflare Computer, but only with specific runtime backends:** the `container-shell` backend allows runtime package installation, while `worker-javascript` requires pre-bundling dependencies at build time. The `worker-shell` backend does not support external libraries at all.

Cloudflare Computer provides three distinct **runtime backends** that determine how code executes and what dependencies are available. Each backend has different capabilities for using external libraries, making backend selection critical for your use case. This guide explains each backend's library support with practical examples from the Cloudflare Computer source code.

## Container-Shell Backend: Full Runtime Package Management

The `container-shell` backend provides a **complete Linux environment** with a real Node.js runtime, writable filesystem, and network access. This is the only backend that supports installing and using external libraries dynamically at runtime.

According to the [Worker backend documentation](https://github.com/cloudflare/computer/blob/main/docs/12_worker_backend.md), "The container backend … gives you a real Linux environment with arbitrary binaries … and a full POSIX filesystem"【/cache/repos/github.com/cloudflare/computer/main/docs/12_worker_backend.md†L25-L28】.

### Installing Packages at Runtime

The `workspace.runtime.exec` interface lets you execute any shell command, including package managers like `npm`, `pnpm`, or `yarn`【/cache/repos/github.com/cloudflare/computer/main/docs/05_runtime_interface.md†L71-L78】.

```typescript
// Install and use lodash in a container backend
const handle = await workspace.runtime.exec(
  `npm install lodash && node -e "console.log(require('lodash').shuffle([1,2,3]))"`,
  { 
    backend: "container-shell", 
    cwd: "/workspace", 
    env: { NODE_ENV: "production" } 
  }
);
const result = await handle.result();
console.log(result.stdout); // [3, 1, 2] or similar shuffled array

```

**Use this backend when you need:**
- Dynamic dependency installation based on runtime conditions
- Access to native Node.js modules or compiled binaries
- A full POSIX environment with standard Linux tools

## Worker-JavaScript Backend: Pre-Bundled Dependencies Only

The `worker-javascript` backend runs code in a **JavaScript isolate** without a package manager. External libraries must be **bundled at build time** before reaching the runtime.

The runtime receives environment variables via `process.env`, but the environment is read-only per execution. Dependencies must already exist in your compiled bundle.

### Bundling Dependencies for Worker-JavaScript

Use a bundler like `esbuild`, `webpack`, or `wrangler` to include external libraries in your deployment package.

```typescript
// Build step: bundle dependencies into a single file
// esbuild src/main.ts --bundle --outfile=dist/bundle.js --platform=node

// At runtime – lodash is already in the bundle
const handle = await workspace.runtime.exec(
  `import _ from "./bundle.js"; console.log(_.shuffle([1,2,3]));`,
  { backend: "worker-javascript" }
);
const result = await handle.result();
console.log(result.stdout);

```

**Key implementation details:**
- Source location: `packages/computer/src/backends/worker-javascript`
- No filesystem writes possible during execution
- All `import` statements must resolve to files in the deployed bundle

## Worker-Shell Backend: Built-In Utilities Only

The `worker-shell` backend uses a **Just-Bash interpreter** running inside a Dynamic Worker. It forwards filesystem calls to the host DO but lacks a Node.js runtime entirely.

The documentation explicitly states this backend "does not have the full Linux userland" and that "JavaScript modules run through the `worker-javascript` backend, not through just-bash's Node-only language commands"【/cache/repos/github.com/cloudflare/computer/main/docs/12_worker_backend.md†L32-L36】.

### Available Capabilities

Only built-in shell utilities are available—no `npm`, `node`, or external packages:

```typescript
// Only standard shell tools work in worker-shell
const handle = await workspace.runtime.exec(
  `grep -i "error" logs.txt | wc -l`,
  { backend: "worker-shell" }
);
const result = await handle.result();
console.log(result.stdout); // Line count of matching entries

```

**Available tools include:** `cat`, `grep`, `awk`, `jq`, `sed`, `head`, `tail`, and other common POSIX utilities.

## Backend Comparison for External Libraries

| Backend | Library Support | Method | Performance | Use Case |
|--------|-----------------|--------|-------------|----------|
| **container-shell** | ✅ Full runtime `npm install` | Dynamic installation | Slower (cold start + install) | Complex dependencies, native modules, interactive development |
| **worker-javascript** | ✅ Pre-bundled only | Build-time bundling | Fast (no install step) | Production APIs, predictable dependencies, edge deployment |
| **worker-shell** | ❌ None | Built-in utilities only | Fastest | Text processing, simple automation, no JS dependencies |

## Choosing the Right Runtime Type

**Select `container-shell` when:**
- You need packages with native compiled dependencies (e.g., `sharp`, `bcrypt`)
- Dependencies vary by user input or runtime configuration
- You're prototyping and want fast iteration without build steps

**Select `worker-javascript` when:**
- You want predictable, fast cold starts
- Your dependency tree is stable and known at deploy time
- You're deploying to the edge and need minimal bundle size

**Select `worker-shell` when:**
- Your task requires only standard Unix text processing
- You want the lowest latency and smallest resource footprint
- No JavaScript execution is needed

## Key Source Files

These locations in the Cloudflare Computer repository define each backend's capabilities:

- [`docs/05_runtime_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/05_runtime_interface.md) – `workspace.runtime.exec` API and backend selection【/cache/repos/github.com/cloudflare/computer/main/docs/05_runtime_interface.md†L71-L78】
- [`docs/12_worker_backend.md`](https://github.com/cloudflare/computer/blob/main/docs/12_worker_backend.md) – Backend capability comparison and limitations【/cache/repos/github.com/cloudflare/computer/main/docs/12_worker_backend.md†L25-L36】
- `packages/computer/src/backends/container` – Container-shell implementation with full Node.js environment
- `packages/computer/src/backends/worker-javascript` – JavaScript isolate for pre-bundled code
- `packages/computer/src/backends/worker-shell` – Just-Bash interpreter with POSIX utilities only

## Summary

- **External libraries work with Cloudflare Computer** in two specific ways: runtime installation via `container-shell`, or build-time bundling for `worker-javascript`
- **Container-shell** (`backend: "container-shell"`) is the only option for `npm install` during execution—use it when you need dynamic or native dependencies
- **Worker-javascript** requires bundling tools like `esbuild` or `wrangler` to include external libraries before deployment
- **Worker-shell** has no external library support—limit yourself to built-in shell utilities like `grep`, `awk`, and `jq`
- Choose your backend based on whether you prioritize **flexibility** (`container-shell`) or **performance** (`worker-javascript`, `worker-shell`)

## Frequently Asked Questions

### Can I run `npm install` in a Cloudflare Computer script?

**Yes, but only with the `container-shell` backend.** This backend provides a full Linux environment with Node.js and network access, allowing arbitrary shell commands including `npm install`, `pnpm add`, or `yarn add`. The `worker-javascript` and `worker-shell` backends do not support runtime package installation.

### How do I use npm packages with the worker-javascript backend?

**Bundle your dependencies at build time.** Since the `worker-javascript` backend runs in a JavaScript isolate without a package manager, you must use a bundler like `esbuild`, `webpack`, or `wrangler` to include external libraries in your deployment artifact. Import paths in your runtime code must reference the bundled files, not `node_modules`.

### Why does worker-shell not support external libraries?

**The `worker-shell` backend uses Just-Bash, a Bash interpreter without Node.js.** According to the source documentation, it "does not have the full Linux userland" and explicitly excludes JavaScript execution capabilities. It forwards filesystem calls to the host DO but can only run built-in POSIX utilities like `cat`, `grep`, and `jq`—not `node` or `npm`.

### Which backend should I use for production APIs with external dependencies?

**Use `worker-javascript` with pre-bundled dependencies.** This provides the fastest cold starts and most predictable performance, as no installation step occurs at runtime. Build your application with `esbuild` or similar tools, deploy the bundle to Cloudflare Computer, and specify `backend: "worker-javascript"` in your `workspace.runtime.exec` calls.