Frontend Routing

Frontend routing is a popular way to switch views in a single-page application. This guide covers recommended approaches for different frontend frameworks when using Wails.

The recommended approach for routing in Vue is Hash Mode:

import { createRouter, createWebHashHistory } from "vue-router";

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    //...
  ],
});

Hash mode uses the URL hash to render different views, avoiding issues with the Wails runtime interfering with routing by using the hash-based URL format.

The recommended approach for routing in Angular is HashLocationStrategy:

RouterModule.forRoot(routes, { useHash: true });

Using hash-based URLs ensures routing works correctly with Wails’ window handling on all platforms.

The recommended approach for routing in React is HashRouter:

import ReactDOM from "react-dom/client";
import { HashRouter, Routes, Route } from "react-router-dom";

ReactDOM.createRoot(root).render(
  <HashRouter basename={"/"}>
    {/* The rest of your app goes here */}
    <Routes>
      <Route path="/" element={<Page0 />} />
      <Route path="/page1" element={<Page1 />} />
      <Route path="/page2" element={<Page2 />} />
      {/* more... */}
    </Routes>
  </HashRouter>
);

HashRouter uses URL hashes instead of paths, which works reliably with Wails across all platforms.

The recommended approach for routing in Svelte is svelte-spa-router:

<script>
    import Router from "svelte-spa-router";
</script>

<Router
    routes={{
        "/": Home,
        "/products": wrap({
            asyncComponent: () => import("./routes/Products.svelte"),
        }),
        "/settings": Settings,
        "*": NotFound,
    }}
/>

svelte-spa-router supports hash-based routing, making it compatible with Wails applications.

Why Hash Routing?

Wails embeds your frontend into a native webview window. Using hash-based routing (#/page instead of /page) avoids conflicts with:

The Wails runtime’s internal routing
Native window URL handling on different platforms
Production assets served from non-root paths

Troubleshooting

If you’re having issues with frontend routing in production builds:

Make sure your frontend build tool is configured to output for hash mode routing
For Vite-based projects, add base: "./" to your vite.config.js
Verify your index.html handles the fallback properly for SPA routing