Imports and Package Management

Agents with versions older than 1.1.76 have limitations (pure ESM packages and native packages are generally not supported). Install version 1.1.76 for broader package support.

Use standard JavaScript imports like import dayjs from "dayjs@1.11.11" or use the zw API zw.import() for custom options to install (if needed) and import packages during a TaskBot run. ZeroWork installs missing packages and makes them available to your code.

Manage packages with zw.packages.list(), zw.packages.uninstall(), and zw.packages.uninstallAll().

API zw.import(), zw.packages.*

// @zw-run-locally

// Use desktop automation in ZeroWork

import { execSync } from "child_process";
import { keyboard } from "@computer-use/nut-js";

// Open an editor depending on OS
if (process.platform === "win32") {
  execSync("start notepad");
} else if (process.platform === "darwin") {
  execSync(`osascript -e 'tell application "TextEdit" to activate' -e 'tell application "TextEdit" to make new document'`);
} else {
  execSync("gedit || xed || kate || nano", { shell: "/bin/bash" });
}

// Wait briefly for the editor window to appear
await zw.delay({ min: 2_000 });

// Type into the editor
await keyboard.type("Hello from ZeroWork desktop automation!");

---

1. Imports

Standard Imports

You can use standard ESM or CommonJS syntax. Any such import installs the package if needed, then loads it.

// @zw-run-locally

// ESM default import
import dayjs from "dayjs@1.11.11";
await zw.log("now", dayjs().toISOString());

// ESM subpath import
import chunk from "lodash/chunk";
await zw.log("chunked result", chunk([1, 2, 3, 4], 2));

// CommonJS require
const _ = require("lodash@4.17.21");
await zw.log("uniq result", _.uniq([1, 1, 2, 3]));

// Import from Git (HTTPS only)
import Chance from "git+https://github.com/chancejs/chancejs.git";

Notes

• Installed packages are available to any TaskBot by default. To scope per TaskBot, use zw.import() with { isolate: true } (see details further below).

• If a package isn’t used for one week, it's removed automatically. To change this time window or prevent automatic uninstall, use zw.import() with uninstallIfUnusedFor (see details further below).

• Subpaths like "lodash/chunk" and Git repositories are supported.

• You can disable auto-imports by adding a comment // @zw-disable-auto-import

  // @zw-disable-auto-import
  
  import dayjs from "dayjs@1.11.11"; // throws error

---

Imports with zw.import()

Use zw.import() when you need options or want to import several packages at once.

At a Glance

• async await zw.import(pkg: string | string[] | { [key: string]: string }, options?: ImportOptions) → installs if needed and returns the loaded module(s)

// Reference only — not runnable in Write JS
type ImportOptions = {
  uninstallIfUnusedFor?: number | null; // hours; default 168 (1 week); null = never uninstall
  isolate?: boolean;                    // scope to this TaskBot only; default false
  preferDefault?: boolean;              // advanced; default true
};

Examples

Single package with options

// @zw-run-locally
const dayjs = await zw.import(
  "dayjs@1.11.11",
  { isolate: true, uninstallIfUnusedFor: 300 }
);

Multiple packages as an array

// @zw-run-locally
const [dayjs, lodash] = await zw.import(
  ["dayjs@1.11.11", "lodash@4.17.21"]
);

Named mapping as an object

// @zw-run-locally
const { time, dash } = await zw.import(
  { time: "dayjs@1.11.11", dash: "lodash@4.17.21" }
);

Installing from Git (HTTPS only)

// @zw-run-locally
const gitChance = await zw.import(
  "git+https://github.com/chancejs/chancejs.git"
);

Never uninstall

// @zw-run-locally
const lodash = await zw.import(
   "lodash@4.17.21",
   { uninstallIfUnusedFor: null }
);

Import Options

• uninstallIfUnusedFor (default: 168) Defaults to 168 hours (one week). Set to null to keep the package on the device indefinitely.

• isolate (default: false) When true, the package is scoped to this TaskBot only and isn’t visible in other TaskBots. Useful when different TaskBots need different versions of the same package. Note: If the TaskBot is deleted, the package isn’t removed automatically; you can manage it later with zw.packages.* (see details further below).

