extension-to-functions-codebase

Takes a Firebase Extension — a ready-made add-on installed into your project — and turns it into ordinary code you own, either inside your app's own backend functions or as a package other people can install.

WHEN TO USE

SCOPE

USE FOR

Bring an installed extension's code into your project's own functions so you can change it freely.
Turn an extension into a reusable package, ready for you to publish yourself.
Upgrade the extension's code from the older generation of Cloud Functions to the current one.
Keep running costs as they were by holding each function to one request at a time after the move.
Get a README covering install steps, settings and what changed compared with the extension.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (5)

Extension to Functions Codebase & npm Package Migration

Overview

Migrates a Firebase Extension into either:

A local Cloud Functions codebase (functions/src/ for app integration).
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

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).
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:

Installation instructions (npm install).
Re-export snippet (export * from "<package-name>").
Parameterized Configuration .env reference table.
What Changed (Extension vs Package) comparison table.

Reminder: NEVER execute npm publish.

Account or credentials required

You'll need access credentials, such as an API key or token.

This skill ships inside the Firebase Agent Skills plugin. Listed package contents include 1 agent and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add firebase/agent-skills --skill "extension-to-functions-codebase" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Firebase Agent Skills plugin package selected for your AI tool.

Add the plugin's marketplace, then install it

Install Claude Code first to get the claude command, then run the commands below in your terminal, outside a Claude Code session.

claude plugin marketplace add firebase/agent-skills
claude plugin install firebase@firebase

Add Firebase's marketplace, then install the plugin

Run both lines in a terminal. They add Firebase's marketplace, which is this repository, and install the firebase plugin: Firebase's skills plus the Firebase MCP server.

01

codex plugin marketplace add firebase/agent-skills

02
```
codex plugin add firebase@firebase
```

Installation and loading

Start a new Codex session before using it.

Good to know

Plugins work in Codex CLI and the ChatGPT desktop app, not in the Codex IDE extension.
For the desktop app, Firebase has you run the first line, fully restart the app, then install Firebase from Plugins.

Run it in a terminal, not inside a Gemini CLI session. It installs this repository as a Gemini CLI extension with Firebase's skills and the Firebase MCP server.

Install checklist

Installing from GitHub needs git on your computer.
Node.js, because the Firebase MCP server starts through npx.

gemini extensions install https://github.com/firebase/skills

Installation and loading

Restart Gemini CLI if it is already open.

Good to know

The address uses the repository's earlier name, firebase/skills, which GitHub forwards to firebase/agent-skills.

Open plugin page ↗

View on GitHub

The repository is licensed under Apache-2.0 — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →

Extension to Functions Codebase & npm Package Migration

Overview

Target Migration Workflows

Core Rules & Constraints

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

2. Global Parameter Access Restriction

3. V2 Concurrency & Cost Parity

Step-by-Step Migration Execution

Step 1: Inventory Extension Resources

Step 2: Configure package.json

Step 3: Upgrade Triggers from V1 to V2

Step 4: Convert Lifecycle Events

Step 5: Package README & Export Instructions

Account or credentials required

Install just this skill

Install the whole plugin

Add the plugin's marketplace, then install it

Add Firebase's marketplace, then install the plugin

More skills

firebase-ai-logic-basics

firebase-app-hosting-basics

firebase-auth-basics

firebase-basics

firebase-crashlytics

firebase-data-connect

Step 2: Configure `package.json`