feat: add callback functions to override default behavior (#3)

* add callback functions to override default behavior

* changeset

* refactor

.changeset/late-rockets-clap.md

@@ -0,0 +1,6 @@
+---
+"@t3-oss/env-nextjs": minor
+"@t3-oss/env-core": minor
+---
+
+adds callback functions that allows overriding the default behavior when validation fails or variables are illegally accessed

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

@@ -19,15 +19,13 @@ export const env = createEnv({
 
 ## Overriding the default error handler
 
-<Callout type="info">This option is not released just yet.</Callout>
-
 ```ts title="src/env.ts"
 import { createEnv } from "@t3-oss/env-core";
 
 export const env = createEnv({
   // ...
   // Called when the schema validation fails.
-  onValidationFail: (error: ZodError) => {
+  onValidationError: (error: ZodError) => {
     console.error(
       "❌ Invalid environment variables:",
       parsed.error.flatten().fieldErrors

examples/nextjs/next.config.mjs

@@ -1,4 +1,4 @@
-// import { env as _env } from "./app/env.mjs";
+import { env as _ } from "./app/env.mjs";
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {

examples/nextjs/tsconfig.json

@@ -24,6 +24,6 @@
       "~/*": ["./app/*"]
     }
   },
-  "include": ["next-env.d.ts", "app", ".next/types/**/*.ts"],
+  "include": ["next-env.d.ts", "app", ".next/types/**/*.ts", "next.config.mjs"],
   "exclude": ["node_modules"]
 }

packages/core/index.ts

@@ -1,4 +1,4 @@
-import z, { ZodObject, ZodType } from "zod";
+import z, { type ZodError, type ZodObject, type ZodType } from "zod";
 
 export type ErrorMessage<T extends string> = T;
 
@@ -36,6 +36,18 @@ export interface BaseOptions<
    */
   isServer?: boolean;
 
+  /**
+   * Called when validation fails. By default the error is logged,
+   * and an error is thrown telling what environment variables are invalid.
+   */
+  onValidationError?: (error: ZodError) => never;
+
+  /**
+   * Called when a server-side environment variable is accessed on the client.
+   * By default an error is thrown.
+   */
+  onInvalidAccess?: (variable: string) => never;
+
   /**
    * Whether to skip validation of environment variables.
    * @default !!process.env.SKIP_ENV_VALIDATION && process.env.SKIP_ENV_VALIDATION !== "false" && process.env.SKIP_ENV_VALIDATION !== "0"
@@ -86,40 +98,54 @@ export function createEnv<
     | LooseOptions<TPrefix, TServer, TClient>
     | StrictOptions<TPrefix, TServer, TClient>
 ): z.infer<ZodObject<TServer>> & z.infer<ZodObject<TClient>> {
-  const _client = typeof opts.client === "object" ? opts.client : {};
-  const client = z.object(_client);
-  const server = z.object(opts.server);
   const runtimeEnv = opts.runtimeEnvStrict ?? opts.runtimeEnv ?? process.env;
-  const isServer = opts.isServer ?? typeof window === "undefined";
+
   const skip =
     opts.skipValidation ??
     (!!process.env.SKIP_ENV_VALIDATION &&
       process.env.SKIP_ENV_VALIDATION !== "false" &&
       process.env.SKIP_ENV_VALIDATION !== "0");
-
   // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-explicit-any
   if (skip) return runtimeEnv as any;
 
+  const _client = typeof opts.client === "object" ? opts.client : {};
+  const client = z.object(_client);
+  const server = z.object(opts.server);
+  const isServer = opts.isServer ?? typeof window === "undefined";
+
   const merged = server.merge(client);
   const parsed = isServer
     ? merged.safeParse(runtimeEnv) // on server we can validate all env vars
     : client.safeParse(runtimeEnv); // on client we can only validate the ones that are exposed
 
+  const onValidationError =
+    opts.onValidationError ??
+    ((error: ZodError) => {
+      console.error(
+        "❌ Invalid environment variables:",
+        error.flatten().fieldErrors
+      );
+      throw new Error("Invalid environment variables");
+    });
+
+  const onInvalidAccess =
+    opts.onInvalidAccess ??
+    ((_variable: string) => {
+      throw new Error(
+        "❌ Attempted to access a server-side environment variable on the client"
+      );
+    });
+
   if (parsed.success === false) {
-    console.error(
-      "❌ Invalid environment variables:",
-      parsed.error.flatten().fieldErrors
-    );
-    throw new Error("Invalid environment variables");
+    return onValidationError(parsed.error);
   }
 
   const env = new Proxy(parsed.data, {
     get(target, prop) {
       if (typeof prop !== "string") return undefined;
-      if (!isServer && !prop.startsWith(opts.clientPrefix))
-        throw new Error(
-          "❌ Attempted to access a server-side environment variable on the client"
-        );
+      if (!isServer && !prop.startsWith(opts.clientPrefix)) {
+        return onInvalidAccess(prop);
+      }
       return target[prop as keyof typeof target];
     },
   });

packages/nextjs/index.ts

@@ -1,4 +1,4 @@
-import type { ZodType } from "zod";
+import type { z, ZodType } from "zod";
 import { createEnv as createEnvCore, type ErrorMessage } from "../core";
 
 export function createEnv<
@@ -42,6 +42,19 @@ export function createEnv<
    * @default !!process.env.SKIP_ENV_VALIDATION && process.env.SKIP_ENV_VALIDATION !== "false" && process.env.SKIP_ENV_VALIDATION !== "0"
    */
   skipValidation?: boolean;
+
+  /**
+   * Called when validation fails. By default the error is logged,
+   * and an error is thrown telling what environment variables are invalid.
+   * Function must throw an error at the end.
+   */
+  onValidationError?: (error: z.ZodError) => never;
+
+  /**
+   * Called when a server-side environment variable is accessed on the client.
+   * By default an error is thrown.
+   */
+  onInvalidAccess?: (variable: string) => never;
 }) {
   return createEnvCore({
     ...opts,