Vite HMR Through HTTPS: WebSockets, Docker, OAuth

Why the page can load while Vite HMR remains disconnected

A remote Vite development session involves at least two browser connection types. The initial document, JavaScript modules, stylesheets, source maps, and other assets use ordinary HTTP requests. Hot Module Replacement uses a persistent WebSocket connection so the Vite development server can notify the browser when a source file changes. A successful page load proves that ordinary HTTP traffic reached the application, but it does not prove that the WebSocket request reached Vite, upgraded successfully, or stayed connected.

With Localtonet, our client application runs on a device that can reach the development service. The client establishes an outbound connection to a Localtonet relay server. An HTTP tunnel then provides a public HTTPS URL and forwards requests to the local IP address and port selected for the tunnel. No inbound router port forwarding, public IP address, VPN setup, or inbound firewall change is required. The endpoint is available only while the selected client is connected and the tunnel is running.

The expected request path is the remote browser to the public HTTPS endpoint, the Localtonet relay to the connected client, and the client to the local Vite target. If Vite runs in Docker, that final part also crosses from the host into the container. Every layer must agree about where traffic should go, but the address used at each layer is not necessarily the same.

The connection layers that must agree

Understand what localhost means at each boundary

In a colleague’s browser, localhost means the colleague’s computer. Inside a Docker container, it means that container. On the development host, it means the host operating system. A Vite process listening at 127.0.0.1 inside a container is therefore not listening on the host’s loopback interface, even if both environments use the same port number.

Prerequisites and version scope

The examples in this guide target the Vite 7 server configuration schema. Vite 7 requires Node.js 20.19 or later, or Node.js 22.12 or later. If your project uses another Vite major version, inspect the version installed by the project lockfile and confirm the corresponding server option documentation before copying the configuration. Do not use the behavior of an old Vite 2 discussion as evidence for a current project.

Before configuring the public endpoint, make sure you have all of the following:

• A Vite project that starts successfully with its normal development command.
• A Node.js release supported by the Vite major version installed in the project.
• Docker Engine with Docker Compose available if you are following the container workflow.
• A local Vite service reachable from the device where the Localtonet client will run.
• The Localtonet application installed and running on that device.
• A device-specific Localtonet authentication token entered through the supported client workflow.
• Access to the OAuth provider’s application settings if you plan to test an OAuth callback.
• A public hostname selected by the Localtonet HTTP tunnel workflow.

Check the installed runtime and Vite version from the project directory:

node --version
npm --version
npm ls vite

For Docker, verify that both the engine and Compose are available:

docker version
docker compose version

The exact output depends on your environment. The important result is that Node satisfies the installed Vite release, npm ls vite identifies the project’s actual Vite version, and Docker commands can communicate with the Docker engine.

Configure Vite for a reachable and predictable server

Begin with the smallest configuration needed to make Vite reachable from Docker or another host namespace. Keep HMR on the same public origin initially. Only add explicit browser-facing HMR overrides if DevTools proves that Vite constructed the wrong WebSocket destination.

Minimal configuration for the base server

Set PUBLIC_PREVIEW_HOST to the hostname assigned to the active tunnel, without https://, a path, or a port. The variable is read by the Node-side Vite configuration and is not a credential.

import { defineConfig } from 'vite'

const publicPreviewHost = process.env.PUBLIC_PREVIEW_HOST

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    strictPort: true,
    allowedHosts: publicPreviewHost ? [publicPreviewHost] : []
  }
})

This baseline deliberately omits server.hmr. In a same-origin topology, the preferred first test is for the browser to use the public page origin for HMR while the tunnel forwards the WebSocket request to the same local Vite service. Because WebSocket behavior must be confirmed for the exact route, inspect the resulting connection rather than assuming that page delivery guarantees an upgrade.

What each Vite server option controls

strictPort: true is especially important in a fixed tunnel or container setup. Without strict mode, Vite can move from 5173 to another free port when 5173 is occupied. Docker may continue publishing 5173 and the Localtonet tunnel may continue targeting 5173, leaving both pointed at the wrong process or an inactive port.

Add browser-facing HMR overrides only when required

If DevTools shows that the HMR client is attempting ws://, localhost, a private address, or Vite’s internal port, add an explicit HMR block:

import { defineConfig } from 'vite'

