alchemy-env-types

name	alchemy-env-types
description	Derive Cloudflare worker env types from Alchemy resource Env types instead of hand-writing env shapes. Use when editing worker bindings, adding or removing env vars in packages/infra, touching cloudflare-env.d.ts or env.d.ts files, importing from cloudflare:workers, or fixing env typing in API or web apps.

Alchemy Env Types

Use Alchemy's generated worker Env type as the single source of truth for Cloudflare env bindings in this repo.

• Do not hand-write env shapes like Record<string, string | undefined>.
• Do not redeclare individual env vars in app typing files when the Alchemy resource type already contains them.
• Do not locally cast env in app code if the declaration file can carry the correct type.

Pattern

1. Export the worker resource type from infra:

export type WebResource = Awaited<ReturnType<typeof createWeb>>

2. Derive an env alias from that resource in packages/infra/src/types/:

import type { WebResource } from "../web"

export type WebEnv = WebResource["Env"]

3. In the app declaration file, extend Cloudflare.Env from that alias:

declare namespace Cloudflare {
  type WebEnv = import("infra/types/web-env").WebEnv
  interface Env extends WebEnv {}
}

4. If the app imports env from cloudflare:workers, make sure the module is declared and exports that merged env type:

interface CloudflareEnv extends Cloudflare.Env {}

declare module "cloudflare:workers" {
  export const env: CloudflareEnv
}

Repo Notes

• apps/api/env.d.ts is the reference API pattern.
• apps/web/cloudflare-env.d.ts is the reference web pattern.
• packages/infra/src/types/env.ts contains API env aliases.
• packages/infra/src/types/web-env.ts contains the web env alias.
• In this repo, the web app needs the declare module "cloudflare:workers" block so TypeScript can resolve that module. Keep that block minimal and sourced from Cloudflare.Env.

When Changing Bindings

When adding, removing, or renaming a binding in infra:

1. Update the Alchemy resource definition in packages/infra/src/web.ts or the corresponding worker factory.
2. Make sure the worker resource type is exported.
3. Make sure the app declaration file extends the env alias derived from that worker resource.
4. Remove any manual env var redefinitions or local casts that duplicate the generated type.

Bad

const env = cloudflareEnv as {
  VITE_STAGE?: string
}

declare module "cloudflare:workers" {
  export const env: {
    VITE_STAGE: string
    INTERNAL_CALLBACK_SECRET: string
  }
}

Good

import { env } from "cloudflare:workers"

const stage = env.VITE_STAGE

Keep the declaration layer thin. The env var list should come from Alchemy, not be copied by hand into app code.