@rbxts/react

TypeScript type definitions for React Lua.


npm package →

TypeScript type definitions for React Lua and roblox-ts, sourced from the official React types. Currently, only @rbxts/react and
@rbxts/react-roblox may be installed.

If we're missing any deviations from React Lua, please open an issue or pull request to let us know!

If you're encountering issues with @rbxts/react, please see the Troubleshooting section for more information.

📦 Setup

$3

Get started by installing the alpha versions of @rbxts/react and @rbxts/react-roblox:

``sh
npm install @rbxts/react@alpha @rbxts/react-roblox@alpha
yarn add @rbxts/react@alpha @rbxts/react-roblox@alpha
pnpm add @rbxts/react@alpha @rbxts/react-roblox@alpha # 🔴 See below
`

Then, add the following to your Rojo project file, under the node_modules folder:

`json
"node_modules": {
"$className": "Folder",
"@rbxts": {
"$path": "node_modules/@rbxts"
},
"@rbxts-js": {
"$path": "node_modules/@rbxts-js"
}
}
`

$3

Set up your tsconfig.json JSX options to use React's createElement and Fragment:

`json
"compilerOptions": {
"jsxFactory": "React.createElement",
"jsxFragmentFactory": "React.Fragment"
}
`

$3

If you're using PNPM as your package manager, you'll need to create a .npmrc file in the root of your project with the following content:

`ini
public-hoist-pattern[]=@rbxts
`

$3

To connect to DevTools from a new application, you need to import the backend portion of the stack. Add ReactDevtools and ReactGlobals as dependencies in your package manager:

`sh
npm install @rbxts/react-globals@alpha @rbxts/react-devtools-core@alpha
yarn add @rbxts/react-globals@alpha @rbxts/react-devtools-core@alpha
pnpm add @rbxts/react-globals@alpha @rbxts/react-devtools-core@alpha # 🔴 See above
`

Similar to when setting the __DEV__ or __PROFILE__ flags, DevTools must be initialized before React is imported.

`ts
import { backend } from "@rbxts/react-devtools-core";
import ReactGlobals from "@rbxts/react-globals";

// The DEV flag enables some DevTools features you otherwise wouldn't have
ReactGlobals.__DEV__ = true;
// The PROFILE flag allows you to run the DevTools profiler
ReactGlobals.__PROFILE__ = true;

backend.connectToDevtools();
`

Now, if you launch DevTools and then run your code, you should see your React component tree!

🚀 Examples

$3

`tsx
import React, { StrictMode } from "@rbxts/react";
import { createPortal, createRoot } from "@rbxts/react-roblox";

const root = createRoot(new Instance("Folder"));

root.render({createPortal(, playerGui)});
`

$3

`tsx
import React, { useState } from "@rbxts/react";

interface CounterProps {
initialCount: number;
}

export function Counter({ initialCount }: CounterProps) {
const [count, setCount] = useState(initialCount);

return (
Text={Count: ${count}}
AnchorPoint={new Vector2(0.5, 0.5)}
Size={new UDim2(0, 100, 0, 50)}
Position={new UDim2(0.5, 0, 0.5, 0)}
Event={{
Activated: () => setCount(count + 1),
}}
/>
);
}
`

$3

`tsx
import React, { Component, ReactComponent } from "@rbxts/react";

interface CounterProps {
initialCount: number;
}

interface CounterState {
count: number;
}

@ReactComponent
export class Counter extends Component {
state: CounterState = {
count: this.props.initialCount,
};

render() {
return (
Text={Count: ${this.state.count}}
AnchorPoint={new Vector2(0.5, 0.5)}
Size={new UDim2(0, 100, 0, 50)}
Position={new UDim2(0.5, 0, 0.5, 0)}
Event={{
Activated: () => this.setState({ count: this.state.count + 1 }),
}}
/>
);
}
}
`

$3

`tsx
import React, { Component, ErrorInfo, ReactComponent } from "@rbxts/react";

interface ErrorBoundaryProps {
fallback: (error: unknown) => React.Element;
}

interface ErrorBoundaryState {
hasError: boolean;
message?: unknown;
}

@ReactComponent
export class ErrorBoundary extends Component {
state: ErrorBoundaryState = {
hasError: false,
};

componentDidCatch(message: unknown, info: ErrorInfo) {
warn(message, info.componentStack);

this.setState({
hasError: true,
message: ${message} ${info.componentStack},
});
}

render() {
if (this.state.hasError) {
return this.props.fallback(this.state.message);
} else {
return this.props.children;
}
}
}
`

🔎 Troubleshooting

$3

If you encounter this error during compilation, it means that you're using an older version of roblox-ts. Make sure to install the latest version of roblox-ts and remove any global installations:

`sh
npm uninstall -g roblox-ts
npm install -D roblox-ts@latest
`

$3

This error typically occurs when tsconfig.json has not been configured correctly. Make sure that your fragment factory is set to React.Fragment, and that your JSX factory is set to React.createElement:

`json
"compilerOptions": {
"jsxFactory": "React.createElement",
"jsxFragmentFactory": "React.Fragment"
}
`

$3

This error can occur when a conflicting installation of react-ts is present in your project. This can be for one of two reasons:

1. You have react-ts installed in your dependencies. (npm uninstall @rbxts/roact)
2. You have an outdated package installed that depends on react-ts.

The most common cause is an outdated package. To view the packages that depend on @rbxts/react-ts (which will be under the alias @rbxts/roact), run the following command:

`sh
npm ls @rbxts/roact
`

If you find any packages that depend on @rbxts/react-ts, you should update them to the latest version, or open an issue on their repository to request an update.

$3

This error happens when a hook was called in an invalid environment. There are two common reasons for this error:

1. You're using a hook outside of a component, or using function components incorrectly.

Hooks must be used inside the body of a function component. A common mistake is to call hooks conditionally, or inside a callback function. Make sure you're calling hooks at the top level of your function component.

Do not call a function component directly. To render a function component, wrap it in a JSX tag:

`tsx
; // 🟢 Good
App(); // 🔴 Bad
`

2. There's more than one version of React in your project.

When multiple versions of React are present in your node_modules, your packages might import hooks from the wrong version of React. Update your packages to the latest version that supports @rbxts/react`, or remove the conflicting packages.

If you have no conflicting dependencies, or a fresh install doesn't remove the outdated package, see the previous section for more information.

$3

If you're encountering an issue that isn't listed here, please post your issue in the roblox-ts Discord server.

📚 Resources

- React Documentation - Learn about React's core concepts and API
- React Lua Documentation - A comprehensive guide for the differences between Roact and React
- JS.Lua Repository - The source code for React Lua

📝 License

This project is licensed under the MIT license.