Merge pull request #1423 from yamcodes/1328-env-module-transform

feat: (v1) env-module transform — canonical env object surface

Author: yamcodes

.changeset/vite-env-module-transform.md

@@ -0,0 +1,40 @@
+---
+"@arkenv/vite-plugin": minor
+---
+
+#### Add `env.ts` transform for Vite fullstack apps
+
+Let the Vite plugin discover your `env.ts` and expose a shared `env` object that works in both client and server code. On the client, public (`VITE_*`) values are inlined at build time and server-only keys throw if read; on the server/SSR, `env.ts` still runs normally and validates against the real environment at boot. The plugin does not rewrite your `env.ts` file on disk.
+
+Works with `@arkenv/vite-plugin` and `@arkenv/vite-plugin/standard`.
+
+Usage:
+
+```ts
+// vite.config.ts
+import arkenv from "@arkenv/vite-plugin";
+
+export default {
+  plugins: [arkenv()], // finds src/env.ts or env.ts
+  // or: arkenv({ schemaPath: "src/env.ts", clientPrefix: "VITE_" })
+};
+```
+
+```ts
+// src/env.ts
+import arkenv from "@arkenv/core";
+
+export const env = arkenv({
+  DATABASE_URL: "string",
+  VITE_API_URL: "string",
+});
+```
+
+```ts
+import { env } from "./env";
+
+env.VITE_API_URL; // available on client and server
+env.DATABASE_URL; // server only — throws if read in the browser
+```
+
+Passing a schema to `arkenv(schema)` (the previous `import.meta.env` define API) continues to work unchanged.

apps/playgrounds/solid-start/README.md

@@ -1,76 +1,45 @@
 # ArkEnv + SolidStart Example
 
