Forem: Fabio Arcari

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

Fabio Arcari — Thu, 14 May 2026 09:43:02 +0000

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:

Any existing proxy process is killed (tracked via PID file)
Any process already occupying each app's port is killed
The HTTPS proxy starts
For each app: env vars are synced, then npm run dev starts
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:

Pick a shared local domain, add it to /etc/hosts
Write a small HTTPS proxy with path-based routing
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.

From Microsites to Context-Driven Architecture: Lessons Learned

Fabio Arcari — Fri, 05 Sep 2025 21:15:27 +0000

From 12 separate microsites to 6 context-specific ones: the web architecture powering subito.it, Italy’s leading online classifieds platform, and the lessons we learned from overengineering.

Introduction

Four years ago, at subito.it, we had fully embraced the microsite approach.
Every page or small group of pages had its own repository, its own deploy pipeline, and its own infrastructure.
It was the era of the article "Our microsite architecture" published on Adevinta's tech blog, where we proudly described how we had "accelerated the frequency of releases and the independence of teams by applying a microsite approach."

What is a Microsite?

A microsite is an architectural approach where individual pages or small groups of related pages are developed, deployed, and maintained as completely separate applications.
Each microsite typically has its own:

Repository and codebase
CI/CD pipeline and deployment process
Infrastructure and hosting environment
Technology stack (which can differ from other microsites)
Team ownership and responsibility

This approach contrasts with traditional monolithic applications where all pages are part of a single large codebase.
Microsites aim to provide maximum team autonomy and deployment independence, allowing different teams to work on different parts of a website without interfering with each other.

Today, in 2025, we have an update on this architecture: we've found a better balance between agility and maintainability through continuous learning and optimization

The Microsite Era: When Everything Seemed Perfect

The microsite approach we had adopted seemed like the ideal solution for our problems:

Lean pipelines: each microsite had a fast and independent deploy pipeline
Team autonomy: each team could work on their own piece without interference
Independent releases: no mutual blocking between teams

Over time, however, we started noticing the first issues:

Uncontrolled Repository Proliferation, what had started as a strategy for important pages had begun to be applied to secondary pages as well.
Distributed Technical Debt, with 12 repositories to maintain, some pages started falling behind in dependency updates and security patches
Excessive Infrastructure Overhead, each microsite required:
- Monitoring configuration
- Alerting setup
- Pipeline maintenance
- CDN Configuration

The New Strategy: Context-Driven Microsites

Instead of going completely back to a monolith (which would have reintroduced the problem of overly long pipelines), we chose a middle path: context-specific microsites.

Principles of the New Architecture

Context First: we group pages that share the same business domain
Clear Ownership: each microsite remains owned by a specific team
Manageable Size: large enough to justify the infrastructure, small enough to remain maintainable

Our new architecture consolidates related pages into context-specific groupings:

Public Content Hub: All public content pages and SEO-relevant content
Ad Insertion Flow: The entire ad insertion workflow
Authentication Service: Authentication, login and sign-up
Transaction Service: The entire transaction ecosystem
Paid Options Service: Paid services and premium options
User Management Service: Personal area and profile management

The Transition Process

Our migration follows a structured approach with three main phases:

Phase 1: Preparation and Setup
The initial phase focuses on preparing the target microsite to receive the migrated functionality:

Set up dedicated layouts and components in the target architecture
Import and adapt components to the consolidated codebase
Update environment variables and configuration management
Establish monitoring and alerting for the new consolidated service

Phase 2: Quality Assurance and Testing
Before going live, we conduct comprehensive checks:

Execute automated end-to-end (E2E) and manual tests
Validate third-party integrations (e.g., GTM)
Verify page headers, caching policies, and security configurations
Confirm monitoring and metrics collection are correctly implemented

Phase 3: Production Migration and Cleanup
The final phase involves the actual cutover and decommissioning of legacy systems:

Gradual Rollout:

Route traffic progressively from legacy to consolidated microsite
Monitor performance and error rates during the transition

Legacy Cleanup:
Following our established Service End-of-Life procedures, we systematically decommission the old microsite:

Destroy monitoring, alerts, and dashboards
Archive repositories and remove deployment configurations
Clean up infrastructure resources (databases, IAM roles, etc.)
Update routing and add redirects where necessary

Conclusions

Our journey from microsites to a more consolidated approach wasn't a failure of microsite architecture, but rather a maturation of our understanding of when and how to apply it.

What we learned:

Architecture must evolve with business and team needs
Not everything needs to be a microservice/microsite - like any architectural pattern, it has its trade-offs
Context is fundamental, group by business context, not technical convenience
Pages that belong to the same user flow should probably stay together

Today, with our 6 context-driven microsites, we've found a balance that allows us to maintain team autonomy and deployment speed while significantly reducing maintenance overhead.

The path to perfect architecture doesn't exist, but the path to ever-improving architecture does.