Guidesv5.1.0
Markdown & source details

5.1.0 · stable release (published on npm) · 86ee0599 snapshot. Reading source: 4e5c36d9e8b19ee4dcab2842e3bca6182be0c5a6. Match APIs to your installed version.

On this page

Connect navigation to feature ownership#

Marionette v5 supplies UI and Application lifecycles. Choose browser navigation or a separate router for URL matching and history. Connect route decisions to the owner that shows or starts the destination feature.

Use the optional Router for routed applications#

For a new application needing named URLs, nested feature routes or coordinated route transitions, use optional @mnjs/router with compatible Marionette peers. The HTML-first example uses @mnjs/html; Router works with other renderers too. Router is independently versioned and optional, with its own release cadence. The published example verification records the exact packages used to check this example. Keep an existing host router rather than adding a second global URL owner. The native fragment-navigation alternative remains valid when you do not need a routing package.

Start with the copyable HTML feature below. Read the installed node_modules/@mnjs/router/readme.md and DESIGN.md for version-matched contracts; companion discovery identifies the renderer and larger example paths. No framework checkout is needed.

Use one browser Router and let each RouteApplication declare the routes and children it owns. A mount selects its registered child before dispatching the child's local handler. Keep required data loading in prepareStart, apply the prepared result in onStart, and let Views and Regions own displayed content. The route matcher does not infer ownership from URL nesting. Do not duplicate Application preparation with a separate route-handler loading system.

mountRoutes(router) registers routes but does not activate the root owner. Start independently registered roots before starting the Router; mounted children start through selection. Await router.getInitialDispatch() and handle a failed initial dispatch. For later named navigation, await the returned handle's .finished promise: true means completed, false means cancelled, and failure rejects. Handle rejection at its owner. Changing a mount's own parameters stops and starts the same registered child instance; changing a leaf under the same mount can retain that child. Stop retains registrations; destroy unmounts them. After stop/start, explicitly restart required roots and Router.

The recorded browser run passes on Chromium, Firefox and Playwright WebKit. Those notes identify the tested Router release and describe native WebKit differences. Router requires URLPattern, AbortSignal.any, Promise.withResolvers and URL.canParse; the default driver also requires the Navigation API. historyDriver() is an explicit alternative, not an automatic fallback, and additionally needs structuredClone. Transpilation does not supply these APIs. Follow the installed capability and driver contracts before eagerly constructing a Router. Router's Node minimum is 24.15, independent of core's Node 22 consumer floor. A missing capability is not a reason to silently replace a host's navigation policy.

A minimal HTML feature#

Use this as app.js after the quick start, add @mnjs/router, and keep <div id="app"></div> in the page. Install compatible peers according to the installed Router manifest. This example uses no data provider: plain object snapshots supply each View's template data.

import { Application, View } from 'marionette';
import { Router, RouteApplication } from '@mnjs/router';
import { html } from '@mnjs/html';
import HtmlDomApi from '@mnjs/html/marionette';

const Page = View.extend({
  template: ({ title }) => html`<h1>${title}</h1>`,
}).setDomApi(HtmlDomApi);

const Item = RouteApplication.extend({
  routes: {
    '': { name: 'item', handler: 'showItem' },
    'reviews': { name: 'reviews', handler: 'showReviews' },
  },
  async prepareStart({ id, loadItem }, { signal }) {
    return loadItem(id, { signal });
  },
  onStart(_app, _options, title) { this.title = title; },
  showItem() { this.showView(new Page({ model: { title: this.title } })); },
  showReviews() { this.showView(new Page({ model: { title: `Reviews: ${this.title}` } })); },
});
const Catalog = RouteApplication.extend({
  childApps: { item: Item },
  routes: {
    '/catalog': { name: 'catalog', handler: 'showCatalog' },
    '/catalog/:id': { mount: 'item', namespace: 'catalog' },
  },
  childRouteOptions() { return { loadItem: this.getOption('loadItem') }; },
  showCatalog() { this.showView(new Page({ model: { title: 'Catalog' } })); },
});

export function createApp({ driver, loadItem = async id => `Item ${id}` } = {}) {
  const frame = new Application();
  const router = frame.addChildApp('navigation', new Router({ driver }));
  const catalog = frame.addChildApp('catalog', new Catalog({
    region: { el: '#app' }, loadItem,
  }));
  catalog.mountRoutes(router);
  return {
    frame, router, catalog,
    async start() {
      try {
        if (!await frame.start() || !await catalog.start() || !await router.start()) {
          frame.destroy();
          return { status: 'cancelled' };
        }
        const result = await router.getInitialDispatch();
        if (result.status === 'failed') throw result.error;
        return result;
      } catch (error) {
        frame.destroy();
        throw error;
      }
    },
  };
}

In the browser entry module, import createApp, create it without a driver to use the native Navigation API, and await app.start() inside the host's error boundary. Serve /catalog and /catalog/42 through the same application entry. The initial URL is dispatched by startup. Unmatched URLs have no fallback in this minimal example; choose the host's missing-page policy explicitly.

For an interaction, return or await app.router.navigate('catalog:item', { id: '42' }).finished and handle its rejection. The promise resolves false for cancellation, not success. Keep event handlers in View events/triggers, not template event bindings. Required loading runs in Item preparation once per selected ID; moving to its reviews leaf retains that prepared child. Changing ID reloads it. app.frame.destroy() tears down Router, feature Applications and displayed Views. No manually maintained route-to-View registry or second loader is needed.

The factory's driver argument is an explicit testing/integration seam. For a memory test, import memoryDriver from @mnjs/router and pass memoryDriver({ url: 'https://example.test/catalog/42' }). Await app.start(), navigate to the reviews leaf and a different ID, assert rendered content/loading, then destroy the frame. Memory/History drivers additionally require structuredClone; memory does not remove the package's other capabilities.

The executable companion check runs this exact fence against public npm packages, with the memory driver and a DOM environment, and separately compiles a TypeScript consumer. It is distinct from core's Node 22 checks because Router has a higher Node floor. It does not establish real-browser behavior or benchmark performance.

Alternatives and browser verification#

Keep an existing host router and follow the existing UI boundary. For a small standalone application without a routing package, use the native fragment examples. Do not combine those global listeners with Router. Test direct links, Back/Forward, focus and scroll in a real browser; memory-driver checks do not certify them.