Let's create a new app called hello

mkdir hello
cd hello
reflex init

This will create a directory structure like this:

hello
├── .web
├── assets
├── hello
│   ├── __init__.py
│   └── hello.py
└── rxconfig.py

Let's go over each of these directories and files.

This is where the compiled Javascript files will be stored. You will never need to touch this directory, but it can be useful for debugging.

Each Reflex page will compile to a corresponding .js file in the .web/pages directory.

The assets directory is where you can store any static assets you want to be publicly available. This includes images, fonts, and other files.

For example, if you save an image to assets/image.png you can display it from your app like this:

rx.image(src="image.png")

Initializing your project creates a directory with the same name as your app. This is where you will write your app's logic.

Reflex generates a default app within the hello/hello.py file. You can modify this file to customize your app.

The rxconfig.py file can be used to configure your app. By default it looks something like this:

import reflex as rx


config = rx.Config(
    app_name="hello",
)

We will discuss configuration in more detail in the next section.

Reflex imports the main app module based on the app_name from the config, which must define a module-level global named app as an instance of rx.App.

The main app module is responsible for importing all other modules that make up the app and defining app = rx.App().

All other modules containing pages, state, and models MUST be imported by the main app module or package for Reflex to include them in the compiled output.

As applications scale, effective organization is crucial. This is achieved by breaking the application down into smaller, manageable modules and organizing them into logical packages that avoid circular dependencies.

In the following documentation there will be an app with an app_name of example_big_app. The main module would be example_big_app/example_big_app.py.

In the Putting it all together section there is a visual of the project folder structure to help follow along with the examples below.

All complex apps will have multiple pages, so it is recommended to create example_big_app/pages as a package.

1. This package should contain one module per page in the app.
2. If a particular page depends on the state, the substate should be defined in the same module as the page.
3. The page-returning function should be decorated with rx.page() to have it added as a route in the app.

import reflex as rx

from ..state import AuthState


class LoginState(AuthState):
    def handle_submit(self, form_data):
        self.logged_in = authenticate(
            form_data["username"], form_data["password"]
        )


def login_field(name: str, **input_props):
    return rx.hstack(
        rx.text(name.capitalize()),
        rx.input(name=name, **input_props),
        width="100%",
        justify="between",
    )


@rx.page(route="/login")
def login():
    return rx.card(
        rx.form(
            rx.vstack(
                login_field("username"),
                login_field("password", type="password"),
                rx.button("Login"),
                width="100%",
                justify="center",
            ),
            on_submit=LoginState.handle_submit,
        ),
    )

Most applications maintain a consistent layout and structure across pages. Defining this common structure in a separate module facilitates easy sharing and reuse when constructing individual pages.

Best Practices

1. Factor out common frontend UI elements into a function that returns a component.
2. If a function accepts a function that returns a component, it can be used as a decorator as seen below.

from typing import Callable

import reflex as rx

from .components.menu import menu
from .components.navbar import navbar


def template(
    page: Callable[[], rx.Component]
) -> rx.Component:
    return rx.vstack(
        navbar(),
        rx.hstack(
            menu(),
            rx.container(page()),
        ),
        width="100%",
    )

The @template decorator should appear below the @rx.page decorator and above the page-returning function. See the Posts Page code for an example.

Most pages will use State in some capacity. You should avoid adding vars to a shared state that will only be used in a single page. Instead, define a new subclass of rx.State and keep it in the same module as the page.

As of Reflex 0.4.3, any event handler can get access to an instance of any other substate via the get_state API. From a practical perspective, this means that state can be split up into smaller pieces without requiring a complex inheritance hierarchy to share access to other states.

In previous releases, if an app wanted to store settings in SettingsState with a page or component for modifying them, any other state with an event handler that needed to access those settings would have to inherit from SettingsState, even if the other state was mostly orthogonal. The other state would also now always have to load the settings, even for event handlers that didn't need to access them.

A better strategy is to load the desired state on demand from only the event handler which needs access to the substate.

import reflex as rx


class SettingsState(rx.State):
    refresh_interval: int = 15
    auto_update: bool = True
    prefer_plain_text: bool = True
    posts_per_page: int = 20


def settings_dialog():
    return rx.dialog(...)

This page loads the SettingsState to determine how many posts to display per page and how often to refresh.

import reflex as rx

from ..models import Post
from ..template import template
from ..components.settings import SettingsState


class PostsState(rx.State):
    refresh_tick: int
    page: int
    posts: list[Post]

    async def on_load(self):
        settings = await self.get_state(SettingsState)
        if settings.auto_update:
            self.refresh_tick = (
                settings.refresh_interval * 1000
            )
        else:
            self.refresh_tick = 0

    async def tick(self, _):
        settings = await self.get_state(SettingsState)
        with rx.session() as session:
            q = (
                Post.select()
                .offset(self.page * settings.posts_per_page)
                .limit(settings.posts_per_page)
            )
            self.posts = q.all()

    def go_to_previous(self):
        if self.page > 0:
            self.page = self.page - 1

    def go_to_next(self):
        if self.posts:
            self.page = self.page + 1