const publicPreviewHost = process.env.PUBLIC_PREVIEW_HOST

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    strictPort: true,
    allowedHosts: publicPreviewHost ? [publicPreviewHost] : [],
    hmr: publicPreviewHost
      ? {
          protocol: 'wss',
          host: publicPreviewHost,
          clientPort: 443
        }
      : undefined
  }
})

Replace the environment value with the hostname from the active tunnel. Do not include a URL scheme. This configuration says that Vite still listens locally on port 5173, while browser HMR connects to the public hostname over WSS using the standard HTTPS port. It does not create a second HMR server.

Leave server.hmr.port and server.hmr.path unset for this same-service example. A separate HMR port requires a second deliberately reachable route, and a custom path requires every forwarding layer to agree on that path. Adding either setting speculatively creates more opportunities for mismatch.

Understand Vite’s direct-connection fallback

Current Vite documentation describes a direct WebSocket fallback when the HMR client cannot connect through a reverse proxy. That fallback can cause the browser to attempt a direct connection to the Vite server. A direct attempt may work on the developer’s own machine but fail for a remote viewer because the internal address or port is not publicly reachable.

Treat a fallback attempt as evidence that the intended WebSocket path did not work. Do not publish Vite’s container or host port broadly merely to satisfy the fallback. Instead, inspect the first failed WebSocket request, verify the public destination, and correct the upgrade path or browser-facing HMR values.

Run Vite in Docker and publish the correct port

The following example keeps the development service reproducible while limiting the published port to host loopback. That is appropriate when the Localtonet client runs on the Docker host and targets 127.0.0.1:5173. If our client runs on another device, the service must be reachable from that device through an address permitted by your network policy.

Dockerfile

FROM node:22-alpine

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .

EXPOSE 5173

CMD ["npm", "run", "dev"]

The Node 22 image must resolve to a release new enough for the installed Vite major version. For Vite 7, verify that the runtime is Node 22.12 or later. Production projects may pin an exact image version or digest through their normal dependency update process.

Docker Compose configuration

services:
  vite:
    build:
      context: .
    init: true
    ports:
      - "127.0.0.1:5173:5173"
    environment:
      PUBLIC_PREVIEW_HOST: "${PUBLIC_PREVIEW_HOST:-}"
    volumes:
      - .:/app
      - /app/node_modules
    command: npm run dev
    restart: unless-stopped

The first volume mounts the source tree so edits made on the host appear in the container. The anonymous /app/node_modules volume prevents the bind mount from replacing dependencies installed in the image. The port publication maps host loopback port 5173 to container port 5173. Vite’s host: '0.0.0.0' setting is what makes the process accept traffic arriving through the container interface.

Export the active public hostname before starting the service:

export PUBLIC_PREVIEW_HOST=preview.example.com
docker compose up --build

preview.example.com is a reserved example value. Replace it with the actual hostname assigned to your tunnel, without a scheme, port, or path.

If you use the first baseline configuration without explicit HMR overrides, the environment value controls only allowedHosts. If testing proves that explicit HMR values are required, switch to the second configuration and restart the Vite service.

Start and inspect the container

docker compose up --build -d
docker compose ps
docker compose logs -f vite

The service should remain running, the port mapping should show host port 5173 mapped to container port 5173, and the Vite log should show the server listening on port 5173. If Vite exits because the port is occupied, strictPort: true is working as intended. Free the port or deliberately update the Vite, Compose, and tunnel configurations together.

Confirm the Node and Vite versions inside the running container:

docker compose exec vite node --version
docker compose exec vite npm ls vite

Create the Localtonet HTTP tunnel in the documented order

Complete the local Docker and Vite checks before creating the public endpoint. The Localtonet client must run on the device that can reach the host-published service. The following sequence preserves the current HTTP tunnel documentation workflow.

See the Localtonet HTTP/s tunnel documentation while configuring the endpoint. Current dashboard options, server availability, domain requirements, and plan availability can change.

Verify every layer from container to HMR update

Run the checks in order. Moving outward from the Vite process prevents a public tunnel problem from being confused with a container binding, port publication, or local application failure.

1. Verify Vite inside the container

docker compose exec vite node -e "fetch('http://127.0.0.1:5173').then(r => { console.log(r.status, r.headers.get('content-type')); process.exit(r.ok ? 0 : 1) }).catch(e => { console.error(e); process.exit(1) })"

