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.

When Rojo creates an instance from a file — say, a ModuleScript from a .luau file — it has no way to know about properties you might want to set on that instance beyond the content of the file itself. Meta files solve this problem. They are small JSON sidecar files that let you declare properties, attributes, a class name override, and other instance metadata alongside the source file. Meta files never create instances on their own. They only attach extra configuration to an instance that already exists due to a matching source file or directory.
Both .meta.json and .meta.jsonc variants are supported. The .jsonc variant allows JavaScript-style comments and trailing commas.

​
Two kinds of meta files

​
Adjacent meta files

An adjacent meta file sits next to a source file and shares its base name. It applies to the single instance that the source file produces. 
src/
  PlayerData.luau        ← creates a ModuleScript named "PlayerData"
  PlayerData.meta.json   ← applies extra metadata to that ModuleScript
Name the file <basename>.meta.json, where <basename> is the full name of the source file minus its extension. For PlayerData.luau, the meta file is PlayerData.meta.json.

​
Directory meta files

A directory meta file is named init.meta.json and lives inside a directory. It applies to the instance that the directory itself becomes — typically a Folder. 
src/
  Utilities/
    init.meta.json   ← applies metadata to the Folder named "Utilities"
    StringUtils.luau
    TableUtils.luau
init.meta.json is the only way to set a className override on a directory, changing it from Folder to another class.

​
Fields

Both adjacent and directory meta files share most fields. className is only valid in directory meta files.
​
className
string
(Directory meta files only.) Override the Roblox class of the directory instance. The directory must currently resolve to a Folder — you cannot change the class of a directory that contains an init script, for example.
{
  "className": "Configuration"
}
​
properties
object
A map of property names to values applied to the instance. Rojo resolves each value against the instance’s class using the reflection database. You can supply bare Lua-compatible values when the type is unambiguous, or use explicit type tags when you need precision.
{
  "properties": {
    "Disabled": true,
    "Value": { "String": "hello world" }
  }
}
​
attributes
object
A map of attribute names to values. Attributes are freeform key-value pairs stored on an instance and accessible from scripts via instance:GetAttribute().
{
  "attributes": {
    "Version": { "String": "2.1.0" },
    "IsEnabled": { "Bool": true }
  }
}
​
ignoreUnknownInstances
boolean
Controls whether Rojo leaves unknown child instances alone during live sync. When true, instances that are not tracked by Rojo are preserved rather than removed. Equivalent to $ignoreUnknownInstances in the project file.
​
id
string
A stable identifier for this instance used to resolve referent properties from other instances. Matches the $id field in the project file format.

​
Examples

​
Disable a script without editing source

PlayerData.meta.json
{
  "properties": {
    "Disabled": true
  }
}

​
Set attributes on a module

Config.meta.json
{
  "attributes": {
    "SchemaVersion": { "String": "1" },
    "IsProduction": { "Bool": false }
  }
}

​
Change a directory’s class

A folder that holds configuration objects can become a Configuration instance:
Settings/init.meta.json
{
  "className": "Configuration"
}
className in init.meta.json only works when the directory resolves to a Folder. If the directory contains an init.luau or similar init file, Rojo will error because the class is already determined by that file.

​
Preserve runtime children

If a directory has children added at runtime (by a server script, for example), tell Rojo to leave them alone:
ServerStorage/init.meta.json
{
  "ignoreUnknownInstances": true
}

​
Combine properties and attributes

ReplicatedStorage/GameData.meta.jsonc
{
  // Lock down the script while keeping source-control friendly
  "properties": {
    "Disabled": false
  },
  "attributes": {
    "Author": { "String": "MyTeam" },
    "BuildId": { "String": "abc123" },
  }
}

​
Property value format

Meta file properties use the same unresolved value format as $properties in project files. For most property types, you can supply a plain JSON value and Rojo infers the correct Roblox type from the class’s reflection data: 
{
  "properties": {
    "Anchored": true,
    "Name": "MyPart"
  }
}
When inference is ambiguous or when you need a specific type, supply an explicit type tag as a single-key object: 
{
  "properties": {
    "Value": { "Float32": 3.14 },
    "Color": { "Color3": [1, 0.5, 0] }
  }
}
Rojo merges meta file properties with any properties already set by the source file. Properties defined in the meta file take precedence.

Build docs developers (and LLMs) love

Get started for freeTalk to us