skip to content

In Cloud Functions for Firebase, how do parameters from firebase-functions/params and secrets from defineSecret get their values, and what breaks when they are misused?

level: middleimportance: should knowfreq 38%

answer

  1. typed values checked at deploy
  2. .env.<projectId> and the CLI prompt
  3. options take the param, handlers call value()
  4. secrets bound per function
  5. functions.config() and v7

basics

~20 s

Parameters such as defineString and defineInt are typed values the CLI resolves at deploy time from .env files, defaults or a prompt. Secrets from defineSecret live in Cloud Secret Manager and reach only functions that list them in secrets.

solid answer

~40 s

The CLI loads `.env` and `.env.<project>` files, prompts for any parameter without a value or `default`, saves the answer to `.env.<projectId>` and refuses to deploy until every parameter is valid. In trigger options you pass the parameter object itself (`{ maxInstances: maxParam }`); inside the handler you call `.value()`. Calling `.value()` in global scope is the classic mistake, because the code is inspected at deploy time; use `onInit()` for initialisation. Secrets are created with `firebase functions:secrets:set`, bound with `secrets: [apiKey]`, and read with `apiKey.value()`; an unbound function gets an empty string, and a rotated secret needs a redeploy of the functions that bind it. In firebase-functions v7 the old `functions.config()` is removed and throws, so legacy config must move to params or secrets.

code

typescript · 27 lines
typescript
import { onDocumentCreated } from "firebase-functions/firestore";
import { defineInt, defineSecret, defineString } from "firebase-functions/params";
import { sendMail } from "./mail";

const mailApiKey = defineSecret("MAIL_API_KEY");
const senderAddress = defineString("SENDER_ADDRESS");
const confirmationMaxInstances = defineInt("CONFIRMATION_MAX_INSTANCES", { default: 10 });

export const sendConfirmation = onDocumentCreated(
  {
    document: "orders/{orderId}",
    secrets: [mailApiKey],                   // only bound functions receive the value
    maxInstances: confirmationMaxInstances,  // the param itself, resolved at deploy time
  },
  async (event) => {
    const order = event.data?.data();
    if (!order) {
      return;
    }
    await sendMail({
      apiKey: mailApiKey.value(),            // .value() only at run time
      from: senderAddress.value(),
      to: order.email,
      orderId: event.params.orderId,
    });
  },
);

go deeper

for a junior

Recall that defineString-style parameters come from .env files or a prompt, and that secrets need firebase functions:secrets:set plus a secrets entry on the function.

for a middle

Explain why options take the parameter object while handlers call value(), and what onInit() is for.

for a senior

Show you can diagnose an empty secret, a deploy that fails in global scope, and a rotated key that never arrived, and that you migrate functions.config() before v7 breaks it.

for a principal

Decide the configuration policy: which values are committed per-project .env files, which are secrets bound to the fewest functions, and who may rotate them.

