Firebase Plugin

Deploy Genkit applications to Firebase and enable telemetry

Firebase Plugin

The @genkit-ai/firebase plugin provides Firebase integration for Genkit, including deployment to Cloud Functions for Firebase and comprehensive telemetry/monitoring capabilities.

Installation

npm install @genkit-ai/firebase

Features

• Telemetry & Monitoring - Production observability in Firebase console
• Durable Streaming - Persistent stream state with Firestore or Realtime Database
• Cloud Functions - Deploy flows as Firebase Cloud Functions
• Firebase Integration - Seamless integration with Firebase services

Basic Setup

Enable Telemetry

import { genkit } from 'genkit';
import { enableFirebaseTelemetry } from '@genkit-ai/firebase';

enableFirebaseTelemetry();

const ai = genkit({
  plugins: [
    // Your other plugins
  ],
});

This enables:

• Request tracing
• Performance metrics
• Error tracking
• Usage analytics

View telemetry in the Firebase Console under Genkit.

Durable Streaming (Beta)

Durable streaming persists stream state, allowing clients to disconnect and reconnect without losing progress. The plugin provides two StreamManager implementations:

Firestore Stream Manager

Persists stream state in Google Cloud Firestore:

import { expressHandler } from '@genkit-ai/express';
import { FirestoreStreamManager } from '@genkit-ai/firebase/beta';
import express from 'express';
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

// Initialize Firebase
const fApp = initializeApp();

// Create Firestore stream manager
const firestore = new FirestoreStreamManager({
  firebaseApp: fApp,
  db: getFirestore(fApp),
  collection: 'streams',  // Collection to store streams
});

// Use with Express handler
const app = express();
app.use(express.json());

app.post('/myDurableFlow', expressHandler(myFlow, { 
  streamManager: firestore 
}));

app.listen(8080);

Firestore Limitations:

• Maximum document size: 1MB (strict Firestore limit)
• If stream output exceeds 1MB, the flow will fail
• Store entire stream history in a single document

Realtime Database Stream Manager

Persists stream state in Firebase Realtime Database:

import { RtdbStreamManager } from '@genkit-ai/firebase/beta';
import { initializeApp } from 'firebase-admin/app';

const fApp = initializeApp();

// Create RTDB stream manager
const rtdb = new RtdbStreamManager({
  firebaseApp: fApp,
  refPrefix: 'streams',  // Database path prefix
});

app.post('/myDurableRtdbFlow', expressHandler(myFlow, { 
  streamManager: rtdb 
}));

RTDB Considerations:

• No strict 1MB limit like Firestore
• Better for larger streams
• May impact performance with very large streams
• Subject to other RTDB quotas

Client Usage

Clients can connect and reconnect to durable streams:

import { streamFlow } from 'genkit/beta/client';

// Start a new stream
const result = streamFlow({
  url: 'http://localhost:8080/myDurableFlow',
  input: 'tell me a long story',
});

// Get and save the stream ID
const streamId = await result.streamId;
console.log('Stream ID:', streamId);

// Process chunks
for await (const chunk of result.stream) {
  console.log('Chunk:', chunk);
}

// ... later, reconnect to the same stream ...
const reconnectedResult = streamFlow({
  url: 'http://localhost:8080/myDurableFlow',
  streamId: streamId,  // Reconnect with saved ID
});

for await (const chunk of reconnectedResult.stream) {
  console.log('Resumed chunk:', chunk);
}

Deployment

Deploy to Cloud Functions for Firebase

1. Initialize Firebase project:

firebase init functions

2. Define flows in functions/src/index.ts:

import { genkit } from 'genkit';
import { enableFirebaseTelemetry } from '@genkit-ai/firebase';
import { googleAI } from '@genkit-ai/google-genai';
import * as functions from 'firebase-functions';
import { z } from 'genkit';

enableFirebaseTelemetry();

const ai = genkit({
  plugins: [googleAI()],
});

const generateStory = ai.defineFlow(
  {
    name: 'generateStory',
    inputSchema: z.object({ theme: z.string() }),
    outputSchema: z.string(),
  },
  async ({ theme }) => {
    const { text } = await ai.generate({
      model: googleAI.model('gemini-2.5-flash'),
      prompt: `Write a short story about ${theme}`,
    });
    return text;
  }
);

