Add environment variables to functions

Learn to add environment variables to your functions.

Environment variables let you keep secrets, like tokens or API keys, hidden and out of version control. Sanity Functions lets you manage environment variables from the CLI so they're available to your deployed functions.

In this guide, you'll learn to add environment variables and access them from within your function code.

Prerequisites:

• Complete the Functions quick start, or be comfortable creating and deploying a function.
• Use the latest version of the sanity CLI (sanity@latest) to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with npx sanity@latest.

If you don't already have a blueprint and function set up, create them now.

Initialize a blueprint:

npx sanity@latest blueprints init

pnpm dlx sanity@latest blueprints init

yarn dlx sanity@latest blueprints init

bunx sanity@latest blueprints init

Add a function:

npx sanity@latest functions add

pnpm dlx sanity@latest functions add

yarn dlx sanity@latest functions add

bunx sanity@latest functions add

In this example, set the function to trigger on Document Create and Document Update, use TypeScript, and set the name to envExample.

✔ Enter function name: envExample
✔ Choose events to trigger your function: Document Create, Document Update
✔ Choose function language: TypeScript
✔ Add @sanity/functions helpers to the new Function? yes
✔ How to install the @sanity/functions helpers: npm

This creates a function in the functions/envExample directory.

Variables added with functions env add aren't available locally, but you can simulate them by prefixing your CLI command with the variable and value.

Start by updating the function to display the variable. This example uses a variable called SANITY_SECRET_SAUCE.

import { documentEventHandler } from '@sanity/functions'

export const handler = documentEventHandler(async ({ context, event }) => {
  console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
})

export async function handler({context, event}) {
  console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
}

All environment variables are accessible on process.env.

To test the function's access to a variable, prefix the CLI command with it.

SANITY_SECRET_SAUCE="content operating system" npx sanity@latest functions test envExample

If everything worked, you'll see this output:

Logs:
The secret: content operating system

Now that it works locally, make the same variable available to your deployed function.

Before you can add environment variables, you need to deploy the blueprint.

npx sanity@latest blueprints deploy

pnpm dlx sanity@latest blueprints deploy

yarn dlx sanity@latest blueprints deploy

bunx sanity@latest blueprints deploy

With the blueprint deployed, you can add environment variables to the function.

Add them with the sanity functions env add FUNCTION_NAME VARIABLE_NAME VARIABLE_VALUE command.

npx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

pnpm dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

yarn dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

bunx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

Create or update a document to trigger the function, then check the function's logs. The output matches the one from the local test.

npx sanity@latest functions logs envExample

pnpm dlx sanity@latest functions logs envExample

yarn dlx sanity@latest functions logs envExample

bunx sanity@latest functions logs envExample

You've now deployed and accessed an environment variable from a function.

When you're done with this function and blueprint, destroy the blueprint to prevent unexpected billing:

npx sanity@latest blueprints destroy

pnpm dlx sanity@latest blueprints destroy

yarn dlx sanity@latest blueprints destroy

bunx sanity@latest blueprints destroy

Environment variables are linked to individual functions. In addition to add, you can use the following commands to interact with them:

• sanity functions env list FUNCTION_NAME: List the environment variable keys set on the given function. Values are never displayed.
• sanity functions env remove FUNCTION_NAME VARIABLE_NAME: Remove the variable from the deployed function.

For additional usage information, add --help after each CLI command. You can read more about the CLI in the Functions CLI reference.

sanity functions env add writes to the Sanity’s Functions service, not to your local blueprint. The function has to exist in a deployed stack first, so running it before sanity blueprints deploy fails. The command doesn't warn and continue; it stops. env list and env remove behave the same way.

Which message you get depends on how far the CLI gets:

• Missing Stack: provide --stack, or set a Stack in your Blueprint config (`sanity blueprints config --edit`).: No stack is configured yet.
• Missing Stack deployment: A stack ID is set, but no deployment exists to load.
• Unable to find deployed function: "FUNCTION_NAME": The stack is deployed, and the function is declared locally but isn't in the deployment yet.
• Unable to find function: "FUNCTION_NAME": The name doesn't match any function in the stack.

None of these messages tells you to deploy. They point you at sanity blueprints doctor, which reports the configuration problem but not the ordering mistake behind it. Run sanity blueprints deploy first, then add the variable. Adding a variable doesn't redeploy the stack, and the new value takes effect on the next function invocation.

Run the command from the blueprint directory or a subdirectory. The manifest is required even though the command only touches remote state. Without it you get Could not find a Blueprint manifest (sanity.blueprint.ts, .js, or .json). If the API rejects the change after the function resolves, the CLI reports Failed to update VARIABLE_NAME with the reason from the Functions API.