@matthew-hre/env 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @matthew-hre/env
 
-Type safe environment variable validation for NextJS projects.
+Type safe environment variable validation for NextJS projects with support for client/server separation.
 
 > This package is mostly for my own projects, and I wouldn't recommend using it yourself in its current state. It may be improved in the future. May.
 
@@ -10,14 +10,44 @@ Type safe environment variable validation for NextJS projects.
 npm install @matthew-hre/env
 ```
 
-### env.ts
+## Usage
+
+### Client/Server Schema (Recommended)
 
-First, create an `env.ts` file in your project (e.g. in the `lib` folder):
+For NextJS projects, you can separate client and server environment variables for better security and type safety:
 
 ```ts
 // lib/env.ts
+import { loadEnv } from "@matthew-hre/env";
 import { z } from "zod";
+
+const schema = {
+  server: z.object({
+    NODE_ENV: z.enum(["development", "production"]),
+    DATABASE_URL: z.string().url(),
+    SECRET_KEY: z.string(),
+  }),
+  client: z.object({
+    NEXT_PUBLIC_API_URL: z.string().url(),
+    NEXT_PUBLIC_APP_NAME: z.string(),
+  }),
+};
+
+// optionally, export the schemas for use elsewhere
+export type ServerEnvSchema = z.infer<typeof schema.server>;
+export type ClientEnvSchema = z.infer<typeof schema.client>;
+
+export const { serverEnv, clientEnv } = loadEnv(schema);
+```
+
+### Legacy Single Schema
+
+For simpler projects or backward compatibility, you can still use the original single schema format:
+
+```ts
 import { loadEnv } from "@matthew-hre/env";
