Skip to content
Nimbus

Run Cloud Functions workloads on Nimbus

Run your existing firebase-functions/v2 handlers and @google-cloud/functions-framework targets on Nimbus without source rewrites. Firestore document triggers get at-least-once delivery with durable retry, and HTTP/callable handlers serve directly from the Nimbus server.

functions/src/index.ts
import { onRequest } from "firebase-functions/v2/https";
import { onDocumentCreated } from "firebase-functions/v2/firestore";


export const hello = onRequest(async (req, res) => {
  res.json({ message: "Hello from Nimbus Cloud Functions!" });
});


export const onMessageCreated = onDocumentCreated(
  "messages/{messageId}",
  async (event) => {
    console.log("New message:", event.data?.data());
  },
);

Before you start

Section titled “Before you start”
  • Install Nimbus — see the developer quickstart for install options.
  • Install Node.js 22 with npm. Cloud Functions code generation runs through the external Node toolchain.
  • The firebase-functions and firebase-admin packages are your own dependencies, installed from the npm registry (or a preinstalled node_modules).

Start a new project

Section titled “Start a new project”
Terminal window
nimbus init cloud-functions my-functions-app
cd my-functions-app
nimbus dev

nimbus init cloud-functions scaffolds a conventional Firebase layout: firebase.json, plus a functions/ package with package.json, tsconfig.json, and a src/index.ts containing an onRequest handler and an onDocumentCreated trigger. nimbus dev finds the app root, runs codegen, and serves the local deployment, re-running codegen as you edit.

Bring an existing Firebase project

Section titled “Bring an existing Firebase project”

Keep your functions source unchanged, then generate artifacts and start the server from the project root:

Terminal window
nimbus codegen
nimbus start --app-dir .

nimbus start does no source-tree discovery — pass --app-dir explicitly. (nimbus dev does walk up from the current directory, bounded by the nearest .git.)

Test an HTTP handler — Firebase onRequest exports serve at /<exportName> on the main server port (default 8080):

Terminal window
curl http://localhost:8080/hello

What you get

Section titled “What you get”

Firestore document triggers run with:

  • at-least-once delivery backed by a durable invocation ledger
  • crash/restart replay for pending and due-retry invocations
  • bounded retry for retryable failures
  • service-principal execution (not the calling end-user principal)
  • chain-depth limiting so recursive write-back triggers stop at a configured depth instead of looping forever
  • no-op suppression — overwrites that change nothing do not emit update events

Write handlers to be idempotent: redelivery is possible by design.

Generated artifacts

Section titled “Generated artifacts”

nimbus codegen writes Cloud Functions outputs under .nimbus/firebase/:

.nimbus/firebase/
  artifact.json
  targets.json
  bundle.mjs
  bundle.sha256

Standalone Functions Framework packages must author .nimbus/firebase/targets.json themselves, because functions.http(...) and functions.cloudEvent(...) name targets without carrying binding metadata in source — see Migrate Cloud Functions for the file format.

Deploy

Section titled “Deploy”
Terminal window
nimbus deploy --url <server-url> --token <deploy-token>

--url and --token can also come from the NIMBUS_DEPLOY_URL and NIMBUS_DEPLOY_TOKEN environment variables.

Where next

Section titled “Where next”