🚀 Browser Automation with Stagehand & Browserbase

A powerful, production-ready browser automation toolkit built with Stagehand and Browserbase. Automate complex web interactions, scrape data, test responsive designs, and build intelligent web agents with AI-powered browser control.

✨ Why This Tool?

Traditional browser automation is brittle and maintenance-heavy. Stagehand + Browserbase changes the game:

• 🧠 AI-Powered Actions - Natural language commands that adapt to UI changes
• ☁️ Cloud Browser Infrastructure - No local Chrome management, instant scalability
• 🎯 Intelligent Element Detection - Robust selectors that survive DOM changes
• 📸 Built-in Debugging - Screenshots, session replays, detailed logging
• 🔄 Easy Scaling - Run hundreds of browsers in parallel
• 🎨 Viewport Testing - Test across any device size or resolution

🎯 Use Cases

This toolkit enables countless automation scenarios:

🕷️ Web Scraping & Data Collection

• Extract structured data from dynamic websites
• Monitor competitor pricing and inventory
• Aggregate content from multiple sources
• Build custom APIs from websites without APIs

🧪 Testing & QA

• Responsive design testing across devices
• Cross-browser compatibility checks
• E2E testing for complex user flows
• Visual regression testing

🤖 Intelligent Web Agents

• Automated form filling and submissions
• Social media automation
• Lead generation and research
• Content posting and management

🔍 SEO & Marketing

• SERP scraping and ranking analysis
• Competitor analysis automation
• Content audit and analysis
• Link checking and validation

📊 Business Intelligence

• Market research automation
• Real-time data monitoring
• Automated reporting
• Trend analysis

🚀 Quick Start

Prerequisites

• Node.js 18+
• pnpm (or npm/yarn)
• Browserbase account (free tier available)
• OpenAI API key (for AI-powered actions)

Installation

# Clone the repository
git clone https://github.com/laurentknauss/browser-automation.git
cd browser-automation

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your API keys:
# - BROWSERBASE_API_KEY
# - BROWSERBASE_PROJECT_ID
# - OPENAI_API_KEY

Your First Script

pnpm start

📖 Example Scripts

Basic Navigation & Extraction

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();

// Navigate and extract data
await stagehand.page.goto("https://example.com");
const data = await stagehand.page.extract({
  instruction: "Extract all product names and prices",
  schema: z.object({
    products: z.array(z.object({
      name: z.string(),
      price: z.string()
    }))
  })
});

console.log(data);
await stagehand.close();

AI-Powered Interaction

// Natural language browser control
await stagehand.page.act("Click the 'Sign Up' button");
await stagehand.page.act("Fill in the email field with test@example.com");
await stagehand.page.act("Submit the form");

// Check what happened
const result = await stagehand.page.extract({
  instruction: "Did the signup succeed? What message is shown?",
  schema: z.object({
    success: z.boolean(),
    message: z.string()
  })
});

Multi-Viewport Testing

const viewports = [
  { name: "Mobile", width: 393, height: 851 },
  { name: "Tablet", width: 768, height: 1024 },
  { name: "Desktop", width: 1920, height: 1080 }
];

for (const viewport of viewports) {
  await stagehand.page.setViewportSize(viewport);
  await stagehand.page.screenshot({
    path: `${viewport.name.toLowerCase()}.png`
  });

  // Extract responsive design info
  const layout = await stagehand.page.extract({
    instruction: "Describe the layout and navigation structure",
    schema: z.object({
      navigation: z.string(),
      layout: z.string()
    })
  });

  console.log(`${viewport.name}:`, layout);
}

🛠️ Project Structure

browser-automation/
├── index.ts              # Main entry point (current example: mobile nav testing)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .cursorrules          # AI coding assistant rules
├── .env.example          # Environment variables template
└── README.md             # This file

🔧 Configuration

Local vs Cloud Execution

// Cloud execution (recommended for production)
const stagehand = new Stagehand({
  env: "BROWSERBASE"
});

// Local execution (for development)
const stagehand = new Stagehand({
  env: "LOCAL",
  headless: false  // See the browser in action
});

Custom Configuration

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  enableCaching: true,
  debugDom: true,
  // Add more options as needed
});

📚 Resources

• Stagehand Documentation
• Browserbase Documentation
• Examples Gallery
• Community Discord

🤝 Contributing

Contributions are welcome! Whether it's:

• 🐛 Bug fixes
• ✨ New features
• 📖 Documentation improvements
• 💡 Use case examples

Please feel free to open issues or submit pull requests.

📝 License

MIT License - feel free to use this in your projects!

🌟 Show Your Support

If this project helps you, please consider:

• ⭐ Starring the repository
• 🔀 Forking for your own use cases
• 📢 Sharing with others who might benefit
• 🐛 Reporting issues or suggesting improvements

🔗 Related Projects

• Stagehand - The AI-powered browser SDK
• Browserbase - Cloud browser infrastructure
• Playwright - Browser automation library (Stagehand's foundation)

---

Built with ❤️ using Stagehand and Browserbase

Need help? Open an issue or reach out!