[docs]: fix userDataDir example for Browserbase sessions

[shrey150]

Summary

• Remove incorrect userDataDir from browserbaseSessionCreateParams example (never a valid option)
• Split docs into separate Local and Browserbase sections
• Add correct Browserbase approach using browserSettings.context for persistence

Context

The documentation incorrectly showed userDataDir as a valid browserbaseSessionCreateParams property. Per the schema in /packages/core/lib/v3/types/public/api.ts, userDataDir is only valid in LocalBrowserLaunchOptions for env: "LOCAL" sessions.

For Browserbase persistence, users should use browserSettings.context instead.

Test plan

• Verify docs render correctly on Mintlify
• Confirm link to Browserbase contexts docs works

🤖 Generated with Claude Code

---

Summary by cubic

Fixed docs for user data persistence by removing the invalid userDataDir example for Browserbase sessions and showing the correct contexts-based approach. Split guidance into Local vs Browserbase to reduce confusion.

• Bug Fixes
  • Removed userDataDir from browserbaseSessionCreateParams; it’s only valid for env: "LOCAL" via localBrowserLaunchOptions.
  • Added Browserbase example using browserSettings.context (id + persist) and linked to contexts docs.

^{Written for commit 1166b79. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1166b79

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant App as Application Code
    participant SDK as Stagehand SDK
    participant FS as Local FileSystem
    participant BB as Browserbase API
    participant Context as Browserbase Context Store

    Note over App,Context: Session Initialization & Data Persistence Flow

    App->>SDK: new Stagehand(options)
    App->>SDK: init()

    alt env: "LOCAL"
        SDK->>SDK: Parse localBrowserLaunchOptions
        SDK->>FS: Access userDataDir (Path)
        SDK->>SDK: Launch Playwright/Puppeteer
        Note right of SDK: Browser reads/writes profile<br/>data to local directory
    else env: "BROWSERBASE"
        SDK->>SDK: Parse browserbaseSessionCreateParams
        SDK->>BB: POST /sessions (browserSettings.context)
        
        activate BB
        alt Context ID provided
            BB->>Context: Retrieve/Lock persistent state
            Context-->>BB: Session state loaded
        else persist: true
            BB->>Context: Create new persistent volume
        end
        
        BB-->>SDK: HTTP 201 (sessionId, debuggerUrl)
        deactivate BB
        
        SDK->>SDK: Connect to Remote CDP
    end

    SDK-->>App: Session Ready
    
    loop During Session
        App->>SDK: execute actions (act, extract, etc)
        opt env: "BROWSERBASE"
            SDK->>BB: Commands via WebSocket
            BB->>Context: Sync browser state (async)
        end
    end

    App->>SDK: close()
    alt env: "BROWSERBASE"
        SDK->>BB: Terminate Session
        BB->>Context: Flush & Save State
    end

Loading

[greptile-apps]

Greptile Overview

Greptile Summary

Corrected user data persistence documentation by removing invalid userDataDir from Browserbase example and properly documenting context-based persistence.

• Removed incorrect userDataDir from browserbaseSessionCreateParams (confirmed invalid per /packages/core/lib/v3/types/public/api.ts:279-292)
• Split documentation into "Local Sessions" and "Browserbase Sessions" sections for clarity
• Added proper Browserbase persistence approach using browserSettings.context with link to official Browserbase contexts documentation
• Improved code examples with consistent await stagehand.init() calls

Confidence Score: 5/5

• This PR is safe to merge with no risks
• Documentation-only change that corrects a factual error by removing invalid API usage and adding the proper approach, verified against source code type definitions
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/best-practices/user-data.mdx	Corrected documentation by removing invalid userDataDir from Browserbase examples and adding proper browserSettings.context approach

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant LocalBrowser
    participant Browserbase

    alt Local Session (userDataDir)
        User->>Stagehand: new Stagehand({env: "LOCAL", localBrowserLaunchOptions: {userDataDir}})
        Stagehand->>LocalBrowser: Launch with userDataDir
        LocalBrowser-->>Stagehand: Browser ready with persisted data
    end

    alt Browserbase Session (contexts)
        User->>Stagehand: new Stagehand({env: "BROWSERBASE", browserbaseSessionCreateParams: {browserSettings: {context}}})
        Stagehand->>Browserbase: Create session with context.id
        Browserbase-->>Stagehand: Session ready with persisted context
    end

    User->>Stagehand: init()
    Stagehand-->>User: Session ready

Loading

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[shrey150]

Merge activity

• Feb 4, 7:35 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Feb 4, 7:36 PM UTC: @shrey150 merged this pull request with Graphite.