Migration Guides

Migrating to v5.0.0

nut.js 5.0.0 is a major release that raises the minimum Node.js version to 22, drops support for older macOS versions, changes several core APIs, and requires explicit registration for plugins that previously auto-registered on import.

Node.js 22+ Required

All packages in the nut.js ecosystem now require Node.js v22 or later. This applies to @nut-tree/nut-js, @nut-tree/bolt, @nut-tree/libnut, @nut-tree/plugin-ocr, and other packages.

macOS 14+ Required

Support for macOS versions older than 14 (Sonoma) has been dropped in @nut-tree/nut-js, @nut-tree/bolt, and @nut-tree/libnut. If you need to support older macOS versions, stay on the v4.x release line.

screen.grabRegion / screen.captureRegion Removed

The dedicated screen.grabRegion(region) and screen.captureRegion(fileName, region) methods have been removed. Instead, screen.grab and screen.capture now accept an optional region parameter directly.

// Before
const image = await screen.grabRegion(region);
await screen.captureRegion("screenshot.png", region);

// After
const image = await screen.grab(region);
await screen.capture("screenshot.png", region);

mouse.move Is Now Non-Blocking

mouse.move is now non-blocking. If your code depends on the mouse having arrived at its destination before continuing, make sure you await the call. While most existing code already awaits mouse operations, any fire-and-forget usage will behave differently.

// Make sure to await mouse.move
await mouse.move(straightTo(centerOf(region)));
await mouse.click(Button.LEFT);

Explicit Plugin Registration

Several plugins that previously auto-registered on import now require an explicit setup call. This gives you control over when providers are initialized and avoids side effects on import.

// Before — auto-registered on import
import "@nut-tree/nl-matcher";
import "@nut-tree/plugin-ocr";
import "@nut-tree/element-inspector";

// After — explicit registration
import { useNlMatcher } from "@nut-tree/nl-matcher";
import { useOcrPlugin } from "@nut-tree/plugin-ocr";
import { useElementInspector } from "@nut-tree/element-inspector";

useNlMatcher();
useOcrPlugin();
useElementInspector();

Affected packages:

• @nut-tree/nl-matcher — call useNlMatcher()
• @nut-tree/plugin-ocr — call useOcrPlugin()
• @nut-tree/element-inspector — call useElementInspector()

ESM / CJS Dual Module Support

All packages now ship both CommonJS and ESM builds. This should be transparent for most users, but if you were relying on internal file paths or require resolution behavior, review the exports field in each package's package.json.

Companion Package Versions

When upgrading to nut.js 5.0.0, update all companion packages to their latest major versions:

• @nut-tree/bolt@3.0.0
• @nut-tree/libnut@3.0.0
• @nut-tree/nl-matcher@5.0.1
• @nut-tree/plugin-ocr@4.0.0
• @nut-tree/element-inspector@1.0.0
• @nut-tree/plugin-ai-sdk@1.0.0 (new)
• @nut-tree/plugin-screenrecording@1.1.0 (new)

API Documentation Moved

Type docs are no longer published to nut-tree.github.io/apidoc. API reference documentation is now integrated into the nutjs.dev website.

Migrating to v4.0.0

nut.js 4.0.0 includes two breaking changes: a fix for OCR confidence overrides and an updated Node.js version requirement.

OCR Confidence Override Fix

Custom ocrConfidence values weren't being properly passed to image and text-search providers, preventing users from applying confidence overrides. This has been fixed by redesigning how confidence values flow through the system.

• @nut-tree/plugin-ocr@2.0.1
• @nut-tree/plugin-azure@2.0.1
• @nut-tree/nl-matcher@3.0.0

Node.js Version Requirement

The minimum supported Node.js version has been increased to Node 16 or later due to dependency updates in 4.0.0.

Migrating to v3.0.0

nut.js 3.0.0 includes breaking changes affecting search parameters, image handling, and the clipboard API.

OptionalSearchParameters Changes

The OptionalSearchParameters object was restructured to support multiple search providers more effectively. It no longer carries a searchMultipleScales property, but instead now holds a generic providerData property.

Provider-specific settings now nest within providerData:

// Before
await screen.find(imageResource("my-image.png"), {
    searchMultipleScales: true
});

// After
await screen.find(imageResource("my-image.png"), {
    providerData: {
        searchMultipleScales: true
    },
});

{
  "peerDependencies": {
    "@nut-tree/nut-js": ">=3.0.0"
  }
}

Image Class Metadata

The Image class now includes metadata about pixel depth and byte width. If you're using standard loader functions (loadImage, imageResource), no changes are needed.

If you manually instantiate Image objects, you must now provide the new bitsPerPixel and byteWidth properties.

Clipboard API Renaming

Method names were changed to reduce confusion about actual clipboard operations versus content retrieval:

• clipboard.copy() → clipboard.setContent()
• clipboard.paste() → clipboard.getContent()

// Before
await clipboard.copy("Hello World");
const text = await clipboard.paste();

// After
await clipboard.setContent("Hello World");
const text = await clipboard.getContent();

Migrating to v2.0.0

nut.js 2.0.0 introduced a plugin architecture for image matching, along with changes to how screen search methods work.

ImageFinder Providers

nut.js shifted to a plugin architecture and no longer ships image matching code by default. You must install a separate provider package to enable image matching functionality.

npm install @nut-tree/template-matcher

Then require the provider in your code:

import { screen } from "@nut-tree/nut-js";
import "@nut-tree/template-matcher";

screen.find() Changes

Template images no longer load automatically from screen.config.resourceDirectory. You must pass an Image object directly or wrap filenames using the imageResource() helper.

// Before
await screen.find("file.png");

// After
await screen.find(imageResource("file.png"));

screen.waitFor() Updates

Two changes affect screen.waitFor():

1. Template Image Handling: Same requirement as screen.find() — use the imageResource() wrapper
2. Configurable Interval: The polling interval is now parameterizable (previously hardcoded at 500ms)

// Before
await screen.waitFor("file.png", 3000);

// After (3000ms timeout, 500ms polling interval)
await screen.waitFor(imageResource("file.png"), 3000, 500);

LocationParameters Deprecation

The LocationParameters object has been removed entirely. Use OptionalSearchParameters as the replacement.