Browser automation powered by LLMs in JavaScript/TypeScript.

⚠️ IMPORTANT NOTE ⚠️

This library is currently under heavy development and NOT READY FOR PRODUCTION USE. The API is unstable and subject to major changes.

See ROADMAP.md for the current development status and priorities.

browser-use-node is a powerful library that combines browser automation capabilities with Large Language Models (LLMs) to create intelligent browser interactions. Built on top of Playwright and LangChain, it provides a seamless way to automate browser tasks with AI assistance.

This is a JavaScript/TypeScript port of the original browser-use Python library.

This project is based on browser-use, originally created by:

• Shroominic
• LangChain

We are grateful for their pioneering work in browser automation with LLMs.

• LLM-powered browser automation
• Multi-tab support
• Built on reliable technologies (Playwright, LangChain)
• TypeScript support
• Modern async/await API

⚠️ Note: These instructions are for development purposes only. The library is not yet ready for production use.

The package is available on npm for experimental purposes:

# ⚠️ Not recommended for production use
npm install browser-use-node

Note: While the package is available on npm as browser-use-node, it's currently intended for exploration only. The API is unstable and will undergo significant changes. For development and contributions, please use the development setup below.

• Bun (Required for development)
• A modern browser (Chrome/Firefox/Edge)

1. Clone the repository:

   git clone https://github.com/browser-use/browser-use-node.git
   cd browser-use-node

2. Install dependencies:

   bun install

3. Set up environment variables:

   cp .env.example .env

   Edit .env and add your API keys and configuration:

   • OPENAI_API_KEY - Required for LLM functionality
   • Other configuration options as needed

The examples/ directory contains sample scripts demonstrating various features:

bun run examples/amazon-search.ts

⚠️ These are development tests. The test suite is still being expanded.

# Run all tests
bun test

# Run specific test suite
bun test --grep "Browser"

# Run tests in watch mode
bun test --watch

When contributing new features or fixes:

1. Add tests in the tests/ directory
2. Follow the existing test patterns
3. Include both unit and integration tests where applicable
4. Use the provided test utilities in tests/utils/

For development debugging:

1. Use the DEBUG environment variable:

   DEBUG=browser-use* bun test

2. Chrome DevTools are available when running browser tests
3. VSCode launch configurations are provided in .vscode/launch.json

Bun is used as the primary runtime because it provides:

• Faster dependency installation
• Quicker test execution
• Better TypeScript performance
• Improved overall development experience
• Native test runner with better performance
• Built-in TypeScript support
• Ability to build as a native binary or jsc bytecode which is a huge performance boost

# Building
bun run build           # Build the project
bun run clean          # Clean build artifacts

# Development
bun run type-check     # Run TypeScript type checking
bun run format         # Format code with Prettier
bun run lint          # Run ESLint
bun run prepare        # Run build before publishing

# Examples
bun run example:amazon     # Run Amazon search example
bun run example:multi-tab  # Run multi-tab example
bun run example:simple     # Run simple example

# Testing
bun run test           # Run all tests
bun run test:smoke     # Run smoke tests

# Documentation
bun run docs:dev       # Start documentation development server
bun run docs:build     # Build documentation
bun run docs:serve     # Serve built documentation
bun run docs:clear     # Clear documentation cache
bun run docs:generate-api # Generate API documentation
bun run docs           # Generate API docs, build and serve

The project generates these outputs in the dist directory:

• Main bundle (target: bun)
• TypeScript declaration files
• Example builds
• Native binary (experimental)

1. Start with an example:

   bun run example:simple

   This helps verify your setup is working.

2. Before committing:

   bun run type-check  # Check types
   bun run format      # Format code
   bun run lint        # Check for issues
   bun run test        # Run tests

The project supports various environment configurations:

# Required
OPENAI_API_KEY=your_key_here

# Optional
DEBUG=browser-use*           # Enable debug logging
HEADLESS=false             # Run browsers in headed mode

For the best development experience:

1. VSCode Extensions:

   • ESLint
   • Prettier
   • TypeScript and JavaScript
   • Playwright Test for VSCode

2. Recommended VSCode settings are provided in .vscode/settings.json

1. Browser Debugging:

   # Run with browser debugging enabled
   DEBUG=browser-use* HEADLESS=false bun run example:simple

2. Test Debugging:

   # Run tests with debug output
   DEBUG=browser-use* bun test

• Use the build:binary option for maximum performance and maximum risks

The project uses Docusaurus for documentation and TypeDoc for API reference.

# Start development server
bun run docs:dev

# Build documentation
bun run docs:build

# Serve built documentation
bun run docs:serve

# Generate API documentation
bun run docs:generate-api

• /docs/ - Main documentation site
  • /docs/intro - Getting started guide
  • /docs/guides - Usage guides and tutorials
  • /docs/api - Auto-generated API documentation
  • /docs/examples - Example usage and code snippets

1. Documentation source files are in Markdown format
2. API documentation is generated from TypeScript source code comments
3. Examples should include both code and explanation
4. Follow the documentation style guide

We welcome contributions! Please see our Contributing Guidelines for details on how to get started and our development process. By participating in this project, you agree to abide by our Code of Conduct.

We take security seriously. If you discover a security vulnerability, please follow our Security Policy for responsible disclosure.

• Node.js 16+
• Bun (for development)
• Required packages:
  • Playwright ^1.49.1
  • LangChain ^0.1.0
  • @langchain/openai ^0.0.10
  • Other dependencies as listed in package.json

• TypeScript ^5.3.3
• ESLint ^8.56.0
• Prettier ^3.1.1
• Various type definitions (@types/*)

Current Version: 0.1.11