chore: bundle the browser and node entry points for packages/socket (#32726)

AtofStryker · web-flow · commit 246501c65eac · 2025-10-16T18:01:02.000-04:00
diff --git a/guides/esm-migration.md b/guides/esm-migration.md
@@ -12,7 +12,11 @@
 
 #### Notes
 
-When migrating some of these projects away from the `ts-node` entry [see `@packages/scaffold-config` example](https://github.com/cypress-io/cypress/blob/v15.2.0/packages/scaffold-config/index.js), it is somewhat difficult to make separate browser/node entries as the v8-snapshot [tsconfig.json](https://github.com/cypress-io/cypress/blob/v15.2.0/tooling/v8-snapshot/tsconfig.json) is using an older style of module resolution where the `exports` key inside a package's `package.json` is not well supported. Because of this, we need to find ways to bundle code that is needed internally in the browser vs in node without them being a part of the same bundle. This is a temporary work around until we are able to get every package being able to build as an ES Module, which as that point we can re assess how the Cypress binary is being built as well as v8-snapshots, and will allow us to reconfigure this packages to export content in a more proper fashion.
+When migrating some of these projects away from the `ts-node` entry [see `@packages/scaffold-config` example](https://github.com/cypress-io/cypress/blob/v15.2.0/packages/scaffold-config/index.js), it is somewhat difficult to make separate browser/node entries as the v8-snapshot [tsconfig.json](https://github.com/cypress-io/cypress/blob/v15.2.0/tooling/v8-snapshot/tsconfig.json) is using an older style of module resolution where the `exports` key inside a package's `package.json` is not well supported. Because of this, we need to find ways to bundle code that is needed internally in the browser vs in node without them being a part of the same bundle. This is a temporary work around until we are able to get every package being able to build as an ES Module, which as that point we can re assess how the Cypress binary is being built as well as v8-snapshots, and will allow us to reconfigure this packages to export content in a more proper fashion. We are currently doing something similar in the following packages:
+
+* `@packages/scaffold-config`
+* `@packages/socket`
+* `@packages/telemetry`
 
 #### Status
 
@@ -63,7 +67,7 @@ When migrating some of these projects away from the `ts-node` entry [see `@packa
 - [x] packages/runner ✅ **COMPLETED**
 - [x] packages/scaffold-config ✅ **COMPLETED**
 - [ ] packages/server **PARTIAL** - many source/test files in JS. highest priority
-- [ ] packages/socket **PARTIAL** - entry point is JS. Tests are JS
+- [x] packages/socket ✅ **COMPLETED**
 - [x] packages/stderr-filtering ✅ **COMPLETED**
 - [x] packages/telemetry ✅ **COMPLETED**
 - [ ] packages/ts **PARTIAL** - ultimate goal is removal and likely not worth the effort to convert
diff --git a/packages/app/cypress/component/support/ctSupport.ts b/packages/app/cypress/component/support/ctSupport.ts
@@ -1,6 +1,6 @@
 import { AutIframe } from '../../../src/runner/aut-iframe'
 import { EventManager } from '../../../src/runner/event-manager'
-import type { Socket } from '@packages/socket/lib/browser'
+import type { Socket } from '@packages/socket/browser/client'
 
 export const StubWebsocket = new Proxy<Socket>(Object.create(null), {
   get: (obj, prop) => {
diff --git a/packages/app/index.d.ts b/packages/app/index.d.ts
@@ -1,6 +1,6 @@
 /// <reference path="../driver/types/internal-types-lite.d.ts" />
 
-import type { SocketShape } from '@packages/socket/lib/types'
+import type { SocketShape } from '@packages/socket/browser/client'
 import type MobX from 'mobx'
 import type { EventManager } from './src/runner/event-manager'
 
diff --git a/packages/app/src/runner/event-manager.ts b/packages/app/src/runner/event-manager.ts
@@ -7,7 +7,7 @@ import type { LocalBusEmitsMap, LocalBusEventMap, DriverToLocalBus, SocketToDriv
 import type { RunState, CachedTestState, AutomationElementId, FileDetails, ReporterStartInfo, ReporterRunState } from '@packages/types'
 
 import { logger } from './logger'
-import type { SocketShape } from '@packages/socket/lib/types'
+import type { SocketShape } from '@packages/socket/browser/client'
 import { automation, useRunnerUiStore, useSpecStore } from '../store'
 import { useScreenshotStore } from '../store/screenshot-store'
 import { useStudioStore } from '../store/studio-store'
diff --git a/packages/app/src/runner/index.ts b/packages/app/src/runner/index.ts
@@ -22,7 +22,7 @@ import { getRunnerElement, empty } from './utils'
 import { IframeModel } from './iframe-model'
 import { AutIframe } from './aut-iframe'
 import { EventManager } from './event-manager'
-import { createWebsocket as createWebsocketIo } from '@packages/socket/lib/browser'
+import { createWebsocket as createWebsocketIo } from '@packages/socket/browser/client'
 import type { AutomationElementId } from '@packages/types'
 import { useSnapshotStore } from './snapshot-store'
 import { useStudioStore } from '../store/studio-store'
diff --git a/packages/data-context/src/actions/ServersActions.ts b/packages/data-context/src/actions/ServersActions.ts
@@ -2,9 +2,8 @@ import util from 'util'
 
 import type { AddressInfo } from 'net'
 import type { Server } from 'http'
-import type { SocketIONamespace, SocketIOServer } from '@packages/socket'
+import type { SocketIONamespace, SocketIOServer, CDPSocketServer } from '@packages/socket'
 import type { DataContext } from '..'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
 
 export class ServersActions {
   constructor (private ctx: DataContext) {}
diff --git a/packages/data-context/src/data/coreDataShape.ts b/packages/data-context/src/data/coreDataShape.ts
@@ -4,12 +4,11 @@ import type { NexusGenObjects } from '../gen/nxs.gen'
 // tslint:disable-next-line no-implicit-dependencies - electron dep needs to be defined
 import type { App, BrowserWindow } from 'electron'
 import type { ChildProcess } from 'child_process'
-import type { SocketIONamespace, SocketIOServer } from '@packages/socket'
+import type { SocketIONamespace, SocketIOServer, CDPSocketServer } from '@packages/socket'
 import type { Server } from 'http'
 import type { ErrorWrapperSource } from '@packages/errors'
 import type { EventCollectorSource, GitDataSource } from '../sources'
 import { machineId as getMachineId } from 'node-machine-id'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
 
 export type Maybe<T> = T | null | undefined
 
diff --git a/packages/extension/app/v2/client.ts b/packages/extension/app/v2/client.ts
@@ -1,4 +1,4 @@
-import { client } from '@packages/socket/lib/browser'
+import { client } from '@packages/socket/browser/client'
 
 export const connect = (host, path, extraOpts = {}) => {
   return client(host, {
diff --git a/packages/extension/test/integration/v2/background_spec.js b/packages/extension/test/integration/v2/background_spec.js
@@ -2,7 +2,7 @@
 require('../../spec_helper')
 const _ = require('lodash')
 const http = require('http')
-const socket = require('@packages/socket')
+const { SocketIOServer } = require('@packages/socket')
 const mockRequire = require('mock-require')
 const client = require('../../../app/v2/client')
 
@@ -38,7 +38,7 @@ describe('app/background', () => {
     global.window = {}
 
     this.httpSrv = http.createServer()
-    this.server = socket.server(this.httpSrv, { path: '/__socket' })
+    this.server = new SocketIOServer(this.httpSrv, { path: '/__socket' })
 
     const ws = {
       on: sinon.stub(),
diff --git a/packages/frontend-shared/src/graphql/urqlClient.ts b/packages/frontend-shared/src/graphql/urqlClient.ts
@@ -10,8 +10,8 @@ import {
 } from '@urql/core'
 import { devtoolsExchange } from '@urql/devtools'
 import { useToast } from 'vue-toastification'
-import type { SocketShape } from '@packages/socket/lib/types'
-import { client } from '@packages/socket/lib/browser'
+import type { SocketShape } from '@packages/socket/browser/client'
+import { client } from '@packages/socket/browser/client'
 import { createClient as createWsClient } from 'graphql-ws'
 
 import { cacheExchange as graphcacheExchange } from '@urql/exchange-graphcache'
diff --git a/packages/frontend-shared/src/graphql/urqlExchangePubsub.ts b/packages/frontend-shared/src/graphql/urqlExchangePubsub.ts
@@ -1,6 +1,6 @@
 import { pipe, tap } from 'wonka'
 import type { Exchange, Operation, OperationResult } from '@urql/core'
-import type { SocketShape } from '@packages/socket/lib/types'
+import type { SocketShape } from '@packages/socket/browser/client'
 import type { DefinitionNode, DocumentNode, OperationDefinitionNode } from 'graphql'
 
 export const pubSubExchange = (io: SocketShape): Exchange => {
diff --git a/packages/frontend-shared/src/graphql/urqlFetchSocketAdapter.ts b/packages/frontend-shared/src/graphql/urqlFetchSocketAdapter.ts
@@ -1,5 +1,5 @@
 import _ from 'lodash'
-import type { SocketShape } from '@packages/socket/lib/types'
+import type { SocketShape } from '@packages/socket/browser/client'
 import type { ClientOptions } from '@urql/core'
 
 export const urqlFetchSocketAdapter = (io: SocketShape): ClientOptions['fetch'] => {
diff --git a/packages/network/test/unit/agent.spec.ts b/packages/network/test/unit/agent.spec.ts
@@ -9,7 +9,7 @@ import url from 'url'
 import DebuggingProxy from '@cypress/debugging-proxy'
 import Request from '@cypress/request-promise'
 
-import * as socketIo from '@packages/socket/lib/browser'
+import * as socketIo from '@packages/socket/browser/client'
 import {
   buildConnectReqHead,
   createProxySock,
diff --git a/packages/server/lib/browsers/chrome.ts b/packages/server/lib/browsers/chrome.ts
@@ -21,7 +21,7 @@ import type { Automation } from '../automation'
 import memory from './memory'
 
 import type { BrowserLaunchOpts, BrowserNewTabOpts, ProtocolManagerShape, CyPromptManagerShape, RunModeVideoApi } from '@packages/types'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
+import type { CDPSocketServer } from '@packages/socket'
 import { DEFAULT_CHROME_FLAGS } from '../util/chromium_flags'
 
 const debug = debugModule('cypress:server:browsers:chrome')
diff --git a/packages/server/lib/browsers/electron.ts b/packages/server/lib/browsers/electron.ts
@@ -13,7 +13,7 @@ import type { Browser, BrowserInstance, GracefulShutdownOptions } from './types'
 import type { BrowserWindow } from 'electron'
 import type { Automation } from '../automation'
 import type { BrowserLaunchOpts, Preferences, ProtocolManagerShape, CyPromptManagerShape, RunModeVideoApi } from '@packages/types'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
+import type { CDPSocketServer } from '@packages/socket'
 import memory from './memory'
 import { BrowserCriClient } from './browser-cri-client'
 import { getRemoteDebuggingPort } from '../util/electron-app'
diff --git a/packages/server/lib/browsers/index.ts b/packages/server/lib/browsers/index.ts
@@ -10,7 +10,7 @@ import { BROWSER_FAMILY, BrowserLaunchOpts, BrowserNewTabOpts, FoundBrowser, Pro
 import type { Browser, BrowserInstance, BrowserLauncher } from './types'
 import type { Automation } from '../automation'
 import type { DataContext } from '@packages/data-context'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
+import type { CDPSocketServer } from '@packages/socket'
 
 const debug = Debug('cypress:server:browsers')
 const isBrowserFamily = (browser: string) => BROWSER_FAMILY.includes(browser)
diff --git a/packages/server/lib/browsers/types.ts b/packages/server/lib/browsers/types.ts
@@ -1,7 +1,7 @@
 import type { FoundBrowser, BrowserLaunchOpts, BrowserNewTabOpts, ProtocolManagerShape, CyPromptManagerShape } from '@packages/types'
 import type { EventEmitter } from 'events'
 import type { Automation } from '../automation'
-import type { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
+import type { CDPSocketServer } from '@packages/socket'
 
 export type Browser = FoundBrowser & {
   majorVersion: number | string
diff --git a/packages/server/lib/socket-base.ts b/packages/server/lib/socket-base.ts
@@ -6,7 +6,7 @@ import { getCtx } from '@packages/data-context'
 import { handleGraphQLSocketRequest } from '@packages/data-context/graphql/makeGraphQLServer'
 import { onNetStubbingEvent } from '@packages/net-stubbing'
 import * as socketIo from '@packages/socket'
-import { CDPSocketServer } from '@packages/socket/lib/cdp-socket'
+import { CDPSocketServer } from '@packages/socket'
 
 import * as errors from './errors'
 import fixture from './fixture'
diff --git a/packages/server/test/integration/websockets_spec.js b/packages/server/test/integration/websockets_spec.js
@@ -5,7 +5,9 @@ const ws = require('ws')
 const httpsProxyAgent = require('https-proxy-agent')
 const evilDns = require('evil-dns')
 const Promise = require('bluebird')
-const socketIo = require(`@packages/socket/lib/browser`)
+// NOTE: we need to import the client from the lib directory because the browser/client directory is compiled to ESM.
+// we are unable to import ESM into a CommonJS test context, even if we await import() the module.
+const socketIo = require('@packages/socket/lib/client')
 const httpsServer = require(`@packages/https-proxy/test/helpers/https_server`)
 const config = require(`../../lib/config`)
 const { ServerBase } = require(`../../lib/server-base`)
diff --git a/packages/server/test/unit/socket_spec.js b/packages/server/test/unit/socket_spec.js
@@ -3,7 +3,10 @@ require('../spec_helper')
 const _ = require('lodash')
 const path = require('path')
 const httpsAgent = require('https-proxy-agent')
-const socketIo = require('@packages/socket/lib/browser')
+// NOTE: we need to import the client from the lib directory because the browser/client directory is compiled to ESM.
+// we are unable to import ESM into a CommonJS test context, even if we await import() the module.
+const socketIo = require('@packages/socket/lib/client')
+
 const Fixtures = require('@tooling/system-tests')
 
 const errors = require('../../lib/errors')
@@ -28,6 +31,19 @@ describe('lib/socket', () => {
       path: 'path-to-browser-one',
     }
 
+    // needed to run these tests locally
+    // sinon.stub(ctx.browser, 'machineBrowsers').resolves([
+    //   {
+    //     channel: 'stable',
+    //     displayName: 'Electron',
+    //     family: 'chromium',
+    //     majorVersion: '123',
+    //     name: 'electron',
+    //     path: 'path-to-browser-one',
+    //     version: '123.45.67',
+    //   },
+    // ])
+
     // Don't bother initializing the child process, etc for this
     sinon.stub(ctx.actions.project, 'initializeActiveProject')
     sinon.stub(preprocessor.emitter, 'on')
diff --git a/packages/socket/.eslintignore b/packages/socket/.eslintignore
@@ -1 +1,5 @@
 **/tsconfig.json
+
+cjs/
+esm/
+browser/
diff --git a/packages/socket/.gitignore b/packages/socket/.gitignore
@@ -0,0 +1,3 @@
+cjs/
+esm/
+browser/
diff --git a/packages/socket/README.md b/packages/socket/README.md
@@ -1,32 +1,19 @@
 # Socket
 
-This is a shared lib for holding both the `socket.io` server and client.
+This is a shared lib for holding both the `socket.io` Cypress implements of the server and client.
 
 ## Using
 
 ```javascript
 const socket = require("@packages/socket")
 
-// returns
-{
-  server: require("socket.io"),
-  getPathToClientSource: function () {
-    // returns path to the client 'socket.io.js' file
-    // for use in the browser
-  }
-}
-```
-
-```javascript
-const socket = require("@packages/socket")
-
 // server usage
 const srv = require("http").createServer()
-const io = socket.server(srv)
+const io = new SocketIOServer(srv)
 io.on("connection", function(){})
 
 // client usage
-const { client } = require("@packages/socket/lib/client")
+const { client } = require("@packages/socket/browser/client")
 const client = socket.client("http://localhost:2020")
 client.on("connect", function(){})
 client.on("event", function(){})
diff --git a/packages/socket/index.js b/packages/socket/index.js
diff --git a/packages/socket/lib/client/browser.ts b/packages/socket/lib/client/browser.ts
@@ -1,8 +1,6 @@
 import io, { ManagerOptions, SocketOptions } from 'socket.io-client'
 import { CDPBrowserSocket } from './cdp-browser'
-import type { SocketShape } from './types'
-
-export type { Socket } from 'socket.io-client'
+import type { SocketShape } from './cdp-browser'
 
 declare global {
   interface Window {
@@ -26,8 +24,7 @@ export function client (uri: string, opts?: Partial<ManagerOptions & SocketOptio
     // Connect the socket regardless of whether or not we have newly created it
     window.cypressSockets[fullNamespace].connect()
 
-    // @ts-expect-error TODO: fix type
-    return window.cypressSockets[fullNamespace]
+    return window.cypressSockets[fullNamespace] as unknown as SocketShape
   }
 
   return io(uri, opts)
@@ -49,8 +46,7 @@ export function createWebsocket ({ path, browserFamily }: { path: string, browse
     // Connect the socket regardless of whether or not we have newly created it
     window.cypressSockets[fullNamespace].connect()
 
-    // @ts-expect-error TODO: fix type
-    return window.cypressSockets[fullNamespace]
+    return window.cypressSockets[fullNamespace] as unknown as SocketShape
   }
 
   return io({
diff --git a/packages/socket/lib/client/cdp-browser.ts b/packages/socket/lib/client/cdp-browser.ts
@@ -1,8 +1,9 @@
 /// <reference lib="dom" />
-import Emitter from 'component-emitter'
 import { v4 as uuidv4 } from 'uuid'
-import { decode, encode } from './utils'
-import type { SocketShape } from './types'
+import { decode, encode } from '../utils'
+import Emitter from 'component-emitter'
+
+export type SocketShape = Emitter
 
 type CDPSocketNamespaceKey = `cypressSocket-${string}`
 type CDPSendToServerNamespaceKey = `cypressSendToServer-${string}`
diff --git a/packages/socket/lib/client/index.ts b/packages/socket/lib/client/index.ts
@@ -0,0 +1,7 @@
+export { client, createWebsocket } from './browser'
+
+export { CDPBrowserSocket } from './cdp-browser'
+
+export type { Socket } from 'socket.io-client'
+
+export type { SocketShape } from './cdp-browser'
diff --git a/packages/socket/lib/node/cdp-socket.ts b/packages/socket/lib/node/cdp-socket.ts
@@ -2,7 +2,7 @@ import type { CDPClient } from '@packages/types/src/protocol'
 import type Protocol from 'devtools-protocol/types/protocol.d'
 import { EventEmitter } from 'stream'
 import { randomUUID } from 'crypto'
-import { decode, encode } from './utils'
+import { decode, encode } from '../utils'
 import Debug from 'debug'
 
 const debugVerbose = Debug('cypress-verbose:server:socket:cdp-socket')
@@ -36,6 +36,7 @@ export class CDPSocketServer extends EventEmitter {
 
   // @ts-expect-error TODO: fix emit type
   emit = async (event: string, ...args: any[]) => {
+    // tslint:disable-next-line:no-floating-promises
     this._cdpSocket?.emit(event, ...args)
 
     return true
diff --git a/packages/socket/lib/node/index.ts b/packages/socket/lib/node/index.ts
@@ -0,0 +1,5 @@
+export { SocketIOServer, getPathToClientSource, getClientVersion } from './socket'
+
+export type { ServerOptions, Socket, Namespace as SocketIONamespace } from 'socket.io'
+
+export { CDPSocketServer } from './cdp-socket'
diff --git a/packages/socket/lib/node/socket.ts b/packages/socket/lib/node/socket.ts
@@ -1,18 +1,15 @@
 import buffer from 'buffer'
 import type http from 'http'
-import server, { Server as SocketIOBaseServer, ServerOptions, Socket, Namespace } from 'socket.io'
-
-export type { Socket, Namespace as SocketIONamespace }
+import { Server as SocketIOBaseServer, ServerOptions } from 'socket.io'
 
+// TODO: this will need to be updated to use an ESM version of the package
 const { version } = require('socket.io-client/package.json')
 const clientSource = require.resolve('socket.io-client/dist/socket.io.js')
 
-export { ServerOptions }
-
 // socket.io types are incorrect
 type PatchedServerOptions = ServerOptions & { cookie: { name: string | boolean } }
 
-class SocketIOServer extends SocketIOBaseServer {
+export class SocketIOServer extends SocketIOBaseServer {
   constructor (srv: http.Server, opts?: Partial<PatchedServerOptions>) {
     opts = opts ?? {}
 
@@ -27,12 +24,6 @@ class SocketIOServer extends SocketIOBaseServer {
   }
 }
 
-export {
-  server,
-  SocketIOServer,
-}
-
-// TODO: I don't know that this is used anywhere?
 export const getPathToClientSource = () => {
   return clientSource
 }
diff --git a/packages/socket/lib/node/types.ts b/packages/socket/lib/node/types.ts
diff --git a/packages/socket/package.json b/packages/socket/package.json
diff --git a/packages/socket/test/socket.spec.ts b/packages/socket/test/socket.spec.ts
diff --git a/packages/socket/tsconfig.browser.json b/packages/socket/tsconfig.browser.json
diff --git a/packages/socket/tsconfig.cjs.json b/packages/socket/tsconfig.cjs.json
diff --git a/packages/socket/tsconfig.esm.json b/packages/socket/tsconfig.esm.json
diff --git a/packages/socket/tsconfig.json b/packages/socket/tsconfig.json
diff --git a/system-tests/projects/non-proxied/cypress.config.js b/system-tests/projects/non-proxied/cypress.config.js
diff --git a/tooling/v8-snapshot/cache/darwin/snapshot-meta.json b/tooling/v8-snapshot/cache/darwin/snapshot-meta.json
diff --git a/tooling/v8-snapshot/cache/linux/snapshot-meta.json b/tooling/v8-snapshot/cache/linux/snapshot-meta.json
diff --git a/tooling/v8-snapshot/cache/win32/snapshot-meta.json b/tooling/v8-snapshot/cache/win32/snapshot-meta.json

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { client } from '@packages/socket/lib/browser'`
	`1`	`+import { client } from '@packages/socket/browser/client'`
`2`	`2`
`3`	`3`	`export const connect = (host, path, extraOpts = {}) => {`
`4`	`4`	`return client(host, {`