@rust-js/react 0.0.1

package/Cargo.toml

@@ -0,0 +1,52 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2024"
+name = "rust-js-react"
+version = "0.0.1"
+build = "build.rs"
+include = [
+    "src",
+    "build.rs",
+    "versions.json",
+    "README.md",
+]
+autolib = false
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+description = "React for rust-js: components written in Rust, compiled to the JSX you'd write"
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/rust-js-lang/rust-js"
+
+[package.metadata.rust-js.npm]
+react = ">=18.0.0"
+react-dom = ">=18.0.0"
+
+[lib]
+name = "react"
+path = "src/lib.rs"
+
+[dependencies.js]
+version = "~0.0.1"
+package = "rust-js-builtins"
+
+[dependencies.webapi]
+version = "~0.0.1"
+package = "rust-js-webapi"
+
+[lints.rust.unexpected_cfgs]
+level = "warn"
+priority = 0
+check-cfg = ["cfg(rust_js)"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tu Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# react: React for rust-js
+
+Write React components in Rust. rust-js compiles them to the components
+you'd write in JSX by hand ([ADR 0041](../docs/decisions/0041-react.md)).
+The crate binds all of React's and React DOM's API, as of React 19.3, for
+whichever React from 18.0 on your project has installed
+([ADR 0043](../docs/decisions/0043-react-versions.md)):
+
+```rust
+#![allow(non_snake_case)]
+
+use react::{Element, jsx, use_state};
+
+pub fn App() -> Element {
+    let (count, set_count) = use_state(0);
+    jsx! {
+        <button className="counter" onClick={move |_| set_count.update(|count| count + 1)}>
+            {"Count is "}{count}
+        </button>
+    }
+}
+```
+
+```jsx
+// App.jsx
+import { useState } from "react";
+
+export function App() {
+  const [count, setCount] = useState(0);
+  return <button className="counter" onClick={() => setCount((count) => count + 1 | 0)}>Count is {count}</button>;
+}
+```
+
+It's all bindings: rustc checks the types, and nothing of this crate ends up
+in the JS.
+
+`jsx!` is built into rust-js, in both the native and browser compilers, and
+imported as any macro is, `use react::jsx;`.
+Tags and attributes look like JSX; expressions inside braces are Rust.
+Text is quoted (`{"Hello"}`), and handlers are Rust closures. See the
+[syntax guide](../docs/jsx.md) for components, spreads and current limits.
+
+**Use JSX to construct elements.** Element builders and `component(...)` are
+compiler plumbing; direct use produces an error. Hooks, styles and React DOM
+operations remain ordinary Rust APIs.
+
+Attributes use React's spelling: `className`, `onPointerDownCapture`,
+`aria-label`, and so on. Handlers receive typed events such as
+`event::Mouse` and `event::Keyboard`. A `ref` accepts a ref object or a
+callback; `action` and `formAction` accept URLs, or on React 19+, functions
+and action dispatches. No alternate prop names are needed.
+
+A component is a function with a capitalized name that returns `Element`.
+Its props, if it has any, are a struct, and a field named `children` holds
+its children. A tuple of children is several of them, a `Vec` is a list
+whose items need keys, and `None` renders nothing.
+
+With `js::camel_case!();` in the crate root, props and custom hooks get
+React's names: a field `on_press` is the prop `onPress`, and `pub fn use_clicks()`
+is the hook `useClicks`, which React's rules and React Compiler find by that
+name ([ADR 0046](../docs/decisions/0046-camel-case-crates.md)).
+
+**Hooks** are React's, in snake case, with a `_with` variant for an optional
+argument: `use_state`, `use_reducer`, `use_context`, `use_ref`,
+`use_imperative_handle`, `use_effect`, `use_layout_effect`,
+`use_insertion_effect`, `use_effect_event`, `use_memo`, `use_callback`,
+`use_transition`, `use_deferred_value`, `use_id`, `use_sync_external_store`,
+`use_debug_value`, `use_action_state`, `use_optimistic`, and React 19's
+`use` as `use_`, since `use` is a Rust keyword.
+
+- What a hook gives back is `&'static T`, read-only as React's state is, and
+  `Copy`, so every handler can `move` it in.
+- An effect's dependencies are a tuple: `(count, name)` is `[count, name]`,
+  and `()` is `[]`.
+- An effect's closure returns nothing, or the closure that cleans it up.
+
+**Context and `memo`** are made once, as JS makes them at a module's top
+level. In Rust that's a `thread_local!`, which rust-js compiles to just that:
+
+```rust
+thread_local! {
+    static THEME: Context<&'static str> = create_context("light");
+    static FAST_CARD: Memo<CardProps> = memo(Card);
+}
+
+pub fn Toolbar() -> Element {
+    let theme = use_context(&THEME);
+    jsx! { <FAST_CARD title={theme} /> }
+}
+
+pub fn App() -> Element {
+    jsx! { <THEME value="dark"><Toolbar /></THEME> }
+}
+```
+
+```jsx
+const THEME = createContext("light");
+const FAST_CARD = memo(Card);
+
+export function Toolbar() {
+  const theme = useContext(THEME);
+  return <FAST_CARD title={theme} />;
+}
+
+export function App() {
+  return <THEME value="dark">
+    <Toolbar />
+  </THEME>;
+}
+```
+
+`memo_with(Card, |a, b| ..)` is `memo(Card, arePropsEqual)`.
+Use `<THEME.Provider value="dark">...</THEME.Provider>` on React 18;
+React 19 also supports `<THEME value="dark">...</THEME>`.
+
+Put a context in a module of its own, `mod theme;`, as React advises. Saving
+a file runs its module again, and a context made there is a new one, so
+React remounts everything under its provider and its state is lost. That's
+the same in hand-written React. rust-js leaves an unchanged `theme.js` alone
+when `App.rs` changes, so Fast Refresh keeps the state. `memo` needs nothing
+like this.
+
+**React DOM** is `react::dom`: `create_portal`, `flush_sync`, the resource
+hints (`preload`, `preinit`, ..), `use_form_status`, `request_form_reset`
+and `browser`. Under it:
+- `dom::client`: `create_root` and `hydrate_root`, with `RootOptions`;
+- `dom::server`: `render_to_string`, `render_to_readable_stream`,
+  `render_to_pipeable_stream`, `resume`, ..;
+- `dom::prerender`: `react-dom/static`'s `prerender` and the rest.
+
+Options are objects built by methods:
+`create_root_with(el, RootOptions::new().identifier_prefix("app-"))` is
+`createRoot(el, { identifierPrefix: "app-" })`.
+
+Left out on purpose:
+- class components and error boundaries, since rust-js has no classes;
+- React's other legacy APIs (`createElement`, `cloneElement`, `Children`,
+  `createRef`, `isValidElement`);
+- anything `unstable_`.
+
+## React versions
+
+What a React release after 18.0 added is gated by it, `#[cfg(react = "19.2")]`,
+and the crate is built for the React your project has. On React 18.2,
+`use_effect_event` doesn't compile, and the error says why:
+
+```text
+error[E0432]: unresolved import `react::use_effect_event`
+note: found an item that was configured out
+496 | #[cfg(react = "19.2")]
+    |       -------------- the item is gated behind the `19.2` feature
+```
+
+[`versions.json`](versions.json) records which release first has each export,
+event and attribute, read from the releases themselves by
+[`generate.ts`](generate.ts). The tests check every binding against it, for
+every release. When React has a new release, `bun run generate:react` reads
+it. Then the tests say which of its exports still need binding, and with
+which gate.
+
+## Build it
+
+```bash
+react/build.sh -o target/libreact.rmeta                         # the latest React; also writes libwebapi.rmeta and libjs.rmeta
+react/build.sh -o target/react-18/libreact.rmeta --react 18.2.0 # for React 18.2
+rust-js App.rs -- --extern react=target/libreact.rmeta -L target
+```
+
+`bun run build` does the first step. In a Vite project,
+[@rust-js/vite-plugin](../vite-plugin/index.js) does both, on every save, for
+the React the project has installed. See
+[examples/vite-react](../examples/vite-react/README.md).

