Installation

This guide covers everything you need to install and deploy Arre, from local development to production hosting. Whether you’re setting up for the first time or deploying to Firebase Hosting, we’ve got you covered.

Prerequisites

Before installing Arre, ensure you have the following:

Required Software

Node.js 22.12+

Download from nodejs.org. Verify with node --version

npm Package Manager

Comes with Node.js. Verify with npm --version

Git

Version control system. Verify with git --version

Firebase CLI (Production)

Install with npm install -g firebase-tools

Firebase Account (Production Only)

For production deployment, you’ll need:

A Firebase account
A Firebase project with Spark plan (free) or Blaze plan (pay-as-you-go)
Enabled services: Authentication, Firestore, Functions, Storage, Hosting

For local development, you don’t need a Firebase account. The Firebase emulators run entirely offline.

Local Development Setup

Get Arre running on your machine with Firebase emulators for a complete local development environment.

Clone the Repository

git clone https://github.com/pedro3087/arre.git
cd arre

Replace pedro3087 with your GitHub username if you’ve forked the repository.

Install Dependencies

Install all Node.js packages:

npm install

This installs:

Package	Purpose
`[email protected]`	UI framework
`[email protected]`	Backend SDK
`[email protected]`	Build tool
`[email protected]`	Type safety
`[email protected]`	Animations
`[email protected]`	Charts
`[email protected]`	Icons
`[email protected]`	E2E testing
`[email protected]`	Emulators & deployment

Configure Environment Variables (Optional)

For local development, environment variables are optional because the app uses Firebase emulators. However, you can create a .env file for consistency:

# .env (optional for local development)
VITE_FIREBASE_API_KEY=demo-api-key
VITE_FIREBASE_AUTH_DOMAIN=demo-auth-domain
VITE_FIREBASE_PROJECT_ID=demo-project-id
VITE_FIREBASE_STORAGE_BUCKET=demo-storage-bucket
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=demo-app-id

// Arre automatically uses emulators in development
import { initializeApp } from 'firebase/app';
import { getAuth, connectAuthEmulator } from 'firebase/auth';
import { getFirestore, connectFirestoreEmulator } from 'firebase/firestore';

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
};

const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const db = getFirestore(app);

// Connect to emulators in development
if (import.meta.env.DEV) {
  connectAuthEmulator(auth, 'http://localhost:9099');
  connectFirestoreEmulator(db, 'localhost', 8080);
}

Never commit real Firebase credentials to version control. Add .env to your .gitignore file.

Start Firebase Emulators

Open a dedicated terminal window for emulators:

npm run emulators

This starts four local services:

Emulator	Port	Purpose
Auth	9099	Mock user authentication
Firestore	8080	Local database
Functions	5001	Cloud functions for AI import
Storage	9199	File uploads (PDFs, CSVs)

Emulator UI: Access at http://localhost:4000 to inspect data, view users, and monitor function calls.

Keep this terminal open! Closing it will stop all backend services.

Start Development Server

In a new terminal, start Vite:

npm run dev

The app starts at http://localhost:5173 with:

⚡ Hot module replacement (instant updates)
🔥 Firebase emulator connections
🎨 Full theme system (light/dark)
📊 Real-time Firestore sync

Verify Installation

Open http://localhost:5173 in your browser. You should see:

Redirect to Login: Automatic navigation to /login
Google Sign-In: Click “Continue with Google”
Mock Account Creation: Instant simulated authentication
Today View: Landing page with empty task list

✅ Success! Your local development environment is ready.

Production Deployment

Deploy Arre to Firebase Hosting for a production-ready, globally distributed application.

Production deployment requires a Firebase project on the Blaze plan (pay-as-you-go) because Cloud Functions are used for AI Magic Import.

Create Firebase Project

Go to Firebase Console
Click “Add project”
Enter project name (e.g., arre-prod)
Enable Google Analytics (optional)
Create project

Enable Firebase Services

In your Firebase project, enable:

Authentication

Go to Authentication → Sign-in method
Enable Google provider
Add authorized domains (your production domain)

Firestore Database

Go to Firestore Database → Create database
Start in production mode
Choose a location (e.g., us-central1)
Deploy security rules from firestore.rules

Storage

Go to Storage → Get started
Use default settings
Deploy rules from storage.rules

Cloud Functions

Upgrade to Blaze plan (required)
Enable Cloud Functions API
Set up Secret Manager for GEMINI_API_KEY

Configure Firebase CLI

# Login to Firebase
firebase login

# Initialize project
firebase init

Select the following features:

✅ Firestore
✅ Functions
✅ Hosting
✅ Storage
✅ Emulators

# Use existing rules
? What file should be used for Firestore Rules? firestore.rules
? File firestore.rules already exists. Do you want to overwrite it? No

Set Environment Variables

Create a production .env file with your Firebase project credentials:

# .env.production
VITE_FIREBASE_API_KEY=your_production_api_key
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=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

Get these values from: Firebase Console → Project Settings → Your apps → Web app

