ember
Documentation menuembr 0.13.0

Guides

Using Ember with Azul

Last updated November 3, 2026

Azul is a two-way sync tool for Roblox, an alternative to Rojo. In Azul, Studio is the source of truth. Azul mirrors the place to disk, by default in a sync/ folder. From embr 0.13.0, Ember puts your packages into Studio through Azul.

Rojo reads the packages folders from the project file, so Studio gets them when rojo serve runs. Azul does not read the disk into Studio by itself. Ember therefore pushes each packages folder with azul push, after each install that changes it, and when you run embr studio push.

Set up a project#

You need Node.js 20.19.0 or newer, because Azul is an npm package.

  1. Pin Azul as a project tool:

    embr tool add npm:azul-sync@2.4.0
    

    embr tool add azul does the same, but only when the registry's shorthand list has the name azul.

  2. Tell Ember that the project uses Azul. Add this to ember.toml:

    [studio]
    sync = "azul"
    

    This step is optional when the project already has a sync/ folder from Azul. See How Ember finds an Azul project.

  3. Add packages and install them. embr install also installs Azul:

    embr add chief/core
    embr install
    
  4. In Studio, install the Azul Companion Plugin and open your place. In the plugin settings, turn on auto-connect, so the plugin connects to each push without a click.

  5. Push the packages:

    embr studio push
    

    The command waits until the plugin connects. Click Connect in the plugin if auto-connect is off.

  6. Start live sync:

    azul
    

The ember.toml of the project now has these lines:

[dependencies]
core = { name = "chief/core", version = "^" }

[tools]
azul = "npm:azul-sync@2.4.0"

[studio]
sync = "azul"

Where the packages go#

EnvironmentFolder on diskPlace in Studio
robloxpackages/robloxReplicatedStorage.Packages
roblox_serverpackages/serverServerStorage.Packages

The client and the server both see ReplicatedStorage. ServerStorage never replicates to a client, so server packages stay on the server. Other environments, such as Lune, do not run in Studio, and Ember does not push them.

Each push clears the Studio folder first. Ember owns ReplicatedStorage.Packages and ServerStorage.Packages, in the same way it owns packages/. Do not keep your own instances in them.

The manifest settings#

All four keys go under [studio], beside the universe, place or file keys of embr studio open. Each key is optional.

[studio]
sync = "azul"                                # or "rojo"
sync-dir = "sync"                            # Azul's syncDir
roblox-packages = "ReplicatedStorage.Packages"
server-packages = "ServerStorage.Packages"
KeyDefaultWhat it does
syncread from diskThe sync tool of the project: azul or rojo.
sync-dirsyncThe folder that Azul mirrors Studio into. Set it when your Azul config sets another syncDir.
roblox-packagesReplicatedStorage.PackagesThe Studio folder for the roblox packages.
server-packagesServerStorage.PackagesThe Studio folder for the roblox_server packages.

A Studio path is dot separated, such as ReplicatedFirst.Deps. A game. in front is removed. An empty segment, as in ReplicatedStorage..Packages, is an error. The folders on disk come from [config], as for every install.

How Ember finds an Azul project#

  1. When sync under [studio] is set, Ember uses it. The setting always wins.
  2. Else, when the sync folder holds a Studio service folder, such as sync/ReplicatedStorage, and no *.project.json file is beside ember.toml, the project is an Azul project.
  3. Else the project is a Rojo project. Rojo is the default.

A project with both a sync folder and a Rojo project file is not clear, so Ember uses Rojo. Set sync = "azul" in that project.

What embr studio push runs#

For each installed packages folder, Ember runs one Azul push:

azul push --source packages/roblox --destination ReplicatedStorage.Packages --destructive --rojo --no-warn
  • --rojo reads the folder the way Rojo does. The link files and the vendored Rojo project files need this.
  • --destructive clears the Studio folder first, so a package that you removed also goes from Studio.
  • --no-warn skips the question that --destructive asks.

When the project pins npm:azul-sync, Ember runs that version with node. Else it runs the azul command on your PATH.

While azul runs, a push cannot start. azul push needs the port that live sync uses. Ember then stops with this message:

Azul's live sync uses its port, so `azul push` cannot start; stop `azul`, run `embr studio push`, then start `azul` again

Each push is one plugin session, and the plugin disconnects after it. With two packages folders, the plugin connects two times.

Automatic push after install#

In an Azul project, embr install compares ember.lock before and after the install. It pushes each packages folder whose locked packages changed. A folder with no change is not pushed. embr add and embr remove only edit ember.toml. The embr install that follows them makes the push.

An automatic push never makes the install fail. When the push cannot happen, Ember prints one line that tells you what to do:

CaseWhat Ember prints
Studio is not openStudio is not open, so embr did not push the packages. Open it, then run embr studio push
The plugin does not connect in 15 secondsStudio did not connect to Azul in 15 s. Run embr studio push, then click Connect in the Azul plugin
azul live sync runsAzul's live sync uses its port, so embr did not push. Stop azul, run embr studio push, then start azul again
Azul is not installedAzul is not installed, so embr did not push. Run embr tool add npm:azul-sync, embr install, then embr studio push

Ember looks for the Studio process before it starts Azul, so a closed Studio costs no wait. CI has no Studio, so an install in CI only prints the first line.

Run Azul from a script#

Ember does not write scripts for you. If you want a short name for live sync, add your own script:

[scripts]
dev = "azul"

Then embr run dev starts Azul. Remember to stop it before an install that changes packages, because a push cannot start while it runs.

.gitignore#

Azul mirrors Studio back to disk. The packages that Ember pushed come back as copies, such as sync/ReplicatedStorage/Packages/. Each time Ember pushes, it adds these folders to .gitignore:

sync/ReplicatedStorage/Packages/
sync/ServerStorage/Packages/

A line that is already there, in any common spelling, is not added again. The lines follow sync-dir, roblox-packages and server-packages.

Publishing#

embr publish never packs the mirrored copies. In an Azul project, the folders from the list above are skipped like packages/. The rest of the sync folder, which holds your own code, is packed as usual.

Azul as a pinned tool#

Azul ships on npm only, so [tools] takes an npm form:

[tools]
azul = "npm:azul-sync@2.4.0"
  • embr tool add npm:azul-sync pins the latest version. Add @2.4.0, or --version 2.4.0, for one version. The key is the command of the package, azul.
  • embr install runs npm install into ~/.ember/tools/npm/azul-sync/2.4.0/ and puts an azul shim on PATH. Each project runs the version it pins, as with every tool.
  • Node.js must be on PATH. When it is missing, or older than the engines field of the package asks for, the install stops and says so.
  • embr tool update, embr tool list and embr tool delete npm:azul-sync work as they do for GitHub tools.

A global npm install -g azul-sync also works. Ember then runs the azul command on your PATH.

See also#