Azul

Azul is a two-way synchronization tool between Roblox Studio and your local filesystem with full Luau-LSP support, which allows code completion & type checking.

Azul allows you to use professional-grade tools like Visual Studio Code in Roblox development.

Yes, the name is a pun on Rojo (Spanish for "red"). Azul means "blue"!

Quick Start — Why Azul — Documentation

Philosophy

Azul treats Studio as the source of truth. The local filesystem mirrors what's in Studio, not the other way around.

Azul avoids the complexity and ambiguity that can come with tools like Rojo: for example, deciding a new Script's parent class, properties, or attributes. Rather than trying to encode Studio state in extra files (e.g. *.meta.json), Azul lets Studio be the source of truth. This, in my opinion, leads to a much simpler and more intuitive workflow.

Azul also allows pushing local files into Studio using the azul build command, which creates or overwrites instances in Studio based on your local files.

Features

• • 🔄 Bi-directional sync: Changes in Studio update files, and file edits update Studio
• • 🏗️ Build command: azul build one-time pushes your local files into Studio (creates or overwrites, never deletes)
• • 📦 Push command: azul push selectively pushes local files. Useful when importing external libraries or using package managers (i.e Wally)
• • 🏛️ Fully hermetic builds: Use azul pack to fully serialize Instance properties, allowing for 1:1 reproductible builds when building or pushing.
• • 🔴 Rojo compatibility mode: Supports importing from Rojo projects with the --rojo flag.
• • 🌳 DataModel mirroring: Instance hierarchy 1:1 mapped to folder structure
• • 🎯 No manual config / required structure: Works out of the box with new and existing Roblox Studio projects, regardless of structure.
• • 🗺️ Automatic sourcemap generation: Generates a Rojo-compatible sourcemap.json so tools like Luau-lsp work out of the box.

Why Azul?

Because Azul is as simple as it gets: Run the azul command in your project folder, connect the companion plugin in Studio & start coding.

Compatible with projects both old and new, no more extra worrying about how to “Rojo-ify” your project. Your code is literally 1:1 mapped to what’s in Studio.

Rojo already exists, why make another tool?

While Rojo is a powerful tool, I don't believe it's always the best fit for every developer or project. Otherwise trivial tasks in Studio, like inserting a Script inside Tool or Model, suddenly become non-trivial challenges. Rojo just lacks the flexibility of Studio.

Azul is my approach to solve these issues. I built Azul for workflows similar to mine: Studio-first developers who'd rather manage their projects in the dedicated environment instead of fighting with meta files.

Why not use the upcoming Script Sync feature?

Azul offers several advantages over the upcoming Script Sync feature:

• Azul mirrors everything: Script Sync can only sync specified folders and scripts, not entire projects. Azul directly mirrors the entire DataModel, meaning you don't have to worry about manually syncing specific parts of your project.

• Building from filesystem: Script Sync only syncs changes made in Studio to the filesystem. Azul allows you to push changes from your local files into Studio using the azul build command.

• Pushing from filesystem: Sync any code you have stored locally directly to your desired destination using azul push. Useful when importing external libraries (e.g. GitHub) or when using Package Managers (e.g. Wally, pesde)

• Rojo compatibility: Azul can import existing Rojo projects using the --rojo & --rojo-project=<ProjectFile> flags, making Azul compatible with many existing open source projects.

  • Generates a Rojo-compatible sourcemap.json: This allows any tooling that require Rojo-style sourcemaps (like luau-lsp, the language server) to work seamlessly.

• You can use it today!: Azul requires no commitment to a specific project structure. If you want to try out Script Sync (or any other tool) in the future, Azul won't get in your way.

---

Quick Start

Auto-Install (Recommended)

1. Install Node.js from nodejs.org.
2. Run the following command in your terminal:

   npm install azul-sync -g

3. Install the Azul Companion Plugin to Roblox Studio.
   • Guide: Azul Plugin: Install Instructions
4. Create a new Folder to house your Azul project and open it in your IDE.
5. With the terminal in your project folder, run:

   azul
   

6. In Roblox Studio, click on the "Connect" button in the Azul plugin.
7. Start coding!
8. (Optional) For the best experience, check out the Recommended Tools & Extensions.

Manual Install

1. Clone this repository using Git:

   git clone https://github.com/Ransomwave/azul.git

2. Install Node.js from nodejs.org or by using your system's package manager:

   # Windows (using winget)
   winget install OpenJS.NodeJS.LTS
   # macOS (using Homebrew)
   brew install node
   # Linux (using apt)
   sudo apt install nodejs npm

3. Install dependencies by running

   npm install

4. Build the project

   npm run build

5. Install the project globally

   npm install -g .

6. Install the Azul Companion Plugin to Roblox Studio.
   • Guide: Azul Plugin: Install Instructions
7. Create a new Folder to house your Azul project and open it in your IDE.
8. With the terminal in your project folder, run:

   azul

9. In Roblox Studio, click on the "Connect" button in the Azul plugin.

Recommended Tools & Extensions

VSCode with Luau-LSP

To get the best experience, use Visual Studio Code with the Luau Language Server extension.

To get IntelliSense working, open your User Settings (JSON) from the command palette (Ctrl+Shift+P or Cmd+Shift+P) and make sure to set up luau-lsp like this:

  "luau-lsp.plugin.enabled": true,
  "luau-lsp.sourcemap.enabled": true,
  "luau-lsp.sourcemap.autogenerate": false,
  "luau-lsp.sourcemap.sourcemapFile": "sourcemap.json",
  "luau-lsp.sourcemap.includeNonScripts": true,

This is my recommended setup for Azul projects. That said, Azul is compatible with any IDE or text editor that can edit .luau files. Luau-LSP is also available for other editors like Neovim.

VSCode with Verde

Verde is a VSCode extension that mimics the Roblox Studio Explorer and Properties windows. It works great alongside Azul to provide a seamless development experience.

Contributing

Contributions are welcome! Please open issues or pull requests on GitHub. I want to make Azul the best it can be for myself and anybody who wants to use it.