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 sourcemap is a JSON file that describes your project’s instance tree and points each node back to the file (or files) it was created from. Luau language servers and other static analysis tools read this file to understand your project’s structure without needing to run Roblox.

​
What the sourcemap contains

Each node in the sourcemap describes one Roblox instance with four fields:
FieldTypeDescription
namestringThe instance’s name (equivalent to Instance.Name)
classNamestringThe Roblox class name (e.g. "ModuleScript", "Folder")
filePathsstring[]Paths to the source files that produced this instance
childrennode[]Child instances, recursively
filePaths and children are omitted from the output when empty.

​
Example output

sourcemap.json
{
  "name": "my-game",
  "className": "DataModel",
  "filePaths": ["default.project.json"],
  "children": [
    {
      "name": "ReplicatedStorage",
      "className": "ReplicatedStorage",
      "children": [
        {
          "name": "Utils",
          "className": "ModuleScript",
          "filePaths": ["src/ReplicatedStorage/Utils.luau"]
        }
      ]
    },
    {
      "name": "ServerScriptService",
      "className": "ServerScriptService",
      "children": [
        {
          "name": "GameManager",
          "className": "Script",
          "filePaths": ["src/Server/GameManager.server.luau"]
        }
      ]
    }
  ]
}

​
Generating a sourcemap

rojo sourcemap [project] [options]
With no options, the sourcemap is written to stdout. Pass --output to write to a file. 
# Write to stdout
rojo sourcemap

# Write to a file
rojo sourcemap --output sourcemap.json

# Use a specific project file
rojo sourcemap my-project.project.json --output sourcemap.json

​
Flags

​
--output
string
Path to write the sourcemap JSON file. If omitted, the output is printed to stdout.
​
--include-non-scripts
boolean
By default, the sourcemap only includes script instances (Script, LocalScript, ModuleScript) and their ancestors. Pass this flag to include all instances in the tree regardless of class.
​
--watch
boolean
Regenerate the sourcemap whenever any input file changes. The command runs until interrupted. Useful when integrated into an editor workflow or a tool that reloads the sourcemap on disk changes.
rojo sourcemap --output sourcemap.json --watch
​
--absolute
boolean
Emit absolute filesystem paths in filePaths instead of paths relative to the project directory. Some tools require absolute paths to locate files correctly.
rojo sourcemap --output sourcemap.json --absolute

​
Use with luau-lsp

luau-lsp is the most common consumer of Rojo sourcemaps. To set it up:
1

Generate the sourcemap

Run sourcemap generation in watch mode so the language server always has an up-to-date view:
rojo sourcemap --output sourcemap.json --watch
2

Point luau-lsp at the sourcemap

Configure your editor extension to use the generated file. For VS Code with the luau-lsp extension, set:
settings.json
{
  "luau-lsp.sourcemap.rojoProjectFile": "default.project.json"
}
The extension can run rojo sourcemap automatically when this setting is provided.
Add sourcemap.json to your .gitignore. It is a generated file that changes frequently and does not need to be tracked in version control. Rojo’s rojo init command adds it to .gitignore by default.

​
Filtering behavior

When --include-non-scripts is not set, Rojo builds the full instance tree internally but prunes any node that is neither a script class nor an ancestor of one. This keeps the sourcemap small and focused on the instances that language tools actually care about. A node is retained if:
  • Its className is Script, LocalScript, or ModuleScript, or
  • It has at least one child that is retained.

Build docs developers (and LLMs) love

Get started for freeTalk to us