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.

Prefixes & Client Exposure

Learn how environment variable prefixes work and which variables are exposed to the client.

What are Prefixes?

Environment variable prefixes determine which variables are exposed to the browser and which are kept server-side. The prefix tells Vite and Bini.js how to handle each variable.

.env
.env.local
.env.development
.env.production
PrefixExposed to browserRead withUse for
BINI_Yesimport.meta.envPublic client config
VITE_Yesimport.meta.envPublic client config
No prefixNogetEnv / requireEnvSecrets - server only
Both BINI_ and VITE_ prefixes are exposed to the browser by default. Variables without a prefix are never exposed to the client.

BINI_ Prefix

BINI_ is the default prefix for client-side environment variables in Bini.js. These variables are exposed to the browser via import.meta.env.

.env
src
app
page.tsx
/
.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
BINI_APP_NAME=My App
BINI_ANALYTICS_ID=UA-XXXX
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL
  const appName = import.meta.env.BINI_APP_NAME
  const analyticsId = import.meta.env.BINI_ANALYTICS_ID

  return (
    <div>
      <h1>{appName}</h1>
      <p>API: {apiUrl}</p>
      <p>Analytics: {analyticsId}</p>
    </div>
  )
}
Important: BINI_* variables are bundled into your client-side JavaScript. Never put secrets in BINI_* variables.

VITE_ Prefix

VITE_ is Vite's standard prefix for client-side environment variables. Any variable starting with VITE_ is exposed to the browser.

.env
# .env
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App
VITE_GA_ID=UA-XXXXX
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.VITE_API_URL
  const title = import.meta.env.VITE_APP_TITLE
  const gaId = import.meta.env.VITE_GA_ID

  return (
    <div>
      <h1>{title}</h1>
      <p>API: {apiUrl}</p>
      <p>Analytics: {gaId}</p>
    </div>
  )
}
Note: VITE_* and BINI_* work the same way. Both are exposed to the browser. Choose whichever you prefer.

No Prefix (Secrets)

Variables without a prefix are never exposed to the browser. They are only accessible server-side via getEnv(c, key) in API routes.

.env
src
app
api
ƒconfig.ts
/api/config
.env
# .env
DATABASE_URL=postgres://localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_...
SMTP_PASS=super_secret
JWT_SECRET=your_jwt_secret
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'
import { requireEnv } from 'bini-env'

const app = new Hono()

app.get('/config', (c) => {
  // These are only accessible server-side
  const dbUrl = requireEnv(c, 'DATABASE_URL')
  const jwtSecret = requireEnv(c, 'JWT_SECRET')
  const smtpPass = requireEnv(c, 'SMTP_PASS')

  // Never expose secrets in responses
  return c.json({
    dbConnected: !!dbUrl,
    jwtConfigured: !!jwtSecret,
    smtpConfigured: !!smtpPass,
  })
})

export default app
Critical: Variables without a prefix are the only way to keep secrets secure. Never use BINI_* or VITE_* for sensitive data.

Client-Side Access

Client-side variables are accessed via import.meta.env in any component:

src/app/page.tsx
export default function Page() {
  // Access client-side variables
  const apiUrl = import.meta.env.BINI_API_URL
  const appName = import.meta.env.VITE_APP_NAME

  return (
    <div>
      <h1>{appName}</h1>
      <p>API: {apiUrl}</p>
    </div>
  )
}

The same works in MDX files:

src/app/about/page.mdx
export const metadata = {
  title: import.meta.env.VITE_APP_NAME,
}

# Welcome to {import.meta.env.VITE_APP_NAME}
import.meta.env is available in all client-side code including pages, components, and MDX files.

Server-Side Access

Server-side variables are accessed via getEnv(c, key) and requireEnv(c, key) in API routes:

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

const app = new Hono()

