DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

Environment Variables

Standard environment variable handling for Bini.js - works across Node.js, Bun, Deno, Vercel Edge, Netlify Edge, and Cloudflare Workers.

Bini.js uses standard environment variable handling across the client and server. On the client, variables are accessed through import.meta.env. In API routes, they are read from the Hono request context via c.env, ensuring they resolve correctly from the host platform (Node.js, Bun, Deno, Cloudflare, etc.) with no platform-specific code.

Zero config: During development, .env files are loaded automatically. Secrets are available in your API routes via c.env without any extra setup.

Quick Start

Bini.js is configured out of the box. Just start using the environment variables in your routes.

.env
vite.config.ts
src
app
api
ƒhello.ts
/api/hello
vite.config.ts
// vite.config.ts - already configured on scaffold
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // ...your plugins
  ],
})

Read env vars in your Hono handlers

src/app/api/hello.ts
// src/app/api/hello.ts
import { Hono } from 'hono'

const app = new Hono()

app.post('/hello', async (c) => {
  const apiKey = c.env.MY_API_KEY
  const appName = c.env.APP_NAME ?? 'World'

  if (!apiKey) {
    return c.json({ error: 'Missing MY_API_KEY' }, 500)
  }

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

export default app
Your secret just needs to exist in .env with no prefix. In production, set it in your hosting platform's dashboard.

Usage Pattern

Access environment variables directly from the Hono context c.env. This ensures they are request-scoped and correctly resolved for your runtime.

src/app/api/example.ts
// src/app/api/example.ts
import { Hono } from 'hono'

const app = new Hono()

app.post('/example', async (c) => {
  // Required vars: check and throw immediately if missing
  const dbUrl = c.env.DATABASE_URL
  const apiKey = c.env.STRIPE_SECRET_KEY
  if (!dbUrl || !apiKey) {
    return c.json({ error: 'Missing required configuration' }, 500)
  }

  // Optional vars: fall back to sensible defaults
  const model = c.env.AI_MODEL ?? 'gpt-4o'
  const region = c.env.AWS_REGION ?? 'us-east-1'
  const maxRetries = parseInt(c.env.MAX_RETRIES ?? '3')
  const debug = c.env.DEBUG_MODE === 'true'

  return c.json({ model, region, maxRetries, debug })
})

export default app

The pattern in three steps:

src/app/api/pattern.ts
// src/app/api/pattern.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/pattern', (c) => {
  const secret = c.env.KEY        // 1. required: check for missing
  const mode = c.env.MODE ?? 'default' // 2. optional: ?? gives a default

  if (!secret) {
    return c.json({ error: 'Missing KEY' }, 500)
  }

  return c.json({ ok: true, mode })
})

export default app
  • Check c.env.KEY for vars the handler cannot run without.
  • Use c.env.KEY ?? 'default' for optional vars with sensible defaults.
  • An empty value (KEY=) is returned as '', so ?? does not fall back. Check for it explicitly if you rely on a fallback.

Environment Prefixes

Vite loads .env files from your project root. The prefix of each variable decides where it ends up.

.env
.env.local
.env.development
.env.production

BINI_ - Client-side vars

BINI_ variables are exposed to import.meta.env. Use them for public client-side config.

.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL

  return <p>API: {apiUrl}</p>
}

VITE_ - Public client vars

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

.env
# .env
VITE_ANALYTICS_ID=UA-XXXX
src/app/page.tsx
export default function HomePage() {
  const analyticsId = import.meta.env.VITE_ANALYTICS_ID

  return <p>Analytics: {analyticsId}</p>
}

No prefix - Secrets (server only)

Variables without a prefix are NOT exposed to the browser. They are read via c.env in API routes. During dev and preview they are also mirrored into process.env automatically.

.env
# .env
DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...
src/app/api/secrets.ts
// src/app/api/secrets.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/secrets', (c) => {
  const dbUrl = c.env.DATABASE_URL

  if (!dbUrl) {
    return c.json({ error: 'Missing DATABASE_URL' }, 500)
  }

  return c.json({ dbConnected: true })
})

export default app

Prefix Summary

PrefixExposed to browserMirrored to process.env (dev/preview)Use for
BINI_YesYes (unless already set)Public client config
VITE_YesYes (unless already set)Public client config
No prefixNoYes (unless already set)Secrets - server only
Critical: Never put secrets in BINI_* or VITE_* variables - both are exposed to the browser. Use un-prefixed variables for secrets and read them via c.env inside API route handlers only.

API Reference

Accessing variables

On the client, use import.meta.env for public variables. In API routes, use c.env to read from the runtime bindings.

EnvironmentAccess MethodBehavior
Clientimport.meta.env.KEYBundled at build time. Only BINI_ and VITE_ prefixes.
API Routesc.env.KEYRuntime bindings. All variables, including secrets.
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/config', async (c) => {
  const region = c.env.AWS_REGION ?? 'us-east-1'
  const logLevel = c.env.LOG_LEVEL ?? 'info'
  const debug = c.env.DEBUG_MODE === 'true'

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

