Imports and Package Management (upcoming)

Available in version 1.1.72 (not yet live).

Use standard JavaScript imports like import dayjs from "[email protected]" 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 "[email protected]";
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("[email protected]");
await zw.log("uniq result", _.uniq([1, 1, 2, 3]));

// Import from Git (HTTPS only)
import lodash from "git+https://github.com/lodash/lodash.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 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 "[email protected]"; // 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(options: ImportOptions, pkg: string | string[] | { [key: string]: string }) → installs if needed and returns the loaded module(s)

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

Examples

Single package with options

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

Multiple packages as an array

// @zw-run-locally
const [dayjs, lodash] = await zw.import(
  { isolate: true },
  ["[email protected]", "[email protected]"]
);

Named mapping as an object

// @zw-run-locally
const { time, dash } = await zw.import(
  { uninstallIfUnusedFor: null },
  { time: "[email protected]", dash: "[email protected]" }
);

Installing from Git (HTTPS only)

// @zw-run-locally
const gitLodash = await zw.import(
  { uninstallIfUnusedFor: null },
  "git+https://github.com/lodash/lodash.git"
);

Use default options by passing an empty object {}

// @zw-run-locally
const lodash = await zw.import({}, "[email protected]");

Import Option Details

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 second argument.

String "lodash", "[email protected]", "lodash/chunk", "https://github.com/user/repo.git#main" or "git+https://github.com/user/repo.git#main"
Array of strings ["[email protected]", "[email protected]"]
Object mapping { util: "[email protected]", time: "[email protected]" }

Invalid inputs that are rejected

Tarball URLs, local file paths, and directories
Non-HTTPS Git URLs

Special Package Types

Built-in Packages

These packages 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 "[email protected]";

Pure ESM Packages

ZeroWork isn’t pure ESM yet. Pure ESM packages aren’t supported and will throw an error similar to:

This package appears to be pure ESM. Pure ESM packages are currently not supported. To confirm, check the package documentation.

Workarounds for pure ESM packages

Use a maintained non-ESM fork if available. For example, cacheable-lookup is a pure ESM module but a maintained fork is available: @esm2cjs/cacheable-lookup.
Pin a non-ESM version if the project provides one. For example, the latest chalk version is pure ESM but its documentation recommends pinning to v4 chalk@4 for a CommonJS build.
If the package is pure ESM with no CommonJS fork or version, you will have to find an alternative.

Native Packages

Packages that include native code (C/C++ or other system-level bindings) may not work reliably. They often require a compatible Node version, build tools, or system libraries. This typically affects modules that talk directly to the operating system or hardware — for example node-window-manager, robotjs, or ffi-napi. Advanced users with the right setup might get them working, but they aren’t guaranteed to install or run on all systems.

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({}, "[email protected]"))().toISOString());
}

// 2. Recommended: reuse a local reference
const dayjs = await zw.import({}, "[email protected]");
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({}, "[email protected]");
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

[email protected]
[email protected]
[email protected]   // 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 package name/version

// @zw-run-locally

const ids = await zw.packages.list();
const target = ids.find(id => id.includes("[email protected]"));
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

Import locally in one block, expose a function, then call it 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.

PreviousWrite JavaScript (upcoming)NextWrite and Read Variables and Tables

Last updated 13 days ago

Was this helpful?

1. Imports

Standard Imports

Imports with zw.import()

At a Glance

Examples

Import Option Details

Supported Package Inputs

Special Package Types

Built-in Packages

Pure ESM Packages

Native Packages

Reusing References

2. Package Management

At a Glance

What’s a Package ID?

Examples

3. Local and Browser Execution

How to Use Imported Packages in the Browser

Imports with `zw.import()`