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.

rojo sourcemap reads your project and outputs a JSON tree that maps each Roblox instance in the project to the filesystem paths that produced it. Language tools like luau-lsp consume this file to provide accurate go-to-definition, type inference, and diagnostics for your scripts.

​
Synopsis

rojo sourcemap [PROJECT] [OPTIONS]

​
Arguments and flags

​
PROJECT
string
Path to the project file or to a directory containing a default.project.json. Defaults to the current directory.
​
--output, -o
string
Path to write the sourcemap JSON file. When omitted, the sourcemap is printed to stdout.
​
--include-non-scripts
boolean
default:"false"
Include non-script instances (e.g. Part, Folder) in the sourcemap. By default only Script, LocalScript, and ModuleScript instances are emitted, keeping the file compact for language tools that only care about scripts.
​
--watch
boolean
Automatically regenerate the sourcemap when any source file changes. The sourcemap is only re-written when a change affects the sourcemap output.
​
--absolute
boolean
Use absolute filesystem paths instead of paths relative to the project directory. Some tools require absolute paths.

​
Global flags

​
--verbose / -v
boolean
Increase log verbosity. Pass multiple times (e.g. -vv) for more detail.
​
--color
string
default:"auto"
Control color output. Accepted values are auto, always, and never.

​
Sourcemap format

The output is a JSON object tree mirroring the Roblox instance hierarchy. Each node has the following shape: 
{
  "name": "ReplicatedStorage",
  "className": "ReplicatedStorage",
  "filePaths": ["src/ReplicatedStorage"],
  "children": [
    {
      "name": "Shared",
      "className": "ModuleScript",
      "filePaths": ["src/ReplicatedStorage/Shared.lua"],
      "children": []
    }
  ]
}
filePaths lists every filesystem path that contributed to an instance. For a .lua file this is the script itself; for a directory-based instance it is the folder.

​
Using with luau-lsp

Generate a sourcemap file and point luau-lsp at it using its --sourcemap flag: 
# Generate once
rojo sourcemap --output sourcemap.json

# Or keep it up to date automatically
rojo sourcemap --output sourcemap.json --watch
Then launch the language server: 
luau-lsp analyze --sourcemap=sourcemap.json src/
Run rojo sourcemap --watch in a separate terminal alongside rojo serve. Both commands watch for file changes and stay in sync automatically.

​
Examples

Print the sourcemap to stdout: 
rojo sourcemap
Write to a file: 
rojo sourcemap --output sourcemap.json
Include all instances and use absolute paths (useful for some IDE integrations): 
rojo sourcemap --output sourcemap.json --include-non-scripts --absolute
Watch mode with a specific project file: 
rojo sourcemap path/to/my-game.project.json --output sourcemap.json --watch

Build docs developers (and LLMs) love

Get started for freeTalk to us