Vue Turbolinks Hotwire Adapter

2.2.2 · active · verified Sun Apr 19

vue-turbolinks is a JavaScript package designed to facilitate the integration of Vue.js components into applications that utilize Turbolinks or Hotwire's Turbo. Its primary function is to manage the lifecycle events of Vue components—specifically their proper setup and teardown—within the context of a Turbolinks/Turbo page navigation cycle. This allows developers to incrementally add interactive Vue elements to traditional server-rendered applications without converting them into full Single-Page Applications (SPAs). The current stable version is 2.2.2, with recent minor updates indicating active maintenance. A key differentiator is its explicit focus on solving the challenges of combining Vue's reactivity with Turbolinks'/Turbo's caching mechanisms, making it unsuitable and unnecessary for projects already employing client-side routing libraries like Vue Router.

Common errors

```
NoModificationAllowedError: Failed to set the 'outerHTML' property on 'Element'
```
cause Attempting to destroy a Vue root component whose top-level element is a `<transition>` component during a Turbolinks/Turbo cache event.

fix Wrap your root `<transition>` component in a regular HTML element (e.g., `<div>`) in your Vue component's template.
```
TypeError: Cannot read properties of undefined (reading 'use') when installing globally
```
cause Attempting to use `Vue.use(TurbolinksAdapter)` before Vue is properly imported or globally available.

fix Ensure `import Vue from 'vue';` is present at the top of your file or that Vue is globally exposed before attempting to install the adapter globally. If using Webpack, check your configuration for Vue aliasing.

Warnings

gotcha Do not use `vue-turbolinks` if your application already employs a client-side JavaScript routing library like `vue-router`. This adapter is designed for traditional server-rendered applications enhanced by Turbolinks or Hotwire's Turbo, not for Single-Page Applications (SPAs).
Fix: If using a client-side router, remove `vue-turbolinks` as it provides no benefit and can introduce conflicts. If not using a client-side router, ensure Turbolinks/Turbo is correctly configured.
gotcha When a `$root` Vue component's direct root node is a `<transition>` element, its destruction upon `turbo:before-cache` or `turbolinks:before-cache` can fail with `NoModificationAllowedError`. This is because directly setting `outerHTML` on a Vue transition component's root might not be supported or stable.
Fix: Always wrap Vue `<transition>` components within a standard DOM element (e.g., `<div>`) at the root level of your component's template. For example, instead of `<template><transition>...</transition></template>`, use `<template><div><transition>...</transition></div></template>`.
breaking Prior to v2.2.1, the `turbolinksAdapterMixin` might not have been correctly exported, causing issues when attempting to import it as a named export.
Fix: Upgrade to `vue-turbolinks` version 2.2.1 or higher to ensure the `turbolinksAdapterMixin` named export functions as expected.

Install

npm install vue-turbolinks npm
yarn add vue-turbolinks yarn
pnpm add vue-turbolinks pnpm

Imports

TurbolinksAdapter
wrong:
```
const TurbolinksAdapter = require('vue-turbolinks');
```
correct:
```
import TurbolinksAdapter from 'vue-turbolinks';
```
This is the default export used for global installation via `Vue.use()`.
turbolinksAdapterMixin
wrong:
```
const { turbolinksAdapterMixin } = require('vue-turbolinks');
```
correct:
```
import { turbolinksAdapterMixin } from 'vue-turbolinks';
```
This is a named export for integrating the mixin into individual Vue components via the `mixins` option.
Options for Vue.use()
```
Vue.use(TurbolinksAdapter, { destroyEvent: 'turbo:before-cache' });
```
The global adapter can be configured with an options object, for example, to customize the teardown event.

Quickstart

This quickstart demonstrates how to initialize a Vue component using the `turbolinksAdapterMixin` on a `turbo:load` event, ensuring proper lifecycle management with Hotwire/Turbolinks. It includes a basic Vue component and simulates the DOM changes and events typical in a Turbo application.

import { turbolinksAdapterMixin } from 'vue-turbolinks';
import Vue from 'vue';

// A mock App component for demonstration
const App = {
  template: '<div>Hello from Vue and Turbolinks! Count: {{ count }} <button @click="count++">Increment</button></div>',
  data() {
    return { count: 0 };
  },
  mounted() {
    console.log('App mounted!');
  },
  beforeDestroy() {
    console.log('App beforeDestroy!');
  }
};

document.addEventListener('turbo:load', () => {
  const element = document.getElementById("hello");

  if (element != null) {
    new Vue({
      el: element,
      template: '<App/>',
      mixins: [turbolinksAdapterMixin],
      components: { App }
    });
    console.log('Vue app initialized on turbo:load.');
  } else {
    console.log('No #hello element found, skipping Vue initialization.');
  }
});

// Simulate a Turbolinks/Turbo page load for demonstration
// In a real app, this would be triggered by navigation.
setTimeout(() => {
  const rootDiv = document.createElement('div');
  rootDiv.id = 'hello';
  document.body.appendChild(rootDiv);
  document.dispatchEvent(new Event('turbo:load'));
}, 500);

setTimeout(() => {
  const elementToRemove = document.getElementById('hello');
  if (elementToRemove) {
    elementToRemove.parentNode.removeChild(elementToRemove);
  }
  document.dispatchEvent(new Event('turbo:before-cache')); // Simulate cache event
}, 3000);

view raw JSON →