+// lib/env.ts
+import { z } from "zod";
 
 const schema = z.object({
   NODE_ENV: z.string(),
@@ -32,40 +62,89 @@ export const env = loadEnv(schema);
 
 ### next.config.js
 
-Then, import and use the `env` object in your `next.config.js`:
+Import the `env` file in your `next.config.js`. This is enough to ensure the environment variables are validated at build time.
 
-```js
-// next.config.js
+```ts
+// next.config.ts
 import type { NextConfig } from "next";
-import { env } from "src/lib/env"; // or wherever your env.ts file is
+
+import "src/lib/env";
 
 const nextConfig: NextConfig = {
-  ...
+  // ...
 };
 
 export default nextConfig;
 ```
 
-## Usage
+## Examples
 
-You can now use the `env` object anywhere in your NextJS project:
+### Using Client/Server Environment Variables
 
 ```ts
-import { env } from "src/lib/env"; // or wherever your env.ts file is
+// server-side code (api routes, etc.)
+import { clientEnv, serverEnv } from "src/lib/env";
+
+export async function GET() {
+  // can access both server and client variables
+  const dbUrl = serverEnv.DATABASE_URL;
+  const apiUrl = clientEnv.NEXT_PUBLIC_API_URL;
+
+  // full type safety and autocompletion
+  return fetch(`${apiUrl}/data`, {
+    headers: { authorization: serverEnv.SECRET_KEY }
+  });
+}
+```
+
+```tsx
+// client-side code (components, hooks, etc.)
+"use client";
 
-console.log(env.NEXT_PUBLIC_API_URL);
+import { clientEnv } from "src/lib/env";
+
+export function ApiClient() {
+  // can access client variables
+  const apiUrl = clientEnv.NEXT_PUBLIC_API_URL;
+
+  return (
+    <span>
+      API URL:
+      {apiUrl}
+    </span>
+  );
+}
 ```
 
-This is type safe and will give you autocompletion based on your schema. Additionally, errors will be thrown at runtime if the environment variables do not match the schema.
+### Environment Variable Validation
+
+```ts
+const schema = {
+  server: z.object({
+    NODE_ENV: z.enum(["development", "production"]),
+    DATABASE_URL: z.url(),
+  }),
+  client: z.object({
+    NEXT_PUBLIC_API_URL: z.url(),
+  }),
+};
+```
 
 ## Configuration
 
-The `loadEnv` function accepts two optional parameters: `env` and `options`.
+The `loadEnv` function accepts optional parameters:
 
 - `env`: An object representing the environment variables to validate. Defaults to `process.env`.
-- `options`: An object containing options to customize the behavior of the `loadEnv` function.
+- `options`: An object containing options to customize the behavior:
   - `exitOnError`: If set to `true`, the process will exit with a non-zero status code if the environment variables are invalid. Defaults to `true`.
 
+```ts
+const customEnv = { NODE_ENV: "test", NEXT_PUBLIC_API_URL: "http://localhost:3000" };
+const { serverEnv, clientEnv } = loadEnv(schema, customEnv);
+
+const { serverEnv, clientEnv } = loadEnv(schema, process.env, { exitOnError: false });
+```
+
 ## License
 
 Matthew Hrehirchuk © 2025. Licensed under the MIT License.

package/dist/index.cjs

@@ -36,22 +36,96 @@ module.exports = __toCommonJS(index_exports);
 
 // src/core/load-env.ts
 var import_zod = require("zod");
+
+// src/core/error-handling.ts
 var import_picocolors = __toESM(require("picocolors"), 1);
+function handleClientServerErrors(errors, options) {
+  let message = import_picocolors.default.red("Invalid environment variables:\n");
+  errors.forEach(({ context, error }) => {
+    message += import_picocolors.default.yellow(`
+${context.toUpperCase()} variables:
+`);
+    error.issues.forEach((issue) => {
+      const name = String(issue.path[0]);
+      message += ` - ${import_picocolors.default.bold(name)} ${import_picocolors.default.dim(`(${issue.message})`)}
+`;
+    });
+  });
+  console.error(message);
+  if (options.exitOnError) {
+    process.exit(1);
+  }
+  throw errors[0].error;
+}
+function handleSingleSchemaError(error) {
+  let message = import_picocolors.default.red("Invalid environment variables:\n");
+  error.issues.forEach((issue) => {
+    const name = String(issue.path[0]);
+    message += ` - ${import_picocolors.default.bold(name)} ${import_picocolors.default.dim(`(${issue.message})`)}
+`;
+  });
+  console.error(message);
+}
+
+// src/core/load-env.ts
 var defaultOptions = {
   exitOnError: true
 };
 function loadEnv(schema, env = process.env, options = defaultOptions) {
+  if (isClientServerSchema(schema)) {
+    return parseClientServerSchema(schema, env, options);
+  } else {
+    return parseSingleSchema(schema, env, options);
+  }
+}
+function isClientServerSchema(schema) {
+  return typeof schema === "object" && schema !== null && "server" in schema && "client" in schema && schema.server instanceof import_zod.ZodObject && schema.client instanceof import_zod.ZodObject;
+}
+function parseClientServerSchema(schema, env, options) {
+  const errors = [];
+  let serverEnv;
+  let clientEnv;
+  const isServer = typeof window === "undefined";
+  if (isServer) {
+    try {
+      serverEnv = schema.server.parse(env);
+    } catch (err) {
+      if (err instanceof import_zod.ZodError) {
+        errors.push({ context: "server", error: err });
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    serverEnv = new Proxy({}, {
+      get: () => {
+        throw new Error("\u274C Attempted to access a server-side environment variable on the client");
+      }
+    });
+  }
+  const clientEnv_variables = Object.fromEntries(
+    Object.entries(env).filter(([key]) => key.startsWith("NEXT_PUBLIC_"))
+  );
+  try {
+    clientEnv = schema.client.parse(clientEnv_variables);
+  } catch (err) {
+    if (err instanceof import_zod.ZodError) {
+      errors.push({ context: "client", error: err });
+    } else {
+      throw err;
+    }
+  }
+  if (errors.length > 0) {
+    handleClientServerErrors(errors, options);
+  }
+  return { serverEnv, clientEnv };
+}
+function parseSingleSchema(schema, env, options) {
   try {
     return schema.parse(env);
   } catch (err) {
     if (err instanceof import_zod.ZodError) {
-      let message = import_picocolors.default.red("Invalid environment variables:\n");
-      err.issues.forEach((issue) => {
-        const name = String(issue.path[0]);
-        message += ` - ${import_picocolors.default.bold(name)} ${import_picocolors.default.dim("(" + issue.message + ")")}
-`;
-      });
-      console.error(message);
+      handleSingleSchemaError(err);
     } else {
       console.error("Unexpected error while parsing env:", err);
     }

package/dist/index.d.cts

@@ -1,8 +1,22 @@
-import { ZodRawShape, ZodObject, z } from 'zod';
+import { ZodObject, z, ZodRawShape } from 'zod';
 
-interface LoadEnvOptions {
+type LoadEnvOptions = {
     exitOnError?: boolean;
-}
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): z.output<typeof schema>;
+};
+type ClientServerSchema = {
+    server: ZodObject<any>;
+    client: ZodObject<any>;
+};
+type IsClientServerSchema<T> = T extends ClientServerSchema ? true : false;
+type LoadEnvResult<T> = IsClientServerSchema<T> extends true ? T extends {
+    server: infer S;
+    client: infer C;
+} ? S extends ZodObject<any> ? C extends ZodObject<any> ? {
+    serverEnv: z.output<S>;
+    clientEnv: z.output<C>;
+} : never : never : never : T extends ZodObject<infer R> ? z.output<ZodObject<R>> : never;
 
-export { loadEnv };
+declare function loadEnv<T extends ClientServerSchema>(schema: T, env?: Record<string, string | undefined>, options?: LoadEnvOptions): LoadEnvResult<T>;
+declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): LoadEnvResult<ZodObject<T>>;
+
+export { type ClientServerSchema, type LoadEnvOptions, type LoadEnvResult, loadEnv };

package/dist/index.d.ts

@@ -1,8 +1,22 @@
-import { ZodRawShape, ZodObject, z } from 'zod';
+import { ZodObject, z, ZodRawShape } from 'zod';
 
-interface LoadEnvOptions {
+type LoadEnvOptions = {
     exitOnError?: boolean;
-}
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): z.output<typeof schema>;
+};
+type ClientServerSchema = {
+    server: ZodObject<any>;
+    client: ZodObject<any>;
+};
+type IsClientServerSchema<T> = T extends ClientServerSchema ? true : false;
+type LoadEnvResult<T> = IsClientServerSchema<T> extends true ? T extends {
+    server: infer S;
+    client: infer C;
+} ? S extends ZodObject<any> ? C extends ZodObject<any> ? {
+    serverEnv: z.output<S>;
+    clientEnv: z.output<C>;
+} : never : never : never : T extends ZodObject<infer R> ? z.output<ZodObject<R>> : never;
 
-export { loadEnv };
+declare function loadEnv<T extends ClientServerSchema>(schema: T, env?: Record<string, string | undefined>, options?: LoadEnvOptions): LoadEnvResult<T>;
+declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): LoadEnvResult<ZodObject<T>>;
+
+export { type ClientServerSchema, type LoadEnvOptions, type LoadEnvResult, loadEnv };

package/dist/index.js

@@ -1,21 +1,95 @@
 // src/core/load-env.ts
-import { ZodError } from "zod";
+import { ZodError, ZodObject } from "zod";
+
+// src/core/error-handling.ts
 import pc from "picocolors";
+function handleClientServerErrors(errors, options) {
+  let message = pc.red("Invalid environment variables:\n");
+  errors.forEach(({ context, error }) => {
+    message += pc.yellow(`
+${context.toUpperCase()} variables:
+`);
+    error.issues.forEach((issue) => {
+      const name = String(issue.path[0]);
+      message += ` - ${pc.bold(name)} ${pc.dim(`(${issue.message})`)}
+`;
+    });
+  });
+  console.error(message);
+  if (options.exitOnError) {
+    process.exit(1);
+  }
+  throw errors[0].error;
+}
+function handleSingleSchemaError(error) {
+  let message = pc.red("Invalid environment variables:\n");
+  error.issues.forEach((issue) => {
+    const name = String(issue.path[0]);
+    message += ` - ${pc.bold(name)} ${pc.dim(`(${issue.message})`)}
+`;
+  });
+  console.error(message);
+}
+
+// src/core/load-env.ts
 var defaultOptions = {
   exitOnError: true
 };
 function loadEnv(schema, env = process.env, options = defaultOptions) {
+  if (isClientServerSchema(schema)) {
+    return parseClientServerSchema(schema, env, options);
+  } else {
+    return parseSingleSchema(schema, env, options);
+  }
+}
+function isClientServerSchema(schema) {
+  return typeof schema === "object" && schema !== null && "server" in schema && "client" in schema && schema.server instanceof ZodObject && schema.client instanceof ZodObject;
+}
+function parseClientServerSchema(schema, env, options) {
+  const errors = [];
+  let serverEnv;
+  let clientEnv;
+  const isServer = typeof window === "undefined";
+  if (isServer) {
+    try {
+      serverEnv = schema.server.parse(env);
+    } catch (err) {
+      if (err instanceof ZodError) {
+        errors.push({ context: "server", error: err });
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    serverEnv = new Proxy({}, {
+      get: () => {
+        throw new Error("\u274C Attempted to access a server-side environment variable on the client");
+      }
+    });
+  }
+  const clientEnv_variables = Object.fromEntries(
+    Object.entries(env).filter(([key]) => key.startsWith("NEXT_PUBLIC_"))
+  );
+  try {
+    clientEnv = schema.client.parse(clientEnv_variables);
+  } catch (err) {
+    if (err instanceof ZodError) {
+      errors.push({ context: "client", error: err });
+    } else {
+      throw err;
+    }
+  }
+  if (errors.length > 0) {
+    handleClientServerErrors(errors, options);
+  }
+  return { serverEnv, clientEnv };
+}
+function parseSingleSchema(schema, env, options) {
   try {
     return schema.parse(env);
   } catch (err) {
     if (err instanceof ZodError) {
-      let message = pc.red("Invalid environment variables:\n");
-      err.issues.forEach((issue) => {
-        const name = String(issue.path[0]);
-        message += ` - ${pc.bold(name)} ${pc.dim("(" + issue.message + ")")}
-`;
-      });
-      console.error(message);
+      handleSingleSchemaError(err);
     } else {
       console.error("Unexpected error while parsing env:", err);
     }

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@matthew-hre/env",
-  "version": "0.2.0",
-  "description": "Type safe environment variable validation for NextJS projects",
   "type": "module",
+  "version": "0.3.1",
+  "description": "Type safe environment variable validation for NextJS projects",
+  "author": "Matthew Hrehirchuk",
+  "license": "MIT",
+  "keywords": [
+    "nextjs",
+    "zod",
+    "env",
+    "typed",
+    "validation"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -11,28 +20,28 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts --watch --dts",
-    "test": "vitest"
+    "test": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint ."
   },
-  "keywords": [
-    "nextjs",
-    "zod",
-    "env",
-    "typed",
-    "validation"
-  ],
-  "author": "Matthew Hrehirchuk",
-  "license": "MIT",
   "dependencies": {
     "picocolors": "^1.1.1",
     "zod": "^4.1.9"
   },
   "devDependencies": {
+    "@antfu/eslint-config": "^5.4.1",
+    "@eslint/js": "^9.36.0",
     "@types/node": "^24.5.2",
+    "eslint": "^9.36.0",
+    "eslint-plugin-format": "^1.0.2",
+    "globals": "^16.4.0",
+    "jiti": "^2.5.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
+    "typescript-eslint": "^8.44.0",
     "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}