// Export as Cloud Function
export const storyFlow = functions.https.onCall(async (data, context) => {
  return await generateStory(data);
});

3. Deploy:

firebase deploy --only functions

Using with Express

For HTTP endpoints, combine with the Express plugin:

import { startFlowServer } from '@genkit-ai/express';
import { enableFirebaseTelemetry } from '@genkit-ai/firebase';
import { genkit } from 'genkit';

enableFirebaseTelemetry();

const ai = genkit({
  plugins: [/* your plugins */],
});

const myFlow = ai.defineFlow(
  { name: 'myFlow' },
  async (input) => {
    // Flow logic
    return result;
  }
);

// Start server with Firebase telemetry enabled
startFlowServer({
  flows: [myFlow],
  port: 3000,
});

Telemetry Features

Automatic Tracking

When Firebase telemetry is enabled, Genkit automatically tracks:

• Flow executions - Start time, duration, success/failure
• Model calls - Provider, model name, tokens used, latency
• Tool calls - Tool name, execution time, errors
• Errors - Stack traces, error types, frequency
• Custom traces - User-defined trace spans

View in Firebase Console

1. Go to Firebase Console
2. Select your project
3. Navigate to Genkit section
4. View:
   • Flow performance metrics
   • Model usage and costs
   • Error rates and logs
   • Request volumes
   • Latency percentiles

Custom Traces

Add custom tracing to your flows:

import { runInNewSpan } from 'genkit';

const myFlow = ai.defineFlow(
  { name: 'myFlow' },
  async (input) => {
    // Custom trace span
    const result = await runInNewSpan(
      { name: 'processData' },
      async () => {
        // Processing logic
        return processedData;
      }
    );
    
    return result;
  }
);

Configuration Options

Telemetry Options

enableFirebaseTelemetry({
  projectId: 'my-firebase-project',  // Optional: auto-detected
  // Additional configuration options
});

Stream Manager Options

Firestore:

new FirestoreStreamManager({
  firebaseApp: fApp,          // Required: Firebase app instance
  db: getFirestore(fApp),     // Required: Firestore instance
  collection: 'streams',      // Required: Collection name
})

Realtime Database:

new RtdbStreamManager({
  firebaseApp: fApp,          // Required: Firebase app instance
  refPrefix: 'streams',       // Required: Database path prefix
})

Best Practices

Production Monitoring

1. Always enable telemetry in production:

if (process.env.NODE_ENV === 'production') {
  enableFirebaseTelemetry();
}

2. Set up alerts in Firebase Console for:

   • High error rates
   • Increased latency
   • Usage spikes

3. Review metrics regularly to identify:

   • Performance bottlenecks
   • Cost optimization opportunities
   • Usage patterns

Durable Streaming

1. Choose the right storage:

   • Firestore - Most use cases, strict 1MB limit
   • RTDB - Larger streams, more flexible

2. Handle stream limits:

try {
  const result = await streamFlow({ url, input });
  for await (const chunk of result.stream) {
    console.log(chunk);
  }
} catch (error) {
  if (error.message.includes('1MB')) {
    console.error('Stream exceeded Firestore limit');
    // Consider using RTDB or chunking differently
  }
}

3. Clean up old streams periodically:

// Firestore cleanup
const oldStreams = await db.collection('streams')
  .where('createdAt', '<', oneWeekAgo)
  .get();

for (const doc of oldStreams.docs) {
  await doc.ref.delete();
}

Security

Secure your Cloud Functions:

import * as functions from 'firebase-functions';

export const secureFlow = functions.https.onCall(async (data, context) => {
  // Check authentication
  if (!context.auth) {
    throw new functions.https.HttpsError(
      'unauthenticated',
      'User must be authenticated'
    );
  }
  
  // Check authorization
  if (!context.auth.token.admin) {
    throw new functions.https.HttpsError(
      'permission-denied',
      'User must be admin'
    );
  }
  
  return await myFlow(data);
});

Links

• Firebase Console
• Deploying Genkit with Firebase
• Genkit Monitoring
• Cloud Functions Documentation
• Firestore Documentation
• Realtime Database Documentation
• Source Code