5.0.0-beta.1 · Published beta · b06750c5. Published on npm. Match your installed version.

Installing Marionette#

Install the core package, show a View, then add the integrations your application needs. Native DOM APIs, plain objects, and function templates work out of the box.

This guide covers the published Marionette 5.0.0-beta.1 package and its matching companion packages.

Documentation Index#

• Install
• Peer dependencies
• Quick start
• TypeScript
• Independent runtimes
• Observable data sources
• Distribution formats
• Backbone is optional
• jQuery DOM adapter is optional
• DOM content adapters are optional
• Current v5 documentation

Install#

The v5 package name is marionette.

npm install marionette@5.0.0-beta.1

The beta is available on npm. Pin this exact version and use the matching documentation. For unreleased changes, build and pack a known source revision separately.

The v4 package name has changed. See the upgrade guide for migration guidance from earlier releases.

Core and @mnjs/data automatically install the matching @mnjs/utils version. Applications do not need a separate install unless they import helpers directly. During prereleases, keep Marionette packages on the same version. See the shared helpers for reusable component helpers.

Peer dependencies#

Marionette v5 core has no peer dependencies. The separate @mnjs/adapters package requires the matching Marionette version and declares the integration-specific peers as optional.

Optional peers are installed only when you opt into them:

# Only if you use the Backbone integration
npm install @mnjs/adapters@5.0.0-beta.1 backbone

# Only if you use the jQuery DomApi adapter
npm install @mnjs/adapters@5.0.0-beta.1 jquery

# Only if you use XState actors
npm install @mnjs/adapters@5.0.0-beta.1 xstate

The XState actor adapter does not import or declare XState as a peer. Install XState alongside the adapter; the adapter consumes its public actor shape.

Npm does not install missing optional peers. TypeScript consumers of an optional subpath must install its matching type package explicitly:

# Only if TypeScript imports @mnjs/adapters/backbone
npm install --save-dev @types/backbone@^1.4.23

# Only if TypeScript imports @mnjs/adapters/dom/jquery
npm install --save-dev @types/jquery@^4.0.1

Marionette core does not import or require Underscore. Install it as an application dependency only when your own code uses it, such as an _.template used by a View.

Quick start#

Marionette v5 exposes its public API through named ESM imports. There is no default-namespace export; use named imports only. Add a mount element to the page before running the module:

<div id="app"></div>

import { Application, View } from 'marionette';

const RootView = View.extend({
  template: () => '<div>Hello, Marionette.</div>'
});

const app = new Application({
  region: document.getElementById('app'),
  onStart() {
    this.showView(new RootView());
  }
});

await app.start();

View and CollectionView accept a DOM element for el. They do not resolve selector strings — pass document.querySelector('#root') at the call site. See the upgrade guide for the migration entry. Region continues to accept selector strings.

TypeScript#

Marionette 5.0.0-beta.1 includes declarations for TypeScript 6 and 7, with ESM and CommonJS entrypoints. Core needs no separate @types package. Annotate initialize to describe a View's application options; TypeScript uses that signature to check construction and this.options.

import { View } from 'marionette';

const MessageView = View.extend({
  template: false,
  initialize(options: { message: string }) {
    this.el.textContent = options.message;
  },
  message(): string {
    return this.options.message;
  }
});

const view = new MessageView({ message: 'Hello, Marionette.' });
document.body.append(view.render().el);

This View requires a string message. Missing options or a numeric message are compile errors. template: false preserves the text set during initialization.

Named imports work with NodeNext or bundler module resolution. The consumer TypeScript guide covers application options, DOM events, module resolution, and inheritance choices. Optional integrations may need their own type packages, listed above.

Independent runtimes#

The named root exports form one default runtime. Use createMarionette() only when independent applications in the same process need isolated classes, adapters, renderer configuration, or Radio channels:

import { createMarionette } from 'marionette';

const isolated = createMarionette();
const IsolatedView = isolated.View.extend({ template: () => 'Independent' });

See Runtime isolation for composition and ownership rules.

Observable data sources#

Core's default DataApi supports plain objects and static arrays without a required dependency. Backbone Models and Collections are observable sources too; retain them through the Backbone adapter when the application already uses them. For a new application needing observable Model and ordered Collection sources, the optional @mnjs/data package is the native choice:

npm install @mnjs/data@5.0.0-beta.1

Configure its adapters before constructing owners. See the @mnjs/data guide for a complete adapter setup and rendered list example.

Applications using XState actors can select an ordered array of child actor references through @mnjs/adapters/xstate. See XState actors.

Distribution formats#

ES modules are the canonical path for new applications. Use import syntax so package export conditions select the ESM entry, and use Marionette's named exports.

Marionette also ships compatibility distributions throughout v5:

• CommonJS supports legacy Node and build-tool consumers through require('marionette').
• Unminified and minified UMD builds support no-bundler, AMD, and Marionette-global consumers.

All four ESM, CommonJS, unminified UMD, and minified UMD outputs remain supported and distribution-validated for v5. Marionette will not add another format or switch to unbundled source modules without measured consumer benefit. Six months after v5.0.0 is published, the distribution review is an evidence checkpoint for a future major version, not a removal commitment.

Backbone is optional#

Starting with v5, Marionette core does not depend on Backbone at runtime. Plain objects and arrays use the default DataApi. Applications passing Backbone Models or Collections to Marionette must configure the Backbone DataApi before constructing those consumers:

import BackboneApi from '@mnjs/adapters/backbone';
import { setDataApi } from 'marionette';

setDataApi(BackboneApi);

This configures model and collection use. Select the StateApi role separately when an owner uses Backbone state; see Optional Backbone. Data API describes the neutral runtime contract.

jQuery DOM adapter is optional#

Marionette v5 core is jQuery-free. The default DOM API uses native browser methods, and view.$(selector) returns a NodeList.

Applications that want jQuery-shaped results from Marionette's DOM helpers — for example, view.$(selector) returning a jQuery collection — can opt into the optional @mnjs/adapters/dom/jquery adapter at app boot:

import { setDomApi } from 'marionette';
import JQueryDomApi from '@mnjs/adapters/dom/jquery';

setDomApi(JQueryDomApi);

The adapter imports jquery, so this integration requires jquery only when you select that adapter. If existing code also uses $el, assign this.$el = $(this.el) in its View, CollectionView, or Behavior initialize() method. See the upgrade guide for the migration entries on jQuery DOM compatibility and the detachContents policy.

DOM content adapters are optional#

Use the same @mnjs/adapters package for incremental rendering. Install only the DOM library you select:

npm install @mnjs/adapters@5.0.0-beta.1 morphdom
# or
npm install @mnjs/adapters@5.0.0-beta.1 lit-html

Import MorphdomDomApi from @mnjs/adapters/dom/morphdom, or LitDomApi from @mnjs/adapters/dom/lit-html, and pass it to ViewClass.setDomApi() before creating instances. Each adapter preserves unrelated DOM operations. Lit supplies the attachment hooks its directives need. DataApi and StateApi configuration remains explicit and separate.

See Rendering to DOM for examples and lifecycle requirements.

Getting Started#

Choose a class for the job, or learn the shared configuration patterns.