Sift Roblox module: Setup Guide for Luau and roblox-ts

The Sift Roblox module is an immutable data library designed for Luau and roblox-ts development. It is intended for Roblox projects that need safer table and dictionary transformations, especially when managing state, configuration objects, player data, or collections that should not be changed in place.

Sift is heavily based on the Llama library, but it uses native Luau types rather than relying on runtime type-checking. That design makes Sift useful in codebases where type information is handled during development and verified through the language or toolchain instead of through a separate runtime layer.

The library is not a Roblox game, experience, character, or progression system. It is a developer utility that becomes part of a project’s source tree or package dependencies.

A useful mental model is to regard every operation as producing a replacement value. Your code can keep the old table for comparison, undo logic, debugging, or reference checks while assigning the returned table to the next state.

This approach is especially valuable in larger Roblox projects. Direct mutation can make it difficult to identify which system changed a shared table. Immutable operations establish clearer boundaries: input data enters a function, a transformed result comes out, and the original value remains available for inspection.

Sift can be added to a Roblox project through several distribution paths. The best choice depends on whether your team uses Wally, roblox-ts, Rojo, or a manual Studio workflow.

For Wally users, the dependency declaration should remain part of the source-controlled project configuration. Avoid installing a package manually and forgetting to add it to the project manifest, because another developer may not receive the same dependency during setup.

For roblox-ts users, the package name is @rbxts/sift. The TypeScript API is intended to mirror the Luau API, which makes it easier to translate examples between the two environments.

The installation source does not change the library’s core purpose. Wally, npm, Creator Store, GitHub, and Rojo are delivery methods; they are not separate versions of Sift’s data model.

Sift is most useful when a project needs consistent transformations on dictionaries or other structured data. The central habit is simple: preserve the input, create a result, and use the result as the next state.

A basic merge operation can combine several dictionaries while excluding a key with Sift.None:

Dictionary.merge({ a: 1, c: 2 }, { b: 3, c: Sift.None })

The resulting dictionary is { a: 1, b: 3 }. The example demonstrates two important ideas: values from a later dictionary can participate in the result, and Sift.None can remove an existing key during the merge.

When using immutable utilities, name intermediate values clearly. A name such as nextConfig, updatedState, or mergedProfile communicates that the variable represents a replacement rather than a modified reference.

A practical state update flow looks like this:

1. Read the current table.
2. Pass it into a transformation.
3. Store the returned table.
4. Compare or publish the new value.
5. Keep the old value available when rollback or inspection matters.

This pattern works well for configuration layers. Start with defaults, merge environment-specific settings, then apply player or session overrides. If a value must be removed, use the library’s supported removal marker rather than relying on an uncontrolled mutation elsewhere in the codebase.

Sift does not perform runtime type-checking by itself. If a game needs to validate data received from clients, persistent storage, or external systems during execution, add an appropriate validation library separately. Immutability and validation solve different problems.

The project documentation identifies GreenTea and t as examples of libraries that can be installed manually for type-checking needs. Select a validation tool based on the project’s actual runtime requirements rather than assuming Sift covers input validation.

Sift supports two closely related development paths. Luau teams can use native Luau types and package workflows designed for Roblox development. roblox-ts teams can use the npm package and TypeScript-compatible API.

The API should remain conceptually consistent between Luau and TypeScript. That consistency is helpful for teams where systems are split between server code, client code, tooling, or generated scripts.

However, an identical API does not mean the surrounding toolchain is identical. Imports, build commands, generated output, package lockfiles, and synchronization settings still belong to the language-specific workflow.

Before adopting Sift in a new production codebase, review these maintenance questions:

• Does the project require active upstream fixes?
• Is the selected release compatible with the current Luau or roblox-ts toolchain?
• Will the team accept responsibility for bug fixes if a fork is required?
• Are package versions pinned in source control?
• Is the project prepared to replace Sift if an unsupported edge case appears?

The repository is distributed under the MIT license, and its public project page includes release, contributor, and package information. Use the Sift GitHub repository as the primary reference for package details, source review, and current maintenance status.

A small, isolated test is the safest starting point. Do not begin by replacing every table operation in a large project. First select one configuration object, state reducer, or profile transformation and compare the old and new behavior.

Start with predictable data. Configuration dictionaries are often easier to test than network payloads or persistent profiles because their shape is known before runtime.

Next, test key collisions. If two dictionaries contain the same key, define which source should win and verify that the result follows that rule. Then test removal behavior using the supported Sift.None marker where appropriate.

Finally, test the surrounding system. An immutable result can still be assigned incorrectly, sent to the wrong consumer, or stored under the wrong key. Sift makes transformations clearer, but the project must still define ownership and data flow.

Common mistakes include treating Sift as a validation framework, installing both Luau and TypeScript packages without a reason, or copying a dependency into Studio without documenting its source. These choices can create confusion even when the underlying operations work correctly.

For teams migrating from Llama, compare each existing operation carefully. Sift is heavily based on Llama but has its own type and documentation decisions. Confirm imports, return types, tests, and edge-case behavior instead of assuming that every surrounding project convention transfers automatically.

The best use of Sift is deliberate and focused: install it through a documented workflow, use immutable transformations where they clarify state changes, and keep validation and long-term dependency ownership separate. That approach lets Luau and roblox-ts teams benefit from consistent dictionary utilities while maintaining a realistic plan for project support.