app.post('/email/send', async (c) => {
  // Server-side secrets (no prefix)
  const smtpHost = requireEnv(c, 'SMTP_HOST')
  const smtpPass = requireEnv(c, 'SMTP_PASS')
  const fromEmail = requireEnv(c, 'FROM_EMAIL')

  // Optional config with defaults
  const smtpPort = parseInt(getEnv(c, 'SMTP_PORT') ?? '587')

  // Client-side config (BINI_)
  const publicUrl = getEnv(c, 'BINI_API_URL')

  return c.json({
    success: true,
    publicUrl, // This is safe to return
    // smtpPass is NEVER returned to the client
  })
})

export default app
Access MethodWhereVariables
import.meta.envClient componentsBINI_, VITE_
getEnv(c, key)API routesAll variables (including no prefix)
requireEnv(c, key)API routesAll variables (throws if missing)

getEnv vs requireEnv

Both getEnv and requireEnv read environment variables from the Hono request context, but they behave differently:

FeaturegetEnv(c, key)requireEnv(c, key)
Returnsstring | undefinedstring
On missingReturns undefinedThrows error immediately
Use caseOptional configuration with defaultsRequired configuration
Default patterngetEnv(c, 'KEY') ?? 'default'requireEnv(c, 'KEY')
Error handlingManual check for undefinedTry/catch or let it bubble
When to useFeature flags, optional settingsDatabase URLs, API keys, credentials
src/app/api/compare.ts
// src/app/api/compare.ts
import { Hono } from 'hono'
import { getEnv, requireEnv } from 'bini-env'

const app = new Hono()

app.get('/compare', (c) => {
  // getEnv - for optional values
  const debug = getEnv(c, 'DEBUG_MODE') === 'true'
  const region = getEnv(c, 'AWS_REGION') ?? 'us-east-1'
  const maxRetries = parseInt(getEnv(c, 'MAX_RETRIES') ?? '3')

  // requireEnv - for required values
  const dbUrl = requireEnv(c, 'DATABASE_URL')
  const apiKey = requireEnv(c, 'STRIPE_SECRET_KEY')
  const smtpPass = requireEnv(c, 'SMTP_PASS')

  return c.json({ debug, region, maxRetries, ready: !!(dbUrl && apiKey && smtpPass) })
})

export default app
Best practice: Use requireEnv for critical configuration that your app cannot function without. Use getEnv with ?? defaults for optional configuration.

On failure, requireEnv throws with a descriptive message that is safe to catch and return to the caller:

src/app/api/safe.ts
try {
  const smtpHost = requireEnv(c, 'SMTP_HOST')
  // ...
} 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)
}

Security Best Practices

  • Never prefix secrets - Use no prefix for database URLs, API keys, and tokens.
  • Use BINI_ or VITE_ for public config - Use these for non-sensitive configuration like API URLs.
  • Use requireEnv for critical values - Fail fast when required configuration is missing.
  • Use getEnv with defaults for optional values - Keep your app flexible with sensible defaults.
  • Never expose secrets in responses - Do not return secret values from API routes.
  • Use .env.example - Document required variables without committing actual values.
  • Keep .env in .gitignore - Never commit environment files with secrets.

.env.example

.env.example
# .env.example - commit this file, never your real .env

# Public (exposed to the browser)
BINI_PUBLIC_API_URL=
VITE_APP_NAME=

# Secrets (server only)
DATABASE_URL=
JWT_SECRET=

.gitignore

.gitignore
# .gitignore
.env
.env.local
.env.*.local

Environment Variables

Read secrets with getEnv and requireEnv.

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?
PreviousEnvironment Variables
NextUsing in API Routes

On this page

  • What are Prefixes?
  • BINI_ Prefix
  • VITE_ Prefix
  • No Prefix (Secrets)
  • Client-Side Access
  • Server-Side Access
  • getEnv vs requireEnv
  • Security Best Practices
Edit this page on GitHub

Prefixes & Client Exposure

Learn how environment variable prefixes work and which variables are exposed to the client.

What are Prefixes?

