Skip to content

Latest commit

 

History

History
323 lines (234 loc) · 13.1 KB

README.md

File metadata and controls

323 lines (234 loc) · 13.1 KB

Vonage Video API Reference App for React

Table of Contents

What is it?

The Vonage Video API Reference App for React is an open-source video conferencing reference application for the Vonage Video API using the React framework.

The Reference App demonstrates the best practices for integrating the Vonage Video API with your application for various use cases, from one-to-one and multi-participant video calling to recording, screen sharing, reactions, and more.

Why use it?

The Vonage Video API Reference App for React provides developers an easy-to-setup way to get started with using our APIs with React.

The application is open-source, so you can not only get started quickly, but easily extend it with features needed for your use case. Any features already implemented in the Reference App use best practices for scalability and security.

As a commercial open-source project, you can also count on a solid information security architecture. While no packaged solution can guarantee absolute security, the transparency that comes with open-source software, combined with the proactive and responsive open-source community and vendors, provides significant advantages in addressing information security challenges compared to closed-source alternatives.

This application provides features for common conferencing use cases, such as:

  • A landing page for users to create and join meeting rooms. Screenshot of landing page
  • A waiting room for users to preview their audio and video device settings and set their name before entering a meeting room. Screenshot of waiting room
  • A post-call page to navigate users to the landing page, re-enter the left room, and display archive(s), if any. Screenshot of goodbye page
  • A video conferencing “room” supporting up to 25 participants and the following features:
  • Input and output device selectors. Screenshot of audio devices selector
  • Background blur and noise suppression toggles.
  • Composed archiving capabilities to record your meetings. Screenshot of archiving dialog box
  • In-call tools such as screen sharing, group chat function, and emoji reactions. Screenshot of emojis
  • Active speaker detection.
  • Layout manager with options to display active speaker, screen share, or all participants in a grid view.
  • The dynamic display adjusts to show new joiners, hide video tiles to conserve bandwidth, and show the “next” participant when someone previously speaking leaves.
  • Ability to mute other participants during the meeting. Screenshot of muting participant dialog box
  • Call participant list with audio on/off indicator. Screenshot of participant list
  • Meeting information with an easy-to-share URL to join the meeting.
  • A reporting tool to enable participants to file any in-call issues. Screenshot of report issue pane

Project Architecture

Vonage Video API Reference App Architecture Diagram

Platforms Supported

The Vonage Video API Reference App for React is currently supported on the latest release versions for the following browsers:

  • Chrome icon Google Chrome
  • Firefox icon Firefox
  • Edge icon Microsoft Edge
  • Opera icon Opera
  • Safari icon Safari
  • Electron icon Electron

Note: Mobile web views have limited supported at the moment.

Requirements

  • node.js (version 22)
  • yarn
  • optional - nvm (recommended for switching Node versions)

Running Locally

Config

In project directory, create the environment variables for the project.

cp backend/.env.example backend/.env

Click here to learn more about config variables used in the backend.

Add your Vonage Video API credentials to the newly created .env file.

cp frontend/.env.example frontend/.env

Click here to learn more about config variables used in the frontend.

Running the project

Installing dependencies

yarn

This command installs all appropriate dependencies for the project. If you would like more information on the packages we use, please refer to the Dependencies document.

Dev mode

yarn dev

This command builds and watches both the backend server (:3345) and frontend vite dev server (:5173) You should now see the app running at http://localhost:5173/

Production mode

This command builds a production bundle of the app frontend and cps it to the backend to be served by the express server.

yarn start

The app and API are both served on http://localhost:3345/

Deployment to Vonage Cloud Runtime

You can easily deploy your local branch to Vonage Cloud Runtime (VCR) using the tools in this repository. See https://developer.vonage.com/en/vonage-cloud-runtime/overview for an overview of Vonage Cloud Runtime.

Firstly, install the VCR cli: https://developer.vonage.com/en/vonage-cloud-runtime/getting-started/working-locally#cli-installation.

Run vcr configure entering your Vonage API Key and Secret, and select a region. You can find your API key and secret on the dashboard: https://dashboard.nexmo.com/.

