Registry / web-framework / vue-turbolinks

vue-turbolinks

JSON →
library2.2.2jsnpmunverified

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.

npm install vue-turbolinks
INSTALL
IMPORT
SIG · VUE-TURBOLINKS
V
vue-turbolinks
web-frameworkjavascriptv2.2.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TurbolinksAdapter
✓ import TurbolinksAdapter from 'vue-turbolinks';
✗ const TurbolinksAdapter = require('vue-turbolinks');
This is the default export used for global installation via `Vue.use()`.
turbolinksAdapterMixin
✓ import { turbolinksAdapterMixin } from 'vue-turbolinks';
✗ const { turbolinksAdapterMixin } = require('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.

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);
Debug
Known issues
gotchaDo 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.
affects: >=1.0.0
gotchaWhen 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>`.
affects: >=1.0.0
breakingPrior 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.
affects: <2.2.1
Errors
Common errors & fixes
NoModificationAllowedError: Failed to set the 'outerHTML' property on 'Element'
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
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.
Upgrade
Version history
2.2.2latest on npm
Audit
Dependencies
vuerequiredRequired for the mixin functionality, as vue-turbolinks is an adapter for Vue.js components.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
vue-turbolinks — npm install vue-turbolinks · libregistry