piral-vue-3
Version:
Plugin for integrating Vue@3 components in Piral.
198 lines (139 loc) • 5.55 kB
Markdown
[](https://piral.io)
# [Piral Vue 3](https://piral.io) · [](https://github.com/smapiot/piral/blob/main/LICENSE) [](https://www.npmjs.com/package/piral-vue-3) [](https://jestjs.io) [](https://discord.gg/kKJ2FZmK8t)
This is a plugin that only has a peer dependency to `vue`. What `piral-vue-3` brings to the table is a set of Pilet API extensions that can be used with `piral` or `piral-core`.
The set includes a Vue@3 converter for any component registration, as well as a `fromVue3` shortcut and a `Vue3Extension` component.
By default, these API extensions are not integrated in `piral`, so you'd need to add them to your Piral instance.
## Documentation
The following functions are brought to the Pilet API.
### `fromVue3()`
Transforms a standard Vue@3 component into a component that can be used in Piral, essentially wrapping it with a reference to the corresponding converter.
### `Vue3Extension`
The extension slot component to be used in Vue@3 components. This is not really needed, as it is made available automatically via a Vue@3 custom element named `extension-component`.
### `defineVue3Middleware`
This function is used to declare additional middleware such as plugins when setting up Vue3.
Example in a standalone pilet:
```ts
import { fromVue3, defineVue3Middleware } from 'piral-vue-3/convert';
import Page from './Page.vue';
import i18next from 'i18next';
import I18NextVue from 'i18next-vue';
import type { PiletApi } from 'sample-piral';
i18next.init({
lng: 'de',
interpolation: {
escapeValue: false
},
fallbackLng: false,
resources: {
en: {
translation: {
greeter: "Welcome",
},
},
de: {
translation: {
greeter: "Willkommen",
},
},
}
});
export function setup(app: PiletApi) {
defineVue3Middleware(vue => {
vue.use(I18NextVue, { i18next });
});
app.registerPage('/sample', fromVue3(Page));
}
```
Here we integrate the `i18next` plugin using the `i18next-vue` package. By defining the middleware using the `defineVue3Middleware` and the provided callback, we can integrate the plugin without requiring any access to the original `app` instance of Vue.
## Usage
::: summary: For pilet authors
You can use the `fromVue3` function from the Pilet API to convert your Vue@3 components to components usable by your Piral instance.
Example use:
```ts
import { PiletApi } from '<name-of-piral-instance>';
import VuePage from './Page.vue';
export function setup(piral: PiletApi) {
piral.registerPage('/sample', piral.fromVue3(VuePage));
}
```
Within Vue@3 components the Piral Vue@3 extension component can be used by referring to `extension-component`, e.g.,
```html
<extension-component name="name-of-extension"></extension-component>
```
Alternatively, if `piral-vue-3` has not been added to the Piral instance you can install and use the package also from a pilet directly.
```ts
import { PiletApi } from '<name-of-piral-instance>';
import { fromVue3 } from 'piral-vue-3/convert';
import VuePage from './Page.vue';
export function setup(piral: PiletApi) {
piral.registerPage('/sample', fromVue3(VuePage));
}
```
:::
::: summary: For Piral instance developers
Using Vue with Piral is as simple as installing `piral-vue-3` and `vue@3`.
```ts
import { createVue3Api } from 'piral-vue-3';
```
The integration looks like:
```ts
const instance = createInstance({
// important part
plugins: [createVue3Api()],
// ...
});
```
The `vue` package should be shared with the pilets via the *package.json*:
```json
{
"importmap": {
"imports": {
"vue": ""
}
}
}
```
:::
## Development Setup
For your bundler additional packages may be necessary. For instance, for Webpack the following setup is required:
First, install the additional dev dependencies
```sh
npm i vue-loader @vue/compiler-sfc@^3 --save-dev
```
then add a *webpack.config.js* to use them
```js
const { VueLoaderPlugin } = require('vue-loader');
module.exports = function (config) {
config.module.rules.unshift({
test: /\.vue$/,
use: 'vue-loader'
});
config.plugins.push(new VueLoaderPlugin());
return config;
};
```
Now, *.vue* files are correctly picked up and handled.
Alternatively, the Webpack configuration can be rather simplistic. In many cases you can use the convenience `extend-webpack` module.
This is how your *webpack.config.js* can look like with the convenience module:
```js
const extendWebpack = require('piral-vue-3/extend-webpack');
module.exports = extendWebpack({});
```
For using `piral-vue-3/extend-webpack` you must have installed:
- `vue-loader` (at least version 16)
- `@vue/compiler-sfc^3`
- `webpack`, e.g., via `piral-cli-webpack5`
You can do that via:
```sh
npm i vue-loader @vue/compiler-sfc^3 piral-cli-webpack5 --save-dev
```
The available options for `piral-vue-3/extend-webpack` are the same as for the options of the `vue-loader`, e.g.:
```js
const extendWebpack = require('piral-vue-3/extend-webpack');
module.exports = extendWebpack({
enableTsInTemplate: true,
customElement: /\.ce\.vue$/,
});
```
## License
Piral is released using the MIT license. For more information see the [license file](./LICENSE).