• preferDefault (default: true) — advanced Returns module.default when present (otherwise the module object). This only changes the return shape; it doesn’t affect how the module is resolved.

  // @zw-run-locally
  
  // In most cases, leave preferDefault as is (true).
  const mysql = await zw.import("mysql2@latest/promise"); // works
  const { chalk } = await zw.import({ chalk: "chalk@4" }); // works

Supported Package Inputs

You can pass any of the following to zw.import() as the first argument (package input).

• String "lodash", "lodash@4.17.21", "lodash/chunk", "https://github.com/user/repo.git#main" or "git+https://github.com/user/repo.git#main"

• Array of strings ["dayjs@1.11.11", "lodash@4.17.21"]

• Object mapping { util: "lodash@4.17.21", time: "dayjs@1.11.11" }

Invalid inputs that are rejected

• Tarball URLs, local file paths, and directories

• Non-HTTPS Git URLs

---

Built-in Packages

The following packages and Node core modules are pre-bundled and resolve without installation.

• Node core modules such as fs, os, etc.

• axios pinned to ^1.6.6

• playwright pinned to ^1.45.0

They don’t appear in zw.packages.list(), and you can’t change their versions or uninstall them.

// @zw-run-locally

import * as fs from "fs";  // pre-bundled; no installation occurs
import axios from "axios"; // resolves to axios@^1.6.6

// Version spec is ignored; resolves to pinned playwright@^1.45.0
import playwright from "playwright@1.46.0";

Note on Playwright

The pre-bundled playwright import gives you the Playwright API, but the Agent does not bundle the browser binaries Playwright normally downloads. TaskBots run on the Chrome (or the executablePath of another Chromium-based browser) installed on your device. So playwright.chromium.launch() with no options fails; launch with the Chrome channel instead: await playwright.chromium.launch({ channel: "chrome" }). That said, in most cases you don't need this because you can use zw.browserContext.launch().

---

Reusing References

Import once and reuse the reference, as is generally best practice. The package won’t reinstall if it’s already installed, but package parsing and resolution still add overhead.

// @zw-run-locally

// 1. Anti-pattern: import inside the loop (re-parses/resolves each time)
for (let i = 0; i < 1_000_000; i++) {
  await zw.log((await zw.import("dayjs@1.11.11"))().toISOString());
}

// 2. Recommended: reuse a local reference
const dayjs = await zw.import("dayjs@1.11.11");
for (let i = 0; i < 1_000_000; i++) {
  await zw.log(dayjs().toISOString());
}

// 3. Optional (micro-optimization): reuse across Write JS blocks via run state
const cachedDayjs = await zw.import("dayjs@1.11.11");
const state = zw.state.access();
if (!state.cachedResolvedImports) {
  state.cachedResolvedImports = {};
}
state.cachedResolvedImports.dayjs = cachedDayjs;

// In a later building block:
await zw.log(zw.state.access().cachedResolvedImports.dayjs().toISOString());

---

2. Package Management

At a Glance

• async await zw.packages.list() → returns string[] of package IDs.

• async await zw.packages.uninstall(id: string) → removes one.

• async await zw.packages.uninstallAll() → removes all user-managed packages.

Built-ins (axios@^1.6.6, playwright@^1.45.0, and Node core modules like os, fs, etc.) do not appear in list() and cannot be uninstalled.

What’s a Package ID?

A package ID uniquely identifies an installed package instance. It’s an opaque string made of an optional isolation prefix (<taskbotId>_), a lower-cased, sanitized package name, @, and a version tag (<semver>, latest, git, or a commit hash). It may differ from your original import string (subpaths aren’t included; characters are normalized).

Examples

lodash@4.17.21
dayjs@1.11.11
12345_dayjs@1.11.0   // isolated to a specific TaskBot (prefix includes its ID)
repo_name@git        // Git source without a specific commit
repo_name@9f3a2c4    // Git source pinned to a commit

Use these IDs with zw.packages.uninstall(id).

---

Examples

List packages

// @zw-run-locally

const ids = await zw.packages.list();
await zw.log("packages", ids);

