Environment Variables with AstroJS and Cloudflare

Understanding Environment Variables in AstroJS

With Astro 5 environment variables got a huge upgrade in developer experience and safety. Until recently, AstroJS developers using Cloudflare had to use the legacy environment variable handling system. The good news is that Astro’s new environment variable configuration system now works seamlessly with the Cloudflare adapter!

You can always check out the AstroJS docs for the latest information, but this guide focuses specifically on the Cloudflare integration details you need to know.

Legacy Environment Variable Handling: The Old Way

Let’s quickly review the previous method of handling environment variables with Cloudflare. This context will help you understand why the new approach is such a significant improvement.

With the legacy approach, you had to manually define your environment variables and inject them into the build process:

1
import { defineConfig } from 'astro/config';
2
import cloudflare from '@astrojs/cloudflare';
3

4
const envVars = ['PUBLIC_VARIABLE_1', 'PUBLIC_VARIABLE_2', 'PRIVATE_VARIABLE_3'] as const;
5

6
export default defineConfig({
7
  site: 'https://example.com',
8
  output: 'static',
9
  trailingSlash: 'ignore',
10
  integrations: [],
11
  adapter: cloudflare(),
12
  vite: {
13
    ssr: {
14
      target: 'webworker',
15
    },
16
    define: envVars.reduce((acc, key) => {
17
      acc[`process.env.${key}`] = JSON.stringify(process.env[key]);
18
      return acc;
19
    }, {}),
20
  },
21
});

You also needed to manually define the types for your environment variables:

1
type Variables = 'PUBLIC_VARIABLE_1' | 'PUBLIC_VARIABLE_2' | 'PRIVATE_VARIABLE_3';
2

3
interface ImportMetaEnv extends Record<Variables, string> {}
4

5
interface ImportMeta {
6
  readonly env: ImportMetaEnv;
7
}

Then you could access your variables like this:

1
import.meta.env.PUBLIC_VARIABLE_1;

This approach had several significant drawbacks:

1. No security boundary: Private variables could accidentally be exposed to the client
2. No validation: Missing environment variables wouldn’t cause errors until runtime
3. Limited type safety: TypeScript couldn’t verify the correct usage of variables
4. No default values: You couldn’t specify fallbacks for optional variables
5. Manual maintenance: You had to update multiple files when adding new variables

Modern Environment Variable System: Type-Safe and Secure

Astro’s new environment variable system addresses all these limitations with an elegant, type-safe solution that now works perfectly with Cloudflare. Let’s explore the benefits and implementation details.

Key Benefits of the New Environment Variable System

• Runtime validation: Errors if required variables are missing

• Enhanced type safety: Full TypeScript integration with proper types

• Intelligent IntelliSense: Autocomplete in your IDE for available variables

• Security boundaries: Private variables cannot be exposed to the client

• Default values: Specify fallbacks for optional variables

• Centralized configuration: Define everything in one place

How to Implement the New Environment Variable System

1
import { defineConfig, envField } from 'astro/config';
2
import cloudflare from '@astrojs/cloudflare';
3

4
// https://astro.build/config
5
export default defineConfig({
6
  site: 'https://example.com',
7
  output: 'static',
8
  trailingSlash: 'ignore',
9
  integrations: [],
10
  adapter: cloudflare(),
11
  env: {
12
    schema: {
13
      // Public variable accessible anywhere
14
      PUBLIC_VARIABLE_1: envField.string({
15
        context: 'client',
16
        access: 'public',
17
        default: 'default value',
18
      }),
19
      // Public variable accessible on the server
20
      PUBLIC_VARIABLE_2: envField.boolean({
21
        context: 'server',
22
        access: 'public',
23
        default: false,
24
      }),
25
      // Private variable accessible on the server
26
      PRIVATE_VARIABLE_3: envField.number({
27
        context: 'server',
28
        access: 'secret',
29
      }),
30
    },
31
  },
32
  vite: {
33
    ssr: {
34
      target: 'webworker',
35
    },
36
  },
37
});

Notice how each variable is defined with:

1. Type information (string, boolean, number)
2. Context (client or server)
3. Access level (public or secret)
4. Optional default values

This configuration automatically generates the appropriate TypeScript types and enforces security boundaries between client and server code.

How to Access Environment Variables in Your Code

1
// Server-side code
2
import { PUBLIC_VARIABLE_2, PRIVATE_VARIABLE_3 } from 'astro:env/server';
3

4
// Client-side code
5
import { PUBLIC_VARIABLE_1 } from 'astro:env/client';

This import pattern creates a clear separation between client and server variables, preventing accidental exposure of sensitive information. The TypeScript compiler will even throw errors if you try to import server variables in client code!

Setting Up Cloudflare for AstroJS Environment Variables

For the new environment variable system to work correctly with Cloudflare, you need to update your Cloudflare Pages settings. You have two options:

1. Set the compatibility date to April 1, 2025, or later
2. Enable the compatibility flag specifically for this feature

Here’s how to access these settings in your Cloudflare dashboard:

Option 1: Updating Your Compatibility Date

If you’re starting a new project or can safely update your compatibility date:

Option 2: Enabling the Specific Compatibility Flag

If you need to maintain an earlier compatibility date for other features:

Environment Variable Best Practices for AstroJS and Cloudflare

• Use descriptive variable names that indicate their purpose

• Set appropriate access levels (public vs. secret) for each variable

• Provide default values for non-critical configuration

• Group related variables together in your schema

• Document expected formats in comments for team members

By following these practices, you’ll create a more maintainable, secure, and developer-friendly configuration for your AstroJS projects on Cloudflare Pages.

The new environment variable system represents a significant improvement in how we manage configuration in AstroJS projects. With proper Cloudflare integration, you can now enjoy all these benefits while deploying to one of the fastest and most reliable edge networks available.