Migration paths to nut.js 3.0.0

Breaking changes introduced with nut.js version 3.0.0


With the improvements to screen.find and its siblings, OptionalSearchParameters received an update as well.
It no longer carries a searchMultipleScales property, but instead now holds a generic providerData property.
The searchMultipleScales property stemmed from a time when screen.find was limited to image search, but with the
introduction of different find providers, this property did not make sense anymore.

Instead, search provider specific configuration like searchMultipleScales can now be passed via the providerData

Required changes from a users perspective

Instead of setting searchMultipleScales on OptionalSearchParameters, you now have to pass it via providerData:

1await screen.find(imageResource("my-image.png"), {
2    providerData: {
3        searchMultipleScales: true
4    },

Required changes from a developer perspective

Developers of custom nut.js providers have to adjust their packages such that they'll correctly handle providerData.
To ensure compatibility with nut.js 3.0.0, you could add a peerDependency to @nut-tree/nut-js version 3.0.0 or higher in your providers package.json.

2  ...
3  "peerDependencies": {
4    "@nut-tree/nut-js": ">=3.0.0"
5  },
6  ...

It's also considered a good practice to export an interface that describes the structure of providerData for a given provider.


The Image class has been adjusted to also carry information about an images bits per pixel and byte width.

If you are loading images using the existing loader functions like loadImage or imageResource, you don't have to adjust anything.

In case you're manually creating Image instances, please make sure to also provide the newly added properties bitsPerPixel and byteWidth.


The previous naming scheme of clipboard.copy(...) and clipboard.paste(...) repeatedly caused people to think it would literally copy and paste content to the environment,
instead of just setting/getting the current clipboard content.

To avoid further confusion, the copy and paste methods have been renamed to setContent and getContent respectively.

1// Pre 3.0.0
2await clipboard.copy("Hello World");
4// 3.0.0
5await clipboard.setContent("Hello World");
1// Pre 3.0.0
2const clipboardContent = await clipboard.paste();
4// 3.0.0
5const clipboardContent = await clipboard.getContent();

© 2023