Custom-components
/
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 --helpUsage: 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.
Below is an example of running the init command.
reflex component initreflex 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
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.
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.
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 .
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 .
The help manual is shown when adding the --help option to the command.
reflex component init --helpUsage: 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.
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.
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 --helpreflex 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.
Did you find this useful?
