@matthew-hre/env 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,150 @@
 # @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.
+
+## Installation
+
+```bash
+npm install @matthew-hre/env
+```
+
+## Usage
+
+### Client/Server Schema (Recommended)
+
+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(),
+  NEXT_PUBLIC_API_URL: z.url(),
+});
+
+// optionally, export the schema for use elsewhere
+export type EnvSchema = z.infer<typeof schema>;
+
+export const env = loadEnv(schema);
+```
+
+### 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.
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+import "src/lib/env";
+
+const nextConfig: NextConfig = {
+  // ...
+};
+
+export default nextConfig;
+```
+
+## Examples
+
+### Using Client/Server Environment Variables
+
+```ts
+// 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";
+
+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>
+  );
+}
+```
+
+### 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 optional parameters:
+
+- `env`: An object representing the environment variables to validate. Defaults to `process.env`.
+- `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

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -23,22 +33,97 @@ __export(index_exports, {
   loadEnv: () => loadEnv
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/core/load-env.ts
 var import_zod = require("zod");
-function loadEnv(schema, env = process.env) {
+
+// 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;
+  try {
+    serverEnv = schema.server.parse(env);
+  } catch (err) {
+    if (err instanceof import_zod.ZodError) {
+      errors.push({ context: "server", error: err });
+    } else {
+      throw err;
+    }
+  }
+  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 = "Invalid environment variables:\n";
-      err.issues.forEach((issue) => {
-        message += ` - ${String(issue.path[0])} (${issue.message})
-`;
-      });
-      console.error(message);
+      handleSingleSchemaError(err);
     } else {
       console.error("Unexpected error while parsing env:", err);
     }
-    process.exit(1);
+    if (options.exitOnError) {
+      process.exit(1);
+    }
+    throw err;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -1,5 +1,22 @@
-import { ZodRawShape, ZodObject, z } from 'zod';
+import { ZodObject, z, ZodRawShape } from 'zod';
 
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>): z.output<typeof schema>;
+type LoadEnvOptions = {
+    exitOnError?: boolean;
+};
+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,5 +1,22 @@
-import { ZodRawShape, ZodObject, z } from 'zod';
+import { ZodObject, z, ZodRawShape } from 'zod';
 
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>): z.output<typeof schema>;
+type LoadEnvOptions = {
+    exitOnError?: boolean;
+};
+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,20 +1,93 @@
-// src/index.ts
-import { ZodError } from "zod";
-function loadEnv(schema, env = process.env) {
+// src/core/load-env.ts
+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;
+  try {
+    serverEnv = schema.server.parse(env);
+  } catch (err) {
+    if (err instanceof ZodError) {
+      errors.push({ context: "server", error: err });
+    } else {
+      throw err;
+    }
+  }
+  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 = "Invalid environment variables:\n";
-      err.issues.forEach((issue) => {
-        message += ` - ${String(issue.path[0])} (${issue.message})
-`;
-      });
-      console.error(message);
+      handleSingleSchemaError(err);
     } else {
       console.error("Unexpected error while parsing env:", err);
     }
-    process.exit(1);
+    if (options.exitOnError) {
+      process.exit(1);
+    }
+    throw err;
   }
 }
 export {

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@matthew-hre/env",
-  "version": "0.1.0",
-  "description": "Type safe environment variable validation for NextJS projects",
   "type": "module",
+  "version": "0.3.0",
+  "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": [
@@ -10,26 +19,29 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts --watch --dts"
+    "dev": "tsup src/index.ts --watch --dts",
+    "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": "^5.9.2",
+    "typescript-eslint": "^8.44.0",
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}