Vue Shadow DOM Integration

Common errors

• Failed to resolve component: shadow-root

  cause The `vue-shadow-dom` plugin has not been correctly registered with the Vue application instance, meaning its components and directives are not globally available.
  fix After creating your Vue application with `createApp()`, ensure you register the plugin by calling `app.use(shadow)` before mounting the application, e.g., `const app = createApp(MyRootComponent); app.use(shadow); app.mount('#app');`

• TypeError: app.use is not a function

  cause This error typically indicates that `app` is not a valid Vue 3 application instance. This can happen if you are using Vue 2's `new Vue()` API instead of Vue 3's `createApp()` or if `app` is otherwise undefined.
  fix Confirm that your application entry point uses `createApp()` to initialize your Vue 3 application. If you are targeting Vue 2, you must use `vue-shadow-dom@1` and its corresponding initialization method for Vue 2 plugins.

Warnings

• breaking Version 2.0 and higher of `vue-shadow-dom` are exclusively built for Vue 3. Attempting to use these versions with Vue 2 applications will result in runtime errors due to significant API changes.
  Fix: For Vue 2 projects, you must install `vue-shadow-dom@1` using `npm i vue-shadow-dom@1`. Always verify your project's Vue version aligns with the compatible library version.
• gotcha Using the `abstract` prop on `<shadow-root>` attaches the shadow root directly to the host element. This makes other external sibling HTML tags within the same host element unavailable or unrenderable inside the Shadow DOM, which can lead to unexpected layout or missing content.
  Fix: Carefully consider the implications of `abstract`. If you need sibling content to render alongside the shadow root or to be styled by global styles, avoid using `abstract`. The default behavior without `abstract` creates an intermediate `div` for the shadow root, allowing siblings to coexist.
• gotcha Importing the incorrect distribution file (e.g., a bundler-specific ESM build directly in a browser without a module loader, or a UMD build in a modern bundler setup) can cause module resolution failures or runtime errors.
  Fix: Consult the 'Files' section in the `vue-shadow-dom` README. Ensure you are importing the correct build artifact for your specific environment: `shadow.esm-bundler.mjs` for packaging tools, `shadow.esm-browser.mjs` for browser ESM, `shadow.global.js` for UMD, and `shadow.cjs.cjs` or the main `vue-shadow-dom` package for Node.js CommonJS.

Install

• npm install vue-shadow-dom npm
• yarn add vue-shadow-dom yarn
• pnpm add vue-shadow-dom pnpm

Imports

• shadow
  wrong:

  import { shadow } from 'vue-shadow-dom'

  correct:

  import shadow from 'vue-shadow-dom'

  This is the default export representing the Vue plugin instance. For CommonJS environments, `const shadow = require('vue-shadow-dom')` can be used directly or specific CJS build paths like `'vue-shadow-dom/dist/shadow.cjs.cjs'`.
• ShadowRootExpose

  import type { ShadowRootExpose } from 'vue-shadow-dom'

  Used for TypeScript users to type the exposed `shadow_root` property when accessing the native ShadowRoot instance from a `<shadow-root>` component ref.

Quickstart

Demonstrates initializing the `vue-shadow-dom` plugin, using the `<shadow-root>` component with custom tag and abstract prop, applying encapsulated styles with `<shadow-style>`, and accessing the native ShadowRoot instance via a ref for direct DOM interaction.

import { createApp, ref, defineComponent } from 'vue';
import shadow, { type ShadowRootExpose } from 'vue-shadow-dom';

const MyShadowComponent = defineComponent({
  template: `
    <div style="border: 1px solid blue; padding: 10px; margin: 20px;">
      <h2>Component Host</h2>
      <p>Content outside the shadow root. Styles here will leak unless encapsulated.</p>
      <shadow-root ref="shadowRef" tag="section" abstract>
        <template #default>
          <shadow-style>
            p { color: green; font-weight: bold; }
            h3 { color: darkred; }
            button { background-color: lightblue; padding: 8px; border: none; cursor: pointer; }
          </shadow-style>
          <h3>Shadow Root Content</h3>
          <p>This paragraph should be green and bold inside the shadow DOM.</p>
          <button @click="logShadowRoot">Log Shadow Root</button>
        </template>
      </shadow-root>
      <p>This paragraph is outside the shadow root.</p>
    </div>
  `,
  setup() {
    const shadowRef = ref<ShadowRootExpose | null>(null);

    const logShadowRoot = () => {
      if (shadowRef.value && shadowRef.value.shadow_root) {
        console.log('Shadow Root Instance:', shadowRef.value.shadow_root);
        // You can interact with the native ShadowRoot object directly
        const pElement = shadowRef.value.shadow_root.querySelector('p');
        if (pElement) {
          console.log('Paragraph inside shadow root:', pElement.textContent);
        }
      } else {
        console.warn('ShadowRoot instance not available yet.');
      }
    };

    return { shadowRef, logShadowRoot };
  },
});

const app = createApp(MyShadowComponent);
app.use(shadow);
app.mount('#app');

// To run this, you would typically have an index.html like:
// <div id="app"></div>