Introduction

Configuration

Configure nut.js behavior through config objects on keyboard, mouse, and screen.

Overview

Each nut.js module exposes a config object that controls its runtime behavior. You set properties on these objects before (or between) operations — there are no config files or initialization functions required. Changes take effect immediately.

typescript

import { keyboard, mouse, screen } from "@nut-tree/nut-js";

// Configure each module directly
keyboard.config.autoDelayMs = 50;
mouse.config.mouseSpeed = 1500;
screen.config.confidence = 0.9;

Keyboard Configuration

autoDelayMs

keyboard.config.autoDelayMs: number

default: 300

Delay in milliseconds between individual key events. Higher values make typing more realistic; lower values make it faster.

abortSignal

keyboard.config.abortSignal?: AbortSignal

default: undefined

Optional global abort signal for cancellable keyboard actions like type(). When the signal is aborted, the ongoing operation will be cancelled.

typescript

import { keyboard } from "@nut-tree/nut-js";

// Slow, human-like typing
keyboard.config.autoDelayMs = 100;
await keyboard.type("Typing slowly...");

// Fast typing
keyboard.config.autoDelayMs = 10;
await keyboard.type("Typing quickly!");

// No delay between keystrokes
keyboard.config.autoDelayMs = 0;
await keyboard.type("Instant");

// Cancel a long typing operation
const controller = new AbortController();
keyboard.config.abortSignal = controller.signal;
setTimeout(() => controller.abort(), 1000);
await keyboard.type("This will be cancelled after 1 second");

When to Adjust

Some applications miss keystrokes when typing is too fast. If you notice dropped characters, increase autoDelayMs.

Mouse Configuration

mouseSpeed

mouse.config.mouseSpeed: number

default: 1000

Mouse movement speed in pixels per second. Higher values move the cursor faster.

autoDelayMs

mouse.config.autoDelayMs: number

default: 100

Delay in milliseconds between consecutive mouse actions (clicks, moves, scrolls).

abortSignal

mouse.config.abortSignal?: AbortSignal

default: undefined

Optional global abort signal for cancellable mouse actions like move() and drag(). When the signal is aborted, the ongoing operation will be cancelled.

typescript

import { mouse } from "@nut-tree/nut-js";

// Slow, visible cursor movement
mouse.config.mouseSpeed = 500;

// Fast cursor movement
mouse.config.mouseSpeed = 3000;

// No delay between mouse actions
mouse.config.autoDelayMs = 0;

Debugging

Lower mouseSpeed values make it easier to follow what your automation script is doing. Increase it for faster execution in production.

Screen Configuration

Image Search

confidence

screen.config.confidence: number

default: 0.99

Global confidence threshold for image matching (0.0 to 1.0). A match must meet or exceed this value to be considered valid. Can be overridden per search call.

resourceDirectory

screen.config.resourceDirectory: string

default: process.cwd()

Path to the directory containing reference images used with imageResource(). Resolved relative to process.cwd().

typescript

import { screen, imageResource } from "@nut-tree/nut-js";

// Set where reference images are stored
screen.config.resourceDirectory = "./images";

// Lower the global confidence threshold
screen.config.confidence = 0.9;

// Per-search override (takes precedence over global config)
const match = await screen.find(imageResource("button.png"), {
    confidence: 0.85,
});

Highlighting

autoHighlight

screen.config.autoHighlight: boolean

default: false

When enabled, automatically draws a highlight overlay on matched regions after find/waitFor operations. Useful for debugging.

highlightDurationMs

screen.config.highlightDurationMs: number

default: 500

How long the highlight overlay is displayed in milliseconds.

highlightOpacity

screen.config.highlightOpacity: number

default: 0.25

Opacity of the highlight overlay (0.0 fully transparent to 1.0 fully opaque).

typescript

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

// Enable auto-highlighting for debugging
screen.config.autoHighlight = true;
screen.config.highlightDurationMs = 1000;
screen.config.highlightOpacity = 0.5;

Common Patterns

Centralized Setup

Configure everything once at the start of your script or test setup:

typescript

import { keyboard, mouse, screen } from "@nut-tree/nut-js";

// -- Setup --
keyboard.config.autoDelayMs = 50;
mouse.config.mouseSpeed = 1500;
mouse.config.autoDelayMs = 50;
screen.config.resourceDirectory = "./images";
screen.config.confidence = 0.9;
screen.config.autoHighlight = true;

// -- Automation --
// All operations below use the config above
await screen.find(imageResource("target.png"));
await keyboard.type("Hello!");

Test Framework Setup

In test frameworks, configure nut.js in a beforeAll or setup file:

typescript

import { test } from "@playwright/test";
import { keyboard, mouse, screen } from "@nut-tree/nut-js";

test.beforeAll(() => {
    keyboard.config.autoDelayMs = 50;
    mouse.config.autoDelayMs = 50;
    mouse.config.mouseSpeed = 1500;
    screen.config.resourceDirectory = "./test-images";
    screen.config.confidence = 0.9;
});

Temporary Config Changes

Change a config value for a specific operation, then restore it:

typescript

import { keyboard } from "@nut-tree/nut-js";

// Normal speed
keyboard.config.autoDelayMs = 50;
await keyboard.type("Normal speed");

// Slow down for a password field that drops characters
keyboard.config.autoDelayMs = 150;
await keyboard.type("s3cur3_p@ss");

// Restore normal speed
keyboard.config.autoDelayMs = 50;

Quick Reference

Property	Type	Description
`keyboard.config.autoDelayMs`	number	Delay between key events (ms)
`keyboard.config.abortSignal`	AbortSignal?	Cancel keyboard operations
`mouse.config.mouseSpeed`	number	Cursor movement speed (px/s)
`mouse.config.autoDelayMs`	number	Delay between mouse actions (ms)
`mouse.config.abortSignal`	AbortSignal?	Cancel mouse operations
`screen.config.confidence`	number	Image match threshold (0–1)
`screen.config.resourceDirectory`	string	Path to reference images
`screen.config.autoHighlight`	boolean	Highlight matches on screen
`screen.config.highlightDurationMs`	number	Highlight display time (ms)
`screen.config.highlightOpacity`	number	Highlight overlay opacity (0–1)

Mouse Control

Full mouse control documentation

Keyboard Input

Full keyboard input documentation

Screen

Screen dimensions, capture, and regions

Image Search

Image-based element detection