ESM migration

[miguelg719]

why

what changed

test plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 542d72d

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

[greptile-apps]

Greptile Overview

Greptile Summary

Migrated @browserbasehq/stagehand package to ESM with backward compatibility for CommonJS consumers. Added "type": "module" to package.json and configured dual ESM/CJS builds via tsup.

• Updated TypeScript compiler to target ES2022 modules
• Added __dirname polyfills using fileURLToPath(import.meta.url) across 8 files that relied on CommonJS globals
• Cleaned up duplicate property declarations in LLM client classes, properly leveraging base class inheritance
• Configured package exports to support both ESM (import) and CJS (require)

The migration follows standard ESM patterns and maintains backward compatibility through dual builds.

Confidence Score: 4/5

• This PR is safe to merge with low risk - standard ESM migration with proper backward compatibility
• The migration follows established ESM patterns correctly: proper __dirname polyfills, dual build output, and removal of redundant property declarations. Minor concern about moduleResolution: "Node" vs "NodeNext" for optimal ESM compatibility, but this shouldn't cause runtime issues. The PR lacks a description and test plan, which would have increased confidence.
• packages/core/tsconfig.json - verify moduleResolution setting works correctly with your build tooling

Important Files Changed

Filename	Overview
packages/core/package.json	Added ESM support with type: "module", dual exports (ESM/CJS), and updated build config
packages/core/tsconfig.json	Updated module system to ES2022 - verify moduleResolution should be "Node" vs "Node16"/"NodeNext" for ESM
packages/core/lib/v3/dom/genDomScripts.ts	Correctly added __dirname polyfill using fileURLToPath and import.meta.url for ESM
packages/core/lib/v3/llm/AnthropicClient.ts	Removed duplicate clientOptions property declaration (now inherited from base class)

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant TS as TypeScript Compiler
    participant Build as Build System (tsup)
    participant Scripts as DOM Scripts Generator
    participant Consumers as Package Consumers

    Note over Dev,Consumers: ESM Migration Flow

    Dev->>TS: Update tsconfig.json to ES2022 modules
    Dev->>Build: Update package.json with "type": "module"
    Dev->>Build: Configure dual ESM/CJS output in tsup
    
    Dev->>Scripts: Add __dirname polyfill to scripts
    Scripts->>Scripts: dirname(fileURLToPath(import.meta.url))
    
    Dev->>TS: Remove duplicate property declarations
    Note over TS: Use base class properties via inheritance
    
    Build->>Build: Generate ESM output (dist/index.js)
    Build->>Build: Generate CJS output (dist/index.cjs)
    Build->>Build: Generate type definitions (dist/index.d.ts)
    
    Consumers->>Build: Import via ESM (import)
    Build-->>Consumers: Serve dist/index.js
    
    Consumers->>Build: Require via CJS (require)
    Build-->>Consumers: Serve dist/index.cjs

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

consider using "moduleResolution": "Node16" or "NodeNext" instead of "Node" for better ESM compatibility with explicit file extensions

Suggested change

	"moduleResolution": "Node",
	"moduleResolution": "NodeNext",

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/core/tsconfig.json
Line: 8:8

Comment:
consider using `"moduleResolution": "Node16"` or `"NodeNext"` instead of `"Node"` for better ESM compatibility with explicit file extensions

```suggestion
    "moduleResolution": "NodeNext",
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[cubic-dev-ai]

1 issue found across 15 files

Confidence score: 3/5

• There is a concrete publish-time risk: packages/core/package.json omits dist/index.cjs from the files array, which would break CommonJS consumers when the package is published.
• Severity is high (8/10) with clear user impact, so this isn’t quite a low-risk merge despite being a small change.
• Pay close attention to packages/core/package.json - ensure dist/index.cjs is included in the published files.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/package.json">

<violation number="1" location="packages/core/package.json:6">
P1: The `dist/index.cjs` file referenced here is not included in the `files` array. When published to npm, this file won't be included, breaking CommonJS support. Add `"dist/index.cjs"` to the `files` array.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant System as Build System (tsx)
    participant Scripts as Internal Scripts
    participant Builder as TSUP / TSC
    participant Pkg as package.json
    participant Consumer as Consumer Runtime

    Note over System, Scripts: Phase 1: Internal Tooling (ESM Migration)
    
    System->>Scripts: Execute gen*.ts (e.g., genDomScripts)
    
    rect rgb(30, 41, 59)
        Note right of Scripts: CHANGED: Path Resolution Strategy
        Scripts->>Scripts: import.meta.url
        Scripts->>Scripts: fileURLToPath()
        Scripts->>Scripts: dirname()
        Note right of Scripts: Replaces legacy CommonJS __dirname
    end
    
    Scripts->>Scripts: Generate Assets (DOM/Locator scripts)

    Note over System, Consumer: Phase 2: Artifact Generation & Consumption

    System->>Builder: build-js (Target ES2022)
    Builder->>Builder: CHANGED: Generate ESM (.js)
    Builder->>Builder: NEW: Generate CommonJS (.cjs)
    Builder->>Pkg: Update Exports Definition

    Note over Pkg, Consumer: NEW: Conditional Module Resolution

    alt Consumer uses "import" (ESM)
        Consumer->>Pkg: Resolve "@browserbasehq/stagehand"
        Pkg-->>Consumer: returns dist/index.js (type: module)
    else Consumer uses "require" (CJS)
        Consumer->>Pkg: Resolve "@browserbasehq/stagehand"
        Pkg-->>Consumer: returns dist/index.cjs
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: The dist/index.cjs file referenced here is not included in the files array. When published to npm, this file won't be included, breaking CommonJS support. Add "dist/index.cjs" to the files array.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/core/package.json, line 6:

<comment>The `dist/index.cjs` file referenced here is not included in the `files` array. When published to npm, this file won't be included, breaking CommonJS support. Add `"dist/index.cjs"` to the `files` array.</comment>

<file context>
@@ -1,14 +1,22 @@
+  "type": "module",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
</file context>