Routing

Steroids allows you to define a unified routing tree for the entire project, which can be considered a sitemap.

In the project, the tree is usually defined in the routes/index.ts file, where the root route root represents the main page (usually with the address /), and the branches of the tree are defined through items. Each page is described by an object with the IRouteItem interface.

By setting up this route tree, you gain several advantages:

• You can create links by route ID: <Link toRoute='root'>...</Link>.
• You can select a slice of the tree and render navigation based on it: <Nav items='profile'/>.
• Link labels and page titles will be taken from the described route tree.
• The relative path to pages – URL, is only described in the route tree, making it easy to change without refactoring the project.
• Developers can visually see the entire project map by simply opening this file.
• Roles can be specified for routes – roles, to restrict access to a page based on user roles.

An example of a route tree with three pages - the main page and profile pages:

import IndexPage from './IndexPage';
1import ProfileGeneral from './ProfileGeneral';
2import ProfileSettings from './ProfileSettings';
3import { IRouteItem } from '@steroidsjs/core/ui/nav/Router/Router';
4
5export const ROUTE_ROOT = 'root';
6export const ROUTE_PROFILE = 'profile';
7export const ROUTE_PROFILE_GENERAL = 'profile_general';
8export const ROUTE_PROFILE_SETTINGS = 'profile_settings';
9
10export default {
11    id: ROUTE_ROOT,
12    exact: true,
13    path: '/',
14    label: __('Main Page'),
15    component: IndexPage,
16    roles: [null, 'user'], // visible to guests and authenticated users
17    items: {
18        [ROUTE_PROFILE]: {
19            label: __('Profile'),
20            path: '/profile',
21            redirectTo: true,
22            roles: ['user'], // visible only to authenticated users
23            items: {
24                [ROUTE_PROFILE_GENERAL]: {
25                    label: __('General Information'),
26                    path: '/general', // specify only the path segment, the rest will be added from the parent
27                    component: ProfileGeneral,
28                    // roles are not specified here, they are inherited from the parent
29                },
30                [ROUTE_PROFILE_SETTINGS]: {
31                    label: __('Settings'),
32                    path: '/settings',
33                    component: ProfileSettings,
34                },
35            },
36        },
37    },
38} as IRouteItem;

Relative and Absolute Paths

By default, for nested routes, you only need to specify the path segment, and the full path will automatically be formed by appending the parent path segment.

For example:

// src/routes/index.ts
1import {IRouteItem} from '@steroidsjs/core/ui/nav/Router/Router';
2import IndexPage from './IndexPage';
3import LoginPage from './LoginPage';
4import SignUpPage from './SignUpPage';
5
6export const ROUTE_ROOT = 'root';
7
8const roles = [null];
9
10export default {
11    id: ROUTE_ROOT,
12    exact: true,
13    path: '/',
14    component: IndexPage,
15    roles,
16    items: {
17        auth: {
18            exact: true,
19            path: '/auth',
20            roles,
21            items: {
22                login: {
23                    exact: true,
24                    path: '/login', 
25                    roles,
26                    component: LoginPage,
27                }, // LoginPage will be accessible at URL /auth/login
28                signUp: {
29                    exact: true,
30                    path: '/sign-up',
31                    roles,
32                    component: SignUpPage
33                } // SignUpPage will be accessible at URL /auth/sign-up
34            }
35        }
36    }
37} as IRouteItem;

To use a route tree with absolute paths, add the alwaysAppendParentRoutePath flag to routerProps in the Application.tsx file:

// src/Application.tsx
1import useApplication from '@steroidsjs/core/hooks/useApplication';
2
3export default function Application() {
4    const {renderApplication} = useApplication({
5        routerProps: {
6            alwaysAppendParentRoutePath: false, // specify the flag to use absolute paths
7        },
8        /* ... */
9    });
10
11    return renderApplication();
12}

Then, to access the login and registration pages at the same URLs as in the previous example, you need to adjust the route tree structure to:

