Add compiler plugin hooks and move compilation pipeline out of App

Move the frontend compilation pipeline from App._compile into
compiler.compile_app(), introducing a CompilerPlugin protocol with
enter_component/leave_component/eval_page/compile_page hooks. Remove
the ExecutorType/ExecutorSafeFunctions abstractions in favor of a
sequential plugin-driven compilation model.

Author: FarhanAliRaza

packages/reflex-core/src/reflex_core/components/component.py

@@ -1556,6 +1556,7 @@ def _iter_parent_classes_names(cls) -> Iterator[str]:
             yield clz.__name__
 
     @classmethod
+    @functools.cache
     def _iter_parent_classes_with_method(cls, method: str) -> Sequence[type[Component]]:
         """Iterate through parent classes that define a given method.
 
@@ -1582,7 +1583,7 @@ def _iter_parent_classes_with_method(cls, method: str) -> Sequence[type[Componen
                 continue
             seen_methods.add(method_func)
             clzs.append(clz)
-        return clzs
+        return tuple(clzs)
 
     def _get_custom_code(self) -> str | None:
         """Get custom code for the component.

packages/reflex-core/src/reflex_core/environment.py

@@ -2,14 +2,11 @@
 
 from __future__ import annotations
 
-import concurrent.futures
 import dataclasses
 import enum
 import importlib
-import multiprocessing
 import os
-import platform
-from collections.abc import Callable, Sequence
+from collections.abc import Sequence
 from functools import lru_cache
 from pathlib import Path
 from typing import (
@@ -529,97 +526,6 @@ class PerformanceMode(enum.Enum):
     OFF = "off"
 
 
-class ExecutorType(enum.Enum):
-    """Executor for compiling the frontend."""
-
-    THREAD = "thread"
-    PROCESS = "process"
-    MAIN_THREAD = "main_thread"
-
-    @classmethod
-    def get_executor_from_environment(cls):
-        """Get the executor based on the environment variables.
-
-        Returns:
-            The executor.
-        """
-        from reflex_core.utils import console
-
-        executor_type = environment.REFLEX_COMPILE_EXECUTOR.get()
-
-        reflex_compile_processes = environment.REFLEX_COMPILE_PROCESSES.get()
-        reflex_compile_threads = environment.REFLEX_COMPILE_THREADS.get()
-        # By default, use the main thread. Unless the user has specified a different executor.
-        # Using a process pool is much faster, but not supported on all platforms. It's gated behind a flag.
-        if executor_type is None:
-            if (
-                platform.system() not in ("Linux", "Darwin")
-                and reflex_compile_processes is not None
-            ):
-                console.warn("Multiprocessing is only supported on Linux and MacOS.")
-
-            if (
-                platform.system() in ("Linux", "Darwin")
-                and reflex_compile_processes is not None
-            ):
-                if reflex_compile_processes == 0:
-                    console.warn(
-                        "Number of processes must be greater than 0. If you want to use the default number of processes, set REFLEX_COMPILE_EXECUTOR to 'process'. Defaulting to None."
-                    )
-                    reflex_compile_processes = None
-                elif reflex_compile_processes < 0:
-                    console.warn(
-                        "Number of processes must be greater than 0. Defaulting to None."
-                    )
-                    reflex_compile_processes = None
-                executor_type = ExecutorType.PROCESS
-            elif reflex_compile_threads is not None:
-                if reflex_compile_threads == 0:
-                    console.warn(
-                        "Number of threads must be greater than 0. If you want to use the default number of threads, set REFLEX_COMPILE_EXECUTOR to 'thread'. Defaulting to None."
-                    )
-                    reflex_compile_threads = None
-                elif reflex_compile_threads < 0:
-                    console.warn(
-                        "Number of threads must be greater than 0. Defaulting to None."
-                    )
-                    reflex_compile_threads = None
-                executor_type = ExecutorType.THREAD
-            else:
-                executor_type = ExecutorType.MAIN_THREAD
-
-        match executor_type:
-            case ExecutorType.PROCESS:
-                executor = concurrent.futures.ProcessPoolExecutor(
-                    max_workers=reflex_compile_processes,
-                    mp_context=multiprocessing.get_context("fork"),
-                )
-            case ExecutorType.THREAD:
-                executor = concurrent.futures.ThreadPoolExecutor(
-                    max_workers=reflex_compile_threads
-                )
-            case ExecutorType.MAIN_THREAD:
-                FUTURE_RESULT_TYPE = TypeVar("FUTURE_RESULT_TYPE")
-
-                class MainThreadExecutor:
-                    def __enter__(self):
-                        return self
-
-                    def __exit__(self, *args):
-                        pass
-
-                    def submit(
-                        self, fn: Callable[..., FUTURE_RESULT_TYPE], *args, **kwargs
-                    ) -> concurrent.futures.Future[FUTURE_RESULT_TYPE]:
-                        future_job = concurrent.futures.Future()
-                        future_job.set_result(fn(*args, **kwargs))
-                        return future_job
-
-                executor = MainThreadExecutor()
-
-        return executor
-
-
 class EnvironmentVariables:
     """Environment variables class to instantiate environment variables."""
 
@@ -660,14 +566,6 @@ class EnvironmentVariables:
         Path(constants.Dirs.UPLOADED_FILES)
     )
 
