How to Rebuild and Reload Rust Services in Macro: Fast Development Workflow

Macro provides an interactive hot-key workflow and one-shot commands to rebuild only changed Rust crates and reload services instantly without stopping the entire stack.

The macro-inc/macro repository ships with a streamlined development environment that eliminates full-stack restarts when iterating on Rust microservices. Whether you prefer keyboard-driven hot-reloading or scripted automation, the justfile-based tooling detects changes, rebuilds only affected crates, and swaps containers in place. This guide covers both interactive and non-interactive methods to rebuild and reload Rust services in Macro with minimal disruption.

Interactive Hot-Key Workflow

Macro’s fastest feedback loop runs inside an attached terminal session where single keystrokes trigger incremental rebuilds.

Starting the Development Stack

Boot the local environment with the command that attaches your terminal for hot-key input:

just run_local

# Alternative: just stack up

This command initializes the Docker Compose infrastructure and begins listening for keyboard input.

Triggering Rebuilds with the r Key

While the stack is attached, press r to invoke the just stack update logic. According to docs/RUNNING_LOCALLY.md, this hot-key executes three steps in sequence:

1. Change detection – The helper inspects the Cargo workspace to identify crates with modified source files.
2. Compilation – Changed crates are passed to cargo build using your active profile (debug or release).
3. Container replacement – Fresh binaries are copied into the service’s Dockerfile context, a new image is built, and the running container is swapped without dropping network or volume mounts.

Clean Shutdown with q

Press q to exit the hot-key loop gracefully. This action also removes the existing containers, ensuring the next just run_local invocation starts from a clean state.

One-Shot Rebuild Commands

If you prefer not to keep an attached terminal, achieve the same result via CLI.

Basic Service Update

Run the following command from the repository root to rebuild and reload only the changed services:

just stack update

This executes the same change-detection and container-swap logic as the interactive r key.

Including Frontend Assets

To rebuild both Rust services and the frontend bundle after UI modifications, append the --frontend flag:

just stack update --frontend

Change Detection and Build Process

Understanding the internals helps debug build failures or optimize iteration speed.

Cargo Workspace Inspection

The just helper scans the workspace manifest to detect file changes. Only crates with modified source are submitted to the Rust compiler, keeping rebuild times minimal for large monorepos.

Docker Image Reconstruction

Compiled binaries from target/ are copied into the service-specific Dockerfile context. For example, services/document_storage_service/Dockerfile consumes the freshly built binary during image reconstruction.

Container Swapping Strategy

Docker Compose stops the outdated container for the specific service and starts a fresh instance from the newly built image. The operation preserves the underlying network and volume configuration, maintaining database connections and state between reloads.

Complete Development Workflow Examples

The following patterns illustrate typical daily usage for Rust service development in Macro.

Standard Iteration Loop

# 1. Start the stack with hot-key support

just run_local

# 2. Edit Rust code, e.g., services/document_storage_service/src/lib.rs

# 3. Press 'r' in the attached terminal to rebuild and reload

Non-Interactive CI or Scripting

# Rebuild only what changed and reload services

just stack update

# Or include frontend rebuild

just stack update --frontend

Working with Auxiliary Services

For services excluded from the default build, launch with the auxiliary flag and then use standard reload triggers:

just run_local --build-aux-services

# Then press 'r' as needed, or run `just stack update` in another window

Summary

• Macro’s development tooling resides in the justfile and is documented in docs/RUNNING_LOCALLY.md.
• Interactive mode uses just run_local plus the r key for instant reloads and q for clean exits.
• One-shot updates use just stack update, with optional --frontend to include UI assets.
• Change detection is workspace-aware, rebuilding only modified Rust crates and swapping Docker containers in place.
• Auxiliary services require the --build-aux-services flag during startup but follow the same reload workflow.

Frequently Asked Questions

What is the fastest way to rebuild and reload Rust services in Macro during development?

Run just run_local to attach your terminal, then press r whenever you modify Rust source code. This triggers a targeted rebuild and container swap without restarting the entire stack.

How do I rebuild only the changed services without restarting the entire stack?

Execute just stack update from any terminal window. The command detects which Cargo crates changed, recompiles them, rebuilds the Docker images, and reloads only the affected containers.

Can I rebuild auxiliary services that are excluded from the default build?

Yes. Start the stack with just run_local --build-aux-services to include additional services in the initial composition. Once running, use the same r hot-key or just stack update command to reload them after code changes.

How do I include the frontend bundle in the rebuild process?

Append the --frontend flag to your update command: just stack update --frontend. This rebuilds the Rust services and runs the frontend build pipeline in a single operation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}