The Tiny Proxy That Fixed Local Development for Our Multi-Repo Frontend

This article is a follow-up to From Independent Microsites to Context-Driven Architecture, where we explain why we split our frontend into multiple independent Next.js repositories.

If you'd rather explore the code before reading the architecture behind it, a small demo is available here: https://github.com/Subito-it/articles-code/tree/main/olympus-mini

---

The Problem Everyone in a Micro-Frontend Setup Hits

Your production environment has a smart edge router: Akamai, Cloudflare, nginx, whatever, that maps URL paths to different frontend applications:

/search         → next.js app A
/ads            → next.js app B
/profile        → next.js app C

It works beautifully in production. Then you open your laptop.

Each app runs on its own port, and suddenly you're managing this:

localhost:3001  → app A
localhost:3002  → app B
localhost:3003  → app C

Two things break immediately:

Cross-app links stop working. If app A renders <Link href="/ads/123">, that link resolves relative to localhost:3001; wrong app, wrong port. You either hardcode ports in your local env vars, or you just accept that links are broken locally.

Starting everything is a chore. Feature work that spans two apps means two terminals, two npm run dev commands, and memorizing which port does what. Add a third app and it gets worse.

You can't replicate your edge infrastructure locally. It's a cloud service. But you don't need to. You need something much smaller.

The Idea: A Purpose-Built Local Proxy

Instead of reaching for Docker Compose + nginx (which works, but is heavy and requires maintaining config that mirrors production), we built a small tool called Olympus: a Node.js HTTPS reverse proxy paired with a bash orchestration script.

It does the following things:

• Path-based routing: all apps are reachable under one local domain, with each URL path forwarded to the correct app, just like a monolith.
• API proxying without CORS: apps call a local /api-proxy route instead of hitting the staging API directly. The proxy forwards those requests, so the app never makes a cross-origin request.
• API mocking: a flag swaps the staging API for a local Mockoon instance, with no changes to app code required.
• Single command: a global command starts one or more apps together, with unified log output.

Path-based routing

Setting Up the Local Domain

The foundation is a fake local domain shared across the team, made possible by adding one entry to the /etc/hosts file:

127.0.0.1  www.myapp.local

Now https://www.myapp.local:9443 resolves to your machine. The proxy listens there and routes from a single origin, the same shape as production.

How the Routing Works

The proxy is a Node.js HTTPS server using http-proxy. Each app runs on a fixed local port, defined once in config (proxy/config.js):

const apps = {
  "app-search": 3001,
  "app-ads": 3002,
  "app-profile": 3003,
};

Routing is a list of regex patterns matched in order, first-match-wins, using the same mental model as nginx location blocks (proxy/utils/routing.js):

// www.myapp.local
{ pattern: /^\/ads/,     app: "app-ads" }
{ pattern: /^\/profile/, app: "app-profile" }
{ pattern: /.*/,         app: "app-search" }  // catch-all

When a request arrives, the proxy matches the path, looks up the port, and forwards it.
The Next.js app receives the request as if it came directly; it has no idea it's behind a proxy.

API proxying without CORS

Our apps in staging hit APIs on a different domain (e.g. api.staging.subito.it). Locally, the browser origin is www.myapp.local, so any direct call to that API would be cross-origin and blocked by the browser unless the server responds with the right CORS headers, which we don't control on the staging API.

The fix is to never make that cross-origin request at all. In the local environment, each app points its API base URL at a /api-proxy/* route on the same origin:

API_BASE_URL=https://www.myapp.local:9443/api-proxy

The proxy intercepts requests matching /api-proxy/*, strips the prefix, and forwards them server-side to the real staging API:

                 Browser
                    ↓
https://www.myapp.local/api-proxy/users/list
                    ↓
 https://api.staging.subito.it/users/list 

From the browser's perspective the request never leaves www.myapp.local, so CORS is never triggered.

API Mocking with Mockoon

A specific flag swaps the staging API for a local Mockoon instance, with no changes to app code required.

When you pass the flag, the Mockoon CLI starts and the proxy is launched, which redirects all /api-proxy traffic from the real staging API to Mockoon running on localhost:9999.

                 Browser
                    ↓
https://www.myapp.local/api-proxy/users/list
                    ↓
 http://localhost:9999/users/list (Mockoon)

Because mock definitions live in the repo, every developer gets the same responses without any manual setup. The script also watches the JSON file for changes and restarts Mockoon automatically, so updating a mock response takes effect immediately.

This is useful when staging is unstable, you're offline, or you need a deterministic response for a scenario that's hard to reproduce against a real API.

Single Command

The orchestration lives in a bash script (start.sh), invoked via a short wrapper (o) added to your $PATH during setup.

o app-search                        # proxy + one app
o app-search app-ads app-profile    # proxy + three apps
o --mock app-search                 # route API calls to local mocks
o --verbose app-search              # detailed proxy request logs

When you run it:

1. Any existing proxy process is killed (tracked via PID file)
2. Any process already occupying each app's port is killed
3. The HTTPS proxy starts
4. For each app: env vars are synced, then npm run dev starts
5. All apps run in parallel, each with a colored [app-name] prefix in the shared log stream

Ctrl+C kills everything cleanly via a SIGTERM trap.

The colored output is a small thing that makes a big difference — when five apps are logging simultaneously, being able to instantly tell which one produced a line saves real time.

Why Not Docker + nginx?

We considered it. The honest answer: it's more than we needed, and the maintenance cost compounds.

With Docker + nginx you get:

• An nginx config that needs to mirror your routing rules
• A docker-compose.yml to keep in sync with app changes
• Slower startup
• One more thing that works differently across developer machines

With a Node.js proxy:

• Routing config is one JS file
• Startup is instant
• It's just a process, kill, restart, done
• Any frontend dev can read and modify it

The principle: a small purpose-built tool beats a general one when the problem is well-scoped. Local dev routing is a well-scoped problem.

Takeaway

If your team runs multiple frontend apps locally and you're dealing with port juggling and broken cross-app links, the pattern is simple:

1. Pick a shared local domain, add it to /etc/hosts
2. Write a small HTTPS proxy with path-based routing
3. Wrap the startup logic in a single command

You don't need to replicate your production edge infrastructure. You need something that behaves enough like it to make local development feel natural. That bar is much lower than it looks.

Try It Yourself

A minimal working demo, three apps, one proxy, one command, is available at https://github.com/Subito-it/articles-code/tree/main/olympus-mini.

The key files:

File	What it does
proxy/config.js	Port mappings and SSL paths
proxy/utils/routing.js	Regex rules → app mapping
proxy/server.js	HTTPS server + http-proxy wiring
start.sh	Kill ports, start proxy + apps in parallel

No framework dependencies.