Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

docs: Guide frontend contributors on using hosted APIs with Vite versus having to run the entire stack locally (#5853)

Cameron Pak3891b4beeff4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cbf86fb215..f84e3d0ddd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,7 +44,11 @@ No generated boilerplate, no exhaustive file-by-file change lists.
## Development setup
-See [docs/RUNNING_LOCALLY.md](docs/RUNNING_LOCALLY.md) for running the full app locally.
+You do not need the local stack if you only change the frontend.
+
+If you only change the frontend, run the [frontend against hosted services](docs/RUNNING_LOCALLY.md#run-the-frontend-against-hosted-services).
+
+If you change a backend service, the database, or behavior that must stay on your machine, [run the local stack](docs/RUNNING_LOCALLY.md#run-the-local-stack).
## Before you push
diff --git a/README.md b/README.md
index 865bf209c7..48aa50c501 100644
--- a/README.md
+++ b/README.md
@@ -201,7 +201,7 @@ Deeper reading: [key concepts](https://docs.macro.com/concepts/blocks) covers bl
# Running it locally
-To run the full app on your machine, follow [Running locally](docs/RUNNING_LOCALLY.md).
+To run the frontend against hosted services, or to run the local stack, follow [Running locally](docs/RUNNING_LOCALLY.md).
To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/docs/RUNNING_LOCALLY.md b/docs/RUNNING_LOCALLY.md
index db2f6dfd74..20a50134c6 100644
--- a/docs/RUNNING_LOCALLY.md
+++ b/docs/RUNNING_LOCALLY.md
@@ -1,16 +1,21 @@
-# Running Locally
+# Running locally
-This guide explains how to run Macro on your machine. The local stack runs without Doppler. It runs Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth in Docker, with dummy AWS credentials and fixed test secrets.
+This guide covers two ways to run Macro on your machine.
-## What You Need
+If you only change the frontend, run the frontend against hosted services. You do not need Docker or the local stack.
-Install Nix before you start:
+If you change a backend service, the database, or behavior that must stay on your machine, run the local stack.
-1. [Nix](https://nix.dev/install-nix) package manager
+## Choose a path
-On Linux, the Nix dev shell supplies the Docker CLI, daemon, Compose, and `fuse-overlayfs`. Nix is the only host dependency.
+- **Frontend against hosted services.** Vite on your machine. APIs on hosted `*-dev` services. See [Run the frontend against hosted services](#run-the-frontend-against-hosted-services).
+- **Local stack.** Docker, local infrastructure, and local Rust services. See [Run the local stack](#run-the-local-stack).
-On macOS, install a Docker runtime such as Docker Desktop, OrbStack, or Colima. The Nix dev shell supplies the Docker CLI, but macOS still needs the runtime to provide the daemon.
+## Shared prerequisites
+
+Install Nix before you start:
+
+1. [Nix](https://nix.dev/install-nix) package manager
Clone the repository:
@@ -19,9 +24,7 @@ git clone https://github.com/macro-inc/macro.git
cd macro
```
-## Enter the Nix Shell
-
-The Nix shell provides `just`, Cargo, the Rust toolchain, Bun, sqlx, zig, cargo-zigbuild, and Docker tooling. You do not need to install these tools separately.
+The Nix shell provides `just`, Cargo, the Rust toolchain, Bun, `wasm-pack`, sqlx, zig, and cargo-zigbuild. You do not need to install these tools separately.
```bash
nix develop
@@ -41,7 +44,41 @@ experimental-features = nix-command flakes
The default shell does not include the Tauri platform dependencies. They are large, so they live in their own shells. For Linux desktop development, use `nix develop .#tauri-linux`. For Android development on x86_64 Linux, use `nix develop .#tauri-android`.
-## Start the Stack
+## Run the frontend against hosted services
+
+The web app talks to hosted `*-dev` services when you run `bun run dev` from the web app.
+
+Limits:
+
+- You still need Nix. The first `bun run dev` may compile wasm. Later runs skip that compile when versions match.
+- The UI calls hosted `*-dev` services and shared data.
+- Sign-in is not the local Mailpit flow. If you need a private database or to change a backend service, use the [local stack](#run-the-local-stack).
+
+From the repository root, inside the Nix shell:
+
+```bash
+bun install
+cd apps/web
+bun run dev
+```
+
+The first run, or a run after a wasm version change, may build wasm packages. Vite prints a local URL when it is ready.
+
+## Run the local stack
+
+The local stack runs without Doppler. It runs Postgres, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth in Docker, with dummy AWS credentials and fixed test secrets.
+
+On Linux, the Nix dev shell supplies the Docker CLI, daemon, Compose, and `fuse-overlayfs`. Nix is the only host dependency.
+
+On macOS, install a Docker runtime such as Docker Desktop, OrbStack, or Colima. The Nix dev shell supplies the Docker CLI, but macOS still needs the runtime to provide the daemon.
+
+Run the preflight check before the first start:
+
+```bash
+just doctor-local
+```
+
+The check tests the Docker daemon, the toolchain, and the required ports. It reports any problem and suggests a fix. If a start fails, run the check again.
Run this command from the repository root if you do not have Doppler access:
@@ -127,16 +164,6 @@ just run_local --no-doppler --env-file ./local.env
Keys in the file override the code-defined defaults, so you only need to list the integrations you care about. With Doppler access, `just run_local` (without `--no-doppler`) supplies everything automatically.
-## Check the Setup
-
-Run the preflight check before the first start:
-
-```bash
-just doctor-local
-```
-
-The check tests the Docker daemon, the toolchain, and the required ports. It reports any problem and suggests a fix. If a start fails, run the check again.
-
## Control the Running Stack
While `run_local` is attached: