Before submitting an issue, please:

• Check the documentation for relevant information
• Search existing issues to avoid duplicates

Environment Information

Please provide the following information to help us reproduce and resolve your issue:

Stagehand:

• Language/SDK: TypeScript / Node.js
• Stagehand version: 3.0.6
• Framework: Next.js 16.0.10 with Turbopack
• Package Manager: pnpm 9.x

AI Provider:

• Provider: Multiple (OpenAI, Anthropic, Google)
• Model: claude-sonnet-4.5, gpt-5
• Environment: BROWSERBASE (cloud mode)

Deployment Environment:

• Platform: Railway
• Node.js: 20.x
• Environment: Production (Docker container)

Issue Description

Title: [v3] Playwright should be in optionalDependencies, causing production deployment failures

Current Behavior

Stagehand 3.0.6 includes playwright as a required dependency in package.json. While the v3 release notes mention that Playwright has been removed in favor of direct CDP (Chrome DevTools Protocol) communication, the current package still lists playwright as a required dependency.

This causes deployment failures in serverless/containerized environments (Railway, Vercel, etc.) that lack Playwright's system-level dependencies (Chromium browser + system libraries), even when using BROWSERBASE cloud mode which shouldn't require local browser binaries.

Expected Behavior

According to the Stagehand v3 blog post, Playwright should be optional for integration purposes only, not a core requirement. The package.json should have:

{
  "optionalDependencies": {
    "playwright": "^1.52.0",
    "playwright-core": "^1.57.0"
  }
}

Instead of:

{
  "dependencies": {
    "playwright": "^1.52.0"  // ❌ Should be optional
  }
}

Steps to Reproduce

1. Create a Next.js project with Stagehand 3.0.6:

   pnpm add @browserbasehq/[email protected]

2. Import Stagehand in your code:

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

3. Configure for BROWSERBASE cloud mode (no local browser needed):

   const stagehand = new Stagehand({
     env: "BROWSERBASE",
     apiKey: process.env.BROWSERBASE_API_KEY,
     projectId: process.env.BROWSERBASE_PROJECT_ID,
   });

4. Deploy to Railway/Vercel with standard Node.js buildpack (no browser dependencies)

5. Application crashes on module load with:

   Cannot read properties of undefined (reading 'prototype')
   

Minimal Reproduction Code

import { Stagehand } from '@browserbasehq/stagehand';

// Even with BROWSERBASE cloud mode, the import fails
// Playwright appears to initialize on module load
const stagehand = new Stagehand({
  env: "BROWSERBASE",  // Using cloud browser, no local browser needed
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  verbose: 2,
});

await stagehand.init();

Error Messages / Log trace

❌ Failed to load Browserbase tools: {
  message: "Failed to load external module @browserbasehq/stagehand: TypeError: Cannot read properties of undefined (reading 'prototype')",
  stack: "Error: Failed to load external module @browserbasehq/stagehand: TypeError: Cannot read properties of undefined (reading 'prototype')\n" +
    '    at Context.externalRequire [as x] (/app/.next/server/chunks/[turbopack]_runtime.js:514:15)\n' +
    '    at module evaluation (/app/.next/server/chunks/[root-of-the-server]__9b8e2a0d._.js:1:46)',
  env: {
    browserMode: 'BROWSERBASE',
    hasApiKey: true,
    hasProjectId: true,
    nodeEnv: 'production'
  }
}

Dependency chain confirmed via pnpm why playwright:

dependencies:
@browserbasehq/stagehand 3.0.6
└── playwright 1.57.0

From installed package's package.json:

$ cat node_modules/@browserbasehq/stagehand/package.json | grep -A 3 '"dependencies"'

"dependencies": {
  ...
  "playwright": "^1.52.0",  # ❌ Problem here
  ...
},
"optionalDependencies": {  # ✅ Should be here
  "chrome-launcher": "1.2.1",
  "patchright-core": "1.57.0",
  "playwright-core": "1.57.0",
  ...
}

Root Cause Analysis

1. Playwright is listed as a required dependency instead of optional
2. When Node.js loads the Stagehand module, Playwright appears to initialize
3. Playwright appears to check for browser binaries and system libraries
4. In production containers without browser dependencies, this initialization seems to fail
5. The error propagates even though BROWSERBASE mode doesn't need local browsers

Impact

• ❌ Prevents deployment to Railway, Vercel, and other serverless platforms
• ❌ Forces users to install unnecessary system dependencies in production
• ❌ May not align with Stagehand v3's "CDP-first" architecture goals
• ❌ Increases Docker image size and deployment time

Proposed Solution

Move playwright from dependencies to optionalDependencies:

  "dependencies": {
    "@ai-sdk/provider": "^2.0.0",
    "devtools-protocol": "^0.0.1464554",
-   "playwright": "^1.52.0",
    "ws": "^8.18.0",
    ...
  },
  "optionalDependencies": {
+   "playwright": "^1.52.0",
    "playwright-core": "^1.57.0",
    "chrome-launcher": "1.2.1",
    ...
  }

This way:

• ✅ Users with Playwright integration can still use it
• ✅ BROWSERBASE-only users don't need local browser dependencies
• ✅ Production deployments work without extra configuration
• ✅ Aligns with v3's CDP-first architecture

Workarounds (Temporary)

Until this is fixed, users can:

1. Add Playwright dependencies to Dockerfile:

   RUN apt-get update && apt-get install -y \
       chromium \
       libnss3 \
       libatk1.0-0 \
       # ... other dependencies

2. Use pnpm overrides (not recommended, may break functionality):

   "pnpm": {
     "overrides": {
       "@browserbasehq/stagehand>playwright": "npm:noop@^1.0.0"
     }
   }

3. Disable Browserbase tools in production (loses functionality)

4. Use disablePino: true option to avoid pino-pretty issues:

   const stagehand = new Stagehand({
     env: "BROWSERBASE",
     disablePino: true,  // Avoids pino-pretty transport errors
   });

Related Issues

None found - this appears to be the first report of this dependency configuration issue.

Additional Context

The Stagehand v3 announcement explicitly states:

"Stagehand v3 removes the Playwright dependency and uses CDP directly for better performance and reliability"

However, the npm package still requires Playwright, which contradicts this design goal.

Community Impact

This issue affects anyone trying to deploy Stagehand-based applications to:

• Railway
• Vercel
• AWS Lambda
• Google Cloud Run
• Azure Container Instances
• Any containerized environment without browser dependencies

The issue is particularly confusing because users following the official documentation for BROWSERBASE cloud mode still encounter this error.

Closing Notes

I understand this might be an unintended packaging issue. I'm happy to help test any fixes, provide additional information, or contribute a PR if needed. Thank you for considering this report and for your continued work on Stagehand!