AutoGineer
Generated banner for Extension To Functions Codebase
Generated logo for Extension To Functions Codebase

Extension To Functions Codebase

Firebase (Google)OfficialCreated by Google LLCDistributed by Firebase (Google)

  • Skill
  • Workflow
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Skill for converting an installed Firebase Extension (or extension source) into a standalone Cloud Functions for Firebase codebase or publishable npm package, including V1 to V2 trigger upgrades, lifecycle hooks, and declarative security
— the description by Google LLC

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured process for converting Firebase Extensions into either a local Cloud Functions codebase for direct application integration or a publishable npm package for reuse. It emphasizes modernizing legacy V1 triggers to V2, implementing declarative IAM and API management, and utilizing the Destructuring Compatibility Shim to preserve existing business logic during the transition.

What it does

  • Converts extension configuration parameters into modern defineString, defineInt, and defineSecret declarations.
  • Upgrades V1 Cloud Functions triggers to V2 using the Destructuring Compatibility Shim.
  • Maps extension lifecycle events to SDK lifecycle hooks like afterFirstDeploy and afterRedeploy.
  • Configures package.json for reusable npm distribution with proper peer dependencies and exports.
  • Implements declarative IAM roles and API requirements directly within the codebase.
  • Generates documentation including installation instructions and configuration references.

When to use it

  • When you need to move from a managed Firebase Extension to a custom, maintainable codebase.
  • When you want to share extension logic across multiple projects as a reusable npm package.
  • When you need to modernize legacy V1 functions to V2 while preserving complex internal logic.
  • When you want to replace manual gcloud scripts with declarative infrastructure-as-code.

Advantages

  • Preserves existing business logic through the use of the Destructuring Compatibility Shim.
  • Reduces local configuration overhead by using native SDK declarations for IAM and APIs.
  • Enables modern V2 features like increased concurrency and improved runtime options.
  • Provides a clear path for creating shareable, version-controlled function packages.

Usage examples

“Migrate my installed Firebase Extension to a local functions codebase.”
The agent will inventory your extension.yaml, map parameters to define functions, upgrade triggers to V2, and structure the code in functions/src/.
“Convert this extension into a reusable npm package.”
The agent will configure your package.json, set up the exports map, and generate a README for consumers to re-export your functions.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/firebase/extension-to-functions-codebase/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip extension-to-functions-codebase.zip -d .agents/skills

Documentation by Google LLC

Extension to Functions Codebase & npm Package Migration

Overview

Migrates a Firebase Extension into either:

  1. A local Cloud Functions codebase (functions/src/ for app integration).

  2. A publishable npm package (reusable open-source package exporting V2 functions).

Leverages native Cloud Functions features (declarative IAM, Parameterized Config, SDK Lifecycle Hooks) and modernizes 1st Gen triggers to 2nd Gen using the Destructuring Compatibility Shim.

Target Migration Workflows

  • Target A: Local Functions Codebase (End-User App Integration)

    • Output: Code under functions/src/. Config in .env.

    • Deployment: firebase deploy --only functions.

  • Target B: Publishable npm Package / Shareable Package

    • Output: Reusable npm package exporting V2 functions.

    • Configuration: package.json specifying exports map, engines: { "node": ">=22" }, and peerDependencies: { "firebase-functions": ">=6.0.0" }.

    • Usage: Consumers install package and re-export functions in index.ts (export * from "<package-name>").

Core Rules & Constraints

1. Declarative IAM & APIs (Zero-Local-Overhead)

Use native SDK declarations instead of manual gcloud scripts or console instructions:

  • Use requiresRole("roles/...") for required GCP IAM permissions.

  • Use requiresAPI("service.googleapis.com", "Description") for Google APIs.

2. Global Parameter Access Restriction

  • Never call .value() at top-level module load scope.

  • Initialize global SDK instances inside onInit() or lazy getters:

    import { defineString } from "firebase-functions/params";
import { onInit } from "firebase-functions/v2";

const dataset = defineString("DATASET_ID");
let client: BigQuery;

onInit(() => {
  client = new BigQuery({ datasetId: dataset.value() });
});
3. V2 Concurrency & Cost Parity

V2 enables concurrency (up to 80 requests). To preserve V1 single-concurrency pricing, set cpu: "gcf_gen1".

Step-by-Step Migration Execution

Step 1: Inventory Extension Resources

  1. extension.yaml:

    • params → defineString, defineInt, defineBoolean, defineSecret.

    • apis → requiresAPI(...).

    • roles → requiresRole(...).

    • lifecycleEvents → afterFirstDeploy & afterRedeploy.

    • resources → Upgrade 1st Gen triggers to 2nd Gen (onDocumentWritten, onTaskDispatched, onRequest).

  2. Files & Scripts: Preserve devDependencies, test framework (jest), and test scripts.

Step 2: Configure package.json

  • Set name: "<package-name>", engines: { "node": ">=22" }.

  • Set peerDependencies:

    "peerDependencies": {
  "firebase-admin": "^11.0.0 || ^12.0.0",
  "firebase-functions": ">=6.0.0"
}

  • Configure exports map targeting ESM/CommonJS and TypeScript declarations (lib/index.js, lib/index.d.ts).

