Firebase Setup

Study Sync uses Firebase for user authentication and session management. This guide covers both client-side and server-side Firebase configuration.

Overview

Firebase is configured in two parts:

Client SDK (src/lib/firebase.js) - Handles user authentication in the browser
Admin SDK (src/lib/firebase-admin.js) - Server-side authentication and user management

Prerequisites

Google/Firebase account
Firebase project created in Firebase Console

Client-side Setup

Step 1: Create Firebase Project

Create new project

Go to Firebase Console and click “Add project”.

Enable Authentication

Navigate to Authentication > Sign-in method and enable your desired providers:

Email/Password
Google
GitHub
Other providers as needed

Go to Project Settings > General and click “Add app” > Web icon.

Step 2: Get Configuration Values

In Firebase Console, go to Project Settings > General > Your apps section. Copy the Firebase configuration object values:

const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.firebasestorage.app",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abc123"
};

Step 3: Configure Environment Variables

Add these to your .env.local file:

NEXT_PUBLIC_FIREBASE_API_KEY=AIza...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abc123

All Firebase client variables must be prefixed with NEXT_PUBLIC_ to be accessible in the browser.

Client Configuration Code

The Firebase client is configured in src/lib/firebase.js:

import { initializeApp, getApps, getApp } from "firebase/app";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
};

// Validate that all required config values are present
if (typeof window !== "undefined") {
  const missingVars = Object.entries(firebaseConfig)
    .filter(([key, value]) => !value)
    .map(([key]) => key);

  if (missingVars.length > 0) {
    console.error("Missing Firebase configuration variables:", missingVars);
    console.error("Current config:", firebaseConfig);
  }
}

// Initialize Firebase only if it hasn't been initialized already
const app = getApps().length === 0 ? initializeApp(firebaseConfig) : getApp();
const auth = getAuth(app);

export { app, auth };

Server-side Setup (Admin SDK)

The Firebase Admin SDK allows server-side operations like verifying ID tokens and managing users.

Step 1: Generate Service Account Key

Navigate to Service Accounts

In Firebase Console, go to Project Settings > Service Accounts.

Generate new key

Click “Generate new private key” and confirm. This downloads a JSON file.

Secure the file

Store the serviceAccountKey.json file securely. Never commit it to version control.

The service account key grants full admin access to your Firebase project. Keep it secure and never expose it publicly.

Step 2: Encode Service Account Key

The service account key must be base64-encoded to store as an environment variable:

Linux/Mac
Windows PowerShell
Node.js

base64 -w 0 serviceAccountKey.json

Copy the output (it will be a long string).

[Convert]::ToBase64String([System.IO.File]::ReadAllBytes("serviceAccountKey.json"))

Copy the output from PowerShell.

const fs = require('fs');
const key = fs.readFileSync('serviceAccountKey.json');
console.log(key.toString('base64'));

Step 3: Set Environment Variable

Add the base64-encoded key to .env.local:

FIREBASE_SERVICE_ACCOUNT_KEY=eyJ0eXBlIjoic2VydmljZV9hY2NvdW50IiwicHJvamVjdF9pZCI6InlvdXItcHJvamVjdCIsInByaXZhdGVfa2V5X2lkIjoiLi4uIn0=

This variable should NOT have the NEXT_PUBLIC_ prefix as it must remain server-side only.

Admin Configuration Code

The Firebase Admin SDK is configured in src/lib/firebase-admin.js:

import admin from "firebase-admin";

/**
 * Firebase Admin SDK Configuration for Next.js
 * Initializes Firebase Admin with service account credentials
 */

if (!admin.apps.length) {
  try {
    const decoded = Buffer.from(
      process.env.FIREBASE_SERVICE_ACCOUNT_KEY,
      "base64"
    ).toString("utf8");

    const serviceAccount = JSON.parse(decoded);

    admin.initializeApp({
      credential: admin.credential.cert(serviceAccount),
    });

    console.log("✅ Firebase Admin SDK initialized");
  } catch (error) {
    console.error("❌ Failed to initialize Firebase Admin SDK:", error.message);
    throw error;
  }
}

export default admin;

Authentication Methods

Study Sync supports multiple authentication providers:

Email/Password

Enable in Firebase Console: Authentication > Sign-in method > Email/Password
Toggle “Enable” and save

Enable in Firebase Console: Authentication > Sign-in method > Google
Toggle “Enable”
Set project support email
Save changes

Create OAuth App in GitHub Settings
Get Client ID and Client Secret
Enable GitHub in Firebase Console
Add Client ID and Secret
Copy Authorization callback URL from Firebase and add to GitHub OAuth app

Security Rules

