Skip to main content

Syncing with Rojo

Introduction​

The role of roblox-ts is to turn TypeScript (.ts) files into Luau files (.lua). That alone isn't very useful! You need to move the files into Roblox Studio to be able to use them for a game, plugin, model, etc.

To do this, you can use Rojo!

Rojo takes files from your local filesystem and will either:

  • turn them into a single Roblox file (.rbxm, .rbxl, .rbxmx, or .rbxlx) via rojo build
  • sync them into an open Roblox Studio session via rojo serve

Rojo uses a default.project.json file to describe how files should be organized within a Roblox file.

Heads up!

Your default.project.json file should have all "$path" fields relative to your outDir (which is the "out" folder by default).

The workflow should look like this:

.ts files in src

⬇️

roblox-ts via rbxtsc

⬇️

.lua files in out

⬇️

Rojo via rojo build or rojo serve

⬇️

Roblox Studio 🎉


roblox-ts will use your project.json file to understand how TypeScript (.ts) files eventually end up inside of Roblox Studio. This is primarily used for compiling import statements.

To use a different project.json file instead of default.project.json for compiling, you can use the --rojo flag:

rbxtsc --rojo other.project.json

Customization​

Like any other Rojo project, you can organize a roblox-ts project however you'd like with a few restrictions:

  • The include folder and node_modules folder must be in a place that is visible to both the client and server
  • All "$path" fields should be relative to your outDir (which is the "out" folder by default)

By default, the default.project.json file should look something like this (truncated):

{
"name": "roblox-ts-game",
"tree": {
"$className": "DataModel",
"ServerScriptService": {
"$className": "ServerScriptService",
"TS": {
"$path": "out/server" // server folder goes in ServerScriptService.TS
}
},
"ReplicatedStorage": {
"$className": "ReplicatedStorage",
// this _must_ stay the same (except for the name)
"rbxts_include": {
"$path": "include",
"node_modules": {
"$path": "node_modules/@rbxts"
}
},
"TS": {
"$path": "out/shared" // shared folder goes in ReplicatedStorage.TS
}
},
"StarterPlayer": {
"$className": "StarterPlayer",
"StarterPlayerScripts": {
"$className": "StarterPlayerScripts",
"TS": {
"$path": "out/client" // client folder goes in StarterPlayer.StarterPlayerScripts.TS
}
}
}
}
}

You can find the full version here.

Example​

Suppose you wanted to add scripts to StarterPlayer.StarterCharacterScripts.

To do this, we'll need to add a folder to src (so that when we compile it will have a matching folder in out). We'll call this src/character.

Then, we need to update our default.project.json:

"StarterPlayer": {
"$className": "StarterPlayer",
"StarterPlayerScripts": {
"$className": "StarterPlayerScripts",
"TS": {
"$path": "out/client"
}
},
"StarterCharacterScripts": {
"$className": "StarterCharacterScripts",
"TS": {
"$path": "out/character"
}
}
}