export default app

Security Best Practices

Rule 1: Never Prefix Secrets

.env
# .env

# BAD - This will be exposed to the browser!
BINI_DATABASE_URL=postgres://...

# GOOD - Not exposed, read via c.env in API routes
DATABASE_URL=postgres://...

Rule 2: Use BINI_ or VITE_ for Public Data

.env
# .env

# GOOD - Public data
BINI_API_URL=https://api.example.com
VITE_GA_ID=UA-XXXXX

Rule 3: Do not Leave Secret Placeholders Empty

An empty value (API_KEY=) is still treated as configured by the runtime, but you should check for it explicitly in your handler to fail fast:

Troubleshooting

ProblemSolution
Env var undefined in productionSet variables in your hosting platform env dashboard (Vercel, Netlify, Cloudflare, etc.).
Works in dev, undefined in prodLocal dev works because .env files are loaded automatically. Production requires platform-level configuration.
c.env is undefinedEnsure you are passing the Hono context c directly to your route handlers.
getEnv returned an empty string instead of my defaultAn empty .env value is returned as '', and ?? only falls back for undefined. Check for it explicitly or remove the empty line.
Cloudflare secret not foundSecrets set via wrangler secret put are only available via c.env. Ensure you are passing c to the function.
Types not foundAdd /// <reference types="vite/client" /> to your tsconfig.json or entry file.

Complete Example

.env
src
app
page.tsx
api
ƒconfig.ts
/
/api/config
.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
VITE_APP_NAME=My App
DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=your_jwt_secret
src/app/page.tsx
// src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL
  const appName = import.meta.env.VITE_APP_NAME
  return <h1>{appName}</h1>
}
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/config', (c) => {
  const dbUrl = c.env.DATABASE_URL
  const jwtSecret = c.env.JWT_SECRET
  const debug = c.env.DEBUG_MODE === 'true'

  if (!dbUrl || !jwtSecret) {
    return c.json({ error: 'Missing required configuration' }, 500)
  }

  return c.json({ debug, dbConnected: true })
})

export default app

Prefixes & Client Exposure

What gets bundled and what stays server-side.

Using in API Routes

Read env vars from Hono handlers.

API Routes Overview

