[Feature Request] varlock audit: detect cloudflare:workers, IaC bindings, and framework env usage

Open
  • Is something wrong?
#736 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@theoephraim is already working on this.

Since Jun 1, 2026.

Assessment

This issue has not been assessed yet.

Description

Description

varlock audit compares keys defined in .env.schema against environment-variable references found in source code. Today it works well for direct process.env.VAR usage and ENV.VAR from varlock/env, but it reports false positives ("unused in schema") for several common deployment patterns — especially Cloudflare Workers deployed via IaC tools other than varlock-wrangler.

In a monorepo using Alchemy for Cloudflare Workers + D1 + Astro:

  1. Deploy time: secrets and vars are declared as Worker bindings via alchemy.env.VAR / alchemy.secret.env.VAR in alchemy.run.ts. Alchemy reads resolved values from process.env (injected by varlock run --), but audit does not scan those binding declarations.
  2. Worker runtime: application code reads env.VAR from cloudflare:workers (sometimes via a thin package re-export). Audit does not trace property access on that import.
  3. Astro marketing site: public vars are consumed via astro:env/client imports, not process.env.

Running varlock audit from the infra package entry point flags every binding key (e.g. BETTER_AUTH_SECRET, PUBLIC_SERVER_URL, ALCHEMY_PASSWORD) as unused, even though they are actively used.

We currently work around Alchemy-only keys with # @auditIgnore per the audit hint ("If this is used by an external tool…"), but Worker and Astro keys are genuinely referenced in code — audit just cannot see them yet.

Motivation

Accurate varlock audit is important for:

  • Solo developers using AI coding agents (detecting drift between schema and code)
  • Monorepos where schema lives in packages/infra but consumption is spread across apps/packages
  • Alchemy / better-t-stack adopters who use varlock run -- <deploy> without varlock-wrangler

Without improved detection, audit either fails noisily or teams blanket @auditIgnore, which defeats the purpose.

Proposed Solution

Extend varlock audit (and/or document first-class patterns) for:

  1. cloudflare:workers env access — detect env.VAR, destructuring from cloudflare:workers, and common re-export wrappers (e.g. @talkiva/env/server).
  2. IaC binding declarations — optional detectors for known patterns such as alchemy.env.VAR, alchemy.secret.env.VAR, and potentially SST/Pulumi equivalents.
  3. Framework env modules — e.g. import { VAR } from "astro:env/client" mapped back to schema keys.
  4. Monorepo-aware scanning — when varlock.loadPath spans multiple packages, default audit scan roots could include sibling app/package directories referenced by the schema entry point.

If full static analysis is out of scope for some patterns, documenting recommended @auditIgnore categories (external CLI tools vs. runtime bindings) would still help.

Alternatives
  • @auditIgnore on all binding keys — works today but removes audit coverage for real drift.
  • Wait for @varlock/cloudflare-integration + varlock-wrangler only — does not help Alchemy/SST/Pulumi deploy paths where Worker code still uses cloudflare:workers without migrating imports to varlock/env.
  • Custom audit scripts — possible but duplicates logic Varlock already owns.
Additional Information
  • Related runtime binding request (separate concern): #735 — public API to build __VARLOCK_ENV for non-wrangler deploy tools.
  • better-t-stack adoption context: AmanVarshney01/create-better-t-stack#1029 — stacks deploying via Alchemy hit both #735 (runtime redaction) and this audit gap.
  • Real-world repro: Alchemy deploy with varlock run -- alchemy dev; schema at packages/infra/.env.schema importing apps/server/.env.schema; audit run from packages/infra with explicit scan paths still reports all binding keys unused.

Example binding declaration audit should recognize:

export const server = await Worker("server", {
  bindings: {
    BETTER_AUTH_SECRET: alchemy.secret.env.BETTER_AUTH_SECRET!,
    CORS_ORIGIN: alchemy.env.CORS_ORIGIN!,
  },
});

Example runtime usage audit should recognize:

import { env } from "cloudflare:workers";
// or: import { env } from "@talkiva/env/server";
const origin = env.CORS_ORIGIN;
Dominant language
TypeScript
Stars
4.9k
Forks
140
Avg merge
2d 3h
Merged PRs (30d)
35

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dmno-dev/varlock

All issues in dmno-dev/varlock

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.