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.

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:

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.
• 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:

<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.

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.

<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.

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.

<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.

<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.

<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.

<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:

<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

const rownd = useRownd();
rownd.user.set({
    first_name: 'Juliet',
    last_name: 'Rose'
});

Set a specific field in the user profile programmatically

const rownd = useRownd();
user.setValue('first_name', 'Alice');