Prerequisites

Please make sure to follow the installation guide to get all prerequisites set up.

Installation

With our prerequisites met, let’s continue installing. The following steps are meant to be carried out in a dedicated directory of your choice. We will simply refer to this directory as working directory.

npm project

Let’s first initialize a new npm project in our working directory by executing:

npm init

Feel free to fill out the interactive dialogue, but it’s not a hard requirement to continue the initial setup.

(You could even accept all defaults by running npm init -y)

Install nut.js

Running

npm i @nut-tree/nut-js

or

yarn add @nut-tree/nut-js

in our newly created npm project will install nut.js and its required dependencies.

Get Things Moving

Now that we're all set up it's time to get things moving!

In our working directory, let's create a new file, index.js.

Open it in your favourite editor and add the following lines to get started:

const { mouse } = require("@nut-tree/nut-js");

(async () => {
    
})();

mouse gives you control over your, well, mouse, so let's play around with it a bit!

Attention: nut.js is fully async, so in most examples you will see something like the above snippet, which is an async IIFE used as a workaround to use async / await at the top-level.

Simple Movement

const { mouse, left, right, up, down } = require("@nut-tree/nut-js");

(async () => {
    await mouse.move(left(500));
    await mouse.move(up(500));
    await mouse.move(right(500));
    await mouse.move(down(500))
})();

nut.js provides a declarative API, so instead of explicitly stating where we want our cursor to be, we can use the MovementApi functions to move our cursor relative to our current position.

When executed via node index.js you'll see that your cursor moves along a square and ends up at its initial position.

Targeting Specific Points

Moving our cursor in up, down, left or right direction is a good start, but we're not sitting in front of an Etch A Sketch. Let's see how we can target specific points on our screen.

const { mouse, straightTo, Point } = require("@nut-tree/nut-js");

(async () => {
    const target = new Point(500, 350);
    
    await mouse.move(straightTo(target));
})();

straightTo is another MovementApi function which takes a target Point and computes a straight line towards it, starting at our current cursor position.

Speeding up / Slowing down

In case you want to configure mouse movement speed to go faster / slower, every instance exposed by nut.js provides a config object.

The mouse config object allows you to configure movement speed measured in pixels per second.

const { mouse, straightTo, Point } = require("@nut-tree/nut-js");

(async () => {
    mouse.config.mouseSpeed = 2000;
    const fast = new Point(500, 350);
    await mouse.move(straightTo(fast));
    mouse.config.mouseSpeed = 100;
    const slow = new Point(100, 150);
    await mouse.move(straightTo(slow));
})();

Beam me up, Scotty!

Sometimes we don't want to move along a path to reach a certain point.

In such cases, we can rely on setPosition to immediately change our cursor position to the provided Point.

const { mouse, Point } = require("@nut-tree/nut-js");

(async () => {
    const target = new Point(500, 350);
    await mouse.setPosition(target);
})();

Summary

• nut.js provides a mouse instance to control your cursor.
• Movement speed in pixels / second is configurable via the config object.
• It provides a high-level MovementApi for easy relative mouse movement.
• For fast changes of cursor position, setPosition is the right tool.