docs(proxy): note that existing middleware can intercept the Next.js rewrites proxy path

[molockss]

Problem

If you set up the reverse proxy on a Next.js app that already has middleware, the middleware can grab the proxy path before the rewrite runs. I hit this with next-intl but it applies to NextAuth or any custom middleware.ts / proxy.ts too.

In my case next-intl with localePrefix: 'always' turned POST /ingest/s into a 307 to /en/ingest/s, which 404s. Same for /ingest/e and /ingest/flags. So no events, feature flags, or recordings made it to PostHog.

What made it slow to track down: the static SDK assets at /ingest/static/*.js have a file extension, so the default next-intl matcher /((?!api|_next|_vercel|.*\\..*).*) skips them and they load fine. PostHog initializes and looks connected. Only the no-extension endpoints get redirected, and those are the ones that actually carry the data.

The fix is one line. Add the proxy path to the matcher's negative lookahead:

matcher: ['/((?!api|ingest|_next|_vercel|.*\\..*).*)']

Change

The rewrites guide doesn't mention any of this. This adds a warning callout in the Setup step and a bullet under "Rewrites not working" so people don't lose an hour to it.

I found this going through the setup wizard, which follows this page. See PostHog/wizard#62 — this is the docs side of that. (Different repo, so it won't auto-close.)

[molockss]

@bretthoerner @gesh @pauldambra kindly review :)