What Rojo Does and Why It Matters
Rojo is a project management tool that maps files on your computer's filesystem to instances inside Roblox Studio. A Lua file at src/server/CombatService.server.lua becomes a Script named CombatService inside ServerScriptService. A folder at src/shared/Modules becomes a Folder in ReplicatedStorage. Rojo watches your filesystem for changes and live-syncs them into a running Studio session. This means you can write code in VS Code with extensions like Luau LSP (full type checking, autocomplete, and diagnostics), use Git for version control, and work with teammates using standard branching and pull request workflows. For any project larger than a weekend jam, Rojo is the industry standard.
Installation and Initial Setup
Install Rojo in three steps. First, install the Rojo CLI tool. The easiest method is through Aftman (a Roblox toolchain manager): create an aftman.toml file in your project root with [tools] and rojo = "rojo-rbx/rojo@7.4.4" (or the latest version), then run aftman install. Alternatively, install with Foreman or download the binary directly from the Rojo GitHub releases page. Second, install the Rojo plugin for Roblox Studio from the Rojo GitHub or the Roblox Plugin Marketplace — this is the Studio-side component that receives synced changes. Third, initialize your project by running rojo init in your project directory. This creates a default.project.json file and a src folder structure.
- Install Aftman: cargo install aftman (requires Rust) or download from GitHub
- Add rojo to aftman.toml: rojo = "rojo-rbx/rojo@7.4.4"
- Run aftman install to download the Rojo binary
- Install the Rojo Studio plugin (connects Studio to the Rojo server)
- Run rojo init myproject to scaffold a new project
Understanding default.project.json
The project file (default.project.json) is the heart of Rojo. It defines how your filesystem maps to Roblox's instance tree. The top-level "tree" object represents game (DataModel). Inside it, you map Roblox services to filesystem directories. A typical setup maps ServerScriptService to src/server, ReplicatedStorage to src/shared, StarterPlayer/StarterPlayerScripts to src/client, and ReplicatedFirst to src/client/ReplicatedFirst. Each mapping uses the "$path" key to point to a directory. File naming conventions determine instance types: .server.lua becomes a Script, .client.lua becomes a LocalScript, .lua becomes a ModuleScript, and directories become Folders. You can also map individual files, JSON files to configuration instances, and .rbxm/.rbxmx files for models and other non-script assets.
- myScript.server.lua — becomes a Script (server-side)
- myScript.client.lua — becomes a LocalScript (client-side)
- myModule.lua — becomes a ModuleScript
- Folders on the filesystem become Folder instances in Studio
- .model.json files define complex instances with properties
Syncing and the Development Workflow
Start the Rojo development server by running rojo serve in your project directory. Then open Roblox Studio and click "Connect" in the Rojo plugin toolbar — Studio connects to the local Rojo server and begins live-syncing. Now, every time you save a .lua file in VS Code, the change appears in Studio within milliseconds. The workflow becomes: write code in VS Code, save, switch to Studio to test, switch back to VS Code to iterate. For non-script assets (models, terrain, UI), you can work directly in Studio and then use rojo build to generate an .rbxl file, or use two-way sync (experimental in Rojo 7+) to pull Studio changes back to your filesystem. When you are ready to build a final place file, run rojo build -o game.rbxlx to generate the complete place from your source files.
Git Integration and Team Collaboration
Rojo's biggest advantage is enabling Git workflows. Since your code lives as files on disk, you can use Git for version control, branching, merging, and pull requests — exactly like professional software development. Create a .gitignore that excludes .rbxl/.rbxlx build files, the roblox directory if you have one, and any local configuration. Each team member clones the repo, runs rojo serve, and connects their Studio instance. Branching lets developers work on features independently without conflicts. Pull requests enable code review before changes merge into the main branch. For teams, this is transformational — no more overwriting each other's work inside a single Studio place file.
- Initialize Git in your Rojo project root with git init
- Add .gitignore: *.rbxl, *.rbxlx, /build, .DS_Store
- Use feature branches for new systems (git checkout -b feature/combat-system)
- Open pull requests for code review before merging to main
- Use VS Code's Git integration or GitHub Desktop for visual diffing
VS Code Extensions for Roblox Development
VS Code with the right extensions provides a far superior coding experience to Studio's built-in editor. Install the Luau Language Server extension for full type checking, autocomplete, and inline diagnostics. Install Roblox LSP or use the Luau types definitions file for autocomplete on Roblox API types (workspace, game, Instance methods). The Rojo VS Code extension adds a status bar indicator showing sync state. Selene (a Luau linter) catches common bugs and style issues. StyLua auto-formats your code on save. Together, these tools catch errors before you even test in Studio, dramatically reducing iteration time. This professional tooling is the primary reason experienced Roblox developers use Rojo.