@invertase/example-firebase-kit-hello-world

A hello-world Firebase Functions kit: an npm package containing ready-made Cloud Functions that you add to your own functions codebase and deploy into your own project. There is no hosted version.

It exists to exercise tooling that installs, configures, and deploys kits, so it is deliberately trivial - one HTTP function and one callable, both returning a configurable greeting.

Install

npm install @invertase/example-firebase-kit-hello-world

Usage

Re-export the functions from your codebase entry point:

// functions/src/index.ts
import { setGlobalOptions } from "firebase-functions";

setGlobalOptions({ region: "us-central1" });

export * from "@invertase/example-firebase-kit-hello-world";

The re-export matters: the Firebase CLI discovers functions from the top-level exports of your codebase entry, so a bare import deploys nothing.

Configure with a .env (or .env.<projectId>), which the Firebase CLI loads at deploy time:

GREETING=Hello

Then:

firebase deploy --only functions

helloWorld responds with:

{ "message": "Hello, World!", "instanceId": "example-firebase-kit-hello-world" }

Configuration

| Param | Required | Default | Description | |---|---|---|---| | GREETING | no | Hello | Greeting word placed before , World! |

FIREBASE_KIT_INSTANCE_ID is not configured by you. If it is present in the environment the functions run in, its value is echoed back as instanceId; otherwise instanceId is null. It is returned purely so that per-instance environment injection is observable from a live response. To set it yourself when running locally:

FIREBASE_KIT_INSTANCE_ID=my-instance firebase emulators:start --only functions

Deliberate properties

This package is a test fixture, so several choices are load-bearing:

• No region is set on either function. A caller's setGlobalOptions({ region }) is therefore what takes effect. A kit that set a per-function region would silently override it.
• Params are read inside the handler, never at module load, so deploy-time discovery can load the module before param values exist.
• The main entry exports only the two functions. Helpers and types live behind the ./lib subpath, so export * from this package in a consumer codebase pulls in functions and nothing else.
• There are no install scripts. The build runs from prepack, so the package installs correctly under npm install --ignore-scripts.
• firebase-functions is a peer dependency, so the kit and the codebase that re-exports it always share one copy. Global options are module-scoped state; two copies would mean setGlobalOptions silently not applying.
• The published tarball contains lib/ and src/, so the compiled output has working source maps.

API surface

• Main entry (@invertase/example-firebase-kit-hello-world): helloWorld, helloWorldCallable. Defines triggers, so it only runs cleanly inside the Firebase toolchain (deploy discovery, runtime, or the emulator).
• Library entry (./lib): buildGreeting plus its types. No load-time side effects, safe to import anywhere.

Published variants

Each variant is a version of this same package, so tooling can be pointed at a specific one with @version.

| Version | Differs how | What it exercises | |---|---|---| | 0.1.0 | baseline, no npm-shrinkwrap.json | install of an unpinned third-party package | | 0.2.0 | ships a committed npm-shrinkwrap.json | install of a dependency-pinned package | | 0.3.0 | triggers written against firebase-functions/v1 | rejection of first-generation functions |

Only 0.1.0 exists so far. To cut 0.2.0:

npm install --package-lock-only && npm shrinkwrap

0.3.0 swaps src/index.ts for a firebase-functions/v1 trigger. Check that the firebase-functions major in dependencies still ships the /v1 subpath; if not, pin that version to the last major that does.

Development

npm install
npm run build
npm test

To try it without publishing, pack it and install the tarball into a scratch functions codebase:

npm pack
cd ../scratch-functions
npm install --ignore-scripts ../example-firebase-kits/invertase-example-firebase-kit-hello-world-0.1.0.tgz
firebase emulators:start --only functions

License

Apache-2.0