Better compatibility with ReactJS Packages

Start by reading the current component_from_npm interface and the re-engineered JavaScript API issue #1001, then map the proposed build, install, uninstall, download-bun, and upgrade-bun commands. Done would require a decided design covering package generation, Bun handling, Python interfaces, and ReactJS compatibility, but this issue names no files or tests.

TLDR

We want users to be able to use ReactJS components from NPM in a similar level of complexity to a pip install. This will require developing ReactPy Package Manager. This tool will pull packages down using Bun, statically build/analyze them, then auto-generate a Python file containing the usable interface.

The alternative option for power users is using the re-engineered the JavaScript API to leverage any standard JavaScript tooling.

Current Situation

It's not reasonable manually translate every ReactJS component to a Python, and the current component_from_npm interface is not able to give Python type hints for functions (technological limitation). This ultimately necessitates automating the generation of ReactPy JavaScript component APIs.

Design Concept

Create a ReactPy build step can automatically generate Python wrappers of JavaScript functionality. Ideally, this machine generated Python would also include type hints that are automatically inferred from the JavaScript code. We will need some method of determining variable names from the JavaScript source. This likely will involve using a JavaScript AST parser (or TypeScript AST parser).

A generated Python file for a react-bootstrap Card could potentially look something like this:

_Card = component_from_file(file=Path(__file__).parent / "dist" / "react-bootstrap.js", import_names=["Card"])

def Card(bsPrefix=None, className=None, bg=None, text=None, border=None, body=None, children=None, as='div', body=False):
    return _Card(bsPrefix, className, bg, text, border, body, children, as, body)

How to handle JavaScript

Automatic type hints are only half the battle for ReactJS package compatibility.

A bigger question is, how do we make sure things written for ReactJS are compatible with ReactPy? As a goal, we should investigate how to best fully interface with the top 100 React libraries on NPM.

This might necessitate rethinking our JavaScript API layer in order to access JavaScript data/attributes/modules/hooks/etc. We should consider rewriting our client using an proxy object system. The end goal is to have compatibility for all the potential pieces within a ReactJS module, such as:

• Hooks
• Events
• Components
• Variables
• Props
• Child Elements
• ref values within props

Command Line Interface

The CLI should be accessible within the reactpy <command> namespace.

We should probably follow the same precedence as Playwright/Selenium. If the user tries to use a command, we should first check if bun has been installed. If it hasn't, we will tell the user to run reactpy download-bun.

build command

1. User generated packages will need a package.json using the standard format
2. Users must declare their own dependencies within a package.json
3. reactpy build <DIR> will build a single package.
4. We will output the Python code (and JavaScript source) into reactpy.reactjs.<pkg_name>, unless a different output file is specified via --outdir.
5. Automatically create a .gitignore containing * within the output dir, as this built code should be assumed as ephemeral.

install command

1. Should have a --outdir option
2. Should have a --exports=... option to limit what gets built
3. Installed modules are accessible within Python via reactpy.reactjs.<pkg_name>

uninstall command

1. uninstall command should have an --all option

download-bun command

1. Downloads bun to the current environment, similar to how selenium or playwright can download Chromium via command line.
2. Ignores subsequent requests to download bun, if it already exists.

upgrade-bun command

1. Runs bun upgrade to put the user on the latest version of bun