-    REFLEX_COMPILE_EXECUTOR: EnvVar[ExecutorType | None] = env_var(None)
-
-    # Whether to use separate processes to compile the frontend and how many. If not set, defaults to thread executor.
-    REFLEX_COMPILE_PROCESSES: EnvVar[int | None] = env_var(None)
-
-    # Whether to use separate threads to compile the frontend and how many. Defaults to `min(32, os.cpu_count() + 4)`.
-    REFLEX_COMPILE_THREADS: EnvVar[int | None] = env_var(None)
-
     # The directory to store reflex dependencies.
     REFLEX_DIR: EnvVar[Path] = env_var(constants.Reflex.DIR)
 

packages/reflex-core/src/reflex_core/plugins/__init__.py

@@ -2,12 +2,28 @@
 
 from ._screenshot import ScreenshotPlugin as _ScreenshotPlugin
 from .base import CommonContext, Plugin, PreCompileContext
+from .compiler import (
+    BaseContext,
+    CompileContext,
+    CompilerHooks,
+    CompilerPlugin,
+    ComponentAndChildren,
+    PageContext,
+    PageDefinition,
+)
 from .sitemap import SitemapPlugin
 from .tailwind_v3 import TailwindV3Plugin
 from .tailwind_v4 import TailwindV4Plugin
 
 __all__ = [
+    "BaseContext",
     "CommonContext",
+    "CompileContext",
+    "CompilerHooks",
+    "CompilerPlugin",
+    "ComponentAndChildren",
+    "PageContext",
+    "PageDefinition",
     "Plugin",
     "PreCompileContext",
     "SitemapPlugin",

packages/reflex-core/src/reflex_core/plugins/base.py

@@ -2,12 +2,14 @@
 
 from collections.abc import Callable, Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, ParamSpec, Protocol, TypedDict
+from typing import TYPE_CHECKING, Any, ParamSpec, Protocol, TypedDict
 
 from typing_extensions import Unpack
 
 if TYPE_CHECKING:
     from reflex.app import App, UnevaluatedPage
+    from reflex_core.components.component import BaseComponent, StatefulComponent
+    from reflex_core.plugins.compiler import ComponentAndChildren, PageContext
 
 
 class CommonContext(TypedDict):
@@ -117,6 +119,93 @@ def post_compile(self, **context: Unpack[PostCompileContext]) -> None:
             context: The context for the plugin.
         """
 
+    def eval_page(
+        self,
+        page_fn: Any,
+        /,
+        **kwargs: Any,
+    ) -> "PageContext | None":
+        """Evaluate a page-like object into a page context.
+
+        Args:
+            page_fn: The page-like object to evaluate.
+            kwargs: Additional compiler-specific context.
+
+        Returns:
+            A page context when the plugin can evaluate the page, otherwise ``None``.
+        """
+        del page_fn, kwargs
+        return None
+
+    def compile_page(
+        self,
+        page_ctx: "PageContext",
+        /,
+        **kwargs: Any,
+    ) -> None:
+        """Finalize a page context after its component tree has been traversed."""
+        del page_ctx, kwargs
+        return
+
+    def enter_component(
+        self,
+        comp: "BaseComponent",
+        /,
+        *,
+        page_context: "PageContext",
+        compile_context: Any,
+        in_prop_tree: bool = False,
+        stateful_component: "StatefulComponent | None" = None,
+    ) -> "BaseComponent | ComponentAndChildren | None":
+        """Inspect or transform a component before visiting its descendants.
+
+        Args:
+            comp: The component being compiled.
+            page_context: The active page compilation state.
+            compile_context: The active compile-run state.
+            in_prop_tree: Whether the component is being visited through a prop subtree.
+            stateful_component: The surrounding stateful component, when applicable.
+
+        Returns:
+            An optional replacement component and/or structural children.
+        """
+        del comp, page_context, compile_context, in_prop_tree, stateful_component
+        return None
+
+    def leave_component(
+        self,
+        comp: "BaseComponent",
+        children: tuple["BaseComponent", ...],
+        /,
+        *,
+        page_context: "PageContext",
+        compile_context: Any,
+        in_prop_tree: bool = False,
+        stateful_component: "StatefulComponent | None" = None,
+    ) -> "BaseComponent | ComponentAndChildren | None":
+        """Inspect or transform a component after visiting its descendants.
+
+        Args:
+            comp: The component being compiled.
+            children: The compiled structural children for the component.
+            page_context: The active page compilation state.
+            compile_context: The active compile-run state.
+            in_prop_tree: Whether the component is being visited through a prop subtree.
+            stateful_component: The surrounding stateful component, when applicable.
+
+        Returns:
+            An optional replacement component and/or structural children.
+        """
+        del (
+            comp,
+            children,
+            page_context,
+            compile_context,
+            in_prop_tree,
+            stateful_component,
+        )
+        return None
+
     def __repr__(self):
         """Return a string representation of the plugin.