Mithril Router: Minimal Setup, State Boundaries, and Operational Safeguards

Why a Minimal Router Matters

In a single‑page application (SPA) the router is the glue that keeps the URL, browser history, and view in sync. A lean configuration reduces boilerplate, eases testing, and limits the surface area for bugs. This note walks through the smallest working Mithril router, explains how route state is isolated, and lists checks you should perform in production to guard against common failure modes.

1. The Bare‑Bones Router Initialization

All you need to start routing is a DOM node and a routes object. The call:

m.route(document.body, "/home", {
  "/home": Home,
  "/about": About,
  "/user/:id": User,
  "/404": NotFound
});

does the following automatically:

• Hooks into the browser’s pushState / popstate events.
• Replaces the default location.hash fallback if the History API is present.
• Renders the component that matches the current URL into document.body.

When the page first loads, the router resolves the current URL against the routes map. If no match is found, it falls back to the route defined for /404 (or the first route if none is provided).

2. Route State Boundaries

Each route is a stateless component that receives a vnode object. The router supplies the following to the component:

• attrs – any static attributes you pass in the route definition, e.g., {user: "john"}.
• Dynamic parameters extracted from the URL via m.route.param(name).

Because m.route.param queries the global router state, you should treat dynamic values as read‑only within the component. If a component needs to modify the route (e.g., to redirect), call m.route.set('/new/path') in oninit or an event handler.

Example: Accessing a User ID

var User = {
  oninit: function(vnode) {
    // Fetch data for the user ID in the URL
    var id = m.route.param('id');
    this.user = fetchUser(id);
  },
  view: function() {
    return m("div", [
      m("h1", "User " + this.user.id),
      m("p", this.user.name)
    ]);
  }
};

Because m.route.param is global, you can also use it in helper functions outside the component, but avoid storing it in a shared variable that other routes might overwrite.

3. Operational Checks for Navigation

When building an SPA you must confirm that navigation behaves as expected under various conditions. Here are the practical checks you should run:

1. Initial Load: Verify that m.route renders the default route (/home) when the app is first opened. Use a bookmark or direct URL to ensure deep linking works.
2. Declarative Links: Add an <a href="/about" m.route-link> element and click it. The URL should update without a full page reload, and the About component should appear.
3. Programmatic Navigation: Call m.route.set('/user/42') from a button click or oninit. The view should transition to User and m.route.param('id') should return 42.
4. Fallback Route: Navigate to a non‑existent path, e.g., /nope. The router should render the NotFound component.
5. History API Fallback: Disable pushState in a test environment (e.g., by running in an older browser or by mocking history.pushState to throw). The router should automatically switch to hash URLs (e.g., #/home) and still render the correct component.
6. Error Handling: Throw an error inside oninit of a component. The router should stop navigation and present the default Mithril error overlay. If you have a custom error boundary, ensure it captures the error and logs it.
7. Dynamic Route Loading: Use m.route.buildRoute to load a component asynchronously. Confirm that the component renders after the promise resolves and that navigation still works if the user refreshes the page on that route.

4. Lifecycle Events and Guarding Routes

Mithril emits onbeforeload and onload events that give you hooks to perform analytics or guard access.

m.route(document.body, "/", {
  "/admin": {
    onbeforeload: function() {
      if (!isAuthenticated()) {
        m.route.set('/login');
        return false; // cancel navigation
      }
    },
    view: Admin
  }
});

Use return false in onbeforeload to cancel navigation. If the guard fails, redirect to a login page or show an error message. Remember that onbeforeload runs before the component’s oninit, so you can abort expensive data fetches.

5. Failure Modes and When the Design Should Change

Failure Mode	Symptoms	Remedy
Missing History API	Navigation falls back to hash URLs but URLs contain # when you want clean paths.	Set m.route.mode = 'hash' explicitly or serve a fallback index.html that rewrites all paths to the root.
Dynamic Route Not Found	Deep linking to /user/999 shows a blank page or error overlay.	Ensure /404 is defined and that the component gracefully handles missing data.
Uncaught Exception in oninit	Router stops navigation and shows the error overlay; user sees a broken page.	Wrap data fetches in try/catch, use m.startComputation / m.endComputation for async errors.
Runtime Route Modification	Adding a new route after initialization does nothing.	Re‑initialize the router with m.route or use a custom routing wrapper that supports dynamic addition.

6. Practical Verification Checklist

• Run npm test with a headless browser and assert that m.route.param('id') matches the URL for dynamic routes.
• Use a network proxy to force a 404 on fetch and confirm the NotFound component renders.
• Disable pushState in a test harness and verify the URL updates with a hash.
• Instrument onbeforeload to log analytics events and ensure the event fires before the component renders.

By following this minimal configuration and performing the checks above, you can build a Mithril SPA that is resilient to navigation errors, provides clear route boundaries, and is easy to maintain.