Support all standard schema libraries (#299)

Co-authored-by: juliusmarminge <[email protected]>

.changeset/fair-rats-hammer.md

@@ -0,0 +1,15 @@
+---
+"@t3-oss/env-nextjs": minor
+"@t3-oss/env-core": minor
+"@t3-oss/env-nuxt": minor
+---
+
+feat!: support standard schema
+
+Validators can now be any validator that supports [Standard Schema](https://github.com/standard-schema/standard-schema),
+for example Zod & Valibot.
+
+This feature comes with some breaking changes:
+
+- If using Zod, the minimum required version is now 3.24.
+- `onValidationError` now gets `StandardSchemaV1.Issue[]` instead of `ZodError`

.github/workflows/main.yml

@@ -51,4 +51,5 @@ jobs:
         uses: actions/checkout@v4
       - uses: ./.github/setup
 
-      - run: bun test
+      - run: bun turbo run build --filter=@t3-oss/env*
+      - run: bun test

README.md

@@ -76,4 +76,4 @@ export const GET = (req: Request) => {
 
 ## Roadmap
 
-- [ ] Bring your own validation library - currently only supports Zod.
+- [x] Bring your own validation library - now supports any [Standard Schema library](https://github.com/standard-schema/standard-schema?tab=readme-ov-file#what-schema-libraries-implement-the-spec)

bun.lock

@@ -57,6 +57,19 @@
         "vite": "^6.0.1",
       },
     },
+    "examples/astro-valibot": {
+      "name": "@examples/astro-valibot",
+      "dependencies": {
+        "@astrojs/solid-js": "^5.0.4",
+        "@t3-oss/env-core": "workspace:*",
+        "astro": "^5.1.9",
+        "solid-js": "^1.9.4",
+        "valibot": "^1.0.0-beta.14",
+      },
+      "devDependencies": {
+        "vite": "^6.0.1",
+      },
+    },
     "examples/nextjs": {
       "name": "@examples/nextjs",
       "dependencies": {
@@ -91,14 +104,16 @@
       "devDependencies": {
         "bunchee": "^6.3.2",
         "typescript": "^5.7.3",
+        "valibot": "^1.0.0-beta.14",
         "zod": "^3.24.1",
       },
       "peerDependencies": {
         "typescript": ">=5.0.0",
-        "zod": "^3.0.0",
+        "zod": "^3.24.0",
       },
       "optionalPeers": [
         "typescript",
+        "zod",
       ],
     },
     "packages/nextjs": {
@@ -114,10 +129,11 @@
       },
       "peerDependencies": {
         "typescript": ">=5.0.0",
-        "zod": "^3.0.0",
+        "zod": "^3.24.0",
       },
       "optionalPeers": [
         "typescript",
+        "zod",
       ],
     },
     "packages/nuxt": {
@@ -133,10 +149,11 @@
       },
       "peerDependencies": {
         "typescript": ">=5.0.0",
-        "zod": "^3.0.0",
+        "zod": "^3.24.0",
       },
       "optionalPeers": [
         "typescript",
+        "zod",
       ],
     },
   },
@@ -343,6 +360,8 @@
 
     "@examples/astro": ["@examples/astro@workspace:examples/astro"],
 
+    "@examples/astro-valibot": ["@examples/astro-valibot@workspace:examples/astro-valibot"],
+
     "@examples/nextjs": ["@examples/nextjs@workspace:examples/nextjs"],
 
     "@examples/nuxt": ["@examples/nuxt@workspace:examples/nuxt"],
