# How Cloudflare Workers Environment Variables Are Configured in the y-gui Backend

> Discover how y-gui backend configures Cloudflare Workers environment variables using wrangler.toml, TypeScript, .dev.vars, and Env object for seamless deployment.

- Repository: [luohy15/y-gui](https://github.com/luohy15/y-gui)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The y-gui backend configures Cloudflare Workers environment variables through [`wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/wrangler.toml) manifest declarations, auto-generated TypeScript interfaces, local `.dev.vars` files, and strict runtime access via the `Env` object.**

The y-gui project deploys its backend as a Cloudflare Workers service, requiring a robust system for managing API keys, storage bindings, and service URLs. **Cloudflare Workers environment variables** are configured through a declarative manifest system—implemented in `luohy15/y-gui`—that binds KV stores, R2 buckets, D1 databases, and secrets to the runtime. This architecture ensures type-safe access to configuration across both local development and production deployments.

## Declaring Bindings in wrangler.toml

According to the `luohy15/y-gui` source code, all environment resources are registered in [`backend/wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/backend/wrangler.toml). This manifest tells Cloudflare which external services and variables the worker can access at runtime.

The configuration includes **KV namespaces**, **R2 buckets**, **D1 databases**, and custom string variables under the `[vars]` section:

```toml

# backend/wrangler.toml (excerpt)

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

[[r2_buckets]]
binding = "STORAGE_BUCKET"
bucket_name = "your-bucket-name"

[vars]
OPENROUTER_BASE_URL = "https://openrouter.ai/api"

```

When deployed, Cloudflare injects these bindings into the worker's `Env` object. Secrets stored via the Cloudflare Dashboard are also available through the same interface but remain encrypted and are not listed in the manifest's `[vars]` section.

## Type Safety with worker-configuration.d.ts

To prevent runtime errors and provide IntelliSense, y-gui uses **automatic TypeScript generation** via the `npm run cf-typegen` command. This process reads [`wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/wrangler.toml) and emits [`backend/src/worker-configuration.d.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/worker-configuration.d.ts), which exports the strictly typed `Env` interface:

```typescript
// backend/src/worker-configuration.d.ts (auto-generated)
interface Env {
  USER_KV: KVNamespace;
  STORAGE_BUCKET: R2Bucket;
  OPENROUTER_BASE_URL: string;
  OPENROUTER_FREE_KEY: string;
}

```

Every worker handler receives this `Env` object as a parameter, enabling compile-time verification of all environment access. The generated interface ensures that referencing undefined variables triggers TypeScript errors rather than runtime failures.

## Local Development with .dev.vars

For local testing, y-gui provides `backend/.dev.vars.example` as a template for environment values. Developers copy this file to `.dev.vars` and populate it with local secrets:

```bash

# backend/.dev.vars

OPENROUTER_FREE_KEY=sk-local-test-key
MCP_SERVER_URL=http://localhost:3000

```

When running `wrangler dev`, the CLI automatically loads these values into the worker's environment using the same `Env` interface. This eliminates code changes between local and production contexts, as both environments populate identical TypeScript types.

## Runtime Access Patterns in Source Code

The y-gui codebase accesses **Cloudflare Workers environment variables** exclusively through the typed `Env` object passed to handler functions. This pattern appears consistently across utility modules.

### Accessing API Keys and URLs

In [`backend/src/utils/token-refresh.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/utils/token-refresh.ts), the worker constructs API requests using environment variables for the base URL and authentication token:

```typescript
// backend/src/utils/token-refresh.ts
export async function refreshToken(env: Env) {
  const response = await fetch(`${env.OPENROUTER_BASE_URL}/auth/refresh`, {
    method: 'POST',
    headers: { 
      Authorization: `Bearer ${env.OPENROUTER_FREE_KEY}` 
    },
  });
  // Token refresh logic...
}

```

The TypeScript compiler verifies that `OPENROUTER_BASE_URL` and `OPENROUTER_FREE_KEY` exist as string properties on the `Env` interface, preventing undefined variable errors before deployment.

### Querying KV Namespaces

For storage operations, [`backend/src/utils/auth.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/utils/auth.ts) demonstrates how to access the bound KV namespace:

```typescript
// backend/src/utils/auth.ts
if (env?.USER_KV && sub) {
  const cached = await env.USER_KV.get(`user:${sub}`);
  // Authentication logic...
}

```

Here, `USER_KV` is typed as `KVNamespace`, providing full IntelliSense for Cloudflare's KV storage methods including `get()`, `put()`, and `delete()`.

## Summary

- **Configuration Declaration**: All bindings are declared in [`backend/wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/backend/wrangler.toml) using Cloudflare's standard syntax for KV, R2, D1, and custom variables.
- **Type Generation**: Running `npm run cf-typegen` creates [`backend/src/worker-configuration.d.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/worker-configuration.d.ts), which defines the strict `Env` interface used throughout the codebase.
- **Local Development**: The `backend/.dev.vars` file (copied from `.dev.vars.example`) supplies local values when running `wrangler dev`.
- **Runtime Access**: Code references environment variables exclusively through the typed `env` parameter, ensuring compile-time safety for API keys, storage bindings, and service URLs.

## Frequently Asked Questions

### How do I add a new secret to the y-gui backend?

Add the variable name to [`backend/wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/backend/wrangler.toml) under the `[vars]` section for non-sensitive configuration, or use `wrangler secret put VARIABLE_NAME` for encrypted secrets. Run `npm run cf-typegen` to update [`worker-configuration.d.ts`](https://github.com/luohy15/y-gui/blob/main/worker-configuration.d.ts), then access the variable via `env.VARIABLE_NAME` in your handlers.

### What is the difference between `.dev.vars` and [`wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/wrangler.toml) variables?

[`wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/wrangler.toml) contains non-sensitive configuration and resource bindings (like KV namespace IDs) that are safe to commit to version control. The `.dev.vars` file contains local development secrets (like API keys) that should never be committed and are loaded only during `wrangler dev` execution.

### How does TypeScript know the types for my Cloudflare Workers environment variables?

The [`worker-configuration.d.ts`](https://github.com/luohy15/y-gui/blob/main/worker-configuration.d.ts) file is auto-generated by the `cf-typegen` command, which parses [`wrangler.toml`](https://github.com/luohy15/y-gui/blob/main/wrangler.toml) and creates an `Env` interface with correct types (e.g., `KVNamespace` for storage bindings, `string` for custom variables). Import this interface into your handler files to enable type checking and autocomplete.

### Can I access environment variables globally instead of through the `env` parameter?

No, Cloudflare Workers isolates environment bindings per request and exposes them only through the `env` object passed to handlers. Global access patterns (like `process.env` in Node.js) are not supported in the Workers runtime, making the explicit `Env` parameter required for all configuration access.