{"id":11557,"library":"piral-vue-3","title":"Piral Vue 3 Plugin","description":"piral-vue-3 is a plugin designed to seamlessly integrate Vue 3 components within a Piral microfrontend application. It enables developers to build 'pilets' (microfrontends) using Vue 3, which can then be dynamically loaded and rendered by a Piral instance (the 'shell' application). The current stable version is 1.10.3, with minor point releases occurring frequently, typically addressing dependency updates, bug fixes, and improvements across the Piral ecosystem. Key differentiators include its tight integration with the Piral Pilet API, allowing Vue 3 components to leverage the Piral communication layer and shared services, and its focus on enabling a multi-framework approach within a single microfrontend host. It abstracts away the complexities of mounting and unmounting Vue 3 applications within the Piral lifecycle, providing a robust solution for incorporating Vue 3 into larger, heterogeneous microfrontend architectures.","status":"active","version":"1.10.3","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral","tags":["javascript","piral","pilet-api","smapiot","portal","modules","api","plugin","plugin-converter","typescript"],"install":[{"cmd":"npm install piral-vue-3","lang":"bash","label":"npm"},{"cmd":"yarn add piral-vue-3","lang":"bash","label":"yarn"},{"cmd":"pnpm add piral-vue-3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Piral framework, required to host Vue 3 pilets.","package":"piral","optional":false},{"reason":"Runtime dependency for Vue 3 components within pilets.","package":"vue","optional":false}],"imports":[{"note":"Used to create the Piral API extension for Vue 3 pilets. Piral packages are primarily ESM-first.","wrong":"const { createVue3Api } = require('piral-vue-3');","symbol":"createVue3Api","correct":"import { createVue3Api } from 'piral-vue-3';"},{"note":"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.","wrong":"import { Vue3PiletApi } from 'piral-vue-3';","symbol":"Vue3PiletApi","correct":"import type { Vue3PiletApi } from 'piral-vue-3';"},{"note":"A utility function to define a Vue 3 pilet, simplifying component registration and lifecycle management.","wrong":"import defineVue3Pilet from 'piral-vue-3';","symbol":"defineVue3Pilet","correct":"import { defineVue3Pilet } from 'piral-vue-3';"}],"quickstart":{"code":"import { Piral, createPiralFactory } from 'piral';\nimport { createVue3Api } from 'piral-vue-3';\nimport { createApp, defineComponent } from 'vue';\n\nconst MyVueComponent = defineComponent({\n  template: '<div>Hello from Vue! Count: {{ count }}</div>',\n  data() {\n    return { count: 0 };\n  },\n  mounted() {\n    setInterval(() => {\n      this.count++;\n    }, 1000);\n  }\n});\n\nconst piralApp = createPiralFactory({\n  requestPilets() {\n    return Promise.resolve([\n      {\n        name: 'my-vue-pilet',\n        version: '1.0.0',\n        spec: 'v1',\n        hash: 'abc',\n        dependencies: {},\n        setup(app) {\n          app.registerPage('/vue-page', MyVueComponent);\n          app.showNotification('Vue Pilet Loaded!', { autoClose: 2000 });\n        }\n      }\n    ]);\n  },\n  plugins: [createVue3Api()]\n});\n\n// In a real Piral application, the Piral instance would be mounted to a DOM element.\n// For demonstration, we'll just show the setup.\n// Piral renders its components into a designated DOM container.\n// For a full Piral app, this would be `render(<Piral instance={piralApp} />, document.querySelector('#app'))`.\n\nconsole.log('Piral app with Vue 3 plugin initialized.', piralApp);\n// Simulate a Piral app mounting cycle if needed for full execution context.\n// In a browser environment, you'd mount `<Piral instance={piralApp} />` into your root element.\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Hydration completed but contains mismatches."},{"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.","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.","error":"Cannot read properties of undefined (reading '$root')"},{"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.","cause":"The Vue 3 component specified in `app.registerPage` or `app.registerTile` could not be found or imported correctly within the pilet's context.","error":"Failed to resolve component: [ComponentName]"}],"ecosystem":"npm"}