Infinite RPC reconnection loop when running behind reverse proxy (nginx)

[fabkho]

Environment

• @nuxt/a11y version: 1.0.0-alpha.1
• Nuxt version: 4.x
• Reverse proxy: nginx (Laravel Valet)

Reproduction

1. Run a Nuxt app with @nuxt/a11y behind a reverse proxy (nginx)
2. Add the /__nuxt-a11y-client location block to nginx config
3. Open DevTools and navigate to the a11y tab
4. Observe the infinite reconnection loop in WebSocket messages and console

Describe the bug

Setup

I'm running a Nuxt app behind an nginx reverse proxy with a base path:

location /admin {
    proxy_pass http://127.0.0.1:8091;
    proxy_set_header X-Real-Ip $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

# Added for a11y module
location /__nuxt-a11y-client {
    proxy_pass http://127.0.0.1:8091;
    proxy_set_header X-Real-Ip $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Without the added "location /__nuxt-a11y-client" it does not work at all cause this module does not set the baseUrl set in nuxt config. Other modules devtools just work btw. So maybe we should do that?

Problem

When I open the Nuxt DevTools and navigate to the a11y tab, the module enters an infinite reconnection loop. The WebSocket messages show nuxt-a11y-rpc:connected being called repeatedly with different IDs:

This causes:

• Continuous scanning that never stops
• Console logs repeating indefinitely
• DevTools UI constantly reloading/refreshing

The loop stops when I switch to a different DevTools tab.

Possible cause

The onDevtoolsClientConnected callback in client/app/composables/rpc.ts appears to fire multiple times when the connection is unstable. Each call triggers nuxtA11yRpc.value!.connected() which sends nuxt-a11y:connected to the main app, triggering a new scan.

Temporary fix

Add a guard to prevent multiple connected() calls:

let hasConnected = false

onDevtoolsClientConnected(async (client) => {
  // ... setup code ...

  if (!hasConnected) {
    hasConnected = true
    try {
      await nuxtA11yRpc.value!.connected()
    } catch (error) {
      console.debug('[Nuxt A11y] Initial connection error (expected):', error)
    }
  }
})

Additional context

No response

Logs

[timdamen]

Thanks for the detailed report @fabkho! After investigating, I can confirm there are two bugs here:

1. Infinite reconnection loop

The onDevtoolsClientConnected callback fires every time the devtools iframe reconnects (via the __NUXT_DEVTOOLS__ property setter). Behind a reverse proxy with unstable WebSocket connections, this happens repeatedly. Each invocation calls connected() → server sends nuxt-a11y:connected → client plugin triggers scanAndBroadcast() — creating the infinite loop you described.

Fix: Adding a hasConnected guard (exactly as you suggested) so the initial connected() call only happens once. The RPC setup itself still runs on reconnection to keep the reference fresh.

2. DevTools tab doesn't respect app.baseURL

The custom tab iframe src is hardcoded to /__nuxt-a11y-client without considering nuxt.options.app.baseURL. This is why the module doesn't work at all behind a reverse proxy without the extra nginx location block. Other Nuxt modules like @nuxt/fonts had the same issue and fixed it using joinURL(nuxt.options.app.baseURL, path).

Fix: Using joinURL from ufo to prepend the baseURL to the iframe src.

Working on a PR for both fixes.