How I Integrated Firebase with Algolia Search Using a Local Extension

Integrating Firebase with Algolia to enable full-text search from Firestore seemed like a straightforward task — until I ran into a series of tricky errors related to Firebase Extensions and Cloud Function runtimes. In this post, I'll walk you through what I encountered, how I debugged it, and how I finally got it deployed successfully using the Firebase CLI and a locally patched extension.

Background

I wanted to use the "Search Firestore with Algolia" Firebase Extension to sync documents from a Firestore collection into an Algolia index. Since I was installing from the Firebase Console UI, everything looked fine at first — until deployment failed with a cryptic error.

The Initial Error

Runtime validation errors:
[error_code: INVALID_RUNTIME
message: "Runtime \"nodejs22\" is not supported on GCF Gen1"]

The issue? The extension was trying to deploy Cloud Functions using nodejs22 on Google Cloud Functions Gen 1, which doesn’t support that runtime.

Understanding the Problem

Firebase Extensions default to Gen 1 unless explicitly configured for Gen 2.
Node.js 22 is only supported in Cloud Functions Gen 2.
The Firebase Console UI does not expose the runtime/platform options.

The Fix: Use a Local Extension

I decided to install the extension manually using the Firebase CLI. Here's what I did:

Cloned the extension source code from its public GitHub repository.

Modified the extension.yaml to specify:

platform: gcfv2
runtime: nodejs20

Created a params.env file with my Algolia and Firestore configuration.
Configured my project’s firebase.json to include the extension block.

Another Gotcha: .env File Naming

When defining a custom extension name in firebase.json, the CLI expects a .env file that matches the instance name:

extensions/my-extension-name.env

I had to rename or copy params.env to match this format so Firebase would recognize it.

Unexpected Error: extInstallPath.trim is not a function

This one threw me for a loop. It turns out that the firebase.json file had malformed or extra extension definitions. Firebase CLI expects every extension source to be a clean string path. Removing all leftover or improperly structured entries solved the problem.

New CLI Behavior (Firebase CLI 11+)

With the latest Firebase CLI, running firebase ext:install no longer deploys the extension immediately. Instead, it writes configuration to:

firebase.json
extensions/<instance-name>.env

To apply the changes, you must run:

firebase deploy --only extensions

Success!

After deploying, the extension was successfully installed, functions were created in the correct region using Gen 2, and documents from Firestore started syncing to Algolia.

Conclusion

Firebase Extensions are powerful — but when the defaults don’t align with your setup (like runtime versions), it pays to dive deeper. Installing locally with full control gave me the flexibility to use the latest Node.js and Gen 2 functions while keeping things stable.

Step-by-Step Fix

Clone the extension:

git clone https://github.com/algolia/firebase-extension.git extensions/firestore-algolia-search
cd extensions/firestore-algolia-search

Update the runtime and platform in extension.yaml:
```
platform: gcfv2
runtime: nodejs20
```

Create a params.env file:

ALGOLIA_APP_ID=your_algolia_app_id
ALGOLIA_API_KEY=your_algolia_admin_api_key
FIELDS=title,description,company
INDEXES=jobs
COLLECTION_PATH=jobs

Configure firebase.json in your project root:

{
  "extensions": {
    "algolia-extension": {
      "source": "extensions/firestore-algolia-search",
      "params": {
        "ALGOLIA_APP_ID": "your_algolia_app_id",
        "ALGOLIA_API_KEY": "your_algolia_admin_api_key",
        "FIELDS": "title,description,company",
        "INDEXES": "jobs",
        "COLLECTION_PATH": "jobs"
      }
    }
  }
}

Ensure the params file matches the instance name:

cp extensions/firestore-algolia-search/params.env extensions/algolia-extension.env

Deploy the extension:

firebase deploy --only extensions --project your_project_id

New CLI Behavior (Firebase CLI 11+)

With the latest Firebase CLI, running firebase ext:install no longer deploys the extension immediately. Instead, it writes configuration to:

firebase.json
extensions/<instance-name>.env

To apply the changes, you must run:

firebase deploy --only extensions

Success!

After deploying, the extension was successfully installed, functions were created in the correct region using Gen 2, and documents from Firestore started syncing to Algolia.

Hopefully, this guide saves you a few hours of trial and error if you hit the same roadblocks!

Search This Blog