@instra/vite-plugin-instra (PoC)

Customer-installed Vite plugin for serve-time public env vars.

It rewrites direct reads of:

• import.meta.env.INSTRA_PUBLIC_*
• process.env.INSTRA_PUBLIC_*

into:

• __instraEnv.INSTRA_PUBLIC_*

…and injects (once per transformed module):

import __instraEnv from "instra-envs";

The specifier instra-envs is resolved to the runtime module path /.instra/env.mjs (same-origin).

Build/preview without the Worker

To keep builds self-contained, the plugin emits a static fallback env module into the build output at:

• dist/.instra/env.mjs (derived from runtimePath)

This fallback is generated from .env files via Vite loadEnv() and includes only the INSTRA_PUBLIC_* keys that were actually rewritten in your source.

At runtime on the Instra platform, the multi-tenant edge Worker overrides GET /.instra/env.mjs to return per-tenant values.

Install

pnpm add -D @instra/vite-plugin-instra

Usage

// vite.config.ts
import { defineConfig } from "vite";
import { instraEnvPlugin } from "@instra/vite-plugin-instra";

export default defineConfig({
  plugins: [instraEnvPlugin()]
});

Supported patterns (PoC)

✅ Supported (direct member access only):

• import.meta.env.INSTRA_PUBLIC_API_URL
• process.env.INSTRA_PUBLIC_FLAG

❌ Not supported yet (documented limitation):

• Bracket access: import.meta.env["INSTRA_PUBLIC_X"], process.env["INSTRA_PUBLIC_X"]
• Destructuring: const { INSTRA_PUBLIC_X } = import.meta.env / process.env
• Indirect access: const env = import.meta.env; env.INSTRA_PUBLIC_X

Runtime requirement

Your app must be served behind the Instra gateway Worker which serves:

• GET /.instra/env.mjs

…on the same hostname as the app.

Options

instraEnvPlugin({
  prefix: "INSTRA_PUBLIC_",          // default
  moduleId: "instra-envs",           // default
  runtimePath: "/.instra/env.mjs"     // default
  emitStaticFallback: true,           // default
  devMiddleware: true                // default
})