Environment variable prefixes determine which variables are exposed to the browser and which are kept server-side. The prefix tells Vite and Bini.js how to handle each variable.

.env
.env.local
.env.development
.env.production
PrefixExposed to browserRead withUse for
BINI_Yesimport.meta.envPublic client config
VITE_Yesimport.meta.envPublic client config
No prefixNogetEnv / requireEnvSecrets - server only
Both BINI_ and VITE_ prefixes are exposed to the browser by default. Variables without a prefix are never exposed to the client.

BINI_ Prefix

BINI_ is the default prefix for client-side environment variables in Bini.js. These variables are exposed to the browser via import.meta.env.

.env
src
app
page.tsx
/
.env
# .env
BINI_PUBLIC_API_URL=https://api.example.com
BINI_APP_NAME=My App
BINI_ANALYTICS_ID=UA-XXXX
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.BINI_PUBLIC_API_URL
  const appName = import.meta.env.BINI_APP_NAME
  const analyticsId = import.meta.env.BINI_ANALYTICS_ID

  return (
    <div>
      <h1>{appName}</h1>
      <p>API: {apiUrl}</p>
      <p>Analytics: {analyticsId}</p>
    </div>
  )
}
Important: BINI_* variables are bundled into your client-side JavaScript. Never put secrets in BINI_* variables.

VITE_ Prefix

VITE_ is Vite's standard prefix for client-side environment variables. Any variable starting with VITE_ is exposed to the browser.

.env
# .env
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App
VITE_GA_ID=UA-XXXXX
src/app/page.tsx
export default function HomePage() {
  const apiUrl = import.meta.env.VITE_API_URL
  const title = import.meta.env.VITE_APP_TITLE
  const gaId = import.meta.env.VITE_GA_ID

  return (
    <div>
      <h1>{title}</h1>
      <p>API: {apiUrl}</p>
      <p>Analytics: {gaId}</p>
    </div>
  )
}
Note: VITE_* and BINI_* work the same way. Both are exposed to the browser. Choose whichever you prefer.

No Prefix (Secrets)

Variables without a prefix are never exposed to the browser. They are only accessible server-side via getEnv(c, key) in API routes.

.env
src
app
api
ƒconfig.ts
/api/config
.env
# .env
DATABASE_URL=postgres://localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_...
SMTP_PASS=super_secret
JWT_SECRET=your_jwt_secret
src/app/api/config.ts
// src/app/api/config.ts
import { Hono } from 'hono'
import { requireEnv } from 'bini-env'

const app = new Hono()

app.get('/config', (c) => {
  // These are only accessible server-side
  const dbUrl = requireEnv(c, 'DATABASE_URL')
  const jwtSecret = requireEnv(c, 'JWT_SECRET')
  const smtpPass = requireEnv(c, 'SMTP_PASS')

  // Never expose secrets in responses
  return c.json({
    dbConnected: !!dbUrl,
    jwtConfigured: !!jwtSecret,
    smtpConfigured: !!smtpPass,
  })
})

export default app
Critical: Variables without a prefix are the only way to keep secrets secure. Never use BINI_* or VITE_* for sensitive data.

Client-Side Access

Client-side variables are accessed via import.meta.env in any component:

src/app/page.tsx
export default function Page() {
  // Access client-side variables
  const apiUrl = import.meta.env.BINI_API_URL
  const appName = import.meta.env.VITE_APP_NAME

  return (
    <div>
      <h1>{appName}</h1>
      <p>API: {apiUrl}</p>
    </div>
  )
}

The same works in MDX files:

src/app/about/page.mdx
export const metadata = {
  title: import.meta.env.VITE_APP_NAME,
}

# Welcome to {import.meta.env.VITE_APP_NAME}
import.meta.env is available in all client-side code including pages, components, and MDX files.

Server-Side Access

Server-side variables are accessed via getEnv(c, key) and requireEnv(c, key) in API routes:

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

const app = new Hono()