Add .env.production to .gitignore to keep credentials secure.

Configure Gemini API Key

For AI Magic Import, set up the Gemini API key in Firebase Secret Manager:

# Add secret to Firebase
firebase functions:secrets:set GEMINI_API_KEY

# Enter your Gemini API key when prompted

Get your Gemini API key from Google AI Studio.

Build for Production

Build the optimized production bundle:

npm run build

This creates a dist/ directory with:

Minified JavaScript bundles
Optimized CSS
Code splitting for faster loads
Source maps for debugging

Expected output:

vite v7.3.1 building for production...
✓ 234 modules transformed.
dist/index.html                   0.45 kB │ gzip:  0.30 kB
dist/assets/index-a1b2c3d4.css   23.45 kB │ gzip: 12.34 kB
dist/assets/index-e5f6g7h8.js   234.56 kB │ gzip: 89.12 kB
✓ built in 3.45s

Deploy to Firebase

Deploy all services to production:

# Deploy everything
firebase deploy

# Or deploy specific services
firebase deploy --only hosting
firebase deploy --only firestore:rules
firebase deploy --only functions

Expected output:

=== Deploying to 'your-project-id'...

i  deploying firestore, functions, hosting, storage
✔  firestore: rules updated
✔  functions: deployed analyzeDocument
✔  hosting: deployed successfully
✔  storage: rules updated

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/your-project-id
Hosting URL: https://your-project-id.web.app

Your production app is now live at https://your-project-id.web.app!

Post-Installation Setup

After deploying to production, complete these steps:

Security Rules

Verify your Firestore and Storage rules are deployed correctly:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users can only access their own tasks
    match /tasks/{taskId} {
      allow read, write: if request.auth != null 
        && request.auth.uid == resource.data.userId;
    }
    
    // Users can only access their own projects
    match /projects/{projectId} {
      allow read, write: if request.auth != null 
        && request.auth.uid == resource.data.userId;
    }
  }
}

Analytics and Monitoring

Set up monitoring for production:

Firebase Performance: Track app performance metrics
Crashlytics: Monitor errors and crashes
Google Analytics: Track user engagement (if enabled)

CI/CD Pipeline (Optional)

Arre includes a GitHub Actions workflow for automated deployments:

.github/workflows/deploy.yml

name: Deploy to Firebase Hosting

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 22
      - run: npm install
      - run: npm run build
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          channelId: live

See the CI/CD Pipeline documentation in the source repository for details on the AI QA Agent integration.

Development Commands

Reference for all available npm scripts:

Command	Description
`npm run dev`	Start Vite development server (port 5173)
`npm run build`	Build production bundle to `dist/`
`npm run preview`	Preview production build locally
`npm run emulators`	Start Firebase emulators
`npm run test`	Run Playwright E2E tests
`npm run test:ui`	Run tests with Playwright UI

Troubleshooting

Build Fails with TypeScript Errors

Ensure you’re using TypeScript 5.9.3:

npm install [email protected] --save-dev
npm run build

Firebase Deploy Fails

Check that you’re logged in and have the correct project selected:

firebase login
firebase use --add
firebase projects:list

Functions Deploy Fails

Ensure you’re on the Blaze plan and have set the Gemini API key:

firebase projects:list
firebase functions:secrets:access GEMINI_API_KEY

Emulator Data Not Persisting

Export and import emulator data between sessions:

# Export on exit
firebase emulators:start --export-on-exit=./emulator-data

# Import on start
firebase emulators:start --import=./emulator-data

Next Steps

Backend Architecture

Learn about Firestore schema, security rules, and Cloud Functions

Testing Guide

Set up Playwright tests and understand the AI QA Agent

Features

Deep dive into Magic Import, metrics, and project management

API Reference

Explore the Firebase functions API and frontend hooks

Need help? Check out the GitHub Issues or contribute to the project!

Get Started

Core Features

User Guide

Installation

Installation

Prerequisites

Required Software

Node.js 22.12+

npm Package Manager

Git

Firebase CLI (Production)

Firebase Account (Production Only)

Local Development Setup

Production Deployment

Post-Installation Setup

Security Rules

Analytics and Monitoring

CI/CD Pipeline (Optional)

Development Commands

Troubleshooting

Next Steps

Backend Architecture

Testing Guide

Features

API Reference

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

​Installation

​Prerequisites

​Required Software

Node.js 22.12+

npm Package Manager

Git

Firebase CLI (Production)

​Firebase Account (Production Only)

​Local Development Setup

​Production Deployment

​Post-Installation Setup

​Security Rules

​Analytics and Monitoring

​CI/CD Pipeline (Optional)

​Development Commands

​Troubleshooting

​Next Steps

Backend Architecture

Testing Guide

Features

API Reference

Build docs developers (and LLMs) love

Installation

Prerequisites

Required Software

Firebase Account (Production Only)

Local Development Setup

Production Deployment

Post-Installation Setup

Security Rules

Analytics and Monitoring

CI/CD Pipeline (Optional)

Development Commands

Troubleshooting

Next Steps