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.

A Rojo project file is a JSON document that tells Rojo how to map files and directories on your filesystem to Roblox instances. Every Rojo workflow starts with one.

​
File format

Project files are named with the .project.json or .project.jsonc extension. Rojo automatically locates a file named default.project.json or default.project.jsonc when you point a command at a directory.
.project.jsonc files support JavaScript-style comments (//, /* */) and trailing commas. Use them when you want to annotate your configuration.
A minimal project file looks like this:
default.project.json
{
  "name": "my-game",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$path": "src/ReplicatedStorage"
    }
  }
}
The two required fields are name (or a resolvable filename) and tree. Everything else is optional.

​
Instance tree (tree)

The tree field describes a hierarchy of Roblox instances. Every key that does not start with $ is treated as a child instance whose name is that key. Keys starting with $ are Rojo directives.

​
Instance node fields

​
$className
string
The Roblox class name for this instance (e.g. "ModuleScript", "Folder", "Part"). Required when $path is not set. Cannot be set if $path points to a file that produces a non-Folder instance.
​
$path
string | object
A path to a file or directory, relative to the project file. Rojo maps the file to an instance using its sync rules.Use a plain string for a required path that must exist:
"$path": "src/ServerScriptService"
Use an object with an optional key for a path that may or may not exist:
"$path": { "optional": "src/ServerScriptService" }
​
$properties
object
A map of Roblox property names to values to assign to the instance. Property values follow the unresolved value format, which supports type-tagged objects for non-string types.
"$properties": {
  "Anchored": true,
  "Size": {
    "Vector3": [4, 1, 4]
  }
}
​
$attributes
object
A map of attribute names to values to set on the instance.
"$attributes": {
  "MaxHealth": 100,
  "IsEnemy": false
}
​
$ignoreUnknownInstances
boolean
Controls how Rojo handles instances that exist in Roblox Studio but are not present in your project tree during live sync.
  • true — leave unknown instances alone.
  • false — destroy unknown instances.
  • Omitted — defaults to true when $path is not set, and false when $path is set.
​
$id
string
A stable identifier for this instance, used to wire up referent properties (such as ObjectValue.Value) that point to another instance in the tree.

​
Children

Any key that does not begin with $ declares a child instance. The key becomes the instance’s Name in Roblox. 
{
  "tree": {
    "$className": "DataModel",
    "ServerScriptService": {
      "$className": "ServerScriptService",
      "GameManager": {
        "$path": "src/Server/GameManager.server.luau"
      }
    }
  }
}
Keys starting with $ are reserved by Rojo. If your project uses a child instance whose name starts with $, rename it to avoid forward-compatibility issues.

​
Top-level project fields

​
name
string
The name of the top-level instance the project describes. When the project file is named default.project.json, Rojo automatically uses the containing folder’s name if this field is omitted.
​
tree
object
required
The root instance node. See Instance tree above.
​
servePort
number
default:"34872"
The default port for rojo serve when using this project. Overrides the global default of 34872. Can be further overridden by the --port flag at the command line.
​
serveAddress
string
default:"127.0.0.1"
The IP address rojo serve binds to. Useful when you need to expose the server on a non-loopback interface. Overridden by --address on the command line.
​
servePlaceIds
number[]
A list of Roblox place IDs that this project is compatible with. When set, the Roblox Studio plugin rejects connections from any place not in this list. Use this to prevent accidentally syncing into the wrong place.
​
blockedPlaceIds
number[]
A list of Roblox place IDs that this project is explicitly incompatible with. The Studio plugin rejects connections from any place in this list.
​
placeId
number
Sets the place ID that Roblox Studio reports when connecting to the Rojo server.
​
gameId
number
Sets the game (universe) ID that Roblox Studio reports when connecting to the Rojo server.
​
emitLegacyScripts
boolean
default:"true"
When true (the default), *.server.lua files produce a Script and *.client.lua files produce a LocalScript — the classic Roblox class types. When false, Rojo uses the newer RunContext-based behavior where both produce a Script with RunContext set to Server or Client respectively.
​
globIgnorePaths
string[]
A list of glob patterns, relative to the project file’s directory, that match files Rojo should ignore entirely. Useful for excluding test files, generated output, or OS metadata files.
"globIgnorePaths": [
  "**/*.spec.lua",
  "**/.DS_Store"
]
​
syncbackRules
object
Configuration for rojo syncback. See Converting Roblox files to a Rojo project for full details.
​
syncRules
object[]
A list of custom file-to-instance mapping rules that extend or override the built-in sync rules. Each entry requires a pattern glob and a use middleware name. See How Rojo maps files to Roblox instances for the available middleware names.
"syncRules": [
  {
    "pattern": "*.data.json",
    "use": "json"
  }
]

​
Example project files

​
Place project

A full-game project that mirrors Roblox’s default DataModel service layout.
default.project.json
{
  "name": "my-game",
  "tree": {
    "$className": "DataModel",

    "ReplicatedStorage": {
      "$className": "ReplicatedStorage",
      "$path": "src/ReplicatedStorage"
    },

    "ServerScriptService": {
      "$className": "ServerScriptService",
      "$path": "src/Server"
    },

    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": {
        "$className": "StarterPlayerScripts",
        "$path": "src/Client"
      }
    }
  },
  "servePort": 34872,
  "servePlaceIds": [12345678]
}

​
Model project

A project that describes a single model to be imported into a place.
ToolModel.project.json
{
  "name": "ToolModel",
  "tree": {
    "$className": "Tool",
    "$path": "src",
    "$properties": {
      "RequiresHandle": true
    }
  }
}

​
Plugin project

A project for a Roblox Studio plugin.
default.project.jsonc
{
  // Plugin projects typically target the Plugins service
  "name": "MyPlugin",
  "tree": {
    "$className": "Script",
    "$path": "src/Plugin.plugin.luau"
  },
  "globIgnorePaths": [
    "**/*.spec.luau" // exclude unit tests
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us