app.post('/email/send', async (c) => {
  // Server-side secrets (no prefix)
  const smtpHost = requireEnv(c, 'SMTP_HOST')
  const smtpPass = requireEnv(c, 'SMTP_PASS')
  const fromEmail = requireEnv(c, 'FROM_EMAIL')

  // Optional config with defaults
  const smtpPort = parseInt(getEnv(c, 'SMTP_PORT') ?? '587')

  // Client-side config (BINI_)
  const publicUrl = getEnv(c, 'BINI_API_URL')

  return c.json({
    success: true,
    publicUrl, // This is safe to return
    // smtpPass is NEVER returned to the client
  })
})

export default app
Access MethodWhereVariables
import.meta.envClient componentsBINI_, VITE_
getEnv(c, key)API routesAll variables (including no prefix)
requireEnv(c, key)API routesAll variables (throws if missing)

getEnv vs requireEnv

Both getEnv and requireEnv read environment variables from the Hono request context, but they behave differently:

FeaturegetEnv(c, key)requireEnv(c, key)
Returnsstring | undefinedstring
On missingReturns undefinedThrows error immediately
Use caseOptional configuration with defaultsRequired configuration
Default patterngetEnv(c, 'KEY') ?? 'default'requireEnv(c, 'KEY')
Error handlingManual check for undefinedTry/catch or let it bubble
When to useFeature flags, optional settingsDatabase URLs, API keys, credentials
src/app/api/compare.ts
// src/app/api/compare.ts
import { Hono } from 'hono'
import { getEnv, requireEnv } from 'bini-env'

const app = new Hono()

app.get('/compare', (c) => {
  // getEnv - for optional values
  const debug = getEnv(c, 'DEBUG_MODE') === 'true'
  const region = getEnv(c, 'AWS_REGION') ?? 'us-east-1'
  const maxRetries = parseInt(getEnv(c, 'MAX_RETRIES') ?? '3')

  // requireEnv - for required values
  const dbUrl = requireEnv(c, 'DATABASE_URL')
  const apiKey = requireEnv(c, 'STRIPE_SECRET_KEY')
  const smtpPass = requireEnv(c, 'SMTP_PASS')

  return c.json({ debug, region, maxRetries, ready: !!(dbUrl && apiKey && smtpPass) })
})

export default app
Best practice: Use requireEnv for critical configuration that your app cannot function without. Use getEnv with ?? defaults for optional configuration.

On failure, requireEnv throws with a descriptive message that is safe to catch and return to the caller:

src/app/api/safe.ts
try {
  const smtpHost = requireEnv(c, 'SMTP_HOST')
  // ...
} 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)
}

Security Best Practices

  • Never prefix secrets - Use no prefix for database URLs, API keys, and tokens.
  • Use BINI_ or VITE_ for public config - Use these for non-sensitive configuration like API URLs.
  • Use requireEnv for critical values - Fail fast when required configuration is missing.
  • Use getEnv with defaults for optional values - Keep your app flexible with sensible defaults.
  • Never expose secrets in responses - Do not return secret values from API routes.
  • Use .env.example - Document required variables without committing actual values.
  • Keep .env in .gitignore - Never commit environment files with secrets.

.env.example

.env.example
# .env.example - commit this file, never your real .env

# Public (exposed to the browser)
BINI_PUBLIC_API_URL=
VITE_APP_NAME=

# Secrets (server only)
DATABASE_URL=
JWT_SECRET=

.gitignore

.gitignore
# .gitignore
.env
.env.local
.env.*.local

Environment Variables

Read secrets with getEnv and requireEnv.

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?
PreviousEnvironment Variables
NextUsing in API Routes

On this page

  • What are Prefixes?
  • BINI_ Prefix
  • VITE_ Prefix
  • No Prefix (Secrets)
  • Client-Side Access
  • Server-Side Access
  • getEnv vs requireEnv
  • Security Best Practices
Edit this page on GitHub