Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kuzzleio/vue-plugin-kuzzle
A Vue.js plugin shipping the Kuzzle Javascript SDK in your components
https://github.com/kuzzleio/vue-plugin-kuzzle
kuzzle vuejs vuejs-plugin
Last synced: 3 days ago
JSON representation
A Vue.js plugin shipping the Kuzzle Javascript SDK in your components
- Host: GitHub
- URL: https://github.com/kuzzleio/vue-plugin-kuzzle
- Owner: kuzzleio
- License: apache-2.0
- Created: 2019-03-04T09:21:06.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-24T09:11:20.000Z (6 months ago)
- Last Synced: 2024-05-23T07:47:08.041Z (5 months ago)
- Topics: kuzzle, vuejs, vuejs-plugin
- Language: TypeScript
- Homepage:
- Size: 131 KB
- Stars: 6
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Vue.js Kuzzle Plugin
This plugin simply exposes the Kuzzle SDK in your Vuejs components.
## Compatibility matrix
| Kuzzle Version | Vue.js Kuzzle Plugin Version |
| -------------- | ---------------------------- |
| 1.x.x | 1.x.x |
| 2.x.x | 2.x.x and higher |
## Getting started
Install the plugin via
```bash
npm install vue-plugin-kuzzle
```
Then, in your Vuejs application, you need to register the plugin in your `Vue` class.
```javascript
import { VueKuzzle } from 'vue-plugin-kuzzle';
Vue.use(VueKuzzle, options);
```
Where `options` may contain the following options.
### `options.backends`
An object of available backends to connect to. Backends are POJOs of the following form (the example shows the default config):
```javascript
options.backends = {
local: {
host: 'localhost',
protocol: 'websocket',
options: {
port: 7512,
sslConnection: false
}
}
};
```
The plugin will instantiate the Kuzzle SDK with the `Websocket` protocol, choosing among the available backends based on the `process.env.VUE_APP_BACKEND` environment variable. If this variable is not specified, the `local` backend is choosen as fallback.
**Warning** Don't forget to `connect()` your instance before performing any actions.
### `options.sdkOptions`
An object that contains the SDK options.
You can find the available options list [here](https://docs.kuzzle.io/sdk/js/7/core-classes/kuzzle/constructor/#options)
## Specify the backend via environment variables
Aside from the `backends` option, you can define the backend to connect to entirely via environment variables.
* `VUE_APP_BACKEND_HOST` contains the hostname (e.g. `kuzzle.mydomain.com`),
* `VUE_APP_BACKEND_PORT` contains the port (e.g. `443`),
* `VUE_APP_BACKEND_SSL` can be set to `true` if the connection supports the SSL layer (do not set this variable if SSL is not supported).
* `VUE_APP_BACKEND_PROTO` can be set to either `http` or `websocket`. If left blank, Websocket protocol is used by default.
For example, you can build your up to connect the Websocket to `wss://kuzzle.mydomain.com:443` like the following
```
VUE_APP_BACKEND_HOST=kuzzle.mydomain.com VUE_APP_BACKEND_PORT=443 VUE_APP_BACKEND_SSL=true npm run build
```
## Specify the backend via a global variable
You can also specify the backend config as a JSON-stringified POJO living in a global variable called `kuzzleBackend`. This variable must be available _before_ the Vue app is started, specifically before the `instantiateKuzzleSDK` public function is called. Here is an example of how to declare it
```javascript
const kuzzleBackend = JSON.stringify({
host: 'myhost.mydomain.com',
options: {
port: 443,
ssl: true
}
})
```
## Specify the backend via localStorage
_Purely for debug purposes_, you can override all the backend configuration by setting your backend as stringified JSON in the `kuzzle-backend` Local Storage item, e.g.
```
{ "host": "myinstance.mydomain.io", "options": { "port": 443, "ssl": true } }
```
**Beware that Local Storage is persistent and it is fairly easy to forget you set this item.** Use it consciously and keep in mind it is a good practice to unset it as soon as your debug session is over.
## Backend declaration precedence order
The plugin makes a choice of the available backend declaration by setting a preference order.
* Local storage (`kuzzle-backend`)
* Global variable (`kuzzleBackend`)
* Environment variables
* Options passed to `Vue.use`
## Accessing the Kuzzle SDK instance within the app
You'll be able to access the Kuzzle SDK instance from the components as
```javascript
this.$kuzzle;
```
And from anywhere in your app where the `Vue` class is available, as
```javascript
Vue.prototype.$kuzzle;
```
### Composition API (Vue 2.7 & 3)
In components with composition API you can use the composable to access the Kuzzle SDK instance
```javascript
import { useKuzzle } from 'vue-plugin-kuzzle';
const $kuzzle = useKuzzle();
```