Expect an HTTP success status and an HTML content type for a normal Vite application entry point. A refused connection means Vite is not running on port 5173. An unexpected response means another process or route may be handling the request.

2. Verify the host-published port

Run this on the Docker host, which is also the Localtonet client device in the example:

curl -I http://127.0.0.1:5173/

Expect a successful or otherwise application-appropriate HTTP response from Vite. If the container check succeeds but this host check fails, inspect the Compose port publication and Vite bind address. Do not proceed to the tunnel until the host can reach the target.

3. Verify the public tunnel page

curl -I https://preview.example.com/

Replace the example hostname with the assigned public hostname. Expect an HTTPS response corresponding to the same Vite application. A tunnel error, unrelated page, or connection failure indicates a target, tunnel state, device connection, hostname, or server-selection problem.

4. Verify the WebSocket in browser DevTools

Open the public URL in a new browser session, then open Developer Tools and select the Network panel. Filter for WebSocket requests, often shown as WS. Reload the page and select the Vite HMR connection.

For a shareable diagnostic image, capture this DevTools view only from a real test. Annotate the public hostname, effective port, successful upgrade status, and HMR frames generated after an edit. Redact query parameters, cookies, authorization headers, tokens, project identifiers, and any private endpoint data before sharing the screenshot.

5. Perform a real file-change HMR test

Keep DevTools open and edit a component or stylesheet that is visible on the current page. Make a reversible change, such as changing a heading or background color, save the file, and observe all three locations:

• The Vite container log should report file or module update activity.
• The browser WebSocket view should show new HMR frames or messages.
• The visible page should update without requiring a manual refresh when the edited module supports HMR.

If the application performs a full reload instead of a module replacement, the transport may still be working. Vite or the framework plugin can choose a full reload for changes that cannot be safely replaced in place. The decisive transport evidence is an open socket plus update traffic after the edit.

6. Inspect logs while reproducing a failure

docker compose logs --tail=200 -f vite

Reload the public page and save a source file while the log stream is visible. Compare the first browser error with the corresponding server output. A host rejection, startup port conflict, watcher silence, or process restart usually becomes clearer when the browser and server timelines are observed together.

Construct and verify an OAuth callback URL

OAuth introduces a separate redirect check. Suppose the active public origin is the reserved example URL https://preview.example.com and the application handles its callback at /auth/callback. The complete redirect URI is:

https://preview.example.com/auth/callback

Replace the example hostname and callback path with the values used by your application. Register that complete URI in the OAuth provider’s application settings and configure the application to send the same redirect URI in its authorization request.

Redirect matching rules vary by provider and by the protocol or profile being implemented. Many providers require an exact registered URI, but do not assume that every provider compares each textual form identically. In a URL, HTTPS without an explicit port normally has an effective port of 443, while a provider may normalize or validate omitted and explicit default ports according to its own rules. Follow the provider’s current documentation and register the form your application actually sends.

Verify the callback in four places:

1. Inspect the redirect URI registered in the provider’s application settings.
2. Inspect the authorization request generated by the application, without publishing its sensitive parameters.
3. Confirm that the browser returns to the active public hostname and intended callback path.
4. Confirm that the local application receives and processes the callback according to its normal server-side flow.

A changing generated hostname also changes the callback URI. If the tunnel receives a different hostname, update PUBLIC_PREVIEW_HOST, restart Vite, update the provider registration, and ensure the application constructs the callback from the new public origin.

HMR and OAuth must be verified independently. A successful OAuth redirect proves that the browser reached an HTTP callback route. It does not prove that the HMR WebSocket upgraded. Likewise, a working HMR socket does not prove that the provider accepted the registered redirect URI.

Troubleshoot common HTTPS, WebSocket, Docker, and OAuth failures

Vite rejects the public hostname

A host rejection means the request reached Vite but the Host value was not accepted. Confirm that PUBLIC_PREVIEW_HOST contains only the current hostname, without https://, a port, slash, or callback path. Restart Vite after changing the environment because the configuration is evaluated at startup. Keep allowedHosts narrow and never replace it with true as a shortcut.

The browser reports mixed content

Inspect the failed WebSocket URL. A page loaded over HTTPS should not be directed to an insecure ws:// HMR socket. First test same-origin inference. If the installed Vite version constructs the wrong protocol, set server.hmr.protocol to wss and verify the result in DevTools.

