Installation Guide

Overview

This guide covers everything you need to install, configure, and deploy Ai Studio for production use. For a faster local setup, see the Quickstart Guide.

System Requirements

Development Environment

Node.js

Version 18.0+ requiredRecommended: Node.js 20 LTS

Package Manager

npm (included with Node.js)Or use yarn/pnpm if preferred

Git

Latest versionFor cloning and version control

Code Editor

VS Code recommendedWith TypeScript/React extensions

Cloud Services

Firebase Account

Free tier supports small to medium restaurants
Paid tier (Blaze) required for Netlify Functions
Create account

Google Cloud Account

Needed for Gemini API access
Free tier includes generous AI quotas
Get started

Netlify Account (Optional)

For hosting and serverless functions
Free tier available
Sign up

Installation Steps

1. Clone the Repository

git clone <your-ai-studio-repo-url>
cd ai-studio

2. Install Dependencies

Install all required packages:

npm install

View Complete Dependency List

From package.json:

{
  "dependencies": {
    "@firebase/app": "^0.14.5",
    "@firebase/firestore": "^4.9.2",
    "@google/genai": "^1.15.0",
    "@netlify/functions": "^4.2.5",
    "firebase": "^12.5.0",
    "html-to-image": "^1.11.11",
    "marked": "^13.0.2",
    "motion": "^12.34.3",
    "qrcode": "^1.5.3",
    "react": "^19.1.1",
    "react-dom": "^19.1.1"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.2.1",
    "@types/node": "^22.14.0",
    "@vitejs/plugin-react": "^5.0.0",
    "autoprefixer": "^10.4.27",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.2.1",
    "typescript": "~5.8.2",
    "vite": "^6.2.0"
  }
}

3. Firebase Project Setup

Create Firebase Project

Go to Firebase Console
Click “Add project” or “Create a project”
Enter project name (e.g., “ai-studio-production”)
Choose whether to enable Google Analytics
Click “Create project” and wait for initialization

Enable Firestore Database

In the Firebase Console, click “Firestore Database”
Click “Create database”
For development: Choose “Start in test mode”
For production: Choose “Start in production mode”
Select a location (choose closest to your users)
Click “Enable”

Test mode allows unrestricted read/write access for 30 days. You MUST configure security rules before going to production.

Configure Security Rules

For production, set up proper Firestore security rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Products are public read, admin write
    match /products/{document=**} {
      allow read: if true;
      allow write: if request.auth != null;
    }
    
    // Orders are created by anyone, but only readable by admins
    match /orders/{document=**} {
      allow create: if true;
      allow read, update, delete: if request.auth != null;
    }
    
    // Reservations same as orders
    match /reservations/{document=**} {
      allow create: if true;
      allow read, update, delete: if request.auth != null;
    }
    
    // Tables, settings, and admin data require authentication
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

Adjust these rules based on your security requirements. Consider implementing authentication for better security.

Get Firebase Configuration

Click the gear icon ⚙️ → “Project settings”
Scroll to “Your apps” section
Click the web icon </> to add a web app
Register app with nickname (e.g., “Ai Studio Web”)
Copy the firebaseConfig object

Example configuration:

const firebaseConfig = {
  apiKey: "AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  authDomain: "ai-studio-prod.firebaseapp.com",
  projectId: "ai-studio-prod",
  storageBucket: "ai-studio-prod.appspot.com",
  messagingSenderId: "123456789012",
  appId: "1:123456789012:web:abcdef123456",
  measurementId: "G-ABCDEFGHIJ"
};

4. Gemini API Configuration

Get API Key

Visit Google AI Studio
Sign in with your Google account
Click “Get API key” or “Create API key”
Select “Create API key in new project” or choose existing project
Copy the generated key (format: AIzaSy...)

Store your API key securely. Never commit it to version control or expose it in client-side code.

Understand API Usage

The Gemini API is used in services/geminiService.ts:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ 
  apiKey: process.env.API_KEY! 
});

export const sendMessageToGemini = async (
  history: ChatMessage[], 
  actionLock: 'order' | 'reservation' | null = null
): Promise<{ text: string }> => {
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: formattedHistory,
    config: {
      systemInstruction: getSystemInstruction(actionLock),
    },
  });
  return { text: response.text };
};

