# Extension To Functions Codebase

> 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

Source: https://skillsagentes.com/skills/firebase/agent-skills/extension-to-functions-codebase
Repository: https://github.com/firebase/agent-skills
Author: firebase
License: Apache-2.0
Updated: hace 8 días
Context cost: 59 tok installed, 1.1k tok once triggered, 5k tok with every bundled file
Bundle: 4 files, 19 KB
Permissions requested: none declared

## Install

```bash
npx -y skills add firebase/agent-skills --skill extension-to-functions-codebase --agent claude-code
```

## What it does

- Convierte una Firebase Extension instalada (o su código fuente) en un codebase local de Cloud Functions o en un paquete npm publicable
- Migra triggers de 1st Gen a 2nd Gen usando el Destructuring Compatibility Shim
- Sustituye scripts manuales de gcloud por requiresRole() y requiresAPI() declarativos
- Convierte lifecycleEvents de la extensión (onInstall, onUpdate/onConfigure) en afterFirstDeploy y afterRedeploy
- Genera package.json, exports map y README.md con instrucciones de reexportación

## Use it when

- Se quiere sacar una Firebase Extension de su formato y convertirla en un codebase de functions/src/ para integrarla en una app
- Se quiere convertir una extension en un paquete npm reutilizable que exporte funciones V2
- Se necesita actualizar triggers 1st Gen (onDocumentWritten, onTaskDispatched, onRequest) a 2nd Gen

## What triggers it

- "Convierte esta Firebase Extension en un codebase de Cloud Functions"
- "Migra este extension.yaml a funciones V2 y publícalo como paquete npm"
- "Actualiza estos triggers V1 de la extensión a V2 con onDocumentWritten"

## Before you install

- Requiere el extension.yaml y el código fuente de la extensión a migrar, además de Node >=22 y firebase-functions >=6.0.0.

## Files

- SKILL.md — 4 KB
- references/configuration-migration.md — 6 KB
- references/destructuring-shim.md — 4 KB
- references/signature-mapping.md — 4 KB

## SKILL.md

Reproduced verbatim from firebase/agent-skills under Apache-2.0. This section is the upstream document and is in English.

# 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).
1. **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:
  ```typescript
  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`).
1. **Files & Scripts**: Preserve devDependencies, test framework (`jest`), and
   test scripts.

### Step 2: Configure `package.json`

- Set `name: "<package-name>"`, `engines: { "node": ">=22" }`.
- Set `peerDependencies`:
  ```json
  "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`).
1. Re-export snippet (`export * from "<package-name>"`).
1. Parameterized Configuration `.env` reference table.
1. What Changed (Extension vs Package) comparison table.

_Reminder: NEVER execute `npm publish`._

---

Skills Agentes — https://skillsagentes.com/skills/firebase/agent-skills/extension-to-functions-codebase