bini-env 1.1.2 → 2.0.1

package/README.md

@@ -6,24 +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 dotenv** — no `.env` parsing at runtime; vars come from the host platform
-- **Vite-native dev** — `.env` loading, file watching, and server restarts are handled by Vite itself
-- **Dev banner** — prints `ß Bini.js (dev/preview)` and lists detected `.env` files on server start
-- **Prefix control** — `BINI_` and `VITE_` included out of the box, extend with your own
-- **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.
 
 ---
 
@@ -37,25 +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()]
 })
 ```
 
-**2. Read env vars in your Hono handlers**
+`biniEnv()` takes no options; there is nothing to configure.
+
+### 2. Read env vars in your Hono handlers
 
 ```ts
 // src/app/api/hello.ts
@@ -66,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)
@@ -88,29 +97,28 @@ app.post('/hello', async (c) => {
 export default app
 ```
 
+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: the handler throws immediately if one is missing or empty
+    const dbUrl  = requireEnv(c, 'DATABASE_URL')
+    const apiKey = requireEnv(c, 'STRIPE_SECRET_KEY')
 
-    // Required vars — handler throws immediately if missing
-    const dbUrl  = requireEnv(ctx, 'DATABASE_URL')
-    const apiKey = requireEnv(ctx, '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)
@@ -120,11 +128,91 @@ 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)).
+
+> **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
+
+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 no source is given and `Deno.env` cannot be read (for example without `--allow-env`), the lookup returns `undefined`.
+
+---
+
+## How It Works in Dev
+
+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.
+
+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.
+
+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.
+
+**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 | ✅ 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:**
+
+- 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, because `biniEnv()` now does it for you:
+
+```ts
+// vite.config.ts — no longer needed, remove this
+const env = loadEnv(mode, process.cwd(), '')
+for (const [key, value] of Object.entries(env)) {
+  if (!key.startsWith('BINI_') && !key.startsWith('VITE_')) {
+    process.env[key] = value
+  }
+}
+```
+
+```ts
+// vite.config.ts — this is all you need now
+export default defineConfig({
+  plugins: [biniEnv()]
+})
+```
+
+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/
+```
 
-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
+- 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.
 
 ---
 
@@ -132,158 +220,148 @@ app.post('/example', async (c) => {
 
 ### The Truth About Prefixes
 
-**Both `BINI_` and `VITE_` work exactly the same way.** Neither is special.
+**Both `BINI_` and `VITE_` work exactly the same way.** `biniEnv()` has no options, so the prefix list is fixed.
 
-| Prefix | Exposed to Browser? | Default Behavior |
-|--------|--------------------|------------------|
-| `BINI_` | **Yes** | Included in `envPrefix` by default |
-| `VITE_` | **Yes** | Vite's default prefix (always included) |
-| Any prefix you add | **Yes** | If you add it to `envPrefix` |
-| No prefix | **No** | Not exposed to browser |
+| Prefix | Exposed to Browser? |
+| --- | --- |
+| `BINI_` | **Yes** |
+| `VITE_` | **Yes** (Vite's own default prefix) |
+| No prefix | **No** |
 
 ### What `biniEnv()` Actually Does
 
 ```ts
-// biniEnv() 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"
+// 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)
+
+- ✅ `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
+# ✅ NOT exposed to the browser; mirrored into process.env for server-side use
 DATABASE_URL=postgres://...
 STRIPE_SECRET_KEY=sk_live_...
 AWS_SECRET_KEY=...
 ```
 
-**If you want `BINI_` to be private, remove it from `envPrefix`:**
-
-```ts
-// vite.config.ts
-biniEnv({ envPrefix: ['VITE_'] }) // Only VITE_ exposed
-// BINI_ is no longer exposed to the browser
-```
+Anything without `BINI_` or `VITE_` in front of it is not exposed to the browser.
 
 ### Choosing the Right Prefix
 
-Since `BINI_` and `VITE_` are both exposed by default:
-
 ```env
 # ✅ Use no prefix for secrets
 DATABASE_URL=postgres://...
 STRIPE_SECRET_KEY=sk_live_...
 
-# ✅ Use any prefix for public config
+# ✅ Use BINI_ or VITE_ for public config
 BINI_API_URL=https://api.example.com
 VITE_ANALYTICS_ID=UA-XXXX
-PUBLIC_APP_NAME=MyApp  # If you add PUBLIC_ to envPrefix
 ```
 
 ### Prefix Summary
 
-| Prefix | Exposed to Browser? | Use For |
-|--------|--------------------|---------|
-| No prefix | ❌ Never | **SECRETS** — API keys, database URLs, tokens |
-| `BINI_` | ✅ Yes (by default) | Public config (same as VITE_) |
-| `VITE_` | ✅ Yes (always) | Public config (Vite's default) |
-| Custom prefix | ✅ If in `envPrefix` | Public config you want to control |
+| Prefix | Exposed to Browser? | Mirrored to `process.env` (dev/preview)? | Use For |
+| --- | --- | --- | --- |
+| 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 | `process.env` ✅ |
-| Bun | Bun | System env / platform dashboard | `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 two things: tells Vite which env prefixes to expose to `import.meta.env`, 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
-config() {
-  return { envPrefix: ['BINI_', 'VITE_', ...yourExtras] }
+// what biniEnv() does internally (simplified)
+config(userConfig, { command, mode }) {
+  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_'] }
 }
 ```
 
-On server start you will see:
+### The env functions: `getEnv` / `requireEnv`
 
-```
-  ß Bini.js (dev)
-  ➜  Environments: .env.local, .env
-  ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.1.7:3000/
-```
-
-Vite handles everything else 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. bini-env does not reimplement any of that.
-
-### 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 are no `process.env` fallbacks. 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)
@@ -293,52 +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).
+```
+
+### `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)
 ```
-[bini-env] error  Missing required environment variable: "SMTP_HOST"
-  -> Set it in your platform's env config or hosting dashboard.
+
+### `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'])
 ```
 
-### `biniEnv(options?)`
+### `loadEnvFiles(root?, mode?)`
 
-Vite plugin. Registers `BINI_` and `VITE_` as env prefixes and optionally adds more.
+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, 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()
-// or with extra prefixes
-biniEnv({ envPrefix: ['MY_PUBLIC_'] })
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `envPrefix` | `string \| string[]` | `[]` | Extra prefixes to expose to `import.meta.env`, in addition to `BINI_` and `VITE_` |
+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',
   }
 }
 ```
@@ -348,47 +463,59 @@ 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
+# ✅ 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
+# ✅ Safe: not exposed, available server-side via getEnv/requireEnv
 DATABASE_URL=postgres://...
 STRIPE_SECRET=sk_live_...
 AWS_SECRET_KEY=...
 ```
 
-### Rule 3: Use Any Prefix for Public Data
+### 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
-PUBLIC_APP_NAME=MyApp
 ```
 
-### Rule 4: Remove `BINI_` from envPrefix if You Want It Private
-```ts
-// To make BINI_ private, remove it from envPrefix
-biniEnv({ envPrefix: ['VITE_'] })
+### Rule 4: Don't Leave Secret Placeholders Empty
+
+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 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
 ```
 
 ---
 
-## Performance
+## Notes on Cost
 
-| Metric | Dev | Prod |
-|--------|-----|------|
-| File reads | 0 | 0 |
-| Runtime cost | ~0ms | 0 |
-| Bundle impact | Minimal | Tree-shaken |
-
-No dotenv. No disk reads. No caching layer. `getEnv` is a direct call to Hono's adapter on every invocation — request-scoped and correct.
+- `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.
 
 ---
 
@@ -396,27 +523,40 @@ No dotenv. No disk reads. No caching layer. `getEnv` is a direct call to Hono's
 
 ### "My BINI_ var is exposed to the browser!"
 
-Yes — by design. `BINI_` is included in `envPrefix` by default. 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 during local development. 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 Vite loads `.env` files 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.
 
-### "Cloudflare secret not found"
+### "My .env value isn't taking effect in dev"
 
-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.
+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`.
 
-### "TypeScript error: Context not assignable to HonoContext"
+### "requireEnv still throws even though my key is in .env"
 
-Hono 4.12+ added a symbol to `HonoRequest` that can break structural assignability in strict TypeScript projects. Cast once per handler:
+- 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.
 
-```ts
-const ctx = c as any
-```
+### "getEnv returned an empty string instead of my default"
+
+An empty `.env` value is returned as `''`, and `??` only falls back for `undefined`. Use `getEnv(c, 'KEY') || 'default'`, or remove the empty line.
+
+### "bini-env isn't reading my .env file from the right folder"
+
+`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`.
+
+### "I set `envDir: false` and nothing loads"
+
+That is intended: `envDir: false` disables `.env` loading, so `bini-env` skips the mirror and the secret-name check.
+
+### "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"
 
@@ -430,12 +570,13 @@ Add to your `tsconfig.json` or entry file:
 
 ## Compatibility
 
-| Tool | Version | Notes |
-|------|---------|-------|
-| Vite | 8.x | `envPrefix` hook is 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.
 
 ---