netris-nestri/docs/alchemy.md

Alchemy — infrastructure as code

This project uses Alchemy (v0.93.12) for infrastructure-as-code — the equivalent of SST, but targeting Cloudflare Workers instead of AWS Lambda.

Project structure

web/
  alchemy.run.ts          # Entry point — creates scope, imports infra
  infra/
    stage.ts              # Stage detection (Scope.getCurrentScope().stage)
    secret.ts             # Encrypted secrets via alchemy.secret()
    auth.ts               # Auth Worker resource
    api.ts                # API Worker resource

alchemy.run.ts — entry point

import alchemy from 'alchemy';

const app = await alchemy('nestri', {
	password: process.env.ALCHEMY_PASSWORD // required for secrets
});

// Import infra modules in dependency order (SST-style)
await import('./infra/stage.ts');
await import('./infra/secret.ts');
await import('./infra/auth.ts');
await import('./infra/api.ts');

await app.finalize();

Key rules:

• alchemy(appName, opts) creates a scope — resources register into this scope automatically
• app.finalize() must be called at the end to persist state
• Import order matters — resources that depend on others must be imported after
• --dev flag runs locally via Miniflare; omit it to deploy to Cloudflare

Infra resources

Each resource is imported from alchemy/cloudflare and called with an ID + props:

import { Worker, KVNamespace, D1Database } from 'alchemy/cloudflare';

export const kv = await KVNamespace('my-kv');
export const db = await D1Database('my-db');

export const worker = await Worker('my-worker', {
	entrypoint: 'apps/some-app/src/index.ts',
	compatibility: 'node', // enables nodejs_compat flag
	url: true, // assign workers.dev URL
	bindings: {
		KV: kv, // resource binding → KVNamespace at runtime
		DB: db, // → D1Database
		PLAIN_VAR: 'hello' // → plain_text binding
	}
});

Supported resources (subset)

Resource	Import	Purpose
Worker	alchemy/cloudflare	Cloudflare Worker (entrypoint or inline script)
KVNamespace	alchemy/cloudflare	KV storage
D1Database	alchemy/cloudflare	D1 SQL database
R2Bucket	alchemy/cloudflare	R2 object storage
Queue	alchemy/cloudflare	Queue/pub-sub

Compatibility flag

Always add compatibility: 'node' to Workers that use Node.js built-ins (node:async_hooks, crypto, node:stream, etc.):

Worker('api', {
	entrypoint: 'apps/api/app/index.ts',
	compatibility: 'node' // enables nodejs_compat
});

Stage detection

// infra/stage.ts
import { Scope } from 'alchemy';
const scope = Scope.getCurrentScope();
export const stage = scope?.stage ?? 'dev';
export const isPermanent = ['production', 'dev'].includes(stage);

Use stage for conditional infrastructure:

const api = await Worker('api', {
	...(isPermanent && {
		observability: { enabled: true },
		logpush: true
	})
});

Pass --stage flag at runtime: bun alchemy.run.ts --stage production

Secrets and environment variables

Three levels of env management, from most-secure to least:

1. alchemy.secret.env.X (preferred)

// infra/secret.ts
import alchemy from 'alchemy';

export const secret = {
	steamApiKey: alchemy.secret.env.STEAM_API_KEY // reads process.env at deploy time
	// Equivalent to:
	// steamApiKey: alchemy.secret(process.env.STEAM_API_KEY),
};

• Reads from process.env at deploy time
• Throws a descriptive error if the env var is missing
• Encrypted in Alchemy state files (.alchemy/)
• Deployed as secret_text binding (hidden from Cloudflare API)

2. alchemy.env() (non-secret config)

export const frontendUrl = alchemy.env('FRONTEND_URL', 'http://localhost:5173');

• Optional default value
• Plain text — not encrypted
• Deployed as plain_text binding

3. Plain strings in bindings (inline)

bindings: {
	MY_VAR: 'hello';
}

• Hard-coded, visible in state files
• Deployed as plain_text binding

How bindings map to runtime types

Alchemy binding type	Deployed as	Runtime type
Worker	service	Service (has .fetch())
KVNamespace	kv_namespace	KVNamespace
D1Database	d1	D1Database
alchemy.secret()	secret_text	string
plain string	plain_text	string
Json(...)	json	typeof json

Service bindings (Worker → Worker)

Pass one Worker as a binding to another:

// infra/auth.ts
export const auth = await Worker('auth', {
  entrypoint: 'apps/auth/src/index.ts',
  compatibility: 'node',
  bindings: { ... },
});

// infra/api.ts
import { auth } from './auth.ts';
export const api = await Worker('api', {
  entrypoint: 'apps/api/app/index.ts',
  bindings: { AUTH: auth },
});

