Routing

micro-lc API offers a set of facilities for routing between sub-applications. Some methods are proxies of the document window, offered to centralize the routing experience, while other are based on internal logic.

goTo

export interface MicrolcApi {
  router: {
    goTo: (url: string | URL | undefined) => void
    // ...rest of the API
  }
  // ...rest of the API
}

goTo can be used to route the application to a specific URL. The behaviour of the method changes based on the relation between the curren URL and the given URL.

If the new URL has a different origin than the current URL, goTo behaves as a window.open with target _self.

If the new URL has same origin and same pathname as the current URL, goTo behaves as a history.replaceState (useful, for example, if you just need to change query parameters).

Finally, if the new URL has same origin and different pathname than the current URL, goTo behaves as a history.pushState.

caution

Using this API does not ensure that the url is changed after the unmount of the current application, if any. To achieve that use goToApplication

goToApplication

export interface MicrolcApi {
  router: {
    goToApplication<S = unknown>(id: string, data?: S): Promise<void>
    // ...rest of the API
  }
  // ...rest of the API
}

goToApplication is the primary method for moving across applications in micro-lc. Instead of requiring the next url, it expects the id of the application that needs to be mounted next. The application must be available in the configuration field applications.

The API then proceeds to:

1. unmount the currently mounted application, if any
2. retrieve the next url from the application id
3. call such url via history.pushState to update the browser
4. mount the application with the given id

caution

If provided id does not match any registered application, goToApplication will route to 404 error page.

goToErrorPage

export interface MicrolcApi {
  router: {
    goToErrorPage(statusCode?: number, reason?: string): void
    // ...rest of the API
  }
  // ...rest of the API
}

goToErrorPage can be used to programmatically route to an error page. Argument statusCode is the error number (defaults to 404), and reason is the cause of the error.

caution

If provided statusCode does not match any registered error page, goToErrorPage will throw an error.

open

export interface MicrolcApi {
  router: {
    open: (url?: string | URL, target?: string, features?: string) => Window | null
    // ...rest of the API
  }
  // ...rest of the API
}

open mirrors the browser native API.

pushState

export interface MicrolcApi {
  router: {
    pushState: (data: any, unused: string, url?: string | URL | null) => void
    // ...rest of the API
  }
  // ...rest of the API
}

pushState mirrors the browser native API.

replaceState

export interface MicrolcApi {
  router: {
    replaceState: (data: any, unused: string, url?: string | URL | null) => void
    // ...rest of the API
  }
  // ...rest of the API
}

replaceState mirrors the browser native API.