Using environment variables in Astro when deploying to Cloudflare

tags: astro, cloudflare, astro ssg, astro ssr, env variables

Overview

• Have multiple branches (dev, production, staging) each will have its own Cloudflare worker and its own environment variables.
• Integrate Cloudflare workers with each branch to trigger build and deploy on pushing to Github, and not run (npm run build && npx wrangler deploy) on your machine.
• No need for Github actions for build and deploy to Cloudflare.
• Use one Wrangler file to manage asset bindings, and other shared configurations for an Astro project to be integrated with Cloudflare.
• Define different buildtime and runtime environment variables for each branch on Cloudflare dashboard for convenience.

Demo Project

• Wrangler file
  • this file has "keep_vars": true (to avoid overwriting variables defined on Cloudflare dashboard)
    a recommended approach is to keep wrangler file as only source of truth
    but for our use case this is a good option.
  • also it is missing name field like: "name": "worker name" we will add this for each worker when setting up deploy command
    like npx wrangler delpoy --name dev-worker or npx wrangler delpoy --name prod-worker

  {
    "$schema": "node_modules/wrangler/config-schema.json",
    "main": "./dist/_worker.js/index.js",
    // Update to today's date
    "compatibility_date": "2025-03-25",
    "compatibility_flags": ["nodejs_compat"],
    "keep_vars": true,
    "assets": {
    "binding": "ASSETS",
    "directory": "./dist"
    },
    "observability": {
    "enabled": true
    }
  }

• .assetsignore (in public directory)
  • required by Cloudflare workers

  _worker.js
  _routes.json

• you need to ensure you have .env file dedfined at the root of the project

  SECRET_VAR_ONE=SECRET_VAR_ONE_VALUE

• add Cloudflare as adapter and set Astro output as ‘server’

// @ts-check
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

// some code ...

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: cloudflare()
  // some code ...
});

Accessing environment variables

• astro.config.mjs
• ssg pages
• ssr pages

For astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import { loadEnv } from "vite";

const { SECRET_VAR_ONE } = loadEnv(
  process.env.TEST_SECRET || "",
  process.cwd(),
  ""
);

console.log("SECRET_VAR_ONE in astro.config.mjs", SECRET_VAR_ONE);

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: cloudflare()

  // somde code ...
});

then we can use the environment variables in any needed actions such as:

• communicating with external APIs and load any needed global Astro configurations

For SSG pages we can use two methods

• we can use import.meta.env but we will see later how we can define a helper function
  that will rerutn environment variables in buildtime or runtime on Cloudflare
• using import { getSecret } from "astro:env/server";
  and for this we need to define schema in astro.config.mjs to have type safety
  and define scope of each environment variable if it is client or server
  in this demo we are only interested in server side environment variables
  
  here is the full code of astro.config.mjs

// @ts-check
import { defineConfig, envField } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import { loadEnv } from "vite";

const { SECRET_VAR_ONE } = loadEnv(
  process.env.TEST_SECRET || "",
  process.cwd(),
  ""
);

console.log("SECRET_VAR_ONE in astro.config.mjs", SECRET_VAR_ONE);

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: cloudflare(),
  env: {
    schema: {
      SECRET_VAR_ONE: envField.string({ context: "server", access: "secret" }),
    },
  },
});

For SSR Pages we can use two methods:

• for import.meta.env it will not work and will be undefined in runtime (ssr) when we deploy to Cloudflare
• we can use
  import { getSecret } from "astro:env/server";
const envGetSecret = getSecret("SECRET_VAR_ONE");
  you can find this used in both ssg-example and ssr-example pages in the demo repo
• another way to access the environment variables in Cloudflare utilizing how it uses the bindings deined in wrangler config file
  and you can access bindings from Astro.locals.runtime
  for more details visit Astro documentation click here
  
  so to access any environment variables during runtime like in your ssr pages and we better adopt this across your entire project
  even on ssg pages you can approach this in two different ways:
• develop a helper function that takes in Astro (Astro global object available in all contexts in .astro files)
• use getSecret function imported from “astro:env/server”

for getEnv() function:

export const getEnv = (ASTRO_GLOBAL:any) =>{
    const AstoEnv = ASTRO_GLOBAL?.locals?.runtime?.env;

    return {
        SITE_TITLE: AstoEnv?.SITE_TITLE || import.meta.env.SITE_TITLE,
    };
}

---
// some code

import { getEnv } from "@/helpers/getEnv";
const envHelper = getEnv(Astro).SECRET_VAR_ONE;

// some code
---
  <p>
    Build time environment variable (using getEnv helper this is the same as
    Astro.locals but moved to a helper function)<br />
    env variable: {envHelper || "not found"}
  </p>

for astro:env/server:

---
// some code
import { getSecret } from "astro:env/server";

const envGetSecret = getSecret("SECRET_VAR_ONE");
// some code
---
  <p>
    Build time environment variable (using getSecret from astro:env/server)<br />
    env variable: {envGetSecret}
  </p>

Some points regarding Cloudflare setup:

• you need to have a worker project create you can use default Astro template and link your repo afterwards
• connect your github repo under settings and choose which branch to connect to
• define your build environment variables
• for build command npm run build
• for deploy command npx wrangler deploy --name {{same name of your worker}}
  
  

  Here is group of screenshots starting a project and connecting to Github

  In case of any failed deployment make sure you have:
• wrangler file
• .assetsignore
• build environment variables defined under Settings>Build
• runtime environment variables defined under Settings>Variables and Secrets
• build command and deploy command setup properly
  
  
  
  
  
  
  
  
  after that you can go to latest failed build and retry deployment
  then in the future pushes all should be working as intended
  
  

  References used

  @astrojs/cloudflare
  Deploy your Astro Site to Cloudflare
  Using environment variables