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.
-
Pin Azul as a project tool:
embr tool add npm:azul-sync@2.4.0embr tool add azuldoes the same, but only when the registry's shorthand list has the nameazul. -
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. -
Add packages and install them.
embr installalso installs Azul:embr add chief/core embr install -
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.
-
Push the packages:
embr studio pushThe command waits until the plugin connects. Click Connect in the plugin if auto-connect is off.
-
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#
| Environment | Folder on disk | Place in Studio |
|---|---|---|
roblox | packages/roblox | ReplicatedStorage.Packages |
roblox_server | packages/server | ServerStorage.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"
| Key | Default | What it does |
|---|---|---|
sync | read from disk | The sync tool of the project: azul or rojo. |
sync-dir | sync | The folder that Azul mirrors Studio into. Set it when your Azul config sets another syncDir. |
roblox-packages | ReplicatedStorage.Packages | The Studio folder for the roblox packages. |
server-packages | ServerStorage.Packages | The 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#
- When
syncunder[studio]is set, Ember uses it. The setting always wins. - Else, when the sync folder holds a Studio service folder, such as
sync/ReplicatedStorage, and no*.project.jsonfile is besideember.toml, the project is an Azul project. - 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
--rojoreads the folder the way Rojo does. The link files and the vendored Rojo project files need this.--destructiveclears the Studio folder first, so a package that you removed also goes from Studio.--no-warnskips the question that--destructiveasks.
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:
| Case | What Ember prints |
|---|---|
| Studio is not open | Studio is not open, so embr did not push the packages. Open it, then run embr studio push |
| The plugin does not connect in 15 seconds | Studio did not connect to Azul in 15 s. Run embr studio push, then click Connect in the Azul plugin |
azul live sync runs | Azul's live sync uses its port, so embr did not push. Stop azul, run embr studio push, then start azul again |
| Azul is not installed | Azul 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-syncpins 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 installrunsnpm installinto~/.ember/tools/npm/azul-sync/2.4.0/and puts anazulshim 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
enginesfield of the package asks for, the install stops and says so. embr tool update,embr tool listandembr tool delete npm:azul-syncwork 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#
embr studio: set up, open, and push to the place.[tools],[scripts]&[studio]: the tables on this page.- Azul's own docs:
azul push,azul build, and the plugin settings.