Router configuration
Learn about configuring the Router-Lite.
The router allows you to configure how it interprets and handles routing in your Aurelia applications. The
customize
method on the RouterConfiguration
object can be used to configure router settings.If you do not provide any configuration value, the default is pushState routing. If you prefer hash-based routing to be used, you can enable this like so:
import Aurelia from 'aurelia';
import { RouterConfiguration } from '@aurelia/router-lite';
Aurelia
.register(RouterConfiguration.customize({ useUrlFragmentHash: true }))
.app(component)
.start();
By calling the
customize
method, you can supply a configuration object containing the property useUrlFragmentHash
and supplying a boolean value. If you supply true
this will enable hash mode. The default is false
.If you are working with pushState routing, you will need a
<base>
element with href
attribute (for more information, refer MDN) in the head of your document. The scaffolded application from the CLI includes this in the index.html
file, but if you're starting from scratch or building within an existing application you need to be aware of this.<head>
<base href="/">
</head>
PushState requires server-side support. This configuration is different depending on your server setup. For example, if you are using Webpack DevServer, you'll want to set the
devServer.historyApiFallback
option to true
. If you are using ASP.NET Core, you'll want to call routes.MapSpaFallbackRoute
in your startup code. See your preferred server technology's documentation for more information on how to allow 404s to be handled on the client with push state.Configuring a base path is useful in many real-life scenarios. One such example is when you are hosting multiple smaller application under a single hosting service. In this case, you probably want the URLs to look like
https://example.com/app1/view42
or https://example.com/app2/view21
. In such cases, it is useful to specify a different base#href
value for every app.<!-- app1/index.html -->
<head>
<base href="/app1">
</head>
<!-- app2/index.html -->
<head>
<base href="/app2">
</head>
Run the following example to understand how the value defined in
base#href
is affecting the URLs.When you open the example in a new browser tab, you can note that the URL in the address bar looks the
HOSTING_PREFIX/app/home
or HOSTING_PREFIX/app/about
. This is also true for the href
values in the a
tags. This happens because <base href="/app">
is used in the index.ejs
(producing the index.html). In this case, the router-lite
is picking up the baseURI
information and performing the routing accordingly.This needs bit more work when you are supporting multi-tenancy for your app. In this case, you might want the URLs look like
https://example.com/tenant-foo/app1/view42
or https://example.com/tenant-bar/app2/view21
. You cannot set the document.baseURI
every time you start the app for a different tenant, as that value is static and readonly, read from the base#href
value.With
router-lite
you can support this by setting the basePath
value differently for each tenant, while customizing the router configuration, at bootstrapping phase. Following is an example that implements the aforementioned URL convention. To better understand, open the the example in a new tab and check the URL in address bar when you switch tenants as well as the links in the a
tags.The actual configuration takes place in the
main.ts
while customizing the router configuration in the following lines of code. // this can either be '/', '/app[/+]', or '/TENANT_NAME/app[/+]'
let basePath = location.pathname;
const tenant =
(!basePath.startsWith('/app') && basePath != '/'
? basePath.split('/')[1]
: null) ?? 'none';
if (tenant === 'none') {
basePath = '/app';
}
const host = document.querySelector<HTMLElement>('app');
const au = new Aurelia();
au.register(
StandardConfiguration,
RouterConfiguration.customize({
basePath,
}),
Registration.instance(ITenant, tenant) // <-- this is just to inject the tenant name in the `my-app.ts`
);
There are also the following links, included in the
my-app.html
, to simulate tenant switch/selection.my-app.html
my-app.ts
tenant: ${tenant}
<nav>
<a href="${baseUrl}/foo/app" external>Switch to tenant foo</a>
<a href="${baseUrl}/bar/app" external>Switch to tenant bar</a>
</nav>
<nav>
<a load="home">Home</a>
<a load="about">About</a>
</nav>
<au-viewport></au-viewport>
import { customElement } from '@aurelia/runtime-html';
import { route } from '@aurelia/router-lite';
import template from './my-app.html';
import { Home } from './home';
import { About } from './about';
import { DI } from '@aurelia/kernel';