Installation

Prerequisites

Before installing PolyChat-AI, ensure you have the following installed on your system:

Node.js

Version 18 or higherDownload from nodejs.org

Package Manager

npm or yarnIncluded with Node.js installation

Git

Latest versionDownload from git-scm.com

OpenRouter API Key

Free tier availableSign up at openrouter.ai

Verify Prerequisites

Check that you have the required versions installed:

node --version
# Should output v18.0.0 or higher

npm --version
# Should output 8.0.0 or higher

git --version
# Should output 2.0.0 or higher

Installation Steps

Clone the Repository

Clone the PolyChat-AI repository from GitHub:

git clone https://github.com/Teeflo/PolyChat-AI.git
cd PolyChat-AI

If you want to contribute to the project, consider forking the repository first and then cloning your fork.

Install Dependencies

Install all required npm packages:

npm install

This will install the following key dependencies:

Package	Version	Purpose
react	^19.1.0	UI framework
typescript	~5.8.3	Type safety
vite	^7.0.4	Build tool
tailwindcss	^4.1.11	Styling
zustand	^5.0.7	State management
@xenova/transformers	^2.17.1	Local embeddings for RAG

The installation may take a few minutes depending on your internet connection. The @xenova/transformers package is particularly large as it includes ML models.

Start the Development Server

Launch the Vite development server:

npm run dev

You should see output similar to:

VITE v7.0.4  ready in 432 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

The development server supports hot module replacement (HMR), so your changes will be reflected instantly without a full page reload.

Open in Browser

Navigate to the local development URL:

http://localhost:5173

The PolyChat-AI application will load and display an onboarding modal on first launch.

Configure API Key

On first launch, you’ll need to configure your OpenRouter API key:

Get your API key from OpenRouter.ai:
- Sign up for a free account
- Navigate to the Keys section
- Click Create Key
- Copy your API key
Enter the key in the onboarding modal that appears
Verify the connection by selecting a model and sending a test message

Keep your API key secure! It’s stored in your browser’s localStorage and should never be committed to version control or shared publicly.

If you need to update your API key later:

Open Settings (Ctrl/Cmd + K)
Navigate to the API tab
Enter your new API key

Project Structure

Understand the organization of the PolyChat-AI codebase:

PolyChat-AI/
├── public/                    # Static assets (logo, icons)
├── src/
│   ├── assets/               # Images and media resources
│   ├── components/           # React components
│   │   ├── Chat/             # Chat interface components
│   │   ├── Layout/           # Header, Sidebar, etc.
│   │   ├── Settings/         # Settings and configuration
│   │   ├── Onboarding/       # First-launch experience
│   │   └── ui/               # Reusable UI components
│   ├── context/              # React Context providers
│   ├── data/                 # Static data (templates, etc.)
│   ├── hooks/                # Custom React hooks
│   ├── services/             # Business logic and APIs
│   │   ├── openRouter.ts     # OpenRouter API client
│   │   ├── ragService.ts     # RAG embeddings service
│   │   ├── modelsApi.ts      # Model fetching/filtering
│   │   └── localStorage.ts   # Browser storage
│   ├── styles/               # Global CSS and themes
│   ├── types/                # TypeScript type definitions
│   ├── utils/                # Utility functions
│   ├── App.tsx               # Root component
│   └── main.tsx              # Application entry point
├── .gitignore
├── .prettierrc               # Code formatting config
├── eslint.config.js          # Linting rules
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── vite.config.ts            # Vite build configuration

Key Files

src/services/openRouter.ts: OpenRouter API integration for chat and image generation
src/services/ragService.ts: Local embeddings using @xenova/transformers
src/components/Chat/ChatInputModern.tsx: Main chat input component
src/components/Chat/MessageBubbleModern.tsx: Message display component
vite.config.ts: Vite configuration

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});

Available Scripts

PolyChat-AI includes several npm scripts for development and production:

Command	Description
`npm run dev`	Start development server with HMR
`npm run build`	TypeScript type check + production build
`npm run preview`	Preview the production build locally
`npm run lint`	Check code quality with ESLint
`npm run format`	Format code with Prettier

