VIDCS-3721: improvements-documentation-video-example

johnny-quesada-developer · johnny-quesada-developer · commit 633ccdc5fb88 · 2025-05-12T11:50:55.000+02:00
Removed the default * (catch-all) route for unfound API endpoints. This behavior was not API-friendly and caused confusion.

Fixed project scripts: some were intended to run both the backend and frontend simultaneously, but Bash is not concurrent by default. We now use concurrently (via npm) to achieve the desired result.

Added a script for debugging the backend project.

Updated the README to make the tutorial more detailed and beginner-friendly.

Readme now includes a clearer explanation of where and how to retrieve the necessary Vonage credentials.

Added steps for testing the app with multiple devices on a local network.
diff --git a/README.md b/README.md
@@ -114,49 +114,105 @@ The Vonage Video API Reference App for React is currently supported on the lates
 
 ## Running Locally
 
-### Config
+### 1. Ensure You Have a Vonage Account
 
- In project directory, create the environment variables for the project.
+To get started, make sure you have a Vonage account. You can create one at the [Vonage API Dashboard](https://dashboard.vonage.com/applications). The sign-up process is straightforward.
 
-```console
-cp backend/.env.example backend/.env
-```
-[Click here](backend/.env.example) to learn more about config variables used in the backend.
+### 2. Create an Application in the Dashboard
 
-Add your Vonage Video API credentials to the newly created .env file.
+Once logged in, navigate to the [Applications page](https://dashboard.vonage.com/applications) via the main dashboard menu:
 
-```console
-cp frontend/.env.example frontend/.env
+<details open>
+<summary>Applications dashboard view</summary>
+<img src="./docs/assets/readme/1-dashboard-applications.png" alt="Applications dashboard" style="max-width: 100%; height: auto;" />
+</details>
+
+If you don’t already have an application, create a new one:
+
+<details open>
+<summary>Create new app</summary>
+<img src="./docs/assets/readme/2-create-app.png" alt="Create app button" style="max-width: 100%; height: auto;" />
+</details>
+
+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:
+
+<details open>
+<summary>Configuring a new app</summary>
+<img src="./docs/assets/readme/3-create-app-form.png" alt="Create app form" style="max-width: 100%; height: auto;" />
+</details>
+
+### 3. Environment Variable
+
+In the root project directory, create the environment files by running:
+
+``` bash
+cp backend/.env.example backend/.env && cp frontend/.env.example frontend/.env
 ```
-[Click here](frontend/.env.example) to learn more about config variables used in the frontend.
 
-### Running the project
+Then, open **backend/.env** and fill in the required configuration:
 
-#### Installing dependencies
+- **VONAGE_APP_ID** – This is the ID of your Vonage application. You can find it on the [Applications page](https://dashboard.vonage.com/applications).
+- **VONAGE_PRIVATE_KEY** – If you've already generated a private key, use that. Otherwise, use the key you downloaded when creating the app.
 
-```console
+### 4. Running the Project
+
+#### Install Dependencies
+
+``` bash
 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](./docs/DEPENDENCIES.md) document.
 
-#### Dev mode
+This command installs all necessary dependencies. For details about the packages used, refer to [Dependencies](./docs/DEPENDENCIES.md).
 
-```console
+#### Start in Development Mode
+
+``` bash
 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/](http://localhost:5173/)
+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](http://localhost:5173).
 
-#### Production mode
+### 5. Testing on Multiple Devices
 
-This command builds a production bundle of the app frontend and `cp`s it to the backend to be served by the express server.
+To test the video API across multiple devices on your local network, you can use **ngrok** to expose your frontend publicly.
 
-```console
-yarn start
+#### Steps:
+
+1. Create an account at [ngrok](https://dashboard.ngrok.com/signup) if you haven’t already (The free tier allows you to have one public tunnel).
+
+2. Follow the [Setup and Installation instructions](https://dashboard.ngrok.com/get-started/setup/) for your operating system to install and configure ngrok.
+
+3. Create a secure tunnel to your frontend using:
+
+``` bash
+yarn forward:frontend
 ```
 
-The app and API are both served on  [http://localhost:3345/](http://localhost:3345/)
+This command creates a publicly accessible HTTPS URL for your frontend. It will appear in your terminal, similar to the image below:
+
+<details  open>
+<summary>ngrok output example</summary>
+<img src="./docs/assets/readme/4-forwarding front-end.png" alt="ngrok tunnel example" style="max-width: 100%; height: auto;" />
+</details>
+
+4. Copy the domain from the output and update your **frontend/.env** file:
+
+``` ini
+# example
+VITE_NGROK_DOMAIN=332a-45-137-35-107.ngrok-free.app
+```
+
+**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
 
diff --git a/backend/package.json b/backend/package.json
@@ -5,8 +5,9 @@
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "dev": "tsx watch --ignore ./tests/**/*.test.ts index.ts",
+    "dev": "tsx watch index.ts",
     "start": "node --import tsx index.ts",
+    "debug": "node --inspect --watch --import tsx index.ts",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --maxWorkers=1 --coverage",
     "test:watch": "yarn test --watch",
     "ts-check": "tsc -p tsconfig.json"
diff --git a/backend/server.ts b/backend/server.ts
@@ -1,4 +1,4 @@
-import express, { Express, Request, Response } from 'express';
+import express, { Express } from 'express';
 import path from 'path';
 import bodyParser from 'body-parser';
 import { fileURLToPath } from 'url';
@@ -27,10 +27,6 @@ app.use((_req, res, next) => {
 
 app.use(express.static(path.join(dirName, './dist')));
 
-app.get('/*', (_req: Request, res: Response) => {
-  res.sendFile(path.join(dirName, 'dist', 'index.html'));
-});
-
 const startServer: () => Promise<Server> = () => {
   return new Promise((res) => {
     const server: Server = app.listen(port, () => {
diff --git a/docs/assets/readme/1-dashboard-applications.png b/docs/assets/readme/1-dashboard-applications.png
diff --git a/docs/assets/readme/2-create-app.png b/docs/assets/readme/2-create-app.png
diff --git a/docs/assets/readme/3-create-app-form.png b/docs/assets/readme/3-create-app-form.png
diff --git a/docs/assets/readme/4-forwarding front-end.png b/docs/assets/readme/4-forwarding front-end.png
diff --git a/frontend/.env.example b/frontend/.env.example
@@ -9,3 +9,7 @@ VITE_ENABLE_REPORT_ISSUE=false
 # This is meant for development only.
 # Note: this only works when opening a room url directly, not when navigating via the landing page.
 VITE_BYPASS_WAITING_ROOM=false
+
+# For testing with multiple devices, you can use ngrok to expose your vite server to the internet.
+# your can see more information on how this works at https://ngrok.com/docs/
+VITE_NGROK_DOMAIN=332a-45-137-35-107.ngrok-free.app
diff --git a/frontend/package.json b/frontend/package.json
@@ -7,7 +7,7 @@
   "scripts": {
     "build": "vite build && yarn cp-build",
     "cp-build": "mkdir -p ../backend/dist && cp -r dist ../backend",
-    "dev": "vite",
+    "dev": "vite --host",
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
     "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
@@ -1,5 +1,5 @@
 /// <reference types="vitest" />
-import { defineConfig, mergeConfig } from 'vite';
+import { defineConfig, loadEnv, mergeConfig } from 'vite';
 import type { UserConfig as VitestUserConfigInterface } from 'vitest/config';
 import { defineConfig as defineVitestConfig } from 'vitest/config';
 import react from '@vitejs/plugin-react';
@@ -26,17 +26,23 @@ const vitestConfig: VitestUserConfigInterface = defineVitestConfig({
 });
 
 // https://vitejs.dev/config/
-const viteConfig = defineConfig({
-  optimizeDeps: {
-    include: ['@emotion/react', '@emotion/styled', '@mui/material/Tooltip'],
-  },
-  plugins: [
-    react(),
-    replace({
-      'process.env.CI': process.env.CI,
-      preventAssignment: true,
-    }),
-  ],
-});
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd());
 
-export default mergeConfig(vitestConfig, viteConfig);
+  return mergeConfig(vitestConfig, {
+    server: {
+      host: true,
+      allowedHosts: ['*', env.VITE_NGROK_DOMAIN],
+    },
+    optimizeDeps: {
+      include: ['@emotion/react', '@emotion/styled', '@mui/material/Tooltip'],
+    },
+    plugins: [
+      react(),
+      replace({
+        'process.env.CI': process.env.CI,
+        preventAssignment: true,
+      }),
+    ],
+  });
+});
diff --git a/package.json b/package.json
@@ -15,17 +15,19 @@
   "scripts": {
     "build": "yarn workspace frontend build",
     "deploy-vcr": "vcr deploy",
-    "dev": "yarn && yarn workspace frontend dev & yarn workspace backend dev",
+    "dev": "concurrently 'yarn workspace frontend dev' 'yarn workspace backend dev'",
     "docs": "yarn workspace frontend docs",
     "docs:watch": "yarn workspace frontend docs:watch",
     "lint": "ESLINT_USE_FLAT_CONFIG=false yarn eslint . --ext .ts,.tsx",
     "lint:filenames": "./scripts/lintFileNames.sh",
     "lint:fix": "yarn prettier --write . && yarn lint --fix",
     "postinstall": "husky",
     "run-server": "yarn workspace backend start",
-    "start": "yarn workspace frontend build && yarn workspace backend start",
+    "start": "yarn workspace backend start",
     "start:backend": "yarn workspace backend dev",
+    "debug:backend": "yarn workspace backend debug",
     "start:frontend": "yarn workspace frontend dev",
+    "forward:frontend": "npx ngrok http 5173",
     "test": "yarn test:backend && yarn test:frontend",
     "test:backend": "yarn workspace backend test",
     "test:backend:watch": "yarn workspace backend test:watch",
@@ -68,6 +70,7 @@
     "husky": "^9.0.11",
     "license-checker": "^25.0.1",
     "lint-staged": "^15.2.2",
+    "concurrently": "^9.1.2",
     "prettier": "^3.2.5",
     "typescript": "^5.8.3"
   },
diff --git a/yarn.lock b/yarn.lock
@@ -3357,7 +3357,7 @@ chalk@^3.0.0:
     ansi-styles "^4.1.0"
     supports-color "^7.1.0"
 
-chalk@^4.0.0, chalk@^4.1.0:
+chalk@^4.0.0, chalk@^4.1.0, chalk@^4.1.2:
   version "4.1.2"
   resolved "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz"
   integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
@@ -3548,6 +3548,19 @@ concat-map@0.0.1:
   resolved "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz"
   integrity sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==
 
+concurrently@^9.1.2:
+  version "9.1.2"
+  resolved "https://registry.yarnpkg.com/concurrently/-/concurrently-9.1.2.tgz#22d9109296961eaee773e12bfb1ce9a66bc9836c"
+  integrity sha512-H9MWcoPsYddwbOGM6difjVwVZHl63nwMEwDJG/L7VGtuaJhb12h2caPG2tVPWs7emuYix252iGfqOyrz1GczTQ==
+  dependencies:
+    chalk "^4.1.2"
+    lodash "^4.17.21"
+    rxjs "^7.8.1"
+    shell-quote "^1.8.1"
+    supports-color "^8.1.1"
+    tree-kill "^1.2.2"
+    yargs "^17.7.2"
+
 confbox@^0.1.7:
   version "0.1.7"
   resolved "https://registry.npmjs.org/confbox/-/confbox-0.1.7.tgz"
@@ -7701,6 +7714,13 @@ run-parallel@^1.1.9:
   dependencies:
     queue-microtask "^1.2.2"
 
+rxjs@^7.8.1:
+  version "7.8.2"
+  resolved "https://registry.yarnpkg.com/rxjs/-/rxjs-7.8.2.tgz#955bc473ed8af11a002a2be52071bf475638607b"
+  integrity sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==
+  dependencies:
+    tslib "^2.1.0"
+
 safe-array-concat@^1.1.2:
   version "1.1.2"
   resolved "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.1.2.tgz"
@@ -7842,6 +7862,11 @@ shebang-regex@^3.0.0:
   resolved "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz"
   integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==
 
+shell-quote@^1.8.1:
+  version "1.8.2"
+  resolved "https://registry.yarnpkg.com/shell-quote/-/shell-quote-1.8.2.tgz#d2d83e057959d53ec261311e9e9b8f51dcb2934a"
+  integrity sha512-AzqKpGKjrj7EM6rKVQEPpB288oCfnrEIuyoT9cyF4nmGa7V8Zk6f7RRqYisX8X9m+Q7bd632aZW4ky7EhbQztA==
+
 shiki@^1.16.2:
   version "1.22.2"
   resolved "https://registry.yarnpkg.com/shiki/-/shiki-1.22.2.tgz#ed109a3d0850504ad5a1edf8496470a2121c5b7b"
@@ -8271,9 +8296,9 @@ supports-color@^7.1.0:
   dependencies:
     has-flag "^4.0.0"
 
-supports-color@^8.0.0:
+supports-color@^8.0.0, supports-color@^8.1.1:
   version "8.1.1"
-  resolved "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz"
+  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-8.1.1.tgz#cd6fc17e28500cff56c1b86c0a7fd4a54a73005c"
   integrity sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==
   dependencies:
     has-flag "^4.0.0"
@@ -8424,6 +8449,11 @@ tr46@~0.0.3:
   resolved "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz"
   integrity sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==
 
+tree-kill@^1.2.2:
+  version "1.2.2"
+  resolved "https://registry.yarnpkg.com/tree-kill/-/tree-kill-1.2.2.tgz#4ca09a9092c88b73a7cdc5e8a01b507b0790a0cc"
+  integrity sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==
+
 treeify@^1.1.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/treeify/-/treeify-1.1.0.tgz#4e31c6a463accd0943879f30667c4fdaff411bb8"
@@ -8473,7 +8503,7 @@ tsconfig-paths@^3.15.0:
     minimist "^1.2.6"
     strip-bom "^3.0.0"
 
-tslib@^2.3.0:
+tslib@^2.1.0, tslib@^2.3.0:
   version "2.8.1"
   resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f"
   integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
@@ -9036,9 +9066,9 @@ yargs-parser@^21.0.1, yargs-parser@^21.1.1:
   resolved "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz"
   integrity sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==
 
-yargs@^17.3.1:
+yargs@^17.3.1, yargs@^17.7.2:
   version "17.7.2"
-  resolved "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz"
+  resolved "https://registry.yarnpkg.com/yargs/-/yargs-17.7.2.tgz#991df39aca675a192b816e1e0363f9d75d2aa269"
   integrity sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==
   dependencies:
     cliui "^8.0.1"