At runtime, env.AUTH is a Service — call it directly:

const response = await env.AUTH.fetch(request);

OpenAuth client + service binding

The @openauthjs/openauth/client only accepts a URL string for issuer, so use a custom fetch to route through the service binding:

function getClient(env: Record<string, unknown>) {
	return createClient({
		issuer: 'https://auth.internal', // dummy — used for path construction
		clientID: 'api',
		fetch: (input, init) => {
			const url = new URL(typeof input === 'string' ? input : input.url);
			const request = new Request(url.pathname + url.search, init);
			return (env.AUTH as { fetch: typeof fetch }).fetch(request);
		}
	});
}

Env propagation to Workers

CF Workers receive env vars as the second argument to the fetch handler (env), NOT via process.env. Bridge the gap with a lazy + overridable schema:

// packages/core/src/env.ts
import { memo } from '../utils/memo.ts';

let _overrides: Record<string, unknown> = {};

export namespace Env {
	export const Info = z.object({
		FRONTEND_URL: z.string().optional(),
		STEAM_API_KEY: z.string().optional(),
		AUTH_ISSUER_URL: z.string().optional()
	});
	export type Info = z.infer<typeof Info>;

	const _get = memo(() => Info.parse({ ...process.env, ..._overrides }));

	export function get(): Info {
		return _get();
	}

	export function init(bindings: Record<string, unknown>) {
		_overrides = bindings;
		_get.reset();
	}
}

Wire in the Hono entrypoint:

export default {
	fetch(request, env, ctx) {
		Env.init(env); // merge CF bindings into Env
		return app.fetch(request, env, ctx);
	}
};

Now any module that imports Env.get() gets the correct values — on Bun dev process.env provides them, on CF Workers the bindings override.

CLI usage

# Local dev (Miniflare)
bun alchemy.run.ts --dev

# Deploy to Cloudflare
bun alchemy.run.ts --stage production

# Destroy all resources
bun alchemy.run.ts --destroy

# With custom stage
bun alchemy.run.ts --stage wanjohiryan

# Password (for encrypting secrets)
export ALCHEMY_PASSWORD="some-passphrase"

When deploying, set CLOUDFLARE_API_TOKEN or configure alchemy login.

Common patterns

Conditional infra per-stage

Worker('api', {
	...(isPermanent && { logpush: true }),
	...(stage === 'production' && { scaling: { min: 3, max: 10 } })
});

Across-app resource references

Alchemy uses top-level await in infra files — resources resolve at import time within the active scope. The scope propagates via AsyncLocalStorage, so any await import() after alchemy(appName) picks it up.

.alchemy/ directory

Created automatically — contains Miniflare state, build output, and encrypted state files. Add to .gitignore.

.alchemy/

---

Index Rule: Null-Safe Exclusions (IS DISTINCT FROM)

When writing indices to track data drift, synchronization deltas, or pending background worker states where values might be nullable, always build a partial index utilizing Postgres-native IS DISTINCT FROM.

Standard inequality operators (!= or <>) evaluate to NULL if either column is NULL, causing them to bypass standard WHERE index filters. Using is distinct from allows Postgres to treat NULL as a real value for state comparison:

• Excludes perfectly synchronized records completely from the index footprint.
• Optimizes heavy background worker poll queries directly into small, lightning-fast index scans.

2. Add to the Pattern: index.ts (Domain Namespace) section

Replace the existing create block and add the upsert block inside SomeModule:

// ── create ───────────────────────────────────────────────────────────
// Use Info.pick({…}) for the schema — keeps fields in sync with Info.
// Always use .returning() to get the updated row context in one database trip.
export const create = fn(Info.pick({ id: true, name: true, email: true }), async (input) => {
	return Database.use(async (tx) => {
		const [row] = await tx
			.insert(SomeTable)
			.values({
				id: input.id,
				name: input.name,
				email: input.email ?? null
			})
			.returning();
		return row;
	});
});

// ── upsert ───────────────────────────────────────────────────────────
// Simple copies use the input values directly. For coalesce-style set
// expressions, reference the excluded pseudo-table with unqualified
// identifiers: sql`excluded.${sql.identifier(SomeTable.name.name)}` —
// interpolating a column object (or its .name string) is invalid.
export const upsert = fn(Info.pick({ id: true, name: true }), async (input) => {
	return Database.use(async (tx) => {
		const [row] = await tx
			.insert(SomeTable)
			.values({ id: input.id, name: input.name })
			.onConflictDoUpdate({
				target: SomeTable.id,
				set: { name: input.name }
			})
			.returning();
		return row;
	});
});