feat: add backend_path config to prefix backend routes

[FarhanAliRaza]

Mirrors frontend_path: sets a URL prefix (e.g. "/api") applied to every backend endpoint (event websocket, /ping, /_upload, /_health, /_all_routes) and automatically included in URLs baked into the frontend via Endpoint.get_url(). Enables proxying Reflex behind a subpath without request rewriting or baking the prefix into api_url.

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

New Feature Submission:

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

Changes To Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

closes #6305

[codspeed-hq]

Merging this PR will not alter performance

✅ 9 untouched benchmarks

---

_{Comparing FarhanAliRaza:add-backend-path (bc80862) with main (d6db9c9)}

[greptile-apps]

Greptile Summary

This PR adds a backend_path config option (e.g. "/api") that prefixes every backend endpoint (event websocket, /ping, /_upload, /_health, /_all_routes) at both the Starlette mount layer and in the URLs baked into the frontend via env.json (populated through Endpoint.get_url()). It closely mirrors the existing frontend_path pattern, refactoring shared normalization logic into a _prepend_path static helper.

Confidence Score: 5/5

Safe to merge; all remaining findings are style-level P2 suggestions.

The feature is correctly implemented end-to-end: backend_path normalisation is consistent, all five Starlette mount points are updated, Endpoint.get_url() propagates the prefix into env.json so the frontend picks it up automatically, unit tests cover path edge cases and the namespace/mount invariant, and integration tests exercise both the no-prefix and /api cases. No P0/P1 issues found.

Minor: reflex/app.py (inline get_config() in add_all_routes_endpoint) and tests/integration/tests_playwright/test_backend_path.py (rx.App() result not stored as app).

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/config.py	Adds backend_path: str = "" field, _prepend_path static normalizer, and prepend_backend_path method; refactors prepend_frontend_path to use the shared helper — clean and correct.
packages/reflex-base/src/reflex_base/constants/event.py	Endpoint.get_url() now calls config.prepend_backend_path(str(self)), so all URLs baked into env.json (via set_env_json) and returned to callers include the configured prefix.
reflex/app.py	All five Starlette route/mount registrations updated to use prepend_backend_path; minor inconsistency in add_all_routes_endpoint which calls get_config() inline instead of storing it at the top of the method.
tests/units/test_config.py	New parametrized unit tests cover path normalization, Endpoint.get_url() with all endpoints × three backend_path variants, and the invariant that the Socket.IO namespace equals the HTTP mount path.
tests/integration/tests_playwright/test_backend_path.py	New integration tests parametrised over no-prefix / /api; rx.App() result not assigned to a variable, inconsistent with the documented test-factory pattern.
tests/integration/tests_playwright/test_stateless_app.py	Updated to use Endpoint.PING.get_url() and config.prepend_backend_path(str(Endpoint.EVENT)) instead of manually constructing URLs; correct and more resilient.
tests/integration/test_upload.py	Replaced manual get_config().api_url + endpoint.value construction with Endpoint.UPLOAD.get_url(), correctly picking up backend_path automatically.
docs/hosting/self-hosting.md	New 'Proxying to a Subpath' section documents backend_path usage, the relationship with frontend_path, and the full-restart requirement.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[rxconfig.py\nbackend_path = '/api'] --> B[Config.prepend_backend_path]
    B --> C1[app.py: _setup_state\nmount '/_event' → '/api/_event']
    B --> C2[app.py: _add_default_endpoints\n/ping → /api/ping\n/_health → /api/_health]
    B --> C3[app.py: _add_optional_endpoints\n/_upload → /api/_upload]
    B --> C4[app.py: add_all_routes_endpoint\n/_all_routes → /api/_all_routes]
    B --> C5[Endpoint.get_url\nreturns api_url + /api/endpoint]
    C5 --> D[set_env_json\nbakes prefixed URLs into env.json]
    D --> E[Frontend JS\nreads env.EVENT / env.UPLOAD\nconnects to /api/_event]
    C1 & C2 & C3 & C4 --> F[Starlette routes\nmounted at prefixed paths]
    E -->|WebSocket| F

Loading

_{Reviews (1): Last reviewed commit: "feat: add backend_path config to prefix ..." | Re-trigger Greptile}