Registry / web-framework / vue-safe-teleport

vue-safe-teleport

library0.1.2jsnpmunverified

vue-safe-teleport is a utility package for Vue 3 applications that enhances the built-in `<Teleport>` component to prevent common runtime errors related to target availability. It provides `<SafeTeleport>` and `<TeleportTarget>` components, ensuring that content is only teleported once its designated target DOM element is fully mounted and available. The current stable version is `0.1.2`. While the package is relatively new, its recent bug fixes (e.g., v0.1.2 for import extensions) indicate active maintenance. Key differentiators include its explicit `TeleportTarget` component for robust target registration and a fallback single-frame delay when using `SafeTeleport` with a standard DOM selector, directly addressing the "Failed to locate Teleport target with selector" issue that frequently arises from race conditions in component lifecycles. It aims to be a drop-in replacement for `<Teleport>` with added safety.

web-framework

npm install vue-safe-teleport

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-SAFE-TELEPORT

vue-safe-teleport

web-frameworkjavascriptv0.1.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.

VueSafeTeleport

✓ import VueSafeTeleport from 'vue-safe-teleport'

✗ const VueSafeTeleport = require('vue-safe-teleport')

This is the plugin for global registration. `vue-safe-teleport` is an ESM-first package.

SafeTeleport

✓ import { SafeTeleport } from 'vue-safe-teleport'

✗ import SafeTeleport from 'vue-safe-teleport'

SafeTeleport is a named export component. Use it as a drop-in replacement for Vue's built-in <Teleport>.

TeleportTarget

✓ import { TeleportTarget } from 'vue-safe-teleport'

TeleportTarget is a named export component. Use it to explicitly define a teleport target that SafeTeleport will wait for.

This code demonstrates how to install `vue-safe-teleport`, register it as a Vue plugin, and then use both `TeleportTarget` to define a persistent teleport destination and `SafeTeleport` to send dynamic content to it, preventing common "target not found" errors. It also shows using `SafeTeleport` with a standard DOM element, which introduces a single-frame delay if the target isn't immediately present.

// main.js or similar import { createApp } from 'vue'; import App from './App.vue'; import VueSafeTeleport from 'vue-safe-teleport'; const app = createApp(App); app.use(VueSafeTeleport); app.mount('#app'); // App.vue or another component <template> <div> <h1>My Vue App</h1>  <TeleportTarget id="modals" /> <button @click="showModal = true">Open Safe Teleported Modal</button>  <SafeTeleport to="#modals" v-if="showModal"> <div style="background: white; border: 1px solid #ccc; padding: 20px; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1000;"> <h2>Modal Content</h2> <p>This content is teleported securely.</p> <button @click="showModal = false">Close</button> </div> </SafeTeleport>  <SafeTeleport to="#floating-element"> <div style="position: absolute; bottom: 10px; right: 10px; background: lightblue; padding: 5px;"> Floating Message </div> </SafeTeleport> <div id="floating-element" style="position: relative; width: 100px; height: 100px;"></div> </div> </template> <script setup lang="ts"> import { ref } from 'vue'; import { SafeTeleport, TeleportTarget } from 'vue-safe-teleport'; const showModal = ref(false); </script> <style> /* Basic styling for demo */ body { margin: 0; font-family: sans-serif; } #app { padding: 20px; } </style>

Debug

Known issues

gotchaWhen migrating from Vue's native `<Teleport>`, you must replace `<Teleport>` with `<SafeTeleport>`. While props are largely compatible, the underlying behavior for target resolution changes significantly.

fix

Replace `<Teleport to="#id">` with `<SafeTeleport to="#id">`. For best results, also introduce `<TeleportTarget id="id" />` in your root component or layout.

affects: >=0.1.0

gotchaUsing `<SafeTeleport>` without a corresponding `<TeleportTarget>` will still resolve the target, but it will implicitly wait one frame if the target is not immediately available. This introduces a slight delay and might not be suitable for performance-critical scenarios where immediate rendering is expected.

fix

For explicit and immediate target availability, always pair `<SafeTeleport to="#id">` with a `<TeleportTarget id="id" />` component which notifies `SafeTeleport` when it's ready.

affects: >=0.1.0

breakingThe `v0.1.2` release included a fix for `add extensions to imports`. While intended as a bug fix, users on older versions (pre-0.1.2) in strict module environments or specific build setups might encounter module resolution errors when importing components or the plugin.

fix

Upgrade to `vue-safe-teleport@0.1.2` or later. Ensure your build configuration correctly handles ES modules and import paths, especially with file extensions.

affects: <0.1.2

Errors

Common errors & fixes

Failed to locate Teleport target with selector "#my-target"

Vue's native Teleport attempts to render content into a target DOM element that has not yet been mounted or is dynamically added later in the component lifecycle, leading to a race condition.

fix

Replace Vue's `<Teleport>` with `<SafeTeleport>` from `vue-safe-teleport` and ensure a `<TeleportTarget id="my-target" />` component exists and is rendered before `<SafeTeleport>` attempts to mount its content.

Module not found: Error: Can't resolve 'vue-safe-teleport'

Incorrect import path or module resolution issues, potentially due to missing file extensions in imports in older versions or incorrect CJS/ESM interop.

fix

Verify the package is correctly installed (`pnpm i vue-safe-teleport`). Ensure you are using ESM `import` statements (e.g., `import { SafeTeleport } from 'vue-safe-teleport'`) and update to `vue-safe-teleport@0.1.2` or later to leverage import path fixes.

Property 'SafeTeleport' does not exist on type 'typeof import("vue-safe-teleport")' or 'Component is not defined'.

Attempting to use `SafeTeleport` or `TeleportTarget` without explicitly importing them as named exports, or without installing the `VueSafeTeleport` plugin globally if not importing them directly.

fix

For direct component usage, ensure `import { SafeTeleport, TeleportTarget } from 'vue-safe-teleport'` is present. If using the plugin, ensure `app.use(VueSafeTeleport)` is called, which registers them globally.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

vuerequiredRequired peer dependency for a Vue 3 component library.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Akryum/vue-safe-teleport ↗

packagehttps://www.npmjs.com/package/vue-safe-teleport ↗