Registry / web-framework / vue-web-component-wrapper

vue-web-component-wrapper

JSON →
library1.7.7jsnpmunverified

vue-web-component-wrapper is a Vue 3 plugin that facilitates the creation of reusable web components (custom elements) from full-fledged Vue applications. The current stable version is 1.7.7, with frequent patch and minor releases addressing bug fixes and introducing new features. This library differentiates itself by providing comprehensive support for the broader Vue ecosystem, including seamless integration with state management (Vuex, Pinia), routing (Vue Router), internationalization (Vue I18n), and validation (VeeValidate). It also offers robust compatibility with popular CSS frameworks like Tailwind CSS, Bootstrap, and Vuetify, alongside support for CSS preprocessors and scoped styles. Key features include Shadow DOM encapsulation, Vue DevTools integration, full slot and `v-model` support, event emitting, `provide`/`inject`, and options for fine-grained control over Shadow DOM behavior and CSS styling (e.g., `:root` to `:host` replacement). It also supports async initialization and loader mechanisms.

npm install vue-web-component-wrapper
INSTALL
IMPORT
SIG · VUE-WEB-COMPONENT-
V
vue-web-component-wrapper
web-frameworkjavascriptv1.7.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

wrap
import { wrap } from 'vue-web-component-wrapper';
const wrap = require('vue-web-component-wrapper');
The primary function used to convert a Vue application instance and a Vue component definition into a custom element. This library is ESM-first, so use `import`.
WebComponentWrapperOptions
import type { WebComponentWrapperOptions } from 'vue-web-component-wrapper';
TypeScript type import for configuring the behavior of the `wrap` function. Use `import type` for type-only imports to ensure proper tree-shaking and bundle size optimization.
defineComponent, createApp
import { defineComponent, createApp } from 'vue';
While not directly exported by `vue-web-component-wrapper`, `defineComponent` and `createApp` from the `vue` package are fundamental for creating the Vue component and application instance that this wrapper consumes. These should also be imported using ESM syntax.

This quickstart demonstrates how to define a basic Vue 3 component, create a Vue application instance from it, and then use `vue-web-component-wrapper` to register it as a custom element. It showcases prop passing, event emitting, and slot handling within the web component context.

import { createApp, defineComponent } from 'vue'; import { wrap } from 'vue-web-component-wrapper'; const MyVueComponent = defineComponent({ props: { message: String, count: { type: Number, default: 0 } }, emits: ['increment'], data() { return { internalCount: this.count }; }, methods: { increment() { this.internalCount++; this.$emit('increment', this.internalCount); } }, template: ` <div style="padding: 1rem; border: 1px solid #1a73e8; border-radius: 4px; margin-bottom: 1rem;"> <h3>Hello from Vue Web Component!</h3> <p>Prop Message: <strong>{{ message }}</strong></p> <p>Current Count: <strong>{{ internalCount }}</strong></p> <button @click="increment" style="padding: 8px 16px; background-color: #4CAF50; color: white; border: none; border-radius: 4px; cursor: pointer;">Increment Count</button> <slot name="footer"></slot> </div> `, }); const app = createApp(MyVueComponent); const WebComponent = wrap(app, MyVueComponent, { props: { message: { type: String, default: 'Default Message' }, count: { type: Number, default: 0 } }, emits: ['increment'], // Example of wrapper options disableShadowDOM: false, // Keep Shadow DOM for encapsulation replaceCssRootToHost: true // Essential for :root styles within Shadow DOM }); // Register the custom element in the browser's CustomElementRegistry customElements.define('my-vue-counter', WebComponent); // Example HTML usage: // <my-vue-counter message="Initial Web Component" count="5"></my-vue-counter> // <my-vue-counter message="Another instance with slot content"> // <p slot="footer" style="color: gray; font-size: 0.9em;">This is content for the footer slot.</p> // </my-vue-counter>
Debug
Known issues
gotchaCareful consideration of CSS scoping is required when utilizing or opting to disable Shadow DOM. By default, styles are encapsulated within Shadow DOM, preventing them from affecting the global document. However, if `disableShadowDOM` is set to `true`, component styles may bleed into the global document. Additionally, the `replaceCssRootToHost` option is crucial for correctly scoping `:root` selectors within Shadow DOM, as `:root` otherwise targets the document root.
fix
Understand the implications of `disableShadowDOM` and `replaceCssRootToHost` options on your component's styling. Adjust the wrapper configuration or component styles to achieve the desired encapsulation or global styling behavior, and thoroughly test for style conflicts.
affects: >=1.0.0
gotchaPrior to version 1.7.7, integrating web components created with this wrapper into environments with strict Content Security Policies (CSPs) might have required manual adjustments or led to issues with script and style execution due to the injection of inline styles and scripts. Version 1.7.7 introduced `nonce`/CSP handling to mitigate these problems.
fix
Upgrade to `vue-web-component-wrapper@1.7.7` or newer to leverage the built-in CSP `nonce` handling feature. For projects unable to upgrade, ensure your CSP explicitly permits inline styles and scripts, or implement a custom solution for CSP compatibility.
affects: <1.7.7
gotchaWhile `vue-web-component-wrapper` includes support for Vue DevTools, debugging components encapsulated within a Shadow DOM can be more challenging than in a standard Vue application. Browser developer tools often require specific settings to inspect Shadow DOM content effectively.
fix
Familiarize yourself with your browser's developer tools settings for inspecting Shadow DOM. Utilize the Vue DevTools extension for component-specific debugging, but be prepared for the added layer of encapsulation when inspecting the DOM structure.
affects: *
Errors
Common errors & fixes
Warning: __NO_SIDE_EFFECTS__ after building with vite
During the Vite build process, earlier versions of `vue-web-component-wrapper` could trigger warnings related to `__NO_SIDE_EFFECTS__` due to how the package's module side effects were interpreted.
fix
Upgrade to `vue-web-component-wrapper@1.6.9` or newer, which includes a specific fix addressing this warning when building with Vite.
TypeScript errors when importing package (e.g., 'Cannot find module 'vue-web-component-wrapper' or missing type definitions for exports')
Earlier versions of the package had incomplete or incorrect TypeScript type definitions, leading to compilation errors or warnings in TypeScript projects when importing or using its exports.
fix
Upgrade to `vue-web-component-wrapper@1.6.5` or newer to resolve known TypeScript definition issues and ensure proper type inference and compilation.
Slot content not rendering correctly or unexpectedly disappearing when `disableShadowDOM: true`.
A bug existed in earlier versions that specifically affected the processing of slot content, especially with nested elements, when the `disableShadowDOM` option was enabled, leading to incorrect rendering.
fix
Upgrade to `vue-web-component-wrapper@1.6.11` or newer. This version includes a fix that addresses issues with slot processing and nested elements when Shadow DOM is disabled.
Upgrade
Version history
1.7.7latest on npm
Audit
Dependencies
vuerequiredRequired as a peer dependency to define and build Vue 3 applications that are subsequently wrapped into web components.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
vue-web-component-wrapper — npm install vue-web-component-wrapper · libregistry