Study Sync uses Firebase Authentication tokens for API route protection. Tokens are verified server-side using the Admin SDK.

Token Verification Example

import admin from '@/lib/firebase-admin';

export async function verifyIdToken(token) {
  try {
    const decodedToken = await admin.auth().verifyIdToken(token);
    return { valid: true, uid: decodedToken.uid };
  } catch (error) {
    return { valid: false, error: error.message };
  }
}

Testing Configuration

Verify Client Setup

Start your development server
Open browser console
Check for Firebase configuration errors
If configured correctly, you should see no errors

Verify Admin Setup

Check server logs when starting the application
Look for: ✅ Firebase Admin SDK initialized
If you see errors, verify your base64-encoded key is correct

Troubleshooting

”Missing Firebase configuration variables”

Cause: One or more NEXT_PUBLIC_FIREBASE_* variables are missing or empty. Solution: Verify all six client variables are set in .env.local and restart your dev server.

”Failed to initialize Firebase Admin SDK”

Cause: Invalid or incorrectly encoded service account key. Solutions:

Verify the base64 encoding is correct (no line breaks)
Ensure the service account JSON is valid
Check that the key hasn’t been revoked in Firebase Console

”Firebase App already initialized”

Cause: Hot reload in development can cause multiple initialization attempts. Solution: The code already handles this with getApps().length === 0 check. If you still see issues, restart your dev server.

Authentication not working

Check:

Sign-in method is enabled in Firebase Console
Authorized domains include your deployment domain (Project Settings > Authorized domains)
Browser console for specific error messages

Production Deployment

Environment Variables

Set all Firebase environment variables in your hosting platform:

Vercel: Project Settings > Environment Variables
Netlify: Site Settings > Environment Variables
Other platforms: Refer to platform documentation

Authorized Domains

Add your production domain to Firebase authorized domains:

Go to Authentication > Settings > Authorized domains
Click “Add domain”
Enter your production domain (e.g., yourdomain.com)

Always use separate Firebase projects for development and production environments.

Security Best Practices

Rotate service account keys regularly (every 90 days recommended)
Use environment-specific projects (dev, staging, production)
Enable App Check for additional security
Monitor authentication logs for suspicious activity
Set up billing alerts to prevent quota abuse
Implement rate limiting on sensitive operations

Get Started

Core Features

User Guides

Configuration

Architecture

Overview

Prerequisites

Client-side Setup

Step 1: Create Firebase Project

Step 2: Get Configuration Values

Step 3: Configure Environment Variables

Client Configuration Code

Server-side Setup (Admin SDK)

Step 1: Generate Service Account Key

Step 2: Encode Service Account Key

Step 3: Set Environment Variable

Admin Configuration Code

Authentication Methods

Email/Password

Security Rules

Token Verification Example

Testing Configuration

Verify Client Setup

Verify Admin Setup

Troubleshooting

”Missing Firebase configuration variables”

”Failed to initialize Firebase Admin SDK”

”Firebase App already initialized”

Authentication not working

Production Deployment

Environment Variables

Authorized Domains

Security Best Practices

Resources

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

Architecture

​Overview

​Prerequisites

​Client-side Setup

​Step 1: Create Firebase Project

​Step 2: Get Configuration Values

​Step 3: Configure Environment Variables

​Client Configuration Code

​Server-side Setup (Admin SDK)

​Step 1: Generate Service Account Key

​Step 2: Encode Service Account Key

​Step 3: Set Environment Variable

​Admin Configuration Code

​Authentication Methods

​Email/Password

​Google Sign-In

​GitHub Sign-In

​Security Rules

​Token Verification Example

​Testing Configuration

​Verify Client Setup

​Verify Admin Setup

​Troubleshooting

​”Missing Firebase configuration variables”

​”Failed to initialize Firebase Admin SDK”

​”Firebase App already initialized”

​Authentication not working

​Production Deployment

​Environment Variables

​Authorized Domains

​Security Best Practices

​Resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Client-side Setup

Step 1: Create Firebase Project

Step 2: Get Configuration Values

Step 3: Configure Environment Variables

Client Configuration Code

Server-side Setup (Admin SDK)

Step 1: Generate Service Account Key

Step 2: Encode Service Account Key

Step 3: Set Environment Variable

Admin Configuration Code

Authentication Methods

Email/Password

Google Sign-In

GitHub Sign-In

Security Rules

Token Verification Example

Testing Configuration

Verify Client Setup

Verify Admin Setup

Troubleshooting

”Missing Firebase configuration variables”

”Failed to initialize Firebase Admin SDK”

”Firebase App already initialized”

Authentication not working

Production Deployment

Environment Variables

Authorized Domains

Security Best Practices

Resources