Initial setup for ROQ's UI Components

Welcome to the "Getting Started" page of our technical documentation! Here, you will find all the necessary information to help you get up and running ROQ’s features without using ROQ's authentication. This page provides you with step-by-step instructions for installing and configuring ROQ.

(1) Client side installation

Install ROQ’s UI components by running this NPM command.

npm i --save @roq/ui-react

At the moment, ROQ is available for React only. However, if you need support for other libraries like Vue.js or Angular, don't hesitate to contact us on Slack (opens in a new tab).

(2) Server side installation

On the server side of your application, you need to install ROQ's SDK:

npm install @roq/nextjs --save

Please create a free account in the console (opens in a new tab) and get your environment credentials. To install ROQ you need the apiKey, environmentId and the host. To learn more about the SDK, please read the Using SDK section.

Now you can initialize the services using the credentials on the backend-side of your application.

import { Platform } from "@roq/nodejs";
 
const client = new Platform({
  environmentId: "abc",
  apiKey: "abc",
  host: "abc",
});

👀 You can find an example usage here: roq-nextjs-prisma-quickstart/src/server/roq/roq.client.ts (opens in a new tab)

(3) Synchronize user data

In case you don't use ROQ's authentication, you need to synchronize some of your user data. Please follow the instructions on this page: Sync Users

(4) Pass token from server to client-side

The AuthorisationClientService is used to fetch user tokens from ROQ Platform. You can create a token of a user with the createUserToken method and the ID which you received from the createUser method previously:

const roqAccessToken = await client.authorization.createUserToken(
  user.roqUserId
);

👀 You can find an example usage here: roq-nextjs-prisma-quickstart/src/pages/api/auth/...nextauth.ts (opens in a new tab)

The token needs to be passed over to your client-side. The specific implementation depends on your framework. Feel free to look into the code of the example app (opens in a new tab) to see how it needs to be wired-up.

(5) Install <RoqProvider/> on client-side

To use ROQ's UI components, you need to wrap your application into the <RoqProvider/> which provides all the required configuration. The minimum working setup requires three props: host (~ URL of ROQ Platform) and getToken.

Read the documentation about <RoqProvider/> for more details.

import { RoqProvider } from "@roq/ui-react";
import { getUserToken } from "<..yourlib/auth>";
import "@roq/ui-react/dist/index.css";
 
function App() {
  const token = getUserToken();
 
  return (
    <RoqProvider
      config={{
        host: "https://...",
        token,
      }}
    >
      <Component />
    </RoqProvider>
  );
}

Debug mode

To help understand what was going on under the hood, you could use the debug mode for additional logging in your development environment. When this is enabled, logs are written to your browser console.

import { RoqProvider } from "@roq/ui-react";
import { getUserToken } from "<..yourlib/auth>";
import "@roq/ui-react/dist/index.css";
 
function App() {
  const token = getUserToken();
 
  return (
    <RoqProvider
      debug
      config={{
        host: "https://...",
        token,
      }}
    >
      <Component />
    </RoqProvider>
  );
}

Handling errors

It's highly recommended to add error handling on your application, and you can do so using the onError callback.

import { RoqProvider } from "@roq/ui-react";
import { refetchSession, getUserToken, handleError } from "<..yourlib/auth>";
import "@roq/ui-react/dist/index.css";
 
function App() {
  const token = getUserToken();
 
  return (
    <RoqProvider
      config={{
        host: "https://...",
        token,
      }}
      onError={handleError}
      onTokenExpired={refetchSession}
    >
      <Component />
    </RoqProvider>
  );
}

👀 You can find an example usage here: roq-nextjs-prisma-quickstart/src/pages/_app.tsx (opens in a new tab)

What's next

🎉🎉🎉🎉🎉 That’s it! Now you are ready to select one of the UI components and to implement and business logic based on ROQ! You may want to start with the chat system, notifications or file uploads.

If you have any questions, ideas or need support then join our Community Slack (opens in a new tab) and talk to us directly.