feat(functions): add functions:kits:install command by wandamora · Pull Request #10900 · firebase/firebase-tools

wandamora · 2026-08-07T00:00:41Z

Description

Adds the firebase functions:kits:install command (gated behind the kits experiment) to allow developers to install and configure reusable Cloud Function kits in their Firebase projects.

Note: this is the first iteration of the command that just handles the first instance in a single project.

Key Changes:

Command Registration & Experiment Gating: Registers functions:kits:install conditionally when the kits experiment is enabled.
Interactive & Flag Input: Accepts a --npm_package <package> flag, and interactively prompts for the kit and initial instance ID.
Package Parsing & Validation:
- Parses scoped and unscoped package specifiers with optional versions/tags.
- Sanitizes package names into valid kit identifiers.
- Validates kit ID uniqueness and ensures instance IDs do not collide with existing codebase names or other kit instances in firebase.json.
Security & Third-Party Safeguards:
- Differentiates first-party (@firebase-functions-kits/*) and third-party packages.
- Inspects packages for npm-shrinkwrap.json via npm pack --dry-run --json to warn users when dependencies are unlocked.
- Prompts for explicit user confirmation before installing third-party kits.
- Installs third-party packages with --ignore-scripts for safety.
Wrapper Project Scaffolding:
- Scaffolds a wrapper directory under function-kits/<kit-id>/ containing package.json, tsconfig.json, .gitignore, and src/index.ts from templates.
- Generates index.ts using templates/init/functions/typescript/index-kit.ts, re-exporting the kit package with customizable global function parameters.
- Automatically runs npm install and npm run build.
Configuration Updates: Adds the kit configuration block and instance mapping into firebase.json.
Testing: Comprehensive unit test suite in src/commands/functions-kits-install.spec.ts.

Scenarios Tested

Experiment gating: Verified error is thrown when kits experiment is disabled.
Precondition checks: Verified error when run outside a Firebase project directory (firebase.json missing).
Package specifier parsing for scoped/unscoped packages with and without versions.
Package name sanitization to valid kit identifiers (length truncation, character filtering).
Third-party package detection and warnings for packages without npm-shrinkwrap.json.
User confirmation flow cancellation / acceptance for third-party kits.
Validated that third-party kits run npm install --ignore-scripts.
Kit installation end-to-end scaffolding (package.json, tsconfig.json, index.ts, firebase.json).
Conflict validations:
- Duplicate functions.kit ID in firebase.json.
- Collision between kit instanceId and existing function codebase name.

Sample Commands

# Enable the kits experiment
firebase experiments:enable kits

# Install a package CLI
firebase functions:kits:install --npm_package @invertase/example-firebase-kit-hello-world@0.1.0

wiz-9635d3485b · 2026-08-07T00:01:16Z

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	13
Software Management Findings	-

Total	13

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

gemini-code-assist

Code Review

This pull request introduces the functions:kits:install command, allowing users to install Cloud Function kits into their Firebase projects. It includes implementation logic, unit tests, command registration under the kits experiment, and a TypeScript entry point template. The review feedback highlights two key areas for improvement: first, a potential runtime crash in functions-kits-install.ts due to unsafe direct access of options.config.src after using optional chaining; second, the need to throw a FirebaseError immediately if parsing the package.nolint.json template fails, rather than silently continuing with an empty object and causing downstream build failures.

- throw error for failing to parse template - remove redundant ? for options.config.src, it shouldn't be undefined or null

package.json, tsconfig.json, and .gitignore should live in the root of the kit, and index.ts will be in /src.

- Prompt for kit ID - Update npm shrinkwrap warning - change FIREBASE_FUNCTION_KIT_REGION param to FUNCTION_KIT_REGION

ajperel

Thanks for getting this out!

A bunch of minor comments and questions and a few things we should iron out through discussion.

ajperel · 2026-08-08T01:10:02Z

+      const res = parsePackageSpecifier("my-kit@^2.0.0");
+      expect(res).to.deep.equal({
+        packageName: "my-kit",
+        version: "^2.0.0",


Probably also good to test release candidate versions since we'll use them

or tags like @latest

technically npm distinguished between versions and tags but maybe we can just call it all version and get away with that?

Thoughts @inlined ?

ajperel · 2026-08-08T01:13:07Z

+    });
+
+    it("should return true for packages outside @firebase-functions-kits scope", () => {
+      expect(isThirdPartyPackage("@other-scope/my-kit")).to.be.true;


I'd test "@firebase-function-kits-fake/foo" to also be 3rd party. Gotta stop the people trying to be malicious.

ajperel · 2026-08-08T01:16:10Z

+      ).to.be.rejectedWith(FirebaseError, /functions.kit must be unique/);
+    });
+
+    it("should reject instance ID that collides with codebase name", async () => {


Even now we should also test and reject instance ID that collides with another since you could have two different kits that decide to use the same instance id if the user picks silly ones.

ajperel · 2026-08-08T01:21:12Z

+const INDEX_KIT_TEMPLATE = readTemplateSync("init/functions/typescript/index-kit.ts");
+
+export interface FunctionsKitsInstallOptions extends Options {
+  npm_package?: string;


As I see this.... I am again debating between this and

--package
(future) --package_manager

Pros:

We only ever need 2 flags (I hope)

Maybe easier to re-use logic in the future in cases where like... yarn packages and npm packages are the same since they are both npm behind the scenes

Cons:

Users not using npm have to always specify two flags instead of one.

I am still very torn. Curious what you and @inlined think after getting into it more.

ajperel · 2026-08-08T01:22:51Z

+ * e.g., "@firebase-functions-kits/firestore-bigquery-export" -> "firestore-bigquery-export"
+ */
+export function sanitizePackageNameToKitName(packageName: string): string {
+  const parts = packageName.split("/");


I think this is true but you've verified that package names can only have one "/" and only if scoped right?

ajperel · 2026-08-08T02:03:33Z

+      }
+    }
+
+    pkgJson.name = `${kitId}-wrapper`;


