feat: make loadConfig synchronous

[rqbazan]

Why

loadConfig was async only because dynamic import() is — the async-ness was incidental, not a feature. Pre-v1, collapsing it to a single synchronous function is simpler and strictly more capable: it works in app code and in config files that tooling loads via require() or bundles to CJS (e.g. database/ORM tool configs), where a top-level await is rejected (ERR_REQUIRE_ASYNC_MODULE).

Verified across the matrix: require(esm) + native TS stripping load .ts/.mjs/.json configs synchronously on Node ≥22.18, Bun, and Deno (with createRequire based on the config path, so it stays clean even when a config is bundled to CJS).

What

@vlandoss/env/fs exports a single, synchronous loadConfig — same auto-discovery and {env} template shapes, but it loads with require() and returns Config<S> directly:

import { defineEnv } from "@vlandoss/env";
import { loadConfig } from "@vlandoss/env/fs";

export const env = defineEnv({ schema: Env, config: loadConfig(Env) });

BREAKING

loadConfig is now synchronous — drop the await:

- const config = await loadConfig(Env);
+ const config = loadConfig(Env);

await loadConfig(...) still returns the right value at runtime (awaiting a non-promise yields the value), but the await keeps the module asynchronous — a config file that keeps it still can't be require()'d. Remove it. (Minor bump: pre-v1.)

Changes

• fs: loadConfig is sync, over a shared pure core (discovery, {env} template, default-export unwrap, normalization); loads via require().
• tests: fs.test.ts covers the sync loader — auto-discovery, .ts via require, template, throws, composition.
• examples: backend-{node,bun,deno} drop the await; new backend-{node,bun,deno}-cjs boot the server from a CommonJS require() entry (server.cjs) and are e2e-tested with Playwright — they only boot because loadConfig is sync.
• engines: bump to >=22.18 (require(esm) + native TS stripping).
• docs: loadConfig guide, fs reference, quickstart, SSR guide, landing snippet, examples tables — all reflect the sync API.

Verification

• Package suite: 82 tests pass (node + browser).
• e2e: backend-{node,bun,deno} + backend-{node,bun,deno}-cjs (6 each) and ssr-react-router (4) pass.
• rr check (package + docsite): pass.

🤖 Generated with Claude Code

[vland-bot]

Preview release

Latest commit: e0021bb

Some packages have been released:

Package	Version	Install
@vlandoss/env	0.2.2-git-e0021bb.0	@vlandoss/env@0.2.2-git-e0021bb.0

Note

Use the PR number as tag to install any package. For instance:

pnpm add @vlandoss/env@pr-22