URL Specification

URL Specification

@microfrontend/controller uses a custom URL hash format to encode the state of all microfrontends across outlets.

Reserved Symbols

Symbol	Meaning
;	Separates outlets
~	Separates outlet name from its routes
!	Separates routes of different microfrontends within an outlet

Default Outlet Format

When using a single (default) outlet, the outlet name is omitted. The hash consists of microfrontend routes separated by !:

#metaRoute1/subRoute!metaRoute2/subRoute

Rules:

• The first route in the list is the active (visible) microfrontend
• Subsequent routes are hidden but their state is preserved
• Each route consists of a metaRoute optionally followed by /subRoute

Examples

URL Hash	Active MF	Active Subroute	Hidden MFs
#a	a	(none)	(none)
#a/settings	a	settings	(none)
#a!b	a	(none)	b
#a/settings!b	a	settings	b (no subroute)
#a/settings!b/home	a	settings	b (subroute home)
#b!a/settings	b	(none)	a (subroute settings)

Detailed Walkthrough

Given the URL hash:

#a/b/c!x/y/z

This encodes two microfrontends in the default outlet:

• Microfrontend a:
  • Currently visible (first in the list)
  • Internal subroute: b/c
• Microfrontend x:
  • Currently hidden (not first)
  • Internal subroute: y/z

Full URL Format (Named Outlets)

Note: The current version supports a single outlet only. Named outlet syntax is reserved for future use.

The full format includes outlet names, with outlets separated by ;:

#outlet1~metaRoute1/sub!metaRoute2/sub;outlet2~metaRoute3/sub

Example

#outlet1~a/b/c!x/y/z;outlet2~k/l/m

This encodes two outlets:

outlet1 contains two microfrontends:

• Microfrontend a — visible, subroute b/c
• Microfrontend x — hidden, subroute y/z

outlet2 contains one microfrontend:

• Microfrontend k — visible, subroute l/m

URL Construction and Parsing

The UrlHelper class (internal) handles URL construction and parsing:

• Parsing: Splits by ; (outlets), then ~ (outlet name vs routes), then ! (individual routes), then / (metaRoute vs subRoute)
• Construction: Reverses the process to build a full hash from internal state

History Integration

When the URL hash changes:

1. User click navigation (e.g., router.go('b')) → uses history.pushState() to create a new browser history entry
2. Programmatic/internal updates (e.g., microfrontend reports a route change) → uses history.replaceState() to update the current entry without creating a new one
3. Back/forward button → triggers a hashchange event, which the MetaRouter handles by activating the encoded route

This design ensures that the browser's back and forward buttons correctly navigate between microfrontend states.

Hash Prefix

The FrameConfig.hashPrefix (default: '/') is prepended to hash routes when constructing iframe URLs. This allows microfrontends to use hash-based routing (e.g., #/settings inside the iframe) while the shell manages the meta-routing hash.