React Lua is a comprehensive translation of upstream ReactJS from JavaScript into Lua, and is highly-turned for both performance and correctness.
When possible, upstream flowtype and definitely-typed types have been translated into Luau type annotations. The major and minor version of React Lua is aligned to the upstream used for the translation, except where noted. Due to the close nature of the two implementations, most article, video, or blog posts that gives React JS advice can be applied to React Lua -- modulo language differences, of course.
This repository is a fork of roblox/react-lua
with the intention of being the Roblox and global Lua community go-to for React in Lua. Roblox's repository is a read-only mirror of their internal project, and as such cannot be contributed to by the community. They have not published React to any public package registry and have not made alterations for easier use by the community.
Roblox has removed commit author history in their public mirror, which removes credit for the original project authors. Below is a non-exhaustive list of those who originally worked on the project, in no particular order:
The react repo is a monorepo with a number of member projects in its packages
folder, managed by a Yarn workspace. Below is a description of each of those package, its status in React Lua, and how it likely fits into our future plans.
π Considered part of react's core functionality or testing capabilities; some or all of this package is necessary to build and validate an MVP.
Project | Description | Status | Plan | Notes |
---|---|---|---|---|
create-subscription |
Used for subscribing to external data | β Not ported | β Not yet assessed | |
dom-event-testing-library |
Dom event simulation for tests | β Not ported | β Not yet assessed | |
eslint-plugin-react-hooks |
Linting plugin for hooks rules | β Not ported | β Not yet assessed | Depends on future linting tools |
jest-mock-scheduler |
Reexports scheduler testing utilities | β Not ported | β Not yet assessed | |
πjest-react |
Jest matchers and utilities | βοΈ Ported | Used for testing React component implementations. | |
πreact |
Base react interface | βοΈ Ported | Defines basic shape of internals like Components and Elements. We added Roblox-specifics like Bindings, but otherwise comply with upstream ReactJS. | |
react-art |
For drawing vector graphics | β Not ported | β Unlikely to be ported | |
react-cache |
Basic cache for use with experimental React features | βοΈ Ported | β | API is flagged as unstable, is stable in React 18, used in advanced Suspense cases |
react-client |
Experimental package for consuming React streaming models | β Not ported | β Not yet assessed | API considered unstable. Might be worth investigating if it stabilizes |
react-debug-tools |
Experimental debugger package | βοΈ Ported | Used by DevTools and (the Roblox internal) Roblox Studio Inspector | |
react-devtools |
Top-level app for react devtools | β Not ported | β Likely to be ported | Devtools needs to be addressed as a whole to see where/how it translates |
react-devtools-core |
Standalone devtools impl | β Not ported | β Likely to be ported | Devtools needs to be addressed as a whole to see where/how it translates |
react-devtools-extensions |
Devtools browser extension | β Not ported | β Unlikely to be ported | |
react-devtools-inline |
Impl for embedding in browser-based IDEs | β Not ported | β Likely to be ported | Devtools needs to be addressed as a whole to see where/how it translates |
react-devtools-scheduling-profiler |
Experimental concurrent mode profiler | β Not ported | β Not yet assessed | |
react-devtools-shared |
Private shared utilities for devtools | βοΈ Ported | Used by Roblox Studio Inspector | |
react-devtools-shell |
Harness for testing other devtools packages | β Not ported | β Not yet assessed | Devtools needs to be addressed as a whole to see where/how it translates |
react-dom |
Entrypoint for DOM and server renderers | β Not ported | β Unlikely to be ported | Heavily inspired the top-level interface of the React-Roblox Renderer |
react-fetch |
For use with experimental React features | β Not ported | β Not yet assessed | API considered unstable |
react-interactions |
For use with experimental React features | β Not ported | β Not yet assessed | |
πreact-is |
Runtime type checks for React elements | βοΈ Ported | ||
react-native-renderer |
Renderer interface for react-native | β Not ported | β Not yet assessed | This package has no readme, so it's hard to understand its scope |
πreact-noop-renderer |
Renderer used for debugging Fiber | βοΈ Ported | Used heavily for internal framework testing | |
πreact-reconciler |
Reconciler implementation used with various renderers | βοΈ Ported | Bulk of React's complicated logic lives here | |
react-refresh |
Wiring for Fast Refresh | β Not ported | β Not yet assessed, depend on applicability | Officially supported successor to "hot reloading" |
react-server |
Experimental package for creating React streaming server renderers | β Not ported | β Not yet assessed | |
react-test-renderer |
Test renderer helpful utilities and snapshot support | βοΈ Ported | Used for testing much of React's internals, can be used by external developers | |
react-transport-dom-delay |
Internal package, likely for testing | β Not ported | β Unlikely to be ported | No readme in package |
react-transport-dom-webpack |
Related to above | β Not ported | β Unlikely to be ported | Appears to be webpack-specific |
πscheduler |
Cooperative scheduling implementation | βοΈ Ported | Includes Tracing and Profiling features, which are enabled through ReactFeatureFlags | |
πshared |
Loose collection of shared utilities and definitions | βοΈ Ported | We pushed many things into this leaf node module to fix circular dependencies. Working with upstream to clean this up. | |
use-subscription |
Hook for managing subscriptions in concurrent mode | β Not ported | β Not yet assessed | Not sure if/how this will apply to Roblox and Lua |
Projects not in the upstream React repo: | Project | Description | Notes |
---|---|---|---|
πreact-shallow-renderer |
Shallow renderer used in tests for some older React features. Re-exported alongside react-test-renderer , source of truth here. |
βοΈ Ported - with tests that are helping us exercise functionality in the react package |
|
react-roblox |
Based on react-dom renderer, shares much of its code and public interface. | Also exports act() functionality, which is required for testing components that are asynchronously rendered (the default). |
|
roact-compat |
A comaptibility layer that emulates some deprecated behaviors of legacy Roact | Meant to ease initial adoption of Roact Lua, using React APIs directly is encouraged and necessary for newer functonality (eg Hooks) |
This repo is meant to supplant the Roact
project, which is an open-source project that currently powers many Roblox projects. Our goal is to be as compatible as possible with Roact.
With that in mind, however, there will still be a small number of behavioral deviations that make the transition from existing Roact smoother, or account for nuances of the Roblox ecosystem:
_context
feature will not be present in React Lua; users will have to switch to the createContext
feature, which is present in both Roact and React Lua and is semantically equivalentRoact.Ref
prop key to support this with minimal disruptioncreateBindings
and joinBindings
, a feature unique to Roact and documented hereSee this document for details about any deviations and the design and refactoring efforts being proposed to address them.
-- ROBLOX upstream https://github.com/facebook/react/blob/9abc2785cb070148d64fae81e523246b90b92016/packages/scheduler/src/Scheduler.js
-- ROBLOX deviation: use explicit nil check instead of falsey
For deviations due to Lua language differences (no spread operator) that don't involve changing the logic, don't put a deviation comment. Just use the appropriate equivalent from LuauPolyfill and other utility libraries.
For files that are new and Roblox-specific, use the file name: Timeout.roblox.lua
and for Roblox-specific tests, use the file name format: Timeout.roblox.spec.lua