-This example demonstrates how to use [@arkenv/vite-plugin](https://arkenv.js.org/docs/vite-plugin) with [SolidStart](https://start.solidjs.com). It showcases:
+This example demonstrates `@arkenv/vite-plugin` with [SolidStart](https://start.solidjs.com):
 
-- **Environment variable validation** at build-time with ArkEnv
-- **Typesafe `import.meta.env`** with full TypeScript support
-- **Client-side environment variables** with automatic filtering of `VITE_*` prefixed variables
+- A single `src/env.ts` is the typed source of truth (`import { env } from "./env"`)
+- **Client graph**: plugin inlines coerced `VITE_*` literals and guards server-only keys
+- **SSR graph**: `env.ts` runs as-is → boot-time validation against the real environment
+- Reading `env.DATABASE_URL` in the browser throws
 
 ## Setup
 
-The example uses a single schema definition in `app.config.ts` that defines the shape of your environment variables:
+```ts title="src/env.ts"
+import arkenv from "@arkenv/core";
+
+export const env = arkenv({
+  DATABASE_URL: "string = 'postgres://localhost:5432/solidstart'",
+  VITE_TEST: "string = 'Hello from SolidStart'",
+  VITE_NUMERIC: "string.numeric = '42'",
+  VITE_BOOLEAN: "boolean = true",
+});
+```
 
 ```ts title="app.config.ts"
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import { defineConfig } from "@solidjs/start/config";
-import { type } from "arkenv";
-
-// Define the schema
-export const Env = type({
-  VITE_TEST: "string",
-  VITE_NUMERIC: "string.numeric",
-  VITE_BOOLEAN: "boolean",
-});
 
 export default defineConfig({
   vite: {
-    // Pass the schema to the plugin
-    plugins: [arkenvVitePlugin(Env)],
+    plugins: [arkenvVitePlugin()],
   },
 });
 ```
 
-## Typesafe `import.meta.env`
-
-The example includes type augmentation for `import.meta.env` in `src/global.d.ts`. This ensures correct TypeScript inference for all variables defined in your schema.
-
-```ts title="src/global.d.ts"
-/// <reference types="@solidjs/start/env" />
-
-type ImportMetaEnvAugmented =
-  import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
-    typeof import("../app.config").Env
-  >;
-
-// Augment import.meta.env with your schema
-// Only `VITE_*` prefixed variables will be included
-interface ImportMetaEnv extends ImportMetaEnvAugmented {}
-```
-
-This makes usage in your Solid components fully typesafe:
+## Usage
 
 ```tsx
-const test = import.meta.env.VITE_TEST; // ✅ string
-const num = import.meta.env.VITE_NUMERIC; // ✅ number
-const bool = import.meta.env.VITE_BOOLEAN; // ✅ boolean
-```
-
-## Environment Variables
+import { env } from "./env";
 
-You can verify the validation by looking at the `.env.production` file (or creating a `.env` file):
-
-```env title=".env.production"
-VITE_TEST=Hello from SolidStart (Production)
-VITE_NUMERIC=3
-VITE_BOOLEAN=false
+env.VITE_TEST; // string (inlined on the client)
+env.DATABASE_URL; // throws in the browser; works on the server
 ```
 
-The plugin automatically:
-
-- Validates all variables at build-time
-- Filters to only expose `VITE_*` variables to the client
-- Ensures `import.meta.env` matches your schema
-
 ## Running the Example
 
 ```bash
@@ -89,10 +58,7 @@ pnpm start
 
 ## Documentation
 
-For more information, see the [@arkenv/vite-plugin documentation](https://arkenv.js.org/docs/vite-plugin):
-
-- [Introduction](https://arkenv.js.org/docs/vite-plugin)
+- [Vite plugin docs](https://arkenv.js.org/docs/vite-plugin)
 - [Typing import.meta.env](https://arkenv.js.org/docs/vite-plugin/typing-import-meta-env)
-- [Using ArkEnv in Vite config](https://arkenv.js.org/docs/vite-plugin/arkenv-in-viteconfig)
 
 ## this project was created with the [Solid CLI](https://github.com/solidjs-community/solid-cli)

apps/playgrounds/solid-start/app.config.ts

@@ -1,15 +1,8 @@
-import { type } from "@arkenv/core";
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import { defineConfig } from "@solidjs/start/config";
 
-export const Env = type({
-	VITE_TEST: "string",
-	VITE_NUMERIC: "string.numeric",
-	VITE_BOOLEAN: "boolean",
-});
-
 export default defineConfig({
 	vite: {
-		plugins: [arkenvVitePlugin(Env)],
+		plugins: [arkenvVitePlugin()],
 	},
 });

apps/playgrounds/solid-start/src/app.tsx

@@ -1,8 +1,13 @@
 import { createSignal } from "solid-js";
+import { isServer } from "solid-js/web";
+import { env } from "./env";
 import "./app.css";
 
+const serverDatabaseUrl = isServer ? env.DATABASE_URL : null;
+
 export default function App() {
 	const [count, setCount] = createSignal(0);
+	const [serverError, setServerError] = createSignal<string | null>(null);
 
 	return (
 		<main>
@@ -26,17 +31,43 @@ export default function App() {
 				to learn how to build SolidStart apps.
 				<br />
 				<br />
-				<code>import.meta.env.VITE_TEST</code>:{" "}
-				{String(import.meta.env.VITE_TEST)} (of type{" "}
-				{typeof import.meta.env.VITE_TEST})
+				<code>env.VITE_TEST</code>: {String(env.VITE_TEST)} (of type{" "}
+				{typeof env.VITE_TEST})
+				<br />
+				<code>env.VITE_NUMERIC</code>: {String(env.VITE_NUMERIC)} (of type{" "}
+				{typeof env.VITE_NUMERIC})
 				<br />
-				<code>import.meta.env.VITE_NUMERIC</code>:{" "}
-				{String(import.meta.env.VITE_NUMERIC)} (of type{" "}
-				{typeof import.meta.env.VITE_NUMERIC})
+				<code>env.VITE_BOOLEAN</code>: {String(env.VITE_BOOLEAN)} (of type{" "}
+				{typeof env.VITE_BOOLEAN})
 				<br />
-				<code>import.meta.env.VITE_BOOLEAN</code>:{" "}
-				{String(import.meta.env.VITE_BOOLEAN)} (of type{" "}
-				{typeof import.meta.env.VITE_BOOLEAN})
+				{serverDatabaseUrl ? (
+					<>
+						<code>env.DATABASE_URL</code> (SSR): {serverDatabaseUrl}
+						<br />
+					</>
+				) : null}
+				<br />
+				<button
+					type="button"
+					onClick={() => {
+						try {
+							void env.DATABASE_URL;
+							setServerError(null);
+						} catch (error) {
+							setServerError(
+								error instanceof Error ? error.message : String(error),
+							);
+						}
+					}}
+				>
+					Read env.DATABASE_URL on the client
+				</button>
+				{serverError() ? (
+					<>
+						<br />
+						<code>{serverError()}</code>
+					</>
+				) : null}
 			</p>
 		</main>
 	);

apps/playgrounds/solid-start/src/env.ts

@@ -0,0 +1,14 @@
+import arkenv from "@arkenv/core";
+
+/**
+ * Canonical env object for the SolidStart example.
+ * Client (`VITE_*`) keys are inlined by `@arkenv/vite-plugin` in the browser graph;
+ * server-only keys validate at boot in the SSR graph.
+ */
+export const env = arkenv({
+	DATABASE_URL: "string = 'postgres://localhost:5432/solidstart'",
+	VITE_TEST: "string = 'Hello from SolidStart'",
+	VITE_NUMERIC: "string.numeric = '42'",
+	VITE_BOOLEAN: "boolean = true",
+	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
+});

apps/playgrounds/solid-start/src/global.d.ts

@@ -1,10 +1 @@
 /// <reference types="@solidjs/start/env" />
-
-type ImportMetaEnvAugmented =
-	import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
-		typeof import("../app.config").Env
-	>;
-
-// Augment import.meta.env with your schema
-// Only `VITE_*` prefixed variables will be included
-interface ImportMetaEnv extends ImportMetaEnvAugmented {}

examples/basic-js/package.json

@@ -8,7 +8,7 @@
 		"clean": "rimraf dist node_modules"
 	},
 	"dependencies": {
-		"@arkenv/core": "1.0.0-alpha.7",
+		"@arkenv/core": "1.0.0-alpha.4",
 		"arktype": "^2.2.0"
 	},
 	"engines": {

examples/basic/package.json

@@ -9,7 +9,7 @@
 		"clean": "rimraf dist node_modules"
 	},
 	"dependencies": {
-		"@arkenv/core": "1.0.0-alpha.7",
+		"@arkenv/core": "1.0.0-alpha.4",
 		"arktype": "^2.2.0",
 		"zod": "^4.4.1"
 	},

examples/with-bun-react/package.json

@@ -12,7 +12,7 @@
 	},
 	"dependencies": {
 		"@arkenv/bun-plugin": "1.0.0-alpha.6",
-		"@arkenv/core": "1.0.0-alpha.7",
+		"@arkenv/core": "1.0.0-alpha.4",
 		"arktype": "^2.2.0",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5"

examples/with-bun/package.json

@@ -10,7 +10,7 @@
 		"clean": "rimraf dist node_modules"
 	},
 	"dependencies": {
-		"@arkenv/core": "1.0.0-alpha.7",
+		"@arkenv/core": "1.0.0-alpha.4",
 		"arktype": "^2.2.0"
 	},
 	"devDependencies": {