Project file format reference

Every Rojo project is described by a .project.json or .project.jsonc file. This file tells Rojo how to map your filesystem to a Roblox instance tree, which ports to serve on, which place IDs to allow, and more. This page is the definitive reference for every field you can set in a project file.

.project.jsonc files support JavaScript-style single-line (//) and multi-line (/* */) comments, as well as trailing commas in objects and arrays. Use them freely for documentation inside your project files.

Top-level fields

These fields sit at the root of the JSON object.

name

string

The name of the top-level instance described by the project. When the file is named default.project.json, this defaults to the name of the containing folder. For all other project files you must set this explicitly.

tree

ProjectNode

required

The root instance and its descendants. See ProjectNode fields below.

servePort

number

default:"34872"

The port that rojo serve listens on when using this project. Overridden by the --port flag.

serveAddress

string

default:"127.0.0.1"

The address that rojo serve binds to. Override this to expose Rojo on a non-loopback interface.

servePlaceIds

number[]

A set of Roblox place IDs that are permitted to sync with this project. When set, Rojo rejects connections from any place not in this list. Use this to prevent accidentally syncing into the wrong place.

blockedPlaceIds

number[]

A set of Roblox place IDs that are explicitly blocked from syncing with this project. Connections from these places are rejected even if servePlaceIds is not set.

placeId

number

The place ID of the current place. Sent to the Roblox Studio plugin when it connects so the plugin knows which place it is working with.

gameId

number

The universe (game) ID of the current place. Sent to the Roblox Studio plugin on connection.

emitLegacyScripts

boolean

When true (the default), Rojo creates the classic Script and LocalScript instances for *.server.lua and *.client.lua files. Set to false to opt into the newer RunContext-based behavior where both produce a Script with the RunContext property set to Server or Client respectively.

globIgnorePaths

string[]

Glob patterns, relative to the project file’s folder, for files and directories that Rojo should ignore entirely. Useful for excluding test fixtures, generated files, or editor metadata.

"globIgnorePaths": [
  "**/*.spec.lua",
  "**/*.test.luau",
  ".git/**"
]

syncRules

SyncRule[]

Custom rules that map file glob patterns to snapshot middleware. Rules are checked before the built-in defaults, so you can override how any file type is handled. See Custom sync rules for full documentation.

syncbackRules

object

Configuration for the rojo syncback command, which writes changes from Roblox Studio back to the filesystem.

Show syncbackRules fields

ignoreTrees

string[]

A list of Roblox instance path strings (e.g. "game/Workspace/Terrain") whose entire subtree is excluded from syncback.

ignorePaths

string[]

Glob patterns matched against the filesystem path an instance would be written to. Matching instances are skipped during syncback.

ignoreProperties

object

A map from class name to a list of property names to skip for that class. Inheritance is respected — properties listed for a parent class are also ignored on child classes.

"ignoreProperties": {
  "BasePart": ["Anchored"],
  "Script": ["Source"]
}

syncCurrentCamera

boolean

default:"false"

Whether Workspace.CurrentCamera is included in syncback. Defaults to false because CurrentCamera is usually a transient runtime object.

syncUnscriptable

boolean

default:"true"

Whether properties that cannot be read or written by scripts are included in syncback.

ignoreReferents

boolean

default:"false"

When true, referent properties such as Model.PrimaryPart are not written during syncback.

createIgnoreDirPaths

boolean

default:"true"

When true, any ignorePaths glob that ends with /** is automatically extended to also match the directory itself, giving more intuitive ignore behavior.

ProjectNode fields

A ProjectNode describes one Roblox instance and optionally its children. You define the tree as a ProjectNode object, and every named key that does not start with $ becomes a named child ProjectNode.

$className

string

The Roblox class name for this instance (e.g. "Folder", "ModuleScript", "RemoteEvent"). Required when $path is not set. Cannot be set to a non-Folder class when $path is also set.

$path

string | object

A path, relative to the project file, that this instance should come from. Rojo determines the class and content from the file or directory at that path.Use a plain string for a required path — Rojo will error if the file is missing:

"$path": "src"

Use an object with an "optional" key for a path that may not exist:

"$path": { "optional": "src/generated" }

$properties

object

A map of property names to values that are applied to the resulting instance. Values use the same unresolved value format as the reflection database — Rojo infers the type when possible, or you can supply an explicit type tag.

"$properties": {
  "Disabled": true,
  "Value": { "String": "hello" }
}

$attributes

object

A map of attribute names to values set on the instance. Values follow the same format as $properties.

"$attributes": {
  "Version": { "String": "1.0.0" }
}

$ignoreUnknownInstances

boolean

Controls what Rojo does during live sync when it encounters instances inside this node that are not present in the project.

true — leave unknown instances alone.
false — destroy instances Rojo does not recognize.
Unset — defaults to true when $path is not set, false when $path is set.

Setting $ignoreUnknownInstances to true can cause stale instances to accumulate when source files are deleted while Rojo is not running.

$id

string

An identifier for this instance used to resolve referent properties. Other nodes can reference this ID in property values that expect a Ref.

(any other key)

ProjectNode

Any key that does not start with $ is treated as a named child instance. Its value must be another ProjectNode object. This is how you build an instance hierarchy directly in the project file without corresponding filesystem paths.

Complete examples

Place project
Library project
Plugin project

A typical game place that roots everything in src/ and applies a few top-level properties.

default.project.json

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$className": "ReplicatedStorage",
      "Shared": {
        "$path": "src/shared"
      }
    },
    "ServerScriptService": {
      "$className": "ServerScriptService",
      "$properties": {
        "LoadStringEnabled": false
      },
      "Server": {
        "$path": "src/server"
      }
    },
    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": {
        "$className": "StarterPlayerScripts",
        "Client": {
          "$path": "src/client"
        }
      }
    }
  },
  "servePort": 34872,
  "servePlaceIds": [1234567890],
  "emitLegacyScripts": false,
  "globIgnorePaths": ["**/*.spec.luau"]
}

A reusable model or package that is included in other projects via $path.

default.project.json

{
  "name": "MyLibrary",
  "tree": {
    "$path": "src"
  }
}

Another project can then include this library:

game.project.json

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$className": "ReplicatedStorage",
      "MyLibrary": {
        "$path": "modules/MyLibrary"
      }
    }
  }
}

A Roblox Studio plugin that maps to a single Plugin script hierarchy.

default.project.json

{
  // Plugin projects target a specific place for safety
  "name": "MyPlugin",
  "tree": {
    "$className": "Folder",
    "$path": "src",
    "$properties": {
      "Name": { "String": "MyPlugin" }
    }
  },
  // Only allow syncing from the plugin development place
  "servePlaceIds": [9876543210],
  "syncRules": [
    {
      "pattern": "*.plugin.luau",
      "use": "pluginScript",
      "suffix": ".plugin.luau"
    }
  ]
}

Get Started

Guides

Command Reference

Configuration

Reference

Project file format reference

Top-level fields

ProjectNode fields

Complete examples

Build docs developers (and LLMs) love

Get Started

Guides

Command Reference

Configuration

Reference

Documentation Index

​Top-level fields

​ProjectNode fields

​Complete examples

Build docs developers (and LLMs) love

Top-level fields

ProjectNode fields

Complete examples