[Runtime Config] support runtime config via `.json` file when using `npm run dev`

[brian-smith-tcril]

Warning

This issue description was generated using an LLM based on the transcript from the FWG meeting where this was discussed. I will update it to better reflect reality as I work on it.

Context

We want frontend-base (and apps using it) to support runtime config loaded from a hosted JSON file. During the 2025-12-18 Frontend Working Group meeting, I said I’d look into a good dev story that lets us iterate on runtime config and validate behavior while running apps in dev.

This work is about consuming runtime config in dev, not defining or generating it.

Problem

There is currently no clear or documented way to:

• configure frontend-base to read runtime config from a hosted URL in dev, and
• iterate on that config locally and verify behavior while the app is running.

Goal

Provide a simple, well-documented way for apps running in dev to fetch runtime config from a URL, so developers can edit a JSON file, refresh, and confirm runtime-config-driven behavior (e.g., external routes).

Scope

• Define how a runtime-config URL is configured in dev (env var / config option).
• Ensure frontend-base fetches and uses that config reliably in dev.
• Optionally provide a lightweight helper for serving a local JSON file, but without changing the app’s dev server workflow.

Non-goals

• Building the backend translation endpoint/plugin.
• Hot-reloading runtime config without refresh.
• Solving all runtime-config use cases (this is about the dev loop).

Proposed approach

Runtime-config URL

• Introduce or document a single config value (e.g. RUNTIME_CONFIG_URL) that frontend-base uses to fetch runtime config.
• frontend-base fetches this URL at startup (and on reload).

Optional helper for local JSON

• Provide an optional helper command to serve a local JSON file as a hosted endpoint:

  • e.g. an extra frontend-base script or an openedx CLI helper

• This helper runs independently of the app’s dev server.

Dev workflow example

1. Serve runtime-config.json via the helper (or any local server)
2. Run the app in dev as usual
3. Edit the JSON → refresh browser → observe changes

Acceptance criteria

• Apps running in dev can be configured to fetch runtime config from a URL.
• Editing the JSON and refreshing the page updates runtime-config-driven behavior.
• The workflow is documented and easy to follow.

[brian-smith-tcril]

Got a proof-of-concept working with

• openedx/frontend-app-authn@f854877
• d3669b2