npm package: @rownd/vue
Description: Easily add Rownd instant accounts and authentication to your Vue-based project.
Latest version: 1.4.0

# Vue bindings for Rownd

Easily add Rownd instant accounts and authentication to your Vue-based project.

## Installation

Simply run `npm install @rownd/vue` or `yarn add @rownd/vue`.

> NOTE: This plugin only works with Vue 3 and above! If you need support for Vue 2, please [get in touch](mailto:support@rownd.io?subject=Support%20for%20Vue%20v2).

## Usage

The library provides a Vue plugin and injector hook for Vue-based apps.

In your app's main entrypoint, install the Rownd plugin like in the following example:
```js
import { createApp } from "vue";
import { RowndPlugin } from "@rownd/vue";  // Import the plugin

import App from "./App.vue";
import router from "./router";

const app = createApp(App);

// Initialize the plugin. Be sure to include your app key!
app.use(RowndPlugin, {
  appKey: "<your app key>",
});

app.use(router);

app.mount("#app");
```

### Plugin options

  * `appKey` (required): This is the key generated by the [Rownd dashboard](https://app.rownd.io/).
  * `rootOrigin` (optional): If you're using Rownd across multiple domains (e.g., `rownd.io` and `app.rownd.io`), set this to the "root" _origin_ (e.g., https://rownd.io).

Later on within your app's components, you can use the Rownd injector/hook to access the Rownd browser API:

```html
<script setup lang="ts">
    import { RouterLink, RouterView } from "vue-router";
    import HelloWorld from "@/components/HelloWorld.vue";
    import { useRownd } from "@rownd/vue";

    const rownd = useRownd();
</script>

<template>
    <div v-if="rownd.is_authenticated">
        <h1>Welcome, {{ rownd.user.data.full_name }}!</h1>
        <strong>{{ rownd?.user?.data?.first_name }}</strong>
    </div>

    <div v-if="!rownd.is_authenticated">
        <button @click="rownd.requestSignIn({})">Sign in</button>
    </div>
</template>
```

## API reference

Most API methods are made available via the Rownd plugin and its associated `useRownd` injector.
Javascript will be used for most examples, but these should work with Vue directives as well.

#### requestSignIn()

Trigger the Rownd sign in dialog. This can be used from a link/button or programmatically, if you wanted to allow
a user to use parts of your app without signing in, but then trigger the sign-in prior to them doing something important.

```javascript
const rownd = useRownd();

rownd.requestSignIn({
    auto_sign_in: false,                           // optional
    identifier: 'me@company.com' || '+19105551212' // optional
});
```

* `auto_sign_in: boolean` - when `true`, automatically trigger a sign-in attempt _if_ `identifier` is included or an email address or phone number has already been set in the user data.
* `identifier: string` - an email address or phone number (in E164 format) to which a verification message may be sent. If the Rownd app is configured to allow unverified users, then sign-in will complete without verification if the user has not signed in previously.

#### signOut()

Sign out the user and clear their profile, returning them to a completely unauthenticated state.

```vue
<script setup>
    const rownd = useRownd();
</script>

<template>
    <button v-if="rownd.is_authenticated" @click="rownd.signOut()">Sign out</button>
</template>
```

#### **getAccessToken()**

Retrieves the active, valid access token for the current user.

```javascript
const rownd = useRownd();
let accessToken = await rownd.getAccessToken({
    waitForToken: false
});
```

* `waitForToken: boolean` - when `true`, if no access token is present or if it's expired, the promise will not resolve until a valid token is available. While unlikely, this could result in waiting forever.

**is\_initializing**

`is_initializing` will be `true` until the Hub has fully loaded, recalled its state, and resolved the current user's authentication status. This usually takes only a few milliseconds, but if you make decisions that depend on the `is_authenticated` flag while `is_initializing` is still `true`, your code/logic may not work as you expect.

```html
<script setup>
    const rownd = useRownd();
</script>

<template>
    <div v-if="rownd.is_initializing">Loading...</div>
    <div v-else>
        <p>Show some real content</p>
    </div>
</template>
```

#### is\_authenticated

Indicates whether the current user is signed in or not.

```html
<script setup>
    const rownd = useRownd();
</script>

<template>
    <ProtectedComponent v-if="rownd.is_authenticated" />
    <PublicComponent v-else />
</template>
```

#### access\_token

Represents the current access token for the user.

```html
<script setup>
    const rownd = useRownd();

    const resp = await fetch('/api/sessions', {
        method: 'post',
        headers: {
            authorization: `Bearer ${rownd.access_token}`
        }
    });

    const body = await resp.json();
</script>
```

#### user

Represents information about the current user, specifically their profile information. In the example below, we use the existing data to display the current value of `first_name` in a form field, and then immediately sync changes to Rownd as the user updates the form field.

```html
<script setup>
    const rownd = useRownd();
</script>

<template>
    <label for="first_name">
        <input 
            id="first_name" 
            type="text" 
            v-model="rownd.user.data.first_name"
        />
    </label>
</template>
```

You might not want to sync changes to Rownd immediately, but rather wait for the user to click a button,
as in the following example:

```html
<script setup>
    import { reactive } from 'vue';
    const rownd = useRownd();

    const userData = reactive(rownd.value.user.data);

    function onSubmit() {
        rownd.user.set(userData);
    }
</script>

<template>
    <form @submit.prevent="onSubmit">
        <label for="first_name">
            <input 
                id="first_name" 
                type="text" 
                v-model="userData.first_name"
            />
        </label>
        <button type="submit">Save</button>
    </form>
</template>
```

**Merge data into the user profile programmatically**
```javascript
const rownd = useRownd();
rownd.user.set({
    first_name: 'Juliet',
    last_name: 'Rose'
});
```

Set a specific field in the user profile programmatically
```javascript
const rownd = useRownd();
user.setValue('first_name', 'Alice');
```