Skip to main content

Installation

Install the Native Frame client for your stack

To install the Native Frame client, pick the package that matches your stack and add it with npm, yarn, or the CDN. Use @video/video-client-react in a React application — it ships the hooks, context providers, and components. Use @video/video-client-core for vanilla JavaScript or any non-React framework. This guide gets the client installed and confirms it loads; building a broadcaster and a viewer is the Quickstart.

Prerequisites​

Before you install, you need:

  • Node.js 14 or later with npm or yarn, if you install from the registry
  • React 16.8 or later, if you use the React package — hooks are required
  • A browser from Chrome 74+, Firefox 68+, Safari 12.1+, or Edge 79+
  • HTTPS on any site that captures camera or microphone, except on localhost

Credentials are not needed to install the client, but you need them before it can connect to anything. Get your authentication token, stream key, and backend endpoint from Create an account and get credentials.

Install​

Which package you install depends on your framework, so start there.

React applications install @video/video-client-react from the Native Frame registry. Point the @video scope at it in your .npmrc:

@video:registry=https://npm-packages.nativeframe.com/

Then add the package with npm or yarn:

npm install @video/video-client-react
# or
yarn add @video/video-client-react

The package ships its own TypeScript definitions, so there is no separate types package to add.

The CDN is not an option for React

The CDN serves @video/video-client-core only. A React application installs from the registry.

From the CDN​

The CDN serves @video/video-client-core only, so this path is for vanilla JavaScript and non-React frameworks. There is nothing to install and no build step — load the client with an import map:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Native Frame App</title>

  <script type="importmap">
  {
    "imports": {
      "vdc-cdn": "https://cdn.nativeframe.com/video-client-core/14.0.0/index.js"
    }
  }
  </script>
</head>
<body>
  <div id="app"></div>

  <script type="module">
    import { createCall, BaseAuthClient } from 'vdc-cdn';
    // Your code here
  </script>
</body>
</html>

The version is part of the CDN path, so a page stays pinned to whatever version its import map names. Change that segment of the path to move to another release. The path also accepts latest, but it moves under you without a deploy on your side — do not point production at it.

Import maps need a recent browser

Import maps require Chrome 89+, Firefox 108+, Safari 16.4+, or Edge 89+. To support anything older, install from the registry and use a bundler instead.

Verify​

Render this component in your app. If it compiles and you see your camera preview, the React package is installed and working:

import React from 'react';
import { usePreviewPlayer } from '@video/video-client-react/hooks';
import { MediaStreamControllerAPIProvider, PlayerAPIProvider } from '@video/video-client-react/context';
import { Video } from '@video/video-client-react/components';

export default function VerifyInstallation() {
  const { mediaStreamController, previewPlayer, isLoading } = usePreviewPlayer();

  if (isLoading) {
    return <div>Loading camera...</div>;
  }

  return (
    <MediaStreamControllerAPIProvider mediaStreamController={mediaStreamController}>
      <PlayerAPIProvider player={previewPlayer}>
        <Video />
      </PlayerAPIProvider>
    </MediaStreamControllerAPIProvider>
  );
}

Your browser prompts for camera access the first time it runs. Connecting to a real stream needs your credentials and is covered in the Quickstart.

Troubleshooting​

Cannot find module '@video/video-client-react'​

The package is not installed, or npm cannot reach the Native Frame registry.

  1. Confirm the package is installed: npm list @video/video-client-react
  2. Confirm your .npmrc points the @video scope at the Native Frame registry
  3. Reinstall from scratch: rm -rf node_modules && npm install
  4. Clear the npm cache: npm cache clean --force
  5. Check that the package is listed under dependencies in package.json

Browser does not support import maps​

The CDN method needs a browser that understands import maps.

  1. Update to Chrome 89+, Firefox 108+, Safari 16.4+, or Edge 89+
  2. Or install from the registry and use a bundler, which needs no import-map support
  3. An import-map polyfill also works, but do not depend on one in production

TypeScript reports errors on Native Frame types​

Both packages ship their own definitions, so type errors usually mean your compiler options do not match them.

  1. Update to the current package version: npm update @video/video-client-react
  2. Set moduleResolution: "node", esModuleInterop: true, and allowSyntheticDefaultImports: true in tsconfig.json; React projects also need jsx: "react"
  3. Restart the TypeScript server in your editor
  4. skipLibCheck: true silences the errors as a temporary workaround, not a fix

A bundler cannot resolve the package​

Vite resolves both packages with no extra configuration. Webpack and Rollup need ES-module resolution set up: add .js, .ts, and .tsx to Webpack's resolve.extensions, or add @rollup/plugin-node-resolve and @rollup/plugin-commonjs to a Rollup build.

If none of these fix it, the Troubleshooting guide and the FAQ cover more cases.

When you contact Native Frame support, include your Node and npm versions (node -v && npm -v), the installed package version (npm list @video/video-client-react), the full error and stack trace, and your browser and operating system.

FrameworksFramework support

The packages, registry, and versions behind the choice above, including Next.js and React Native.

GuideToken setup

Mint and refresh tokens in your app so the installed client can connect.