Configuring Environment Variables in Cloudflare Pages

This guide explains how to configure environment variables in Cloudflare Pages Dashboard for astro-minimax. Proper environment variable configuration is essential for AI chat, notification systems, and build processes to function correctly.

Overview

Why Environment Variables Matter

Environment variables in astro-minimax serve three primary purposes:

Build-time vs Runtime Variables

Understanding when variables are accessed is crucial:

Build-time Variables are used during the build process. Changes require a new deployment to take effect.

Runtime Variables are accessed when the application runs. Changes take effect on the next request without redeployment.

Accessing Environment Variables

Navigate to the Cloudflare Pages environment variables settings:

Cloudflare Dashboard → Workers & Pages → [your-project] → Settings → Environment variables

Environment Scopes

Cloudflare Pages provides two environment scopes:

Required Variables

These variables are essential for astro-minimax to function properly.

Build Configuration

AI Configuration

Optional Variables

Configure these based on your feature requirements.

Notification Variables

Telegram Notifications

See the Notification Guide for setup instructions.

Email Notifications (Resend)

AI Provider Variables

For custom AI providers (not Cloudflare Workers AI):

See the AI Guide for detailed configuration.

Site Configuration

Step-by-Step: Adding Variables

Follow these steps to add environment variables in Cloudflare Pages Dashboard.

Step 1: Open Your Project

1. Log in to Cloudflare Dashboard
2. Click Workers & Pages in the left sidebar
3. Select your astro-minimax project from the list

Step 2: Navigate to Settings

1. Click the Settings tab in the project navigation
2. Scroll down to find Environment variables
3. Click Environment variables to open the configuration panel

Step 3: Add Variables

For each variable you need to configure:

1. Click Add variable button
2. Enter the variable name (e.g., NODE_VERSION)
3. Enter the value (e.g., 22)
4. Select the environment scope:
   • Production for live deployments
   • Preview for branch previews
   • Or select both if the value is the same
5. Click Save

Step 4: Configure Encryption (Recommended)

For sensitive values like API keys:

1. After adding the variable, locate it in the list
2. Click the Encrypt option if available
3. This prevents the value from being visible in the dashboard

Step 5: Deploy Changes

Build-time variables require a new deployment:

1. Go to the Deployments tab
2. Click Retry deployment on the latest deployment
3. Or push a new commit to trigger automatic deployment

Runtime variables take effect immediately without redeployment.

AI Binding Configuration

The AI chat feature uses Cloudflare Workers AI, which requires proper binding configuration.

wrangler.toml Configuration

Your project should have a wrangler.toml file in apps/blog/:

name = "astro-minimax"
pages_build_output_dir = "dist"
compatibility_date = "2026-03-12"
compatibility_flags = ["nodejs_compat"]

[ai]
binding = "minimaxAI"

[[kv_namespaces]]
binding = "CACHE_KV"
id = "your-kv-namespace-id"

Matching Environment Variable

The AI_BINDING_NAME environment variable must match the [ai].binding value:

How It Works

1. Cloudflare Pages reads wrangler.toml during deployment
2. The [ai].binding creates a Workers AI binding
3. Your code accesses AI via the binding name
4. The environment variable tells astro-minimax which binding to use

KV Namespace Configuration

KV Namespace is optional and used for caching AI responses.

When to Configure KV

Adding KV Namespace

1. In Cloudflare Dashboard, go to Workers & Pages → KV
2. Create a new namespace or use an existing one
3. Copy the namespace ID
4. Update your wrangler.toml:

[[kv_namespaces]]
binding = "CACHE_KV"
id = "your-kv-namespace-id"

5. Redeploy your project

Security Best Practices

Secrets Management

Variable Scope Recommendations

Access Control

In Cloudflare Dashboard:

Your Project → Settings → Access policies

Configure who can:

• View environment variables
• Modify environment variables
• Deploy to production

Troubleshooting

Build Fails: Node Version Issues

Symptom: Build fails with Node.js compatibility errors.

Solution:

1. Verify NODE_VERSION=22 is set in environment variables
2. Check that the variable is set for Production environment
3. Redeploy after adding or changing the variable

AI Chat Not Working

Symptom: AI chat returns errors or no response.

Solutions:

Notifications Not Sending

Symptom: No notifications received for comments or AI chat.

Solutions:

Variables Not Taking Effect

Symptom: Changes to environment variables don’t change behavior.

Solutions:

1. Build-time variables: Trigger a new deployment
2. Runtime variables: Wait a few seconds for propagation
3. Cache: Clear Cloudflare cache if applicable
4. Variable name: Check for typos in variable names

Preview vs Production Differences

Symptom: Features work in preview but not production (or vice versa).

Solution:

1. Open environment variables settings
2. Check which scope each variable is assigned to
3. Ensure critical variables are set for both Production and Preview

Next Steps

After configuring environment variables:

1. Test AI Chat: Visit your deployed site and test the AI chat feature. See AI Guide for detailed testing.

2. Test Notifications: Trigger a test comment or AI conversation to verify notifications. See Notification Guide for troubleshooting.

3. Monitor Deployment: Check deployment logs in Cloudflare Dashboard for any build errors.

4. Configure Custom Domain: Add your custom domain in Cloudflare Pages settings. See Deployment Guide for instructions.

5. Set Up Analytics: Configure Umami analytics for visitor tracking.

Related Documentation

• Deployment Guide — Complete deployment instructions
• AI Guide — AI chat configuration details
• Notification Guide — Notification system setup
• Feature Overview — All available features