I think it's worth a comment explaining what you're doing and why.

ajperel · 2026-08-08T02:04:39Z

+      await options.config.askWriteProjectFile(relIndexTsPath, indexContent);
+    }
+
+    const installArgs = isThirdParty ? ["install", "--ignore-scripts"] : ["install"];


I wonder if we should just always ignore scripts. Yes, we could technically trust ours more... but when would we use them?

ajperel · 2026-08-08T02:13:31Z

+    const newKitConfig: KitFunctionConfig = {
+      kit: kitId,
+      sourcePackage: {
+        id: packageName,


This is 100% what we put in the design doc... but as I brush up while reviewing...
none of the package systems talk about ids. They talk about package / distribution names. I wonder if we should also name this name. But.... maybe not a big deal? If we did want to do it maybe easier in a separate follow up change? Thoughts.

package systems also talk about the full spec (including version, etc.) but we're not storing that and I don't think we should since it'll get out of date.

ajperel · 2026-08-08T02:16:13Z

@@ -0,0 +1,101 @@
+import { setGlobalOptions } from "firebase-functions";
+import {
+//   defineBoolean,


I have feedback on Victor's PR that maybe changes how we do this completely in which case this comment is not needed.

This is fine but I also was wondering if just to save people effort uncommenting if we should do something like

import * as params from "firebase-functions/params"

and then like params.defineString()

Only to save us this long list of maybe not used things?

ajperel · 2026-08-08T02:19:38Z

+  description: "Region where functions should be deployed.",
+});
+
+// To configure more https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions


I think we could make this a more user friendly comment if we keep it guide users a bit more.

something like

To require setting a global option for each instance of this kit uncomment the option parameter definition and the line configuring it below. Learn more about these options at: https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions

or if we go the process.env route a different but equally helpful comment.

gemini-code-assist Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread src/commands/functions-kits-install.ts Outdated

Comment thread src/commands/functions-kits-install.ts

Add kits:install command

e4b08d8

wandamora force-pushed the morawand-kits-install branch from 2aeea99 to e4b08d8 Compare August 7, 2026 00:11

Address GCA comments

2872d49

- throw error for failing to parse template - remove redundant ? for options.config.src, it shouldn't be undefined or null

wandamora force-pushed the morawand-kits-install branch from 073b681 to 2872d49 Compare August 7, 2026 17:09

wandamora added 3 commits August 7, 2026 17:53

Update source tree

2a56a12

package.json, tsconfig.json, and .gitignore should live in the root of the kit, and index.ts will be in /src.

Few more changes

9c53565

- Prompt for kit ID - Update npm shrinkwrap warning - change FIREBASE_FUNCTION_KIT_REGION param to FUNCTION_KIT_REGION

Update 3p test

b67c1c9

wandamora marked this pull request as ready for review August 7, 2026 18:55

wandamora requested review from ajperel and inlined August 7, 2026 18:55

Merge branch 'main' into morawand-kits-install

8aab5c4

ajperel reviewed Aug 8, 2026

View reviewed changes

Uh oh!

Conversation

wandamora commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Scenarios Tested

Sample Commands

Uh oh!

wiz-9635d3485b Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Wiz Scan Summary

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

ajperel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ajperel Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wandamora commented Aug 7, 2026 •

edited

Loading

wiz-9635d3485b Bot commented Aug 7, 2026 •

edited

Loading

ajperel Aug 8, 2026 •

edited

Loading