fix: support USE_HTTPS for local hmr (#14053)

Closes #12087

When using `--experimental-https` from Nextjs we have no way of
detecting that right now so I've added documentation on how to handle
this flag and added to support for `USE_HTTPS` to set the websocket
protocol for HMR to `wss` instead of `ws`

Author: paulpopus

docs/troubleshooting/troubleshooting.mdx

@@ -126,3 +126,21 @@ To further investigate the issue:
 - Go to the login screen. Open your inspector. Go to the Network tab.
 - Log in and then find the login request that should appear in your network panel. Click the login request.
 - The login request should have a Set-Cookie header on the response, and the cookie should be getting set successfully. If it is not, most browsers generally have a little yellow ⚠️ symbol that you can hover over to see why the cookie was rejected.
+
+## Using --experimental-https
+
+If you are using the `--experimental-https` flag when starting your Payload server, you may run into issues with your WebSocket connection for HMR (Hot Module Reloading) in development mode.
+
+To resolve this, you can set the `USE_HTTPS` environment variable to `true` in your `.env` file:
+
+```
+USE_HTTPS=true
+```
+
+This will ensure that the WebSocket connection uses the correct protocol (`wss://` instead of `ws://`) when HTTPS is enabled.
+
+Alternatively if more of your URL is dynamic, you can set the full URL for the WebSocket connection using the `PAYLOAD_HMR_URL_OVERRIDE` environment variable:
+
+```
+PAYLOAD_HMR_URL_OVERRIDE=wss://localhost:3000/_next/webpack-hmr
+```

packages/payload/src/index.ts

@@ -1120,13 +1120,14 @@ export const getPayload = async (
     ) {
       try {
         const port = process.env.PORT || '3000'
+        const protocol = process.env.USE_HTTPS === 'true' ? 'wss' : 'ws'
 
         const path = '/_next/webpack-hmr'
         // The __NEXT_ASSET_PREFIX env variable is set for both assetPrefix and basePath (tested in Next.js 15.1.6)
         const prefix = process.env.__NEXT_ASSET_PREFIX ?? ''
 
         cached.ws = new WebSocket(
-          process.env.PAYLOAD_HMR_URL_OVERRIDE ?? `ws://localhost:${port}${prefix}${path}`,
+          process.env.PAYLOAD_HMR_URL_OVERRIDE ?? `${protocol}://localhost:${port}${prefix}${path}`,
         )
 
         cached.ws.onmessage = (event) => {