Diagnosing Mithril Routing Failures: A Step‑by‑Step Checklist

The Problem: URL Changes Without View Updates

In a typical Mithril single‑page application (SPA), navigating to a new URL should trigger m.route.set or a link that calls it, causing the router to match the path and render the corresponding view. When that doesn’t happen, you’ll see the URL change in the address bar, but the page content remains static. The underlying cause is almost always a router mis‑configuration or an environment mismatch. This guide gives you a structured diagnostic flow to isolate the issue.

Symptom‑to‑Cause Table

Symptom	Likely Cause	Quick Check	Fix
URL changes but view stays the same	Router not initialized before first view render	Check that m.route is called after the DOM is ready	Move m.route init to document.addEventListener('DOMContentLoaded', …)
Console shows m.route is undefined	Missing or corrupted Mithril script	Verify mithril.js loads without 404	Include the correct script tag or bundle path
Routes defined without a leading slash (e.g., home)	Route path mismatch	Inspect route keys in the router object	Prefix all routes with /
App served from a subdirectory but URLs don’t match	Base URL mismatch	Check <base href=\"…\"> or baseURL option	Set baseURL in m.route or add the base tag
Browser history navigation (back/forward) does not update view	History API disabled or overridden	Test window.history.pushState in console	Ensure no global window.onpopstate override and that Mithril runs in HTML5 mode

Ordered Diagnostic Checks

1. Library Presence

   Open the browser console and type m. It should return an object. If it’s undefined, the Mithril script is missing or not loaded.

2. Router Initialization Timing

   Ensure the router starts after the DOM is ready. A common pattern:

   document.addEventListener('DOMContentLoaded', function() {
       m.route(document.body, '/home', {
           '/home': HomeView,
           '/about': AboutView
       });
   });
   

3. Route Definition Syntax

   All keys in the routes object must begin with /. Verify each route:

   {
       '/home': HomeView,
       '/about': AboutView
   }
   

4. Base URL Alignment

   If your app lives under /subdir/, either add a <base> tag or set baseURL:

   m.route(document.body, '/subdir/home', {
       '/home': HomeView,
       '/about': AboutView
   }, {
       baseURL: '/subdir/'
   });
   

5. History API Support

   Run window.history.pushState in console. If it throws or is undefined, the browser or environment blocks the API. In that case, force hash mode:

   m.route(document.body, '/home', {
       '/home': HomeView
   }, {
       hash: true
   });
   

6. View Re‑render Verification

   After clicking a link or calling m.route.set('/about'), open the console and run m.route.get(). It should return /about (or the hashed path).

Common Fixes Tied to Findings

• Missing Script – Add <script src=\"/js/mithril.js\"> or include the bundle in your build pipeline.
• Router Not Started – Wrap m.route in DOMContentLoaded or a module loader callback.
• Incorrect Route Paths – Prefix all routes with / or use relative paths consistently.
• Base URL Issues – Add <base href=\"/subdir/\"> in <head> or supply baseURL in the router options.
• History API Blocked – Switch to hash mode or configure a server‑side fallback that serves index.html for all non‑API routes.
• In‑View Navigation Calls – Move any m.route.set calls out of the view function into an event handler or a controller.

Escalation Criteria

If all the above checks pass but the view still does not update, consider:

• Version mismatch: All modules must import the same Mithril major version. Verify your package.json and build output.
• Custom middleware or server‑side rendering that interferes with the router. Check for any window.onpopstate overrides.
• Stateful components that cache old views. Ensure components return fresh elements on each render.
• Browser extensions or privacy settings that block pushState. Test in a clean profile.

Practical Verification Checklist

1. Open DevTools → Console → m.route returns a function.
2. Navigate to /home and confirm m.route.get() matches the URL.
3. Inspect Network tab: the bundle containing m.route should load without 404.
4. For subdirectory deployments, check the <base> tag or baseURL option in the router init.
5. Trigger back/forward navigation and observe the view change.

Following this diagnostic flow will usually surface the root cause of a Mithril routing failure. Once the issue is fixed, re‑run the verification steps to confirm the view updates correctly after every URL change.