Code.Build 💻

Firestore Tree Data Model

Jonathan Gamble — Sun, 22 Sep 2024 13:02:05 GMT

We often need to model tree data in Firestore. Nested comments, categories, graphs, and groups are just some examples. Modeling is difficult, but it can be done with a few hacks.

TL;DR

When you want to query nested data in Firestore, you must model the data so that one query can get all documents. This can be possible by using a long string for the path.

We Need One Query

You can easily model the data for multiple queries. The original thought was to query all posts where the parent equals some ID. If there were children, query them separately. The problem with this method is that you will have multiple calls to Firestore. While you would be reading the same documents, you don’t want to have several fetches to Firestore on one page, especially when it can be avoided.

Tree Demo in SvelteKit

This demo uses SvelteKit, so I recommend you read the Firebase SvelteKit post first. There are many advanced techniques, but I am only concentrating on the data model for this post. I use Firebase Client, but I could have equally used Firebase Admin with SvelteKit Form Actions.

Hierarchy

A tree is data that can belong to other data in a hierarchy. To nest data, we must use startsWith character hack mentioned in the Fuzzy Full-Text Search post. The algorithm will be slightly different, but we will order the path and parent variables to get the desired results.

Tree Data Model

We are building a comment system similar to a Reddit Clone, where people can comment on one post in a tree fashion.

Short Document ID

We will create a short ID for faster searching and longer string storage. Theoretically, a document can be as big as 1MB, so one field could be up to that large.

const id = doc(
    collection(db, 'comments')
).id.substring(0, 5);

This limits the document ID to 5 characters, although you can use whatever length you like.

Creating a Comment Document

We will create the document with a few fields.

export const addComment = async (event: SubmitEvent) => {

    const { text, parent: _parent, formElement } = getComment(event);

    const level = _parent.split('/').length + 1 || 1;
    const parent = _parent.split('/').join('_');

    const currentUser = auth.currentUser;

    if (!currentUser) {
        throw 'No user!';
    }

    // create short ID
    const id = doc(
        collection(db, 'comments')
    ).id.substring(0, 5);

    const path = parent ? `${parent}_${id}` : id;

    try {
        await setDoc(
            doc(db, `comments/${id}`),
            {
                createdBy: currentUser.uid,
                createdAt: serverTimestamp(),
                text,
                level,
                path,
                parent,
                votes: 0
            }
        );
        formElement.reset();

    } catch (e) {
        if (e instanceof FirebaseError) {
            console.error(e);
        }
    }
};

text field stores the comment
level stores the level number from the root
path stores the full path to the document. / will be replaced with _ for searching.
parent stores the full path to the parent document, or null. / will be replaced with _ for searching.
votes is not used in this demo, but could be used to create a voting mechanism similar to Reddit.

Deleting a Comment

When we delete a comment, we must also delete all of its children. We search for them, then use batch to delete them in a transaction.

export const deleteComment = async (path: string) => {

    const _path = path.split('/').join('_');

    const childrenSnap = await getDocs(
        query(
            collection(db, 'comments'),
            ...startsWith('path', _path)
        )
    );

    if (childrenSnap.empty) {
        throw 'No ids!';
    }

    const batch = writeBatch(db);

    try {
        childrenSnap.docs.map(doc => {
            batch.delete(doc.ref);
        });
        await batch.commit();
    } catch (e) {
        if (e instanceof FirebaseError) {
            console.error(e);
        }
    }
};

Starts With

We have a shorter version of the startsWith in Fuzzy Text Search. This allows you to search for something which starts with a character. We need to use it with the spread operator, as we cannot return more than one item, only an array of items.

export const startsWith = (
    fieldName: string,
    term: string
) => {
    return [
        orderBy(fieldName),
        startAt(term),
        endAt(term + '~')
    ];
};

Querying the Tree

We query the tree by searching for comments ordered by the parent document. If we want the votes feature, we order by the votes secondly. This demo does not use votes, but the feature could easily be added.

export const useComments = (
    term: string | null = null,
    levels: number[] = []
) => {

    const user = useUser();

    // filtering comments depend on user
    return derived<
        Readable,
        CommentType[]
    >(
        user, ($user, set) => {
            set([]);
            if (!$user) {
                return;
            }
            const queryConstraints = [];
            if (term) {
                const _term = term.split('/').join('_');
                queryConstraints.push(
                    where('path', '>=', _term),
                    where('path', '<=', _term + '~')
                );
            }
            if (levels?.length) {
                queryConstraints.push(
                    where('level', 'in', levels)
                );
            }
            return onSnapshot(
                query(
                    collection(db, 'comments'),
                    where('createdBy', '==', $user.uid),
                    orderBy('path'),
                    orderBy('votes', 'desc'),
                    ...queryConstraints
                ), (q) => set(snapToData(q))
            );
        });
};

If we enter a term when creating this query, it will only display items under that parent. This is where we need the startsWith hack again.

Snapshot Data

We must take our data and modify it in a tree format. Remember our data is sorted correctly, but we need to display it in a tree fashion.

export const snapToData = (
    q: QuerySnapshot
) => {

    // creates comment data from snapshot
    if (q.empty) {
        return [];
    }
    const comments = q.docs.map((doc) => {
        const data = doc.data({
            serverTimestamps: 'estimate'
        });
        const createdAt = data['createdAt'] as Timestamp;
        const comment = {
            ...data,
            path: data['path']?.split('_').join('/'),
            parent: data['parent']?.split('_').join('/'),
            createdAt: createdAt.toDate(),
            id: doc.id
        };
        return comment;
    }) as CommentType[];

    // create children from IDs
    const _comments = nestedComments(comments);
    if (dev) {
        console.log(_comments);
    }
    return _comments;
}

Our parent and path are reformed to a path format.

Threaded Comments

To get our data in the right place, we need to put all children in a children array, and all their children in a children array etc. This will allow us to display the data correctly in our component template.

export const nestedComments = (comments: CommentType[]) => {
    const commentMap: Record = {};
    const result: CommentType[] = [];

    // Initialize the commentMap and set up children arrays
    for (let i = 0; i < comments.length; i++) {
        const comment = comments[i];
        comment.children = [];
        commentMap[comment.path] = comment;
    }

    // Nest comments under their parents, or handle cases where parent is missing
    for (const comment of comments) {
        // If the comment doesn't have a parent, add it to the top-level result immediately
        if (!comment.parent) {
            result.push(comment);
            continue;
        }

        // If the parent is not in the dataset, handle the child as a top-level comment (or change as needed)
        const parent = commentMap[comment.parent];
        if (!parent) {
            result.push(comment);
            continue;
        }

        // Add the comment to the parent's children array if the parent exists
        parent.children!.push(comment);
    }

    return result;
};

Recursive Component

Now our data is ready to be displayed recursively in our component.



