Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rojo-rbx/rojo/llms.txt

Use this file to discover all available pages before exploring further.

Live sync is the core workflow Rojo is built around. You run rojo serve on your machine, install the Roblox Studio plugin, and any file change you make is reflected in Studio within moments — without restarting or rebuilding.

​
Architecture overview

rojo serve starts an HTTP server that the Studio plugin connects to. The server maintains a snapshot of your project’s instance tree and a message queue of pending changes. The plugin opens a WebSocket connection to the server, receives patches describing what changed, and applies them to the live DataModel.
Rojo switched from long-polling to WebSockets in version 7.7.0-rc.1. The WebSocket connection provides lower latency and a more reliable sync experience.
The serve session works like this:
1

Session starts

rojo serve reads your project file and builds an initial snapshot of the entire instance tree by walking the filesystem. All files are processed through sync rules to produce instance snapshots.
2

Studio connects

The Roblox Studio plugin connects to the server over WebSocket. The server sends the current snapshot so Studio can synchronize its DataModel.
3

Files change

The server watches for filesystem events (file added, modified, or deleted). When a change is detected, it updates the instance tree snapshot and enqueues a patch describing the difference.
4

Studio receives patches

The plugin receives patches from the server over the WebSocket connection and applies them to the live DataModel. Only the changed instances are updated.

​
Default port and address

By default, rojo serve listens on 127.0.0.1:34872. You can override either value:
  • In the project file — set servePort and/or serveAddress to change the defaults for that project.
  • At the command line — pass --port <number> or --address <ip> to override for a single session.
# Use a custom port for this session
rojo serve --port 34873

# Bind on all interfaces (useful for remote development)
rojo serve --address 0.0.0.0
The command-line flags take precedence over project file settings, which take precedence over the built-in defaults.

​
Place ID safety guards

To prevent accidentally syncing into the wrong Roblox place, you can configure allow and block lists in your project file.
​
servePlaceIds
number[]
A list of place IDs the project is compatible with. The Studio plugin refuses to sync if the current place ID is not in this list.
​
blockedPlaceIds
number[]
A list of place IDs the project is explicitly incompatible with. The Studio plugin refuses to sync if the current place ID appears in this list.
default.project.json
{
  "name": "my-game",
  "tree": { "$className": "DataModel" },
  "servePlaceIds": [12345678],
  "blockedPlaceIds": [99999999]
}
Set servePlaceIds on every shared project to protect against syncing production data into a development place or vice versa.

​
Script class behavior and emitLegacyScripts

By default, Rojo uses the legacy script class types:
  • *.server.lua / *.server.luau → Script
  • *.client.lua / *.client.luau → LocalScript
If you prefer the newer RunContext-based API, set emitLegacyScripts: false in your project file: 
{
  "emitLegacyScripts": false
}
When set to false, server scripts produce a Script with RunContext = Server and client scripts produce a Script with RunContext = Client, using the newer Roblox API.

​
Excluding files with globIgnorePaths

You can prevent Rojo from processing specific files or directories entirely using glob patterns. This is useful for excluding test files, build artifacts, and editor metadata. 
{
  "globIgnorePaths": [
    "**/*.spec.lua",
    "**/*.spec.luau",
    "**/.DS_Store",
    "node_modules/**"
  ]
}
Patterns are matched relative to the project file’s directory. Files matching any pattern are invisible to Rojo — they are not turned into instances and changes to them do not trigger syncs.
Add .git/** to globIgnorePaths if you notice Rojo trying to process files inside your Git directory.

​
What triggers a sync

The serve session watches for three kinds of filesystem events:
EventEffect
File createdNew instance added to the tree
File modifiedExisting instance updated (source changed, properties re-read)
File deletedInstance removed from the tree
Directory events (creating or deleting a folder) are also handled. If a folder gains or loses an init.lua file, the folder’s instance type changes accordingly.

Build docs developers (and LLMs) love

Get started for freeTalk to us