Kine UI: Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using Kine UI, an open-source library for integrating spatial computing gestures into React applications.

1. Prerequisites

Before you begin, ensure you have the following installed:

Node.js: Version 20 or higher.
Webcam: A functional webcam with support for { video: { facingMode: "user" } } is required for hand tracking.
React Project: An existing React-based project. Next.js 14+ is recommended.

2. Installation

Kine UI is designed to be integrated into your existing React project using its CLI.

Installing Kine UI CLI

To initialize Kine UI in your project and install core dependencies:

npx @opendevsociety/kine-ui@latest init

This command will:

Prompt you to specify a directory for spatial components (e.g., components/kine).
Install framer-motion and @mediapipe/tasks-vision as core dependencies.
Create a kine-ui.json file in your project root to store the configured components directory.

Adding KineProvider

The KineProvider is essential for Kine UI to function. It manages the MediaPipe HandLandmarker engine.

npx @opendevsociety/kine-ui@latest add kine-provider

This command will add the KineProvider component to your configured components directory. You will then need to wrap your application or relevant sections with this provider.

Adding Gesture Components

Kine UI provides various pre-built gesture components. You can add them one by one. For example, to add the Air Cursor component:

npx @opendevsociety/kine-ui@latest add air-cursor

Refer to the Kine UI documentation for a list of available components and their usage.

3. Configuration

Kine UI primarily relies on client-side processing and does not require extensive server-side configuration.

`kine-ui.json`

During the init process, a kine-ui.json file is created in your project's root. This file stores the componentsDir path, which the CLI uses to place new components.

Example kine-ui.json:

{
  "componentsDir": "components/kine"
}

Environment Variables

The project's API route for fetching GitHub stars (src/app/api/stars/route.ts) can optionally use a GitHub token for higher rate limits.

GITHUB_TOKEN: (Optional) Your GitHub Personal Access Token. If provided, it will be used to fetch star counts from the GitHub API. This is primarily for the Kine UI website itself and not required for integrating Kine UI gestures into your application.

4. Build & Run

Kine UI components are integrated directly into your React project. The build and run processes follow your project's standard procedures (e.g., Next.js).

Development

To run your Next.js project locally in development mode:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

This will start the development server, typically on http://localhost:3000.

Production Build

To build your Next.js project for production:

npm run build
# or
yarn build
# or
pnpm build
# or
bun build

This command compiles your application for optimal performance.

Start Production Server

To start the production server after building:

npm run start
# or
yarn start
# or
pnpm start
# or
bun start

5. Deployment

Kine UI is built with Next.js and is well-suited for deployment on platforms that support Next.js applications, such as Vercel.

Deploying to Vercel

Vercel is the recommended platform for deploying Next.js applications.

Create a Vercel Account: If you don't have one, sign up at vercel.com.
Install Vercel CLI:
```
npm i -g vercel
```
Login to Vercel:
```
vercel login
```
Deploy Your Project: Navigate to your project directory and run:
```
vercel
```
Follow the prompts to link your project and deploy. Vercel automatically detects Next.js projects and configures the build process.

If you have a GITHUB_TOKEN environment variable, configure it in your Vercel project settings under "Environment Variables".

Other Platforms

You can also deploy to other platforms that support Node.js and Next.js, such as Netlify, AWS Amplify, or a custom Node.js server. The build process remains the same (npm run build), and the deployment method will depend on your chosen platform.

6. Troubleshooting

Webcam Access Issues:
- Problem: Kine UI cannot access the webcam, or the video feed is not appearing.
- Solution: Ensure your browser has permission to access the webcam. Check your browser's site settings for camera permissions. Also, verify that no other application is currently using the webcam.
Performance Issues / Laggy Detection:
- Problem: Hand tracking is slow or inaccurate.
- Solution:
  - Lighting: Ensure good, even lighting in your environment. MediaPipe performs best with clear visibility of hands.
  - Hardware: Detection quality can vary based on your device's CPU/GPU performance. Close other resource-intensive applications.
  - Model Loading: Ensure the MediaPipe models are loaded correctly. Check the browser console for any network errors related to unpkg or jsdelivr URLs.
@mediapipe/tasks-vision Errors:
- Problem: Errors related to MediaPipe tasks or WebAssembly.
- Solution: Verify that @mediapipe/tasks-vision is correctly installed and that your browser supports WebAssembly. Ensure the FilesetResolver is loading the WASM files from the correct CDN path (https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm).
CLI Not Working:
- Problem: npx @opendevsociety/kine-ui@latest commands fail.
- Solution: Ensure you have Node.js 20+ installed. Clear npm cache (npm cache clean --force) and try again.
Component Not Appearing:
- Problem: After adding a component with npx add, it doesn't render in your application.
- Solution:
  1. Verify the component file exists in the componentsDir specified in kine-ui.json.
  2. Ensure you have correctly imported and mounted the KineProvider and the gesture component in your React tree.
  3. Check the browser console for any React errors during rendering.

How to Deploy & Use kine-ui