@matthew-hre/env 0.1.0 → 0.2.0

package/README.md

@@ -3,3 +3,69 @@
 Type safe environment variable validation for NextJS projects.
 
 > 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
+```
+
+### env.ts
+
+First, create an `env.ts` file in your project (e.g. in the `lib` folder):
+
+```ts
+// lib/env.ts
+import { z } from "zod";
+import { loadEnv } from "@matthew-hre/env";
+
+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
+
+Then, import and use the `env` object in your `next.config.js`:
+
+```js
+// next.config.js
+import type { NextConfig } from "next";
+import { env } from "src/lib/env"; // or wherever your env.ts file is
+
+const nextConfig: NextConfig = {
+  ...
+};
+
+export default nextConfig;
+```
+
+## Usage
+
+You can now use the `env` object anywhere in your NextJS project:
+
+```ts
+import { env } from "src/lib/env"; // or wherever your env.ts file is
+
+console.log(env.NEXT_PUBLIC_API_URL);
+```
+
+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.
+
+## Configuration
+
+The `loadEnv` function accepts two optional parameters: `env` and `options`.
+
+- `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.
+  - `exitOnError`: If set to `true`, the process will exit with a non-zero status code if the environment variables are invalid. Defaults to `true`.
+
+## 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,32 @@ __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) {
+var import_picocolors = __toESM(require("picocolors"), 1);
+var defaultOptions = {
+  exitOnError: true
+};
+function loadEnv(schema, env = process.env, options = defaultOptions) {
   try {
     return schema.parse(env);
   } catch (err) {
     if (err instanceof import_zod.ZodError) {
-      let message = "Invalid environment variables:\n";
+      let message = import_picocolors.default.red("Invalid environment variables:\n");
       err.issues.forEach((issue) => {
-        message += ` - ${String(issue.path[0])} (${issue.message})
+        const name = String(issue.path[0]);
+        message += ` - ${import_picocolors.default.bold(name)} ${import_picocolors.default.dim("(" + issue.message + ")")}
 `;
       });
       console.error(message);
     } 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,8 @@
 import { ZodRawShape, ZodObject, z } from 'zod';
 
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>): z.output<typeof schema>;
+interface LoadEnvOptions {
+    exitOnError?: boolean;
+}
+declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): z.output<typeof schema>;
 
 export { loadEnv };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { ZodRawShape, ZodObject, z } from 'zod';
 
-declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>): z.output<typeof schema>;
+interface LoadEnvOptions {
+    exitOnError?: boolean;
+}
+declare function loadEnv<T extends ZodRawShape>(schema: ZodObject<T>, env?: Record<string, string | undefined>, options?: LoadEnvOptions): z.output<typeof schema>;
 
 export { loadEnv };

package/dist/index.js

@@ -1,20 +1,28 @@
-// src/index.ts
+// src/core/load-env.ts
 import { ZodError } from "zod";
-function loadEnv(schema, env = process.env) {
+import pc from "picocolors";
+var defaultOptions = {
+  exitOnError: true
+};
+function loadEnv(schema, env = process.env, options = defaultOptions) {
   try {
     return schema.parse(env);
   } catch (err) {
     if (err instanceof ZodError) {
-      let message = "Invalid environment variables:\n";
+      let message = pc.red("Invalid environment variables:\n");
       err.issues.forEach((issue) => {
-        message += ` - ${String(issue.path[0])} (${issue.message})
+        const name = String(issue.path[0]);
+        message += ` - ${pc.bold(name)} ${pc.dim("(" + issue.message + ")")}
 `;
       });
       console.error(message);
     } 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,6 +1,6 @@
 {
   "name": "@matthew-hre/env",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Type safe environment variable validation for NextJS projects",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
   ],
   "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"
   },
   "keywords": [
     "nextjs",
@@ -22,12 +23,14 @@
   "author": "Matthew Hrehirchuk",
   "license": "MIT",
   "dependencies": {
+    "picocolors": "^1.1.1",
     "zod": "^4.1.9"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"