The system uses Gemini 2.5 Flash for fast, cost-effective responses. You can switch to gemini-2.5-pro for more complex reasoning if needed.

5. Environment Configuration

Create Environment File

Copy the example environment file:

cp .env.example .env.local

Or create a new .env.local file in the project root.

Configure All Variables

Edit .env.local with your actual values:

.env.local

# ===========================================
# Gemini AI Configuration
# ===========================================
GEMINI_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# ===========================================
# Firebase Configuration
# ===========================================
VITE_FIREBASE_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789012
VITE_FIREBASE_APP_ID=1:123456789012:web:abcdef123456
VITE_FIREBASE_MEASUREMENT_ID=G-ABCDEFGHIJ

# ===========================================
# Application Configuration
# ===========================================
# Optional: Base URL for QR codes and deep links
# For development, use http://localhost:3000
# For production, use your actual domain
VITE_APP_URL=https://your-domain.com

All variables prefixed with VITE_ are exposed to the client-side code. The GEMINI_API_KEY without prefix is used server-side only.

Verify Configuration

The Firebase configuration is loaded in services/firebase.ts:

const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
  appId: import.meta.env.VITE_FIREBASE_APP_ID,
  measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID
};

const app = getApps().length === 0 
  ? initializeApp(firebaseConfig) 
  : getApp();
const db = getFirestore(app);

6. Build Configuration

Review and customize vite.config.ts if needed:

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

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, '.', '');
  return {
    server: {
      port: 3000,
      host: '0.0.0.0',
    },
    plugins: [react()],
    define: {
      'process.env.API_KEY': JSON.stringify(env.GEMINI_API_KEY),
      'process.env.GEMINI_API_KEY': JSON.stringify(env.GEMINI_API_KEY)
    },
    resolve: {
      alias: {
        '@': path.resolve(__dirname, '.'),
      }
    }
  };
});

Configuration Options Explained

server.port: Development server port (default: 3000)
server.host: Bind to all network interfaces for LAN access
plugins: Enables React Fast Refresh for hot reloading
define: Injects environment variables at build time
resolve.alias: Enables @/ imports for cleaner paths

Running the Application

Development Mode

Start the development server with hot reload:

npm run dev

Access the application:

Local: http://localhost:3000
Network: http://YOUR_IP:3000 (shown in terminal)

Production Build

Create an optimized production build:

npm run build

This generates static files in the dist/ directory.

Preview Production Build

Test the production build locally:

npm run preview

Deployment Options

Option 1: Netlify (Recommended)

Install Netlify CLI

npm install -g netlify-cli

netlify login

Initialize Netlify

netlify init

Follow the prompts to connect your repository.

Configure Build Settings

Ensure netlify.toml exists (it should be in the repo):

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Set Environment Variables

In Netlify dashboard:

Go to Site settings → Environment variables
Add all variables from your .env.local
Save changes

Deploy

netlify deploy --prod

Option 2: Vercel

Install Vercel CLI

npm install -g vercel

Deploy

vercel

Follow prompts to configure and deploy.

Add Environment Variables

In Vercel dashboard:

Go to Project Settings → Environment Variables
Add all .env.local variables
Redeploy: vercel --prod

Option 3: Traditional Hosting

Build the project

npm run build

Upload dist/ folder

Upload the contents of dist/ to your web server.

Configure server

Ensure your server redirects all routes to index.html for client-side routing.Nginx example:

location / {
  try_files $uri $uri/ /index.html;
}

Apache example:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Post-Installation Setup

Initial Data Configuration

Access Admin Panel

Open your deployed application
Scroll to the footer
Click “Admin” link

Configure Products

Go to “Productos” tab
Click ”+ Nuevo Producto”
Add your menu items with:
- Name
- Category
- Price
- Description
- Image URL (optional)

Set Business Hours

Go to “Configuración” tab
Find “Horario” section
Set opening hours for each day
Add multiple time slots if needed (e.g., lunch and dinner)

Create Tables

Go to “Mesas” tab
Add tables with:
- Name (e.g., “Mesa 1”)
- Capacity
- Allow reservations checkbox

Configure Reservation Settings

In “Configuración” → “Reservas”:

Duration: How long reservations last (e.g., 120 minutes)
Min booking time: Minimum advance notice (e.g., 60 minutes)
Slot interval: Reservation time increments (e.g., 30 minutes)

Activate Bots

In “Configuración”:

Find “Bot Web” section
Toggle to activate the web chat assistant
(Optional) Configure WhatsApp bot if using

Troubleshooting

Build Errors

TypeScript errors during build

Symptom: Type errors prevent compilationSolution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check TypeScript version
npm list typescript

Ensure TypeScript version is ~5.8.2 as specified in package.json.

Module resolution errors

Symptom: Cannot find module ’@/…’ or similarSolution: Verify tsconfig.json has correct paths:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Runtime Errors

Firebase initialization failed

Symptom: Console shows Firebase configuration errorsSolution:

Verify all VITE_FIREBASE_* variables in .env.local
Ensure no extra spaces or quotes in values
Restart dev server after environment changes
Check Firebase Console that Firestore is enabled

Gemini API errors (401, 403)

Symptom: AI assistant doesn’t respond, console shows authentication errorsSolution:

Verify GEMINI_API_KEY is correct
Check API key is enabled at AI Studio
Ensure no billing/quota issues in Google Cloud Console
Test API key with a simple curl:

curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_API_KEY"

Chat button disabled

Symptom: Floating chat button appears grayed outSolution: The Slice bot needs to be activated:

Go to Admin Panel
Navigate to “Configuración” tab
Find “Bot Web” section
Click toggle to activate

Performance Issues

Slow Firebase queries

Solution: Add Firestore indexes for common queries:

Check browser console for index creation links
Click the link to auto-create the index
Or manually create in Firebase Console → Firestore → Indexes

Large bundle size

Solution:

Verify tree-shaking is working
Check for unnecessary imports
Use production build: npm run build
Consider code splitting for admin panel

Security Best Practices

Critical: Implement these security measures before going to production:

Environment Variables
- Never commit .env.local to git
- Use different API keys for dev/prod
- Rotate keys periodically
Firestore Security Rules
- Don’t use test mode in production
- Implement proper authentication
- Validate data on write operations
- Use field-level security
API Rate Limiting
- Consider implementing rate limiting for Gemini API
- Monitor usage in Google Cloud Console
- Set up billing alerts
CORS Configuration
- Configure Firebase to only accept requests from your domain
- Set up proper CORS headers in Netlify Functions
Data Validation
- Validate all user inputs
- Sanitize data before storing in Firestore
- Implement server-side validation for critical operations

Next Steps

API Reference

Explore the codebase APIs and services

WhatsApp Integration

Set up the WhatsApp bot for mobile customers

Admin Features

Master the admin dashboard capabilities

Core Features

Learn about AI assistants and other features

Support

If you encounter issues not covered in this guide:

Check browser console (F12) for error messages
Review Firebase Console logs
Verify environment variables are loaded correctly
Test with a fresh installation

For production deployments, consider implementing monitoring and logging solutions to track errors and performance metrics.

Get Started

Core Features

Admin Dashboard

Integrations

Configuration

​Overview

​System Requirements

​Development Environment

Node.js

Package Manager

Git

Code Editor

​Cloud Services

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​3. Firebase Project Setup

​4. Gemini API Configuration

​5. Environment Configuration

​6. Build Configuration

​Running the Application

​Development Mode

​Production Build

​Preview Production Build

​Deployment Options

​Option 1: Netlify (Recommended)

​Option 2: Vercel

​Option 3: Traditional Hosting

​Post-Installation Setup

​Initial Data Configuration

​Troubleshooting

​Build Errors

​Runtime Errors

​Performance Issues

​Security Best Practices

​Next Steps

API Reference

WhatsApp Integration

Admin Features

Core Features

​Support

Build docs developers (and LLMs) love

Overview

System Requirements

Development Environment

Cloud Services

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Firebase Project Setup

4. Gemini API Configuration

5. Environment Configuration

6. Build Configuration

Running the Application

Development Mode

Production Build

Preview Production Build

Deployment Options

Option 1: Netlify (Recommended)

Option 2: Vercel

Option 3: Traditional Hosting

Post-Installation Setup

Initial Data Configuration

Troubleshooting

Build Errors

Runtime Errors

Performance Issues

Security Best Practices

Next Steps

Support