Uninstall by matching name/version in the package ID

// @zw-run-locally

const ids = await zw.packages.list();
const target = ids.find(id => id.includes("lodash@4.17.21"));
if (target) await zw.packages.uninstall(target);

Uninstall all for a specific TaskBot

// @zw-run-locally

const myTaskBotId = 12345;
const ids = await zw.packages.list();
const targets = ids.filter(id => id.startsWith(`${myTaskBotId.toString()}_`));
for (const target of targets) {
  await zw.packages.uninstall(target);
}

Uninstall all

// @zw-run-locally

await zw.packages.uninstallAll();

---

3. Local and Browser Execution

Package installation and management run locally only. Standard import/require, zw.import(), and zw.packages.* are supported only when the Write JS block runs outside the browser context. Enable the Run locally checkbox in the block UI, or add the comment // @zw-run-locally.

✅ You can still use imported packages in the browser by exposing functions from a local block (see below).

How to Use Imported Packages in the Browser

Here's how:

• Import in a block that runs locally (e.g. use @zw-run-locally) and expose the needed function.

• Call the function from a later block that runs in the browser.

// Write JS Block A — runs locally

// @zw-run-locally 
import lodash from "lodash";

// Illustrative for simplicity (but prefer pattern below)
const context = zw.browserContext.getContext();
await context.exposeFunction("exposedChunkFn", (arr) => lodash.chunk(arr, 2));

// Better pattern for context continuity
// Ensure function is exposed on any (re)launch
await zw.browserContext.setDefaults({
  onContextReady: async (context) => {
    await context.exposeFunction("exposedChunkFn", (arr) => lodash.chunk(arr, 2));
  }
});

// Write JS Block B — runs in the browser

const result = await exposedChunkFn([1, 2, 3, 4]); // [[1,2],[3,4]]
await zw.log("exposedChunkFn result", result);

Functions exposed via context.exposeFunction() always become asynchronous in the browser, even if they were defined as synchronous. Always call them with await.

---

4. Troubleshooting

I need a package inside an in-browser execution but I can't import it there.

See 3. Local and Browser Execution. That section explains how you should import it in a locally running Write JS block first and then use the imported package's function(s) in a Write JS block running in the browser.

Some packages require extra pre-installed tools on your machine.

In such cases, the error typically mentions "node-gyp" or "gyp ERR!" like in this example:

The package "robotjs" was not installed. Error details: command failed. (pkg: robotjs@0.6.0, event: install, code: 1, script: node-gyp rebuild, stderr: ...gyp ERR! ...)

This usually means that the package tried to compile native code and the required build tools may be missing, such as Xcode Command Line Tools (Mac), Visual Studio Build Tools with C++ (Windows), or build-essential (Linux).

Note that the "node-gyp" / "gyp ERR!" error can also happen for other reasons: the package may not support the Agent's Node version (see below: Node version mismatch...), may not support your device's CPU architecture, may depend on a missing system library, or may contain a bug itself. The stderr: part of the error contains the compiler output that usually identifies the actual problem, so check it first before installing anything.

Node version mismatch: Package fails with a syntax error or 'X is not a function'.

The package may require a newer Node.js version than the Agent ships with (currently Node 22). Packages state their supported Node.js versions in the engines field of their package.json, usually also in their release notes. The failure can take different forms: a syntax error, a missing API at runtime ("X is not a function"), or a load error. The fix is to pin the newest version of the package whose engines range includes Node 22. If no such version exists, use an alternative package.

I'd like to import from a local file.

Local file paths, directories, and tarballs are not supported in zw.import() or standard import/require statements.

Instead:

• For your own code, push it to a Git repository and import the HTTPS Git URL. Bonus: This works on every device the TaskBot runs on.

• Load the file directly with Node:

  // @zw-run-locally
  
  const { createRequire } = await zw.import("node:module");
  const req = createRequire("/"); // don't rename to "require"; require() calls in Write JS don't accept file paths
  const myLib = req("/Users/<username>/my-scripts/my-lib.js");

The import takes forever and never resolves.

