Marionette v5 documentation#

These guides target marionette 5.0.0, whose core is independent of Backbone and jQuery. Choose the bundled guides for your installed package and version; applications using legacy backbone.marionette need their own contracts. When upgrading from v4, start with the migration guide.

Choose a starting point#

• New project: quick start for the first render; use the optional progression below as the feature grows.
• Existing application: choose a task or class reference below; follow additional contracts when needed.
• Agent work: task routing and lookup, with optional skill/plugin setup.

Learn as the feature grows#

1. Render a View in a Region.
2. Handle DOM events, then edit local data. A View can save its own model when its data or API layer provides persistence.
3. Add observable data and compose Views with Regions, or display a list. Optional @mnjs/data supplies observation; fetching and persistence require a separate API layer or another data solution.
4. When the feature needs readiness or an independent lifetime, prepare and activate an Application. Retained restart repeats readiness while preserving the shell and local input. Child Applications are started or restarted explicitly. Records brings these pieces together.

Common tasks#

• Migrate from another framework: preserve journeys and design native ownership.
• Migrate from v4: update configuration and lifecycle boundaries.
• Test an application: run interaction, replacement, readiness and teardown checks.
• Use TypeScript: typed options, DOM handlers, state and lifecycle results.
• Edit a View’s own model: live edits, local drafts, and API saves.
• Restart readiness while retaining UI: repeat preparation without rebuilding the shell or draft.
• Add behavior to existing HTML: enhance existing markup and manage its lifetime.
• Integrate with existing UI: mount, communicate, and clean up under another UI owner.
• Connect navigation: synchronous or asynchronous destinations, a retained shell, and browser subscriptions.
• Work with lists: row identity, sorting, filtering, and empty presentation.
• Integrate a control: connect an imperative DOM API to View lifetime.
• Accessibility and rendering: keyboard interaction, focus, and text/HTML boundaries.
• Build and deploy: installed packages, startup ownership, and production delivery checks.

Core reference#

• API index: classes, shared contracts, and current coverage.
• Application: feature readiness, child Applications, root ownership, and restart.
• View: rendering, bindings, child Regions, and lifecycle.
• CollectionView: repeated children, sorting, filtering, and empty presentation.
• Region: showing, replacing, retaining, and destroying Views.
• Behavior: reusable host interactions and lifecycle.
• MnObject: nonvisual state, communication, and cleanup.

Shared contracts and configuration#

• Events, state, common methods, and rendering/View bindings apply across classes.
• Runtime configuration explains setters and configuration scope.
• Rendering/DOM providers and data/state providers define interfaces for supplying integrations.

Companion packages and integration#

• @mnjs/data: Model and Collection: an optional observable data layer with its own operations, events, identity, and disposal. Fetching and persistence require an API layer or another data solution.
• @mnjs/radio: channels and requests: scoped communication, request/reply handlers, and cleanup.
• @mnjs/utils: standalone component and object utilities.
• @mnjs/adapters: optional Backbone, XState, Lit, Morphdom, and jQuery contracts.
• Renderer and data setup: configure Lit and @mnjs/data.

The records source is included for reading alongside the lesson. Its README explains the repository development commands.

Check and debug#

Application tooling sets up lint and TypeScript checks and shows diagnostic lookup. Use errors and diagnostics for the error contract.

Find these docs from an installed package#

From your application's directory:

node -p "require.resolve('marionette/package.json')"

Open docs/readme.md beside that package.json. Follow the relative Markdown links to the reference or lesson you need. This works without a documentation server or framework-specific retrieval tool.