Repository files navigation

A comprehensive, but not exhaustive, translation of upstream ReactJS 17.x into Roblox Lua.

• In a new project, you can consume this library by adding this line to your rotriever.toml
  • React = "github.com/roblox/roact-alignment@17.0.1"
• If you have legacy Roact code, use the roact-compat library instead
  • RoactCompat = "github.com/roblox/roact-alignment@17.0.1"
• Make sure you are using the latestrotriever 0.5 (or later) release
  • you can download the release binary, or add it to yourforeman.toml:rotrieve = { source = "roblox/rotriever", version = "=0.5.12" }
• For unit testing components and trees of components, you'll want to use theact() API exported from the react-roblox package.

Thereact repo is a monorepo with a number of member projects in itspackages folder, managed by a yarn workspace. Below is a description of each of those package, its status in our alignment repo, 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.

Projects not in the upstream React repo:

This repo is meant to supplant theRoact project, which is an open-source project that currently powers the majority of the Lua App and is used by the community as well. Our goal is to be as compatible as possible with Roact by the time we're ready to start adopting this alignment effort for use.

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:

• Stable Keys: Aligned Roact will allow table keys to be used as stable keys for child elements, equivalent to the behavior relied upon in Roact today
• Context: Legacy Roact's deprecated_context feature will not be present in aligned Roact; users will have to switch to thecreateContext feature, which is present in both current and aligned Roact and is semantically equivalent
• Class Component Refs: Aligned Roact will allow refs provided to class components (referred to in Roact documentation as "stateful components") to point to the actual component instance. This is not supported in current Roact, and there may be changes around theRoact.Ref prop key to support this with minimal disruption
• Bindings: We intend to keepcreateBinding andjoinBindings, a feature unique to Roact anddocumented here

Seethis document for details about any deviations and the design and refactoring efforts being proposed to address them.

You need to create a GitHub Access Token:

• GitHub.com -> Settings -> Developer Settings -> Personal Access Tokens
• Your token must have therepo and read:packages` scopes
• On that same page, you then need to click Enable SSO
• BE SURE TO COPY THE ACCESS TOKEN SOMEWHERE

npm login --registry=https://npm.pkg.github.com/ --scope=@roblox

For your password here, you will enter the GitHub Access Token from the instructions above.

npm install --global @roblox/rbx-aged-cli

Before you can use rbx-aged-cli, you need to be logged into the VPN so the Artifactory repository is accessible.

mkdir ~/binrbx-aged-cli download roblox-cli --dst ~/binexport PATH=$PATH:~/binroblox-cli --help

You should see roblox-cli output its help text.Before going ahead, you might want to addexport PATH=$PATH:~/bin to your bash profile file of choice, so you don't have to run it every time you open your terminal.

The next step is to clone the repo. When prompted for it, use the personal access token as your password.

git clone https://github.com/Roblox/roact-alignment.gitcd roact-alignmentroblox-cli analyze default.project.json

Foreman is an un-package manager that retrieves code directly from GitHub repositories. We'll use this to get a Lua package manager and other utilities. The Foreman packages are listed inforeman.toml.

You can install Foreman from a binary by downloading the appropriate version for your platform fromthe GitHub releases page.

Alternatively, since Foreman uses Rust, you can install Rust and use cargo to install it:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shexport PATH=$PATH:$HOME/.cargo/bincargo install foreman

Once Foreman is installed, provide an API token so that it can access private tools likerotriever and make sure that it's added to your path.

foreman github-auth <your GitHub API token that you used for npm login above>foreman installexport PATH=~/.foreman/bin/:$PATH # you might want to add this to your bash profile file too

Now you can run the tests, edit code, and contribute! Next we need to install our Lua package dependencies. We do this with a tool called Rotriever, which Foreman just installed for us. The package dependencies are listed inrotriever.toml.

rotrieve install

Now we can useroblox-cli to run our tests. We need to specify some additional arguments to make sure that the latest luau language features are enabled as well asdebug.loadmodule, which allows us to reset module state between tests.

roblox-cli run --load.model tests.project.json --run bin/spec.lua --fastFlags.overrides EnableLoadModule=true --fastFlags.allOnLuau

If rojo doesn't understand the nested project structure, exemplified by require statements not finding things, make sure you don't have a globally-installed rojo binary that is shadowing the one this project specifies locally. Youmust be using rojo 6.0 or above.

Once you remove the global rojo, you'll need to tickle bash's PATH hash cache so it doesn't keep looking in the place rojowas. (Yes, this is weird.) To update the bash path hash cache, run:hash -d rojo

To avoid this in the future, be sure that your foreman binary path isbefore the carbo binary path in yourPATH enviroment.

• Try to keep the directory structure, file name/location, and code symbol names aligned with React upstream. At the top of the mirrored files, put a comment in this format that includes the specific hash of the version of the file you're mirroring:

-- ROBLOX upstream https://github.com/facebook/react/blob/9abc2785cb070148d64fae81e523246b90b92016/packages/scheduler/src/Scheduler.js

• If you have a deviation from upstream code logic for Lua-specific reasons (1-based array indices, etc) put a comment above the deviated line:

-- 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 the es7-luau (fka 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

First, install the roblox-lrdb debugger extension for VSCode (followingthe installation instructions here).

Note: As specified in the lrdb installation instructions, youmust be connected to the VPN in order for the Internal Tool Provider to be able to download what it needs.

In order for breakpoints to work correctly, you'll need to disable the module reloading behavior that relies ondebug.loadmodule by providing the__NO_LOADMODULE__ global. To do so, create alaunch.json file with the following contents:

{"version": "0.2.0","configurations": [{"type": "roblox-lrdb","request": "launch","name": "Debug Unit Tests","args": ["--load.project","tests.project.json","--run","bin/spec.lua","--lua.globals","__NO_LOADMODULE__=true",],"cwd": "${workspaceFolder}","stopOnEntry": true,},]}

With module resetting disabled, most tests will only work if they're thefirst test run. UseitFOCUS orfit to focus a single test in your test suite when debugging this way. Once you've set that up, useRun -> Start Debugging or the equivalent keyboard shortcut to start debugging.

To run the upstream tests, you will need to install yarn and have it download the development dependencies:

npm install --global yarnyarn

First, set a breakpoint in the ReactJS code you want to step through, like at the beginning of a specific test.

Note: You probably don't want to set a breakpoint on thefit,it, oritFOCUS line itself, but the first line of the test after that.

Note: Usinghttps://github.com/Roblox/vscode-rbx-lrdb , you can set the same breakpoint in your equivalent Lua test. This allows you to single step in both the JS and Lua implementations, lock-step, to see where they deviate.

In VS Code, pressF1 key. Search for "auto attach" and select it.

Set the Auto Attach option to "Smart"

Open a JavaScript Debug Terminal, by first using View -> Terminal.

In the Terminal window, select "Create Debug JavaScript Terminal".

In Debug JavaScript Terminal window, paste in the command you use to run the specific React test file you are interested in.An example:yarn test --watch -v -r www-modern packages/react-reconciler/src/__tests__/ReactFiberHostContext-test.internal.jsNote that to match the React feature set that Roblox is aligning to, youneed to enable the variantand www-modern flags.

You should see your status bar turnorange (depending on your local theme), indicating that VS Code auto attach worked.

Shortly after you see the status bar change colors to indicate an active debugger attachment, you should hit your breakpoint.

Note that VS Code even tells you the value of the variables on the line. Pretty cool!