Now run vcr init and follow the steps to:

  1. choose a project name
  2. choose an instance name
  3. select nodejs22 for the runtime
  4. Select a region for your app
  5. Choose or create an application for deployment. ⚠️ You should use a separate Vonage application to your Vonage Video application (i.e. the value you used for VONAGE_APP_ID in the backend/.env file) to avoid issues with your private key
  6. Choose an application for debug, if you SKIP it will re-use the application from your deployment
  7. For the product template select SKIP

You will see a new file created ./vcr.yml. This file is ignored by git so that each developer can have their own deployment setup locally. This file is still missing the entrypoint and build-script fields which you can copy and paste from ./vcr.yml.example.

Your file should now look something like this:

project:
  name: my-project-name
instance:
  name: my-instance-name
  runtime: nodejs22
  region: aws.euw1
  build-script: './vcrBuild.sh'
  entrypoint: [yarn, run-server]
  application-id: my-deployment-app-id
debug:
  entrypoint: [yarn, run-server]
  application-id: my-debug-app-id

Now run yarn deploy-vcr to deploy your project. After a successful deployment the url of you instance will be shown in the output as 'Instance host address'. You can also check your instances at https://dashboard.nexmo.com/serverless/instances.

Note: This will deploy the project using your local code and .env files, which is useful for debugging. For a more centralized deployment to VCR see our GHA workflow .github/workflows/deploy-to-vcr.yml.

Testing

Integration Tests

We have integration tests using Playwright. We recommend using their VSCode integration to run tests.

To run the tests you need to run the app server separately:

# In one terminal tab
yarn start

# In a separate tab. Or use vscode extension to run tests
yarn test:integration

Screenshot tests or Visual comparisons

We use Playwright Visual Comparison for Screenshot UI tests. Since screenshot tests are part of our integration tests, running our integration tests also executes the screenshot tests.

Generating and Updating Screenshots

If we need to update the expected screenshot due to UI changes, we can delete the existing expected screenshot and then run the test. The test will fail, but a new expected screenshot will be generated. Running the test again should pass, as the expected and actual screenshots will now match.

For CI tests, we require screenshots for various browsers and operating systems because they render interfaces with subtle differences.

To capture CI-specific screenshots, you can use the update-screenshots job. This job is triggered by creating a pull request (PR) with the update-screenshots label on GitHub. Once triggered, it will capture new screenshots on the virtual machine (VM) and automatically push those to the PR's branch.

Running the backend and frontend test suites

  • To run the frontend and backend tests:
yarn test

Backend Suite

  • To run backend tests once:
yarn test:backend
  • To run backend tests in watch mode (ie you're adding more tests):
yarn test:backend:watch

Frontend Suite

We have frontend tests using vitest and React Testing Library. We recommend using the vitest VSCode integration to run tests.

Alternatively you can run the tests in the terminal:

  • To run frontend tests once:
yarn test:frontend
  • To run frontend tests in watch mode (ie you're adding more tests):
yarn test:frontend:watch

Code style

Linting and auto-formatting

We use eslint and prettier to format code. Prettier issues will show up in eslint too via eslint-plugin-prettier. You can setup an eslint extension for your editor. For VSCode use: dbaeumer.vscode-eslint.

You can either set up vscode to fix eslint issues on save or fix them with VSCode keyboard command palette shortcut cmd + shift + p > "ESLint: Fix all auto-fixable problems".

In the terminal you can run

yarn lint

to check for eslint issues and

yarn lint:fix

to fix any auto-fixable issues and also run prettier on all files.

File names

All filenames are in camelCase.

Documentation Generation

We use typedoc to generate documentation from our jsdoc comments. Generated documents can be found in the frontend/dist folder.

To generate documentation, run the following in the terminal

yarn docs

Code of Conduct

Please read our Code of Conduct.

Getting Involved

If you wish to contribute to this project, read how in Contributing.

Known Issues

We track known issues in Known Issues. Please refer to it for details.

Report Issues

If you have any issues, feel free to open an issue or reach out to support via support@api.vonage.com.