How to Use External Libraries with Cloudflare Computer Runtime Types

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, "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】.

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

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}