AutoAnchorJS

A cross-platform automation library that uses Rust binaries for high-performance cursor, mouse, and keyboard control. Similar to nutjs or robotjs, but with the reliability and performance of Rust.

Overview

AutoAnchorJS was built not only to provide robust automation capabilities but also to address the shortcomings of existing libraries. By leveraging Rust for the backend, AutoAnchorJS ensures high performance and stability across all major operating systems. The Node.js frontend offers a simple and intuitive API, making it easy for developers to integrate automation features into their applications.

AutoAnchorJS is used internally at Anchorclick to power our new RPA (Robotic Process Automation) Desktop agent (wip), enabling us to automate desktop tasks efficiently and reliably with AI-powered workflows.

Features

• 🖱️ Mouse Control: Move cursor, click (left/right/middle), get position
• ⌨️ Keyboard Input: Type text, press keys, keyboard shortcuts
• 📺 Screen Info: Get screen dimensions
• 🚀 High Performance: Rust backend for maximum speed and reliability
• 🌍 Cross-Platform: Windows, macOS, and Linux support
• 📦 Easy to Use: Simple JavaScript/TypeScript API
• 🔧 TypeScript Support: Full type definitions included

Installation

npm install autoanchorjs

Quick Start

const autoAnchor = require('autoanchorjs');

async function example() {
  // Get current cursor position
  const position = await autoAnchor.getCursorPosition();
  console.log(`Cursor at: ${position.x}, ${position.y}`);

  // Move cursor to center of screen
  const screenSize = await autoAnchor.getScreenSize();
  await autoAnchor.moveCursor(screenSize.x / 2, screenSize.y / 2);

  // Click at current position
  await autoAnchor.leftClick();

  // Type some text
  await autoAnchor.typeText('Hello, AutoAnchor!');

  // Press Enter
  await autoAnchor.pressEnter();
}

API Reference

Mouse Functions

getCursorPosition(): Promise<Point>/

Get the current cursor position.

const position = await autoAnchor.getCursorPosition();
console.log(`x: ${position.x}, y: ${position.y}`);

moveCursor(x: number, y: number): Promise<void>

Move the cursor to the specified coordinates.

await autoAnchor.moveCursor(100, 200);

click(button?: 'left' | 'right' | 'middle', x?: number, y?: number): Promise<void>

Click at the specified coordinates or current position.

// Click at current position
await autoAnchor.click();

// Click at specific coordinates
await autoAnchor.click('left', 100, 200);

// Right click at current position
await autoAnchor.click('right');

leftClick(x?: number, y?: number): Promise<void>

Convenience method for left clicking.

await autoAnchor.leftClick(100, 200);

rightClick(x?: number, y?: number): Promise<void>

Convenience method for right clicking.

await autoAnchor.rightClick();

middleClick(x?: number, y?: number): Promise<void>

Convenience method for middle clicking.

await autoAnchor.middleClick();

Keyboard Functions

typeText(text: string, delayMs?: number): Promise<void>

Type text at the current cursor position. Optionally supply delayMs to slow down typing (milliseconds per key). The default per-key delay is 50ms.

// Default (50ms per key)
await autoAnchor.typeText('Hello, World!');

// Slower typing (100ms per key)
await autoAnchor.typeText('Hello, World!', 100);

pressKey(key: string, modifiers?: string[]): Promise<void>

Press a key with optional modifiers.

// Press a single key
await autoAnchor.pressKey('enter');

// Press key with modifiers
await autoAnchor.pressKey('c', ['ctrl']); // Ctrl+C
await autoAnchor.pressKey('v', ['ctrl', 'shift']); // Ctrl+Shift+V

Screen Functions

getScreenSize(): Promise<Point>

Get the screen dimensions.

const screenSize = await autoAnchor.getScreenSize();
console.log(`Screen: ${screenSize.x}x${screenSize.y}`);

takeScreenshot(activeWindow?: boolean): Promise<Buffer>

Take a screenshot of the entire screen (default) or, if activeWindow is true, of the current active/foreground window.

// Full screen
const screenshot = await autoAnchor.takeScreenshot();
require('fs').writeFileSync('screenshot.png', screenshot);

// Active window only
const active = await autoAnchor.takeScreenshot(true);
require('fs').writeFileSync('screenshot-active.png', active);

Convenience Methods

await autoAnchor.pressEnter();    // Press Enter
await autoAnchor.pressTab();      // Press Tab
await autoAnchor.pressEscape();   // Press Escape
await autoAnchor.pressCtrlC();    // Press Ctrl+C
await autoAnchor.pressCtrlV();    // Press Ctrl+V
await autoAnchor.pressCtrlA();    // Press Ctrl+A

Screen Functions

getScreenSize(): Promise<Point>

Get the screen dimensions.

const screenSize = await autoAnchor.getScreenSize();
console.log(`Screen: ${screenSize.x}x${screenSize.y}`);

Supported Keys

Special Keys

• enter, return
• space
• tab
• escape, esc
• backspace
• delete

Modifier Keys

• ctrl, control
• alt, option (macOS)
• shift
• cmd, command (macOS)
• win, windows (Windows)
• super (Linux)

Arrow Keys

• up
• down
• left
• right

Function Keys

• f1 through f12

Letters and Numbers

• a through z
• 0 through 9

Platform Support

| Platform | Architecture | Status | | -------- | ------------ | ------ | | Windows | x64 | ✅ | | Windows | ARM64 | ✅ | | macOS | x64 | ✅ | | macOS | ARM64 | ✅ | | Linux | x64 | ✅ | | Linux | ARM64 | ✅ |

Development

Prerequisites

• Node.js 14+
• Rust 1.70+
• Platform-specific dependencies:
  • Windows: Visual Studio Build Tools
  • macOS: Xcode Command Line Tools
  • Linux: libx11-dev, libxtst-dev

Building

# Install dependencies
npm install

# Build for current platform
npm run build

# Build for all platforms (requires cross-compilation setup)
npm run build:cross-platform

# Build only Rust
npm run build:rust

# Build only TypeScript
npm run build:js

Testing

npm test

Examples

Run the examples to see AutoAnchor in action:

# Basic usage example
node examples/basic-usage.js

# Advanced usage example
node examples/advanced-usage.js

How It Works

AutoAnchor uses a hybrid architecture:

1. Rust Backend: High-performance, cross-platform automation logic
2. Node.js Frontend: JavaScript/TypeScript API that spawns Rust processes
3. Binary Distribution: Pre-compiled Rust binaries for each platform

The Rust binary handles all the low-level system calls for mouse and keyboard control, while the Node.js layer provides a clean, promise-based API.

Comparison with Other Libraries

| Feature | AutoAnchorJS | nut.js | RobotJS | | ----------- | ------------ | ------ | ------- | | Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | | TypeScript | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | Maintenance | ⭐⭐⭐⭐ | ⭐ | ⭐ | | Bundle Size | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | | | | | |

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

Binary not found error

• Make sure you've run npm run build after installation
• Check that the binary exists in binaries/[platform]/[arch]/

Permission denied (Linux/macOS)

• You may need to grant accessibility permissions
• On macOS: System Preferences → Security & Privacy → Accessibility
• On Linux: Ensure your user is in the appropriate groups

Build failures

• Ensure you have the required build tools installed
• Check that Rust is properly installed: rustc --version
• Verify platform-specific dependencies are installed

Getting Help

• Check the Issues page
• Create a new issue with detailed information about your problem
• Include your platform, Node.js version, and error messages