Index of every page on this site: llms.txt
All skills
firebase avatar

/extension-to-functions-codebase

@99954a3 official
by firebasefirebase/agent-skills520 stars
116
Run it yourself

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

Use this Skill: https://skilld.dev/gh/firebase/agent-skills/extension-to-functions-codebase

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈68 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈3.8k more on demand in 3 files.

Description uses 3.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈271 characters, or 3.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill facilitates the migration of Firebase Extensions to Cloud Functions or npm packages. While structurally sound and focused on development workflows, it possesses an attack surface for indirect prompt injection by processing untrusted external configuration and source code.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 99954a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 months ago
metadata
{
  "author": "Google LLC",
  "category": "Serverless"
}

README badge

README badge for firebase/agent-skills/extension-to-functions-codebase