Setup Guide

Setup Guide

Complete guide to set up and configure your Firebase React application from scratch.

Table of Contents

1. Prerequisites
2. Initial Setup
3. Firebase Project Setup
4. Environment Configuration
5. Local Development
6. Verify Setup

---

Prerequisites

Before starting, ensure you have:

Required Software

• Node.js (v18 or higher) - Download
• npm (comes with Node.js) or yarn
• Git - Download
• Code Editor - VS Code recommended

Required Accounts

• GitHub Account - For version control
• Google Account - For Firebase access

Install Firebase CLI

npm install -g firebase-tools

Verify installation:

firebase --version

---

Initial Setup

Step 1: Clone the Repository

git clone https://github.com/ThanuMahee12/firebase-react-template.git
cd firebase-react-template

Step 2: Install Dependencies

Using npm:

npm install

Using yarn:

yarn install

This will install all dependencies listed in package.json:

• React & React DOM
• Firebase SDK
• Redux Toolkit & React-Redux
• React Router DOM
• React Icons
• Vite & Build tools

---

Firebase Project Setup

Step 1: Create Firebase Project

1. Go to Firebase Console
2. Click "Add Project" or "Create a project"
3. Enter project name (e.g., my-awesome-app)
4. Disable Google Analytics (optional for free tier)
5. Click "Create Project"
6. Wait for project creation

Step 2: Register Your Web App

1. In Firebase Console, click the Web icon </>
2. Enter an App nickname (e.g., My App)
3. Don't check "Also set up Firebase Hosting" (we'll do this later)
4. Click "Register app"
5. Copy the configuration object - you'll need this soon

Example configuration:

{
  apiKey: "AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  authDomain: "my-app-12345.firebaseapp.com",
  projectId: "my-app-12345",
  storageBucket: "my-app-12345.appspot.com",
  messagingSenderId: "123456789012",
  appId: "1:123456789012:web:abcdef123456"
}

Step 3: Enable Firebase Services

Enable Authentication

1. In Firebase Console sidebar, click "Authentication"
2. Click "Get started"
3. Click on "Sign-in method" tab
4. Enable "Email/Password":
   • Click on "Email/Password"
   • Toggle "Enable"
   • Click "Save"
5. (Optional) Enable "Google" sign-in:
   • Click on "Google"
   • Toggle "Enable"
   • Select your support email
   • Click "Save"

Enable Firestore Database

1. In sidebar, click "Firestore Database"
2. Click "Create database"
3. Choose "Start in production mode" (we'll deploy rules later)
4. Select your Cloud Firestore location:
   • Choose closest to your users
   • Note: Location can't be changed later!
5. Click "Enable"

Enable Storage (Optional)

1. In sidebar, click "Storage"
2. Click "Get started"
3. Keep default security rules
4. Use same location as Firestore
5. Click "Done"

---

Environment Configuration

Step 1: Create Environment File

Copy the example file:

cp .env.example .env

On Windows:

copy .env.example .env

Step 2: Add Firebase Configuration

Open .env file and add your Firebase configuration:

VITE_FIREBASE_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
VITE_FIREBASE_AUTH_DOMAIN=my-app-12345.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=my-app-12345
VITE_FIREBASE_STORAGE_BUCKET=my-app-12345.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789012
VITE_FIREBASE_APP_ID=1:123456789012:web:abcdef123456

Important:

• All variables must start with VITE_ prefix
• Do NOT commit .env file (it's in .gitignore)
• Never share your .env file publicly

Step 3: Update Firebase Project ID

Edit .firebaserc file:

{
  "projects": {
    "default": "my-app-12345"
  }
}

Replace my-app-12345 with your actual Firebase project ID.

---

Local Development

Step 1: Start Development Server

npm run dev

You should see:

VITE v5.x.x ready in XXX ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

Step 2: Open in Browser

Open http://localhost:5173 in your browser.

You should see the template homepage with:

Firebase React Template
Get started by editing src/App.jsx

Step 3: Test Hot Module Replacement (HMR)

1. Open src/App.jsx in your editor
2. Change the text
3. Save the file
4. Browser should update automatically without refresh

---

Verify Setup

Check Firebase Connection

Create a test file src/firebase/test.js:

import { auth, db } from './config';

console.log('Firebase Auth:', auth);
console.log('Firebase Firestore:', db);

Import it in src/main.jsx:

import './firebase/test';

Check browser console - you should see Firebase objects logged.

Test Firestore

Add to src/firebase/test.js:

import { collection, addDoc } from 'firebase/firestore';

// Test write to Firestore
const testFirestore = async () => {
  try {
    const docRef = await addDoc(collection(db, 'test'), {
      message: 'Hello Firebase!',
      timestamp: new Date()
    });
    console.log('Document written with ID:', docRef.id);
  } catch (error) {
    console.error('Error adding document:', error);
  }
};

testFirestore();

Check Firebase Console → Firestore Database - you should see a test collection.

---

Common Issues

Error: "Firebase: Error (auth/invalid-api-key)"

• Check your VITE_FIREBASE_API_KEY in .env
• Make sure it starts with AIza
• Verify it matches Firebase Console

Error: "Module not found"

• Run npm install again
• Delete node_modules and package-lock.json, then reinstall
• Check Node.js version: node --version (should be 18+)

Environment variables not working

• Make sure variables start with VITE_ prefix
• Restart dev server after changing .env
• Use import.meta.env.VITE_FIREBASE_API_KEY to access values

Firestore permission denied

• Check firestore.rules file
• Make sure authentication is enabled
• Verify you're signed in when testing authenticated features

---

Next Steps

✅ Setup Complete! Now you can:

1. Configure Firebase - Set up security rules and advanced features
2. Understand Project Structure - Learn the codebase organization
3. Start Development - Build your application
4. Deploy Your App - Go live with Firebase Hosting

---

Need Help?

• 🐛 Report Issues
• 💬 Ask Questions
• 📖 Firebase Docs
• 📚 React Docs