Step 3: Upgrade Triggers from V1 to V2

  • Firestore: Use onDocumentWritten from firebase-functions/v2/firestore.

  • Tasks: Use onTaskDispatched from firebase-functions/v2/tasks. Remove EXT_INSTANCE_ID when enqueueing tasks.

  • HTTP: Use onRequest from firebase-functions/v2/https.

  • Apply Destructuring Compatibility Shim ({ change, context }, { snapshot, context }) where legacy 1st Gen handlers expect (change, context).

Step 4: Convert Lifecycle Events

Map extension lifecycle events to SDK lifecycle hooks in src/index.ts:

  • onInstall → afterFirstDeploy({ task: { function: "initTask" } })

  • onUpdate / onConfigure → afterRedeploy({ task: { function: "setupTask" } })

Step 5: Package README & Export Instructions

Generate README.md containing:

  1. Installation instructions (npm install).

  2. Re-export snippet (export * from "<package-name>").

  3. Parameterized Configuration .env reference table.

  4. What Changed (Extension vs Package) comparison table.

Reminder: NEVER execute npm publish.

Files

references/destructuring-shim.md

Architectural Deep Dive: Destructuring Compatibility Shim

The Destructuring Compatibility Shim is a Zero-Touch Logic Migration pattern. It allows you to upgrade a function's infrastructure to V2 (and take advantage of GCF 2nd Gen runtimes) without rewriting any of your internal business logic.

How it Works

When you migrate a V1 function to V2, the signature changes from two parameters (data, context) to a single CloudEvent object.

Instead of manually rewriting all usages of context.params or message.json inside the function, you use JavaScript's Object Destructuring in the signature.

Example Transformation
Step 1: Legacy V1
export const processOrder = functions.pubsub.topic("orders").onPublish((message, context) => {
  const orderId = message.json.id;
  console.log(`Processing order ${orderId} at ${context.timestamp}`);
});
Step 2: Modern V2 + Shim

We change the trigger to onMessagePublished, and instead of accepting event, we destructure { message, context } directly:

export const processOrder = onMessagePublished("orders", ({ message, context }) => {
  const orderId = message.json.id; // Legacy logic remains untouched!
  console.log(`Processing order ${orderId} at ${context.timestamp}`);
});
Why This Works

The Firebase Functions SDK uses a utility called addV1Compat to attach these properties via Lazy Getters on the CloudEvent object for standard event triggers. When you attempt to destructure { message, context } from the event, the SDK transparently maps the V2 event properties back into V1-compatible objects on the fly! This feature is available in modern V2 environments supported by the SDK.

Provider Mapping Examples

Here are the exact destructuring patterns for every supported V2 provider:

1. Cloud Firestore

  • Created / Deleted triggers:

    // V2: onDocumentCreated, onDocumentDeleted
export const processDoc = onDocumentCreated("users/{id}", ({ snapshot, context }) => { ... });

  • Updated / Written triggers:

    // V2: onDocumentUpdated, onDocumentWritten
export const processDoc = onDocumentUpdated("users/{id}", ({ change, context }) => { ... });
2. Cloud Storage

  • All triggers (onObjectFinalized, onObjectDeleted, onObjectArchived, onObjectMetadataUpdated):

    export const processFile = onObjectFinalized(({ object, context }) => { ... });
3. Realtime Database

  • Created / Deleted triggers:

    export const processData = onValueCreated("/users/{id}", ({ snapshot, context }) => { ... });

  • Updated / Written triggers:

    export const processData = onValueWritten("/users/{id}", ({ change, context }) => { ... });
4. Remote Config

  • Updated triggers:

    export const processConfig = onConfigUpdated(({ version, context }) => { ... });

Best Practices for AI Agents

  1. Rely on the shim for complex logic. When converting functions with extensive or complex internal business logic, prefer using the destructuring shim ({ shimmedKey, context }) by default to minimize risk and avoid introducing subtle bugs.

  2. Clean-room rewrites. If the function body is very simple, or if the user explicitly asks for a comprehensive code modernization/cleanup, you can ask the user if they would prefer a full clean-room rewrite to native V2 event properties.

  3. Always type-check (tsc) after the rewrite. If the types are wrong, the shim might not be fully supported for that specific provider yet.

  4. HTTPS Callables (Flattened Context): Unlike event triggers, Callables do not use V1Compat or a context object. Instead, all context properties are flattened onto the request object.

    • V1 Priority: (data, context) => { ... }

    • V2 Equivalent: ({ data, auth, app }) => { ... }

Related Migrations

For a complete guide on migrating runtime options and functions.config() to V2 Parameterized Configuration, refer to configuration-migration.md.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Google LLC
Publisher
Firebase (Google) (Official)
Distributed by
Firebase (Google)
Source
firebase/agent-skills · skills/extension-to-functions-codebase · commit b76be96
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Google LLC or Firebase (Google).

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download extension-to-functions-codebase.zip