Piral Vue 3 Plugin

Common errors

• Error: Hydration completed but contains mismatches.

  cause This error typically occurs in SSR (Server-Side Rendering) scenarios where the client-side rendered content doesn't exactly match the server-generated HTML, often due to dynamic content or client-only side effects.
  fix Ensure that your Vue 3 pilet and the Piral shell handle SSR correctly. If using `piral-vue-3` in an SSR context, make sure data fetching is completed before hydration and that client-specific code runs only in the browser environment. For client-only rendering, this error might indicate late-loaded content that causes DOM changes.

• Cannot read properties of undefined (reading '$root')

  cause This error often indicates that a Vue component is trying to access `$root` or other instance properties that might not be available in a non-Vue context or when the component is not properly mounted or provided with a root instance.
  fix Verify that your Vue 3 component is correctly registered and mounted by the `piral-vue-3` plugin. Ensure that any Piral-specific API extensions (e.g., `app.foo()`) are accessed through the `PiletApi` provided to the `setup` function and not via Vue's internal mechanisms unless explicitly passed down.

• Failed to resolve component: [ComponentName]

  cause The Vue 3 component specified in `app.registerPage` or `app.registerTile` could not be found or imported correctly within the pilet's context.
  fix Double-check the import path and name of your Vue component. Ensure it's correctly exported from its module and that your pilet's build process correctly bundles it. If using lazy loading, verify the dynamic import syntax and path.

Warnings

• gotcha When developing Vue 3 pilets, ensure that your pilet's `package.json` correctly defines `vue` as a peer dependency and that the Piral shell provides it. Mismatched Vue versions between the shell and pilet, or a pilet bundling its own Vue runtime when it shouldn't, can lead to runtime errors or increased bundle sizes.
  Fix: Configure your pilet's `package.json` to declare `vue` as a `peerDependency`. Ensure your Piral shell is configured to provide `vue` as a shared dependency or that the `piral-vue-3` plugin handles its provisioning. Check bundler configurations (e.g., Webpack externals, Vite build options) for proper exclusion/sharing.
• breaking The `piral-vue-3` plugin is specifically designed for Vue 3. Using it with Vue 2 projects or attempting to mix Vue 2 and Vue 3 pilets without explicit support or isolation mechanisms can lead to runtime failures due to incompatible APIs and rendering contexts.
  Fix: For Vue 2 projects, use `piral-vue` (the Vue 2 specific plugin). Ensure all Vue pilets within a Piral instance target the same major version of Vue to avoid framework conflicts.
• gotcha Vue 3 components registered via `piral-vue-3` operate within the Piral application's lifecycle. Improper cleanup of Vue instances or event listeners within a pilet's `teardown` function can lead to memory leaks, especially when pilets are dynamically loaded and unloaded frequently.
  Fix: Always implement a `teardown` function in your pilet's `setup` method. Ensure that any global event listeners, timers, or Vue instances created by your pilet are properly destroyed or unmounted within this `teardown` to release resources.

Install

• npm install piral-vue-3 npm
• yarn add piral-vue-3 yarn
• pnpm add piral-vue-3 pnpm

Imports

• createVue3Api
  wrong:

  const { createVue3Api } = require('piral-vue-3');

  correct:

  import { createVue3Api } from 'piral-vue-3';

  Used to create the Piral API extension for Vue 3 pilets. Piral packages are primarily ESM-first.
• Vue3PiletApi
  wrong:

  import { Vue3PiletApi } from 'piral-vue-3';

  correct:

  import type { Vue3PiletApi } from 'piral-vue-3';

  This is a type definition for extending the Pilet API with Vue 3 specific functionalities. Import it using `type` for clarity and to avoid bundling issues.
• defineVue3Pilet
  wrong:

  import defineVue3Pilet from 'piral-vue-3';

  correct:

  import { defineVue3Pilet } from 'piral-vue-3';

  A utility function to define a Vue 3 pilet, simplifying component registration and lifecycle management.

Quickstart

This quickstart demonstrates how to initialize a Piral application with the `piral-vue-3` plugin and register a simple Vue 3 component as a pilet page. It sets up a basic Piral factory, includes the Vue 3 plugin, and shows how a mock pilet could register a Vue component route.

import { Piral, createPiralFactory } from 'piral';
import { createVue3Api } from 'piral-vue-3';
import { createApp, defineComponent } from 'vue';

const MyVueComponent = defineComponent({
  template: '<div>Hello from Vue! Count: {{ count }}</div>',
  data() {
    return { count: 0 };
  },
  mounted() {
    setInterval(() => {
      this.count++;
    }, 1000);
  }
});

const piralApp = createPiralFactory({
  requestPilets() {
    return Promise.resolve([
      {
        name: 'my-vue-pilet',
        version: '1.0.0',
        spec: 'v1',
        hash: 'abc',
        dependencies: {},
        setup(app) {
          app.registerPage('/vue-page', MyVueComponent);
          app.showNotification('Vue Pilet Loaded!', { autoClose: 2000 });
        }
      }
    ]);
  },
  plugins: [createVue3Api()]
});

// In a real Piral application, the Piral instance would be mounted to a DOM element.
// For demonstration, we'll just show the setup.
// Piral renders its components into a designated DOM container.
// For a full Piral app, this would be `render(<Piral instance={piralApp} />, document.querySelector('#app'))`.

console.log('Piral app with Vue 3 plugin initialized.', piralApp);
// Simulate a Piral app mounting cycle if needed for full execution context.
// In a browser environment, you'd mount `<Piral instance={piralApp} />` into your root element.