{#each comments as comment}
	
		{#if comment.children?.length}
			
		{/if}
	
{/each}

Depth

Finally, we may want to display only a certain depth in our tree. Remember, a depth is calculated from the current post in whatever position it may be in. For example, a comment in the 5th position but the 3rd position on that page will have a depth of 5 on the main page and 3 on that comment page.

where('level', 'in', levels)

We calculate the levels on that page and add them to the query in an array (or multiple where clauses). Three positions starting at level 3, will have a value of [3, 4, 5] in the levels array. This works as a filter, so we don’t over-fetch unneeded data.

About the Demo Tree

This demo creates each comment tree using the user’s ID. A real comment tree will probably use a post ID. This is only for demo purposes, so users can have their own tree; we don’t want spam.

Bonus: Votes

With votes being the second orderBy clause, you could easily modify this demo to be a Reddit Clone. Up and Down clicks on the votes would increment the votes counter on the post. I didn’t do that for simplification, but it would be an easy addition.

⚠️ Don’t forget to add the necessary indexes from the console.log when you run the demo locally using your database.

Demo: Vercel Serverless

Repo: GitHub

Passwordless Login in Firebase

Jonathan Gamble — Sun, 15 Sep 2024 13:00:00 GMT

I’m a huge fan of passwordless login. You will notice I do not have any articles on creating, resetting, or changing a password. I hate passwords. We do not need them in 2024, and we should not design an application that still uses them. Not only are they insecure, they require more work to implement. Let’s simplify, shall we?

TL;DR

Passwordless login is the future. You can log in with only an email using a Magic Link. While you can attach the email address to the link, Firebase recommends saving the email address in the local storage for retrieval. Passwords are insecure.

Magic Link Login

Our application will request an email from the user. The email is saved to the local storage. The user will receive an email confirming their email address. When the user clicks on the link, the login page obtains the email address from the local storage and logs in. They must confirm their email address if they click the link from a different device.

Note on SvelteKit

This demo uses SvelteKit, but all premises are the same for any framework. See the SvelteKit Setup for Firebase configuration.

Login Functions

First, we need to send the magic link.

export const sendMagicLink = async (
    email: string,
    originURL: string
) => {
    try {
        await sendSignInLinkToEmail(auth, email, {
            handleCodeInApp: true,
            url: originURL + '/auth/callback'
        });
    } catch (e) {
        if (e instanceof FirebaseError) {
            console.error(e);
            return e;
        }
    }
};

We also need to sign in using the magic link.

export const signInWithMagic = async (
    email: string,
    url: string
) => {
    try {
        await signInWithEmailLink(auth, email, url);
    } catch (e) {
        if (e instanceof FirebaseError) {
            console.error(e);
            return e;
        }
    }
};

Finally, we should be able to test if the sign in URL is valid.

export const isMagicLinkURL = (url: string) => {
    return isSignInWithEmailLink(auth, url);
};

Firebase Helper

This is optional, but it allows you to check for a user immediately in the loader function. This can only run on the browser. If you need server authentication, see Server App or Firebase Admin.

export const getUser = async () =>
    new Promise((resolve, reject) => {
        const unsubscribe = onIdTokenChanged(auth, (user) => {
            unsubscribe();
            resolve(user);
        }, (error) => {
            unsubscribe();
            reject(error);
        });
    });

📝 You should not use Svelte Stores in a load function, but you can use promises.

📝 You must wait for onIdTokenChanged or onAuthStateChanged as auth.currentUser does not WAIT for the latest value.

Login Page

The login page at /login works as expected.

Route Guard

We create a route guard in the loader function at page.ts using the getUser() method.

import { getUser } from '$lib/use-user';
import { redirect } from '@sveltejs/kit';
import type { PageLoad } from './$types';
import { browser } from '$app/environment';

export const load: PageLoad = async () => {

    if (!browser) {
        return {
            loading: true
        };
    }

    const loggedIn = !!(await getUser());

    if (loggedIn) {
        return redirect(302, '/');
    }
};

You should not see a login page if a user is already logged in.

Login

When not loading, the login page sends the user an email with a valid login link.



{#if data.loading}
	
	Loading...
{:else}
	
		
		{#if emailSent}
			
				Email Sent! Check your mailbox. If you don't see it look under junk or spam!
			
		{/if}
	
{/if}

It then saves the email as emailForSignIn in local storage.

Login Form

I share the login form with the confirm email form since they share almost identical characteristics.




	
		Login with Magic Link
		
			{#if isConfirmPage}
				Please confirm your email address to login!
			{:else}
				Enter your email address to receive a magic link to login!
			{/if}
		
		
			
				Email Address

The form inputs an email and does something.

Form Helper

I also have a form helper that gets the email from a form event.

export const getEmail = (event: SubmitEvent) => {

    event.preventDefault();

    const { email } = Object.fromEntries(
        new FormData(event.target as HTMLFormElement)
    );

    if (!email || typeof email !== 'string') {
        throw "No email!";
    }
    return email;
};

Callback

I created a callback at the url auth/callback, but this could be anywhere or even on the same login page.

Loader

The callback load function at +page.ts does a few things.

import { error, redirect } from '@sveltejs/kit';
import type { PageLoad } from './$types';
import { getUser, isMagicLinkURL, signInWithMagic } from '$lib/use-user';
import { browser } from '$app/environment';

export const load: PageLoad = async ({ url }) => {

    const urlString = url.toString();

    // you can get the email this way as well
    // const _email = url.searchParams.get('email');
    // console.log(_email);

    if (!isMagicLinkURL(urlString)) {
        error(400, 'Bad request');
    }

    // just load on server
    if (!browser) {
        return {
            loading: true
        };
    }

    const loggedIn = !!(await getUser());

    // redirect if already logged in
    if (loggedIn) {
        return redirect(302, '/');
    }

    // ask for email if no email
    const email = localStorage.getItem('emailForSignIn');
    if (!email) {
        return {
            loading: false
        };
    }

    // otherwise login
    const signInError = await signInWithMagic(email, urlString);
    if (signInError) {
        error(500, signInError.message);
    }
    localStorage.removeItem('emailForSignIn');
    return redirect(302, '/');
};

It displays an error if it is not a valid callback URL.
It will redirect you home if you have already logged in.
It checks for an email.
1. Logs in if one exists
2. Displays the confirm email page otherwise

Confirm Email Page

You should only need to confirm an email address if the user is logging in from a different device or if local storage is disabled.



{#if data.loading}
	
	Logging you in...
{:else}
	
		
	
{/if}

Add email to callback URL?

Yes, you can.

// sendMagicLink()
...
await sendSignInLinkToEmail(auth, email, {
    handleCodeInApp: true,
    url: originURL + '/auth/callback' + `?email=${email}`
});
...

And you can receive it from the URL.

// auth/callback/+page.ts

export const load: PageLoad = async ({ url }) => {

    const _email = url.searchParams.get('email');    
    
    ...

☢️ The problem is that this is theoretically not secure. A user could hack your email and easily log in to a website with a script. A user could technically do this anyway, as they already have your email address from the email itself, but Firebase recommends against this. However, other login systems see no problem with this method. It is up to you.

Repo: GitHub

Demo: Vercel Serverless

Handling Usernames in Firestore

Jonathan Gamble — Sun, 08 Sep 2024 13:00:00 GMT

Most modern apps need usernames. We don’t want to share our email addresses publicly, using a long user ID would look odd. Firebase doesn’t handle usernames out of the box, but you can use them with a few minor modifications.

TL;DR

When adding a new username, a separate usernames collection will complement the users collection. This will enforce uniqueness and allow for easy searchability. To save speed and reads, you should also add the username to a custom claim that can be accessible directly in the ID Token.

Collections

Depending on our app, our username could have three main points of reference:

usernames/{username} document
The field username in the users/{user_id} document
In the custom claim of the currentUser object

📝 We need the usernames collection to maintain distinct usernames. Firestore does not handle unique values, so we must use a document ID to emulate this behavior.

Adding a Username

When we add a username, we should add it to both collections simultaneously. Here, I use firebase-admin, but you could also do this on the client.

const batch = adminDB.batch();

batch.set(
    adminDB.doc(`usernames/${username}`),
    {
        uid,
        username
    }
);

batch.set(
    adminDB.doc(`users/${uid}`),
    {
        username
    },
    { merge: true }
);

await batch.commit();

However, we should also delete the old username to keep our records clean. This allows you to use the same method for updating a username as for adding a new one.

const uid = token.uid;

// get current username if exists
const querySnap = await adminDB
    .collection('usernames')
    .where('uid', '==', uid)
    .get();

const batch = adminDB.batch();

// delete current username if exists
if (!querySnap.empty) {

    querySnap.docs.forEach((snap) => {
        batch.delete(
            adminDB.doc(`usernames/${snap.id}`)
        )
    });
}

// add new username
try {
    batch.set(
        adminDB.doc(`usernames/${username}`),
        {
            uid,
            username
        }
    );

    batch.set(
        adminDB.doc(`users/${uid}`),
        {
            username
        },
        { merge: true }
    );

    await batch.commit();

} catch (e) {
    if (e instanceof FirebaseError) {
        error(400, e.message);
    }
}

📝 The error() method is in SvelteKit, but you could use whatever method your SSR framework uses to handle errors. You could also use a callable function if your app is only client-side.

Custom Claims

It is extremely easy to add a username custom claim on the backend.

try {
    await adminAuth.setCustomUserClaims(uid, {
        username
    });
} catch (e) {
    if (e instanceof FirebaseError) {
        error(400, e.message);
    }
}

⚠️ You cannot create custom claims on the client side; hence, it is recommended that you use the backend for the entire function.

📝 Keeping everything on the client side prevents you from having complex Firestore Rules when adding a username. If you keep these functions on the server, make the usernames collection read-only. See Firestore Rules.

Refreshing Token on the Client

Anytime you update a custom claim, you should update the client token.

await currentUser.getIdToken(true);

This should be done after your backend function is safely finished running.

Verify the User

Before adding any custom claims, you should always verify the user. You must pass the idToken to the server or Firebase function to do this.

export const verifyIdToken = async (idToken: string) => {
    try {
        const token = await adminAuth.verifyIdToken(idToken);
        return {
            token,
            error: null
        };
    } catch (e) {
        if (e instanceof FirebaseError) {
            return {
                error: e.message,
                token: null
            };
        }
    }
    return {
        error: null,
        token: null
    };
};

Usage

const { token, error: tokenError } = await verifyIdToken(idToken);

if (!token || tokenError) {
    error(401, 'Unauthorized!');
}

Checking for Valid Username

If you want to check for a valid username, you check for a username in the usernames collection.

export const usernameAvailable = async (
    username: string
) => {
    try {
        const snap = await getDoc(
            doc(db, 'usernames', username)
        );
        return {
            available: !snap.exists(),
            error: null
        };
    } catch (e) {
        if (e instanceof FirebaseError) {
            return {
                error: e.message,
                available: null
            };
        }
    }
    return {
        error: null,
        available: null
    };
};

Debounce

You can check while typing in an input field, but you should wait a few seconds before fetching Firebase to prevent unnecessary reads.

// reusable debounce function
export function useDebounce
) => ReturnType>(
    func: F,
    waitFor: number,
): (...args: Parameters) => void {
    let timeout: NodeJS.Timeout;
    return (...args: Parameters): void => {
        clearTimeout(timeout);
        timeout = setTimeout(() => func(...args), waitFor);
    };
}

Then you call it with oninput. This varies depending on your framework.

const debouceUsername = useDebounce(() => { // do something here });

This reusable hook should work anywhere.

const { available, error } = await usernameAvailable(username);

Login with Username Feature

It is worth noting that you could also simulate a login with username feature, even though this is NOT supported out-of-the-box, by simply using the username to fetch the user's UID. This would have to be done on the backend, and would use firebase-admin as well.

Example

Demo: Vercel Serverless

Repo: GitHub

📝 Remember firebase-admin will ONLY work in NodeJS Environments. Use a callable Firebase Function to deploy to Bun, Vercel Edge, Cloudflare, or Deno environments.

Firestore Fuzzy Full-Text Search

Jonathan Gamble — Sun, 01 Sep 2024 13:06:05 GMT

After years of getting different ideas for self-indexing search using Firestore, I have finally reached a usable conclusion that doesn’t use too much space, allows typos, sorts by relevance, and works without a separate database.

TL;DR

Adding full-text search capabilities to Firestore can be easy; it just requires your own index. The fuzzy index with soundex makes full-text searching possible with little headache.

Other Databases

If you need advanced features, it is recommended to use an external database built for searching. However, I believe this is overkill for most apps, even large ones.

🤦Yes, Google, the biggest search engine in the world, recommends a non-google product for Full-Text searching.

Idea 1 - Arrays and Maps

If all else fails, you can store keywords inside arrays and search for them with where clauses.

const db = getFirestore();

const q = query(
  collection(db, 'posts'), 
  where('terms', 'array-contains', 'query')
);

For more on this:

Idea 2 - Character Hack

Firestore has a hack that allows you to search for the first character of a value. You search for the word up until the end of the character set. I don’t understand why his works, but it does.

function startsWith(
    collectionRef: CollectionReference,
    fieldName: string,
    term: string
) {
    return query(
        collectionRef,
        orderBy(fieldName),
        startAt(term),
        endAt(term + '~')
    );
}

📝 You can use \uf8ff or the character ~. Both of these are known for the last character in the utf8 dataset.

// THIS IS THE SAME THING BTW
query(
  collectionRef,
  where(fieldName, '>=', term),
  where(fieldName, '<=', term + '\uf8ff')
);

Usage

const d = await getDocs(
    startsWith(
        collection(db, 'posts'),
        'searchField',
        'my-term'
    )
);

☢️ Problems

You can’t search for the start of a word, only the start of a string.
This will not work on maps or arrays.

However, this can be useful in certain situations.

Idea 3 - Trigram Fuzzy Search

I built a trigram search once upon a time ago. I archived the package. It saves trigrams of a word in an array for searching. Imagine elon musk baseball:

// could be stored as array or map
[elo, lon, mus, usk, bas, ase, bal, all]

Then, you would search by using where clauses for each trigram or array-contains-all.

where('elo', '==', true),
where('lon', '==', true)

☢️ Problems

Just like in all databases, trigram indexing is slow and painful. You also must convert each search phrase to a trigram for searching, as your query gets complex.

Idea 4 - Every Character Index

You could index your array or map to contain any iteration of the word for searching. Let’s say you want to store elon musk in a title.

['e']
['el']
['elo']
['elon']
['elon ']
['elon m']
...

☢️ Problems

You need to index every letter manually with repeated information. Imagine if you had a paragraph of text!

Solution

We can build on these ideas and group the text in clusters. No one will search for a whole paragraph; they will search for a few words at a time.

const NUMBER_OF_WORDS = 4;

const createIndex = (text: string) => {

    // regex matches any alphanumeric from any language and strips spaces
    const finalArray: string[] = [];
    
    const wordArray = text
        .toLowerCase()
        .replace(/[^\p{L}\p{N}]+/gu, ' ')
        .replace(/ +/g, ' ')
        .trim()
        .split(' ');

    do {
        finalArray.push(
            wordArray.slice(0, NUMBER_OF_WORDS).join(' ')
        );
        wordArray.shift();

    } while (wordArray.length !== 0);

    return finalArray;
};

This will strip out all non-alphanumeric characters and make an array based on the words in groups of 4. For example, this text:

Baseball is a game of strategy and skill, where every pitch, swing, and catch can change the course of the game in an instant.

We would have something like this:

["baseball is a game"],
["is a game of"],
["a game of strategy"],
["game of strategy and"],
["of strategy and skill"],
...

This does not help us, as we need to be able to search as we type the word. So, again, we must go through every iteration of that iteration.

for (const phrase of index) {
    if (phrase) {
        let v = '';
        for (let i = 0; i < phrase.length; i++) {
            v = phrase.slice(0, i + 1).trim();
            // increment for relevance
            m[v] = m[v] ? m[v] + 1 : 1;
        }
    }
}

And we end up with something like this:

Relevance

Instead of an array, we store it as a map. Notice the number by the word. Luckily, we don’t have to store repeated phrases like “and.” We can increment the value for each repetition of the words. This gives us relevance.

Searching

To search, we find where the search field is equal to searchField.term. Since we are ordering by this also, we don’t need a where clause.

const data = await getDocs(
  query(
    collection(db, 'posts'),
    orderBy(`searchField.${term}`),
    limit(5)
  )
);

Fuzzy Search

What we really want is not an exact search but a fuzzy search. We need some kind of typo tolerance.

Typo Tolerance with Soundex

The soundex algorithm has been used for years to simulate typo tolerance. It allows you to store text as sound patterns, not just as text.

// Take any string, and return the soundex
export function soundex(s: string): string {
    const a = s.toLowerCase().split("");
    const f = a.shift() as string;
    let r = "";
    const codes: Record = {
        a: "",
        e: "",
        i: "",
        o: "",
        u: "",
        b: 1,
        f: 1,
        p: 1,
        v: 1,
        c: 2,
        g: 2,
        j: 2,
        k: 2,
        q: 2,
        s: 2,
        x: 2,
        z: 2,
        d: 3,
        t: 3,
        l: 4,
        m: 5,
        n: 5,
        r: 6,
    };
    r = f + a
        .map((v: string) => codes[v])
        .filter((v, i: number, b) =>
            i === 0 ? v !== codes[f] : v !== b[i - 1])
        .join("");
    return (r + "000").slice(0, 4).toUpperCase();
}

📝 There are different versions for different languages. Here is one for French, for example.

Using this pattern, we can slightly modify our storage mechanism to translate for soundex first.

const temp = [];
// translate to soundex
for (const i of index) {
  temp.push(i.split(' ').map(
	  (v: string) => soundex(v)
  ).join(' '));
}
index = temp;
// add each iteration from the createIndex
for (const phrase of index) {
  if (phrase) {
	  let v = '';
	  const t = phrase.split(' ');
	  while (t.length > 0) {
		  const r = t.shift();
		  v += v ? ' ' + r : r;
		  // increment for relevance
		  m[v] = m[v] ? m[v] + 1 : 1;
	  }
  }
}

The beauty of this is it greatly simplifies your storage.

You’re only storing the sound itself, not the letters, and there are fewer iterations of sounds than words.

Remember to translate the text to soundex before you search as well!


// get the soundex terms
const searchText = text
  .trim()
  .split(' ')
  .map(v => soundex(v))
  .join(' ');

// search
const data = getDocs(
  query(
    collection(db, 'posts'),
    orderBy(`search.${searchText}`),
    limit(50)
  )
);

💵 This is simpler and faster than Vector Search!

🤷 I have archived my j-firebase package, as I lack time to keep up with a repo.

📝 For an extra idea, you could also theoretically add stop-words, and ignore indexing them.

Backend or Frontend

In practice, you should build a trigger function on each document creation for your collection to handle this indexing. The second best option is to use a backend function to add the data simultaneously. Technically, you can do this on the frontend with no problem, but offloading the generation to the backend makes more sense.

Demo: Vercel Serverless

Repo: GitHub

Firestore Vector Full-Text Search

Jonathan Gamble — Sun, 25 Aug 2024 13:00:00 GMT

With the AI revolution, Vector Databases have become popular. Almost every big database that didn’t already have the option has added Vector support, and Firestore is no different. This demo was incredibly tedious and difficult to build; I will try to simplify it and show you what I learned.

TL;DR

While Vector Search adds a type of full-text search support to your app, you must create an embedding for every search term before searching. This can be slow and cumbersome. The Vector Search is really just a document sort, and not a filter. However, it is very powerful and pretty cool in my book.

Vector Setup

Enable the Vector AI API in Google Console.
Get a Firebase Admin Private Key and add it to your .env file.
Add Vertex AI Administrator to the Firebase IAM account you just generated.
Install Firebase Admin for NodeJS

npm i -D firebase-admin

For non-Node environments, you must use the Firebase REST API instead.

(Optional) Install Vertex AI for NodeJS

npm i -D @google-cloud/aiplatform

I have also included the REST API version, which I find more intuitive in this case.

Firebase Admin Setup

Depending on your Framework, this could vary a bit, but the premise is the same.

import { PRIVATE_FIREBASE_ADMIN_CONFIG } from '$env/static/private';
import { getApps, initializeApp, cert, getApp } from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';
import { getFirestore } from 'firebase-admin/firestore';

const firebase_admin_config = JSON.parse(PRIVATE_FIREBASE_ADMIN_CONFIG);

// initialize admin firebase only once
export const adminApp = getApps().length
    ? getApp()
    : initializeApp({
        credential: cert(firebase_admin_config),
        projectId: firebase_admin_config.project_id
    });

export const adminAuth = getAuth(adminApp);
export const adminDB = getFirestore(adminApp, 'firestore-testing');

Notice I am using firestore-testing as a secondary database. We import the key from the .env file created before.

Embeddings

The key to Vector Search is generating embeddings before storing data and searching for data. Unfortunately, this means you must make two API calls every time you search. One call will translate the data from your query text, and another will be used to search the Firestore database.

Vertex AI Model

You can use OpenAI or any other LLM, but Google already has a model ready for text searching.

English models	Multilingual models
`textembedding-gecko@001`	`textembedding-gecko-multilingual@001`
`textembedding-gecko@003`	`text-multilingual-embedding-002`
`text-embedding-004`
`text-embedding-preview-0815`

For English, the recommended model is text-embedding-004.

Task Type

You also must select how you’re storing the data in the embedding.

Task Type	Description
`SEMANTIC_SIMILARITY`	Used to generate embeddings that are optimized to assess text similarity
`CLASSIFICATION`	Used to generate embeddings that are optimized to classify texts according to preset labels
`CLUSTERING`	Used to generate embeddings that are optimized to cluster texts based on their similarities
`RETRIEVAL_DOCUMENT`, `RETRIEVAL_QUERY`, `QUESTION_ANSWERING`, and `FACT_VERIFICATION`	Used to generate embeddings that are optimized for document search or information retrieval

Because we want to build a full-text search, we will use SEMANTIC_SIMILARITY. However, RETRIEVAL_DOCUMENT or RETRIEVAL_QUERY could also work for this use case. I tested those as well, and there is not much difference.

Dimensionality

What is the quality of the Vector you want to store? The higher the quality, the more space you will use in Firestore. While the docs say a number between 1 and 2048, The maximum allowable dimensionality for the best quality is 768.

Instances

Both API versions take an array of instances to search for. You could ultimately use this search for more than one term at a time. However, this example only uses one instance and task type.

Vertex AI Package

We need to generate the embeddings from our text. This version needs to use our Firebase Admin keys directly.

import { PRIVATE_FIREBASE_ADMIN_CONFIG } from '$env/static/private';
import { adminAuth } from '$lib/firebase-admin';
import { PredictionServiceClient, helpers } from '@google-cloud/aiplatform';
import type { google } from '@google-cloud/aiplatform/build/protos/protos';

const firebase_admin_config = JSON.parse(PRIVATE_FIREBASE_ADMIN_CONFIG);

const model = 'text-embedding-004';
const task = 'SEMANTIC_SIMILARITY';
const location = 'us-central1';
const apiEndpoint = 'us-central1-aiplatform.googleapis.com';
const dimensionality = 768;

export const getEmbedding = async (content: string) => {

    const project = adminAuth.app.options.projectId;

    const client = new PredictionServiceClient({
        apiEndpoint,
        credentials: {
            client_email: firebase_admin_config.client_email,
            private_key: firebase_admin_config.private_key
        }
    });

    const [response] = await client.predict({
        endpoint: `projects/${project}/locations/${location}/publishers/google/models/${model}`,
        instances: [
            helpers.toValue({ content, task }) as google.protobuf.IValue
        ],
        parameters: helpers.toValue({
            outputDimensionality: dimensionality
        })
    });

    const predictions = response.predictions;

    if (!predictions) {
        throw 'No predictions!';
    }

    const embeddings = predictions.map(p => {
        const embeddingsProto = p.structValue!.fields!.embeddings;
        const valuesProto = embeddingsProto.structValue!.fields!.values;
        return valuesProto.listValue!.values!.map(v => v.numberValue);
    });

    return embeddings[0] as number[];
};

Packages like firebase-admin usually automatically handle mapping the vector data, but this package was just as difficult to use as basic REST API. You have to map the fields manually and return the complex array correctly. Google Packages will automatically log errors to the console.

REST API Method

Alternatively, call the REST API directly. Here, we can use our Firebase Access Token.

export const getEmbedding2 = async (content: string) => {

    const project = adminAuth.app.options.projectId;
    const token = await adminAuth.app.options.credential!.getAccessToken();

    const url = `https://us-central1-aiplatform.googleapis.com/v1/projects/${project}/locations/us-central1/publishers/google/models/text-embedding-004:predict`;

    const r = await fetch(url, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token.access_token}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            instances: [
                {
                    "task_type": task,
                    // you can also use "title" for RETRIEVAL tasks 
                    "content": content
                },
            ],
            parameters: {
                outputDimensionality: dimensionality
            }
        })
    });

    if (!r.ok) {
        const error = await r.json();
        throw error;
    }

    const response = await r.json();

    const predictions = response.predictions;

    if (!predictions) {
        throw 'No predictions!';
    }

    // @ts-expect-error: You should make your own types in reality here
    const embeddings = predictions.map(p => p.embeddings.values);

    return embeddings[0] as number[];
};

Save Data to Firestore

In this example, we save the content to the text field and the vector to the search field.

const embeddings = await getEmbedding(text);

await adminDB.collection('posts').add({
    text,
    search: FieldValue.vector(embeddings)
});

Retrieving Data

When retrieving our documents normally, without searching, we want to exclude the Vector field, as it will not be serializable from the server, and we don’t need to download extraneous information.

  const data = await adminDB.collection('posts').get();

  // don't return actual vector, won't serialize
  const docs = data.docs.map((doc) => {
      const data = doc.data();
      return {
          id: doc.id,
          text: data['text']
      };
  });

  return {
      docs
  };

📝 Using the Firebase REST API, you can choose the fields you want to download, thus avoiding the vector altogether and saving on data transfer.

Create an Index

Before searching, you must add a Vector Index. Currently, there is no way to do this outside of using the gcloud CLI. I could not even get that to work on my local machine. Luckily, it works as expected using the Google Cloud Shell. Hopefully, this will be fixed soon when it is out of alpha.

gcloud alpha firestore indexes composite create
 --collection-group=YOUR-COLLECTION
 --query-scope=COLLECTION
 --field-config field-path=search,vector-config='{"dimension":"768","flat": "{}"}'
 --project=YOUR-PROJECT-ID
 --database="YOUR-DATABASE"

Replace YOUR-COLLECTION, YOUR-PROJECT-ID, and YOUR-DATABASE with the respected information.

⚠️ COLLECTION is not to be replaced or confused with YOUR-COLLECTION.

📝 You can also edit the dimension here for indexing if you want to change the default quality.

⚠️ Get rid of all new lines before using this command!

Searching

To search, we use the findNearest method. Unfortunately, we must get an embedding even for the data to be searched.

const embeddings = await getEmbedding(text);

const data = await adminDB
    .collection('posts')
    .findNearest(
        'search',
        FieldValue.vector(embeddings), {
        limit: 5,
        distanceMeasure: 'EUCLIDEAN'
    })
    .get();

// don't return actual vector, won't serialize
const docs = data.docs.map((doc) => {
    const data = doc.data();
    return {
        id: doc.id,
        text: data['text']
    };
});

return {
    docs
};

search is our Vector Field
Since all vector data is ultimately related, we limit our results to 5. Otherwise, we could potentially return all documents. This is required for a reason. Vector Search ultimately just sorts the data. You can only return a maximum of 1000 documents.
We want to use EUCLIDEAN to measure the shortest distance for semantic search. However, COSINE and DOT_PRODUCT are also available for more advanced cases.

Pricing

Embeddings are charged $0.000025 per 1000 characters.
Vector Search is charged one read operation for each batch of up to 100 kNN vector index entries read by the query.

Other Filtering

You can also add any other filters except for inequalities. However, each filter will require a separate index.

Vector Limitations

Vectors only work on the backend. If you need frontend support, write a WRITE trigger function that creates the vector anytime a new document is added to your collection. However, you would still need a backend to convert the search text to a vector before searching.
For this reason, I’m not sure if it will ever be available on the frontend JS package. This is the worst part of the search. This also limits the ability to use real-time listeners.

Google needs to use TypeScript for its examples instead of pure JavaScript. This was one of my many issues, and the documentation was terrible. Nevertheless, we got er goin!

Demo

The demo uses SvelteKit with Form Actions.
Searching for something may take 1-20 seconds. This is not ideal, but it varies consistently and is quick enough most of the time.
I disabled adding new data to the production version to reduce spam.

Demo: Vercel Serverless

Repo: GitHub

Note

I highly recommend you use the Fuzzy Full-Text Search instead of this one, as it is faster, smaller, and easier.

Firebase Now Works on the Server

Jonathan Gamble — Sun, 18 Aug 2024 13:00:00 GMT

When Firebase was released, before Google even owned the company, you didn’t need to fetch anything on the server. Over 10 years later, you can pre-fetch your data to Firebase on the server before loading it on the client. This is faster, smaller, and less painful.

TL;DR

You can now use the firebase-js-sdk library directly on the server without needing the firebase-admin package. You can fetch Firestore data that requires user credentials and normal fetching. You can add service workers to your app that add the login token to every fetch. The fetch logins on the server with initializeServerApp.

Firestore Lite

Firebase has technically worked on the server for a long time, but not without headaches. Firebase Admin can load your data, but only on Node servers. Firebase Lite allows you to run Firebase on Edge Servers, including NextJS Middleware, Cloudflare, Bun, and Vercel.

Remember to use firebase/firestore/lite if you’re on the edge for importing Firestore.

Firebase Authentication on the Server

The problem has been using authentication. There has not been a way to authenticate your data on the server that works across platforms. Since Firebase 10.12.3, everything works as expected, even on the Edge.

SvelteKit

This example uses SvelteKit, but I will update all framework examples over time. First, make sure to follow the SvelteKit Todo App with Firebase to understand the Svelte setup.

Firebase Lite

Here, we create a separate server file to handle the server request. This will be identical in all frameworks except loading the .env config and using error handling.

// lib/firebase-lite.ts

import { PUBLIC_FIREBASE_CONFIG } from "$env/static/public";
import { error } from "@sveltejs/kit";
import { initializeServerApp } from "firebase/app";
import { getFirestore } from "firebase/firestore/lite";
import { getAuth } from "firebase/auth";

const firebase_config = JSON.parse(PUBLIC_FIREBASE_CONFIG);

export const firebaseServer = async (request: Request) => {

    const authIdToken = request.headers.get('Authorization')?.split('Bearer ')[1];

    if (!authIdToken) {
        error(401, 'Not Logged In!');
    }

    const serverApp = initializeServerApp(firebase_config, {
        authIdToken
    });

    const auth = getAuth(serverApp);

    const db = getFirestore(serverApp);

    await auth.authStateReady();

    if (auth.currentUser === null) {
        error(401, 'Invalid Token');
    }

    return {
        auth,
        db
    };
};

The initializeServerApp is key. This allows us to create a temporary server app from an ID Token. We must get it from the request first. Then we await the authorization state before getting the current user.

The request object is passed to our firebaseServer function.

// routes/about/+page.server.ts

import { getAbout } from '$lib/about';
import { firebaseServer } from '$lib/firebase-lite';

import type { PageServerLoad } from './$types';

export const load = (async ({ request }) => {

    const { db } = await firebaseServer(request);

    return {
        about: await getAbout(db)
    };

}) satisfies PageServerLoad;

Service Worker

The key to making this work is a Service Worker. The SW intercepts all fetch requests and adds the ID token to it. This is beautiful and doesn’t require complex session cookies.

// service-worker/index.ts

/// 

import { requestProcessor } from "./utils";

declare const self: ServiceWorkerGlobalScope;

self.addEventListener('activate', (event) => {

    const evt = event as ExtendableEvent;

    evt.waitUntil(self.clients.claim())
});

self.addEventListener('fetch', (event) => {

    const evt = event as FetchEvent;

    evt.respondWith(requestProcessor(evt));
});

We want to activate our service worker as soon as it is available, and then we listen to fetch requests.

Process Request

This is simplified code from Firebase. The Authorization Token is added to the request. I had to translate it to TypeScript. It should have been written that way first 🤓

// service-worker/utils.ts

import { getIdTokenPromise } from "$lib/firebase-worker";

export const getOriginFromUrl = (url: string): string => {
    const [protocol, , host] = url.split('/');
    return `${protocol}//${host}`;
};

// Get underlying body if available. Works for text and json bodies.
export const getBodyContent = async (req: Request): Promise => {

    if (req.method === 'GET') {
        return null;
    }

    try {
        if (req.headers.get('Content-Type')?.includes('json')) {
            const json = await req.json();
            return JSON.stringify(json);
        }
        return await req.text();
        
    } catch {
        return null;
    }
};

export const requestProcessor = async (event: FetchEvent) => {

    let req = event.request;

    const idToken = await getIdTokenPromise();

    if (
        self.location.origin === getOriginFromUrl(event.request.url) &&
        (self.location.protocol === 'https:' || self.location.hostname === 'localhost') &&
        idToken
    ) {
        const headers = new Headers(req.headers);
        headers.append('Authorization', 'Bearer ' + idToken);
        const body = await getBodyContent(req);

        try {
            req = new Request(req.url, {
                method: req.method,
                headers: headers,
                mode: 'same-origin',
                credentials: req.credentials,
                cache: req.cache,
                redirect: req.redirect,
                referrer: req.referrer,
                body,
            });
        } catch {
            // This will fail for CORS requests. We just continue with the fetch logic without passing the ID token.
        }
    }

    return await fetch(req);
};

Firebase in the Worker

We need to get the ID token to pass it. onAuthStateChanged will always contain the latest token, so we convert it to a Promise.

import { PUBLIC_FIREBASE_CONFIG } from "$env/static/public";
import { getApp, getApps, initializeApp } from "firebase/app";
import { getAuth, getIdToken, onAuthStateChanged } from "firebase/auth";

const firebase_config = JSON.parse(PUBLIC_FIREBASE_CONFIG);

const workerApp = getApps().length
    ? getApp()
    : initializeApp(firebase_config);

const auth = getAuth(workerApp);

export const getIdTokenPromise = (): Promise => {
    return new Promise((resolve, reject) => {
        const unsubscribe = onAuthStateChanged(auth, async (user) => {
            unsubscribe();
            if (!user) {
                return resolve(null);
            }
            try {
                const idToken = await getIdToken(user);
                resolve(idToken);
            } catch (e) {
                reject(e);
            }
        }, reject);
    });
};

Hosting Caveat

While this works on Vercel Edge, which uses Cloudflare, there is a small bug with direct Cloudflare hosting that we are still waiting for the PR. See Server App Not Logging in. It is one line of code, so hopefully, this will be repaired soon. It should work with Vercel Edge, Vercel Serverless, Netlify, etc.

Demo: Vercel Edge

Code: GitHub

Firebase Storage User Profile Image

Jonathan Gamble — Sun, 23 Jun 2024 13:00:00 GMT

Many database platforms handle authentication with the database functions, but not many have built-in storage capabilities. Firebase Storage allows you to securely and easily upload files in buckets, similar to folders.

TL;DR

We use Svelte to update a user’s photoURL in the Firebase Authentication database. The image is stored in Firebase Storage, the old image is deleted automatically, and only image types are allowable.

Svelte Example

If you read many articles on this site, you should know now that I use Svelte for easy prototyping. This app is no exception. However, the concept is the same in any framework.

Edit Image Component

I use a custom image hook that returns a status and a files writable. In other frameworks, this would use signals instead of stores. You may also use a form and submit this to the backend.




	
		
			Upload Image
			
			{#if $status.progress}
				Percent: {$status.progress.toString()}
			{/if}
			{#if $status.error}
				
					Error: 
					{$status.error}
				
			{/if}

Image Type

You can tell an HTML Input Element what you want to accept. For any image type:

For specific MIME types:

Or by extension:

We will need to secure this later in Firebase Storage Rules.

Upload Image Hook

The hook looks complicated.

import { auth, storage } from "./firebase";
import {
    derived,
    writable,
    type Writable
} from "svelte/store";
import {
    deleteObject,
    getDownloadURL,
    ref,
    uploadBytesResumable,
    type TaskState
} from "firebase/storage";
import { updateProfile } from "firebase/auth";

type UploadState = {
    progress: number | null;
    state: TaskState | null;
    error: string | null;
    downloadURL: string | null;
}

export const useUploadImage = () => {

    const files = writable();

    const status = derived<
        Writable,
        UploadState
    >(files, ($files, set) => {

        if (!$files) {
            set({
                progress: null,
                state: null,
                error: null,
                downloadURL: null
            });
            return;
        }

        if (!auth.currentUser) {
            throw 'Not logged in!';
        }

        const uid = auth.currentUser.uid;

        const new_file = $files[0];

        if (new_file.size >= 1 * 1024 * 1024) {
            set({
                progress: null,
                state: null,
                error: 'Image size must be less than 1MB!',
                downloadURL: null
            })
            return;
        }

        const uploadTask = uploadBytesResumable(
            ref(storage, `profiles/${uid}/${new_file.name}`),
            new_file
        );

        uploadTask.on('state_changed',
            (snapshot) => {

                // handle upload progress
                const progress = (
                    snapshot.bytesTransferred / snapshot.totalBytes
                ) * 100;
                set({
                    progress,
                    state: snapshot.state,
                    error: null,
                    downloadURL: null
                });

            },
            (error) => {

                // error handling
                set({
                    progress: null,
                    state: 'error',
                    error: error.message,
                    downloadURL: null
                })
            },
            () => {

                // success, get download URL
                getDownloadURL(uploadTask.snapshot.ref)
                    .then((downloadURL) => {

                        // delete current image
                        deleteImage().then(() => {
                            if (!auth.currentUser) {
                                throw 'No User!';
                            }
                            // update profile with new image
                            updateProfile(auth.currentUser, {
                                displayName: auth.currentUser.displayName,
                                photoURL: downloadURL
                            }).then(() => {

                                // set progress to 100%
                                set({
                                    progress: 100,
                                    state: 'success',
                                    error: null,
                                    downloadURL
                                });
                            });
                        })

                    });
            }
        );

    });

    return {
        files,
        status
    };
};

File Type

With an input file element, you can keep track of the file being uploaded with a FileList type. Since we are only uploading one file, the file will be the first in the array.

const new_file = $files[0];

We can limit the file size to 1MB for our client. This should be matched on the backend as well.

new_file.size >= 1 * 1024 * 1024

Upload Part

Let’s break down the upload part first.

const uploadTask = uploadBytesResumable(
    ref(storage, `profiles/${uid}/${new_file.name}`),
    new_file
);

We upload to the profiles/{userId}/{filename} folder here. The file name can be anything as long as it is in the user’s folder.

Progress

We can keep track of the upload in real-time using uploadTask.on.

uploadTask.on('state_changed',
    (snapshot) => {

        // handle upload progress
        const progress = (
            snapshot.bytesTransferred / snapshot.totalBytes
        ) * 100;
        // handle progress

    },
    (error) => {

        // error handling
        
    },
    () => {

        // success, get download URL
        getDownloadURL(uploadTask.snapshot.ref)
            .then((downloadURL) => {

                // handle download URL
                // set progress to 100%

            });
    }
);

We can translate this to an observable, a signal, or a store (in the case of Svelte).

Delete Image

In some cases, we may want to allow the user to have only one profile image at a time. Here, we remove the old profile image.

deleteObject(
    ref(storage, photoURL)
);

Update the User Profile

We also need to update the user’s profile once we receive an image, upload a new image, or delete an image. The linked article explains this more fully.

Storage Rules

Of course, we should secure our app on the backend as well.

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
  	match /profiles/{userId}/{image} {
    	allow read;
      allow create: if isLoggedIn() 
      	&& isOwner()
        && isImageType()
        && oneMBLimit();
      allow delete: if isLoggedIn()
        && isOwner();
    }
  }
  
  function isOwner() {
  	return request.path[4] == request.auth.uid;
  }
  
  function isLoggedIn() {
  	return request.auth != null;
	}
  
  function isImageType() {
  	return request.resource.contentType.matches('image/.*');
	}
  
  function oneMBLimit() {
    return request.resource.size < 1 * 1024 * 1024;
  }
  
}

Our path will be the storage file path instead of the collection path. For a more in-depth discussion of rules, see the Firestore Security Rules Example Guide. You may need some advanced rules. See Security Rules for Cloud Storage Reference.

Image Best Practices

If your images could be used in multiple places, you may not want to ever delete them. Images are cheap to store and are hosted on a CDN.
However, if an image could be an orphan (with no links to it), it is best practice to delete it automatically to save yourself in the long run.
Your image should have good keywords in the file name for best SEO practices. I don’t do that here, but it is good to know.
⚠️ Always use a new name when replacing an image. Images are cached by default, and it is extremely hard to reset the browser, server, and CDN caches when you update an image.
- Images belonging to a user should go in that user’s folder. Ex: profiles/{userId}
- You could generate a random UUID for every image or use a date timestamp.
- You could keep the keywords with the random string. Ex: profiles/{userId}/firebase-functions-image-x2030s0eksl.jpg.

Firebase Function Storage Triggers

There are Cloud Storage Trigger Functions that allow you to handle different events. I will only cover Generation 2, which you should use for speed and security.

onObjectArchived - Used when versioning is enabled to archive old versions of files.
onObjectDeleted - Used when a file is deleted.
onObjectFinalized - Used when a file has finished uploading, even when replacing old files.
onMetadataUpdated - Used when metadata changes.

Usage

Relating to this app, you could use a storage trigger function to guarantee that the old user profile image is deleted or that the photoURL is updated.

⚠️ CAVEAT: When the user profile image is updated on the server (in a server function or Cloud Function), it will not get updated until the active user logs out and back in. You could redundantly update it, but in a real app you would probably use Cloud Firestore to store the profile image. See Update a User Profile in Firebase.

In a production app, the best bet is to update Cloud Firestore inside the trigger function with the new download URL.

Demo: Vercel Serverless

Repo: GitHub

Inner Joins with Firebase Functions

Jonathan Gamble — Sun, 02 Jun 2024 13:00:00 GMT

Because Firestore is a NoSQL database, you can’t use joins like in SQL. You must plan your queries when you write your data, or you must over-fetch. There are no other options unless you use a third-party database alongside Firestore.

TL;DR

You can’t have a serious Firebase app without needing Firebase Functions to perform joins for you. Luckily, it can make these aggregations very simple with BulkWriter.

Connections

In SQL, you use joins to get nested data. You may have to use a jsonb type, and return the data as a nested JSON object.

One-to-One

A 1:1 example would be a user and a profile. The user data may be secure, while the profile data is visible to everyone. This is similar to linking a user’s profile data from the Firebase Auth database to the Firestore users or profiles collection.

One-to-Many and Many-to-One

One-to-many is the most common example in Firestore. If there are many authors, and each author only writes one book, that is one-to-one. However, in reality, each author could write several books. An author or user could write several posts, comments, or have many bookmarks. From the author's perspective, this is a one-to-many relationship. Each user can have multiple items. From the item perspective, this is a many-to-one. Each item can only have one user.

🔍 If you query a list of posts, each post needs to query a user. You have 2x the Firestore read cost. This means for every many-to-one query, you get charged double.

Many-to-Many

For completeness, many-to-many relationships are like a book with many authors. Or, a student can belong to many classes, and a class can have many students. I have other posts on these.

Join with Reference Type

If you don’t care about reads or the extra latency of several queries in one, you may want to look into the Reference Type for Joins. This has advantages when you need a quick mock-up or don’t want to deal with Firebase Functions.

Firebase Functions

Before deploying any functions during the creation and testing phases, I suggest you test with Firebase Emulators on your local machine. This will save you time trying to redeploy for every change and can keep you from managing a secondary cloud database.

Initialization

First, update your Firebase CLI to the latest version.

 npm i -g firebase-tools

Next, add Firebase to your project.

firebase init

You will be asked to log in and link to a current Firebase project. I highly suggest you use TypeScript and avoid ESLint unless you’re a pro at it. The default configuration is out-of-date and too strict.

Generation 2

I will use only Generation 2 Functions for this example, as they are faster and allow you to select more than one database.

Inner Joins

To perform joins, you must copy data into the document you want to query. You also need to know your queries when you write your data, before any query occurs. Joins will take the form of nested JSON objects in a Firestore document.

User Operations

Let’s say you want to include the user’s (author’s) information on each post. While the join involves 6 operations, depending on your application, you may need only 3 triggers. It is common to use only two of them.

Add a User
1. You can’t add a post without a user, so there is nothing to do.
Modify a User
1. ❗This is the expensive operation. You must update every post by that user with the new user data only if the user’s data has changed. We use an onDocumentUpdated trigger on the users collection for this.
Delete a User
1. Most modern apps use a soft delete, which requires marking every user's post as hidden. You could add a filter or copy it to an archive collection. Use an onDocumentDeleted trigger on the users collection, then grab all posts and mark them as private or use some other name for a filter.
2. You could also emulate a Cascade Delete, and delete every post by that user. Every post could have comments, and you could delete every comment with a separate Cascade Delete emulation. Use an onDocumentDeleted trigger on the users collection, then grab all posts and delete them individually. You could have the onDocumentDeleted trigger on the posts collection to do the same for the comments.
Create a Post
1. You can add the user information directly when the post is created, and this can be enforced with Firestore Rules. There may be edge cases where you have to add an onCreate trigger to your posts collection to enforce the correct data, but I am only mentioning it for awareness.
Update a Post
1. Again, using Firestore Security Rules you can easily prevent the nested user data from being edited.
Delete a Post
1. Everything gets deleted, so there is nothing to do.

Comment Page Example

I made an example app where users can add comments to a page. I am using comments and profiles collections. We will need 3 Triggers.

Update a Profile
1. Make sure all comments by that user get updated
Create a Comment
1. Add nested user data automatically
Delete a Profile
1. Cascade Delete all comments

Update a Profile

We update all comments with the latest user information. This app displays the photoURL and the displayName. Although not strictly necessary, I also update the Firebase Auth database.

⚠️ Remember that the Firebase Auth database must be updated on the client to be updated immediately in the session. There are lots of moving parts.

export const updateComments = onDocumentUpdated(
    'profiles/{docId}',
    async (event) => {

        const eventData = event.data;

        if (!eventData) {
            return null;
        }

        const userId = event.params.docId;

        // Update user in Firebase Auth
        const { displayName, photoURL } = eventData.after.data();

        await adminAuth.updateUser(userId, {
            displayName,
            photoURL
        });

        // Update all comments
        const db = eventData.after.ref.firestore;

        const bulkWriter = db.bulkWriter();

        const comments = await db.collection('comments')
            .where('createdBy.uid', '==', userId)
            .get();

        // Bulk Update by looping
        comments.forEach((comment) => {
            bulkWriter.set(comment.ref, {
                createdBy: {
                    displayName,
                    photoURL
                }
            }, { merge: true });
        });

        bulkWriter.onWriteError((error) => {
            const MAX_RETRIES = 3;
            if (error.failedAttempts < MAX_RETRIES) {
                return true;
            }
            // Handle errors here
            return false;
        });

        await bulkWriter.close();

        return event;
    });

Bulk Writer

Using batch is faster than consecutive writes but not faster than simultaneous writes. For that, we use bulkwriter. We can retry up to 10 times but are still stuck with the Firebase Function limits of 9 minutes per function call. This should not be a problem. This is known as the fan-out method or aggregating the data. If we need more processing power than Firebase Functions can provide, we should use the trigger function to offload the bulk updates to a faster server.

Create a Comment

We trigger the comments function, but only re-update the comment document if the data has not been properly added. Normally, we want to add the data on the client.

You can pick and choose any field(s). Since it costs money to read a users document, I am getting the data from the Firebase Auth database. You must ALWAYS think about reads. However, most of the time, you should read another document to join data.

export const createComment = onDocumentCreated(
    'comments/{commentId}',
    async (event) => {

        const eventData = event.data;

        if (!eventData) {
            return null;
        }

        // createdBy should be enforced in Security Rules
        const docData = eventData.data();

        const {
            displayName,
            photoURL
        } = await adminAuth.getUser(docData.createdBy.uid);

        if (
            docData.displayName !== displayName
            || docData.photoURL !== photoURL
        ) {
            return eventData.ref.set({
                createdBy: {
                    displayName,
                    photoURL
                }
            }, { merge: true });
        }

        return event;
    });

Cascade Delete

This is just for example. The concept for deleting is exactly the same.

export const deleteProfile = onDocumentDeleted(
    { document: 'profiles/{docId}' },
    async (event) => {

        const eventData = event.data;

        if (!eventData) {
            return null;
        }

        const userId = event.params.docId;

        // Delete in Firebase Auth
        await adminAuth.deleteUser(userId);

        const db = eventData.ref.firestore;

        // Delete all comments...

        const bulkWriter = db.bulkWriter();

        const comments = await db.collection('comments')
            .where('createdBy.uid', '==', userId)
            .get();

        // Bulk Delete by looping
        comments.forEach((comment) => {
            bulkWriter.delete(comment.ref);
        });

        bulkWriter.onWriteError((error) => {
            const MAX_RETRIES = 3;
            if (error.failedAttempts < MAX_RETRIES) {
                return true;
            }
            // Handle errors here
            return false;
        });

        await bulkWriter.close();

        // Delete all posts...

        // ...

        return event;
    });

Trigger from a Different Database

Firebase Functions Generation 2 allows you to select a different database. Instead of using a string for the first input of the trigger, you could use an object with a database key.

export const deleteProfile = onDocumentDeleted(
    { document: 'profiles/{docId}', database: 'cars' },
    async (event) => {

Update Only Changed

There could be situations where a user is updated, and some of the nested data has already been updated. You could save writes by checking for the updates first, although each conditional could slow down write time. This probably won’t be significant.

// Bulk Update by looping
comments.forEach((comment) => {

    const { createdBy } = comment.data();

    // only update if data has changed
    if (
        createdBy.displayName !== displayName
        || createdBy.photoURL !== photoURL
    ) {

        bulkWriter.set(comment.ref, {
            createdBy: {
                displayName,
                photoURL
            }
        }, { merge: true });
    }
});

Even Faster Reads

The Firebase REST API allows you to query only the document IDs for a query. This still costs you one document read per document, but it could save you time and money by not downloading all the document data. However, the setup time will be longer since converting a query to the REST API is cumbersome.

How to Avoid the Joins

Update a Profile
1. Don’t display the user information.
2. Don’t allow user information to be changed (Ex. use a username). This is why you can’t edit a tweet on Twitter; it is an expensive operation.
3. Grab the data on the client, and cache it.
Create a Comment
1. Add the User information on the client, and enforce it with Firestore Rules (you should do this anyway)
Delete a Profile
1. Don’t allow a profile to be deleted.
2. Disable the profile but not the posts or comments.

More on One-to-Many

This method could also save you read charges and give you a better developer experience when reading several documents. You don’t want to make 10 API calls if you have one post with 9 comments. You could aggregate the latest 10 comments to your post document and use an infinite scroll or a load button to load the rest of the comments.

Demo: Vercel Serverless

Repo: GitHub

For more, see Cloud Functions.

Update Firebase Email with Reauthentication

Jonathan Gamble — Wed, 29 May 2024 13:00:00 GMT

Updating an email or password is handled differently in Firebase than updating a user’s profile name or photo URL. There is a separate function, you may have to reauthenticate the user, and the email must be confirmed.

TL;DR

After 5 minutes of logging in with Firebase, you must reauthenticate your login session to change a password or update an email. This requires a different login function than authenticating for the first time. You must check for an error code and direct the user correctly.

Other Methods

You could technically store the user’s email in Firestore, and use a Trigger Function to update the email in the Firebase Auth database like you might use when updating the profile information, but this would be less secure and could cause conflicts. You want to update the email directly in the Firebase Auth database to ensure integrity and security.

Shared State

You need some version of shared state. This app uses Svelte because I can prototype a demo very quickly. The Svelte Shared Store allows you to use a writable context anywhere in your app.

// writable store context
export const useWritable = (name: string, value?: T) =>
    useSharedStore(name, writable, value);
    
// use reLogin
export const useRelogin = () => useWritable('relogin', false);

Relogin

Along with the login, we need to be able to relogin when necessary.

Functions

export const loginWithGoogle = async () =>
    await signInWithPopup(
        auth, new GoogleAuthProvider()
    );

// requires the user
export const reLoginWithGoogle = async () => {
    if (auth.currentUser) {
        await reauthenticateWithPopup(
            auth.currentUser,
            new GoogleAuthProvider()
        );
    }
}

Login Component

Here, we check for the re-login state. Otherwise, we display a regular login component.




	

{#if $relogin}
	You must re-signin to change your email.
{/if}

Update Email

The function returns an error or nothing.

export const updateProfileEmail = async (
    email: string
) => {

    if (!auth.currentUser) {
        return {
            error: 'Not Logged In!'
        };
    }
    try {
        await updateEmail(auth.currentUser, email);
    } catch (e) {
        if (e instanceof FirebaseError) {
            return {
                error: e.message
            };
        }
    }
    return {};
};

Reauthenticate

In Firebase Auth, some actions require reauthentication. If it is necessary, you will be thrown an error.

// error.code === 'auth/requires-recent-login'

or

// error.message === 'Firebase: Error (auth/requires-recent-login).'

Because I’m only dealing with messages in my app for simplicity, I check for the error message.

const user = useUser();
const toast = useToast();
const relogin = useRelogin();

let email: HTMLInputElement;

const updateProfile = async () => {
	const { error } = await updateProfileEmail(email.value);
	if (error) {
		if (error === 'Firebase: Error (auth/requires-recent-login).') {
			relogin.set(true);
			return;
		}
		toast.error(error);
		return;
	}

	toast.open('Email Updated!');
};

This sets the relogin state dynamically, which will display the relogin button.

{#if $user}
	
		
			{#if $relogin}
				
			{:else}
				
					
						Email
					
					
				
				
			{/if}
		
	
{:else}
	
{/if}

After a relogin, the state will return to editing an email. This could be done in a million different ways, but I tried to show you a simple one.

When Is Reauthentication Necessary?

After 5 minutes you must reauthenticate to change your password or change your email. You will not see me showing any password authentication states on this website, as I do not believe it is good practice or secure.

Demo: Vercel Serverless

Repo: GitHub

See more on Svelte with Firebase

How to Update a User Profile in Firebase

Jonathan Gamble — Sun, 12 May 2024 13:00:00 GMT

Firebase Authentication is its own Database, separate from Firestore. You can use it securely with any database you like to handle your login needs. However, this database has no filterable queries and is only available to the client for the logged-in user. How you store your user's profile information depends on your app's complexity.

TL;DR

A user’s profile in Firebase specifically refers to the photoURL and the displayName. These two items can be stored and updated in Firebase without using Firestore or Firebase Realtime Database. You can update them by calling the updateProfile function in Firebase Auth SDK. You must choose how to sync your data with other databases.

Where to Store the User?

If you want the best of both worlds, you can store your user profile information inside Firestore and Firebase Authentication. Copying the data on sign-up is easy. However, updating a user can be trickier.

While there is a user().onCreate trigger, there is NOT a user().onUpdate trigger.
There is no way to prevent users from updating their own record in Firebase Authentication once logged in.
Firebase Authentication is free, but Firestore charges per read.

Handling Synchronization

There are trade-offs in everything we do.

1. Use Firebase Auth as the Main Database

This is the easiest and best way for small apps. There is no reason to have a separate users collection when no joins are involved, or you don't need to have a complicated user profile. This can be the best route when dealing only with the user profile information.

Here, we have an updateUser function that can update the displayName and the photoURL.

export const updateUser = async (
    displayName: string,
    photoURL: string
) => {

    if (!auth.currentUser) {
        return {
            error: 'Not Logged In!'
        };
    }
    try {
        await updateProfile(auth.currentUser, {
            displayName,
            photoURL
        });
    } catch (e) {
        if (e instanceof FirebaseError) {
            return {
                error: e.message
            };
        }
    }
    return {};
};

📝 Get the auth object using your Framework Setup.

This puts the boilerplate in one place. You can call it in your component while only returning an error if there is one.

const { error } = await updateUser(displayName, photoURL);
if (error) {
	// handle error
	...
	return;
}
// handle success
...

If you need to get the user information for a public profile on a different user than is logged in, you would have to use Firebase Admin on the server.

// Get user from Firebase Authentication database
export const getProfile = async (uid: string) {

	const { displayName, photoURL } = await adminAuth.getUser(uid);
	
	// Only return the profile values for security
	return {
	    displayName,
	    photoURL
	};

};

📝 Get the adminAuth object using your Firebase Admin Setup.

2 - Update Both Databases on the Client

This version is more obvious but won’t be as safe.

export const updateUser = async (
    displayName: string,
    photoURL: string
) => {

    // Update Firebase Authentication Database
    ...
    
    // Update Firestore Database
    try {
        await updateDoc(
            doc(db, 'users', auth.currentUser!.uid),
            {
                displayName,
                photoURL
            }
        )
    } catch(e) {
        if (e instanceof FirebaseError) {
            return {
                error: e.message
            }
        }
    } 
    return {};
};

3 - Update Both Databases with a Firestore Trigger

If you want to align both databases, you can trigger Firestore to automatically update the Firebase Authentication database when a change occurs.

import { firestore, https } from 'firebase-functions';
import { auth } from 'firebase-admin';

const adminAuth = auth();

export const updateAuthProfile = firestore
    .document('users/{userId}')
    .onUpdate(async (change, context) => {

        const beforeData = change.before.data();
        const afterData = change.after.data();
        const userId = context.params.userId;

        // Initialize an object to hold updates
        const updates: Partial<{
            displayName: string,
            photoURL: string
        }> = {};

        // Check if displayName has been modified
        if (beforeData.displayName !== afterData.displayName) {
            updates.displayName = afterData.displayName;
        }

        // Check if photoURL has been modified
        if (beforeData.photoURL !== afterData.photoURL) {
            updates.photoURL = afterData.photoURL;
        }

        if (!Object.keys(updates).length) {
            console.log('No relevant changes detected in user profile');
            return;
        }

        // Attempt to update the user's Authentication profile
        try {
            await adminAuth.updateUser(userId, updates);
            console.log(`Updated user profile for user ${userId}:`, updates);
        } catch (error) {
            console.error('Error updating user profile:', error);
            throw new https.HttpsError(
                'internal',
                'Failed to update user profile in Auth',
                error
            );
        }
    });

Generation 2

In case you’re using Generation 2.


import { onDocumentUpdated } from 'firebase-functions/v2/firestore';
import { auth } from 'firebase-admin';
import { https } from 'firebase-functions/v2';

const adminAuth = auth();

export const updateAuthProfile = onDocumentUpdated('users/{userId}',
    async (event) => {

        const beforeData = event.data!.before.data();
        const afterData = event.data!.after.data();
        const userId = event.params.userId;

        // Initialize an object to hold updates
        const updates: Partial<{
            displayName: string,
            photoURL: string
        }> = {};

        // Check if displayName has been modified
        if (beforeData.displayName !== afterData.displayName) {
            updates.displayName = afterData.displayName;
        }

        // Check if photoURL has been modified
        if (beforeData.photoURL !== afterData.photoURL) {
            updates.photoURL = afterData.photoURL;
        }

        if (!Object.keys(updates).length) {
            console.log('No relevant changes detected in user profile');
            return;
        }

        // Attempt to update the user's Authentication profile
        try {
            await adminAuth.updateUser(userId, updates);
            console.log(`Updated user profile for user ${userId}:`, updates);
        } catch (error) {
            console.error('Error updating user profile:', error);
            throw new https.HttpsError(
                'internal',
                'Failed to update user profile in Auth',
                error
            );
        }
    });

📝 You could equally use an SQL trigger function or a trigger function in your database of choice.

Caveats

Because there is no guarantee that both databases will stay in sync if you have any client Firebase features, you must choose your principal database; your client API key will be easily available to any programmer.

Use the Firebase Authentication database if you have no need for complex profile features and you want to save on reads.
Use Firestore or any external database if you have any complex data and don’t care about keeping Firebase Authentication database in sync.
Use both databases if keeping the data in sync is not mandatory.

Repo: GitHub

Demo: Vercel Serverless

Svelte 5 Todo App with Firebase

Jonathan Gamble — Wed, 08 May 2024 13:00:00 GMT

Svelte 5 is coming very soon since it has hit the Release Candidate stage. Svelte 5 now has “runes,” Svelte’s version of signals. These are amazing, and I don’t want to go back. Translating my Todo App was extremely easy, as I have built it many times with signals.

TL;DR

Using a Svelte rune outside of a component requires getters and setters. Once you set up your signals correctly, everything works extremely similarly to other Frameworks. $state() works great in a component, but using the Single Responsibility Principle will force smart programmers to create their own sharable runes.

Setup

The setup is the same as in most other Firebase applications. We export the auth and db handlers.

// lib/firebase.ts

import { PUBLIC_FIREBASE_CONFIG } from '$env/static/public';
import { getApp, getApps, initializeApp } from 'firebase/app';
import { getAuth } from 'firebase/auth';
import { getFirestore } from 'firebase/firestore';

const firebase_config = JSON.parse(PUBLIC_FIREBASE_CONFIG);

// initialize and login
export const app = getApps().length
    ? getApp()
    : initializeApp(firebase_config);

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

Types

Add the types to the global namespace in app.d.ts.

type UserType = {
    displayName: string | null
    photoURL: string | null;
    uid: string;
    email: string | null;
};

type Todo = {
    id: string;
    uid: string;
    text: string;
    complete: boolean;
    createdAt: Date;
};

Runes

I’m not sure why Svelte was built like this, as it is a compiler, but you can’t export $state variables from component to component. I made a cheat version similar to Vue and Qwik's signals.

// lib/rune.svelte.ts

export const rune = (initialValue: T) => {

    let _rune = $state(initialValue);

    return {
        get value() {
            return _rune;
        },
        set value(v: T) {
            _rune = v;
        }
    };
};

Notice that you must use the .svelte.ts file type to work correctly with the $state. Again, this could have been the perfect reason to allow $state to work everywhere, but we are stuck making “getters and setters” manually. I don’t want to do it everywhere, so I made a reusable template function.

Shared

The runes and custom runes need to be sharable everywhere, so I reused my shared contexts to work with signals (runes) and stores.

import { getContext, hasContext, setContext } from "svelte";
import { readable, writable } from "svelte/store";
import { rune } from "./rune.svelte";

export const useSharedStore = (
    name: string,
    fn: (value?: A) => T,
    defaultValue?: A,
) => {
    if (hasContext(name)) {
        return getContext(name);
    }
    const _value = fn(defaultValue);
    setContext(name, _value);
    return _value;
};

// writable store context
export const useWritable = (name: string, value?: T) =>
    useSharedStore(name, writable, value);

// readable store context
export const useReadable = (name: string, value: T) =>
    useSharedStore(name, readable, value);

// shared rune
export const useRune = (name: string, value: T) =>
    useSharedStore(name, rune, value);

User Hook

We need to get the user from onIdTokenStateChanged and share it across our app. We must be careful not to call it more than once, so we use our useShared hook above.

import {
    GoogleAuthProvider,
    onIdTokenChanged,
    signInWithPopup,
    signOut,
    type User
} from "firebase/auth";
import { auth } from "./firebase";
import { useSharedStore } from "./use-shared.svelte";
import { onDestroy } from "svelte";
import { rune } from "./rune.svelte";

export const loginWithGoogle = async () =>
    await signInWithPopup(auth, new GoogleAuthProvider());

export const logout = async () =>
    await signOut(auth);

const _useUser = () => {

    const user = rune<{
        loading: boolean,
        data: UserType | null,
        error: Error | null
    }>({
        loading: true,
        data: null,
        error: null
    });

    const unsubscribe = onIdTokenChanged(
        auth,
        (_user: User | null) => {

            // not logged in
            if (!_user) {
                user.value = {
                    loading: false,
                    data: null,
                    error: null
                };
                return;
            }

            // logged in
            const { displayName, photoURL, uid, email } = _user;
            user.value = {
                loading: false,
                data: { displayName, photoURL, uid, email },
                error: null
            };
        }, (error) => {

            // error
            user.value = {
                loading: false,
                data: null,
                error
            };
        });

    onDestroy(unsubscribe);

    return user;
};

export const useUser = (defaultUser: UserType | null = null) =>
    useSharedStore('user', _useUser, defaultUser);

📝Notes

I import the rune function and call it exactly like Qwik and Vue.
We handle the error and loading states in the signal.
ALWAYS unsubscribe. Here, we use onDestroy as we would in a component.

Todos Hook

We need a hook to get our todos and subscribe to the changes.

import {
    collection,
    deleteDoc,
    doc,
    onSnapshot,
    orderBy,
    query,
    serverTimestamp,
    setDoc,
    where,
    QueryDocumentSnapshot,
    type SnapshotOptions,
    Timestamp,
    type PartialWithFieldValue,
    type SetOptions
} from "firebase/firestore";
import { auth, db } from "./firebase";
import { useUser } from "./user.svelte";
import { FirebaseError } from "firebase/app";
import { untrack } from "svelte";
import { rune } from "./rune.svelte";
import { dev } from "$app/environment";

export const genText = () =>
    Math.random().toString(36).substring(2, 15);

const todoConverter = {
    toFirestore(
        value: PartialWithFieldValue,
        options?: SetOptions
    ) {
        const isMerge = options && 'merge' in options;
        if (!auth.currentUser) {
            throw 'User not logged in!';
        }
        return {
            ...value,
            uid: auth.currentUser.uid,
            [isMerge
                ? 'updatedAt'
                : 'createdAt'
            ]: serverTimestamp()
        };
    },
    fromFirestore(
        snapshot: QueryDocumentSnapshot,
        options: SnapshotOptions
    ) {
        const data = snapshot.data(options);
        const createdAt = data['createdAt'] as Timestamp;
        return {
            ...data,
            id: snapshot.id,
            createdAt: createdAt.toDate()
        } as Todo;
    }
};

export const useTodos = () => {

    const user = useUser();

    const _todos = rune<{
        data: Todo[],
        loading: boolean,
        error: FirebaseError | null
    }>({
        data: [],
        loading: true,
        error: null
    });

    $effect(() => {

        const _user = user.value.data;

        // filtering todos depend on user
        if (!_user) {
            untrack(() => {
                _todos.value = {
                    loading: false,
                    data: [],
                    error: null
                };
            });
            return;
        }

        return onSnapshot(
            query(
                collection(db, 'todos'),
                where('uid', '==', _user.uid),
                orderBy('createdAt')
            ).withConverter(todoConverter), (q) => {

                if (q.empty) {
                    _todos.value = {
                        loading: false,
                        data: [],
                        error: null
                    };
                }

                const data = q.docs.map(doc => doc.data({
                    serverTimestamps: 'estimate'
                }));

                if (dev) {
                    console.log(data);
                }

                _todos.value = {
                    loading: false,
                    data,
                    error: null
                };

            }, (error) => {

                // Handle error
                _todos.value = {
                    loading: false,
                    data: [],
                    error
                };
            });
    });
    return _todos;
};

export const addTodo = async (text: string) => {

    setDoc(doc(collection(db, 'todos'))
        .withConverter(todoConverter), {
        text,
        complete: false
    }).catch((e) => {
        if (e instanceof FirebaseError) {
            console.error(e.code)
        }
    });
}

export const updateTodo = async (
    id: string,
    newStatus: boolean
) => {

    try {
        await setDoc(
            doc(db, 'todos', id),
            { complete: newStatus },
            { merge: true }
        );
    } catch (e) {
        if (e instanceof FirebaseError) {
            console.error(e.code);
        }
    }
}

export const deleteTodo = (id: string) => {
    deleteDoc(doc(db, 'todos', id));
}

📝 Notes

This hook is only called once in one component, so we don't need useShared.
I’m using Data Converters, but they are not necessary.
The createdAt date is added, but you could also add the updatedAt date by adding the data converter to the updateTodo function. See Data Converters.
The todos collection subscription is dependent on the user. If there is no user, we need to automatically unsubscribe and resubscribe when there is one. The $effect() function handles this.
To prevent looping, we generally should not set signals inside $effect(). However, we can get around this by setting our todos signal inside the untrack() function.
We don’t need to use untrack() inside the onSnapshot because it is an async function. This means the signal is not tracked.
When we get our Firebase data with a date type, we need to use estimate with serverTimestamps. This will keep our optimistic updates working well for the user. See Dates and Timestamps.

User Components

You can use the user hook in any component, and it will only be called once.



Svelte 5 Firebase Todo App


	{#if user.data}
		
		
		
		
	{:else if user.loading}
		Loading...
	{:else if user.error}
		Error: {user.error}
	{:else}
		
	{/if}

Here we handle the user state with data, loading, and error. However, we cannot destructure signals.

// ⚠️ THIS WILL NOT WORK!
const { value } = useUser();

// ⚠️ NEITHER WILL THIS
const { data, loading, error } = useUser().value;

If we want to have a reactive user value that is just one variable, we need to redefine it as a new signal using $derived. This will work with any long nested value in a signal.

const user = $derived(_user.value);

Todos Component

Notice you will see the same setup for the todos component. Use the $derived to shorten your variable after you get the signal.



{#if todos.data?.length}
	
		{#each todos.data || [] as todo (todo.id)}
			
		{/each}
	
{:else if todos.loading}
	Loading...
{:else if todos.error}
	{todos.error}
{:else}
	Add your first todo item!
{/if}

Server Fetching

Nothing has changed in SvelteKit when it comes to getting data from the server.

About Library

Remember to use firestore/lite if you want to fetch on an Edge Function.

// lib/about.ts
import { doc, getDoc, getFirestore } from "firebase/firestore/lite";
import { app } from "./firebase";

const db = getFirestore(app);

type AboutDoc = {
    name: string;
    description: string;
};

export const getAbout = async () => {

    const aboutSnap = await getDoc(
        doc(db, '/about/ZlNJrKd6LcATycPRmBPA')
    );

    if (!aboutSnap.exists()) {
        throw 'Document does not exist!';
    }

    return aboutSnap.data() as AboutDoc;
};

About Server

Call the about function.

// routes/about/+page.server.ts
import { getAbout } from '$lib/about';
import type { PageServerLoad } from './$types';

export const load = (async () => {

    return {
        about: await getAbout()
    };

}) satisfies PageServerLoad;

About Component

You can display the data with $page or data from the routes directory.




	
		{data.about.name}
		{data.about.description}

Using Runes in Svelte 5 is much easier than Svelte 4 Stores in every scenario.

Repo: GitHub

Demo: Vercel Edge

↪️ See the Svelte 4 Version

Firestore Security Rules Example Guide

Jonathan Gamble — Sun, 05 May 2024 13:00:00 GMT

I want you to learn “how to write Firebase Rules” rather than what specific rules you need to write. Once you understand what kinds of operations are available and how to write clean code, you should be able to write reusable functions for any Firebase app.

TL;DR

Using Firestore Rules can be cumbersome. However, simplifying your rules into reusable functions can make writing complex, secure apps much easier. Remember the Security Rules Limitations, when to use Trigger Functions instead, and how you are charged per document read.

Firestore Rules

// firestore.rules
rules_version = '2';

service cloud.firestore {

  match /databases/{database}/documents {
  
    // MATCHES

    match /users/{document} {
    
		allow read, write: if false;
			
    }
  }
}

Use version 2 by default
Lock your data by default using if false

Permission

allow read - single and multiple documents
- allow get - a single document with getDoc or onSnapshot
- allow list - multiple documents with getDocs or onSnapshot
allow write - create, update, delete
- allow create - create a document with addDoc or setDoc
- allow update - update a document with updateDoc or setDoc using merge
- allow delete - delete a document with deleteDoc

Resource

resource - document being read or written
- resource.data - map of document data
- resource.id - resource document id as string
- resource['__name__'] or request.path - the document name as path

Request

request - the incoming request context
- request.auth - request authentication context
  - uid - user ID
  - token - token map
- request.method - request method
  - get
  - list
  - create
  - update
  - delete
- request.path - path of affected resource
- request.query - map of query properties when present
  - limit
  - offset
  - orderBy
- request.time - time request was received
- request.resource - new resource value, present on write requests only

Request Resource

request.resource - resource document AFTER write
- request.resource - map of document data
- resource.id - resource document id as string
- resource['__name__'] or request.path - the document name as path

Request token

request.auth.token
- email
- email_verified
- phone_number
- name
- sub
- firebase.identities
- firebase.sign_in_provider
- firebase.tenant

Request Patterns

request.path[3] - request collection
request.path[4] - request document id or request.resource.id
request.path[N] - request sub-collection and sub-collection document ID

There is currently no way to check if a request is for a collection or sub-collection document inside a function. See StackOverflow.

Counters and Timestamp Rules

Batch Increment Counters You can verify increments with rules.
Dates and Timestamps You can use request.time to verify serverTimestamp()

Ownership

Create
- Check for ownership after creation
Delete
- Check for ownership before deletion
Update
- Check for ownership both before and after updating

// assumes you have a `createdBy` set to uid

function isOwnerBefore() {
  return request.auth.uid == resource.data.createdBy
   || resource == null;
}

function isOwnerAfter() {
  return request.auth.uid == request.resource.data.createdBy 
    || request.resource == null;
}

📝 Checking for null before and after makes the function usable in more places with write instead of a separate create and update.

Logged In

function isLoggedIn() {
  return request.auth != null;
}

Verifying Keys

You can verify a document only contains certain fields or that only certain fields can be updated. First, you must get the keys() from the map type.

function hasAll(data, fields) {
  // data has all fields
  return data.keys().hasAll(fields);
}

function hasOnly(data, fields) {
  // data has only fields
  return data.keys().hasOnly(fields);
}

function isValidUserDocument() {
  let fields = ['title', 'slug', 'minutes', 'content'];
  return hasAll(request.resource.data, fields);
}

📝 Arrays are lists in Firebase Rules.

List Methods

concat
hasAll
hasAny
hasOnly
join
removeAll
size
toSet - a unique set of lists

Map Methods

diff(map_to_compare)
get(key, default_value)
keys()
size()
values()

String Verification Example

Strings should be verified as well.

// verify the content is string type and at least 2 characters
&& request.resource.data.content is string
&& request.resource.data.content.size() > 2

String Methods

lower()
matches(re)
replace(re, sub)
size()
split(re)
toUtf8()
trim()
upper()

Slug Example

You could verify a slug, although this might be better handled in a trigger write function.

// verify slug = a slugify(title)
// should be updated for utf8 characters
request.resource.data.slug == request.resource.data.title
.lower().replace('[^a-z0-9]+', '-').replace('^-|-$','')

Other Types

You can view the Firestore Rules Index of all functions and operators for all types.

Reading is Expensive

⚠️ Always use the current document from the request.resource, and resource variables. If you need to compare other documents, it will cost one read for each document. You should also consider custom claims instead of reading the user document from request.auth.token. These are all free, as you are already reading the document outside Firestore Rules.

Reading Firestore External Documents

You can compare other documents with four functions when it can't be avoided.

get(path) - document before write
getAfter(path) - document after write
exists(path) - or get(path) != null whether document exists before write
existsAfter(path) - or getAfter(path) != null whether document exists after write

allow write: if exists(/databases/${database)/documents/collectionName/documentID)

Pricing

You are only charged one read for multiple requests to the same document.
You are only charged one read for the same document in a transaction or batch.
- See StackOverFlow Answer by Firebase Staff
Some document access calls may be cached and don’t count against you

Clean Code and Limitations

You need to model your data correctly to avoid the least amount of reads, keep your data consistent, and not have too much hassle. This requires you to know Firestore well, when to use Functions or the Server Environment, and how to write clean code.

Reusable Functions

I personally avoid using variables in the match path. You can get the data you need from the request and resource variables anywhere in your code; there is no reason to create extra function parameters for global variables.

Notable Function Limitations

Maximum of 7 function arguments
Maximum of 10 let variables per function
Maximum of 20 function call depth
Maximum of 1000 expressions evaluated per request

No Loops

You cannot do loops or recursion in Firestore. This means you must set verifiable limits to verify a data set like tags. Your function would need to run a string test 1-5 times, for example. Otherwise, you would use Firebase Functions to prevent problematic documents (after the write).

Match

Put all your match statements in one place, usually at the top or bottom of the document. The top will allow you less scrolling to see what you need. I like to use one function for every match call to keep in line with the Single Responsibilty Principle and to have cleaner code. However, you must keep track of the function dependencies to not reach the Firestore Rules Limitations.


  match /databases/{database}/documents {
  
    // MATCHES

    match /users/{document} {
    
			allow read, write: if allowUser();
			
    }
    
    // FUNCTIONS
    
    function allowUser() {
    
      return isLoggedIn() && isOwner()...
      
    }
    
    ...
    
  }

Writing Firebase Security Rules is an art.

SolidJS Todo App with Firebase

Jonathan Gamble — Wed, 01 May 2024 13:00:00 GMT

I figured SolidJS would be just like React, but it’s not. It’s way better. I had a few learning curves but got my app up and running. My biggest problem is the lack of good documentation for Solid Start techniques, but the framework itself is solid. See what I did there?

TL;DR

Solid Start is similar to NextJS but works differently under the hood. Using helper functions like Show and For makes JSX more bearable and the underlying signals quick. The loaders require a few extra boilerplate steps, but Suspense can be powerful if you need streaming.

Setup

First, set up your .env file with the Firebase credentials as usual but with the VITE_ prefix for client recognition.

VITE_PUBLIC_FIREBASE_CONFIG={"apiKey":"...","authDomain":"..."...}

📝 Make sure your keys have quotes.

Firebase Library

Create your lib/firebase.ts file, sharing your app for the server version.


import { getApp, getApps, initializeApp } from 'firebase/app';
import { getAuth } from 'firebase/auth';
import { getFirestore } from 'firebase/firestore';

const firebase_config = JSON.parse(
    import.meta.env.VITE_PUBLIC_FIREBASE_CONFIG
);

// initialize and login

export const app = getApps().length
    ? getApp()
    : initializeApp(firebase_config);

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

Shared Context

I created a universal Shared Context Library for React. Since this uses almost identical context code as React, it was easy to translate. This allows you to have one provider and import your reusable hooks wherever you want.

import {
    Component,
    JSX,
    createContext,
    useContext,
    type Context
} from "solid-js";

const _Map = () => new Map();
const Context = createContext(_Map());

export const Provider: Component<{ children: JSX.Element }> = ({
    children
}) =>
    {children};

const useContextProvider = (key: string) => {
    const context = useContext(Context);
    return {
        set value(v: T) { context.set(key, v); },
        get value() {
            if (!context.has(key)) {
                throw Error(`Context key '${key}' Not Found!`);
            }
            return context.get(key) as T;
        }
    }
};

export const useShared = (
    key: string,
    fn: (value?: A) => T,
    initialValue?: A
) => {
    const provider = useContextProvider>(key);
    if (initialValue !== undefined) {
        const state = fn(initialValue);
        const Context = createContext(state);
        provider.value = Context;
    }
    return useContext(provider.value);
};

Put the Provider inside the routes/index.ts file so they can be used for our main route. Normally, you would share this everywhere.

import { Title } from "@solidjs/meta";
import Home from "~/components/home";
import { Provider } from "~/lib/use-shared";

export default function Index() {
  return (
    
      
        SolidStart - Firebase
        
      
    
  );
}

🖇️ Notice how easy it is to use the Title tag anywhere in your code edit the meta tag.

User Hook

The signals in Solid work almost identically to useState and useEffect in React; they are just faster and actually use signals. No more useMemo malarky for basic rendering. That being said, you can use createMemo to memoize expensive computations. For this example, we are using createStore, but we could have used createSignal.

import { useShared } from "./use-shared";
import {
    User,
    onIdTokenChanged,
    signOut,
    signInWithPopup,
    GoogleAuthProvider
} from "firebase/auth";
import { auth } from "./firebase";
import { createStore } from "solid-js/store";
import { onCleanup } from "solid-js";

export interface userData {
    photoURL: string | null;
    uid: string;
    displayName: string | null;
    email: string | null;
};

type UserState = {
    loading: boolean;
    data: userData | null;
};

export function _useUser(initialValue: UserState = {
    loading: true,
    data: null
}) {

    const _store = createStore(initialValue);

    const setUser = _store[1];

    setUser(v => ({ ...v, loading: true }));

    // subscribe to user changes
    const unsubscribe = onIdTokenChanged(auth, (_user: User | null) => {

        if (!_user) {
            setUser({ data: null, loading: false });
            return;
        }

        // map data to user data type
        const { photoURL, uid, displayName, email } = _user;
        const data = { photoURL, uid, displayName, email };

        // print data in dev mode
        if (process.env.NODE_ENV === 'development') {
            console.log(data);
        }

        // set store
        setUser({ loading: false, data });
    });

    onCleanup(unsubscribe);

    return _store;
}

export const useUser = (initialValue?: UserState) =>
    useShared('user', _useUser, initialValue);

export const loginWithGoogle = () =>
    signInWithPopup(auth, new GoogleAuthProvider());

export const logout = () => signOut(auth);

📌 User Notice

I’m converting the onIdTokenChanged event handler to a signal.
Always unsubscribe. In SolidJS, we use onCleanup.
Export the hook with useShared, we only want to subscribe once when we share our user state.

Todos Hook

Fetching todos is similar but relies on the user signal.

import {
    type DocumentData,
    onSnapshot,
    type QuerySnapshot,
    Timestamp
} from 'firebase/firestore';
import {
    addDoc,
    collection,
    deleteDoc,
    doc,
    orderBy,
    query,
    serverTimestamp,
    updateDoc,
    where
} from 'firebase/firestore';

import { db } from './firebase';
import { useUser } from './use-user';
import { createStore } from 'solid-js/store';
import { createComputed, onCleanup } from 'solid-js';

export interface TodoItem {
    id: string;
    text: string;
    complete: boolean;
    created: Date;
    uid: string;
};

export const snapToData = (
    q: QuerySnapshot
) => {

    // creates todo data from snapshot
    if (q.empty) {
        return [];
    }
    return q.docs.map((doc) => {
        const data = doc.data({
            serverTimestamps: 'estimate'
        });
        const created = data.created as Timestamp;
        return {
            ...data,
            created: created.toDate(),
            id: doc.id
        }
    }) as TodoItem[];
}

export function useTodos() {

    const _user = useUser();

    const _store = createStore<{
        todos: TodoItem[],
        loading: boolean
    }>({
        todos: [],
        loading: true
    });

    const user = _user[0];

    const setTodos = _store[1];

    setTodos(v => ({
        ...v,
        loading: true
    }));

    createComputed(() => {

        if (!user.data) {
            setTodos({
                loading: false,
                todos: []
            });
            return _store[0];
        }

        const unsubscribe = onSnapshot(

            // query realtime todo list
            query(
                collection(db, 'todos'),
                where('uid', '==', user.data.uid),
                orderBy('created')
            ), (q) => {

                // get data, map to todo type
                const data = snapToData(q);

                /**
                 * Note: Will get triggered 2x on add 
                 * 1 - for optimistic update
                 * 2 - update real date from server date
                 */

                // print data in dev mode
                if (process.env.NODE_ENV === 'development') {
                    console.log(data);
                }

                // add to store
                setTodos({
                    loading: false,
                    todos: data
                });

            });

        onCleanup(unsubscribe);
    });

    return _store[0];
};

export const addTodo = (
    e: SubmitEvent,
    uid: string
) => {

    e.preventDefault();

    // get and reset form
    const target = e.target as HTMLFormElement;
    const form = new FormData(target);
    const { task } = Object.fromEntries(form);

    if (typeof task !== 'string') {
        return;
    }

    // reset form
    target.reset();

    addDoc(collection(db, 'todos'), {
        uid,
        text: task,
        complete: false,
        created: serverTimestamp()
    });
}

export const updateTodo = (id: string, complete: boolean) => {
    updateDoc(doc(db, 'todos', id), { complete });
}

export const deleteTodo = (id: string) => {
    deleteDoc(doc(db, 'todos', id));
}

📌 Todos Notice

I’m using createComputed to derive the onSnapshot event handler to a signal from the user signal.
createComputed is unique to SolidJS and solves the reactivity problem with effect().
Again, always unsubscribe. In SolidJS, we use onCleanup.
We don’t need useShared since this is only called once in one component.
The snapToData converts the collection array of metadata, to actual data. See Data Patterns.

Profile Component

The first big change you will notice with Solid is the Show component. It makes handling JSX much easier. However, when dealing with a possible null or undefined check, you have to wrap the internal child component inside this awkward {() => ( ... )}. I understand this is necessary for proper reactive handling, but it is really a hack for JSX’s shortcomings. Either way, it is better than React.

import { Logout } from "~/lib/helpers";
import { useUser } from "~/lib/use-user";
import Todos from "./todos";
import { Show } from "solid-js";

export default function Profile() {

    const [user] = useUser();

    return (
        
            {(user) => (
                
                    Hi {user().displayName}!
                    
                        {(data) => (
                            
                        )}
                    
                    Your userID is {user().uid}
                    
                    
                
            )}
        
    );
}

Todos Component

The todos require a similar pattern. I must check for the user again since I use a shared hook. If you deal with prop-drilling, you won’t have this problem, but you will have to deal with prop-drilling.

import { addTodo, useTodos } from "~/lib/use-todos";
import { useUser, userData } from "~/lib/use-user";
import { Todo } from "./todo-item";
import { For, Show } from "solid-js";

export default function Todos() {

    const _user = useUser();

    const todoStore = useTodos();

    const user = _user[0];

    return (
        
            {(user) => (
                <>
                    
                        Add your first todo item!}>
                            {(todo, _index) => (
                                
                            )}
                        
                    
                    
                
            )}
        
    );
}

export const TodoForm = (user: userData) => {
    return (
         addTodo(e, user.uid)}>
            
            
        
    );
};

The fallback is a simple way to handle the loading state of an empty array.
The items are tracked automatically, so you don’t need a key. There are no Fragment types in Solid for this.
You still need to pass the odd {(item, index) => ()} inside a For loop.
React uses className, but Solid is smarter and uses our friend class.

Todo Item

The individual todos are cleaner with Show than with ternaries.

import { Show } from "solid-js";
import { TodoItem, deleteTodo, updateTodo } from "~/lib/use-todos";

// each todo item
export const Todo = ({ todo }: { todo: TodoItem }) => {
    return (
        <>
            
                {todo.text}
            
            
                {todo.id}
            
            
                
            
            
                
            
            
        
    );
};

🖇️ I didn’t need the JSX {() => ()} because I wasn’t dealing with null or undefined inside the Show component.

Home

Finally, we can go home. This is the first component that gets rendered, but I saved it for last.

import { Loading, Login } from "~/lib/helpers";
import { useUser } from "~/lib/use-user";
import Profile from "./profile";
import { Match, Switch } from "solid-js";

export default function Home() {

    const [user] = useUser({ data: null, loading: true });

    return (
        
            
                Solid Start Firebase Todo App
            
            }>
                
                    
                
                
                    
                
            
        
    );
}

We set the user for the first time before onAuthIdTokenChanged. I also used Switch and Match to show you other possibilities as well.

About Page

First, create an about library at lib/about.ts that uses Firestore Lite if you want to host on the Edge.

import { doc, getDoc, getFirestore } from "firebase/firestore/lite";
import { app } from "./firebase";

const db = getFirestore(app);

type AboutDoc = {
    name: string;
    description: string;
};

export const getAbout = async () => {

    const aboutSnap = await getDoc(
        doc(db, '/about/ZlNJrKd6LcATycPRmBPA')
    );

    if (!aboutSnap.exists()) {
        throw 'Document does not exist!';
    }

    return aboutSnap.data() as AboutDoc;
};

About Route

Loading the data from the server required a lot of extra boilerplate compared to NextJS, Qwik, or Remix. There were no good, complete examples, so I had to hit up Discord to figure this out.

import { Title } from "@solidjs/meta";
import { RouteDefinition, cache, createAsync } from "@solidjs/router";
import { Show } from "solid-js";
import { getAbout } from "~/lib/about";

// load data once and cache it
const getAboutPage = cache(async () => {
  'use server';
  return await getAbout();
}, 'about');

// preload the data
export const route = {
  load: () => getAboutPage(),
} satisfies RouteDefinition;

export default function About() {

  // get your preloaded data
  const about = createAsync(() => getAboutPage(), { deferStream: true });

  return (
    
      {(data) => (
        <>
          About
          
            
              {data().name}
              {data().description}
            
          
        
      )}
    
  );
};

Solid Start uses Suspense by default to stream your data to the client as it becomes available. This is awesome, but it gives a bad user experience for this particular example. I don’t want the page to ever be blank. Waiting those few extra milliseconds is worth the wait. Adding deferStream accomplished this.

Final Thoughts

I hate JSX, but SolidJS makes it a bit more bearable if you learn its patterns. While the documentation needs more clear examples, building with it was fun.

Demo: Vercel Edge

Repo: GitHub

Local Development with Firebase Emulators

Jonathan Gamble — Sun, 28 Apr 2024 13:00:00 GMT

I noticed there are many articles about creating unit tests with Firestore Emulators, but I find them most useful for building apps. You can run the full Firebase Local Suite without touching your live data in the cloud or creating an extra development database.

TL;DR

Always remember to install Java JDK. Follow the firebase init instructions. Connect the emulators to your app in development mode only, and use the authentication to generate a random fake user for you.

Emulator Setup

Install Java JDK

The Firebase Emulator Suite is built upon the Java JDK. It must be installed first.

Make sure you have Firebase Tools installed globally.

npm install -g firebase-tools

Initialize Firebase inside your project.

firebase init

Select Emulators and whatever features you want to test locally.
Set up the default project.

The full set of Firebase Emulators requires you to link with an existing project. However, you do not have to modify your cloud version if you’re spinning up a project for local testing.

Use the defaults for firestore.rules and firestore.indexes.json files. Install TypeScript because you’re a professional with standards who writes quality code. Use eslint for testing, and go ahead and install dependencies.
Finally, select the default ports and add the emulators you want to use, like Authentication, Functions, and Firestore.

🗈 If you’re using any of my test projects, use firebase use to connect your local instance to an active database in your Firebase Cloud.

Emulator Helper

I like to add a helper in package.json so that the emulators can be run without switching directories. This is particularly useful with Firebase Functions Emulators.

"emulators": "npm run build --prefix functions & firebase emulators:start"

Functions with Eslint

Edit functions/.eslintrc.js to include .eslintrc.js in the ignore file.

  ignorePatterns: [
    "/lib/**/*", // Ignore built files.
    ".eslintrc.js"
  ],

Also, change your rules to fit your style of writing code.


module.exports = {
  root: true,
  env: {
    es6: true,
    node: true,
  },
  extends: [
    "plugin:import/errors",
    "plugin:import/warnings",
    "plugin:import/typescript",
    "google",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: ["tsconfig.json", "tsconfig.dev.json"],
    sourceType: "module",
    tsconfigRootDir: __dirname,
  },
  ignorePatterns: [
    "/lib/**/*", // Ignore built files.
    ".eslintrc.js"
  ],
  plugins: [
    "@typescript-eslint",
    "import",
  ],
  rules: {
    "quotes": ["error", "single"],
    'object-curly-spacing': ['error', 'always'],
    "import/no-unresolved": 0,
    "indent": ["error", 4],
  },
};

Firebase Setup

Create a lib/firebase.ts file and add emulator support. Your framework implementation may vary slightly.

// emulators
if (dev) {
    connectFirestoreEmulator(db, 'localhost', 8080);
    connectAuthEmulator(auth, 'http://localhost:9099');
    connectFunctionsEmulator(functions, "http://localhost", 5001);
}

Here is a full example file.

import { PUBLIC_FIREBASE_CONFIG } from '$env/static/public';
import { dev } from '$app/environment';

import { getApps, initializeApp } from 'firebase/app';
import { connectAuthEmulator, getAuth } from 'firebase/auth';
import { connectFirestoreEmulator, getFirestore } from 'firebase/firestore';
import { connectFunctionsEmulator, getFunctions } from 'firebase/functions';

const firebase_config = JSON.parse(
    PUBLIC_FIREBASE_CONFIG
);

// initialize and login

if (!getApps().length) {
    initializeApp(firebase_config);
}

export const auth = getAuth();
export const db = getFirestore();
export const functions = getFunctions();

// emulators
if (dev) {
    connectFirestoreEmulator(db, 'localhost', 8080);
    connectAuthEmulator(auth, 'http://localhost:9099');
    connectFunctionsEmulator(functions, "http://localhost", 5001);
}

📝 The ports are imported differently depending on the service.

Angular

If you’re using Angular, you must import it into each of the providers array.

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideClientHydration(),
    // Angular Providers
    importProvidersFrom(
      provideFirebaseApp(() => initializeApp(firebaseConfig)),
      provideFirestore(() => {
            const firestore = getFirestore();
            connectFirestoreEmulator(firestore, 'localhost', 8080);
            return firestore;
        }),
      provideAuth(() => getAuth()),
      // provideStorage(() => getStorage()),
      // provideAnalytics(() => getAnalytics()),
    )
  ]
};

Running the Emulators

Thanks to our emulators helper, we can run the emulators in our root directory with npm run emulators. We should get a second window that opens. Minimize that. Our main terminal will have the emulator links. We can click ctrl+ and the link to open a new window with our emulators.

Authentication

When we want to login to our app, we must create a fake profile.

Clicking on add a new account allows us to emulate a real user.

We can then sign in with this fake user to test our app.

Firestore Emulator

The Firestore Emulator will be in purple to clarify that it is a development environment.

Everything else should work as expected. You can now test your app on your local machine without modifying your live data.

Seeding Data

To seed your data, you must write your own functions. You must connect to Firebase Admin, run the function only in dev mode, and call it in your package.json file with a command or in your app only in development mode.

⚠️ All data is lost when you stop the emulators.

Test Projects

You can view some of the projects in my Counters posts for Firebase Emulator examples.

Now go test locally!

Remix Todo App with Firebase

Jonathan Gamble — Wed, 24 Apr 2024 13:00:00 GMT

After creating my Todo App multiple times for other Frameworks, I figured creating it for Remix would be easy. After all, I had already built the components in React for NextJS. I was wrong. Remix has its own eccentricities.

TL;DR

Remix requires a few hacks to get the environment variables to work, but it is not too different from NextJS. Loaders are beautiful, and the idea has been copied into other Frameworks like Qwik and SolidJS. This article shows the pitfalls and configuration settings for a good Remix app with Firebase.

Firebase Config

First, put your Firebase configuration data inside the .env file as usual.

PUBLIC_FIREBASE_CONFIG={"apiKey":"...","authDomain":"..."...}

📝 Make sure your keys have quotes.

Using Environmental Variables

Remix does not make this easy, as this was by far one of my biggest hurdles. In your root.ts file, create a loader for your env file.

export async function loader() {
  return json({
    ENV: {
      PUBLIC_FIREBASE_CONFIG: process.env.PUBLIC_FIREBASE_CONFIG
    },
  });
}

Next, you have to save it to the Window object. This is not my recommended code, but the recommended way by Remix. This should be placed in your Layout component.