> ## Documentation Index
> Fetch the complete documentation index at: https://vercel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Azul daily workflows and team patterns

> Practical patterns for your daily coding loop, importing Wally packages into Studio, setting up a team with shared config, and diagnosing sync problems.

Azul is flexible enough to fit into most Roblox development workflows, whether you're working solo or coordinating with a team. This page walks through the most common patterns so you can get productive quickly and avoid repeated troubleshooting.

## Daily coding loop

The typical session starts the daemon, connects Studio, and keeps both sides in sync for as long as you're working.

**1. Start the daemon**

Open a terminal in your project folder and run:

```bash theme={null}
azul
```

The daemon starts and waits for Studio to connect on the configured port (default `8080`).

**2. Connect in Studio**

Open your place in Roblox Studio, then click **Connect** in the Azul plugin panel. Your DataModel is mirrored to the local sync directory immediately.

**3. Edit in Studio or your editor**

Edit scripts in Studio or in your local editor — both sides stay in sync automatically. You can switch freely between them.

**4. Commit your changes**

Use any version control tool to commit the local files as you normally would. The sync directory is a plain folder on disk.

> [!TIP]
>
> Leave the daemon running throughout your session. It handles reconnections automatically if Studio closes and reopens.

## Import a package folder into Studio

When you install dependencies locally — for example, with [Wally](https://wally.run/) — you can push them into Studio with a single command rather than uploading files manually.

Use `azul push` with explicit source and destination flags:

```bash theme={null}
azul push -s Packages -d ReplicatedStorage.Packages --destructive --rojo
```

* `-s Packages` — the local folder to push from
* `-d ReplicatedStorage.Packages` — the Studio instance to push into
* `--destructive` — removes any instances in the destination that don't have a matching local file
* `--rojo` — interprets the folder structure using Rojo conventions (required for Wally packages)

> [!NOTE]
>
> If you run this command often, add a `pushMappings` entry to your per-place config so you can run plain `azul push` without repeating the flags every time. See [Advanced configuration](/advanced-usage) for details.

## Team setup with consistent behavior

Storing your daemon configuration inside the place file means every collaborator gets the same behavior automatically — no manual CLI flags required.

**1. Create the config script in Studio**

In Roblox Studio, create a `ModuleScript` at `ServerStorage > Azul > Config`.

**2. Define your project settings**

Return a table from the script with the options your team needs. At minimum, set `port`, `deleteOrphansOnConnect`, and any `pushMappings` you want to share:

```lua theme={null}
-- ServerStorage/Azul/Config
return {
    port = 8080,
    deleteOrphansOnConnect = true,
    pushMappings = {
        {
            source = "Packages",
            destination = { "ReplicatedStorage", "Packages" },
            destructive = true,
            rojoMode = true,
        },
    },
}
```

**3. Commit and share the place file**

Save and commit the place file. Teammates who open it will have the same daemon configuration applied automatically when they connect.

**4. Use standard commands**

Ask everyone on the team to run the same plain commands — `azul` to start the daemon, `azul push` to push packages. The per-place config handles the rest.

> [!TIP]
>
> Versioning the place file alongside your code keeps configuration drift from becoming a problem as the project evolves.

## Troubleshooting checklist

If the daemon and plugin aren't communicating, work through these checks in order before digging deeper.

> **Port mismatch between daemon and plugin**
>
> The plugin connects to the daemon over a WebSocket. If the port in the plugin's settings doesn't match the port the daemon is listening on, the connection will fail silently.
>
> Check the port the daemon is using — it logs it on startup. Then confirm the plugin's WebSocket URL uses the same port. If you've set a custom port in `ServerStorage.Azul.Config`, make sure both sides reflect it.

> **Enable debug logs with --debug**
>
> Run the daemon with the `--debug` flag to see detailed handshake and sync logs:
>
> ```bash theme={null}
> azul --debug
> ```
>
> The output shows each message exchanged between the daemon and plugin, which makes it easy to spot where the connection breaks down.

> **Verify syncDir and sourcemapPath in config**
>
> Run the following command to inspect your current CLI configuration:
>
> ```bash theme={null}
> azul config
> ```
>
> Confirm that `syncDir` points to the folder you expect and that `sourcemapPath` is correct if you're generating a sourcemap. An incorrect `syncDir` means file writes go to the wrong location.

> **Reconnect after changing config**
>
> The daemon reads configuration at startup and the plugin reads per-place config at connection time. If you change anything — CLI config, the per-place `Config` script, or the plugin settings — disconnect and reconnect before testing again.
>
> To reconnect: click **Disconnect** in the Azul plugin, stop the daemon (`Ctrl+C`), start it again with `azul`, then click **Connect** in the plugin.

> [!WARNING]
>
> If you change the port in `ServerStorage.Azul.Config` while the daemon is running, you must restart the daemon for the new port to take effect.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.