Command Reference
The custom component commands are under reflex component
subcommand. To see the list of available commands, run reflex component --help
. To see the manual on a specific command, run reflex component <command> --help
, for example, reflex component init --help
.
reflex component --help
Usage: reflex component [OPTIONS] COMMAND [ARGS]...
Subcommands for creating and publishing Custom Components.
Options:
--help Show this message and exit.
Commands:
build Build a custom component.
init Initialize a custom component.
publish Publish a custom component.
reflex component init
Below is an example of running the init
command.
reflex component init
reflex component init
─────────────────────────────────────── Initializing reflex-google-auth project ───────────────────────────────────────
Info: Populating pyproject.toml with package name: reflex-google-auth
Info: Initializing the component directory: custom_components/reflex_google_auth
Info: Creating app for testing: google_auth_demo
──────────────────────────────────────────── Initializing google_auth_demo ────────────────────────────────────────────
[07:58:16] Initializing the app directory. console.py:85
Initializing the web directory. console.py:85
Success: Initialized google_auth_demo
─────────────────────────────────── Installing reflex-google-auth in editable mode. ───────────────────────────────────
Info: Package reflex-google-auth installed!
Custom component initialized successfully!
─────────────────────────────────────────────────── Project Summary ───────────────────────────────────────────────────
[ README.md ]: Package description. Please add usage examples.
[ pyproject.toml ]: Project configuration file. Please fill in details such as your name, email, homepage URL.
[ custom_components/ ]: Custom component code template. Start by editing it with your component implementation.
[ google_auth_demo/ ]: Demo App. Add more code to this app and test.
The init
command uses the current enclosing folder name to construct a python package name, typically in the kebab case. For example, if running init in folder google_auth
, the package name will be reflex-google-auth
. The added prefix reduces the chance of name collision on PyPI (the Python Package Index), and it indicates that the package is a Reflex custom component. The user can override the package name by providing the --package-name
option.
The init
command creates a set of files and folders prefilled with the package name and other details. During the init, the custom_component
folder is installed locally in editable mode, so a developer can incrementally develop and test with ease. The changes in component implementation is automatically reflected where it is used. Below is the folder structure after the init
command.
google_auth/
├── pyproject.toml
├── README.md
├── custom_components/
│ └── reflex_google_auth/
│ ├── google_auth.py
│ └── __init__.py
└── google_auth_demo/
└── assets/
google_auth_demo/
requirements.txt
rxconfig.py
pyproject.toml
The pyproject.toml
is required for the package to build and be published. It is prefilled with information such as the package name, version (0.0.1
), author name and email, homepage URL. By default the Apache-2.0 license is used, the same as Reflex. If any of this information requires update, the user can edit the file by hand.
README
The README.md
file is created with installation instructions, e.g. pip install reflex-google-auth
, and a brief description of the package. Typically the README.md
contains usage examples. On PyPI, the README.md
is rendered as part of the package page.
Custom Components Folder
The custom_components
folder is where the actual implementation is. Do not worry about this folder name: there is no need to change it. It is where pyproject.toml
specifies the source of the python package is. The published package contains the contents inside it, excluding this folder.
reflex_google_auth
is the top folder for importable code. The reflex_google_auth/__init__.py
imports everything from the reflex_google_auth/google_auth.py
. For the user of the package, the import looks like from reflex_google_auth import ABC, XYZ
.
reflex_google_auth/google_auth.py
is prefilled with code example and instructions from the wrapping react guide.
Demo App Folder
A demo app is generated inside google_auth_demo
folder with import statements and example usage of the component. This is a regular Reflex app. Go into this directory and start using any reflex commands for testing. The user is encouraged to deploy the demo app, so it can later be included as part of the Gallery.
Help Manual
The help manual is shown when adding the --help
option to the command.
reflex component init --help
Usage: reflex component init [OPTIONS]
Initialize a custom component.
Args: library_name: The name of the library. install: Whether to
install package from this local custom component in editable mode.
loglevel: The log level to use.
Raises: Exit: If the pyproject.toml already exists.
Options:
--library-name TEXT The name of your library. On PyPI, package
will be published as `reflex-{library-
name}`.
--install / --no-install Whether to install package from this local
custom component in editable mode.
[default: install]
--loglevel [debug|info|warning|error|critical]
The log level to use. [default:
LogLevel.INFO]
--help Show this message and exit.
reflex component publish
To publish to a package index, a user is required to already have an account with them. As of 0.4.3, Reflex only supports uploading to PyPI and TestPyPI. Those indices are separate PyPI and TestPyPI should have sufficient documentation on the account creation and how to generate API tokens. We also have a short guide covering this topic.
The publish process starts with a build if needed. If the distribution files for the version specified in pyproject.toml file already exist, the command prompts the user to confirm rebuilding the files nor not. After making sure the distribution files are ready, the command proceeds to upload them to the specified python package index.
reflex component publish --help
reflex component publish --help
Usage: reflex component publish [OPTIONS]
Publish a custom component. Must be run from the project root directory
where the pyproject.toml is.
Args: repository: The name of the Python package repository, such pypi,
testpypi. token: The token to use for authentication on python package
repository. If token is provided, no username/password should be provided at
the same time. username: The username to use for authentication on
python package repository. password: The password to use for
authentication on python package repository. loglevel: The log level to
use.
Raises: Exit: If arguments provided are not correct or the publish
fails.
Options:
-r, --repository TEXT The name of the repository. Defaults to
pypi. Only supports pypi and testpypi (Test
PyPI) for now.
-t, --token TEXT The API token to use for authentication on
python package repository. If token is
provided, no username/password should be
provided at the same time
-u, --username TEXT The username to use for authentication on
python package repository. Username and
password must both be provided.
-p, --password TEXT The password to use for authentication on
python package repository. Username and
password must both be provided.
--build / --no-build Whether to build the package before
publishing. If the package is already built,
set this to False. [default: build]
--loglevel [debug|info|warning|error|critical]
The log level to use. [default:
LogLevel.INFO]
--help Show this message and exit.
reflex component build
It is not required to run the build
command separately before publishing. The publish
command will build the package if it is not already built. The build
command is provided for the user's convenience.
The build
command generates the .tar.gz
and .whl
distribution files to be uploaded to the desired package index, for example, PyPI. This command must be run at the top level of the project where the pyproject.toml
file is. As a result of a successful build, there is a new dist
folder with the distribution files.
reflex component build --help
reflex component build --help
Usage: reflex component build [OPTIONS]
Build a custom component. Must be run from the project root directory where
the pyproject.toml is.
Args: loglevel: The log level to use.
Raises: Exit: If the build fails.
Options:
--loglevel [debug|info|warning|error|critical]
The log level to use. [default:
LogLevel.INFO]
--help Show this message and exit.