Environment variables and serverless functions

For the complete documentation index, see llms.txt

Netlify environment variables are accessible when you run Netlify Functions, including scheduled functions and background functions. This allows you to:

Provide configuration for your project. You can set different values depending on the deploy context.
Securely provide sensitive values for your serverless functions, such as API keys and tokens.
Get information about the current project, such as the site URL.
Access the API keys needed for calling common AI providers, which are automatically set for you.

Declare variables

You can declare and set environment variables using the Netlify UI, CLI, or API for use with serverless functions.

On the Pro plan and above, you can set specific scopes for your environment variables. For an environment variable to be available to serverless functions during runtime, its scope must include Functions.

Note that environment variables declared in a Netlify configuration file (netlify.toml) are not available to serverless functions.

Netlify read-only variables

Netlify offers a number of read-only environment variables during the build step, but only the following variables are available to serverless functions during runtime:

URL: the URL representing the main address for your site. It can be either a Netlify subdomain or your own custom domain if you set one; for example, https://petsof.netlify.app or https://www.petsofnetlify.com.
SITE_NAME: the name of the site, which is also its Netlify subdomain. For example, petsof.
SITE_ID: the unique ID for the site. For example, 1d01c0c0-4554-4747-93b8-34ce3448ab95.

Note that read-only environment variables are reserved in Netlify's system. You can't set or override these values manually.

AI Gateway environment variables

In credit-based plans, the environment variables necessary to use common AI model providers are automatically set without any further configuration, unless you want to provide your own API keys.

This means that common client libraries for calling AI models are usable without setting any keys. You can also access the relevant environment variables for using the keys with REST APIs.

Overrides and limitations

The general environment variable overrides and limitations apply to environment variables used with serverless functions. Here are some additional limitations to note:

Environment variables declared in a Netlify configuration file (netlify.toml) are not available to serverless functions.
Environment variables are applied based on the values set at the time of deployment. Each deploy, including Deploy Previews and branch deploys, uses the environment variable values that were set at the time of deployment. To apply updated environment variable values, create a new deploy.
If you're using Lambda compatibility mode, AWS's environment property limits apply: the total size of all environment variables cannot exceed 4 KB. If you have the option to set specific scopes for your environment variables, you can adjust the scope of your variables to avoid hitting this limit. Alternatively, consider upgrading from Lambda compatibility mode, which removes this limitation.
AWS's reserved environment variables are available for read-only access.
You can set a Node.js runtime version for serverless functions that is different from the version used at build time.

Access environment variables

Once you declare environment variables that are available to all scopes or the Functions scope, you can access them in your serverless functions using the format process.env.VARIABLE_NAME.

TypeScript
JavaScript

import type { Config, Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  const value = process.env.MY_IMPORTANT_VARIABLE

  return Response.json({ message: `Value of MY_IMPORTANT_VARIABLE is ${value}.` })
}

export const config: Config = {
  path: "/example",
}

export default async (req, context) => {
  const value = process.env.MY_IMPORTANT_VARIABLE

  return Response.json({ message: `Value of MY_IMPORTANT_VARIABLE is ${value}.` })
}

export const config = {
  path: "/example",
}

More resources

Did you find this doc useful?

Your feedback helps us improve our docs.