## Three kinds of configuration Cloud Functions for Firebase reads configuration from three places, and each behaves differently at deploy time and at run time: | Mechanism | Defined with | Value comes from | Known at deploy time | |---|---|---|---| | Parameters | `defineString`, `defineInt`, `defineFloat`, `defineBoolean`, `defineList` | `.env` files, a `default`, or a CLI prompt | yes | | Secrets | `defineSecret`, `defineJsonSecret` | Cloud Secret Manager | no | | Plain environment variables | keys in a `.env` file, read with `process.env` | the same `.env` files | no | Parameters are the recommended path: they are typed, validated, and the CLI **blocks the deploy** until every parameter has a valid value. ## How a parameter gets its value 1. On `firebase deploy`, the CLI loads `.env` and a project-specific `.env.<project or alias>` file from the `functions/` directory. 2. A parameter still without a value and without a `default` is **prompted for**, and the answer is saved to `.env.<projectId>`, a file the team may commit. 3. The resolved values become part of the deployed function's environment. Options such as `input: select([...])` or a `validationRegex` shape the prompt. The built-in parameters `projectID`, `databaseURL` and `storageBucket` are never prompted for. ## Deploy time versus run time The CLI loads and inspects the function source during deployment, before parameters have runtime values. That splits usage in two: - **In trigger options, pass the parameter object itself**, as in `{ maxInstances: confirmationMaxInstances }`, and the CLI resolves it at deploy time. Choose between values with comparators such as `environment.equals("prod").thenElse(10, 0)`, not with an `if`. - **Inside the handler, call `.value()`**. - **Not in global scope.** The docs warn that reading a value there fails deployment. In the 7.4.0 source a secret's `value()` throws during deployment, and other parameters log a warning and return a value that is not resolved yet. Initialisation that needs a value goes in `onInit()`, which runs before the first invocation in production but not during deploy. ## Secrets - Create or rotate one with `firebase functions:secrets:set MAIL_API_KEY`. - **Bind** it per function with `secrets: [mailApiKey]`. Only bound functions receive it: in an unbound function `mailApiKey.value()` returns an empty string and logs a warning, and `process.env.MAIL_API_KEY` is `undefined`. - After setting a new value, **redeploy** every function that binds the secret; that is how they pick up the latest version. - `defineJsonSecret` keeps related values in one JSON secret; `.value()` parses it and throws when the stored value is not valid JSON. - Deleting a secret that a deployed function still references makes that function fail silently. `functions:secrets:prune` removes only secrets that no function references. - Instances read their bound secrets each time they cold start, and Secret Manager bills access operations above a monthly allowance, so many instances binding many secrets has a cost. Never put credentials in `.env` files: they are plain configuration, often committed, and not a secure store. ## Choosing the right mechanism - **A parameter** for anything that shapes the deployment or differs per project: instance counts, a region, a feature switch, a sender address. - **A secret** for anything that grants access: API keys, webhook signing secrets, database passwords. Bind it to the fewest functions that need it. - **A plain `.env` variable** only for values that are neither sensitive nor worth validating, since nothing checks them at deploy time. - **Built-in parameters** instead of hard-coded project IDs or bucket names, so the same code deploys to staging and production. ## Local development The Functions emulator layers `.env.local` over `.env` and the project file, and a `.secret.local` file overrides secret values. Without it the emulator tries to read real secrets with application default credentials, which fails in CI that lacks permission. ## The removed API Older projects read configuration with `functions.config()`. It was deprecated in firebase-functions 6.0.0 and is **removed in v7**: in 7.4.0, calling it throws an error that points to the migration guide. `firebase functions:config:export` copies the old values into a Secret Manager secret, which the code then reads with `defineJsonSecret` after binding it in `secrets`. In the order app, the mail provider key is a secret bound only to the confirmation function, the sender address and instance cap are parameters, and the coupon callable never sees the mail key at all.

  • You rotated MAIL_API_KEY with functions:secrets:set, but the function still sends with the old key. Why?
    A deployed function keeps the secret version it was deployed with. Firebase's rule is to redeploy every function that references the secret after setting a new value; until then the old key stays in use. When you do deploy with the new version, the CLI by default tries to destroy secret versions that no function uses any more.
  • Your function creates an API client at module load with apiKey.value() and deploys fail. What is the fix?
    At deploy time the CLI loads the code before values exist, and a secret's `value()` throws there. Move the client creation into an `onInit()` callback, which runs before the first invocation in production but not during deployment, or create the client lazily inside the handler and cache it in a module variable.

  • Every function in the codebase can read every secret in the project.
  • Calling param.value() in trigger options is the right way to set minInstances.
  • A rotated secret reaches running functions without a redeploy.
  • Storing an API key in .env is as safe as Secret Manager.
  • functions.config() still works in firebase-functions v7.

Assumes firebase-functions 7.4.0 (Firebase as of 2026-10-09): functions.config() was deprecated in 6.0.0 and is removed in v7, where calling it throws.