Skip to main content

Migrate from API v1 (v8) to API v2 (v9)

老猫10/22/22About 3 min

If you are familiar with the first-generation APIs, this guide helps you migrate from API v1 to API v2.

Note: The current API v2 (v9) may have memory leak risks. Unless you explicitly need to migrate, verify compatibility, or use Node.js features, you may want to continue prioritizing API v1 (v8) for production scripts.

Enable the second generation API with Node.js engine

For compatibility, Auto.js Pro 9 still defaults to the old Rhino engine (API v1). To use API v2, you must run the script on the Node.js engine.

From globals to require()

In API v2, every module must be imported (for example with require). In API v1, APIs such as app and image lived on globals; in v2 you pull them in explicitly, for example:

// API v1
app.viewFile(...)

// API v2
const app = require('app');
app.viewFile(...)

// Or import only what you need
const { viewFile } = require('app');
viewFile(...)

Most first-generation globals are not available directly, for example sleep, log, and toast:

// API v1
sleep(1000);
log(context.getPackageName());
toast("");

// API v2
const { delay } = require("lang");
const { showToast } = require("toast");

async function main() {
  await delay(1000);
  const context = $autojs.androidContext;
  console.log(context.getPackageName());
  showToast("Hello");
}
main();

Module and function controls

In API v2, some module names are similar to v1 (for example app, color); some features moved to other modules; some v1 modules are replaced by Node.js built-ins (for example files → fs / path); and some are better covered by npm packages (for example WebSocket → the ws package).

Below is a quick map from common v1 modules to v2. Even when names look similar, APIs may differ (for example v1 device.width vs v2 device.screenWidth—check the device docs for exact names).

  • app

Use the app module.

  • base64

Use Node.js Buffer instead. For example:

  • To Base64: Buffer.from("autojs", "utf8").toString("base64")

  • From Base64: Buffer.from("YXV0b2pz", "base64").toString("utf8")

  • color

Use the color module.

  • canvas

The canvas module is similar to the old version. Canvas is currently not supported inside the v9 UI module.

  • console

console.log can be used directly. See Console.

Replace print() / log() with console.log(). For example, replace log("hello") with console.log("hello").

  • crypto

Use the Node.js crypto module.

  • debug

No direct replacement is provided in API v2.

  • device

Use the device module.

  • dialogs

Use the dialogs module.

  • engines

Use the engines module.

  • events

In API v2, some of the old events map to Node.js process events. For example:

  1. exit → process.on("exit", () => {})
  • floating_window

Use the floating_window module.

  • files

Use Node.js fs and path.

  • global functions and variables

  • sleep → delay from lang, e.g. await delay(1000)

  • toast / toastLog → showToast from toast, e.g. showToast("hello", { log: true })

  • exit → process.exit()

  • random → Math.random() (if you need an integer range, you can implement a helper):

    "nodejs";
function random(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() * (max - min + 1)) + min;
}
console.log(random(10, 30));

  • requiresApi → requiresAndroidVersion on OS (see device)

  • requiresAutojsVersion → check process.versions.autojspro

  • runtime.requestPermissions → this.requestPermissions on an Activity instance

  • runtime.loadJar / runtime.loadDex → $java.loadJar / $java.loadDex (see $java.loadDex)

  • context → $autojs.androidContext

  • http

Recommended: use the built-in axios module, which is more capable than the legacy HTTP helpers.

  • media

Use the media module.

  • plugins

Use the plugins module.

  • power_manager

Use the power_manager module.

  • sensors

Use the sensors module.

  • shell

Use the shell module.

  • storages

Use the datastore module.

  • settings

Use the settings module.

  • threads

See: Multithreading and async (below).

  • Timers

Use Node’s timers module. In practice setTimeout and setInterval are available as globals in the v2 runtime as well.

  • work_manager

Use the work_manager module.

  • ui

Use the ui module. UI APIs differ a lot from v1; see UI migration below and Threads and UI in the v9 README.

  • util

Use Node.js util.

  • WebSocket

Prefer the npm ws package instead of the old built-in WebSocket helper.

  • zip

Use the zip module.

Async and Promises

Understanding async/await and Promises is essential for v2: most I/O and Android-facing helpers return Promises instead of blocking the script thread like many v1 APIs did.

  • Use an async function as your script entry (for example main()), await any API that returns a Promise, and attach .catch(...) on the top-level promise so rejections are not silent.
  • Concurrency is not the same as parallel threads: await yields control back to the runtime; overlapping work is scheduled by the engine. For Java calls from JS, use thread hints on .invoke(...) (for example "ui" vs "io") as documented there.
  • For a broader mental model (event loop, timers, process.nextTick), follow any up-to-date Node.js or JavaScript async guide alongside this doc.

UI migration

The v2 UI stack (require("ui"), XML activities, JsWebView, and related modules) differs a lot from v1. Start from the English v9 README sections Threads and UI and UI entry headers, then read the ui barrel and submodules (ui/activity, ui/layout, ui/web, …).

Multithreading and async

v2 follows Node’s single-threaded JavaScript model: your code runs on one JS thread, while heavy or platform work runs on native/runtime threads behind Promise-based APIs. Prefer async composition over blocking sleeps; use worker threads or split processes only when you truly need parallel JS (advanced). See also Threads and UI in the v9 README.

Copyright © 2026 老猫