@rbxts/solid

@rbxts/solid

A powerful reactive library for Roblox TypeScript projects, inspired by SolidJS. This library provides an efficient way to create reactive everything in your Roblox games using JSX syntax and reactive primitives. All that is instance is renderable, so you can use it to create reactive UI, physical elements, and every other instances in your game. Some utilities like ScrollView are provided, the library is likely to grow with time, adding many more utilities.

Warning: This doc is not complete yet, look at the code directly if you want more infos, or dm me on discord: @rsman

Table of Contents

• Installation
• Quick Start
• Core Concepts
  • JSX Elements
  • Components
  • Control Flow
  • Props Utilities
• API Reference
• Performance Tips

Installation

Currently available through GitHub (to get the latest commited build, ensure using commit hash for stability):

npm install @rbxts/solid@github:RsMan-Dev/rbxts-solid

Via NPM:

npm install @rbxts/solid

in tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      {
        "transform": "./node_modules/@rbxts/solid/out/transformer",
      },
    ],

    "jsx": "react",
    "jsxFactory": "SOLID.createElement",
    "jsxFragmentFactory": "SOLID.createFragment"
  }
}

Quick Start

import { createSignal, createRoot } from "@rbxts/signals";
import SOLID, { InstanceContext, getInstance } from "@rbxts/solid";

function Counter() {
  const count = createSignal(0);
  
  return (
    <instFrame Size={new UDim2(0, 200, 0, 100)}>
      <instTextLabel
        Text={count()}
        Size={new UDim2(1, 0, 1, 0)}
        TextSize={24}
      />
      <instTextButton
        Text="Increment"
        Size={new UDim2(0, 100, 0, 30)}
        Position={new UDim2(0.5, -50, 0.5, -15)}
        on:MouseButton1Click={() => {
          count.set(v => v+1)
          print(getInstance(), "clicked")
        }}
      />
    </instFrame>
  );
}

// Create the UI
createRoot(() => {
  InstanceContext.populate(game.GetService("Players").LocalPlayer.WaitForChild("PlayerGui"));
  return <Counter />;
});

Core Concepts

JSX Elements

The library supports creating Roblox instances using JSX syntax. All Roblox instance types are available with the inst prefix.

Instance props have special prefixes for different functionalities:

• Events: Prefixed with on:, once:, parallel:

  • on:MouseButton1Click: Regular event
  • once:MouseButton1Click: One-time event
  • parallel:MouseButton1Click: Parallel event
  • Current instance can be accessed using getInstance()

• Functions: Prefixed with fn:

  • fn:AddTag: Can take array of arguments or function
  • Function receives instance's method as first argument

• Getters/Setters: Prefixed with get: and set:

  • get:Name, set:Name
  • Can provide array of arguments or function

<instFrame Size={new UDim2(0, 200, 0, 100)}>
  <instTextLabel 
    Text="Hello World"
    on:MouseButton1Click={() => print(getInstance(), "clicked")}
    once:MouseButton1Click={() => print(getInstance(), "clicked once")}
    parallel:MouseButton1Click={() => print(getInstance(), "clicked parallel")}
    fn:AddTag={["test"]}
    fn:AddTag={(addTag) => (addTag("test"), addTag("test2"))}
    set:Attribute={["test", 1]}
    set:Attribute={(setAttribute) => (setAttribute("test", 2), setAttribute("test2", 3))}
    get:Attribute={getter => print(getter("test"))}
    get:Attributes={getter => print(getter())}
  />
</instFrame>

Components

Components are functions that return JSX elements. They can be reactive and update when their dependencies change.

JSX props in function components are proxied using @rbxts/jsnatives to maintain reactivity.

⚠️ Warning: Never destructure props in function components, as they are proxied to maintain reactivity.

function Greeting(props: { name: string }) {
  return <instTextLabel Text={`Hello, ${props.name}!`} />;
}

Control Flow

The library provides several control flow components:

Show

Conditionally render content:

<Show When={isVisible()} Fallback={<instTextLabel Text="Loading..." />}>
  <instTextLabel Text="Content is visible!" />
</Show>

FastFor

Efficiently render lists of items. Uses value references to index roots created, so duplicate references are not possible.

<FastFor Each={items()} Fallback={<instTextLabel Text="No items" />}>
  {(item, index) => (
    <instTextLabel Text={`Item ${index()}: ${item}`} />
  )}
</FastFor>

Props Utilities

The library provides several utilities for working with props. All utilities are proxied and require avoiding destructuring to maintain reactivity.

⚠️ Warning: Looping into props needs to use Object.* methods, as they are proxied and will fail if using pairs or ipairs.

• mergeProps: Merge multiple props objects
  • Special case: functions act as getters
  • To return a function, use attr: () => functionValue
• pickProps: Create a new object with only specified props
• omitProps: Create a new object without specified props
• splitProps: Split props into two objects based on keys

Performance Tips

• Use FastFor instead of regular For when you don't need duplicate items (For not implemented yet)
• Use Show for conditional rendering
• Keep components small and focused
• Don't hesitate to memoize expensive computations, or computations that run often, as it's cached to avoid unnecessary effect triggers
• Use untrack when you don't need reactivity
• Use batch in events to avoid unnecessary effect triggers

[ DOC WIP ... ]

look at the code directly if you want more infos

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Acknowledgments

This library was inspired by:

• SolidJS
• @rbxts/signals
• @rbxts/jsnatives