// src/routes/index.ts
1import {IRouteItem} from '@steroidsjs/core/ui/nav/Router/Router';
2import IndexPage from './IndexPage';
3import LoginPage from './LoginPage';
4import SignUpPage from './SignUpPage';
5
6export const ROUTE_ROOT = 'root';
7
8const roles = [null];
9
10export default {
11    id: ROUTE_ROOT,
12    exact: true,
13    path: '/',
14    component: IndexPage,
15    roles,
16    items: {
17        auth: {
18            exact: true,
19            path: '/auth',
20            roles,
21            items: {
22                login: {
23                    exact: true,
24                    path: '/auth/login', // Specify the absolute path
25                    roles,
26                    component: LoginPage,
27                }, // LoginPage will be accessible at URL /auth/login
28                signUp: {
29                    exact: true,
30                    path: '/auth/sign-up', // Specify the absolute path
31                    roles,
32                    component: SignUpPage
33                } // SignUpPage will be accessible at URL /auth/sign-up
34            }
35        }
36    }
37} as IRouteItem;

Route Settings

The path and exact parameters are passed directly to React Router. You can find their descriptions in the official documentation: React Router.

Name and Label

For each route, you can provide a label and title. The application can decide how to use them, but the initial intention is that label is used for link names, and title is used for page titles (and if not provided, label is used).

Displaying Links in the Navigation Tree

There are situations when you don't want to display a link or button in the navigation to navigate to a route. For example, if you need to add a route for profile settings but not add it to the navigation. For such cases, you can conveniently use the isNavVisible parameter, with a value of false.

Modify the route tree to hide the /settings path in navigation:

/* ... */
1
2export default {
3    id: ROUTE_ROOT,
4    exact: true,
5    path: '/',
6    label: __('Main Page'),
7    component: IndexPage,
8    roles: [null, 'user'],
9    items: {
10        [ROUTE_PROFILE]: {
11            /* ... */
12            items: {
13                /* ... */
14                [ROUTE_PROFILE_SETTINGS]: {
15                    label: __('Settings'),
16                    path: '/settings',
17                    component: ProfileSettings,
18                    isNavVisible: false, // hide the route from navigation
19                },
20            },
21        },
22    },
23} as IRouteItem;

Redirect

To automatically redirect a route to another page, you need to set the redirectTo property, specifying the path to the page.

For example:

// src/routes/index.ts
1import {IRouteItem} from '@steroidsjs/core/ui/nav/Router/Router';
2import IndexPage from './IndexPage';
3import LoginPage from './LoginPage';
4import SignUpPage from './SignUpPage';
5
6export const ROUTE_ROOT = 'root';
7
8const roles = [null];
9
10export default {
11    id: ROUTE_ROOT,
12    exact: true,
13    path: '/',
14    component: IndexPage,
15    roles,
16    items: {
17        auth: {
18            exact: true,
19            path: '/auth',
20            roles,
21            redirectTo: '/auth/login', // Specifies the link to which the user will be automatically redirected when trying to access /auth
22            items: {
23                login: {
24                    exact: true,
25                    path: '/login', 
26                    roles,
27                    component: LoginPage,
28                },
29                signUp: {
30                    exact: true,
31                    path: '/sign-up',
32                    roles,
33                    component: SignUpPage
34                }
35            }
36        }
37    }
38} as IRouteItem;

It is often necessary to redirect to a child page of a section. For example, as in the previous example, to make /auth redirect to /auth/login, where login is one of the child pages of the auth. In such cases, you can set redirectTo to true to redirect to the first child route.

// src/routes/index.ts
1import {IRouteItem} from '@steroidsjs/core/ui/nav/Router/Router';
2import IndexPage from './IndexPage';
3import LoginPage from './LoginPage';
4import SignUpPage from './SignUpPage';
5
6export const ROUTE_ROOT = 'root';
7
8const roles = [null];
9
10export default {
11    id: ROUTE_ROOT,
12    exact: true,
13    path: '/',
14    component: IndexPage,
15    roles,
16    items: {
17        auth: {
18            exact: true,
19            path: '/auth',
20            roles,
21            redirectTo: true, // Note that it is not necessary to specify a link if you want to redirect to the first route in items
22            items: {
23                login: {
24                    exact: true,
25                    path: '/login', 
26                    roles,
27                    component: LoginPage,
28                },
29                signUp: {
30                    exact: true,
31                    path: '/sign-up',
32                    roles,
33                    component: SignUpPage
34                }
35            }
36        }
37    }
38} as IRouteItem;