Migration Guides

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.