Runtime Helpers and stable imports

A Runtime Helper is a runtime API used by application code to call, inspect, or use a configured ViteHub primitive. Stable ViteHub import paths keep application code independent from Provider Output, virtual modules, and generated file locations.

Why it exists

Generated output changes with provider, host, package options, and deployment target. Server code should not need those details to call KV, read a Workspace, run an Agent, or access Server Env.

Stable imports also make docs and agent instructions actionable. An agent can search for one documented import instead of guessing provider-specific modules.

Examples

Use a package Runtime Helper from server code.

import { kv } from '@vite-hub/kv'

export default defineEventHandler(async () => {
  return {
    settings: await kv.get('settings'),
  }
})

Use a generated stable import only when the package documents it.

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

export function getGithubToken() {
  return useServerEnv().github.token.unseal()
}

Run an Agent through the Agent Package instead of calling generated route code.

import { runAgent } from '@vite-hub/agent'
import support from '../agents/support'

export default defineEventHandler(async (event) => {
  return runAgent(support, { runtime: 'vite' }, await readBody(event))
})

When to use what

Inspect it

Search for imports from @vite-hub/*, @vite-hub/*/vite, and documented #vitehub/... paths. Those imports show where the public boundary is.

Next steps

• Read Vite Integrations and Provider Output.
• Try First server primitive.
• Open Env for a generated stable import example.