GCP Secret Manager

Resolve environment variables from Google Cloud Secret Manager.

Installation

Install the GCP SDK peer dependency:

npm install @google-cloud/secret-manager

pnpm add @google-cloud/secret-manager

bun add @google-cloud/secret-manager

yarn add @google-cloud/secret-manager

Basic usage

import { createEnv, requiredString } from "@ayronforge/better-env"
import { fromGcpSecrets } from "@ayronforge/better-env/gcp"
import { Effect } from "effect"

const envEffect = createEnv({
  server: {
    DATABASE_URL: requiredString,
    API_KEY: requiredString,
  },
  resolvers: [
    fromGcpSecrets({
      secrets: {
        DATABASE_URL: "database-url",
        API_KEY: "api-key",
      },
      projectId: "my-gcp-project",
    }),
  ],
})

const env = await Effect.runPromise(envEffect)

Options

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Map of env var names to GCP secret names (or full resource paths).
projectId	string	—	GCP project ID. Required when using short secret names.
version	string	"latest"	Secret version to access.

Full resource names

You can use either short secret names or full GCP resource paths:

fromGcpSecrets({
  secrets: {
    // Short name — requires projectId
    DATABASE_URL: "database-url",

    // Full resource path — projectId not needed
    API_KEY: "projects/my-project/secrets/api-key/versions/latest",
  },
  projectId: "my-gcp-project",
})

Short names are expanded to: projects/{projectId}/secrets/{name}/versions/{version}

Custom version

Access a specific version of a secret instead of latest:

fromGcpSecrets({
  secrets: { API_KEY: "api-key" },
  projectId: "my-project",
  version: "3",  // Access version 3 specifically
})