Quick Start

From zero to working Firebase integration in minutes.

1. Initialize

Create a single shared instance. Refirebase reads your Firebase config from environment variables automatically — no config object needed.

lib/firebase.ts

// lib/firebase.ts
import { Refirebase } from 'refirebase';

// Reads FIREBASE_* env vars automatically
export const { db, auth, analytics } = new Refirebase();

2. Firestore

Simple verb-based API for Firestore. No more building Query objects or importing dozens of functions.

Firestore

// Get all docs from a collection
const users = await db.firestore.get('users');

// Query with filters
const admins = await db.firestore.get('users', {
  where: { role: 'admin' },
  orderBy: [{ field: 'created_at', direction: 'desc' }],
  limit: 10,
});

// Add a document (auto-generated ID + timestamps)
const newUser = await db.firestore.add('users', {
  name: 'Alice',
  email: 'alice@example.com',
  role: 'user',
});

// Live updates
const unsubscribe = db.firestore.subscribe('users', (docs) => {
  console.log('users updated:', docs);
});

3. Auth

Multiple auth methods with typed error returns. No try/catch needed — errors are returned as { data, error }.

auth

// Sign in with Google
const { data, error } = await auth.handleProviderSignIn('google');

// Sign up with email
const { data, error } = await auth.handleEmailSignUp(
  'alice@example.com',
  'password123',
  { displayName: 'Alice' },
);

// Sign out
await auth.handleSignOut();

💡

Every method returns { data, error }. The error includes a readable code and message — no more opaque Firebase error objects.

4. React hooks

Wrap your app in RefirebaseProvider once, then use any hook anywhere.

React

// app/layout.tsx
import { RefirebaseProvider } from 'refirebase/react';
import { firebase } from '@/lib/firebase';

export default function Layout({ children }) {
  return (
    <RefirebaseProvider instance={firebase}>
      {children}
    </RefirebaseProvider>
  );
}

// components/UserList.tsx
import { useAuth, useCollection } from 'refirebase/react';

export function UserList() {
  const { user, signInWithGoogle } = useAuth();
  const { data, loading } = useCollection('users');

  if (!user) return <button onClick={signInWithGoogle}>Sign in</button>;
  if (loading) return <p>Loading...</p>;

  return (
    <ul>
      {data.map((u) => <li key={u.id}>{u.name}</li>)}
    </ul>
  );
}

5. React Native / Expo

Mobile projects use the exact same imports! Metro bundler automatically resolves to the native implementation, which swaps popup-based auth for credential-based auth, and provides a uriToBlob helper for uploading device files.

React Native

// app/firebase.ts (React Native / Expo)
import { Refirebase } from 'refirebase';
export const firebase = new Refirebase();

// Sign in with Google (native SDK)
import { GoogleSignin } from '@react-native-google-signin/google-signin';
const { idToken } = await GoogleSignin.signIn();
const { data, error } = await firebase.auth.handleGoogleSignIn({ idToken });

// Upload from device
import { uriToBlob } from 'refirebase';
const blob = await uriToBlob(pickerResult.uri);
await firebase.db.storage.upload('avatars/me.jpg', blob);

← PreviousConfiguration Next →Firestore — get