{"id":10556,"library":"backbone.marionette","title":"Backbone.Marionette","description":"Backbone.Marionette, currently at stable version 4.1.3, is a composite application library designed to bring architectural patterns, view management, and memory management to applications built with Backbone.js. It provides a structured approach to developing large-scale single-page applications by offering components like `Application`, `Region`, `View`, and `CollectionView`. While Backbone offers core building blocks, Marionette extends these with sensible defaults, an event-driven architecture via Backbone.Radio, and built-in lifecycle management, including \"zombie-killing\" for views. This specific package (`backbone.marionette`) is currently in maintenance mode, with its development limited to bug fixes. All new feature work for the framework has transitioned to a new, dependency-agnostic `marionette` package (v5+), which no longer relies on Backbone. This `backbone.marionette` package requires Backbone v1.3.3+ and Underscore v1.8.3+ as peer dependencies, ensuring its compatibility within the Backbone ecosystem.","status":"maintenance","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/marionettejs/backbone.marionette","tags":["javascript","backbone","plugin","marionette","composite","architecture","single","page","app"],"install":[{"cmd":"npm install backbone.marionette","lang":"bash","label":"npm"},{"cmd":"yarn add backbone.marionette","lang":"bash","label":"yarn"},{"cmd":"pnpm add backbone.marionette","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for building applications, Marionette extends Backbone's components.","package":"backbone","optional":false},{"reason":"Utility belt dependency, widely used by Backbone and Marionette for various helper functions and templating.","package":"underscore","optional":false}],"imports":[{"note":"For applications using ESM bundlers (e.g., Webpack, Rollup, Parcel), individual Marionette components are typically imported as named exports.","wrong":"import Marionette from 'backbone.marionette';","symbol":"Application, ItemView, etc.","correct":"import { Application, ItemView, Region, CollectionView } from 'backbone.marionette';"},{"note":"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`.","wrong":"const Marionette = require('backbone.marionette');","symbol":"* as Marionette","correct":"import * as Marionette from 'backbone.marionette';"},{"note":"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`.","wrong":"import { Application } from 'backbone.marionette';","symbol":"CommonJS Module / Global","correct":"const Marionette = require('backbone.marionette');"}],"quickstart":{"code":"import { Application, Region, ItemView } from 'backbone.marionette';\nimport Backbone from 'backbone';\nimport _ from 'underscore';\n\n// 1. Create a simple ItemView to display content\nconst MyItemView = ItemView.extend({\n  template: _.template('<h1>Hello, <%= name %>!</h1><p>This is a Marionette ItemView.</p>'),\n  className: 'my-item-view bg-blue-100 p-4 rounded-md shadow-sm',\n\n  initialize(options) {\n    this.model = new Backbone.Model({ name: options.name || 'World' });\n    console.log('ItemView initialized for:', this.model.get('name'));\n  },\n\n  onRender() {\n    console.log('MyItemView rendered with name:', this.model.get('name'));\n  }\n});\n\n// 2. Create a Marionette Application instance\nconst MyApp = Application.extend({\n  // Define a default region for the application to render into\n  region: {\n    el: '#app-hook',\n    replaceElement: true // Replace the target element with the application's view\n  },\n\n  onStart() {\n    console.log('Marionette Application started!');\n    // Show an initial view in the main region\n    this.showView(new MyItemView({ name: 'Marionette User' }));\n\n    // Demonstrate updating the view after a short delay\n    setTimeout(() => {\n      console.log('Updating view after 2 seconds...');\n      this.showView(new MyItemView({ name: 'Updated User' }));\n    }, 2000);\n  },\n\n  // Application-level events can be handled here\n  onBeforeStart() {\n    console.log('Application is about to start...');\n  }\n});\n\n// 3. Ensure the DOM element exists before starting the app\ndocument.addEventListener('DOMContentLoaded', () => {\n  const appContainer = document.createElement('div');\n  appContainer.id = 'app-hook';\n  document.body.appendChild(appContainer);\n\n  // 4. Instantiate and start the application\n  const myApp = new MyApp();\n  myApp.start();\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 4.0.0 introduced significant breaking changes compared to v3.x. Upgrading requires careful review of the migration guide.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Marionette library was not loaded or initialized correctly before being accessed, or its global object is not available in the current scope.","error":"Uncaught ReferenceError: Marionette is not defined"},{"fix":"Verify that `backbone` is loaded before `backbone.marionette` and that `Backbone` is accessible in the scope where Marionette is loaded.","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`).","error":"TypeError: Cannot read properties of undefined (reading 'extend')"},{"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.","cause":"Attempting to instantiate `new View()` without properly importing `View` as a named export from `backbone.marionette`, or accessing it via `Marionette.View`.","error":"Uncaught TypeError: View is not a constructor"},{"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.","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.","error":"Uncaught TypeError: Cannot read properties of null (reading 'showChildView')"}],"ecosystem":"npm"}