> ## 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.

<Steps>
  <Step title="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`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Leave the daemon running throughout your session. It handles reconnections automatically if Studio closes and reopens.
</Tip>

## 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.
</Note>

## 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.

<Steps>
  <Step title="Create the config script in Studio">
    In Roblox Studio, create a `ModuleScript` at `ServerStorage > Azul > Config`.
  </Step>

  <Step title="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,
            },
        },
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Versioning the place file alongside your code keeps configuration drift from becoming a problem as the project evolves.
</Tip>

## Troubleshooting checklist

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<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.
</Warning>