@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 are available.

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

Important

This package uses unreleased roblox-ts features, and requires roblox-ts@next to be installed. If you're encountering issues with @rbxts/react, please see the Troubleshooting section for more information.

📦 Setup

Installation

Get started by adding React and ReactRoblox to your project:

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

roblox-ts must also be installed with the next tag:

npm install -D roblox-ts@next
yarn add -D roblox-ts@next
pnpm add -D roblox-ts@next

Configuration

Set up your tsconfig.json to use the React JSX factory.

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

Usage with PNPM

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:

node-linker=hoisted

🚀 Examples

Mounting your app

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

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

root.render(<StrictMode>{createPortal(<App />, playerGui)}</StrictMode>);

Function Component

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

interface CounterProps {
	initialCount: number;
}

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

	return (
		<textbutton
			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),
			}}
		/>
	);
}

Class Component

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

interface CounterProps {
	initialCount: number;
}

interface CounterState {
	count: number;
}

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

	render() {
		return (
			<textbutton
				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 }),
				}}
			/>
		);
	}
}

Error Boundary

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<ErrorBoundaryProps, ErrorBoundaryState> {
	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

compilerOptions.jsxFactory must be `Roact.createElement`!

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

npm uninstall -g roblox-ts
npm install -D roblox-ts@next

`(X)` cannot be used as a JSX component. Its return type `Element` is not a valid JSX element.

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

You have react-ts installed in your dependencies. (npm uninstall @rbxts/roact)
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:

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.

Attempt to index nil with `useMemo` (or other hooks)

This error happens when React can't figure out how to retrieve the current instance of the component. This can be for a number of reasons:

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:

<App />; // 🟢 Good
App(); // 🔴 Bad

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

When multiple versions of React are present in your node_modules, any packages that depend on React might try to use the wrong one.

Make sure your rbxts_include.node_module.@rbxts folder in Roblox Studio doesn't contain a module named "React" (capital R). This module is a sign Rojo has not fully removed react-ts. If so, you should delete your node_modules folder and restart Rojo.

If a fresh install doesn't fix the issue, you might have a package installed that depends on react-ts. See the previous section for more information.

My issue isn't listed here!

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.

littensy/rbxts-react