Support for deep-linking (routes)

Deep-linking enables the path part of the URI to indicate a location that should be navigated to.

Tip

This feature is colloquially referred to as routing in the web development world.

Use in Uno Platform applications

Apps using deep-linking typically parse the URI as part of a robust navigation system. No longer is access to resources on discrete pages complicated by repetitive UI steps. Instead, these areas can be navigated directly from a link in an email, a bookmark, or another website. When planning the capabilities of your application, it is essential to decide whether common scenarios necessitate deep-linking.

If so, consider a navigation system that allows mapping route names to specific sectors of UI elements.

Configure deep-linking

This feature is enabled by default in new projects generated from the unoapp template with version 4.9 or later.

When the application is hosted in a subdirectory of the host, set the property to that subdirectory instead, for example /app/ for https://example.com/app/. The value is normalized to a site path with a leading and a trailing /, so app, /app and app/ are equivalent. A value starting with . is kept as a document-relative path, which disables deep-linking. An absolute URL such as https://cdn.example.com/app is kept as written, with a trailing / added.

For project created from older template, add the following parameter to your project file to enable deep-linking:

<PropertyGroup>
  <WasmShellWebAppBasePath>/</WasmShellWebAppBasePath>
</PropertyGroup>

Build-time configuration

This parameter can be configured on build by using a command-line parameter as follows:

dotnet build "-p:WasmShellWebAppBasePath=/"

Behavior

All requests made to the bootstrapper's support files are read from the path specified by the WasmShellWebAppBasePath property. Restrictions are not placed on the depth of the path, so an address like https://example.com/route1/item1 will be supported, assuming that the application is hosted at the root of the host.

One example of such support is done through the Azure Static WebApps support, using navigation fallback:

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/package_*"]
  }
}

Anchor based navigation

When deep-linking is disabled, anchor-based navigation remains supported, as it does not impact the path part of the URI.

See also