How Azul syncs Studio to your filesystem

Understand how Studio instances map to local files, how script types determine file suffixes, and how nested instances are handled on disk.

When you connect the Azul plugin in Studio, the daemon takes a full snapshot of your DataModel and mirrors it into your local syncDir (default: ./sync). Every instance becomes a file or folder whose path directly reflects where it lives in the Studio hierarchy. Understanding this mapping helps you navigate your project and avoid surprises when editing locally.

Basic mapping

Each Script instance in Studio becomes a single file on disk. The path from syncDir to the file mirrors the instance’s ancestry in the DataModel.

Example — a single script:

Studio path	Local file
ReplicatedStorage.Modules.MyServerScript	sync/ReplicatedStorage/Modules/MyServerScript.server.luau

The file name carries a suffix that encodes the script’s class (see Script type suffixes below). Non-script instances that only serve as containers become plain directories.

Script type suffixes

Azul determines the Roblox script class from the file’s suffix when syncing local changes back to Studio, and writes the correct suffix when mirroring Studio to disk.

Studio class	File suffix
Script (server)	.server.luau
LocalScript	.client.luau
ModuleScript	(no suffix) or .module.luau

By default, ModuleScripts have no suffix. You can opt into .module.luau suffixes for all ModuleScripts by enabling suffixModuleScripts in your CLI config.

Nested instances under scripts

When a script has child instances in Studio, Azul can’t flatten them all into one file. Instead, it uses a sibling folder pattern: the script file keeps its normal name, and a folder with the same base name holds the children.

Example — a script with a nested child:

Studio path	Local path
ServerScriptService.Game.ParentScript	sync/ServerScriptService/Game/ParentScript.server.luau
ServerScriptService.Game.ParentScript.NestedScript	sync/ServerScriptService/Game/ParentScript/NestedScript.server.luau

The parent script file (ParentScript.server.luau) and its sibling folder (ParentScript/) sit next to each other at the same directory level. This makes the parent–child relationship clear without hiding any files inside the script itself.

Important behavior notes

Studio is the source of truth for your instance hierarchy. Creating a new file locally does not automatically create a new instance in Studio — you need to use azul build or azul push to import local-only content.

• Editing script contents locally syncs back to Studio in real time once the daemon is connected. The file watcher detects the change and pushes it through the WebSocket.
• Renaming or moving instances must happen in Studio. Doing so on disk alone will not rename or reparent the Studio instance.
• Importing local-only content — for example, packages installed by Wally or code you wrote outside of Studio — requires running azul build or azul push. See Advanced Usage for push mapping options.

Use azul build for a full one-time push of your entire local project into Studio. Use azul push when you want to target a specific folder — for example, pushing a Packages directory to ReplicatedStorage.Packages.