Environment variables

You need: a scaffolded project.

The line

Secrets is where a value goes when it must not be a var, the config directory is where dev copies live, pithy env reports what resolved, and rotating a secret is the maintenance.

A var is a value you would put in a screenshot. A secret is one you would not.

Where
BASE_URL, ENVIRONMENT, PROJECT, WORKERVars, in wrangler.jsonc
A tunable your code reads — a threshold, a feed addressA var you declare with defineVars, in the Worker’s pithy.config.ts
A public Turnstile sitekeypithy.config.ts, where pithy turnstile provision writes it and the front end’s build reads it
An API key, a signing key, an OAuth client secretSecrets

.dev.vars is generated, not authored

It is generated from your machine-local secrets file, which lives at <config>/<project>/secrets.jsonc — outside every checkout, mode 0600.

Nothing to gitignore. Nothing git add -A can reach. Delete the whole clone and the values are still there.

pithy secrets edit      opens it
pithy doctor            tells you the path

Generation is idempotent by content, so a run that changes nothing writes no bytes.

Four vars the kit stamps and reads

VarRead by
PROJECTThe audit recorder
ENVIRONMENTThe audit recorder, and the Turnstile test-key exception
WORKERThe audit recorder — the only thing that tells two Workers’ events apart
BASE_URLWritten by pithy worker sync from your domains block

An emitter cannot set the first three. Origin is a property of the writer, not of the action — and a route that could claim to be another environment would make the column worth nothing precisely when it mattered.

All three are nullable, permanently. A Worker scaffolded before they existed carries none, a CLI action came from no Worker, and no historical row can be back-filled. null means not recorded.

Per-environment values

Every var lives in its environment’s stanza, and an env.<name>.vars block replaces the top-level one rather than merging with it. A var the top level sets and env.prod leaves out deploys to production without it. pithy worker sync writes the ones derived from your config — the route and the BASE_URL a domains block implies, and every var you declare — for every environment it declares.

That is the only non-interactive way to get the route written. A domains block added by hand and never synced declares an address nothing serves.

Declare your own vars

A var of your own — a tunable, a feed address, a threshold — is declared once, with defineVars from @pithy-sh/core/src/worker/vars, and set as vars in the Worker’s pithy.config.ts, beside domains and capabilities. Put the declaration in a module of its own, so your Worker’s code can import it without importing its config:

// apps/stats/src/vars.ts
import { defineVars } from "@pithy-sh/core/src/worker/vars";
import { z } from "zod";

export const VARS = defineVars({
  READY_AFTER_MINUTES: {
    description: "Minutes after the cron the next file is ready.",
    schema: z.coerce.number().int().min(0),
    default: 15,
    environments: { prod: 30 },
  },
});
// apps/stats/pithy.config.ts
import { VARS } from "./src/vars";

const config = {
  domains: DOMAINS,
  capabilities: [ … ],
  vars: VARS,
  app,
};
FieldWhat it is
descriptionOne line saying what the var is. Required: a var without one is refused
schemaThe Zod schema its value parses under
defaultThe value every environment gets that names none of its own
environmentsOptional, keyed by environment: dev is the top-level stanza, and staging, prod or any environment your root pithy.config.ts declares is that env.<name>

The default and every environment value are checked against the schema when the declaration is built, so a bad value fails at load, not at a request. A value must be JSON, because that is what wrangler stores. A name is letters, digits and underscores, and never one every object already has, like constructor or toString.

Then run pithy worker sync. It writes each var into the top-level vars and every env.<name>.vars, at that environment’s value or else the default, and pithy provision does the same for the stanza it provisions. A value you already set by hand that parses under the schema is yours and stays. One that does not is reported and left alone. A var nobody declared is never written or deleted. pithy worker sync has the rest, and pithy doctor’s Worker vars: block names any stanza that drops a var, declared or not. A declared var fails doctor’s exit when a stanza lacks it, holds the top level’s value where you declared that environment its own, or holds a value the schema refuses, so a CI step that runs pithy doctor catches a stanza that would deploy without it. A var nobody declared is only reported.

A capability declares the vars it reads the same way, as the vars option of its defineCapability call. They land in every stanza of every Worker composing it, beside your own. A name declared twice, by your Worker and a capability or by one capability and another, is refused before anything is written, naming both.

Do not build a URL from a literal

// wrong
const successUrl = "https://acme.com/thanks";

An origin written down is production’s origin written into staging — which lands a staging payer in production on an account that has bought nothing.

Build it from BASE_URL, or from the constant the scaffolded config derives from domains.

Reading a var

import { VARS } from "./vars";

const { READY_AFTER_MINUTES } = VARS.read(c.env); // number

A declared var comes back typed. VARS.read(env) parses each one out of the Worker’s env and returns it typed by its schema, with the default in place of one that is missing or does not parse. You never parse a var or fall back by hand.

A var that fell back tells you so, in the same read. Pass onFallback, and VARS.read(env, { onFallback }) calls it once for each var it gave its default, in declaration order, with a VarFallback. The values it returns are the same with it or without it, so you never parse a var a second time to find out what went wrong.

FieldWhat it is
nameThe var’s name
rawThe value env held, or undefined when it held none
reasonmissing or invalid
problemOne line saying why: missing, the plain-decimal rule, or the schema’s own message
issuesThe schema’s own Zod issues. None for a missing var, and the plain-decimal rule as one custom issue for a number written as text another way

A read of an env already read calls onFallback again. The values are parsed once per env and kept, but the fallbacks are reported on every read, so a Worker that logs them on every request logs them on every request. To warn once per isolate, keep your own record of what you warned about:

import type { VarFallback } from "@pithy-sh/core/src/worker/vars";
import { VARS } from "./vars";

const warned = new Set<string>();

function warnOnce({ name, raw, reason, problem }: VarFallback) {
  const key = `${name}=${String(raw)}`;
  if (warned.has(key)) return;
  warned.add(key);
  console.warn(`${name} ${reason}: ${problem}. Using the default.`);
}

const { READY_AFTER_MINUTES } = VARS.read(c.env, { onFallback: warnOnce });

A value that arrives as text, the way a .dev.vars line does, is tried as it is first. A number written as text is a plain decimal: an optional sign, digits, and an optional fraction. 15, -3 and 1.5 parse; 15, 15, 1e3, 0x10 and an empty value do not, under z.number() or z.coerce.number() alike, so a .dev.vars line READY_AFTER_MINUTES=1e3 falls back to the default 15 rather than reading as a thousand. An object, array or boolean var is written as its JSON ({"beta":true}, [1,2], true) and decoded from it. A schema that takes the text itself, such as one that turns 5m into milliseconds, keeps its own rule, and a number wrangler.jsonc stores as a JSON number parses as written. pithy worker sync and pithy doctor judge wrangler.jsonc by the same rule, so "READY_AFTER_MINUTES": "1e3" held there as a string is a value the schema refuses: sync reports it and keeps it, and doctor fails the exit on it.

A var you did not declare is c.env.MY_VAR, and you validate it if anything depends on its shape. It is a string somebody typed into a JSON file, and a Worker that assumes otherwise fails at the first request rather than at boot.

What never goes in a var

No secret. No credential. No token.

If it is in wrangler.jsonc it is in your repository, in every clone, in every CI log that echoes a config, and in the deploy output.

And no secret value is ever printed by any pithy command — not by provision, not by rotate, not by doctor. That is a property of the kit worth not undermining with a var.

ESC