Routing, Navigation and URL

Assuming you want to link from your app to Discover. When building such URL there are two things to consider:

const discoverUrl = core.http.basePath.prepend(`/discover`);

console.log(discoverUrl); // http://localhost:5601/bpr/s/space/app/discover

// Avoid relying on other app's state structure in your app's code:
const discoverUrlWithSomeState = core.http.basePath.prepend(`/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:'2020-09-10T11:39:50.203Z',to:'2020-09-10T11:40:20.249Z'))&_a=(columns:!(_source),filters:!(),index:'90943e30-9a47-11e8-b64d-95841ca0b247',interval:auto,query:(language:kuery,query:''),sort:!())`);

// Properly generated URL to *Discover* app. Locator code is owned by *Discover* app and available on *Discover*'s plugin contract.
const discoverUrl = await plugins.discover.locator.getUrl({filters, timeRange});
// or directly execute navigation
await plugins.discover.locator.navigate({filters, timeRange});

Kibana is a single page application and there is a set of simple rules developers should follow to make sure there is no page reload when navigating from one place in Kibana to another.

For example, navigation using native browser APIs would cause a full page reload.

const urlToADashboard = core.http.basePath.prepend(`/dashboard/my-dashboard`);

// this would cause a full page reload:
window.location.href = urlToADashboard;

To navigate between different Kibana apps without a page reload (by default) there are APIs in core:

Both methods offer customization such as opening the target in a new page, with an options parameter. All the options are optional be default.

Rendering a link to a different Kibana app on its own would also cause a full page reload:

const myLink = () =>
  <a href={urlToADashboard}>Go to Dashboard</a>;

A workaround could be to handle a click, prevent browser navigation and use core.application.navigateToApp API:

const MySPALink = () =>
  <a
    href={urlToADashboard}
    onClick={(e) => {
      e.preventDefault();
      core.application.navigateToApp('dashboard', { path: '/my-dashboard' });
    }}
  >
    Go to Dashboard
  </a>;

As it would be too much boilerplate to do this for each Kibana link in your app, there is a handy wrapper that helps with it: RedirectAppLinks.

const MyApp = () =>
  <RedirectAppLinks coreStart={{application: core.application}}>
    {/*...*/}
    {/* navigations using this link will happen in SPA friendly way */}
      <a href={urlToADashboard}>Go to Dashboard</a>
    {/*...*/}
  </RedirectAppLinks>

const MyForcedPageReloadLink = () =>
  <a
    href={urlToSomeSpecialApp}
    onClick={(e) => {
      e.preventDefault();
      core.application.navigateToUrl('someSpecialApp', { forceRedirect: true });
    }}
  >
    Go to Some Special App
  </a>;

If you also need to bypass the default onAppLeave behavior, you can set the skipUnload option to true. This option is also available in navigateToApp.

It is very common for Kibana apps to use React and React Router. Common rules to follow in this scenario:

This is required to make sure core is aware of navigations triggered inside your app, so it could act accordingly when needed.

Relative links will be resolved relative to your app’s route (e.g.: http://localhost5601/app/{your-app-id}) and setting up internal links in your app in SPA friendly way would look something like:

import {Link} from 'react-router-dom';

const MyInternalLink = () => <Link to="/my-other-page"></Link>

Try to avoid using window.location and window.history directly.
Instead, consider using ScopedHistory instance provided by core.

Common use-case for using core's ScopedHistory directly:

Historically Kibana apps store a lot of application state in the URL. The most common pattern that Kibana apps follow today is storing state in _a and _g query params in rison format.

Those query params follow the convention:

There are utils to help you to implement such kind of state syncing.

When you should consider using state syncing utils:

When you shouldn’t use state syncing utils:

Follow these docs to learn more.

Consider the scenario:

You’d notice that you were navigated to Dashboard app with the same state that you left it with, except that the time filter has changed to the one you applied on Discover app.

Historically Kibana Analyze groups apps achieve that behavior relying on state in the URL. If you’d have a closer look on a link in the navigation, you’d notice that state is stored inside that link, and it also gets updated whenever relevant state changes happen:

This is where separation into _a and _g query params comes into play. What is considered a global state gets constantly updated in those navigation links. In the example above it was a time filter. This is backed by KbnUrlTracker util. You can use it to achieve similar behavior.