Third-Party Tools

For professional development studios, setting up third-party tools and investing in automation can dramatically improve developer productivity. Roblox's cloud-first approach has many advantages, but moving certain portions of the development workflow outside of the cloud can help larger teams track changes over time, review code, and use the languages and tools with which they're already familiar.

The Syncing Problem

At its core, using external tools with Roblox is a syncing problem:

• You want your Roblox scripts to exist as .luau files on disk so that you can use your own tools to work on them.
• You have to get your files back into your Roblox project after you've finished working on them.
• If someone else changed those same files in the meantime, you have to handle any conflicts.

For the whole solution to feel seamless and automatic, you need to a) listen for changes to files and b) incorporate these changes back into Studio. In other words, you need a server and a Studio plugin, which is how Rojo solves this problem.

Rather than Roblox's cloud-first approach, Rojo allows for a "file system-first" approach. It extracts all script files in your project into Luau files. Then it runs a server. The Rojo plugin connects to the server to synchronize those files with Studio.

Installing Rojo with Foreman

You can manually download and run a Rojo binary, but that approach runs the risk of different developers on your team using different Rojo versions. A better solution is to use a tool manager like Foreman, which uses a configuration file—a list of repositories and versions—to make the installation and upgrade process consistent across machines.

Because it manages your baseline development environment rather than the packages within your project, Foreman is more akin to nvm than npm, but the comparison isn't perfect. A simple foreman.toml file looks like this:

[tools]
rojo = { github = "rojo-rbx/rojo", version = "7.4.1" }
wally = { github = "UpliftGames/wally", version = "0.3.2" }

Then you install these tools with foreman install. In addition to a global foreman.toml file, Foreman supports per-project files, so you can easily use different versions of Rojo, Wally, or any other tool for different projects and keep your entire team on those same versions.

When a tool releases a new version, you then explicitly bump the version number in your .toml file, use Foreman to perform the upgrade, test the new version, and downgrade if it causes any problems. For commands and installation instructions, see Foreman.

Running Rojo

After you install Rojo with Foreman, what you've really installed is the Rojo server. The next step is to install the Rojo plugin for Roblox Studio:

rojo plugin install

Then generate the project structure for your new experience and build it:

rojo init my-new-experience
cd my-new-experience
rojo build -o my-new-experience.rbxl

Alternatively, you can port an existing experience. Either way, after you have a project, start the Rojo server:

rojo serve

In Roblox Studio, open the .rbxl file you just built, start the Rojo plugin, and connect to your now-running server, at which point you can start making changes in your preferred text editor and watch those changes automatically sync back to Studio.

Rojo projects have certain naming requirements for files, numerous configuration options, and some limitations, all of which are covered in the Rojo documentation.

Package Managers

Roblox has a robust set of included APIs, but if you want to make use of community software packages in a consistent, reproducible way, you need a package manager. Wally is a popular option. You can install it through Foreman, just like Rojo.

Within your experience's Rojo directory, run wally init. Then add your desired packages to wally.toml. The file might look like this:

[package]
name = "my-home-directory/my-new-experience"
version = "0.1.0"
registry = "https://github.com/UpliftGames/wally-index"
realm = "shared"

[dependencies]
react = "jsdotlua/react@17.1.0"
react-roblox = "jsdotlua/react-roblox@17.1.0"
cryo = "phalanxia/cryo@1.0.3"

Then run wally install. Wally creates a Packages directory and downloads the specified packages there. The final step is to add the Packages directory to Rojo so that its contents sync back to Roblox. Open default.project.json and add the path. For simplicity, this example adds the entire directory to ReplicatedStorage so that all packages are available to all scripts, but you might prefer to add specific packages to ServerScriptService or StarterPlayerScripts:

{
  "name": "my-new-experience",
  "tree": {
    "$className": "DataModel",

    "ReplicatedStorage": {
      "Shared": {
        "$path": "src/shared"
      },
      "Packages": {
        "$path": "Packages"
      }
    },

    ...

  }
}

Then you can require packages within your scripts just like any other ModuleScript:

local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local React = require(ReplicatedStorage.Packages.react)
local ReactRoblox = require(ReplicatedStorage.Packages["react-roblox"])

local handle = Instance.new("ScreenGui", Players.LocalPlayer.PlayerGui)
local root = ReactRoblox.createRoot(handle)

local helloFrame = React.createElement("TextLabel", {
	Text = "Hello World!",
	Size = UDim2.new(0, 200, 0, 200),
	Position = UDim2.new(0.5, 0, 0.5, 0),
	AnchorPoint = Vector2.new(0.5, 0.5),
	BackgroundColor3 = Color3.fromRGB(248, 217, 109),
	Font = Enum.Font.LuckiestGuy,
	TextSize = 24
})

root:render(helloFrame)

Like most other software projects, the goal is that contributors can clone a repository, install Foreman, run a few commands, and have the same development environment as the rest of the team.

Version Control

Having a set of plain text files on your computer unlocks a variety of capabilities, but the primary one is version control. You can store your scripts and configuration files in a Git or Mercurial repository; host remote repositories and review code changes in GitHub, GitLab, or Bitbucket; and use whichever text editor you like.

Visual Studio Code has the largest extension ecosystem, but Sublime Text, Notepad++, and Vim are all popular choices. Whichever editor you choose, matching the capabilities of the Studio script editor will require some extensions.

You might also consider adding:

• A linter like selene to catch common issues and enforce coding standards
• A code formatter like StyLua
• A language server like Luau Language Server for autocompletion, type checking, and more
• Open Cloud scripts (not synced to Studio) to update a published experience or restart servers

Assets

The tools on this page are most applicable to scripts; 3D artists already use external tools like Blender and Maya, store the source files in version control, and import their creations into Studio. After you have a Studio asset, we recommend making use of packages whenever possible.

The Roblox implementation of packages follows many of the same principles as the tools on this page: a centralized repository with version history that offers a seamless way to keep all copies of an asset in sync. For more information on how they can improve your workflow, see Packages.

Undoing Everything

Because third-party tools sync changes back to Roblox Studio rather than replacing it, no part of this workflow involves any lock-in. At any time, you can stop using one or all of these tools and go back to editing your experience exclusively in Studio. The lack of risk makes experimenting with third-party tools particularly appealing.