@rx.page(route="/posts", on_load=PostsState.on_load)
@template
def posts():
    return rx.vstack(
        rx.foreach(PostsState.posts, post_view),
        rx.hstack(
            rx.button(
                "< Prev", on_click=PostsState.go_to_previous
            ),
            rx.button(
                "Next >", on_click=PostsState.go_to_next
            ),
            justify="between",
        ),
        rx.moment(
            interval=PostsState.refresh_tick,
            on_change=PostsState.tick,
            display="none",
        ),
        width="100%",
    )

Common states and substates that are shared by multiple pages or components should be implemented in a separate module to avoid circular imports. This module should not import other modules in the app.

The primary mechanism for reusing components in Reflex is to define a function that returns the component, then simply call it where that functionality is needed.

Component functions typically should not take any State classes as arguments, but prefer to import the needed state and access the vars on the class directly.

In a large app, if a component has many subcomponents or is used in a large number of places, it can improve compile and runtime performance to memoize the function with the @lru_cache decorator.

To memoize the foo component to avoid re-creating it many times simply add @lru_cache to the function definition, and the component will only be created once per unique set of arguments.

from functools import lru_cache

import reflex as rx


class State(rx.State):
    v: str = "foo"


@lru_cache
def foo():
    return rx.text(State.v)


def index():
    return rx.flex(
        rx.button(
            "Change",
            on_click=State.set_v(
                rx.cond(State.v != "bar", "bar", "foo")
            ),
        ),
        *[foo() for _ in range(100)],
        direction="row",
        wrap="wrap",
    )

This package contains reusable parts of the app, for example headers, footers, and menus. If a particular component requires state, the substate may be defined in the same module for locality. Any substate defined in a component module should only contain fields and event handlers pertaining to that individual component.

Reflex 0.4.3 introduced support for the reflex component CLI commands, which makes it easy to bundle up common functionality to publish on PyPI as a standalone Python package that can be installed and used in any Reflex app.

When wrapping npm components or other self-contained bits of functionality, it can be helpful to move this complexity outside the app itself for easier maintenance and reuse in other apps.

It is recommended to implement all database models in a single file to make it easier to define relationships and understand the entire schema.

However, if the schema is very large, it might make sense to have a models package with individual models defined in their own modules.

At any rate, defining the models separately allows any page or component to import and use them without circular imports.

This is a great place to import all state, models, and pages that should be part of the app. Typically, components and helpers do not need to imported, because they will be imported by pages that use them (or they would be unused).

from . import state, models
from .pages import (
    index,
    login,
    post,
    product,
    profile,
    schedule,
)

__all__ = [
    "state",
    "models",
    "index",
    "login",
    "post",
    "product",
    "profile",
    "schedule",
]

If any pages are not imported here, they will not be compiled as part of the app.

This is the main app module. Since everything else is defined in other modules, this file becomes very simple.

import reflex as rx

app = rx.App()

There are two categories of non-code assets (media, fonts, stylesheets, documents) typically used in a Reflex app.

The assets directory is used for static files that should be accessible relative to the root of the frontend (default port 3000). When an app is deployed in production mode, changes to the assets directory will NOT be available at runtime!

When referencing an asset, always use a leading forward slash, so the asset can be resolved regardless of the page route where it may appear.

If an app needs to make files available dynamically at runtime, it is recommended to set the target directory via REFLEX_UPLOADED_FILES_DIR environment variable (default ./uploaded_files), write files relative to the path returned by rx.get_upload_dir(), and create working links via rx.get_upload_url(relative_path).

Uploaded files are served from the backend (default port 8000) via /_upload/<relative_path>

Based on the previous discussion, the recommended project layout look like this.

example-big-app/
├─ assets/
├─ example_big_app/
│  ├─ components/
│  │  ├─ __init__.py
│  │  ├─ auth.py
│  │  ├─ footer.py
│  │  ├─ menu.py
│  │  ├─ navbar.py
│  ├─ pages/
│  │  ├─ __init__.py
│  │  ├─ index.py
│  │  ├─ login.py
│  │  ├─ posts.py
│  │  ├─ product.py
│  │  ├─ profile.py
│  │  ├─ schedule.py
│  ├─ __init__.py
│  ├─ example_big_app.py
│  ├─ models.py
│  ├─ state.py
│  ├─ template.py
├─ uploaded_files/
├─ requirements.txt
├─ rxconfig.py

• Like any other Python project, split up the app into modules and packages to keep the codebase organized and manageable.
• Using smaller modules and packages makes it easier to reuse components and state across the app without introducing circular dependencies.
• Create individual functions to encapsulate units of functionality and reuse them where needed.