🤖 js-auto-robot

A Windows desktop automation library written in TypeScript. Control the mouse, keyboard, browser, and screen — no dependencies, pure Windows API via PowerShell.

Installation

npm install js-auto-robot

TypeScript Project Setup

Before using the library, make sure your project is configured for TypeScript.

1. Install the required dev dependencies:

npm i --save-dev typescript ts-node @types/node

2. Create a tsconfig.json in the root of your project:

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "esModuleInterop": true,
        "strict": true,
        "types": ["node"]
    }
}

3. Run your automation script:

npx ts-node index.ts

These are standard TypeScript project requirements, not specific to this library.

Setup

import { robot } from "js-auto-robot";

Or instantiate directly:

import { Robot } from "js-auto-robot";
const robot = new Robot();

Methods

sleep(ms)

Pauses execution for a given time.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | ------------------------ | | ms | number | — | Duration in milliseconds |

await robot.sleep(1000); // waits 1 second
await robot.sleep(500); // waits 500ms

press(key, wait?)

Presses a key or keyboard shortcut.

| Parameter | Type | Default | Description | | --------- | ---------- | ------- | -------------------------- | | key | PressKey | — | Key name (see table below) | | wait | number | 0 | Wait before executing (ms) |

Available keys:

| Key string | Action | | ------------------------ | --------------- | | 'enter' | Enter | | 'tab' | Tab | | 'esc' | Escape | | 'win' / 'windows' | Windows key | | 'copy' | Ctrl+C | | 'paste' | Ctrl+V | | 'F5', 'DELETE', etc. | Any key by name |

await robot.press("enter");
await robot.press("tab");
await robot.press("copy");
await robot.press("paste");
await robot.press("esc");
await robot.press("win");
await robot.press("F5");
await robot.press("enter", 1000); // waits 1s before pressing

write(text, wait?)

Types a full string of text.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | -------------------------- | | text | string | — | Text to type | | wait | number | 0 | Wait before executing (ms) |

await robot.write("Hello World");
await robot.write("[email protected]");
await robot.write("my search query", 500); // waits 500ms before typing
await robot.write("https://example.com", 1000);

sendKeys(keys, delay?)

Sends raw keys using the SendKeys format.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | --------------------------- | | keys | string | — | SendKeys format string | | delay | number | 500 | Delay after the action (ms) |

await robot.sendKeys("{TAB}");
await robot.sendKeys("^a"); // Ctrl+A (select all)
await robot.sendKeys("%{F4}"); // Alt+F4
await robot.sendKeys("^a", 1000); // Ctrl+A then waits 1s

moveTo(x, y, speedSeconds?, wait?)

Smoothly moves the mouse to a target position.
Coordinates are automatically scaled to the current screen resolution.

| Parameter | Type | Default | Description | | -------------- | -------- | ------- | ----------------------------------- | | x | number | — | Target X position (base resolution) | | y | number | — | Target Y position (base resolution) | | speedSeconds | number | 1 | Movement duration in seconds | | wait | number | 0 | Wait before executing (ms) |

await robot.moveTo(500, 300);
await robot.moveTo(500, 300, 0.5); // faster movement
await robot.moveTo(500, 300, 2); // slower movement
await robot.moveTo(500, 300, 1, 1000); // waits 1s then moves
await robot.moveTo(939, 131, 0.3); // quick snap

click(x, y, clicks?, button?, wait?)

Clicks at a specific screen position.

| Parameter | Type | Default | Description | | --------- | ------------------- | -------- | -------------------------- | | x | number | — | X position | | y | number | — | Y position | | clicks | number | 1 | Number of clicks | | button | 'left' \| 'right' | 'left' | Mouse button | | wait | number | 0 | Wait before executing (ms) |

await robot.click(500, 300);
await robot.click(500, 300, 2); // double click
await robot.click(500, 300, 1, "right"); // right click
await robot.click(500, 300, 2, "left", 1000); // double click after 1s
await robot.click(939, 131, 1, "left", 500);

scroll(percent, wait?)

Scrolls the page up or down.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | --------------------------------------------- | | percent | number | — | Scroll amount. Positive = up, Negative = down | | wait | number | 0 | Wait before executing (ms) |

await robot.scroll(50); // scroll up 50%
await robot.scroll(-50); // scroll down 50%
await robot.scroll(100); // scroll up 100%
await robot.scroll(-100); // scroll down 100%
await robot.scroll(-25, 1000); // wait 1s then scroll down 25%

selectArea(startX, startY, endX, endY, wait?)

Selects an area on screen by clicking and dragging.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | -------------------------- | | startX | number | — | Start X position | | startY | number | — | Start Y position | | endX | number | — | End X position | | endY | number | — | End Y position | | wait | number | 0 | Wait before executing (ms) |

await robot.selectArea(100, 200, 400, 500);
await robot.selectArea(100, 200, 400, 500, 1000); // waits 1s before selecting
await robot.selectArea(50, 50, 800, 600); // large area selection

open(type?, isPrivate?, wait?)

Opens a new browser tab or window.

| Parameter | Type | Default | Description | | ----------- | ------------------- | ------- | -------------------------- | | type | 'tab' \| 'window' | 'tab' | Tab or new window | | isPrivate | boolean | false | Private/incognito mode | | wait | number | 0 | Wait before executing (ms) |

await robot.open(); // new tab
await robot.open("tab"); // new tab
await robot.open("tab", true); // new private tab
await robot.open("window"); // new window
await robot.open("window", true); // new private window
await robot.open("tab", false, 1000); // new tab after 1s
await robot.open("window", true, 2000); // new private window after 2s

getCoords(wait?)

Prints the current mouse position to the terminal.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | -------------------------- | | wait | number | 0 | Wait before capturing (ms) |

await robot.getCoords();
// Output: X=512 Y=400

await robot.getCoords(3000); // waits 3s before capturing

Useful while building automations — call it after a sleep so you have time to position the mouse before the coordinate is captured.

getResolution()

Returns the current screen resolution.

const { width, height } = await robot.getResolution();
console.log(width, height); // e.g. 1920 1080

scaleCoords(x, y)

Scales coordinates from the base resolution to the current screen resolution.
Called automatically by moveTo and click — you rarely need this directly.

const { x, y } = await robot.scaleCoords(500, 300);

Full Example

import { robot } from "js-auto-robot";

async function main() {
    // Open Edge and navigate to a URL
    await robot.press("win", 1000);
    await robot.write("edge", 500);
    await robot.press("enter", 1000);
    await robot.write("https://example.com", 2000);
    await robot.press("enter", 1500);

    // Click the search bar
    await robot.click(760, 45, 1, "left", 1000);

    // Select all text and replace it
    await robot.press("copy");
    await robot.write("https://other-site.com");
    await robot.press("enter");

    // Scroll down halfway
    await robot.scroll(-50, 1000);

    // Select a region and copy it
    await robot.selectArea(100, 200, 700, 500, 1000);
    await robot.press("copy");
}

main();

Resolution Scaling

Automations are built against a base resolution defined inside the library (default: 1536x864). When running on a different machine, all coordinates passed to moveTo and click are automatically scaled proportionally — no changes needed in your scripts.

To find your base resolution, run in your terminal:

powershell -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Screen]::PrimaryScreen.Bounds.Width; [System.Windows.Forms.Screen]::PrimaryScreen.Bounds.Height"

Requirements

• Windows 10 or 11
• Node.js 16+
• PowerShell 5+ (included in Windows by default)