I've opened https://github.com/hotwired/turbo/pull/684, which changes the way that custom actions are defined from directly accessing StreamActions to defining a turbo:before-stream-render event listener.

If that change ships before a 7.2.0 release, this package will need to change how its morphdom integration is defined.

Hey!

Thanks for the lib. I'm reading https://docs.stimulusreflex.com/rtfm/morph-modes to get better understanding of a real world benefits that morphdom brings comparing to typical Turbo.StreamActions (replace/update). Shame on me but I cannot find a good example where morphdom is better than typical stream update/replace action.

Would you be so kind to provide more info on this?

What?

morph() replaces instead of morphs.

Why?

Due to templateContent() returning a DocumentFragment and morphdom not working right with a DocumentFragment. It replaces instead of diffing and morphing like it should.

How?

Pass in a ternary for the new element that if childrenOnly is true passes this.templateContent, else passes this.templateElement.innerHTML. This keeps childrenOnly working as it has no problem with a DocumentFragment but does not work with this.templateElement.innerHTML. And for regular morphs they diff and morph correctly with this.templateElement.innerHTML where templateElement() gets the the template element and innerHTML for the html.

This had come up in the CableReady repo: #58 #67

Came up with a simple file to use @hotwired/turbo-rails so @hotwired/turbo doesn't need imported when using rails. Tested using local turbo-morph.js file with import maps and works great. Took out all initializers and exports as I found they weren't needed. Got a good way to implement in the lib? Also should give ideas to help turbo_power-rails.

turbo-morph.js

import morphdom from "morphdom"
import { Turbo } from "@hotwired/turbo-rails"

Turbo.StreamActions.morph = function() {
  const options = {
    childrenOnly: this.hasAttribute("children-only")
  }

  this.targetElements.forEach(element => {
    morphdom(element, options.childrenOnly ? this.templateContent : this.templateElement.innerHTML, options)
  })
}

application.js

import "@hotwired/turbo-rails"
import "turbo-morph"

A bunch of morphdom alternatives emerged over the past few months. Some of them are very similar to morphdom but each of them has their own nuance.

For now morphdom will stay the default, but there should be an option to replace morphdom with another library fairly easily, so you can chose the best suiting morphing library for your project.

In order to be fully compatible with all approaches turbo-morph is going to support the following morphing libraries:

• morphdom (default)
• @alpinejs/morph
• nanomorph
• micromorph
• idiomorph
• diffhtml
• diff-dom

Current import/initialize

Currently the import and initialize of the library looks like:

import * as Turbo from '@hotwired/turbo'

import TurboMorph from 'turbo-morph'
TurboMorph.initialize(Turbo.StreamActions)

With this Pull Request

If you want to be explicit about what you use (if for some reason turbo-morph is going to change the default in the future) you can rewrite the import-statement like so and everything will continue to work as it did before:

import * as Turbo from '@hotwired/turbo'

import * as TurboMorph from 'turbo-morph/morphdom'
TurboMorph.initialize(Turbo.StreamActions)

But with that you can also easily swap out morphdom with the Alpine plugin if you like:

import * as Turbo from '@hotwired/turbo'

import * as TurboMorph from 'turbo-morph/alpine'
TurboMorph.initialize(Turbo.StreamActions)

Using multiple plugins at the same time:

There might be reasons why you would want to use multiple plugins at the same time. For example if one library is better suited in one place whereas another library is better suited in another place in your application.

import * as Turbo from '@hotwired/turbo'

import { morph as morphdom } from 'turbo-morph/morphdom'
import { morph as nanomorph } from 'turbo-morph/nanomorph'
import { morph as micromorph } from 'turbo-morph/micromorph'

 // Set the one you want to use for `morph` if you still have `morph` Stream Action calls in your application 
Turbo.StreamActions.morph = morphdom

// And register the other ones as their own action
Turbo.StreamActions.morphdom = morphdom
Turbo.StreamActions.nanomorph = nanomorph
Turbo.StreamActions.micromorph = micromorph

Not sure if it's a bug or expected behaviour but having this markup initially on page:

<turbo-frame id="product_list" src="_partials/product/list.html" loading="lazy" target="_top">This is the ORIGINAL product list that is expensive to load on initial page load</turbo-frame>

We cannot issue the following morph:

<turbo-stream action="morph" target="product_list">
  <template
    ><turbo-frame id="product_list"> This is the NEW product list</turbo-frame>
  </template>
</turbo-stream>

The following happens:

1. Morph modifies content of a turbo frame but for some reason it triggers frame reload that in turn reverts original content.