Vonage Video API Reference App for React

Table of Contents

• Table of Contents
• What is it?
• Why use it?
• Project Architecture
• Platforms Supported
• Requirements
• Running Locally
• Testing on Multiple Devices
• Deployment to Vonage Cloud Runtime
• Testing
  • Integration Tests
    • Screenshot tests or Visual comparisons
    • Generating and Updating Screenshots
  • Running the backend and frontend test suites
  • Backend Suite
  • Frontend Suite
• Code style
  • Linting and auto-formatting
  • File names
• Documentation Generation
• Code of Conduct
• Getting Involved
• Known Issues
• Report Issues

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.

  
• A waiting room for users to preview their audio and video device settings and set their name before entering a meeting room.

  
• A post-call page to navigate users to the landing page, re-enter the left room, and display archive(s), if any.

  
• A video conferencing “room” supporting up to 25 participants and the following features:
• Input and output device selectors.

  
• Background blur and noise suppression toggles.
• Composed archiving capabilities to record your meetings.

  
• In-call tools such as screen sharing, group chat function, and emoji reactions.

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

  
• Call participant list with audio on/off indicator.

  
• Meeting information with an easy-to-share URL to join the meeting.
• A reporting tool to enable participants to file any in-call issues.

  

Project Architecture

Platforms Supported

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

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

Note: Mobile web views have limited supported at the moment. The minimum supported device width is 360px.

Requirements

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

Running Locally

• Ensure You Have a Vonage Account

  You can create one at the Vonage API Dashboard.

• Create an Application in the Dashboard

  Once logged in, navigate to the Applications page via the main dashboard menu:

  Applications dashboard view

  

  If you don’t already have an application, create a new one:

  Create new app

  

  During the setup process, make sure to:

  • Provide a name for your application.
  • Generate and download the public and private keys.
  • Enable Video capabilities.

  Refer to the following image for visual guidance:

  Configuring a new app

  
  
  

• Environment Variables

  In the root project directory, create the environment files by running:

  cp backend/.env.example backend/.env && cp frontend/.env.example frontend/.env

  Then, open backend/.env and fill in the required configuration:

  • VONAGE_APP_ID – This is the ID of your Vonage application. You can find it on the Applications page.
  • VONAGE_PRIVATE_KEY – If you've already generated a private key, use that. Otherwise, use the key you downloaded when creating the app.

• Start in Development Mode

  yarn dev

  This starts both the backend server (port 3345) and the frontend Vite dev server (port 5173). You can now access the app at http://localhost:5173.

Testing on Multiple Devices

To test the video API across multiple devices on your local network, you can use ngrok to expose your frontend publicly.

1. Create an account at ngrok if you haven’t already.

2. Follow the Setup and Installation instructions for your operating system to install and configure ngrok.

3. Create a secure tunnel to your frontend using:

   yarn forward:frontend

   This command creates a publicly accessible HTTPS URL for your frontend. It will appear in your terminal, similar to the image below:

   ngrok output example

   
   
   

4. Copy the domain from the output and update your frontend/.env file:

   # example
   VITE_TUNNEL_DOMAIN=GENERIC_DOMAIN

   Note: ngrok assigns a temporary domain. You’ll need to update your environment variable each time the domain changes.

5. Open the provided Forwarding URL in your browser. This exposes your Vite app publicly. However, keep in mind that the backend server is still local, so the devices accessing the app must be on the same local network.

Enjoy testing!

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

• For additional CLI options, see jest docs.

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

• For additional CLI options, see vitest docs

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 [email protected].