The HMR client uses the wrong port

If the public page uses standard HTTPS but the browser tries :5173, it is attempting to reach the local development port directly. For the topology in this guide, set server.hmr.clientPort to 443 while leaving server.port at 5173. The first is browser-facing; the second is where Vite listens locally.

The WebSocket upgrade fails

Record the request URL and response status. A 404 can indicate a wrong custom path or a request reaching the wrong service. A 403 can indicate host or application policy rejection. A gateway response suggests that the upstream service was unavailable or that the connection did not reach Vite. Confirm local HTTP reachability, then test the exact public route again.

Do not add server.hmr.path merely because the upgrade failed. The default same-service path should remain unchanged unless a deliberate path-based forwarding design requires a custom value. If a custom path is used, the browser, Vite, and every intermediate forwarding layer must use the same path.

The browser enters a reconnect loop

Repeated retries are a symptom of a failed or unstable socket. Focus on the first failed request after a clean reload. Check whether the browser is using a direct-connection fallback, whether the socket reaches the public hostname, and whether Vite logs a corresponding request or rejection. Correct the underlying destination or upgrade issue instead of relying on the fallback.

Vite works in the container but not on the host

Confirm that Vite uses host: '0.0.0.0', that Compose publishes 127.0.0.1:5173:5173, and that the container remains healthy. Inspect the effective mapping:

docker compose ps
docker compose port vite 5173
curl -I http://127.0.0.1:5173/

If the Localtonet client runs on a different machine, a loopback-only publication will not be reachable from that machine. Deliberately publish to a suitable host interface and apply firewall and access policy rather than exposing the port unintentionally.

Vite silently starts on another port

This should not happen with strictPort: true. Vite should exit when 5173 is unavailable. Find the process or container already using the port, stop it if appropriate, and restart Vite. If you intentionally select another port, update server.port, the Compose publication, the Localtonet target, and any local verification commands together.

Source edits do not trigger updates

First determine whether the file changed inside the container:

docker compose exec vite sh -lc "ls -l /app && date"

Inspect the edited path directly if needed. If the mounted file changes but Vite logs no event, the host and container filesystem combination may not deliver watcher events reliably. Vite supports watcher configuration through its server watch options, but polling increases resource use and should be enabled only when the environment requires it. Consult the documentation for the installed Vite release before choosing polling options and intervals.

If Vite logs an update but the browser receives no frame, return to the WebSocket path. If the browser receives an update frame but the UI remains unchanged, inspect framework plugin behavior, module boundaries, and browser console errors.

The public hostname changed

A changed hostname affects multiple independent controls. Update the Vite allowed host, any explicit HMR host, the OAuth redirect registration, the application’s public base or callback configuration, and bookmarks shared with testers. Restart Vite after changing its environment. Avoid keeping an old public URL in screenshots or automated test configuration.

The OAuth provider reports a redirect mismatch

Compare the registered URI with the URI sent in the authorization request. Check the scheme, hostname, explicit or omitted port, callback path, trailing slash, character case where relevant, and query component rules. Provider behavior varies, so use that provider’s current redirect URI requirements rather than assuming universal normalization.

Restart behavior, routine operation, and cleanup

Vite reads the configuration and PUBLIC_PREVIEW_HOST when the development server starts. If the hostname or HMR settings change, restart the Vite service:

docker compose restart vite
docker compose logs --tail=100 vite

The Compose example uses restart: unless-stopped, so Docker can restart the development container after a process or daemon restart. This does not start a Localtonet tunnel automatically or guarantee that an OAuth provider still contains the correct callback. After any restart, verify the container, local port, tunnel state, browser WebSocket, and callback configuration again.

When testing is complete, stop the public tunnel from the Localtonet dashboard. Delete it if it is no longer required. The endpoint is available only while the selected client remains connected and the tunnel is running, but intentionally stopping it is still the correct end-of-session operation.

Stop the Compose service when the local development environment is no longer needed:

docker compose down

Review OAuth provider settings and remove temporary callback URIs that should not remain registered. Also remove temporary hostname values from shared environment files, test scripts, screenshots, and team documentation. Never commit a Localtonet authentication token or OAuth secret during cleanup.

Frequently asked questions