Env

Use Env to declare browser-safe values, build replacements, server-only values, and secrets without mixing their access rules. ViteHub generates typed imports for browser and server code and redacts Secret Env values by default.

Your host still stores and supplies secrets. Server code calls unseal() only where it needs the raw value.

Quick start

pnpm add @vite-hub/env @vite-hub/runtime

import { env, hubEnv } from '@vite-hub/env/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubEnv()],
  env: {
    public: {
      appName: env({ default: 'Acme' }),
    },
  },
})

import { usePublicEnv } from '#vitehub/env/public'

const publicEnv = usePublicEnv()
console.log(publicEnv.appName)

Public imports

Configure Env

Add hubEnv() and declare values in the Vite config. env.public becomes browser-safe Public Env, env.define becomes Vite replacements, and env.server becomes Server Env for server runtime code.

import { env, hubEnv } from '@vite-hub/env/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubEnv()],
  env: {
    public: {
      appName: env({ default: 'Acme' }),
    },
    define: {
      __BUILD_TARGET__: env({ default: 'preview' }),
    },
    server: {
      github: {
        token: env({ secret: true, source: env.source('GITHUB_TOKEN') }),
      },
    },
  },
})

Integration options

Pass Integration Options to hubEnv().

Env config sections

Env Declaration options

env() and env.variable() accept the same options.

Env sources

Use it at runtime

Use Public Env from browser-safe code. The import path stays stable even though ViteHub generates the backing module.

import { usePublicEnv } from '#vitehub/env/public'

export const appName = usePublicEnv().appName

Use Server Env from server-only code. Secret Env values redact by default and require unseal() before a third-party SDK or request can receive the underlying string.

import { useServerEnv } from '#vitehub/env/server'

export async function listIssues() {
  const { github } = useServerEnv()

  return fetch('https://api.github.com/issues', {
    headers: {
      authorization: `Bearer ${github.token.unseal()}`,
    },
  })
}

Structured errors

Env resolution failures use ViteHubError with closed, stable codes and JSON-safe context. The codes distinguish invalid declarations, missing required values, invalid runtime values, and failed built-in sources. Custom source resolvers keep application-owned errors unchanged.

import { getViteHubErrorShape } from '@vite-hub/runtime'

try {
  await resolveEnv()
}
catch (error) {
  const shape = getViteHubErrorShape(error)
  if (shape?.code === 'ENV_SOURCE_FAILED') {
    console.error('Env source failed', shape.details?.source)
  }
  throw error
}

Each code owns a fixed public message and bounded details. Source details use identifiers such as git:branch, package.json, env, or custom; raw variable names, package paths, labels, and provider diagnostics remain behind cause. error.toJSON() includes code, message, and details; it omits cause, which remains available only on the in-memory error. Invalid calls to declaration helpers remain TypeError, while parseSchema() continues to throw ordinary schema errors.

Provider output

hubEnv() writes generated env modules under .vitehub/env/ and ambient types under .vitehub/types/. Import #vitehub/env/public and #vitehub/env/server from application code, not generated file paths or integration virtual modules.

Add the generated type directory to tsconfig.json when the app wants field-level types for generated Env access.

{
  "include": [
    "src/**/*.ts",
    "server/**/*.ts",
    ".vitehub/types/**/*.d.ts"
  ]
}

Use Env with Agents

Read application secrets through Server Env inside Agent and Capability callbacks. Don't pass secrets through Agent Invocation metadata or model-facing instructions.

Env is usually not an agent-facing Capability. Other Capabilities consume Server Env when they need credentials, provider tokens, or app-owned configuration.

Production checks

Public Env and Vite define values are visible to built client code. Put secrets only in Server Env with secret: true.

Secret Env provides type friction and default redaction, but it is not a complete leak-prevention system. Unseal secrets as late as possible and avoid returning them in responses, logs, traces, or Agent output.

Next steps

• Learn the server primitive model in Server primitives for any host.
• Use Env with Auth when Auth runtime options need secrets.
• Expose agent abilities through Official capabilities without making secrets model-facing.