Large packages legitimately take a while. Anything that downloads a browser (puppeteer, @playwright/browser-*) moves hundreds of MB on first install and can take several minutes to resolve.

💡When installing browser automation libraries like puppeteer, prefer installing them without browser binaries. For example, you can install puppeteer-core, which can turn a 500 MB installation into just a few MB. Then you can launch with your already installed browser: await puppeteer.launch({ channel: "chrome" }).

Separately, some package versions can ship a faulty install script. For example, some older puppeteer releases (v21 and earlier) stall at the very end of installation even though the download itself succeeds. (Note: current puppeteer versions install cleanly.)

If an install shows no progress for 15+ minutes, stop the run and retry with a different package version. If that doesn't help and you can't find any publicly reported installer bugs or issues for the package, file a bug report and we'll investigate: Report a bug.

Error: "...This git repository requires a build step, which needs the npm command..."

This typically happens with imports from Git URLs. The repository declares a build step (a build, prepare, or install script in its package.json) that the Agent cannot run.

What to do:

• If the package is published to the npm registry, import it by name instead of using a Git URL. Published registry packages usually include the built output and don't require the repository build step.

• If you're on Windows or Linux, install Node.js (which includes npm) and restart the Agent. Note that this won't help on macOS, where desktop apps don't see the PATH locations Node.js installs into.

• For your own private repositories, commit runnable code and remove build-related scripts from package.json (i.e. commit the built output if there is a build).

Error: "The package ... was not installed. ... command failed (pkg: ..., stderr: ...)".

The pkg: field names the dependency whose install script actually failed. This is often a transitive dependency, not the package you imported. The stderr: output contains the underlying reason. You can investigate the issue using that error with AI and/or file a bug report for us to investigate: Report a bug.

Browser-only packages: "...appears to be built for browsers".

Some packages are built to run inside a web page, not in Node. Their code needs a browser environment. Importing them locally fails with an error like:

... This package appears to be built for browsers rather than Node.

✅ These packages can still be used.

Here's how:

• Find the package's bundled build. (Many ship one in their dist/ folder; look for a plain script, not raw ESM source.)

• Save it locally.

• Add it under Scripts in Browser Launch Settings (or in Launch Browser block, or via await zw.browserContext.launch({ launchConfig: { scripts: [{ path: "/Users/me/scripts/guard.js" }] } }) as documented in launchConfig.scripts).

Example: SingleFile

Here's an end-to-end example with SingleFile (captures a complete web page as one HTML string):

1. Step 1: Save the bundle to your machine. You can use the terminal, download it manually, or use a Write JS block. What matters is saving a runnable script: SingleFile publishes its bundle wrapped in a JavaScript string (made for programmatic injection), so it needs one unwrap step. The example below downloads, unwraps, and saves it for you.

💡 This unwrap step is specific to SingleFile. Most browser-oriented packages ship a ready-to-use bundle you can download as-is. Look for a dist/ folder in the repository or fetch it from a CDN like jsdelivr (https://cdn.jsdelivr.net/npm/<package>/dist/...).

// @zw-run-locally
import * as fs from "fs";
import * as os from "os";
import axios from "axios";

// SingleFile specifically publishes its bundle wrapped in a JS string; this unwraps it
const res = await axios.get(
  "https://raw.githubusercontent.com/gildas-lormeau/single-file-cli/master/lib/single-file-bundle.js"
);
const bundle = new Function(
  res.data.replace(/export\s*\{[^}]*\};?\s*$/, "") + "\nreturn script;"
)();

const dir = os.homedir() + "/zerowork-scripts";
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(dir + "/single-file.js", bundle);
await zw.log("Saved bundle to", dir + "/single-file.js");

1. Step 2: In your TaskBot's Browser Launch Settings, open the Scripts section, add a script with type Path and the file path from Step 1.

2. Step 3: Use it from a browser-context Write JS block. The script runs on every page the TaskBot opens, so its singlefile global is available (launch or relaunch the browser after changing Scripts):

// Write JS with in-browser execution

const data = await singlefile.getPageData({ removeHiddenElements: true });
await zw.log("captured bytes: ", data.content.length);
await zw.log("title: ", data.title);