bini-env 2.0.0 → 2.0.1

package/README.md

@@ -6,25 +6,26 @@
 ![vite](https://img.shields.io/badge/vite-8.x-646CFF?style=flat-square&logo=vite)
 ![hono](https://img.shields.io/badge/hono-4.x-E36002?style=flat-square&logo=hono)
 ![typescript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript)
-![node](https://img.shields.io/badge/node-%3E%3D20.19-339933?style=flat-square&logo=node.js)
+![node](https://img.shields.io/badge/node-%3E%3D20.12.0-339933?style=flat-square&logo=node.js)
 
-**Environment variable system + Vite plugin for Bini.js**
+Environment variable system + Vite plugin for Bini.js
 
-Powered by [Hono](https://hono.dev) — reads env vars from the Hono request context so variables are always resolved from the correct runtime binding, whether you're on Node.js, Bun, Deno, Vercel Edge, Netlify Edge, or Cloudflare Workers.
+Powered by [Hono](https://hono.dev). When you pass a Hono context, variables are read through Hono's `env(c)` adapter, so they resolve from the runtime binding of the platform you are on, whether that is Node.js, Bun, Deno, Vercel Edge, Netlify Edge, or Cloudflare Workers.
 
 ---
 
 ## Features
 
-- **Hono-native** — `getEnv(c, key)` / `requireEnv(c, key)` read directly from the Hono request context
-- **Universal runtime** — CF Workers, Node, Bun, Deno, Vercel Edge, Netlify Edge — Hono's adapter handles all of it
-- **Zero-config dev secrets** — non-prefixed `.env` values are always mirrored into `process.env` automatically during `vite dev` / `vite preview`, so Node-hosted Hono routes can read them with no manual loop
-- **Vite-native dev** — `.env` loading, file watching, and server restarts are handled by Vite itself
-- **`envDir`-aware** — respects a custom `envDir` or `root` in your `vite.config.ts` instead of always assuming the working directory
-- **Dev banner** — prints `ß Bini.js (dev/preview)` and lists detected `.env` files on server start
-- **Fixed, predictable prefixes** — only `BINI_` and `VITE_` are ever exposed to the browser; there's no config surface that can accidentally widen it
-- **Tree-shakeable** — nothing lands in the client bundle that shouldn't
-- **Typed** — full TypeScript support with an exported `HonoContext` type
+- **Hono-native.** `getEnv(c, key)` and `requireEnv(c, key)` read from the Hono request context through `hono/adapter`.
+- **Works without a context too.** Pass a plain object, or `undefined` / `null`, and the functions read from that object or from the runtime's own environment (`process.env`, or `Deno.env`).
+- **Zero-config dev secrets.** During `vite dev` and `vite preview`, `.env` values are mirrored into `process.env`, so Node-hosted Hono routes can read them with no manual loop.
+- **Vite-native loading.** The plugin uses Vite's own `loadEnv`, so the standard `.env`, `.env.local`, `.env.[mode]`, and `.env.[mode].local` files apply.
+- **`envDir`-aware.** A custom `envDir` or `root` in your `vite.config.ts` is respected, and `envDir: false` disables loading.
+- **Public-prefix secret warnings.** A variable whose name looks like a secret but starts with `BINI_` or `VITE_` triggers a warning, because it is bundled into client code.
+- **Dev banner.** Prints `ß Bini.js (dev|preview)` and lists detected `.env` files on server start.
+- **Multi-variable helpers.** `checkEnv` and `requireEnvs` validate several variables at once and report every missing name together.
+- **Edge-safe main entry.** The `bini-env` entry imports nothing from `node:` or `vite`. The Vite plugin lives in `bini-env/vite` and the file loader in `bini-env/node`, and a publish-time check (`check:edge`) verifies that `dist/index.js` has no `node:` or `vite` imports.
+- **Typed.** Full TypeScript support, with exported `HonoContext`, `EnvSource`, `EnvInput`, and `EnvCheck` types.
 
 ---
 
@@ -38,27 +39,35 @@ npm install bini-env hono
 yarn add bini-env hono
 ```
 
-> `hono` is a required peer dependency.
+> `hono` (`>=4.0.0`) is a required peer dependency. `vite` (`>=8.0.0`) is an optional peer dependency, needed only for the `bini-env/vite` plugin.
+
+### Entry points
+
+| Import | Contents | Runs on |
+| --- | --- | --- |
+| `bini-env` | `getEnv`, `requireEnv`, `checkEnv`, `requireEnvs`, `biniLogger`, and the types | Any runtime (no `node:` or `vite` imports) |
+| `bini-env/vite` | `biniEnv()` | Node, inside Vite |
+| `bini-env/node` | `loadEnvFiles`, `envFilesFor` | Node |
 
 ---
 
 ## Quick Start
 
-**1. Register the Vite plugin**
+### 1. Register the Vite plugin
 
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite'
-import { biniEnv } from 'bini-env'
+import { biniEnv } from 'bini-env/vite'
 
 export default defineConfig({
   plugins: [biniEnv()]
 })
 ```
 
-`biniEnv()` takes no options — there's nothing to configure.
+`biniEnv()` takes no options; there is nothing to configure.
 
-**2. Read env vars in your Hono handlers**
+### 2. Read env vars in your Hono handlers
 
 ```ts
 // src/app/api/hello.ts
@@ -69,17 +78,14 @@ const app = new Hono()
 
 app.post('/hello', async (c) => {
   try {
-    const ctx = c as any
-
-    // requireEnv throws if the var is missing — fail fast on required config
-    const apiKey  = requireEnv(ctx, 'MY_API_KEY')
+    // requireEnv throws if the var is missing or empty: fail fast on required config
+    const apiKey = requireEnv(c, 'MY_API_KEY')
 
-    // getEnv returns undefined if missing — use ?? to provide a default
-    const appName = getEnv(ctx, 'APP_NAME')     ?? 'World'
-    const timeout = parseInt(getEnv(ctx, 'TIMEOUT_MS') ?? '5000')
+    // getEnv returns undefined if the var is missing: use ?? to provide a default
+    const appName = getEnv(c, 'APP_NAME') ?? 'World'
+    const timeout = parseInt(getEnv(c, 'TIMEOUT_MS') ?? '5000')
 
     return c.json({ message: `Hello, ${appName}!` })
-
   } catch (error: any) {
     if (error.message?.includes('[bini-env] Missing required')) {
       return c.json({ error: error.message }, 500)
@@ -91,31 +97,28 @@ app.post('/hello', async (c) => {
 export default app
 ```
 
-That's it — no manual `loadEnv` loop in `vite.config.ts` needed. `MY_API_KEY` just needs to exist in your `.env` file with no prefix, and `requireEnv` will find it during dev and preview.
+No manual `loadEnv` loop in `vite.config.ts` is needed. `MY_API_KEY` just needs to exist in your `.env` file, and `requireEnv` will find it during dev and preview.
 
 ---
 
 ## Usage Pattern
 
-**Always pass `c` explicitly.** Cast it once at the top of the handler, then use `ctx` throughout.
+Pass the Hono context `c` to every call.
 
 ```ts
 app.post('/example', async (c) => {
   try {
-    const ctx = c as any
-
-    // Required vars — handler throws immediately if missing
-    const dbUrl  = requireEnv(ctx, 'DATABASE_URL')
-    const apiKey = requireEnv(ctx, 'STRIPE_SECRET_KEY')
+    // Required vars: the handler throws immediately if one is missing or empty
+    const dbUrl  = requireEnv(c, 'DATABASE_URL')
+    const apiKey = requireEnv(c, 'STRIPE_SECRET_KEY')
 
-    // Optional vars — fall back to sensible defaults
-    const model      = getEnv(ctx, 'AI_MODEL')    ?? 'gpt-4o'
-    const region     = getEnv(ctx, 'AWS_REGION')  ?? 'us-east-1'
-    const maxRetries = parseInt(getEnv(ctx, 'MAX_RETRIES') ?? '3')
-    const debug      = getEnv(ctx, 'DEBUG_MODE')  === 'true'
+    // Optional vars: fall back to sensible defaults
+    const model      = getEnv(c, 'AI_MODEL')   ?? 'gpt-4o'
+    const region     = getEnv(c, 'AWS_REGION') ?? 'us-east-1'
+    const maxRetries = parseInt(getEnv(c, 'MAX_RETRIES') ?? '3')
+    const debug      = getEnv(c, 'DEBUG_MODE') === 'true'
 
     // ... rest of handler
-
   } catch (error: any) {
     if (error.message?.includes('[bini-env] Missing required')) {
       return c.json({ error: error.message }, 500)
@@ -125,56 +128,58 @@ app.post('/example', async (c) => {
 })
 ```
 
-**The pattern in three steps:**
+- `requireEnv(c, 'KEY')` for vars the handler cannot run without.
+- `getEnv(c, 'KEY') ?? 'default'` for optional vars with sensible defaults.
+- `checkEnv` and `requireEnvs` for several variables at once (see the [API Reference](#api-reference)).
 
-1. `const ctx = c as any` — once, at the top of the handler
-2. `requireEnv(ctx, 'KEY')` — for vars the handler cannot run without
-3. `getEnv(ctx, 'KEY') ?? 'default'` — for optional vars with sensible defaults
+> **Empty values.** `getEnv` returns an empty string as-is (`KEY=` yields `''`), so `??` does not fall back to the default for it. `requireEnv` treats an empty value as missing.
 
----
+### Reading without a Hono context
 
-## How It Works in Dev
+Every function accepts an `EnvInput`: a Hono context, a plain object, or `undefined` / `null`.
+
+```ts
+getEnv(c, 'KEY')              // Hono context: read through Hono's env(c) adapter
+getEnv({ KEY: 'value' }, 'KEY') // plain object: read from it directly
+getEnv(undefined, 'KEY')      // no source: read from process.env, or Deno.env when there is no process.env
+```
 
-When you run `vite dev` (or `vite preview`), `biniEnv()` automatically loads your `.env*` files with Vite's own `loadEnv` and mirrors every **non-prefixed** variable into `process.env`. This is what lets `getEnv` / `requireEnv` resolve server-side secrets inside Hono API routes without any extra setup — Hono's `env(c)` adapter reads from `process.env` on Node, and `process.env` is now populated for you.
+When no source is given and `Deno.env` cannot be read (for example without `--allow-env`), the lookup returns `undefined`.
 
-It reads `.env` files from the same place Vite does: your configured `envDir` if you've set one, otherwise your `root`, otherwise the working directory. A custom `envDir` in `vite.config.ts` is respected automatically. If you've set `envDir: false` in your Vite config to disable `.env` loading entirely, `bini-env` respects that too and skips the mirror.
+---
 
-It happens silently in the background when it succeeds — no terminal log, no banner line, nothing to configure. Your existing dev server output (the `ß Bini.js` banner, detected `.env` files, local/network URLs) stays exactly as it was:
+## How It Works in Dev
 
-```
-  ß Bini.js (dev)
-  ➜  Environments: .env.local, .env
-  ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.1.7:3000/
-```
+When you run `vite dev` or `vite preview` (Vite's `serve` command), `biniEnv()` loads your `.env*` files with Vite's own `loadEnv` and mirrors every variable it finds into `process.env`. This is what lets `getEnv` and `requireEnv` resolve server-side secrets inside Hono API routes on Node without any extra setup.
 
-If loading or mirroring the `.env` file fails for any reason, `bini-env` prints a warning — but the dev server still boots either way, it never throws:
+It reads `.env` files from the same place Vite does: the `envDir` you configured (a relative `envDir` is resolved against `root`), otherwise your `root`, otherwise the working directory. If you set `envDir: false` in your Vite config, `bini-env` skips loading and mirroring altogether.
 
-```
-10:45:55 (!) [bini-env] Failed to inject .env into process.env: <reason>
+The mirror runs once, in the plugin's `config` hook, and prints nothing when it succeeds. If loading fails for any reason, `bini-env` prints a warning and the dev server still boots; it never throws:
+
+```text
+10:45:55 (!) [bini-env] Failed to load .env files: <reason>
 ```
 
-This happens automatically — there is no flag to turn it off. It's core behavior of `biniEnv()`, not an opt-in feature.
+This happens automatically; there is no flag to turn it off.
 
-**Precedence:** a value already present in `process.env` (set by your OS, shell, or CI) always wins. `.env` file values only fill in variables that aren't already set — they never override real environment configuration.
+**Precedence:** a value already present in `process.env` (set by your OS, shell, or CI) always wins. `.env` file values only fill in variables that are not already set; they never override real environment configuration.
 
 **What gets mirrored:**
 
 | Variable | Mirrored into `process.env`? |
-|----------|------------------------------|
+| --- | --- |
 | No prefix (`DATABASE_URL`) | ✅ Yes |
-| `BINI_` / `VITE_` prefixed | ❌ No — already handled via `import.meta.env` |
-| Empty value (`KEY=`) | ❌ No — skipped, so `requireEnv` still fails loudly on a blank placeholder |
-| Already set in the OS/CI environment | ❌ No — existing value is kept |
+| `BINI_` / `VITE_` prefixed | ✅ Yes (they are also exposed through `import.meta.env`) |
+| Empty value (`KEY=`) | ✅ Yes, as an empty string. `requireEnv` still treats it as missing, so a blank placeholder fails loudly |
+| Already set in the OS/CI environment | ❌ No. The existing value is kept |
 
 **Scope:**
 
-- Runs only for `vite dev` and `vite preview` (`command === 'serve'`)
-- **Never** runs for `vite build` — production bundles and `process.env` at build time are untouched
-- **Production** uses your hosting platform's native env injection (`bini-server`, Vercel, Netlify, Cloudflare, etc.) — nothing extra to do there
-- This behavior is always on — there is no option to disable it
+- The mirror runs only when Vite's command is `serve` (`vite dev` and `vite preview`).
+- It does **not** run for `vite build`: nothing is written to `process.env` at build time. The build only checks your env files for public-prefixed variables with secret-looking names (see [Security Best Practices](#security-best-practices)).
+- There is no option to disable the mirror.
 
-**Migrating from a manual loop:** if your project already has this in `vite.config.ts`, you can delete it — `biniEnv()` now does it for you:
+**Migrating from a manual loop:** if your project already has this in `vite.config.ts`, you can delete it, because `biniEnv()` now does it for you:
 
 ```ts
 // vite.config.ts — no longer needed, remove this
@@ -193,47 +198,63 @@ export default defineConfig({
 })
 ```
 
+Note that the plugin also mirrors `BINI_` and `VITE_` prefixed variables, which the loop above skipped.
+
+### Dev banner
+
+When the dev or preview server starts, `biniEnv()` replaces the URL printout with a version that begins with the `ß Bini.js` banner and the `.env` files it found:
+
+```text
+  ß Bini.js (dev)
+  ➜  Environments: .env.local, .env
+  ➜  Local:   http://localhost:3000/
+  ➜  Network: http://192.168.1.7:3000/
+```
+
+- The banner lists the files that exist among `.env.[mode].local`, `.env.[mode]`, `.env.local`, and `.env`, looked up in Vite's `root` (the `Environments` line is omitted when none exist). The `process.env` mirror itself uses `envDir`.
+- Vite's `ready in …` line is hidden.
+
 ---
 
 ## Environment Prefixes
 
 ### The Truth About Prefixes
 
-**Both `BINI_` and `VITE_` work exactly the same way.** Neither is special, and neither can be changed — `biniEnv()` always exposes exactly these two prefixes to the browser, nothing more.
+**Both `BINI_` and `VITE_` work exactly the same way.** `biniEnv()` has no options, so the prefix list is fixed.
 
 | Prefix | Exposed to Browser? |
-|--------|--------------------|
-| `BINI_` | **Yes** — always |
-| `VITE_` | **Yes** — always (Vite's own default prefix) |
-| No prefix | **No** — mirrored into `process.env` in dev/preview instead |
+| --- | --- |
+| `BINI_` | **Yes** |
+| `VITE_` | **Yes** (Vite's own default prefix) |
+| No prefix | **No** |
 
 ### What `biniEnv()` Actually Does
 
 ```ts
-// biniEnv() always sets envPrefix to:
+// biniEnv() always returns this from its config hook:
 envPrefix: ['BINI_', 'VITE_']
 
-// This tells Vite: "Expose ALL variables starting with BINI_ or VITE_ to import.meta.env"
-// Everything else is mirrored into process.env during vite dev / preview
+// This tells Vite: "Expose variables starting with BINI_ or VITE_ to import.meta.env"
 ```
 
 **This means:**
-- ✅ `BINI_API_KEY` → available in browser via `import.meta.env.BINI_API_KEY`
-- ✅ `VITE_API_URL` → available in browser via `import.meta.env.VITE_API_URL`
-- ❌ `DATABASE_URL` → NOT available in browser (no prefix) — available server-side via `getEnv`/`requireEnv`
+
+- ✅ `BINI_API_KEY` → available in the browser via `import.meta.env.BINI_API_KEY`
+- ✅ `VITE_API_URL` → available in the browser via `import.meta.env.VITE_API_URL`
+- ❌ `DATABASE_URL` → not exposed to the browser (no prefix); available server-side via `getEnv` / `requireEnv`
 
 ### How to Keep Secrets Secret
 
 **Use no prefix for secrets:**
 
 ```env
-# ✅ NOT exposed to browser — mirrored into process.env for server-side use only
+# ✅ NOT exposed to the browser; mirrored into process.env for server-side use
 DATABASE_URL=postgres://...
 STRIPE_SECRET_KEY=sk_live_...
 AWS_SECRET_KEY=...
 ```
 
-That's the whole rule. Since the prefix list is fixed, there's no config mistake that can widen what gets exposed — anything without `BINI_` or `VITE_` in front of it simply never reaches the browser.
+Anything without `BINI_` or `VITE_` in front of it is not exposed to the browser.
 
 ### Choosing the Right Prefix
 
@@ -250,102 +271,97 @@ VITE_ANALYTICS_ID=UA-XXXX
 ### Prefix Summary
 
 | Prefix | Exposed to Browser? | Mirrored to `process.env` (dev/preview)? | Use For |
-|--------|--------------------|-------------------------------------------|---------|
-| No prefix | ❌ Never | ✅ Yes (unless empty or already set) | **SECRETS** — API keys, database URLs, tokens |
-| `BINI_` | ✅ Always | ❌ No | Public config |
-| `VITE_` | ✅ Always | ❌ No | Public config (Vite's default) |
+| --- | --- | --- | --- |
+| No prefix | ❌ Never | ✅ Yes (unless already set) | **SECRETS**: API keys, database URLs, tokens |
+| `BINI_` | ✅ Yes | ✅ Yes (unless already set) | Public config |
+| `VITE_` | ✅ Yes | ✅ Yes (unless already set) | Public config (Vite's default) |
 
 ---
 
 ## Platform Support
 
-`getEnv` and `requireEnv` delegate to Hono's `env(c)` adapter, which reads from the correct source on every supported platform automatically. Your code never changes regardless of where it deploys.
+With a Hono context, `getEnv` and `requireEnv` delegate to Hono's `env(c)` adapter, which reads from the correct source on each supported platform. Your code does not change between platforms.
 
 | Platform | Runtime | Env source | How Hono reads it |
-|----------|---------|------------|-------------------|
-| Node.js | Node | System env / platform dashboard / `bini-env` dev mirror | `process.env` ✅ |
+| --- | --- | --- | --- |
+| Node.js | Node | System env / platform dashboard / `bini-env` dev mirror / `.env` files loaded by `bini-server` | `process.env` ✅ |
 | Bun | Bun | System env / platform dashboard / `bini-env` dev mirror | `process.env` ✅ |
 | Vercel Edge | V8 isolate | Project settings → Env Vars | `process.env` ✅ |
 | Netlify Edge | Deno | Site settings → Env Vars | `Deno.env.get()` ✅ |
 | Cloudflare Workers | V8 isolate | `wrangler.toml` / dashboard | CF bindings via `c.env` ✅ |
 | Deno Deploy | Deno | Project settings → Env Vars | `Deno.env.get()` ✅ |
 
-> **Cloudflare note:** Secrets set via `wrangler secret put` are only available inside the fetch handler via `c.env` — this is a Workers architecture constraint. `getEnv(ctx, key)` reads them correctly as long as you pass `c`.
+> **Cloudflare note:** secrets set via `wrangler secret put` are only available inside the fetch handler via `c.env`. `getEnv(c, key)` reads them as long as you pass `c`.
+
+When you pass anything other than a Hono context, the lookup uses that object, or falls back to `process.env` / `Deno.env` as described in [Reading without a Hono context](#reading-without-a-hono-context).
 
 ---
 
 ## How It Works
 
-### The plugin — `biniEnv()`
+### The plugin: `biniEnv()`
 
-Does three things: tells Vite to expose `BINI_` and `VITE_` prefixed vars to `import.meta.env`, mirrors non-prefixed `.env` values into `process.env` during `vite dev` / `vite preview` so Hono routes can read them, and prints the `ß Bini.js` banner with detected `.env` files when the dev or preview server starts.
+A Vite plugin (name `bini-env`, `enforce: 'pre'`) that does four things:
+
+1. Sets Vite's `envPrefix` to `['BINI_', 'VITE_']`.
+2. During `vite dev` and `vite preview`, mirrors `.env` values into `process.env` (without overriding existing values).
+3. Warns about public-prefixed variables with secret-looking names, in dev, preview, and build.
+4. Prints the `ß Bini.js` banner with detected `.env` files, and hides Vite's `ready in` line.
 
 ```ts
-// what biniEnv() does internally
+// what biniEnv() does internally (simplified)
 config(userConfig, { command, mode }) {
-  if (command === 'serve') {
-    const envDir = userConfig.envDir ?? userConfig.root ?? process.cwd()
-    // mirrors non-prefixed, non-empty .env values into process.env
-    // silent on success, warns on failure — no opt-out
+  if (userConfig.envDir !== false) {
+    // envDir: a string is resolved against root, otherwise root
+    if (command === 'serve') {
+      // loadEnv(mode, envDir, '') -> set every key not already in process.env
+    } else {
+      // loadEnv(mode, envDir, ['BINI_', 'VITE_']) -> secret-name warnings only
+    }
+    // on error: biniLogger.warn('Failed to load .env files: ...')
   }
   return { envPrefix: ['BINI_', 'VITE_'] }
 }
 ```
 
-The `process.env` mirror runs silently — it doesn't add any lines to the banner. On server start you will see the same banner as before:
-
-```
-  ß Bini.js (dev)
-  ➜  Environments: .env.local, .env
-  ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.1.7:3000/
-```
-
-Vite handles the rest natively: loading `.env`, `.env.local`, `.env.[mode]` files during dev, watching and restarting on change, injecting prefixed vars into `import.meta.env` at build time, and HMR when env files change.
+### The env functions: `getEnv` / `requireEnv`
 
-### The env functions — `getEnv` / `requireEnv`
+With a Hono context, both read through `env(c)` from `hono/adapter`, so every read is request-scoped and resolved by Hono's adapter for the current platform. A value is only returned when it is a string: other binding types, such as Cloudflare KV namespaces, come back as `undefined`. On Node, Hono's adapter reads from `process.env`, which is why the dev-mode mirror makes `.env` values resolvable there.
 
-Both functions read exclusively from `env(c)` via `hono/adapter` — the Hono request context. There is no direct `process.env` access inside `getEnv`/`requireEnv` themselves; on Node, Hono's adapter reads from `process.env`, which is why the dev-mode mirror above is what makes non-prefixed secrets resolvable there. Every read is request-scoped and resolved by Hono's adapter for the current platform.
-
-`dotenv` is never used. In production, vars are set in your hosting platform's environment config.
+`dotenv` is not used by these modules. In production, set variables in your hosting platform's environment configuration.
 
 ---
 
 ## API Reference
 
-### `getEnv(c, key)`
+### `getEnv(source, key)`
 
-Returns `string | undefined`. Reads from the Hono request context.
+Returns `string | undefined`. `source` is an `EnvInput`: a Hono context, a plain object, or `undefined` / `null`. Values that are not strings return `undefined`; an empty string is returned as-is.
 
 ```ts
 app.get('/config', async (c) => {
-  const ctx = c as any
-
-  const region   = getEnv(ctx, 'AWS_REGION') ?? 'us-east-1'
-  const logLevel = getEnv(ctx, 'LOG_LEVEL')  ?? 'info'
-  const debug    = getEnv(ctx, 'DEBUG_MODE') === 'true'
+  const region   = getEnv(c, 'AWS_REGION') ?? 'us-east-1'
+  const logLevel = getEnv(c, 'LOG_LEVEL')  ?? 'info'
+  const debug    = getEnv(c, 'DEBUG_MODE') === 'true'
 
   return c.json({ region, logLevel, debug })
 })
 ```
 
-### `requireEnv(c, key)`
+### `requireEnv(source, key)`
 
-Returns `string`. Throws immediately if the variable is missing or empty. Logs a descriptive error to the terminal on failure.
+Returns `string`. Throws `Error('[bini-env] Missing required environment variable: "KEY"')` when the variable is missing, empty, or not a string, and logs a descriptive error to the terminal first.
 
 ```ts
 app.post('/send-email', async (c) => {
   try {
-    const ctx = c as any
-
-    const smtpHost = requireEnv(ctx, 'SMTP_HOST')
-    const smtpPass = requireEnv(ctx, 'SMTP_PASS')
-    const smtpPort = parseInt(getEnv(ctx, 'SMTP_PORT') ?? '587')
+    const smtpHost = requireEnv(c, 'SMTP_HOST')
+    const smtpPass = requireEnv(c, 'SMTP_PASS')
+    const smtpPort = parseInt(getEnv(c, 'SMTP_PORT') ?? '587')
 
     // ... send email
 
     return c.json({ sent: true })
-
   } catch (error: any) {
     if (error.message?.includes('[bini-env] Missing required')) {
       return c.json({ error: error.message }, 500)
@@ -355,48 +371,89 @@ app.post('/send-email', async (c) => {
 })
 ```
 
-On failure, the terminal will show:
+On failure, the terminal shows:
 
+```text
+10:45:55 [bini-env] error Missing required environment variable: "SMTP_HOST"
+  -> Set it in your hosting dashboard (or in .env for dev, preview and bini-server).
 ```
-[bini-env] error  Missing required environment variable: "SMTP_HOST"
-  -> Set it in your platform's env config or hosting dashboard.
+
+### `checkEnv(source, keys)`
+
+Checks several variables at once. Returns `{ ok: boolean, missing: string[] }` (`missing` holds names only, never values). When any are missing, it logs one error listing all the missing names. It does not throw.
+
+```ts
+const { ok, missing } = checkEnv(c, ['DATABASE_URL', 'REDIS_URL', 'SESSION_SECRET'])
+if (!ok) return c.json({ error: `Missing: ${missing.join(', ')}` }, 500)
 ```
 
+### `requireEnvs(source, keys)`
+
+Requires several variables at once. Returns a record of key to value. If any are missing or empty, it logs them (through `checkEnv`) and throws one error: `[bini-env] Missing environment variables: A, B`.
+
+```ts
+const { DATABASE_URL, REDIS_URL } = requireEnvs(c, ['DATABASE_URL', 'REDIS_URL'])
+```
+
+### `loadEnvFiles(root?, mode?)`
+
+Imported from `bini-env/node`. Loads `.env` files into `process.env` without Vite; `bini-server` calls it at startup. Defaults: `root` is `process.cwd()`, and `mode` is `process.env.NODE_ENV`, or `'production'` when that is not set. Returns `{ files: string[], injected: number }`.
+
+- Files are read in this order of priority: `.env.[mode].local`, `.env.[mode]`, `.env.local`, `.env`. Only files that exist are read.
+- A value is only written when the variable is not already in `process.env`, so existing environment values win, and a variable set by a higher-priority file is not overridden by a lower one.
+- A leading byte-order mark is removed, files are parsed with Node's `util.parseEnv`, and a file that cannot be read or parsed is skipped.
+
+```ts
+import { loadEnvFiles } from 'bini-env/node'
+
+const { files, injected } = loadEnvFiles(process.cwd(), 'production')
+```
+
+`envFilesFor(root, mode)` (also from `bini-env/node`) returns the list of existing env file paths in that priority order.
+
 ### `biniEnv()`
 
-Vite plugin. Takes no options. Exposes `BINI_` and `VITE_` prefixed vars to `import.meta.env`, and mirrors every other (non-empty) `.env` value into `process.env` during dev/preview.
+Vite plugin, imported from `bini-env/vite`. Takes no options. Sets `envPrefix` to `['BINI_', 'VITE_']`, mirrors `.env` values into `process.env` during dev and preview, warns about public-prefixed variables with secret-looking names, and prints the dev banner.
 
 ```ts
 biniEnv()
 ```
 
-There's nothing to configure — no prefix list to extend, no flag to disable the `process.env` mirror. It reads `.env` files from your `envDir` (or `root`, or the working directory), never runs on `vite build`, never overrides a value already set in `process.env`, and skips the mirror entirely if you've set `envDir: false`.
+There is nothing to configure: no prefix list to extend and no flag to disable the `process.env` mirror. It reads `.env` files from your `envDir` (or `root`, or the working directory), never overrides a value already set in `process.env`, never mirrors during `vite build`, and skips loading entirely when `envDir` is `false`.
 
 ### `biniLogger`
 
-Vite-style terminal logger. Use it in your own Bini.js plugins or server-side code.
+Terminal logger with Vite-style timestamps. Use it in your own Bini.js plugins or server-side code.
 
 ```ts
 import { biniLogger } from 'bini-env'
 
 biniLogger.info('Server ready')
 biniLogger.warn('Missing optional var')
-biniLogger.error('Something broke', error)
+biniLogger.error('Something broke', error) // an Error's message is printed beneath
 ```
 
-### `HonoContext`
-
-Exported type (`Context` from Hono). Use it to type helper functions that group env reads, so you only cast `c as any` once per entry point.
+### Types
 
 ```ts
-import type { HonoContext } from 'bini-env'
+import type { HonoContext, EnvSource, EnvInput, EnvCheck } from 'bini-env'
+```
+
+| Type | Definition |
+| --- | --- |
+| `HonoContext` | Hono's `Context` |
+| `EnvSource` | `Record<string, unknown>` |
+| `EnvInput` | `HonoContext \| EnvSource \| undefined \| null` |
+| `EnvCheck` | `{ ok: boolean; missing: string[] }` |
 
+Use `HonoContext` to type helper functions that group env reads:
+
+```ts
 function readDbConfig(c: HonoContext) {
-  const ctx = c as any
   return {
-    url:      requireEnv(ctx, 'DATABASE_URL'),
-    poolSize: parseInt(getEnv(ctx, 'DB_POOL_SIZE') ?? '10'),
-    ssl:      getEnv(ctx, 'DB_SSL') !== 'false',
+    url:      requireEnv(c, 'DATABASE_URL'),
+    poolSize: parseInt(getEnv(c, 'DB_POOL_SIZE') ?? '10'),
+    ssl:      getEnv(c, 'DB_SSL') !== 'false',
   }
 }
 ```
@@ -406,36 +463,47 @@ function readDbConfig(c: HonoContext) {
 ## Security Best Practices
 
 ### Rule 1: Never Prefix Secrets
+
 ```env
-# ❌ BAD - This will be exposed to the browser!
+# ❌ BAD: this will be exposed to the browser!
 BINI_DATABASE_URL=postgres://...
 
-# ✅ GOOD - Not exposed to browser, mirrored into process.env for server-side use
+# ✅ GOOD: not exposed to the browser, mirrored into process.env for server-side use
 DATABASE_URL=postgres://...
 ```
 
+`biniEnv()` helps catch this. When a variable name contains `SECRET`, `PASSWORD`, `PASSWD`, `PRIVATE`, or `TOKEN` (case-insensitive) and starts with `BINI_` or `VITE_`, it prints a warning once per variable, in dev, preview, and build:
+
+```text
+(!) [bini-env] "BINI_API_TOKEN" starts with a public prefix (BINI_ / VITE_) so it is bundled into client code. Rename it without the prefix if it is a secret.
+```
+
+The check is by name only; it cannot tell whether a value is actually sensitive.
+
 ### Rule 2: Use No Prefix for Anything Secret
+
 ```env
-# ✅ Safe - Not exposed, available server-side via getEnv/requireEnv
+# ✅ Safe: not exposed, available server-side via getEnv/requireEnv
 DATABASE_URL=postgres://...
 STRIPE_SECRET=sk_live_...
 AWS_SECRET_KEY=...
 ```
 
 ### Rule 3: Use `BINI_` or `VITE_` for Public Data
+
 ```env
-# ✅ Safe - Public data
+# ✅ Safe: public data
 BINI_API_URL=https://api.example.com
 VITE_GA_ID=UA-XXXXX
 ```
 
 ### Rule 4: Don't Leave Secret Placeholders Empty
 
-An empty value (`API_KEY=`) is skipped by the `process.env` mirror, so `requireEnv` will correctly throw instead of silently succeeding with an empty string. Fill in real values, or remove the line entirely if it's genuinely unused.
+An empty value (`API_KEY=`) is mirrored as an empty string, and `requireEnv` treats it as missing and throws, so a blank placeholder never passes as configured. `getEnv` returns the empty string as-is, so check for it explicitly if you rely on `getEnv`. Fill in real values, or remove the line entirely if it is unused.
 
 ### Rule 5: Let OS/CI Env Vars Win in Dev
 
-The `process.env` mirror never overrides a variable that's already set. If you need to override a `.env` value locally (e.g. pointing at a different database), export it in your shell before starting the dev server rather than editing `.env`:
+The `process.env` mirror never overrides a variable that is already set. If you need to override a `.env` value locally (for example to point at a different database), export it in your shell before starting the dev server rather than editing `.env`:
 
 ```bash
 DATABASE_URL=postgres://staging... pnpm dev
@@ -443,15 +511,11 @@ DATABASE_URL=postgres://staging... pnpm dev
 
 ---
 
-## Performance
-
-| Metric | Dev | Prod |
-|--------|-----|------|
-| File reads | 1 (`loadEnv`, cached by Vite) | 0 |
-| Runtime cost | ~0ms (mirror runs once at server start) | 0 |
-| Bundle impact | Minimal | Tree-shaken |
+## Notes on Cost
 
-No dotenv. No per-request disk reads. No caching layer beyond Vite's own. `getEnv` is a direct call to Hono's adapter on every invocation — request-scoped and correct. The `process.env` mirror runs exactly once, when the dev or preview server starts.
+- `getEnv` and `requireEnv` read no files. With a Hono context, each call goes through Hono's adapter.
+- The `process.env` mirror runs once, in the plugin's `config` hook, when the dev or preview server starts.
+- `loadEnvFiles` reads each existing env file once per call.
 
 ---
 
@@ -459,41 +523,40 @@ No dotenv. No per-request disk reads. No caching layer beyond Vite's own. `getEn
 
 ### "My BINI_ var is exposed to the browser!"
 
-Yes — by design. `BINI_` is always exposed, the same as `VITE_`. Use no prefix for secrets.
+Yes, by design. `BINI_` is exposed the same way as `VITE_`. Use no prefix for secrets.
 
 ### "Env var is undefined in production"
 
-Vars set in `.env` files are only loaded by Vite (and mirrored into `process.env`) during local development and preview. In production, set your variables in your hosting platform's environment dashboard (Vercel, Netlify, Cloudflare, etc.).
+The `process.env` mirror only runs for `vite dev` and `vite preview`. In production, set your variables in your hosting platform's environment configuration (Vercel, Netlify, Cloudflare, etc.). `bini-server` additionally loads `.env` files from its working directory at startup, and variables already in the environment win.
 
 ### "Works in dev, undefined in prod"
 
-Same as above. Local dev works because `biniEnv()` loads `.env` files and mirrors non-prefixed vars into `process.env` automatically. Production requires platform-level configuration.
+Same as above. Local dev works because `biniEnv()` loads `.env` files and mirrors them into `process.env`. Production requires platform-level configuration.
 
 ### "My .env value isn't taking effect in dev"
 
-Two likely causes:
-- Check your shell and CI environment first — the `process.env` mirror never overrides a variable that's already set there. Unset it in your shell, or override it directly in your shell instead of `.env`.
-- Check the value isn't empty (`KEY=`) — empty values are skipped on purpose.
+Check your shell and CI environment first: the `process.env` mirror never overrides a variable that is already set there. Unset it in your shell, or override it directly in your shell instead of in `.env`.
 
 ### "requireEnv still throws even though my key is in .env"
 
-If the value is `KEY=` with nothing after the `=`, it's treated as unset and skipped by design — this is intentional so a blank placeholder doesn't silently pass as configured. Give it a real value.
+- If the value is `KEY=` with nothing after the `=`, it is treated as missing by `requireEnv`. Give it a real value.
+- The mirror only runs during `vite dev` and `vite preview`. In a production build, the variable must come from the runtime environment.
 
-### "bini-env isn't reading my .env file from the right folder"
+### "getEnv returned an empty string instead of my default"
 
-`biniEnv()` reads from your Vite `envDir` if you've set one, otherwise your `root`, otherwise the working directory — the same resolution Vite itself uses. Double check `envDir`/`root` in `vite.config.ts` if your `.env` lives somewhere non-standard.
+An empty `.env` value is returned as `''`, and `??` only falls back for `undefined`. Use `getEnv(c, 'KEY') || 'default'`, or remove the empty line.
 
-### "Cloudflare secret not found"
+### "bini-env isn't reading my .env file from the right folder"
 
-Secrets set via `wrangler secret put` are only available via `c.env` inside a handler — which is exactly what `getEnv(ctx, key)` reads. Ensure you are passing `c` to the function.
+`biniEnv()` reads from your Vite `envDir` if you have set one (relative paths resolve against `root`), otherwise your `root`, otherwise the working directory. Double-check `envDir` and `root` in `vite.config.ts` if your `.env` lives somewhere non-standard. The dev banner lists env files found in `root`, which can differ from `envDir`.
 
-### "TypeScript error: Context not assignable to HonoContext"
+### "I set `envDir: false` and nothing loads"
 
-Hono 4.12+ added a symbol to `HonoRequest` that can break structural assignability in strict TypeScript projects. Cast once per handler:
+That is intended: `envDir: false` disables `.env` loading, so `bini-env` skips the mirror and the secret-name check.
 
-```ts
-const ctx = c as any
-```
+### "Cloudflare secret not found"
+
+Secrets set via `wrangler secret put` are only available via `c.env` inside a handler, which is what `getEnv(c, key)` reads. Make sure you pass `c` to the function.
 
 ### "Types not found"
 
@@ -507,12 +570,13 @@ Add to your `tsconfig.json` or entry file:
 
 ## Compatibility
 
-| Tool | Version | Notes |
-|------|---------|-------|
-| Vite | 8.x | `envPrefix` hook and `loadEnv` are fully compatible; empty prefix array is never passed |
-| Hono | 4.x | `hono/adapter` `env()` is stable across all 4.x releases |
-| TypeScript | 5.x | Full type support via exported `HonoContext` |
-| Node.js | ≥ 20.19 | Minimum required version |
+| Tool | Version |
+| --- | --- |
+| Vite | `>=8.0.0` (optional peer; only for `bini-env/vite`) |
+| Hono | `>=4.0.0` (peer) |
+| Node.js | `>=20.12.0` |
+
+Typings are included.
 
 ---
 
@@ -524,4 +588,4 @@ PRs are welcome. The goal of this library is to stay minimal and runtime-cost-fr
 
 ## License
 
-MIT © Bini.js Team
+MIT © Bini.js Team