@@ -2459,6 +2478,8 @@
 
     "util-deprecate": ["[email protected]", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
+    "valibot": ["[email protected]", "", { "peerDependencies": { "typescript": ">=5" }, "optionalPeers": ["typescript"] }, "sha512-tLyV2rE5QL6U29MFy3xt4AqMrn+/HErcp2ZThASnQvPMwfSozjV1uBGKIGiegtZIGjinJqn0SlBdannf18wENA=="],
+
     "validate-html-nesting": ["[email protected]", "", {}, "sha512-hGdgQozCsQJMyfK5urgFcWEqsSSrK63Awe0t/IMR0bZ0QMtnuaiHzThW81guu3qx9abLi99NEuiaN6P9gVYsNg=="],
 
     "validate-npm-package-license": ["[email protected]", "", { "dependencies": { "spdx-correct": "^3.0.0", "spdx-expression-parse": "^3.0.0" } }, "sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew=="],

docs/src/app/docs/core/page.mdx

@@ -20,6 +20,12 @@ npm install @t3-oss/env-core zod
 
 <Callout>
 
+Although we'll use Zod as examples throughout these docs, you can use any validator that supports [Standard Schema](https://github.com/standard-schema/standard-schema).
+
+</Callout>
+
+<Callout>
+
 `@t3-oss/env-core` requires a minimum of `[email protected]`.
 
 </Callout>

docs/src/app/docs/customization/page.mdx

@@ -34,10 +34,10 @@ import { createEnv } from "@t3-oss/env-core";
 export const env = createEnv({
   // ...
   // Called when the schema validation fails.
-  onValidationError: (error: ZodError) => {
+  onValidationError: (issues: StandardSchemaV1.Issue[]) => {
     console.error(
       "❌ Invalid environment variables:",
-      error.flatten().fieldErrors
+      issues
     );
     throw new Error("Invalid environment variables");
   },

docs/src/app/docs/nextjs/page.mdx

@@ -19,6 +19,12 @@ pnpm add @t3-oss/env-nextjs zod
 
 <Callout>
 
+Although we'll use Zod as examples throughout these docs, you can use any validator that supports [Standard Schema](https://github.com/standard-schema/standard-schema).
+
+</Callout>
+
+<Callout>
+
 `@t3-oss/env-nextjs` requires a minimum of `[email protected]`.
 
 </Callout>

docs/src/app/docs/nuxt/page.mdx

@@ -20,6 +20,12 @@ pnpm add @t3-oss/env-nuxt zod
 
 <Callout>
 
+Although we'll use Zod as examples throughout these docs, you can use any validator that supports [Standard Schema](https://github.com/standard-schema/standard-schema).
+
+</Callout>
+
+<Callout>
+
 `@t3-oss/env-core` requires a minimum of `typescript@5`.
 
 </Callout>

examples/astro-valibot/.env

@@ -0,0 +1,2 @@
+PORT=3000
+PUBLIC_API_URL=http://localhost:3000

examples/astro-valibot/astro.config.mjs

@@ -0,0 +1,8 @@
+import { defineConfig } from "astro/config";
+
+import solidJs from "@astrojs/solid-js";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [solidJs()],
+});

examples/astro-valibot/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@examples/astro-valibot",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "astro build",
+    "dev": "astro dev",
+    "preview": "astro preview",
+    "start": "astro dev"
+  },
+  "dependencies": {
+    "@astrojs/solid-js": "^5.0.4",
+    "@t3-oss/env-core": "workspace:*",
+    "astro": "^5.1.9",
+    "solid-js": "^1.9.4",
+    "valibot": "^1.0.0-beta.14"
+  },
+  "devDependencies": {
+    "vite": "^6.0.1"
+  }
+}

examples/astro-valibot/src/counter.tsx

@@ -0,0 +1,6 @@
+import { env } from "./t3-env";
+
+export function ClientComponent() {
+  // Try changing PUBLIC_API_URL to PORT - the component will throw
+  return <div>Client API Url:{env.PUBLIC_API_URL}</div>;
+}

examples/astro-valibot/src/pages/index.astro

@@ -0,0 +1,18 @@
+---
+import { ClientComponent } from "../counter";
+import { env } from "../t3-env";
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<h1>Astro</h1>
+		<p>PORT: {env.PORT}</p>
+		<ClientComponent client:only />
+	</body>
+</html>

examples/astro-valibot/src/t3-env.ts

@@ -0,0 +1,17 @@
+import { createEnv } from "@t3-oss/env-core";
+import { string } from "valibot";
+
+export const env = createEnv({
+  server: {
+    PORT: string(),
+  },
+  client: {
+    PUBLIC_API_URL: string(),
+  },
+  // Astro bundles all environment variables so
+  // we don't need to manually destructure them
+  runtimeEnv: import.meta.env,
+  // process is not available in Astro, so we must set this explicitly
+  skipValidation: import.meta.env.SKIP_ENV_VALIDATION === "development",
+  clientPrefix: "PUBLIC_",
+});

examples/astro-valibot/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "astro/tsconfigs/strictest",
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "types": ["astro/client"]
+  },
+  "include": ["src", "astro.config.mjs"]
+}

packages/core/package.json

@@ -29,16 +29,20 @@
   },
   "peerDependencies": {
     "typescript": ">=5.0.0",
-    "zod": "^3.0.0"
+    "zod": "^3.24.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
     "bunchee": "^6.3.2",
     "typescript": "^5.7.3",
-    "zod": "^3.24.1"
+    "zod": "^3.24.1",
+    "valibot": "^1.0.0-beta.14"
   }
 }