Piral Vue 2 Plugin

Common errors

• TypeError: Cannot read properties of undefined (reading 'extend')

  cause This error typically occurs when a Vue 3 component or API is mistakenly used within a Vue 2 context (or vice versa), or when Vue 2 is not properly loaded/available. The `extend` method is specific to Vue 2's component definition.
  fix Verify that `vue@^2.x` is correctly installed in your pilet's `package.json` and that your component definitions strictly adhere to the Vue 2 API. If you intend to use Vue 3, switch to `piral-vue3` instead of `piral-vue`.

• Failed to mount component: template or render function not defined.

  cause This common Vue 2 error indicates that the component object passed to `app.fromVue()` is missing either a `template` string or a `render` function, both of which are essential for Vue to render the component.
  fix Ensure your Vue 2 component definition includes either a `template` property (as a string) or a `render` function. Double-check for any syntax errors in your component's options object or if a build step (like a Vue loader) failed to process the component correctly.

Warnings

• breaking This `piral-vue` package is strictly designed for Vue 2.x applications. Attempting to use it with Vue 3.x or newer will result in runtime errors due to significant API changes between Vue major versions.
  Fix: For Vue 3 projects, use the dedicated `piral-vue3` package. Ensure your Pilet's `package.json` specifies `vue@^2.x` and that your Piral instance is consistently configured for Vue 2.
• gotcha Vue components registered through `piral-vue` operate within isolated contexts. Relying on global Vue instances or directly modifying globally shared state (e.g., a single Vuex store) across multiple pilets can lead to unpredictable behavior, state collisions, or memory leaks.
  Fix: Utilize Piral's built-in event bus (`app.on(...)`, `app.emit(...)`) or Piral's global state management (`app.readState(...)`, `app.updateState(...)`) for communication and state sharing between pilets. Each Vue Pilet should manage its own local Vuex store if needed.
• gotcha While Vue components often use scoped CSS, integration into a microfrontend shell can still lead to styling conflicts. Global styles from the Piral shell or other pilets might unintentionally affect Vue 2 components, and vice-versa.
  Fix: Employ robust CSS methodologies like BEM within your Vue components, use CSS Modules, or leverage Piral's built-in CSS isolation features (if available). Regularly review generated CSS to prevent unintended style bleed, and consider using shadow DOM for stricter encapsulation.

Install

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

Imports

• createVueApi
  wrong:

  const createVueApi = require('piral-vue');

  correct:

  import { createVueApi } from 'piral-vue';

  This function is used in your Piral instance's `createInstance` plugins array to enable Vue 2 support for pilets. Piral primarily uses ESM.
• PiletVueApi
  wrong:

  import { PiletVueApi } from 'piral-vue';

  correct:

  import type { PiletVueApi } from 'piral-vue';

  This TypeScript interface extends the standard PiletApi with Vue 2-specific functions like `fromVue`. Use `import type` for type-only imports to avoid bundling type definitions.
• VueComponent
  wrong:

  import { VueComponent } from 'vue';

  correct:

  import type { VueComponent } from 'piral-vue';

  Refers to the Piral-specific wrapper type for Vue components, ensuring correct integration into the microfrontend context. This is not the raw Vue component constructor directly from the `vue` package.

Quickstart

Demonstrates how a Pilet uses `piral-vue` to define and register a Vue 2 component as both a Piral extension and a full page. This quickstart assumes `piral-vue` has been configured in the main Piral instance.

import type { PiletApi } from 'piral';
import { defineComponent } from 'vue'; // Ensure vue@2 is a dependency in your pilet

// Extend PiletApi with piral-vue specific functions provided by the Piral instance.
// This assumes 'piral-vue' has been configured in the Piral instance's createInstance call.
interface MyPiletApi extends PiletApi {
  fromVue(component: any): any; // The actual type is VueComponentConverter<VueComponent>
}

// Define a simple Vue 2 component
const MyVueComponent = defineComponent({
  name: 'MyVueComponent',
  props: {
    message: {
      type: String,
      default: 'Hello from Vue 2 Pilet!',
    },
  },
  template: `
    <div style="padding: 10px; border: 1px solid #42b983; margin: 10px; border-radius: 5px;">
      <h3>{{ message }}</h3>
      <p>This is a Vue 2 component served by a Pilet.</p>
      <button @click="increment">Count: {{ count }}</button>
    </div>
  `,
  data() {
    return {
      count: 0,
    };
  },
  methods: {
    increment() {
      this.count++;
    },
  },
});

/**
 * The setup function for the Pilet.
 * It registers a Vue component as an extension and a page within the Piral application.
 */
export function setup(app: MyPiletApi) {
  // Register the Vue component as an extension.
  // It can be embedded anywhere in the Piral app using <Extension name="vue-pilet-card" />.
  app.registerExtension('vue-pilet-card', app.fromVue(MyVueComponent));

  // Register the Vue component as a full page, accessible via a route.
  app.registerPage('/vue-pilet-page', app.fromVue(MyVueComponent));

  console.log('Vue 2 Pilet: MyVueComponent registered as extension "vue-pilet-card" and page "/vue-pilet-page".');
}