Backbone.Marionette

Common errors

• Uncaught ReferenceError: Marionette is not defined

  cause The Marionette library was not loaded or initialized correctly before being accessed, or its global object is not available in the current scope.
  fix Ensure `backbone.marionette` is included in your project via a script tag (making `Marionette` global) or correctly imported/required via a module loader/bundler.

• TypeError: Cannot read properties of undefined (reading 'extend')

  cause This error typically occurs if Backbone.js is not loaded or available before Marionette attempts to extend its components (e.g., `Marionette.View.extend`).
  fix Verify that `backbone` is loaded before `backbone.marionette` and that `Backbone` is accessible in the scope where Marionette is loaded.

• Uncaught TypeError: View is not a constructor

  cause Attempting to instantiate `new View()` without properly importing `View` as a named export from `backbone.marionette`, or accessing it via `Marionette.View`.
  fix Use `import { View } from 'backbone.marionette';` (or `ItemView`, `CollectionView`, etc.) or ensure you are referencing the component correctly as `Marionette.View` if using a namespace import or global object.

• Uncaught TypeError: Cannot read properties of null (reading 'showChildView')

  cause This often happens when a `Region` is not properly initialized or its `el` (the DOM element it manages) does not exist in the document when `showChildView` is called.
  fix Ensure the DOM element specified in the `Region`'s `el` property exists in the HTML document before the Marionette Application starts or the `Region` attempts to render.

Warnings

• breaking Version 4.0.0 introduced significant breaking changes compared to v3.x. Upgrading requires careful review of the migration guide.
  Fix: Consult the official upgrade guide from v3 to v4: `https://marionettejs.com/docs/v4.0.0/upgrade-v3-v4.html` to understand necessary code adaptations.
• deprecated The `backbone.marionette` package (v4.x) is now in maintenance mode, limited to bug fixes. All new feature development for the Marionette framework has transitioned to a new, standalone `marionette` package (v5+), which has dropped its dependency on Backbone.js.
  Fix: For new projects or significant feature development, consider migrating to the standalone `marionette` package (v5+) to leverage active development and a future-proof architecture. Existing `backbone.marionette` projects should be aware of the limited future development.
• gotcha Incorrect or missing peer dependencies for `backbone` and `underscore` will lead to runtime errors due to Marionette's deep reliance on their presence and specific APIs.
  Fix: Ensure `backbone` (`^1.3.3`) and `underscore` (`^1.8.3`) are correctly installed and available in your project's `node_modules` and runtime environment.
• gotcha While Marionette provides built-in memory management and "zombie-killing" for views, improper manual event binding (e.g., to global objects or DOM elements outside the view's `el` without corresponding unbinding) can still lead to memory leaks.
  Fix: Always utilize Marionette's `this.listenTo()` for model/collection events and `this.delegateEvents()` for DOM events. Ensure `View.destroy()` is called when a view is removed, and avoid direct `$(window).on()` or `Backbone.Events.on()` without corresponding `off()` calls managed by the view's lifecycle.

Install

• npm install backbone.marionette npm
• yarn add backbone.marionette yarn
• pnpm add backbone.marionette pnpm

Imports

• Application, ItemView, etc.
  wrong:

  import Marionette from 'backbone.marionette';

  correct:

  import { Application, ItemView, Region, CollectionView } from 'backbone.marionette';

  For applications using ESM bundlers (e.g., Webpack, Rollup, Parcel), individual Marionette components are typically imported as named exports.
• * as Marionette
  wrong:

  const Marionette = require('backbone.marionette');

  correct:

  import * as Marionette from 'backbone.marionette';

  This namespace import provides all Marionette exports under a single object. Components are accessed as `Marionette.Application`, `Marionette.ItemView`, etc. The `require` style might return a different module object depending on the build configuration compared to the global `window.Marionette`.
• CommonJS Module / Global
  wrong:

  import { Application } from 'backbone.marionette';

  correct:

  const Marionette = require('backbone.marionette');

  In CommonJS environments (e.g., Node.js or older browserify/webpack setups), `require()` loads the library. When loaded directly via a `<script>` tag in the browser, `Marionette` typically becomes a global object on `window`.

Quickstart

This quickstart demonstrates how to create a basic Marionette Application, define a Region, instantiate an ItemView with a simple template, and display it within the application's region. It also shows how to update the view dynamically.

import { Application, Region, ItemView } from 'backbone.marionette';
import Backbone from 'backbone';
import _ from 'underscore';

// 1. Create a simple ItemView to display content
const MyItemView = ItemView.extend({
  template: _.template('<h1>Hello, <%= name %>!</h1><p>This is a Marionette ItemView.</p>'),
  className: 'my-item-view bg-blue-100 p-4 rounded-md shadow-sm',

  initialize(options) {
    this.model = new Backbone.Model({ name: options.name || 'World' });
    console.log('ItemView initialized for:', this.model.get('name'));
  },

  onRender() {
    console.log('MyItemView rendered with name:', this.model.get('name'));
  }
});

// 2. Create a Marionette Application instance
const MyApp = Application.extend({
  // Define a default region for the application to render into
  region: {
    el: '#app-hook',
    replaceElement: true // Replace the target element with the application's view
  },

  onStart() {
    console.log('Marionette Application started!');
    // Show an initial view in the main region
    this.showView(new MyItemView({ name: 'Marionette User' }));

    // Demonstrate updating the view after a short delay
    setTimeout(() => {
      console.log('Updating view after 2 seconds...');
      this.showView(new MyItemView({ name: 'Updated User' }));
    }, 2000);
  },

  // Application-level events can be handled here
  onBeforeStart() {
    console.log('Application is about to start...');
  }
});

// 3. Ensure the DOM element exists before starting the app
document.addEventListener('DOMContentLoaded', () => {
  const appContainer = document.createElement('div');
  appContainer.id = 'app-hook';
  document.body.appendChild(appContainer);

  // 4. Instantiate and start the application
  const myApp = new MyApp();
  myApp.start();
});