;
function resetStaticReplacements() {
staticReplacements = {};
+ dynamicPublicKeys = [];
for (const itemKey in varlockLoadedEnv?.config) {
const itemInfo = varlockLoadedEnv.config[itemKey];
- // TODO: probably reimplement static/dynamic controls here too
- if (!itemInfo.isSensitive) {
+ const isDynamic = itemInfo.isDynamic ?? itemInfo.isSensitive;
+ if (isDynamic && !itemInfo.isSensitive) {
+ dynamicPublicKeys.push(itemKey);
+ }
+ if (!isDynamic) {
// we have to pass in a string of 'undefined' so it gets replaced properly
const val = itemInfo.value === undefined ? 'undefined' : JSON.stringify(itemInfo.value);
staticReplacements[`ENV.${itemKey}`] = val;
}
}
+ (globalThis as any).__varlockDynamicPublicKeys = dynamicPublicKeys;
debug('static replacements', staticReplacements);
@@ -165,6 +171,7 @@ export function varlockVitePlugin(
'// Virtual module generated by @varlock/vite-integration',
'// Runs before any user code to ensure ENV is available at module top-level',
'globalThis.__varlockThrowOnMissingKeys = true;',
+ `globalThis.__varlockDynamicPublicKeys = ${JSON.stringify(dynamicPublicKeys)};`,
];
const encryptionRequired = varlockLoadedEnv?.settings?.encryptInjectedEnv;
@@ -267,6 +274,11 @@ See https://varlock.dev/integrations/vite/ for more details.
}
isDevCommand = env.command === 'serve';
+ if (env.command === 'build') {
+ process.env._VARLOCK_EXECUTION_PHASE = 'build';
+ } else {
+ delete process.env._VARLOCK_EXECUTION_PHASE;
+ }
// Determine the project root for the current Vite/Vitest project.
// In monorepo setups with Vitest workspace projects, config.root
@@ -392,6 +404,9 @@ See https://varlock.dev/integrations/vite/ for more details.
`globalThis.__varlockValidKeys = ${JSON.stringify(Object.keys(varlockLoadedEnv?.config || {}))};`,
);
}
+ injectCode.push(
+ `globalThis.__varlockDynamicPublicKeys = ${JSON.stringify(dynamicPublicKeys)};`,
+ );
}
injectCode.push('// -------- ');
@@ -437,8 +452,8 @@ See https://varlock.dev/integrations/vite/ for more details.
(_fullMatch, itemKey) => {
if (!varlockLoadedEnv.config[itemKey]) {
throw new Error(`Config item \`${itemKey}\` does not exist`);
- } else if (varlockLoadedEnv.config[itemKey].isSensitive) {
- throw new Error(`Config item \`${itemKey}\` is sensitive and cannot be used in html replacements`);
+ } else if ((varlockLoadedEnv.config[itemKey].isDynamic ?? varlockLoadedEnv.config[itemKey].isSensitive)) {
+ throw new Error(`Config item \`${itemKey}\` is dynamic and cannot be used in html replacements`);
} else {
// undefined will be turned into empty string in html replacements
return varlockLoadedEnv.config[itemKey].value ?? '';
diff --git a/packages/varlock-website/src/content/docs/guides/dynamic-config.mdx b/packages/varlock-website/src/content/docs/guides/dynamic-config.mdx
new file mode 100644
index 000000000..f7acfde42
--- /dev/null
+++ b/packages/varlock-website/src/content/docs/guides/dynamic-config.mdx
@@ -0,0 +1,94 @@
+---
+title: Static vs Dynamic Config
+description: How to control build-time replacement vs runtime resolution, and how to use dynamic+public values safely
+---
+
+Varlock separates two concerns:
+
+- **sensitive vs public**: security boundary (can this be exposed to clients?)
+- **static vs dynamic**: execution-time boundary (can this be replaced at build time?)
+
+These are related, but not the same.
+
+## Defaults and decorators
+
+By default, static/dynamic behavior follows sensitivity:
+
+```env-spec title=".env.schema"
+# @defaultDynamic=sensitive
+# ---
+PUBLIC_FOO= # static by default
+# @sensitive
+SECRET_BAR= # dynamic by default
+```
+
+Override per item with:
+- [`@dynamic`](/reference/item-decorators/#dynamic)
+- [`@static`](/reference/item-decorators/#static)
+
+Or override globally with [`@defaultDynamic`](/reference/root-decorators/#defaultdynamic):
+- `sensitive` (default)
+- `true` (all dynamic unless overridden)
+- `false` (all static unless overridden)
+
+## Typical patterns
+
+- `static + public` (most common): safe to inline in client bundles
+- `dynamic + sensitive` (most common): runtime-only secrets
+- `dynamic + public` (valid): runtime feature flags, environment banners, etc.
+- `static + sensitive` (rare, use with care): server-only build-time replacement
+
+## Runtime helpers for dynamic+public
+
+When public values are dynamic, the client must load them at runtime:
+
+- `getPublicDynamicEnv(keys?)` — server-side helper for endpoint payloads
+- `loadPublicDynamicEnv(opts?)` — client-side fetch + hydrate helper
+- `ENV.MY_VAR` — keep using the same access pattern after hydration
+
+Example:
+
+```ts title="server endpoint"
+import { getPublicDynamicEnv } from 'varlock/env';
+
+export function GET() {
+ return Response.json(getPublicDynamicEnv(), {
+ headers: { 'cache-control': 'no-store' },
+ });
+}
+```
+
+```ts title="client code"
+import { ENV, loadPublicDynamicEnv } from 'varlock/env';
+
+await loadPublicDynamicEnv({ endpoint: '/__varlock/public-env' });
+console.log(ENV.PUBLIC_RUNTIME_FLAG);
+```
+
+## Framework behavior
+
+| Framework | Dynamic server access | Dynamic+public endpoint |
+| :-- | :-- | :-- |
+| Next.js | Dynamic access via `ENV.KEY` in server render paths marks route dynamic | Add a route handler (recommended default path: `/__varlock/public-env`) |
+| Astro | Works in SSR paths | Auto-injected endpoint in SSR mode (configurable) |
+| SvelteKit | Works in SSR paths | Add a `+server.ts` endpoint |
+| Vite (generic) | Works in SSR/server runtime | Add your own server endpoint |
+
+See framework-specific recipes:
+- [Next.js](/integrations/nextjs/)
+- [Astro](/integrations/astro/)
+- [SvelteKit](/integrations/sveltekit/)
+- [Vite](/integrations/vite/)
+
+## Prerender/build guardrails
+
+Dynamic config should not be consumed in static prerender/build contexts unless explicitly designed for it.
+
+Varlock runtime can detect this and warn/error when dynamic keys are accessed during prerender/build phases, helping catch accidental usage early.
+
+## Guidance
+
+- Start with `@defaultDynamic=sensitive` for predictable defaults.
+- Mark intentional runtime public values with `@dynamic`.
+- Keep dynamic+public loading scoped to only the parts of your app that need it.
+- Prefer one app-level endpoint/payload shape per app unless you have a strong reason to split.
diff --git a/packages/varlock-website/src/content/docs/integrations/astro.mdx b/packages/varlock-website/src/content/docs/integrations/astro.mdx
index d5c5705ea..67ab63d58 100644
--- a/packages/varlock-website/src/content/docs/integrations/astro.mdx
+++ b/packages/varlock-website/src/content/docs/integrations/astro.mdx
@@ -75,6 +75,61 @@ console.log(ENV.SOMEVAR); // ✨ recommended
- Better error messages for invalid or unavailable keys
- Enables future DX improvements and tighter control over what is bundled
+## Dynamic+public config
+
+Use [`@dynamic`](/reference/item-decorators/#dynamic) to keep selected public values runtime-resolved:
+For the shared model and tradeoffs, see the [Static vs Dynamic Config guide](/guides/dynamic-config/).
+
+```env-spec title=".env.schema"
+# @defaultSensitive=inferFromPrefix('PUBLIC_')
+# @defaultDynamic=sensitive
+# ---
+PUBLIC_STATIC_FLAG=enabled
+PUBLIC_RUNTIME_FLAG=enabled # @dynamic
+```
+
+### Server rendering
+
+In server-rendered Astro code, access dynamic values via `ENV.KEY` as usual.
+
+### Client-side usage
+
+When the schema contains any dynamic+public keys, this integration automatically injects a route at `/__varlock/public-env` (SSR builds only). Load it in the browser with `loadPublicDynamicEnv()`:
+
+```astro title="src/components/MyClientThing.astro"
+---
+---
+
+```
+
+:::note[Static output]
+If `output: 'static'`, there is no server route to fetch runtime public values from. Dynamic+public values require a server-rendered deployment target.
+:::
+
+### Route injection options
+
+You can control endpoint injection:
+
+```ts title="astro.config.ts"
+import { defineConfig } from 'astro/config';
+import varlockAstroIntegration from '@varlock/astro-integration';
+
+export default defineConfig({
+ integrations: [
+ varlockAstroIntegration({
+ publicDynamicEndpoint: true, // auto by default
+ // or: { path: '/my-public-env' }
+ // or: false (disable auto endpoint)
+ }),
+ ],
+});
+```
+
### Within `astro.config.*`
It's often useful to be able to access env vars in your Astro config. Without varlock, it's a bit awkward, but varlock makes it dead simple - in fact it's already available! Just import varlock's `ENV` object and reference env vars via `ENV.SOME_ITEM` like you do everywhere else.
diff --git a/packages/varlock-website/src/content/docs/integrations/nextjs.mdx b/packages/varlock-website/src/content/docs/integrations/nextjs.mdx
index 4f913a507..b11b45b4d 100644
--- a/packages/varlock-website/src/content/docs/integrations/nextjs.mdx
+++ b/packages/varlock-website/src/content/docs/integrations/nextjs.mdx
@@ -191,6 +191,79 @@ To enable type-safety and IntelliSense for your env vars, enable the [`@generate
- Better error messages for invalid or unavailable keys
- Enables future DX improvements and tighter control over what is bundled
+## Static vs dynamic config
+
+Varlock separates:
+- **sensitive vs public** (security boundary)
+- **dynamic vs static** (runtime vs build-time replacement)
+
+For a full mental model and cross-framework patterns, see the [Static vs Dynamic Config guide](/guides/dynamic-config/).
+
+By default, dynamic behavior follows sensitivity (`@defaultDynamic=sensitive`), but you can override per item with [`@dynamic`](/reference/item-decorators/#dynamic) / [`@static`](/reference/item-decorators/#static).
+
+```env-spec title=".env.schema"
+# @defaultSensitive=inferFromPrefix('NEXT_PUBLIC_')
+# @defaultDynamic=sensitive
+# ---
+NEXT_PUBLIC_STATIC_FLAG=enabled
+NEXT_PUBLIC_RUNTIME_FLAG=enabled # @dynamic
+SECRET_API_KEY= # dynamic by default
+```
+
+### Server-rendered access
+
+For server components and route handlers, use `ENV.KEY` directly:
+
+```tsx title="app/page.tsx"
+import { ENV } from 'varlock/env';
+
+export default function Page() {
+ return {ENV.NEXT_PUBLIC_RUNTIME_FLAG}
;
+}
+```
+
+When a **dynamic** key is accessed in server-rendered code, the Next integration marks that render path as dynamic (not statically prerendered), including nested component access.
+
+### Client-side access for dynamic+public keys
+
+Dynamic+public values are not inlined into client bundles. The recommended pattern is:
+
+1. Add a route that returns `getPublicDynamicEnv()`
+2. Load once in client code with `loadPublicDynamicEnv()`
+3. Continue reading via `ENV.KEY`
+
+```ts title="app/__varlock/public-env/route.ts"
+import { getPublicDynamicEnv } from 'varlock/env';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+ return Response.json(getPublicDynamicEnv(), {
+ headers: { 'cache-control': 'no-store' },
+ });
+}
+```
+
+```tsx title="app/example/client-widget.tsx"
+'use client';
+
+import { useEffect } from 'react';
+import { ENV, loadPublicDynamicEnv } from 'varlock/env';
+
+export function ClientWidget() {
+ useEffect(() => {
+ void loadPublicDynamicEnv();
+ }, []);
+ return {ENV.NEXT_PUBLIC_RUNTIME_FLAG}
;
+}
+```
+
+If you want to return only a subset, pass keys to `getPublicDynamicEnv(['KEY_A', 'KEY_B'])`.
+
+:::tip[Keep unaffected pages static]
+Do not put client dynamic-env loading in your root layout unless every route needs it. Prefer a route group/segment-level layout or a local component so pages that do not use dynamic+public values can still be prerendered.
+:::
+
---
## Managing multiple environments
@@ -277,7 +350,7 @@ APP_ENV=remap($WORKERS_CI_BRANCH,
Next.js uses the `NEXT_PUBLIC_` prefix to determine which env vars are public (bundled for the browser). Varlock lets you control this using decorators.
-Set [`@defaultSensitive`](/reference/root-decorators/#defaultsensitive) and mark specific items [@senstive](/reference/item-decorators/#sensitive):
+Set [`@defaultSensitive`](/reference/root-decorators/#defaultsensitive) and mark specific items [`@sensitive`](/reference/item-decorators/#sensitive):
```diff lang="env-spec" title=".env.schema"
+# @defaultSensitive=true
diff --git a/packages/varlock-website/src/content/docs/integrations/sveltekit.mdx b/packages/varlock-website/src/content/docs/integrations/sveltekit.mdx
index 3e1af932c..72f669939 100644
--- a/packages/varlock-website/src/content/docs/integrations/sveltekit.mdx
+++ b/packages/varlock-website/src/content/docs/integrations/sveltekit.mdx
@@ -56,6 +56,75 @@ See the [**Vite integration page**](/integrations/vite/) for configuration optio
---
+## Dynamic+public recipe
+
+SvelteKit uses Vite, so dynamic/public behavior comes from varlock core + the Vite integration.
+For the shared model and tradeoffs, see the [Static vs Dynamic Config guide](/guides/dynamic-config/).
+
+Use this schema shape:
+
+```env-spec title=".env.schema"
+# @defaultSensitive=false
+# @defaultDynamic=sensitive
+# ---
+PUBLIC_STATIC_VAR=
+PUBLIC_DYNAMIC_VAR= # @dynamic
+
+# @sensitive
+SECRET_VAR=
+```
+
+### 1) Server-rendered routes
+
+In non-prerendered server paths, access `ENV.KEY` directly:
+
+```ts title="src/routes/+page.server.ts"
+import { ENV } from 'varlock/env';
+
+export const load = async () => ({
+ runtimeFlag: ENV.PUBLIC_DYNAMIC_VAR,
+});
+```
+
+### 2) Client routes/components
+
+Expose an endpoint and load once before reading `ENV.KEY` on the client:
+
+```ts title="src/routes/__varlock/public-env/+server.ts"
+import { getPublicDynamicEnv } from 'varlock/env';
+
+export const GET = async () => new Response(JSON.stringify(getPublicDynamicEnv()), {
+ headers: {
+ 'content-type': 'application/json; charset=utf-8',
+ 'cache-control': 'no-store',
+ },
+});
+```
+
+```svelte title="src/routes/+page.svelte"
+
+
+{runtimeFlag}
+```
+
+If you only want a subset, return `getPublicDynamicEnv(['PUBLIC_DYNAMIC_VAR'])` from the endpoint.
+
+### 3) Prerendered routes
+
+Prerendered routes should only use static values. Keep dynamic-key usage out of routes/files that must be prerendered.
+
+---
+
## Setup for Cloudflare Workers
@@ -143,7 +212,7 @@ Varlock replaces all four `$env/*` modules with a single `ENV` object from `varl
| :---------------- | :----------------- |
| `$env/static/public` | `ENV.FOO` where `@sensitive=false` — non-sensitive values are inlined at build time on both client and server |
| `$env/static/private` | `ENV.FOO` where `@sensitive=true`, referenced from SSR/server code — inlined into the server bundle, build errors if referenced from client code |
-| `$env/dynamic/public` | **Not yet supported** — non-sensitive values are currently always inlined at build time (equivalent to `$env/static/public`). Runtime-resolved public values are on the roadmap. |
+| `$env/dynamic/public` | `ENV.FOO` where `@dynamic` + non-sensitive, loaded at runtime for client usage via `loadPublicDynamicEnv()` (see [recipe above](#dynamicpublic-recipe)) |
| `$env/dynamic/private` | `ENV.FOO` — in server contexts it's read from the live runtime env (e.g. Cloudflare bindings via `varlockCloudflareVitePlugin`, or Node's `process.env` elsewhere) rather than baked into the bundle |
| `PUBLIC_` prefix requirement | Per-item [`@sensitive`](/reference/item-decorators/#sensitive) decorator, or a schema-wide [`@defaultSensitive`](/reference/root-decorators/#defaultsensitive) rule |
diff --git a/packages/varlock-website/src/content/docs/integrations/vite.mdx b/packages/varlock-website/src/content/docs/integrations/vite.mdx
index 26d9437ba..aebf021a6 100644
--- a/packages/varlock-website/src/content/docs/integrations/vite.mdx
+++ b/packages/varlock-website/src/content/docs/integrations/vite.mdx
@@ -141,6 +141,50 @@ console.log(ENV.SOMEVAR); // ✨ recommended
- Better error messages for invalid or unavailable keys
- Enables future DX improvements and tighter control over what is bundled
+## Dynamic+public config recipe
+
+Use `@dynamic` for public values that must be resolved at runtime instead of inlined at build time:
+For the shared model and tradeoffs, see the [Static vs Dynamic Config guide](/guides/dynamic-config/).
+
+```env-spec title=".env.schema"
+# @defaultSensitive=inferFromPrefix('VITE_')
+# @defaultDynamic=sensitive
+# ---
+VITE_STATIC_FLAG=enabled
+VITE_RUNTIME_FLAG=enabled # @dynamic
+```
+
+### Server-side rendering
+
+In SSR code, keep using `ENV.KEY` directly.
+
+### Client-side rendering
+
+For browser code, expose an endpoint that returns `getPublicDynamicEnv()` and then hydrate with `loadPublicDynamicEnv()`:
+
+```ts title="server route example"
+import { getPublicDynamicEnv } from 'varlock/env';
+
+export function GET() {
+ return Response.json(getPublicDynamicEnv(), {
+ headers: { 'cache-control': 'no-store' },
+ });
+}
+```
+
+```ts title="client entry example"
+import { ENV, loadPublicDynamicEnv } from 'varlock/env';
+
+await loadPublicDynamicEnv({ endpoint: '/__varlock/public-env' });
+console.log(ENV.VITE_RUNTIME_FLAG);
+```
+
+If you only need a subset, return `getPublicDynamicEnv(['VITE_RUNTIME_FLAG'])`.
+
+:::note[No automatic endpoint in plain Vite]
+The Vite integration does not inject a route automatically. Framework integrations may add this for you (for example, Astro can auto-inject one in SSR mode).
+:::
+
### Within `vite.config.*`
It's often useful to be able to access env vars in your Vite config. Without varlock, it's a bit awkward, but varlock makes it dead simple - in fact it's already available! Just import varlock's `ENV` object and reference env vars via `ENV.SOME_ITEM` like you do everywhere else.
diff --git a/packages/varlock-website/src/content/docs/reference/item-decorators.mdx b/packages/varlock-website/src/content/docs/reference/item-decorators.mdx
index 3afb0980e..a38eaf8a4 100644
--- a/packages/varlock-website/src/content/docs/reference/item-decorators.mdx
+++ b/packages/varlock-website/src/content/docs/reference/item-decorators.mdx
@@ -92,6 +92,32 @@ PUBLIC_API_URL=https://api.example.com
```
+
+### `@dynamic`
+**Value type:** `boolean`
+
+Sets whether the item is _dynamic_ - meaning integrations should avoid replacing it at build time and instead resolve it at runtime.
+
+By default, dynamic behavior follows sensitivity (sensitive items are dynamic, non-sensitive items are static), but this can be overridden globally with [`@defaultDynamic`](/reference/root-decorators/#defaultdynamic).
+
+```env-spec
+# @dynamic
+PUBLIC_RUNTIME_FLAG=
+```
+
+
+
+### `@static`
+**Value type:** `boolean`
+
+Opposite of [`@dynamic`](#dynamic). Equivalent to writing `@dynamic=false`.
+
+```env-spec
+# @static
+SENSITIVE_BUILD_TIME_TOKEN=
+```
+
+
### `@type`
**Value type:** [`data type`](/reference/data-types) (name only or function call)
diff --git a/packages/varlock-website/src/content/docs/reference/root-decorators.mdx b/packages/varlock-website/src/content/docs/reference/root-decorators.mdx
index 4f3534bea..cff1ff6c8 100644
--- a/packages/varlock-website/src/content/docs/reference/root-decorators.mdx
+++ b/packages/varlock-website/src/content/docs/reference/root-decorators.mdx
@@ -110,6 +110,26 @@ OTHER_BAR= # not sensitive (explicit)
```
+
+### `@defaultDynamic`
+**Value type:** `boolean | "sensitive"`
+
+Sets the default state of each item being treated as _dynamic_ (runtime-resolved) vs _static_ (eligible for build-time replacement). Only applied to items that have a definition within the same file. Can be overridden on individual items using [`@dynamic`](/reference/item-decorators/#dynamic)/[`@static`](/reference/item-decorators/#static).
+
+- `"sensitive"` (default): Dynamic behavior follows sensitivity.
+- `true`: All items are dynamic unless explicitly marked static.
+- `false`: All items are static unless explicitly marked dynamic.
+
+```env-spec
+# @defaultSensitive=inferFromPrefix(PUBLIC_)
+# @defaultDynamic=sensitive
+# ---
+
+PUBLIC_FOO= # static by default (public)
+SECRET_BAR= # dynamic by default (sensitive)
+```
+
+
### `@disable`
**Value type:** `boolean`
diff --git a/packages/varlock/src/env-graph/lib/config-item.ts b/packages/varlock/src/env-graph/lib/config-item.ts
index c53ad1972..f2f269507 100644
--- a/packages/varlock/src/env-graph/lib/config-item.ts
+++ b/packages/varlock/src/env-graph/lib/config-item.ts
@@ -455,6 +455,55 @@ export class ConfigItem {
if (sensitiveFromDataType !== undefined) this._isSensitive = sensitiveFromDataType;
}
+ _isDynamic: boolean = true;
+ get isDynamic(): boolean {
+ return this._isDynamic;
+ }
+ private async processDynamic() {
+ try {
+ // Pass 1: explicit per-item @dynamic / @static decorators take highest priority
+ for (const def of this.defs) {
+ const dynamicDecs = def.itemDef.decorators?.filter((d) => d.name === 'dynamic' || d.name === 'static') || [];
+ const dynamicDec = dynamicDecs[0];
+ if (!dynamicDec) continue;
+
+ const usingStatic = dynamicDec.name === 'static';
+ const dynamicDecValue = await dynamicDec.resolve();
+ if (dynamicDec.schemaErrors.some((e) => !e.isWarning)) return;
+ if (![true, false, undefined].includes(dynamicDecValue)) {
+ throw new SchemaError('@dynamic/@static must resolve to a boolean or undefined');
+ }
+ if (dynamicDecValue !== undefined) {
+ this._isDynamic = usingStatic ? !dynamicDecValue : dynamicDecValue;
+ return;
+ }
+ }
+
+ // Pass 2: @defaultDynamic from source files
+ for (const def of this.defs) {
+ const defaultDynamicDec = def.source?.getRootDec('defaultDynamic');
+ if (!defaultDynamicDec) continue;
+
+ const defaultDynamicVal = await defaultDynamicDec.resolve();
+ if (_.isBoolean(defaultDynamicVal)) {
+ this._isDynamic = defaultDynamicVal;
+ return;
+ }
+ if (defaultDynamicVal === 'sensitive') {
+ this._isDynamic = this._isSensitive;
+ return;
+ }
+ throw new SchemaError('@defaultDynamic must resolve to true, false, or "sensitive"');
+ }
+ } catch (err) {
+ this._schemaErrors.push(err instanceof SchemaError ? err : new SchemaError(err as Error));
+ return;
+ }
+
+ // Default behavior: dynamic state follows sensitivity.
+ this._isDynamic = this._isSensitive;
+ }
+
get errors() {
return _.compact([
@@ -527,6 +576,7 @@ export class ConfigItem {
}
}
}
+ await this.processDynamic();
if (!this.valueResolver) {
this.isResolved = true;
@@ -744,6 +794,51 @@ export class ConfigItem {
// on error, fall back to default (sensitive=true, safe default)
}
+ // isDynamic - mirrors processDynamic() logic
+ let isDynamic = isSensitive;
+ try {
+ let foundDynamic = false;
+ for (const def of defs) {
+ const dynamicDecs = def.itemDef.decorators?.filter((d) => d.name === 'dynamic' || d.name === 'static') || [];
+ const dynamicDec = dynamicDecs[0];
+
+ if (dynamicDec) {
+ const usingStatic = dynamicDec.name === 'static';
+ // Skip dynamic decorators to avoid caching a stale result
+ if (dynamicDec.decValueResolver?.fnName !== '\0static') break;
+ const dynamicDecValue = await dynamicDec.resolve();
+ if (dynamicDec.schemaErrors.some((e) => !e.isWarning)) break;
+ if (![true, false, undefined].includes(dynamicDecValue)) break;
+ if (dynamicDecValue !== undefined) {
+ isDynamic = usingStatic ? !dynamicDecValue : dynamicDecValue;
+ foundDynamic = true;
+ break;
+ }
+ }
+
+ const defaultDynamicDec = def.source?.getRootDec('defaultDynamic');
+ if (!defaultDynamicDec) continue;
+
+ const defaultDynamicVal = await defaultDynamicDec.resolve();
+ if (_.isBoolean(defaultDynamicVal)) {
+ isDynamic = defaultDynamicVal;
+ foundDynamic = true;
+ break;
+ }
+ if (defaultDynamicVal === 'sensitive') {
+ isDynamic = isSensitive;
+ foundDynamic = true;
+ break;
+ }
+ }
+ if (!foundDynamic) {
+ isDynamic = isSensitive;
+ }
+ } catch {
+ // on error, fall back to default linkage (dynamic follows sensitivity)
+ isDynamic = isSensitive;
+ }
+
// icon - resolve from filtered defs' decorators
let icon: string | undefined;
for (const def of defs) {
@@ -799,6 +894,7 @@ export class ConfigItem {
isRequired,
isRequiredDynamic,
isSensitive,
+ isDynamic,
icon,
docsLinks,
isDeprecated: this.isDeprecated,
@@ -815,6 +911,7 @@ export type TypeGenItemInfo = {
isRequired: boolean;
isRequiredDynamic: boolean;
isSensitive: boolean;
+ isDynamic: boolean;
icon?: string;
docsLinks: Array<{ url: string, description?: string }>;
isDeprecated: boolean;
diff --git a/packages/varlock/src/env-graph/lib/decorators.ts b/packages/varlock/src/env-graph/lib/decorators.ts
index 417589cfd..d76abdda4 100644
--- a/packages/varlock/src/env-graph/lib/decorators.ts
+++ b/packages/varlock/src/env-graph/lib/decorators.ts
@@ -303,6 +303,16 @@ export const builtInRootDecorators: Array
> = [
}
},
},
+ {
+ name: 'defaultDynamic',
+ process: (decVal) => {
+ if (!decVal.isStatic || ![true, false, 'sensitive'].includes(decVal.staticValue as any)) {
+ throw new Error(
+ '@defaultDynamic decorator value must be a static value of true, false, or "sensitive"',
+ );
+ }
+ },
+ },
{
name: 'disable',
},
@@ -486,6 +496,14 @@ export const builtInItemDecorators: Array> = [
name: 'public',
incompatibleWith: ['sensitive'],
},
+ {
+ name: 'dynamic',
+ incompatibleWith: ['static'],
+ },
+ {
+ name: 'static',
+ incompatibleWith: ['dynamic'],
+ },
{
name: 'type',
useFnArgsResolver: true,
diff --git a/packages/varlock/src/env-graph/lib/env-graph.ts b/packages/varlock/src/env-graph/lib/env-graph.ts
index 47a0ccb63..bcd0213f5 100644
--- a/packages/varlock/src/env-graph/lib/env-graph.ts
+++ b/packages/varlock/src/env-graph/lib/env-graph.ts
@@ -52,6 +52,7 @@ export type SerializedEnvGraph = {
config: Record;
/** Present only when config has errors — consumers can check `if (data.errors)` */
errors?: SerializedEnvGraphErrors;
@@ -296,6 +297,7 @@ export class EnvGraph {
// internal def has no decorators and no source with root-level defaults.
item._isRequired = false;
item._isSensitive = false;
+ item._isDynamic = false;
// Set dataType directly since registerBuiltinVar is called synchronously
// during resolver processing, and the item may not get a process() call
// from the finishLoad loop (for...in doesn't reliably visit new keys).
@@ -556,6 +558,7 @@ export class EnvGraph {
serializedGraph.config[itemKey] = {
value: item.resolvedValue,
isSensitive: item.isSensitive,
+ isDynamic: item.isDynamic,
};
}
diff --git a/packages/varlock/src/env-graph/test/dynamic-decorator.test.ts b/packages/varlock/src/env-graph/test/dynamic-decorator.test.ts
new file mode 100644
index 000000000..3ca787d75
--- /dev/null
+++ b/packages/varlock/src/env-graph/test/dynamic-decorator.test.ts
@@ -0,0 +1,122 @@
+import {
+ describe, test,
+} from 'vitest';
+import outdent from 'outdent';
+import { envFilesTest } from './helpers/generic-test';
+
+describe('@dynamic, @static, and @defaultDynamic', () => {
+ test('default behavior: dynamic follows sensitivity', envFilesTest({
+ envFile: outdent`
+ SECRET= # @sensitive
+ PUBLIC= # @public
+ SECRET_FALSE= # @sensitive=false
+ PUBLIC_FALSE= # @public=false
+ `,
+ expectDynamic: {
+ SECRET: true,
+ PUBLIC: false,
+ SECRET_FALSE: false,
+ PUBLIC_FALSE: true,
+ },
+ }));
+
+ test('@dynamic and @static override default behavior', envFilesTest({
+ envFile: outdent`
+ STATIC_SECRET= # @sensitive @static
+ DYNAMIC_PUBLIC= # @public @dynamic
+ STATIC_FALSE= # @static=false
+ DYNAMIC_FALSE= # @dynamic=false
+ `,
+ expectDynamic: {
+ STATIC_SECRET: false,
+ DYNAMIC_PUBLIC: true,
+ STATIC_FALSE: true,
+ DYNAMIC_FALSE: false,
+ },
+ }));
+
+ test('dynamic @dynamic/@static values work', envFilesTest({
+ envFile: outdent`
+ DYNAMIC_TRUE= # @dynamic=if(yes)
+ DYNAMIC_FALSE= # @dynamic=if(0)
+ STATIC_TRUE= # @static=if(yes)
+ STATIC_FALSE= # @static=if(0)
+ `,
+ expectDynamic: {
+ DYNAMIC_TRUE: true,
+ DYNAMIC_FALSE: false,
+ STATIC_TRUE: false,
+ STATIC_FALSE: true,
+ },
+ }));
+
+ test('@defaultDynamic=true', envFilesTest({
+ envFile: outdent`
+ # @defaultDynamic=true
+ # ---
+ PUBLIC= # @public
+ OTHER=
+ `,
+ expectDynamic: {
+ PUBLIC: true,
+ OTHER: true,
+ },
+ }));
+
+ test('@defaultDynamic=false', envFilesTest({
+ envFile: outdent`
+ # @defaultDynamic=false
+ # ---
+ SECRET= # @sensitive
+ OTHER=
+ `,
+ expectDynamic: {
+ SECRET: false,
+ OTHER: false,
+ },
+ }));
+
+ test('@defaultDynamic=sensitive links dynamic to final sensitivity', envFilesTest({
+ envFile: outdent`
+ # @defaultSensitive=inferFromPrefix(PUBLIC_)
+ # @defaultDynamic=sensitive
+ # ---
+ PUBLIC_FOO=
+ SECRET_BAR=
+ `,
+ expectSensitive: {
+ PUBLIC_FOO: false,
+ SECRET_BAR: true,
+ },
+ expectDynamic: {
+ PUBLIC_FOO: false,
+ SECRET_BAR: true,
+ },
+ }));
+
+ test('explicit @dynamic/@static beats @defaultDynamic', envFilesTest({
+ envFile: outdent`
+ # @defaultDynamic=sensitive
+ # ---
+ SECRET_STATIC= # @sensitive @static
+ PUBLIC_DYNAMIC= # @public @dynamic
+ `,
+ expectDynamic: {
+ SECRET_STATIC: false,
+ PUBLIC_DYNAMIC: true,
+ },
+ }));
+
+ test('serializes isDynamic in graph output', envFilesTest({
+ envFile: outdent`
+ PUBLIC= # @public
+ DYNAMIC_PUBLIC= # @public @dynamic
+ `,
+ expectSerializedMatches: {
+ config: {
+ PUBLIC: { isDynamic: false },
+ DYNAMIC_PUBLIC: { isDynamic: true },
+ },
+ },
+ }));
+});
diff --git a/packages/varlock/src/env-graph/test/helpers/generic-test.ts b/packages/varlock/src/env-graph/test/helpers/generic-test.ts
index c1d13cf9e..170b80692 100644
--- a/packages/varlock/src/env-graph/test/helpers/generic-test.ts
+++ b/packages/varlock/src/env-graph/test/helpers/generic-test.ts
@@ -42,6 +42,7 @@ export function envFilesTest(spec: {
expectRequired?: Record>;
expectRequiredIsDynamic?: Record;
expectSensitive?: Record>;
+ expectDynamic?: Record>;
expectSerializedMatches?: any;
/**
* Simulate calling getTypeGenInfo() on all items before resolveEnvValues(),
@@ -185,6 +186,12 @@ export function envFilesTest(spec: {
expect(item.isSensitive, `expected ${key} to be ${spec.expectSensitive[key] ? 'sensitive' : 'NOT sensitive'}`).toBe(spec.expectSensitive[key]);
}
}
+ if (spec.expectDynamic) {
+ for (const key of Object.keys(spec.expectDynamic)) {
+ const item = g.configSchema[key];
+ expect(item.isDynamic, `expected ${key} to be ${spec.expectDynamic[key] ? 'dynamic' : 'NOT dynamic'}`).toBe(spec.expectDynamic[key]);
+ }
+ }
}
if (spec.expectSerializedMatches) {
diff --git a/packages/varlock/src/index.ts b/packages/varlock/src/index.ts
index 27b7ae843..112eae74d 100644
--- a/packages/varlock/src/index.ts
+++ b/packages/varlock/src/index.ts
@@ -39,7 +39,8 @@ export function getBuildTimeReplacements(opts?: {
const replacements = {} as Record;
for (const key in envInfo.config) {
const itemInfo = envInfo.config[key];
- const replaceItem = !itemInfo.isSensitive || opts?.includeSensitive;
+ const isDynamic = itemInfo.isDynamic;
+ const replaceItem = !isDynamic || opts?.includeSensitive;
if (!replaceItem) continue;
replacements[`${opts?.objectKey || 'ENV'}.${key}`] = JSON.stringify(envInfo.config[key].value);
}
diff --git a/packages/varlock/src/runtime/env.ts b/packages/varlock/src/runtime/env.ts
index be23acb24..e20ea575b 100644
--- a/packages/varlock/src/runtime/env.ts
+++ b/packages/varlock/src/runtime/env.ts
@@ -270,6 +270,8 @@ export function initVarlockEnv(opts?: {
resetRedactionMap(serializedEnvData);
const setProcessEnv = processExists && !serializedEnvData.settings?.disableProcessEnvInjection;
+ const dynamicKeys: Array = [];
+ const dynamicPublicKeys: Array = [];
// if we've already injected process.env vars in the past, we'll reset those now
if (setProcessEnv) {
@@ -281,7 +283,13 @@ export function initVarlockEnv(opts?: {
}
for (const itemKey in serializedEnvData.config) {
- const itemValue = serializedEnvData.config[itemKey].value;
+ const itemData = serializedEnvData.config[itemKey];
+ const itemValue = itemData.value;
+ const isDynamic = itemData.isDynamic;
+ if (isDynamic) {
+ dynamicKeys.push(itemKey);
+ if (!itemData.isSensitive) dynamicPublicKeys.push(itemKey);
+ }
envValues[itemKey] = itemValue;
if (setProcessEnv) {
varlockInjectedProcessEnvKeys?.push(itemKey);
@@ -290,6 +298,8 @@ export function initVarlockEnv(opts?: {
process.env[itemKey] = itemValue === undefined ? '' : String(itemValue);
}
}
+ (globalThis as any).__varlockDynamicKeys = dynamicKeys;
+ (globalThis as any).__varlockDynamicPublicKeys = dynamicPublicKeys;
initializedEnv = true;
}
@@ -324,6 +334,183 @@ const IGNORED_PROXY_KEYS = [
// but TS wont let us, so instead we start with it being empty, which will cause type errors
// unless type generation is enabled
export interface TypedEnvSchema {}
+export interface PublicTypedEnvSchema {}
+type DynamicConfigAccessMeta = {
+ key: string,
+ isPublic: boolean,
+};
+
+function getStringArrayGlobal(name: string): Array {
+ const val = (globalThis as any)[name];
+ if (!Array.isArray(val)) return [];
+ return val.filter((k) => typeof k === 'string');
+}
+
+export function getDynamicConfigKeys(): Array {
+ return getStringArrayGlobal('__varlockDynamicKeys');
+}
+
+export function getDynamicPublicConfigKeys(): Array {
+ return getStringArrayGlobal('__varlockDynamicPublicKeys');
+}
+
+function getDynamicPublicKeys(): Array {
+ return getDynamicPublicConfigKeys();
+}
+
+function resolvePublicDynamicKeys(keys?: Array): Array {
+ const allowedKeys = getDynamicPublicKeys();
+ if (!keys?.length) return allowedKeys;
+ if (!allowedKeys.length) return keys;
+ const allowedSet = new Set(allowedKeys);
+ return keys.filter((k) => allowedSet.has(k));
+}
+
+function getVarlockExecutionPhase() {
+ if ((globalThis as any).__varlockExecutionPhase) return (globalThis as any).__varlockExecutionPhase as string;
+ return globalThis.process?.env?._VARLOCK_EXECUTION_PHASE;
+}
+
+function getDynamicBuildAccessMode() {
+ const mode = (globalThis as any).__varlockDynamicBuildAccessMode
+ ?? globalThis.process?.env?._VARLOCK_DYNAMIC_BUILD_ACCESS_MODE
+ ?? 'error';
+ return mode === 'warn' ? 'warn' : 'error';
+}
+
+function shouldGuardDynamicAccessDuringBuild() {
+ const phase = getVarlockExecutionPhase();
+ return phase === 'build' || phase === 'prerender';
+}
+
+function notifyDynamicConfigAccess(meta: DynamicConfigAccessMeta) {
+ const onDynamicConfigAccess = (globalThis as any).__varlockOnDynamicConfigAccess;
+ if (typeof onDynamicConfigAccess !== 'function') {
+ debug(`[dynamic-access] no hook installed for ENV.${meta.key}`);
+ return;
+ }
+ debug(`[dynamic-access] notifying hook for ENV.${meta.key} (isPublic=${meta.isPublic})`);
+ onDynamicConfigAccess(meta);
+}
+
+const dynamicBuildAccessWarnedKeys = new Set();
+const DEFAULT_PUBLIC_DYNAMIC_ENV_ENDPOINT = '/__varlock/public-env';
+let dynamicPublicEnvLoadPromise: Promise> | undefined;
+let hasLoadedDynamicPublicEnv = false;
+let lastLoadedDynamicPublicEnv = {} as Record;
+
+function hasHydratedDynamicPublicEnv() {
+ const dynamicPublicKeys = getDynamicPublicKeys();
+ if (!dynamicPublicKeys.length) return false;
+ return dynamicPublicKeys.every((key) => key in envValues);
+}
+
+/**
+ * Hydrate dynamic+public env values at runtime (typically in the browser),
+ * while keeping the same `ENV.KEY` access pattern.
+ */
+export function setDynamicPublicEnv(
+ values: Partial | Record,
+) {
+ initializedEnv = true;
+ for (const [key, value] of Object.entries(values || {})) {
+ envValues[key] = value;
+ }
+}
+
+/**
+ * Returns the currently hydrated dynamic+public values from the ENV proxy store.
+ */
+export function getDynamicPublicEnv(): Partial {
+ const out: Record = {};
+ for (const key of resolvePublicDynamicKeys()) {
+ if (key in envValues) out[key] = envValues[key];
+ }
+ return out as Partial;
+}
+
+/**
+ * Returns dynamic+public env values as an object.
+ * Optionally pass a key list to limit which values are included.
+ */
+export function getPublicDynamicEnv(keys?: Array): Partial {
+ const out: Record = {};
+ for (const key of resolvePublicDynamicKeys(keys)) {
+ if (key in envValues) out[key] = envValues[key];
+ }
+ return out as Partial;
+}
+
+/**
+ * Clears hydrated dynamic+public values from the ENV proxy store.
+ */
+export function clearDynamicPublicEnv(keys?: Array) {
+ for (const key of resolvePublicDynamicKeys(keys)) {
+ delete envValues[key];
+ }
+ hasLoadedDynamicPublicEnv = false;
+ lastLoadedDynamicPublicEnv = {};
+}
+
+/**
+ * Loads dynamic+public env values from a server endpoint and hydrates the ENV proxy.
+ * The server endpoint controls which keys are returned.
+ */
+export async function loadPublicDynamicEnv(opts?: {
+ endpoint?: string,
+ fetch?: (input: string | URL, init?: RequestInit) => Promise,
+ force?: boolean,
+ requestInit?: RequestInit,
+}): Promise> {
+ if (!opts?.force) {
+ if (hasHydratedDynamicPublicEnv()) return getDynamicPublicEnv();
+ if (hasLoadedDynamicPublicEnv) return lastLoadedDynamicPublicEnv as Partial;
+ if (dynamicPublicEnvLoadPromise) return dynamicPublicEnvLoadPromise;
+ }
+
+ const endpoint = opts?.endpoint
+ ?? (globalThis as any).__varlockPublicDynamicEnvEndpoint
+ ?? DEFAULT_PUBLIC_DYNAMIC_ENV_ENDPOINT;
+
+ const fetchImpl = opts?.fetch ?? globalThis.fetch?.bind(globalThis);
+ if (!fetchImpl) {
+ throw new Error(
+ '[varlock] loadPublicDynamicEnv requires fetch. '
+ + 'Pass opts.fetch or call it in an environment with global fetch.',
+ );
+ }
+
+ dynamicPublicEnvLoadPromise = (async () => {
+ const response = await fetchImpl(endpoint, {
+ method: 'GET',
+ cache: 'no-store',
+ credentials: 'same-origin',
+ ...opts?.requestInit,
+ });
+ if (!response.ok) {
+ throw new Error(
+ `[varlock] Failed to load dynamic public env (${response.status}) from ${endpoint}`,
+ );
+ }
+
+ const payload = await response.json() as unknown;
+ if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+ throw new Error('[varlock] loadPublicDynamicEnv expected a JSON object payload');
+ }
+ const payloadObj = payload as Record;
+
+ setDynamicPublicEnv(payloadObj);
+ hasLoadedDynamicPublicEnv = true;
+ lastLoadedDynamicPublicEnv = payloadObj;
+ return payloadObj as Partial;
+ })();
+
+ try {
+ return await dynamicPublicEnvLoadPromise;
+ } finally {
+ dynamicPublicEnvLoadPromise = undefined;
+ }
+}
const EnvProxy = new Proxy({}, {
get(target, prop) {
@@ -345,8 +532,48 @@ const EnvProxy = new Proxy({}, {
return undefined;
}
- if (prop in envValues) return envValues[prop];
+ const dynamicKeys = getDynamicConfigKeys();
+ if (prop in envValues) {
+ const isDynamic = dynamicKeys.includes(prop);
+ if (isDynamic) {
+ debug(`[dynamic-access] detected dynamic access for ENV.${prop}`);
+ }
+ if (isDynamic) {
+ notifyDynamicConfigAccess({
+ key: prop,
+ isPublic: getDynamicPublicKeys().includes(prop),
+ });
+ }
+ if (isDynamic && shouldGuardDynamicAccessDuringBuild()) {
+ const msg = [
+ `[varlock] dynamic config \`ENV.${prop}\` was accessed during ${getVarlockExecutionPhase()}.`,
+ 'Dynamic values cannot be safely inlined during static build/prerender.',
+ 'Use runtime SSR access (non-prerender) or load/hydrate dynamic public values at runtime.',
+ ].join(' ');
+ if (getDynamicBuildAccessMode() === 'warn') {
+ if (!dynamicBuildAccessWarnedKeys.has(prop)) {
+ dynamicBuildAccessWarnedKeys.add(prop);
+ // eslint-disable-next-line no-console
+ console.warn(msg);
+ }
+ } else {
+ throw new Error(msg);
+ }
+ }
+ return envValues[prop];
+ }
if ((globalThis as any).__varlockThrowOnMissingKeys) {
+ if (dynamicKeys.includes(prop)) {
+ if (getDynamicPublicKeys().includes(prop)) {
+ throw new Error(
+ `\`ENV.${prop}\` is dynamic+public and has not been hydrated yet. `
+ + 'Load dynamic public env first, then access it via ENV.',
+ );
+ }
+ throw new Error(
+ `\`ENV.${prop}\` is dynamic and is not available in this environment.`,
+ );
+ }
// during development, we can feed in extra metadata and show more helpful errors
if ((globalThis as any).__varlockValidKeys && (globalThis as any).__varlockValidKeys.includes(prop)) {
throw new Error(`\`ENV.${prop}\` exists, but is not available in this environment`);
diff --git a/packages/varlock/src/runtime/test/crypto.test.ts b/packages/varlock/src/runtime/test/crypto.test.ts
index 2b488942a..6458bb081 100644
--- a/packages/varlock/src/runtime/test/crypto.test.ts
+++ b/packages/varlock/src/runtime/test/crypto.test.ts
@@ -9,7 +9,7 @@ import {
const TEST_KEY = 'a'.repeat(64); // valid 256-bit hex key
const TEST_JSON = JSON.stringify({
- config: { API_KEY: { value: 'secret-123', isSensitive: true } },
+ config: { API_KEY: { value: 'secret-123', isSensitive: true, isDynamic: true } },
sources: [],
settings: {},
});
diff --git a/packages/varlock/src/runtime/test/dynamic-public-env.test.ts b/packages/varlock/src/runtime/test/dynamic-public-env.test.ts
new file mode 100644
index 000000000..b20e56f61
--- /dev/null
+++ b/packages/varlock/src/runtime/test/dynamic-public-env.test.ts
@@ -0,0 +1,175 @@
+import {
+ afterEach, beforeEach, describe, expect, it, vi,
+} from 'vitest';
+import {
+ ENV,
+ clearDynamicPublicEnv,
+ getDynamicConfigKeys,
+ getDynamicPublicConfigKeys,
+ getDynamicPublicEnv,
+ loadPublicDynamicEnv,
+ getPublicDynamicEnv,
+ initVarlockEnv,
+ setDynamicPublicEnv,
+} from '../env';
+
+const DYNAMIC_KEY = 'PUBLIC_DYNAMIC_TEST';
+const originalFetch = globalThis.fetch;
+
+describe('dynamic public env hydration', () => {
+ beforeEach(() => {
+ (globalThis as any).__varlockThrowOnMissingKeys = true;
+ (globalThis as any).__varlockExecutionPhase = undefined;
+ (globalThis as any).__varlockDynamicBuildAccessMode = undefined;
+ (globalThis as any).__varlockDynamicKeys = [DYNAMIC_KEY];
+ (globalThis as any).__varlockDynamicPublicKeys = [DYNAMIC_KEY];
+ (globalThis as any).__varlockOnDynamicConfigAccess = undefined;
+ delete process.env._VARLOCK_EXECUTION_PHASE;
+ delete process.env._VARLOCK_DYNAMIC_BUILD_ACCESS_MODE;
+ clearDynamicPublicEnv([DYNAMIC_KEY]);
+ });
+
+ afterEach(() => {
+ globalThis.fetch = originalFetch;
+ });
+
+ it('hydrates ENV values via setDynamicPublicEnv', () => {
+ setDynamicPublicEnv({ [DYNAMIC_KEY]: 'hello-runtime' });
+ expect((ENV as any)[DYNAMIC_KEY]).toBe('hello-runtime');
+ expect((getDynamicPublicEnv() as any)[DYNAMIC_KEY]).toBe('hello-runtime');
+ expect((getPublicDynamicEnv() as any)[DYNAMIC_KEY]).toBe('hello-runtime');
+ });
+
+ it('getPublicDynamicEnv accepts an optional key list', () => {
+ (globalThis as any).__varlockDynamicPublicKeys = [
+ 'PUBLIC_DYNAMIC_TEST',
+ 'OTHER_PUBLIC_DYNAMIC',
+ ];
+ setDynamicPublicEnv({
+ PUBLIC_DYNAMIC_TEST: 'a',
+ OTHER_PUBLIC_DYNAMIC: 'b',
+ });
+ expect(getPublicDynamicEnv(['PUBLIC_DYNAMIC_TEST'])).toEqual({
+ PUBLIC_DYNAMIC_TEST: 'a',
+ });
+ });
+
+ it('getPublicDynamicEnv honors explicit keys when metadata is unavailable', () => {
+ (globalThis as any).__varlockDynamicPublicKeys = undefined;
+ setDynamicPublicEnv({
+ PUBLIC_DYNAMIC_TEST: 'a',
+ OTHER_PUBLIC_DYNAMIC: 'b',
+ });
+ expect(getPublicDynamicEnv(['PUBLIC_DYNAMIC_TEST'])).toEqual({
+ PUBLIC_DYNAMIC_TEST: 'a',
+ });
+ });
+
+ it('throws helpful guidance when dynamic+public key is accessed before hydration', () => {
+ expect(() => (ENV as any)[DYNAMIC_KEY]).toThrow(/dynamic\+public and has not been hydrated yet/i);
+ });
+
+ it('notifies on dynamic key access when a runtime hook is installed', () => {
+ const onAccess = vi.fn();
+ (globalThis as any).__varlockOnDynamicConfigAccess = onAccess;
+ setDynamicPublicEnv({ [DYNAMIC_KEY]: 'hello-runtime' });
+ expect((ENV as any)[DYNAMIC_KEY]).toBe('hello-runtime');
+ expect(onAccess).toHaveBeenCalledWith({
+ key: DYNAMIC_KEY,
+ isPublic: true,
+ });
+ });
+
+ it('exposes dynamic metadata from initVarlockEnv', () => {
+ process.env.__VARLOCK_ENV = JSON.stringify({
+ sources: [],
+ settings: {},
+ config: {
+ PUBLIC_STATIC_TEST: { value: 'a', isSensitive: false, isDynamic: false },
+ PUBLIC_DYNAMIC_TEST: { value: 'b', isSensitive: false, isDynamic: true },
+ SECRET_DYNAMIC_TEST: { value: 'c', isSensitive: true, isDynamic: true },
+ },
+ });
+
+ initVarlockEnv();
+
+ expect(getDynamicConfigKeys()).toEqual(expect.arrayContaining([
+ 'PUBLIC_DYNAMIC_TEST',
+ 'SECRET_DYNAMIC_TEST',
+ ]));
+ expect(getDynamicPublicConfigKeys()).toEqual(['PUBLIC_DYNAMIC_TEST']);
+ });
+
+ it('throws when a dynamic key is accessed during build/prerender phase', () => {
+ (globalThis as any).__varlockDynamicKeys = [DYNAMIC_KEY];
+ (globalThis as any).__varlockExecutionPhase = 'build';
+ setDynamicPublicEnv({ [DYNAMIC_KEY]: 'hello-runtime' });
+ expect(() => (ENV as any)[DYNAMIC_KEY]).toThrow(/accessed during build/i);
+ });
+
+ it('supports _VARLOCK_EXECUTION_PHASE and _VARLOCK_DYNAMIC_BUILD_ACCESS_MODE', () => {
+ (globalThis as any).__varlockExecutionPhase = undefined;
+ (globalThis as any).__varlockDynamicBuildAccessMode = undefined;
+ process.env._VARLOCK_EXECUTION_PHASE = 'build';
+ process.env._VARLOCK_DYNAMIC_BUILD_ACCESS_MODE = 'warn';
+ setDynamicPublicEnv({ [DYNAMIC_KEY]: 'hello-runtime' });
+ expect(() => (ENV as any)[DYNAMIC_KEY]).not.toThrow();
+ });
+
+ it('loadPublicDynamicEnv fetches and hydrates ENV values', async () => {
+ let fetchCount = 0;
+ globalThis.fetch = (async () => {
+ fetchCount += 1;
+ return new Response(JSON.stringify({ [DYNAMIC_KEY]: 'loaded-from-endpoint' }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+ }) as unknown as typeof fetch;
+
+ const payload = await loadPublicDynamicEnv();
+
+ expect(fetchCount).toBe(1);
+ expect(payload).toEqual({ [DYNAMIC_KEY]: 'loaded-from-endpoint' });
+ expect((ENV as any)[DYNAMIC_KEY]).toBe('loaded-from-endpoint');
+ });
+
+ it('loadPublicDynamicEnv avoids refetch when already hydrated', async () => {
+ let fetchCount = 0;
+ globalThis.fetch = (async () => {
+ fetchCount += 1;
+ return new Response(JSON.stringify({ [DYNAMIC_KEY]: 'loaded-once' }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+ }) as unknown as typeof fetch;
+
+ await loadPublicDynamicEnv();
+ const second = await loadPublicDynamicEnv();
+
+ expect(fetchCount).toBe(1);
+ expect(second).toEqual({ [DYNAMIC_KEY]: 'loaded-once' });
+ });
+
+ it('loadPublicDynamicEnv dedupes concurrent fetches', async () => {
+ let fetchCount = 0;
+ globalThis.fetch = (async () => {
+ fetchCount += 1;
+ await new Promise((resolve) => {
+ setTimeout(resolve, 10);
+ });
+ return new Response(JSON.stringify({ [DYNAMIC_KEY]: 'loaded-concurrent' }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+ }) as unknown as typeof fetch;
+
+ const [a, b] = await Promise.all([
+ loadPublicDynamicEnv(),
+ loadPublicDynamicEnv(),
+ ]);
+
+ expect(fetchCount).toBe(1);
+ expect(a).toEqual({ [DYNAMIC_KEY]: 'loaded-concurrent' });
+ expect(b).toEqual({ [DYNAMIC_KEY]: 'loaded-concurrent' });
+ });
+});
diff --git a/packages/varlock/src/runtime/test/scan-for-leaks.test.ts b/packages/varlock/src/runtime/test/scan-for-leaks.test.ts
index 290a9a0d7..03c51b025 100644
--- a/packages/varlock/src/runtime/test/scan-for-leaks.test.ts
+++ b/packages/varlock/src/runtime/test/scan-for-leaks.test.ts
@@ -8,7 +8,7 @@ import type { SerializedEnvGraph } from '../../env-graph';
function setSecret(key: string, value: string) {
resetRedactionMap({
config: {
- [key]: { isSensitive: true, value },
+ [key]: { isSensitive: true, isDynamic: true, value },
},
} as unknown as SerializedEnvGraph);
}