package/build.rs

@@ -0,0 +1,59 @@
+//! The react crate's `cfg`s for one React release (ADR 0043), as `cfg.js`
+//! gives `react/build.sh` them: `react="18.1"` and so on for every minor
+//! release up to `RUST_JS_REACT`, so an item gated `#[cfg(react = "19.2")]`
+//! exists only from React 19.2. The releases are `versions.json`'s.
+
+use std::path::Path;
+
+fn main() {
+    let versions = Path::new(env!("CARGO_MANIFEST_DIR")).join("versions.json");
+    println!("cargo::rerun-if-changed={}", versions.display());
+    println!("cargo::rerun-if-env-changed=RUST_JS_REACT");
+    let text = std::fs::read_to_string(&versions).expect("react/versions.json");
+    let releases = releases(&text);
+    let latest = *releases.last().expect("react/versions.json lists no release");
+    let wanted = match std::env::var("RUST_JS_REACT") {
+        Ok(version) => minor(&version).unwrap_or_else(|| panic!("RUST_JS_REACT: not a React version: {version}")),
+        Err(_) => minor(latest).expect("a release is a version"),
+    };
+    let first = minor(releases[0]).expect("a release is a version");
+    assert!(
+        first <= wanted,
+        "React {}.{} is older than {}, the first release the react crate supports",
+        wanted.0,
+        wanted.1,
+        releases[0]
+    );
+    if wanted > minor(latest).expect("a release is a version") {
+        println!(
+            "cargo::warning=React {}.{} is newer than {latest}, the latest release the react crate knows: it has {latest}'s API",
+            wanted.0, wanted.1
+        );
+    }
+    let values: Vec<String> = releases.iter().map(|release| format!("\"{release}\"")).collect();
+    println!("cargo::rustc-check-cfg=cfg(react,values({}))", values.join(","));
+    for release in releases
+        .iter()
+        .filter(|release| minor(release).is_some_and(|r| r <= wanted))
+    {
+        println!("cargo::rustc-cfg=react=\"{release}\"");
+    }
+}
+
+/// `versions.json`'s releases, `"18.0"` to the latest, as react/generate.ts
+/// writes them: the keys of its `"releases"` object, one to a line.
+fn releases(text: &str) -> Vec<&str> {
+    let start = text.find("\"releases\": {").expect("versions.json has releases");
+    let end = start + text[start..].find('}').expect("releases end");
+    text[start..end]
+        .lines()
+        .skip(1)
+        .filter_map(|line| line.trim().strip_prefix('"')?.split_once('"').map(|(key, _)| key))
+        .collect()
+}
+
+/// A version's major and minor release: `18.2.0` is `(18, 2)`.
+fn minor(version: &str) -> Option<(u32, u32)> {
+    let mut parts = version.split('.');
+    Some((parts.next()?.parse().ok()?, parts.next()?.parse().ok()?))
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rust-js/react",
+  "version": "0.0.1",
+  "description": "React for rust-js: components written in Rust, compiled to the JSX you'd write",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rust-js-lang/rust-js.git",
+    "directory": "react"
+  },
+  "keywords": [
+    "rust-js",
+    "rust"
+  ],
+  "rust-js": {
+    "crate": "rust-js-react"
+  },
+  "peerDependencies": {
+    "@rust-js/builtins": "~0.0.1",
+    "@rust-js/webapi": "~0.0.1",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "files": [
+    "Cargo.toml",
+    "LICENSE",
+    "README.md",
+    "build.rs",
+    "src",
+    "versions.json"
+  ]
+}