Development Workflow

Start Development

npm run dev

Make your changes in src/ and see them reflected instantly.

Check Code Quality

npm run lint

Fix any linting errors before committing.

Format Code

npm run format

Ensure consistent code formatting.

Build for Production

npm run build

Creates an optimized production build in the dist/ directory.

Preview Production Build

npm run preview

Test the production build locally before deployment.

Configuration

Environment Variables

PolyChat-AI doesn’t require environment variables for local development. All configuration is done through the UI and stored in localStorage. However, if you’re deploying to production, you may want to pre-configure certain settings. Create a .env file in the root directory:

.env

# Not required - all config is done via UI
# This is only for advanced deployment scenarios
VITE_DEFAULT_MODEL=openai/gpt-4o
VITE_APP_NAME=PolyChat-AI

Never commit API keys to version control. The .gitignore file already excludes .env files, but always double-check before committing.

Customizing Vite Configuration

To customize the build process, edit vite.config.ts:

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000, // Change default port
    open: true, // Auto-open browser
  },
  build: {
    outDir: 'build', // Change output directory
    sourcemap: true, // Generate source maps
  },
});

Troubleshooting

Common Installation Issues

Port 5173 already in use

If port 5173 is already occupied:

Stop the process using port 5173
Or change the port in vite.config.ts:
```
server: {
  port: 3000
}
```

npm install fails

If npm install fails:

Clear npm cache: npm cache clean --force
Delete node_modules and package-lock.json
Run npm install again
If still failing, try using Node.js LTS version

TypeScript errors on build

If you encounter TypeScript errors:

Check that you’re using TypeScript ~5.8.3
Delete node_modules and reinstall
Run npx tsc --noEmit to see detailed errors

Slow initial load

The first load may be slow due to:

@xenova/transformers downloading ML models
Vite optimizing dependencies

Subsequent loads will be much faster due to caching.

More Troubleshooting Help

View the complete troubleshooting guide for more solutions

Next Steps

Now that you have PolyChat-AI running locally:

Quick Start Guide

Learn how to use PolyChat-AI effectively

Core Features

Explore all available features

Configuration

Customize PolyChat-AI to your preferences

Contributing

Learn how to contribute to the project

Deployment

Ready to deploy your own instance of PolyChat-AI?

Deploy to Vercel (Recommended)

The easiest way to deploy PolyChat-AI is with Vercel:

Click the button above
Connect your GitHub account
Configure your project
Deploy automatically

Build for Production

To build manually:

npm run build

This creates a production-ready build in the dist/ directory that can be deployed to any static hosting service:

Vercel
Netlify
GitHub Pages
Cloudflare Pages
AWS S3 + CloudFront

The production build is optimized with code splitting, minification, and tree-shaking for maximum performance.

Get Started

Core Features

Guides

Advanced

Prerequisites

Node.js

Package Manager

Git

OpenRouter API Key

Verify Prerequisites

Installation Steps

Project Structure

Key Files

Available Scripts

Development Workflow

Configuration

Environment Variables

Customizing Vite Configuration

Troubleshooting

Common Installation Issues

More Troubleshooting Help

Next Steps

Quick Start Guide

Core Features

Configuration

Contributing

Deployment

Deploy to Vercel (Recommended)

Build for Production

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Advanced

​Prerequisites

Node.js

Package Manager

Git

OpenRouter API Key

​Verify Prerequisites

​Installation Steps

​Project Structure

​Key Files

​Available Scripts

​Development Workflow

​Configuration

​Environment Variables

​Customizing Vite Configuration

​Troubleshooting

​Common Installation Issues

More Troubleshooting Help

​Next Steps

Quick Start Guide

Core Features

Configuration

Contributing

​Deployment

​Deploy to Vercel (Recommended)

​Build for Production

Build docs developers (and LLMs) love

Prerequisites

Verify Prerequisites

Installation Steps

Project Structure

Key Files

Available Scripts

Development Workflow

Configuration

Environment Variables

Customizing Vite Configuration

Troubleshooting

Common Installation Issues

Next Steps

Deployment

Deploy to Vercel (Recommended)

Build for Production