feat: use dynamic port allocation to support multiple plugin instances (#208)

* feat: use dynamic port allocation to support multiple plugin instances

BREAKING CHANGE Cypress config callback is now async

Replace hardcoded port 8765 with get-port library to automatically find available ports.
This allows multiple instances of cypress-watch-and-reload to run simultaneously without port conflicts.

- Add [email protected] dependency for dynamic port allocation with CommonJS support
- Update plugins.js to use async/await and get available port
- Pass selected port to client via environment variable
- Update support.js to use dynamic port from environment without fallback

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Remove console log

* docs: update README examples for async plugin usage

The plugin now returns a Promise due to dynamic port allocation.
Updated examples to show async/await usage where needed and added
clarifying note about when to use await vs direct return.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: jameskraus

README.md

@@ -53,9 +53,19 @@ Note: this plugin will work if you pass both `on` and `config` arguments, or jus
 
 ```js
 // pass both arguments
-require('cypress-watch-and-reload/plugins')(on, config)
+await require('cypress-watch-and-reload/plugins')(on, config)
 // or pass just the config object
-require('cypress-watch-and-reload/plugins')(config)
+await require('cypress-watch-and-reload/plugins')(config)
+```
+
+Note: The plugin returns a Promise. Use `await` if not directly returning from `setupNodeEvents`:
+
+```js
+async setupNodeEvents(on, config) {
+  await require('cypress-watch-and-reload/plugins')(on, config)
+  // do other setup...
+  return config
+}
 ```
 
 **Important:** make sure to return the plugin registration or the `config` object
@@ -66,8 +76,8 @@ setupNodeEvents(on, config) {
   return require('cypress-watch-and-reload/plugins')(on, config)
 }
 // or return the config object
-setupNodeEvents(on, config) {
-  require('cypress-watch-and-reload/plugins')(on, config)
+async setupNodeEvents(on, config) {
+  await require('cypress-watch-and-reload/plugins')(on, config)
   return config
 }
 ```

package-lock.json

@@ -22,6 +22,7 @@
   "dependencies": {
     "async-wait-until": "1.2.6",
     "chokidar": "3.6.0",
+    "get-port": "5.1.1",
     "ws": "8.18.3"
   },
   "devDependencies": {

package.json

@@ -1,7 +1,8 @@
 const WebSocket = require('ws')
 const chokidar = require('chokidar')
+const getPort = require('get-port')
 
-module.exports = (on, config) => {
+module.exports = async (on, config) => {
   // sometimes the users might pass both arguments
   // require('cypress-watch-and-reload')(on, config)
   // or just the config
@@ -20,7 +21,8 @@ module.exports = (on, config) => {
   // https://github.com/websockets/ws#simple-server
   // create socket even if not watching files to avoid
   // tripping up client trying to connect
-  const wss = new WebSocket.Server({ port: 8765 })
+  const port = await getPort({ port: 8765 })
+  const wss = new WebSocket.Server({ port })
   let client // future Cypress client
 
   const env = config.env || {}
@@ -85,5 +87,6 @@ module.exports = (on, config) => {
     config.env = {}
   }
   config.env.cypressWatchAndReloadPluginInitialized = true
+  config.env.cypressWatchAndReloadPort = port
   return config
 }

plugins.js

@@ -3,7 +3,8 @@
 if (Cypress.config('isInteractive')) {
   const insertToggleButton = require('./ui/toggle-btn')
   const waitUntil = require('async-wait-until')
-  const ws = new WebSocket('ws://localhost:8765')
+  const port = Cypress.env('cypressWatchAndReloadPort')
+  const ws = new WebSocket(`ws://localhost:${port}`)
 
   let watchAndReloadEnabled = true
   const button = insertToggleButton()