bini-env 1.0.6 → 1.0.8

package/README.md

@@ -1,25 +1,43 @@
 # bini-env
 
-![npm](https://img.shields.io/npm/v/bini-env?color=cyan&style=flat-square)
+![npm](https://img.shields.io/npm/v/bini-env?color=cyan\&style=flat-square)
 ![npm downloads](https://img.shields.io/npm/dm/bini-env?style=flat-square)
 ![license](https://img.shields.io/npm/l/bini-env?style=flat-square)
-![vite](https://img.shields.io/badge/vite-plugin-646CFF?style=flat-square&logo=vite)
-![typescript](https://img.shields.io/badge/TypeScript-ready-3178C6?style=flat-square&logo=typescript)
+![vite](https://img.shields.io/badge/vite-%3E%3D8.0-646CFF?style=flat-square\&logo=vite)
+![typescript](https://img.shields.io/badge/TypeScript-ready-3178C6?style=flat-square\&logo=typescript)
+![node](https://img.shields.io/badge/node-%3E%3D20.19-339933?style=flat-square\&logo=node.js)
 
-Universal environment variable loader and Vite plugin for Bini.js. Automatically loads `.env` files in development, reads env vars from the host in production, and works across Node.js, Deno, Bun, and Vite edge functions — with zero configuration.
+**Zero-config environment variable system + Vite plugin for Bini.js**
+Loads `.env` in development, uses host-provided variables in production, and works across Node.js, Bun, Deno, and edge runtimes — without leaking secrets or adding runtime cost.
 
-## Features
+---
+
+## ⚠️ Before You Use This
+
+This library **does NOT magically make env vars safe**.
+
+* Anything exposed to the client (`import.meta.env`) is **public**.
+* Only server-side code (`getEnv`, `requireEnv`) can safely access secrets.
+* Misconfigured prefixes = **data leak**.
+
+If you don’t understand this, stop and fix that first.
+
+---
+
+## ✨ Features
 
-- **Universal `getEnv()` / `requireEnv()`** — read env vars in any runtime (Node.js, Deno, Bun, Vite client)
-- **Auto `.env` loading** — no manual `dotenv` setup needed in API routes
-- **`BINI_` prefix** — replaces Vite's `VITE_` prefix with `BINI_` automatically
-- **Branded startup banner** — replaces Vite's default header with a clean Bini.js output
-- **Supports dev and preview modes**
-- **Safe for edge bundlers** — dotenv is loaded via dynamic import, never statically resolved
+* **Universal API** — `getEnv()` / `requireEnv()` work across runtimes
+* **Zero-config `.env` loading** in development
+* **Strict production behavior** — no file reads, no dotenv
+* **Prefix control** — supports `BINI_`, `VITE_`, or custom
+* **Tree-shakeable** — no dead code in client bundles
+* **Edge-safe** — no static dotenv import
+* **Typed** — full TypeScript support
+* **Fast** — single load in dev, zero overhead in prod
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 pnpm add bini-env
@@ -31,197 +49,205 @@ yarn add bini-env
 
 ---
 
-## Vite Plugin Setup
+## 🚀 Quick Start (Don’t Overthink It)
 
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
-import biniEnv from 'bini-env';
+import { biniEnv } from 'bini-env';
 
 export default defineConfig({
   plugins: [biniEnv()]
 });
 ```
 
-That's it. Once added:
-- Your `.env` is auto-loaded for API routes in dev
-- Client code uses `import.meta.env.BINI_*` instead of `VITE_*`
-- The startup banner is replaced with the Bini.js header
+Done.
+
+If this doesn’t work, your project setup is broken — not the plugin.
 
 ---
 
-## Environment Variables
+## 🔐 Environment Rules (Read This Twice)
+
+> ✅ **Good news:** Both `BINI_` and `VITE_` prefixes work out of the box — no extra config needed.
 
-### `.env` file
+### Client (PUBLIC)
 
 ```env
-# Client-side vars — accessible via import.meta.env.BINI_*
-BINI_FIREBASE_API_KEY=your_key
-BINI_FIREBASE_AUTH_DOMAIN=your_domain
-
-# Server-side vars — accessible via getEnv() in API routes
-SMTP_USER=user@smtp.example.com
-SMTP_PASS=your_password
-FROM_EMAIL=App Name <noreply@example.com>
+BINI_PUBLIC_API_URL=https://api.example.com
+VITE_ANALYTICS_ID=UA-XXXX
 ```
 
-### In API routes
+Accessible via:
 
 ```ts
-import { getEnv, requireEnv } from 'bini-env';
+import.meta.env.BINI_PUBLIC_API_URL
+```
 
-// Returns string | undefined
-const smtpUser = getEnv('SMTP_USER');
+👉 **Never put secrets here. Ever.**
 
-// Returns string — throws a clear error if missing
-const smtpPass = requireEnv('SMTP_PASS');
-```
+---
+
+### Server (PRIVATE)
 
-### In client code (React / Vue / etc.)
+```env
+SMTP_PASS=super_secret
+DATABASE_URL=postgres://...
+```
 
 ```ts
-// Works because bini-env sets envPrefix: 'BINI_' automatically
-const apiKey = import.meta.env.BINI_FIREBASE_API_KEY;
+import { requireEnv } from 'bini-env';
+
+const pass = requireEnv('SMTP_PASS');
 ```
 
+👉 If this leaks, it’s your fault, not the library’s.
+
 ---
 
-## How env loading works by environment
+## 🧠 How It Actually Works
 
-| Environment | How vars are loaded | dotenv used? |
-|---|---|---|
-| Dev (Node.js / bini-router) | Auto-loaded from `.env` by bini-env | ✅ Yes (automatic) |
-| Preview (`vite preview`) | Auto-loaded from `.env` by bini-env | ✅ Yes (automatic) |
-| Production (Netlify / Vercel) | Injected by host dashboard | ❌ No |
-| Production (bini-server / VPS) | Set via server env or hosting panel | ❌ No |
-| Deno / Edge Functions | Read from `Deno.env` natively | ❌ No |
+| Mode             | Behavior                                 |
+| ---------------- | ---------------------------------------- |
+| Dev (`vite dev`) | Loads `.env` once via dynamic dotenv     |
+| Preview          | Same as dev                              |
+| Production       | Uses `process.env` / host injection only |
+| Edge/Deno        | Uses native `Deno.env`                   |
 
-You never need to import or configure `dotenv` manually.
+**No runtime branching in client bundles. No hidden magic.**
 
 ---
 
-## Startup Output
+## ⚙️ Plugin Options
 
-**Dev mode**
-```
-  ß Bini.js (dev)
-  ➜  Environments: .env.local, .env
-  ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.1.10:3000/
+```ts
+biniEnv({
+  enabled: true,
+  clearViteHeader: true,
+  logo: 'ß',
+  envPrefix: ['BINI_', 'VITE_']
+});
 ```
 
-**Preview mode**
-```
-  ß Bini.js (preview)
-  ➜  Environments: .env.local, .env
-  ➜  Local:   http://localhost:4173/
-  ➜  Network: http://192.168.1.10:4173/
-```
+### Critical Detail
+
+If you change `envPrefix`, you are changing what gets exposed to the browser.
+
+Break this → you leak secrets.
 
 ---
 
-## Plugin Options
+## 📚 API
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `enabled` | `boolean` | `true` | Enable or disable the plugin |
-| `clearViteHeader` | `boolean` | `true` | Replace Vite's default startup header |
-| `logo` | `string` | `'ß'` | Custom logo or text shown in the banner |
-| `envPrefix` | `string` | `'BINI_'` | Prefix for client-side env vars in `import.meta.env` |
+### `getEnv(key)`
 
-```ts
-biniEnv({
-  logo: '🚀',
-  clearViteHeader: true,
-  envPrefix: 'BINI_', // change to 'VITE_' to keep Vite's default
-})
+Returns `string | undefined`.
+
+Safe fallback reader across:
+
+* `Deno.env`
+* `process.env`
+* `import.meta.env`
+
+---
+
+### `requireEnv(key)`
+
+Same as `getEnv` but throws:
+
+```txt
+[bini-env] Missing required environment variable: "SMTP_PASS"
 ```
 
+Use this for anything critical.
+
 ---
 
-## Detected `.env` Files
+### `biniEnv(options)`
 
-The plugin checks for the following files in your project root (in priority order):
+Vite plugin.
+
+If your plugin order is wrong and things break, that’s on your config.
+
+---
+
+## 📂 Env File Resolution Order
 
 1. `.env.local`
-2. `.env.[NODE_ENV].local`
-3. `.env.[NODE_ENV]`
+2. `.env.[mode].local`
+3. `.env.[mode]`
 4. `.env`
 
+Loaded once. Cached. No repeated disk reads.
+
 ---
 
-## API Reference
+## ⚡ Performance
 
-### `getEnv(key: string): string | undefined`
+| Metric        | Dev       | Prod        |
+| ------------- | --------- | ----------- |
+| File Reads    | 1–5       | 0           |
+| Runtime Cost  | ~5ms once | 0           |
+| Bundle Impact | Minimal   | Tree-shaken |
 
-Read an environment variable in any runtime. Checks `Deno.env` → `process.env` → `import.meta.env` in order.
+If you see overhead in production, you did something wrong.
 
-```ts
-import { getEnv } from 'bini-env';
+---
 
-const smtpUser = getEnv('SMTP_USER');
-```
+## 🔥 Common Failure Modes
 
-### `requireEnv(key: string): string`
+### 1. “Env is undefined”
 
-Same as `getEnv` but throws a descriptive error if the variable is missing or empty. Use this for required secrets.
+You forgot the prefix.
 
-```ts
-import { requireEnv } from 'bini-env';
+### 2. “Works in dev, broken in prod”
 
-const smtpPass = requireEnv('SMTP_PASS');
-// Throws: [bini-env] Missing required environment variable: "SMTP_PASS".
-//   → In development: add it to your .env file.
-//   → In production: add it to your hosting dashboard environment variables.
-```
+You relied on `.env` in production.
 
-### `loadEnv(projectRoot?: string): Promise<void>`
+### 3. “Secrets leaked”
 
-Manually trigger `.env` loading. Called automatically by the Vite plugin — you should not need this.
+You exposed them via prefix.
 
-### `detectEnvFiles(projectRoot?: string): DetectedEnvFile[]`
+### 4. “Types not found”
 
-Scan a directory for `.env` files and return an array of matches.
+Add:
 
 ```ts
-import { detectEnvFiles } from 'bini-env';
-
-const files = detectEnvFiles('/my/project');
-// [{ name: '.env.local', path: '/my/project/.env.local' }, ...]
+/// <reference types="vite/client" />
 ```
 
 ---
 
-## Types
+## 🧪 Reality Check
 
-```ts
-interface BiniEnvPluginOptions {
-  enabled?: boolean;
-  clearViteHeader?: boolean;
-  logo?: string;
-  envPrefix?: string;
-}
-
-interface DetectedEnvFile {
-  name: string;
-  path: string;
-}
-```
+This library is intentionally simple.
+
+If you need:
+
+* secret rotation
+* encrypted envs
+* runtime validation schemas
+
+That’s **your job**, not this package.
 
 ---
 
-## Compatibility
+## 🤝 Contributing
+
+PRs welcome — but:
+
+* No bloat
+* No magic
+* No runtime cost
 
-| Runtime | Supported |
-|---|---|
-| Node.js 18+ | ✅ |
-| Bun | ✅ |
-| Deno / Edge Functions | ✅ |
-| Vite 7 | ✅ |
-| Vite 8 | ✅ |
+If it slows startup or increases bundle size, it’s getting rejected.
 
 ---
 
-## License
+## 📄 License
+
+MIT © Bini.js Team
+
+---
 
-MIT
+**Ship fast. Leak nothing. Blame config, not tooling.**

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+import { Plugin } from 'vite';
+export { Plugin } from 'vite';
+
+declare function suppressDotenvLogsGlobally(): void;
+interface BiniEnvPluginOptions {
+    readonly enabled?: boolean;
+    readonly clearViteHeader?: boolean;
+    readonly logo?: string;
+    readonly envPrefix?: string | string[];
+    readonly loadInPreview?: boolean;
+    readonly suppressDotenvLogs?: boolean;
+}
+interface DetectedEnvFile {
+    readonly name: string;
+    readonly path: string;
+}
+declare function getEnv(key: string): string | undefined;
+declare function requireEnv(key: string): string;
+declare function loadEnv(projectRoot?: string): Promise<void>;
+declare function detectEnvFiles(projectRoot?: string): DetectedEnvFile[];
+declare function biniEnv(options?: Readonly<BiniEnvPluginOptions>): Plugin;
+
+export { type BiniEnvPluginOptions, type DetectedEnvFile, biniEnv, detectEnvFiles, getEnv, loadEnv, requireEnv, suppressDotenvLogsGlobally };

package/dist/index.d.ts

@@ -1,79 +1,23 @@
 import { Plugin } from 'vite';
 export { Plugin } from 'vite';
 
+declare function suppressDotenvLogsGlobally(): void;
 interface BiniEnvPluginOptions {
-    /**
-     * Enable/disable the plugin
-     * @default true
-     */
     readonly enabled?: boolean;
-    /**
-     * Remove Vite's default header
-     * @default true
-     */
     readonly clearViteHeader?: boolean;
-    /**
-     * Custom logo/text to display
-     * @default 'ß'
-     */
     readonly logo?: string;
-    /**
-     * Override the env var prefix exposed to client code.
-     * Defaults to 'BINI_' — so BINI_MY_VAR is accessible via import.meta.env.BINI_MY_VAR
-     * Set to 'VITE_' to keep Vite's default behaviour.
-     * @default 'BINI_'
-     */
-    readonly envPrefix?: string;
+    readonly envPrefix?: string | string[];
+    readonly loadInPreview?: boolean;
+    readonly suppressDotenvLogs?: boolean;
 }
 interface DetectedEnvFile {
     readonly name: string;
     readonly path: string;
 }
-/**
- * Read an environment variable in any runtime.
- *
- * Priority order:
- *  1. Deno.env       — Netlify edge functions / Deno runtime
- *  2. process.env    — Node.js / Bun / bini-server
- *  3. import.meta.env — Vite client (BINI_-prefixed vars)
- *
- * Usage in API routes:
- *   import { getEnv } from 'bini-env';
- *   const smtpUser = getEnv('SMTP_USER');
- */
 declare function getEnv(key: string): string | undefined;
-/**
- * Read an environment variable and throw if it's missing or empty.
- * Use this for required secrets so you get a clear error at startup
- * instead of a cryptic crash later.
- *
- * Usage:
- *   const smtpPass = requireEnv('SMTP_PASS');
- */
 declare function requireEnv(key: string): string;
-/**
- * Auto-load .env into process.env for Node.js API route contexts.
- *
- * Behaviour by environment:
- *  - Deno (edge functions)  → no-op, Deno/Netlify injects env natively
- *  - NODE_ENV=production    → no-op, host injects env vars automatically
- *  - Node.js dev            → loads .env via dotenv (dynamic import, safe for bundlers)
- *
- * Called automatically by bini-env Vite plugin. You should not need to call this manually.
- */
 declare function loadEnv(projectRoot?: string): Promise<void>;
-/**
- * Detect which .env files exist in the project root, in Vite's priority order.
- */
 declare function detectEnvFiles(projectRoot?: string): DetectedEnvFile[];
-/**
- * Bini.js Vite plugin.
- *
- * What it does:
- *  - Sets envPrefix to 'BINI_' so client code uses import.meta.env.BINI_MY_VAR
- *  - Auto-loads .env for API routes in dev via loadEnv()
- *  - Replaces Vite's startup output with the Bini.js branded header
- */
 declare function biniEnv(options?: Readonly<BiniEnvPluginOptions>): Plugin;
 
-export { type BiniEnvPluginOptions, type DetectedEnvFile, biniEnv, detectEnvFiles, getEnv, loadEnv, requireEnv };
+export { type BiniEnvPluginOptions, type DetectedEnvFile, biniEnv, detectEnvFiles, getEnv, loadEnv, requireEnv, suppressDotenvLogsGlobally };