feat: build-time substitution for import.meta.env.STX_PUBLIC_* in client bundles

Mirrors the server-side `$env` template context onto the client. Any env var
matching the configured prefix (default `STX_PUBLIC_`) is now inlined as
`import.meta.env.<KEY>` at build time across every client-bundling path:

  - inline-assets.ts        (Bun.build for <script src=...>)
  - client-script-bundler.ts (Bun.build for <script client> with imports)
  - utils.ts                 (Bun.Transpiler for inline <script client>)
  - store-loader.ts          (Bun.Transpiler for resources/stores/*.ts)
  - variable-extractor.ts    (Bun.Transpiler for <script> introspection)

  .env:    STX_PUBLIC_API_URL=https://api.example.com
  store:   const api = import.meta.env.STX_PUBLIC_API_URL
  built:   const api = "https://api.example.com"

Vite-compatible. Build-time replacement, zero runtime cost, dead-branch
tree-shaking works (`if (import.meta.env.X) { ... }` prunes when X is "").

Stores and any other plain `.ts` files now get the same env story as
templates without per-app `window.X` injection boilerplate.

New module `packages/stx/src/public-env.ts` exports `getPublicEnvDefine()`
and `getPublicEnv()` for any consumer that needs the same substitution map.
Both are re-exported from the package barrel.

Author: glennmichael123

packages/stx/src/client-script-bundler.ts

@@ -12,6 +12,7 @@
 import path from 'node:path'
 import fs from 'node:fs' // kept for mkdir/rmSync (no Bun equivalent for dir ops)
 import type { BunPlugin } from 'bun'
+import { getPublicEnvDefine } from './public-env'
 
 // Known imports that are NOT user imports — handled by other transforms
 const EXTERNAL_PATTERNS = [
@@ -194,6 +195,7 @@ export async function bundleClientScript(
       plugins: [createBundlePlugin(projectRoot)],
       define: {
         'process.env.NODE_ENV': minify ? '"production"' : '"development"',
+        ...getPublicEnvDefine(),
       },
       // Resolve relative imports from the template's directory
       root: templateDir,

packages/stx/src/index.ts

@@ -27,6 +27,7 @@ export * from './forms'
 
 // Core modules
 export * from './env'
+export { getPublicEnv, getPublicEnvDefine } from './public-env'
 export * from './a11y'
 export * from './analytics'
 export * from './analyzer'

packages/stx/src/inline-assets.ts

@@ -6,6 +6,7 @@
  * replacing them with inline <script> and <style> blocks.
  */
 import path from 'node:path'
+import { getPublicEnvDefine } from './public-env'
 
 /**
  * Check if a URL is external (http, https, or protocol-relative)
@@ -109,6 +110,7 @@ export async function processInlineAssets(
             entrypoints: [resolvedPath],
             target: 'browser',
             minify: false,
+            define: getPublicEnvDefine(),
           })
           if (result.outputs.length > 0) {
             fileContent = await result.outputs[0].text()

packages/stx/src/public-env.ts

@@ -0,0 +1,56 @@
+/**
+ * Public env exposure for client bundles
+ *
+ * Mirrors the server-side `$env` template context (process.ts:762) onto the
+ * client side via build-time substitution. Any env var matching `envPrefix`
+ * (default `STX_PUBLIC_`) gets inlined as `import.meta.env.STX_PUBLIC_*` in
+ * scripts bundled for the browser.
+ *
+ *   .env:    STX_PUBLIC_API_URL=https://api.example.com
+ *   store:   const api = import.meta.env.STX_PUBLIC_API_URL
+ *   built:   const api = "https://api.example.com"
+ *
+ * Vite-style. Build-time, zero runtime cost.
+ */
+
+import process from 'node:process'
+
+/**
+ * Build the `define` map every client bundler/transpiler should pass to
+ * Bun.build / new Bun.Transpiler({ define }).
+ *
+ * Returns substitutions for both `import.meta.env.<KEY>` (preferred, Vite-
+ * compatible) and a single `import.meta.env` literal that maps to the full
+ * object so consumers can do `if (import.meta.env.X)` and similar idiomatic
+ * patterns.
+ */
+export function getPublicEnvDefine(envPrefix: string = 'STX_PUBLIC_'): Record<string, string> {
+  const define: Record<string, string> = {}
+  const envObject: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith(envPrefix) || value === undefined)
+      continue
+    define[`import.meta.env.${key}`] = JSON.stringify(value)
+    envObject[key] = value
+  }
+
+  // Whole-object substitution lets `Object.keys(import.meta.env)` and similar
+  // dynamic patterns work, not just direct key access.
+  define['import.meta.env'] = JSON.stringify(envObject)
+
+  return define
+}
+
+/**
+ * Get the public env values as a plain object. Useful for places that want
+ * the raw map (e.g. tests, debugging) rather than the define-shaped strings.
+ */
+export function getPublicEnv(envPrefix: string = 'STX_PUBLIC_'): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(envPrefix) && value !== undefined)
+      out[key] = value
+  }
+  return out
+}

packages/stx/src/store-loader.ts

@@ -11,6 +11,7 @@
 
 import path from 'node:path'
 import { loadStxConfig } from './config'
+import { getPublicEnvDefine } from './public-env'
 
 const _cachedStoreScripts = new Map<string, string>()
 
@@ -88,7 +89,7 @@ export async function getStoreScript(storesDir?: string): Promise<string | null>
   // but in the browser these are already globals — just strip the imports.
   const chunks: string[] = []
 
-  const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'browser' })
+  const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'browser', define: getPublicEnvDefine() })
 
   for (const file of sortedFiles) {
     try {

packages/stx/src/utils.ts

@@ -21,6 +21,7 @@ import { unescapeHtml } from './expressions'
 import { transformStoreImports } from './store-imports'
 import { LRUCache } from './performance-utils'
 import { processDirectives } from './process'
+import { getPublicEnvDefine } from './public-env'
 import { processScopedStyles } from './style-scoping'
 
 // Re-export from extracted modules for backward compatibility
@@ -109,6 +110,7 @@ export function transpileTypeScript(code: string): string {
     const transpiler = new Bun.Transpiler({
       loader: 'ts',
       target: 'browser',
+      define: getPublicEnvDefine(),
     })
     let result = transpiler.transformSync(processedCode)
 

packages/stx/src/variable-extractor.ts

@@ -36,6 +36,7 @@ import { findMatchingDelimiter } from './parser/tokenizer'
 // instance that document-shell.ts reads from. Using require() inside the
 // wrapped useHead would create a separate module instance with its own state.
 import { useHead as headUseHead, useSeoMeta as headUseSeoMeta, getHead as headGetHead } from './head'
+import { getPublicEnvDefine } from './public-env'
 
 /**
  * Extract declared variable names from converted CommonJS script.
@@ -324,7 +325,7 @@ export async function extractVariables(
   // Strip TypeScript syntax using Bun.Transpiler for full TS support
   let jsContent: string
   try {
-    const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'browser' })
+    const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'browser', define: getPublicEnvDefine() })
     // Strip .stx component imports before transpiling
     let processedCode = scriptContent.replace(/^\s*import\s+\w+\s+from\s+['"][^'"]*\.stx['"]\s*;?\s*$/gm, '')
     processedCode = processedCode.replace(/^\s*import\s+['"][^'"]*\.stx['"]\s*;?\s*$/gm, '')