bini-env 1.1.1 → 1.1.2

package/README.md

@@ -5,10 +5,10 @@
 ![license](https://img.shields.io/npm/l/bini-env?style=flat-square)
 ![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-ready-3178C6?style=flat-square&logo=typescript)
+![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)
 
-**Zero-config 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.
 
@@ -130,53 +130,73 @@ app.post('/example', async (c) => {
 
 ## Environment Prefixes
 
-### `BINI_` — server-side vars
+### The Truth About Prefixes
 
-`BINI_` is bini-env's own prefix. Variables are **not** exposed to `import.meta.env` by default, making it the right choice for server-side config and secrets.
+**Both `BINI_` and `VITE_` work exactly the same way.** Neither is special.
 
-To additionally expose a `BINI_` var to the client, add it to `envPrefix` explicitly:
+| 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 |
+
+### What `biniEnv()` Actually Does
 
 ```ts
-biniEnv({ envPrefix: ['BINI_', 'VITE_', 'MY_PUBLIC_'] })
+// biniEnv() sets envPrefix to:
+envPrefix: ['BINI_', 'VITE_']
+
+// This tells Vite: "Expose ALL variables starting with BINI_ or VITE_ to import.meta.env"
 ```
 
-### `VITE_` — public client vars
+**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)
 
-`VITE_` is Vite's built-in prefix. Any var starting with `VITE_` is bundled into your client-side JavaScript and is publicly visible.
+### How to Keep Secrets Secret
+
+**Use no prefix for secrets:**
 
 ```env
-VITE_ANALYTICS_ID=UA-XXXX             # bundled into client JS — public
-VITE_API_URL=https://api.example.com  # bundled into client JS — public
+# ✅ NOT exposed to browser
+DATABASE_URL=postgres://...
+STRIPE_SECRET_KEY=sk_live_...
+AWS_SECRET_KEY=...
 ```
 
+**If you want `BINI_` to be private, remove it from `envPrefix`:**
+
 ```ts
-// accessible anywhere, including the browser
-import.meta.env.VITE_ANALYTICS_ID
+// vite.config.ts
+biniEnv({ envPrefix: ['VITE_'] }) // Only VITE_ exposed
+// BINI_ is no longer exposed to the browser
 ```
 
-### Choosing the right prefix
-
-```env
-# ✓ use VITE_ for anything the browser needs
-VITE_API_URL=https://api.example.com
+### Choosing the Right Prefix
 
-# ✓ use BINI_ for server-side config
-BINI_FEATURE_FLAG=true
+Since `BINI_` and `VITE_` are both exposed by default:
 
-# ✓ no prefix for secrets — read via getEnv(ctx, key) only
+```env
+# ✅ Use no prefix for secrets
 DATABASE_URL=postgres://...
 STRIPE_SECRET_KEY=sk_live_...
-```
 
-> Avoid defining the same variable under two different prefixes — your code will silently read whichever one it finds first.
+# ✅ Use any prefix 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 Summary
 
-| Prefix | Exposed to browser | Use for |
+| Prefix | Exposed to Browser? | Use For |
 |--------|--------------------|---------|
-| `BINI_` | No (unless added to `envPrefix`) | Server-side config |
-| `VITE_` | Yes, always | Public client config |
-| No prefix | No | Secrets — server only |
+| 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 |
 
 ---
 
@@ -325,6 +345,41 @@ function readDbConfig(c: HonoContext) {
 
 ---
 
+## Security Best Practices
+
+### Rule 1: Never Prefix Secrets
+```env
+# ❌ BAD - This will be exposed to the browser!
+BINI_DATABASE_URL=postgres://...
+
+# ✅ GOOD - Not exposed to browser
+DATABASE_URL=postgres://...
+```
+
+### Rule 2: Use No Prefix for Anything Secret
+```env
+# ✅ Safe - Not exposed
+DATABASE_URL=postgres://...
+STRIPE_SECRET=sk_live_...
+AWS_SECRET_KEY=...
+```
+
+### Rule 3: Use Any Prefix for Public Data
+```env
+# ✅ 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_'] })
+```
+
+---
+
 ## Performance
 
 | Metric | Dev | Prod |
@@ -339,6 +394,10 @@ No dotenv. No disk reads. No caching layer. `getEnv` is a direct call to Hono's
 
 ## Troubleshooting
 
+### "My BINI_ var is exposed to the browser!"
+
+Yes — by design. `BINI_` is included in `envPrefix` by default. 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.).
@@ -388,4 +447,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bini-env",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Universal environment variable loader and Vite plugin for Bini.js — powered by Hono, works across Node.js, Bun, Deno, Vercel Edge, Netlify Edge, and Cloudflare Workers",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -69,10 +69,10 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "26.1.2",
     "hono": "^4.8.4",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
+    "typescript": "^5.8.3",
     "vite": "^8.0.8"
   },
   "engines": {