Add native env var support: bundle-bound (baked at build) vs backend-only (runtime)

[larsblumberg]

Problem

Reflex compiles Python page code into a static JS bundle at reflex export. Any os.environ read (or pydantic_settings.BaseSettings() instantiation) that happens during page evaluation gets its return value baked into the static bundle — the value the env had at build time becomes a string literal in .web/build/client/*.js.

This is structurally inherent to the architecture: the same Python module runs at both build (export) and runtime (server), and there's nothing in the framework that distinguishes "values safe to embed in the browser bundle" from "values that must stay backend-only."

Minimal repro

# config.py
class Settings(BaseSettings):
    public_api_url: str
    db_password: str

# pages/some_page.py
def _endpoint_card() -> rx.Component:
    return rx.code(_api_url())          # called during page evaluation

def _api_url() -> str:
    return get_settings().public_api_url

get_settings() reads env vars during page evaluation. In a typical build pipeline, the real per-deployment values aren't set at build time (they come from runtime container env or secret manager), so a placeholder/dummy gets baked into the bundle. The wrong value silently ships to every browser, with no warning, no compile error, no test failure.

Worse, the same Settings() call validates all fields — so a build that has no business reading db_password is forced to provide it just to instantiate the class. Teams end up sprinkling dummy db_password=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx values into Dockerfiles, which is a code smell pointing at exactly this design gap.

Why it's a class of bug, not a one-off

• Any third-party library that reads env at import time has the same exposure.
• Any helper that lazily reads config and gets called during page evaluation has the same exposure.
• Refactors that move a backend-only call into a render path silently introduce leaks.
• Adding new env vars is a judgment call ("will this end up in the bundle?") that's invisible to the type system.

The mental model "I'm just reading an env var" doesn't match the reality "this might end up in a CDN-cached JS file forever."

Proposed solution

Make the bundle/backend split a first-class concept, the way Next.js, Nuxt, and SvelteKit do — two pydantic-style base classes provided by Reflex:

• rx.FrontendBundleEnv — values are baked into the JS bundle at reflex export. Browser-visible. Safe to read anywhere.
• rx.BackendEnv — values stay backend-only. Instantiation raises during reflex export, so accidental reads at page-evaluation time fail loud with a useful traceback instead of silently leaking into the static bundle.

The choice between "frontend bundle" and "backend" is a deployment-level decision that doesn't belong in scattered helper logic — it belongs on the env var itself. Putting it in the type lets every reader see, at the call site, which side of the split they're on.

A concrete implementation sketch (~30 lines, no new dependencies, including .get() cached-singleton accessors and the optional bundle-scan defense in depth) is in a follow-up comment below.

Prior art

• Next.js: NEXT_PUBLIC_* prefix → bundled; everything else → server-only. Compile-time check.
• Nuxt: runtimeConfig.public vs runtimeConfig.
• SvelteKit: $env/static/public / $env/static/private / $env/dynamic/public / $env/dynamic/private — the import path itself encodes the classification.

All three solve the same structural problem the same way: make "is this safe to ship to the browser?" a property of the variable, not a judgment call at every read site.

Workaround until upstream support exists

The same shape can be built manually today:

• Two BaseSettings subclasses (e.g. FrontendBundleEnv, BackendEnv)
• A BUILDING_FRONTEND_BUNDLE=1 env set in the Dockerfile for the reflex export step
• get_backend_env() raises if that flag is set
• View code reads get_frontend_bundle_env() directly at module load (no state var) since values are constant per-bundle

It works, but every Reflex user with a real deployment will hit this same shape eventually. Built-in support would catch the bug at framework level rather than relying on each team to reinvent it.

[linear-code]

ENG-9601

[larsblumberg]

Proposed implementation: rx.FrontendBundleEnv / rx.BackendEnv

Core: new reflex/env.py module

import os
from functools import lru_cache
from pydantic_settings import BaseSettings

_EXPORT_FLAG = "REFLEX_EXPORTING"


def _is_exporting() -> bool:
    return os.environ.get(_EXPORT_FLAG) == "1"


class _EnvBase(BaseSettings):
    @classmethod
    @lru_cache(maxsize=None)
    def get(cls):
        """Return the cached singleton for this subclass.

        Env-derived settings don't change at runtime, so re-instantiating
        on every call is pure waste. Subclasses inherit this for free.
        """
        return cls()


class FrontendBundleEnv(_EnvBase):
    """Bundle-bound env vars. Values get baked into the JS at `reflex export`.

    Safe to instantiate anywhere — module level, page evaluation, request
    handlers. Reading at export time is the point: that's when the values
    get embedded in the static bundle shipped to the browser.
    """
    pass


class BackendEnv(_EnvBase):
    """Backend-only env vars. Must NEVER end up in the JS bundle.

    Instantiation raises during `reflex export` so accidental reads at
    page-evaluation time fail loud with a useful traceback, instead of
    silently baking the value into the static bundle shipped to every
    browser.

    The guard is on `__init__`, not on `.get()`, so it catches both
    `MySettings.get()` and any direct `MySettings()` call.
    """
    def __init__(self, **kwargs):
        if _is_exporting():
            raise RuntimeError(
                f"{type(self).__name__} (a BackendEnv subclass) was "
                f"instantiated during `reflex export`. These values are "
                f"backend-only — reading them at export silently bakes "
                f"them into the static JS bundle.\n\n"
                f"Move this read into a request handler, @rx.var method, "
                f"background task, or lifespan startup — anywhere that "
                f"runs after the bundle is built."
            )
        super().__init__(**kwargs)

CLI hook in reflex/reflex.py

@cli.command()
def export(...):
    os.environ[_EXPORT_FLAG] = "1"
    try:
        export_utils.export(...)
    finally:
        os.environ.pop(_EXPORT_FLAG, None)

That's it. An env var is used instead of a ContextVar so the flag also covers any subprocess reflex export happens to spawn.

What users write

import reflex as rx

class BundleSettings(rx.FrontendBundleEnv):
    api_url: str
    feature_flag_x: bool = False

class BackendSettings(rx.BackendEnv):
    db_url: str
    third_party_secret_key: str

# Anywhere — module level, page evaluation, render path:
api_url = BundleSettings.get().api_url     # cached singleton, gets baked

# Inside @rx.event / @rx.var / lifespan / background task:
db = BackendSettings.get().db_url          # cached singleton, runtime only

# During `reflex export`, accidentally at page evaluation:
db = BackendSettings.get().db_url          # raises RuntimeError with clear message

.get() returns the cached singleton — no @lru_cache boilerplate per class. Direct BackendSettings(**kwargs) calls still work as an escape hatch for tests that want to inject overrides, and the export-time guard catches those too.

The traceback points at the exact line — the fix is obvious.

Extensions worth considering (follow-ups, not blockers)

Bundle scan (defense in depth)

After reflex export, instantiate each BackendEnv subclass (using the env present at deploy time, or sentinel placeholders set by CI) and grep .web/build/client for those values. Fails the build if a third-party library or hardcoded literal slipped through that the __init__ guard couldn't catch.

Useful because os.environ[...] calls from third-party libraries at import time aren't subject to the guard.

Auto-prefix enforcement (Next.js-style)

Optionally require FrontendBundleEnv fields to have env var names starting with REFLEX_PUBLIC_ (or similar). Surfaces the intent at the env-var level — anyone reading a deployment manifest can tell which vars are bundle-bound. Configurable in rxconfig.py.

Static lint via reflex check

A pre-commit or CI subcommand that statically inspects pages for os.environ[...] / os.getenv(...) reads outside event handlers and @rx.var methods, flagging anything not routed through FrontendBundleEnv. Catches raw env reads that don't go through pydantic at all.

Migration path for existing users

Document the pattern in the Reflex deployment guide. The transition is mechanical:

1. Identify the existing Settings/BaseSettings class.
2. Split fields by the test "does the browser need this baked in?"
3. Subclass FrontendBundleEnv / BackendEnv accordingly.
4. Replace get_settings() call sites with the appropriate accessor.

The BackendEnv guard immediately surfaces any leak in the existing code paths.

[larsblumberg]

If this proposal lands interest by you maintainers, I am happy to iterate over it via a PR.

[masenf]

we're considering this, but if it comes in, i think it should aim to replace/extend the current Config mechanisms in the framework, where we already have quite a bit of env var and config precedence handling logic.

not ready for a PR yet, but lets keep the conversation going.

[larsblumberg]

Thanks, that makes sense. I looked through the current Config and environment handling, and I agree this should extend the existing config path rather than introduce a parallel pydantic-settings mechanism.

A revised shape could be:

import reflex as rx


class FrontendEnv(rx.FrontendEnv):
    analytics_write_key: str
    billing_public_key: str | None = None
    feature_flag_x: bool = False


class BackendEnv(rx.BackendEnv):
    openai_api_key: str
    stripe_webhook_secret: str
    internal_api_token: str


config = rx.Config(
    app_name="my_app",
    frontend_env=FrontendEnv,
    backend_env=BackendEnv,
)

The core idea is:

• rx.Config remains the registry and source of truth.
• frontend_env and backend_env point to classes, not instances, so registration itself has no side effects.
• Reflex resolves these app env values through Config when accessed, using the same env parsing/conversion path as existing config fields.
• These classes are for app-defined env vars. Existing Reflex-owned config fields such as api_url, db_url, deploy_url, and redis_url should keep their current rx.Config API.
• FrontendEnv values are allowed during frontend bundle generation; if used in page evaluation, they may be baked into the generated JS bundle.
• BackendEnv values are backend/runtime-only. Accessing config.backend_env while generating the frontend bundle should raise with a clear error instead of silently leaking a value into the bundle.
• This is backwards-compatible and opt-in. Existing Reflex apps can keep using their current rx.Config, .env, raw os.environ, or custom settings machinery unchanged.

App code would access these values through the same config access pattern Reflex already exposes:

import reflex as rx


analytics_key = rx.config.get_config().frontend_env.analytics_write_key

and backend-only runtime code can use:

import reflex as rx


openai_api_key = rx.config.get_config().backend_env.openai_api_key

During frontend bundle generation, rx.config.get_config().backend_env would raise a clear error such as:

BackendEnv was accessed while generating the frontend bundle. Backend env values are runtime-only and must not be read during page evaluation. Move this access into an event handler, backend route, lifespan task, or another backend-only runtime path.

A few implementation notes from reading the current code:

• Config.update_from_env() already applies env overrides with type conversion via interpret_env_var_value(). App env classes should reuse that machinery rather than adding a separate settings system.
• This preserves existing type conversion behavior for bool, int, float, str, Path, Enum, Literal, sequences, optionals/unions, etc.
• Reflex already tracks compile context through environment.REFLEX_COMPILE_CONTEXT (RUN, EXPORT, DEPLOY, UNDEFINED). The backend-env guard can use that.
• Backend app env values should probably be treated as sensitive by default in debug logging.
• This design leaves room for Reflex's built-in config/env fields to eventually use the same frontend/backend classification internally, without making that migration part of the first PR.
• Users should not duplicate Reflex-owned fields in FrontendEnv or BackendEnv; the first version should focus on env vars owned by the app.

This also avoids overloading rx.Config with arbitrary user fields while still making app-defined env vars first-class in the framework. The explicit frontend_env= / backend_env= parameters seem preferable to a generic list like env=[...], because the frontend/backend classification is visible at the registration site and there is no ordering ambiguity.

I am happy to keep iterating on this direction before opening a PR.