bini-env

Zero-config environment variable system + Vite plugin for Bini.js

Powered by Hono — 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.

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

Installation

pnpm add bini-env hono
# or
npm install bini-env hono
# or
yarn add bini-env hono

hono is a required peer dependency.

Quick Start

1. Register the Vite plugin

// vite.config.ts
import { defineConfig } from 'vite'
import { biniEnv } from 'bini-env'

export default defineConfig({
  plugins: [biniEnv()]
})

2. Read env vars in your Hono handlers

// src/app/api/hello.ts
import { Hono } from 'hono'
import { getEnv, requireEnv } from 'bini-env'

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')

    // 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')

    return c.json({ message: `Hello, ${appName}!` })

  } catch (error: any) {
    if (error.message?.includes('[bini-env] Missing required')) {
      return c.json({ error: error.message }, 500)
    }
    return c.json({ error: 'Something went wrong.' }, 500)
  }
})

export default app

Usage Pattern

Always pass c explicitly. Cast it once at the top of the handler, then use ctx throughout.

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')

    // 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'

    // ... rest of handler

  } catch (error: any) {
    if (error.message?.includes('[bini-env] Missing required')) {
      return c.json({ error: error.message }, 500)
    }
    return c.json({ error: 'Something went wrong.' }, 500)
  }
})

The pattern in three steps:

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

Environment Prefixes

BINI_ — server-side vars

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.

To additionally expose a BINI_ var to the client, add it to envPrefix explicitly:

biniEnv({ envPrefix: ['BINI_', 'VITE_', 'MY_PUBLIC_'] })

VITE_ — public client vars

VITE_ is Vite's built-in prefix. Any var starting with VITE_ is bundled into your client-side JavaScript and is publicly visible.

VITE_ANALYTICS_ID=UA-XXXX             # bundled into client JS — public
VITE_API_URL=https://api.example.com  # bundled into client JS — public

// accessible anywhere, including the browser
import.meta.env.VITE_ANALYTICS_ID

Choosing the right prefix

# ✓ use VITE_ for anything the browser needs
VITE_API_URL=https://api.example.com

# ✓ use BINI_ for server-side config
BINI_FEATURE_FLAG=true

# ✓ no prefix for secrets — read via getEnv(ctx, key) only
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.

Prefix summary

| 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 |

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.

| 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 ✅ | | 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.

How It Works

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.

// what biniEnv() does internally
config() {
  return { envPrefix: ['BINI_', 'VITE_', ...yourExtras] }
}

On server start you will see:

  ß 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

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.

API Reference

getEnv(c, key)

Returns string | undefined. Reads from the Hono request context.

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'

  return c.json({ region, logLevel, debug })
})

requireEnv(c, key)

Returns string. Throws immediately if the variable is missing or empty. Logs a descriptive error to the terminal on failure.

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')

    // ... 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)
    }
    return c.json({ error: 'Failed to send email.' }, 500)
  }
})

On failure, the terminal will show:

[bini-env] error  Missing required environment variable: "SMTP_HOST"
  -> Set it in your platform's env config or hosting dashboard.

biniEnv(options?)

Vite plugin. Registers BINI_ and VITE_ as env prefixes and optionally adds more.

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_ |

biniLogger

Vite-style terminal logger. Use it in your own Bini.js plugins or server-side code.

import { biniLogger } from 'bini-env'

biniLogger.info('Server ready')
biniLogger.warn('Missing optional var')
biniLogger.error('Something broke', error)

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.

import type { HonoContext } from 'bini-env'

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',
  }
}

Performance

| 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.

Troubleshooting

"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.).

"Works in dev, undefined in prod"

Same as above. Local dev works because Vite loads .env files automatically. Production requires platform-level configuration.

"Cloudflare secret not found"

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.

"TypeScript error: Context not assignable to HonoContext"

Hono 4.12+ added a symbol to HonoRequest that can break structural assignability in strict TypeScript projects. Cast once per handler:

const ctx = c as any

"Types not found"

Add to your tsconfig.json or entry file:

/// <reference types="vite/client" />

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 |

Contributing

PRs are welcome. The goal of this library is to stay minimal and runtime-cost-free. Contributions that add unnecessary complexity, increase bundle size, or introduce startup overhead will not be accepted.

License

MIT © Bini.js Team