Working with Url

Route

Route description format:

const routes = [
  {
    // the name of the route is required
    name: 'foo-bar',
    // the path of the route is required
    path: '/foo/bar/',
    // additional configs for the route
    config: {
      // page component name
      pageComponent: 'page',
      // page layout component name
      nestedLayoutComponent: 'page-layout',
      // global layout component name
      layoutComponent: 'layout',
      // page error boundary component name
      errorBoundaryComponent: 'error-boundary',
    },
  },
];

Route interface (this is a config that is defined for route somewhere when application starts):

interface Route {
  // name of the route
  name: string;
  // path in route config. Might not be equal to the actual path in browser as
  // it may have a dynamic parts
  path: string;
  // additional config for route, that is not used by router library, but
  // might be used by router dependents
  config?: Record<string, any>;
  // redirect options that should happed when navigating to current route
  redirect?: string | NavigateOptions;
}

NavigationRoute interface (this is an instance that created on every navigation from base route by adding additional parameters related to specific navigation):

interface NavigationRoute extends Route {
  // actual path that was resolved from requested url. Unlike `path` actualPath
  // won't contain any dynamic parts and will be equal to path in browser
  actualPath: string;
  // resolved parts of the dynamic routes, where key is the name of dynamic part
  // and value is the actual value from the current url
  params: Record<string, string>;
  // additional state that can be passed by caller side on navigation
  navigateState?: any;
}

Url

Url interface:

interface Url {
  path: string;
  query: Record<string, string | string[]>;
  host: string;
  hostname: string;
  href: string;
  origin: string;
  pathname: string;
  port: string;
  protocol: string;
  search: string;
  hash: string;
}

useRoute() Hook

Returns current active route of the application:

import { useRoute } from '@tramvai/module-router';

export const Component = () => {
  const route = useRoute();

  return <div>Route path: {route.actualPath}</div>;
};

useUrl() Hook

Returns current active URL of the application:

import { useUrl } from '@tramvai/module-router';

export const Component = () => {
  const url = useUrl();

  return <div>Url query: {JSON.stringify(url.query)}</div>;
};

PageService Service

PageService is a wrapper for working with tramvai router. Serves to hide routing internals and is the preferred way to working with router. Available via PAGE_SERVICE_TOKEN token.

This service is intended for use in DI providers and actions, also it is a performant option to get route information in React components, e.g. in callback functions, when you don't need to rerender component when route is changed.

• getCurrentRoute() - get the current route
• getCurrentUrl() - object-result of parsing the current url
• getConfig() - get the config of the current page (route.config property)
• getContent() - get content for the current page (route.config.content property)
• getMeta() - get the meta for the current page (route.config.meta property)

import { provide, declareAction } from '@tramvai/core';
import { PAGE_SERVICE_TOKEN } from '@tramvai/module-router';

const action = declareAction({
  name: 'action',
  fn() {
    const { pageService } = this.deps;

    console.log(`Current path is`, pageService.getCurrentRoute().path);
  },
  deps: {
    pageService: PAGE_SERVICE_TOKEN,
  },
});

RouterStore Reducer

Stores information about the current and previous routes.

Properties:

• currentRoute
• currentUrl
• previousRoute
• previousUrl

Route Params

Dynamic parameters available in current route.params parameter.

In react components, use useRoute hook:

import { useRoute } from '@tramvai/module-router';

const Comment = () => {
  const route = useRoute();

  return (
    <li>
      Current comment id: {route.params.id}
    </li>
  );
};

In actions, use PAGE_SERVICE_TOKEN:

import { declareAction } from '@tramvai/core';

const someAction = declareAction({
  name: 'someAction',
  fn() {
    const route = this.deps.pageService.getCurrentRoute();

    console.log(`Current comment id: ${route.params.id}`);
  },
  deps: {
    pageService: PAGE_SERVICE_TOKEN,
  },
});

Query Params

Read

Parsed query string available in url.query parameter.

In react components, use useUrl hook:

import { useRoute } from '@tramvai/module-router';

const Page = () => {
  const url = useUrl();

  return (
    <li>
      Foo query value: {url.query.foo}
    </li>
  );
};

In actions, use PAGE_SERVICE_TOKEN:

import { declareAction } from '@tramvai/core';

const someAction = declareAction({
  name: 'someAction',
  fn() {
    const url = this.deps.pageService.getCurrentUrl();

    console.log(`Foo query value: ${url.query.foo}`);
  },
  deps: {
    pageService: PAGE_SERVICE_TOKEN,
  },
});

Update

navigate and updateCurrentRoute methods allow you to set a search string for an url as an object via the query option when navigating. The previous query value will be cleared:

pageService.navigate({ query: { a: 'a' } });
pageService.updateCurrentRoute({ query: { b: 'b' } });

preserveQuery option allows you to keep the query value from the current navigation and use them in a new transition:

pageService.updateCurrentRoute({ query: { a: 'a' }, preserveQuery: true });

If you pass undefined as the value for a specific query key, then this value will be cleared in a new query:

pageService.navigate({ query: { a: undefined, b: 'b' }, preserveQuery: true });