Files under app/api/ map to /api/*.

Deployment

Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.

Was this helpful?
PreviousDynamic API Routes
NextPrefixes & Client Exposure

On this page

  • Quick Start
  • Usage Pattern
  • Environment Prefixes
  • API Reference
  • Security Best Practices
  • Troubleshooting
  • Complete Example
Edit this page on GitHub

Environment Variables

Standard environment variable handling for Bini.js - works across Node.js, Bun, Deno, Vercel Edge, Netlify Edge, and Cloudflare Workers.

Bini.js uses standard environment variable handling across the client and server. On the client, variables are accessed through import.meta.env. In API routes, they are read from the Hono request context via c.env, ensuring they resolve correctly from the host platform (Node.js, Bun, Deno, Cloudflare, etc.) with no platform-specific code.

Zero config: During development, .env files are loaded automatically. Secrets are available in your API routes via c.env without any extra setup.

Quick Start

Bini.js is configured out of the box. Just start using the environment variables in your routes.

.env
vite.config.ts
src
app
api
ƒhello.ts
/api/hello
vite.config.ts
// vite.config.ts - already configured on scaffold
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // ...your plugins
  ],
})

Read env vars in your Hono handlers

src/app/api/hello.ts
// src/app/api/hello.ts
import { Hono } from 'hono'

const app = new Hono()

app.post('/hello', async (c) => {
  const apiKey = c.env.MY_API_KEY
  const appName = c.env.APP_NAME ?? 'World'

  if (!apiKey) {
    return c.json({ error: 'Missing MY_API_KEY' }, 500)
  }

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

export default app
Your secret just needs to exist in .env with no prefix. In production, set it in your hosting platform's dashboard.

Usage Pattern

Access environment variables directly from the Hono context c.env. This ensures they are request-scoped and correctly resolved for your runtime.

src/app/api/example.ts
// src/app/api/example.ts
import { Hono } from 'hono'

const app = new Hono()

app.post('/example', async (c) => {
  // Required vars: check and throw immediately if missing
  const dbUrl = c.env.DATABASE_URL
  const apiKey = c.env.STRIPE_SECRET_KEY
  if (!dbUrl || !apiKey) {
    return c.json({ error: 'Missing required configuration' }, 500)
  }

  // Optional vars: fall back to sensible defaults
  const model = c.env.AI_MODEL ?? 'gpt-4o'
  const region = c.env.AWS_REGION ?? 'us-east-1'
  const maxRetries = parseInt(c.env.MAX_RETRIES ?? '3')
  const debug = c.env.DEBUG_MODE === 'true'

  return c.json({ model, region, maxRetries, debug })
})

export default app

The pattern in three steps:

src/app/api/pattern.ts
// src/app/api/pattern.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/pattern', (c) => {
  const secret = c.env.KEY        // 1. required: check for missing
  const mode = c.env.MODE ?? 'default' // 2. optional: ?? gives a default

  if (!secret) {
    return c.json({ error: 'Missing KEY' }, 500)
  }

  return c.json({ ok: true, mode })
})

export default app
  • Check c.env.KEY for vars the handler cannot run without.
  • Use c.env.KEY ?? 'default' for optional vars with sensible defaults.
  • An empty value (KEY=) is returned as '', so ?? does not fall back. Check for it explicitly if you rely on a fallback.

Environment Prefixes

Vite loads .env files from your project root. The prefix of each variable decides where it ends up.

.env
.env.local
.env.development
.env.production

BINI_ - Client-side vars

BINI_ variables are exposed to import.meta.env. Use them for public client-side config.

.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL

  return <p>API: {apiUrl}</p>
}

VITE_ - Public client vars

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

.env
# .env
VITE_ANALYTICS_ID=UA-XXXX
src/app/page.tsx
export default function HomePage() {
  const analyticsId = import.meta.env.VITE_ANALYTICS_ID

  return <p>Analytics: {analyticsId}</p>
}

No prefix - Secrets (server only)

Variables without a prefix are NOT exposed to the browser. They are read via c.env in API routes. During dev and preview they are also mirrored into process.env automatically.

.env
# .env
DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...
src/app/api/secrets.ts
// src/app/api/secrets.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/secrets', (c) => {
  const dbUrl = c.env.DATABASE_URL

  if (!dbUrl) {
    return c.json({ error: 'Missing DATABASE_URL' }, 500)
  }

  return c.json({ dbConnected: true })
})

export default app

Prefix Summary

PrefixExposed to browserMirrored to process.env (dev/preview)Use for
BINI_YesYes (unless already set)Public client config
VITE_YesYes (unless already set)Public client config
No prefixNoYes (unless already set)Secrets - server only
Critical: Never put secrets in BINI_* or VITE_* variables - both are exposed to the browser. Use un-prefixed variables for secrets and read them via c.env inside API route handlers only.

API Reference

Accessing variables

On the client, use import.meta.env for public variables. In API routes, use c.env to read from the runtime bindings.

EnvironmentAccess MethodBehavior
Clientimport.meta.env.KEYBundled at build time. Only BINI_ and VITE_ prefixes.
API Routesc.env.KEYRuntime bindings. All variables, including secrets.
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/config', async (c) => {
  const region = c.env.AWS_REGION ?? 'us-east-1'
  const logLevel = c.env.LOG_LEVEL ?? 'info'
  const debug = c.env.DEBUG_MODE === 'true'

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

export default app

Security Best Practices

Rule 1: Never Prefix Secrets

.env
# .env

# BAD - This will be exposed to the browser!
BINI_DATABASE_URL=postgres://...

# GOOD - Not exposed, read via c.env in API routes
DATABASE_URL=postgres://...

Rule 2: Use BINI_ or VITE_ for Public Data

.env
# .env

# GOOD - Public data
BINI_API_URL=https://api.example.com
VITE_GA_ID=UA-XXXXX

Rule 3: Do not Leave Secret Placeholders Empty

An empty value (API_KEY=) is still treated as configured by the runtime, but you should check for it explicitly in your handler to fail fast:

Troubleshooting

ProblemSolution
Env var undefined in productionSet variables in your hosting platform env dashboard (Vercel, Netlify, Cloudflare, etc.).
Works in dev, undefined in prodLocal dev works because .env files are loaded automatically. Production requires platform-level configuration.
c.env is undefinedEnsure you are passing the Hono context c directly to your route handlers.
getEnv returned an empty string instead of my defaultAn empty .env value is returned as '', and ?? only falls back for undefined. Check for it explicitly or remove the empty line.
Cloudflare secret not foundSecrets set via wrangler secret put are only available via c.env. Ensure you are passing c to the function.
Types not foundAdd /// <reference types="vite/client" /> to your tsconfig.json or entry file.

Complete Example

.env
src
app
page.tsx
api
ƒconfig.ts
/
/api/config
.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
VITE_APP_NAME=My App
DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=your_jwt_secret
src/app/page.tsx
// src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL
  const appName = import.meta.env.VITE_APP_NAME
  return <h1>{appName}</h1>
}
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/config', (c) => {
  const dbUrl = c.env.DATABASE_URL
  const jwtSecret = c.env.JWT_SECRET
  const debug = c.env.DEBUG_MODE === 'true'

  if (!dbUrl || !jwtSecret) {
    return c.json({ error: 'Missing required configuration' }, 500)
  }

  return c.json({ debug, dbConnected: true })
})

export default app

Prefixes & Client Exposure

What gets bundled and what stays server-side.

Using in API Routes

Read env vars from Hono handlers.

API Routes Overview

Files under app/api/ map to /api/*.

Deployment

Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.

Was this helpful?
PreviousDynamic API Routes
NextPrefixes & Client Exposure

On this page

  • Quick Start
  • Usage Pattern
  • Environment Prefixes
  • API Reference
  • Security Best Practices
  • Troubleshooting
  • Complete Example
Edit this page on GitHub