Production build fails with `StateContexts is not defined` during prerender in 0.9.2.post1

[VarYUvrc]

Describe the bug
Production build fails in Reflex 0.9.2, 0.9.2.post1 during prerendering with:

ReferenceError: StateContexts is not defined

The generated route file .web/app/routes/_index.jsx references StateContexts:

useContext(StateContexts.some_state_context)

but the same generated file does not import StateContexts from $/utils/context.

In my generated file, the import was:

import {ClientSide, ColorModeContext} from "$/utils/context"

so prerendering / fails.

To Reproduce

1. Use Reflex 0.9.2.post1.
2. Create an app with state-dependent components on the index page.
3. Run:

uv run reflex run --env prod

4. The production build fails during prerendering with StateContexts is not defined.

The app starts successfully if SSR/prerendering is disabled:

REFLEX_SSR=false uv run reflex run --env prod

Expected behavior

Production build should complete successfully.

If generated route code references StateContexts, the generated route file should import it:

import {ClientSide, ColorModeContext, StateContexts} from "$/utils/context"

When SSR/prerendering is disabled via REFLEX_SSR=false, Reflex should also ensure that the generated React Router config does not attempt to prerender the route.

Screenshots
Not applicable.

Specifics (please complete the following information):

• Python Version:3.12
• Reflex Version: 0.9.2.post1
• OS: Ubuntu 24.04 LTS (WSL2)
• Package manager: uv

Additional context

As a temporary workaround for users affected by this issue, disabling SSR in rxconfig.py also avoids the production build failure:

import os

os.environ.setdefault("REFLEX_SSR", "false")

This should be placed before Reflex reads the environment configuration.

[linear]

ENG-9499

[VarYUvrc]

Additional finding:

After posting this issue, I found that REFLEX_SSR=false is only a partial workaround.

With SSR/prerendering disabled, the production build can complete and the server can start, but opening the app in the browser can still fail with the same kind of frontend runtime error:

ReferenceError: StateContexts is not defined

The reason appears to be the same generated route module problem: the client-side route bundle still contains code like:

useContext(StateContexts.some_state_context)

but the generated route file does not import StateContexts from $/utils/context.

So the issue is not limited to prerendering. It also affects the generated client-side route code.

I also saw a similar runtime failure for a custom component defined via add_custom_code() and referenced from a generated route/component module:

ReferenceError: SomeCustomComponent is not defined

This looks like a related import/scope propagation issue in the generated route/component output.

Updated expected behavior:

• If generated route code references StateContexts, the generated route module should import it from $/utils/context.
• Disabling SSR with REFLEX_SSR=false should not be considered a full workaround if the client bundle still contains missing imports.
• Symbols introduced by add_custom_code() should be available in every generated module that references them, or Reflex should emit/import them in a module-safe way.

[masenf]

can you provide repro code.

running the following app with uv run reflex run --env prod did not produce an error and the resulting app worked on 0.9.2.post1

import reflex as rx


class State(rx.State):
    v: int = 0

    @rx.event
    def increment(self):
        self.v += 1


def index() -> rx.Component:
    return rx.container(
        rx.vstack(
            rx.heading("Welcome to Reflex!", size="9"),
            rx.button(
                State.v,
                on_click=State.increment,
            ),
        ),
    )


app = rx.App()
app.add_page(index)

[VarYUvrc]

@masenf
Thanks, and sorry. I should have checked a simpler app.

I did some additional narrowing and found a minimal pattern that reproduces it. My app has a chat/log-viewer-like structure where the same state-backed body component is reused, and auto-scroll is conditionally enabled or disabled.

Here is a minimal repro:

import reflex as rx


class State(rx.State):
    text: str = "## Hello\n\nState-backed content"
    auto_scroll: bool = True


def make_child() -> rx.Component:
    return rx.el.div(rx.markdown(State.text))


def index() -> rx.Component:
    child = make_child()

    return rx.container(
        rx.cond(
            State.auto_scroll,
            rx.auto_scroll(child),
            rx.box(child),
        )
    )


app = rx.App()
app.add_page(index)

This does not seem limited to production prerendering.

With:

uv run reflex run

the app starts, but opening it in the browser fails with:

[Reflex Frontend Exception]
ReferenceError: StateContexts is not defined
ReferenceError: StateContexts is not defined

With:

uv run reflex run --env prod

the production build fails during prerendering with the same underlying error.

The generated .web/app/routes/_index.jsx contains route-level code like:

const ...state = useContext(StateContexts....state)

but the same route module does not import StateContexts from $/utils/context:

import {ColorModeContext} from "$/utils/context"

.web/utils/context.js does export StateContexts, so this looks like a missing import in the generated route module.

The pattern appears to be:

• an outer rx.cond(...)
• the true branch is rx.auto_scroll(shared_child)
• the false branch is a normal wrapper such as rx.box(shared_child)
• the same state-backed child component object is reused in both branches

This may not be a common minimal example, but I think it is a realistic UI pattern for chat or log viewer screens: build one body component, then conditionally switch auto-scroll on or off.

A practical workaround is to avoid sharing the same child object across the two branches:

def make_child() -> rx.Component:
    return rx.el.div(rx.markdown(State.text))


return rx.container(
    rx.cond(
        State.auto_scroll,
        rx.auto_scroll(make_child()),
        rx.box(make_child()),
    )
)

So I think the generated route module should import StateContexts and useContext whenever it emits route-level useContext(StateContexts...).

[VarYUvrc]

One more clarification from my narrowing:

This does not look like a problem with one specific component. It seems like the key is a combination of a few conditions.

First, this is not specific to rx.markdown. I saw the same kind of issue with the same shared-child pattern using:

rx.markdown(State.text)
rx.text(State.text)
rx.html(State.html_text)
rx.el.div(State.text)

At the same time, rx.auto_scroll does not always fail by itself.

For example, this passed when there was no outer rx.cond:

rx.auto_scroll(child)

This also passed when both branches of the outer rx.cond used normal wrappers:

rx.cond(condition, rx.box(child), rx.box(child))

And this passed too, as long as each branch got a separately constructed but equivalent child:

rx.cond(
    condition,
    rx.auto_scroll(make_child()),
    rx.box(make_child()),
)

So far, the only failing pattern I found is this: the same child that reads state is reused in both branches, and only one branch wraps it with rx.auto_scroll.

child = make_child()

rx.cond(
    condition,
    rx.auto_scroll(child),
    rx.box(child),
)

So my current understanding is that this is not rx.markdown alone or rx.auto_scroll alone. It looks like the generated route module misses import propagation when rx.cond, rx.auto_scroll, and a shared child that reads state are combined in this way.