Customization

Below are examples of how you can customize the behavior of envin. The default values are shown in the snippets below.

Skipping validation

Skipping validation is not encouraged and will lead to your types and runtime values being out of sync. It is available to let you opt out of validation during linting (or similar), or if you're building with Docker and not all environment variables are present when building the image.

env.config.ts

import { defineEnv } from "envin";

export default defineEnv({
  // ... your schema
  // Tell the library to skip validation if condition is true.
  skip: process.env.SKIP_ENV_VALIDATION === "true",
});

When skipping validation, the default values are still used when possible. This is useful for development environments where you want to use the default values but still have the type safety.

Custom error handling

You can customize how validation errors and invalid access attempts are handled:

env.config.ts

import { defineEnv } from "envin";

export default defineEnv({
  // ... your schema
  // Called when the schema validation fails.
  onError: issues => {
    console.error("❌ Invalid environment variables:", issues);
    process.exit(1);
  },
  // Called when server variables are accessed on the client.
  onInvalidAccess: variable => {
    throw new Error(
      `❌ Attempted to access server variable "${variable}" on the client`
    );
  },
});

Server context detection

Tell the library when we're in a server context. This is used to determine whether server-side environment variables should be accessible:

env.config.ts

import { defineEnv } from "envin";

export default defineEnv({
  // ... your schema
  // Tell the library when we're in a server context.
  isServer: typeof window === "undefined",
});

Extending presets

Your env object may extend other presets by using the extends property. This can be used to include system environment variables for your deployment provider, or if you have a monorepo with multiple packages that share some environment variables.

env.config.ts

import { defineEnv } from "envin";
import { vercel } from "envin/presets/zod";

export const env = defineEnv({
  // ... your schema
  // Extend the Vercel preset.
  extends: [vercel],
});

env.VERCEL_URL;       
VERCEL_URL?: string | undefined

envin ships the following presets out of the box, all importable from the /presets entrypoint:

vercel - Vercel environment variables. See full list.
neonVercel - Neon for Vercel environment variables. See full list.
uploadthing - UploadThing environment variables. See full list.
render - Render environment variables. See full list.
railway - Railway provided system environment variables. See full list.
fly - Fly.io provided machine runtime environment variables. See full list.
netlify - Netlify provided system environment variables. See full list.
upstashRedis - Upstash Redis environment variables. See full list.
coolify - Coolify environment variables. See full list.
supabaseVercel - Supabase for Vercel environment variables. See full list.
vite - Vite environment variables. See full list.
wxt - WXT environment variables. See full list.

Feel free to open a PR with more presets!

A preset is just like any other envin configuration object, so you can easily create your own:

env.config.ts

import { defineEnv } from "envin";
import { z } from "zod";

const stripe = {
  clientPrefix: "NEXT_PUBLIC_",
  client: {
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().min(1),
  },
  server: {
    STRIPE_SECRET_KEY: z.string().min(1),
    STRIPE_WEBHOOK_SECRET: z.string().min(1),
  },
} as const;

const env = defineEnv({
  // ... your schema
  extends: [stripe],
});

env.STRIPE_SECRET_KEY;          
type STRIPE_SECRET_KEY: string

You can use custom transformations to process environment variables or add complex validation logic:

env.config.ts

import { defineEnv } from "envin";
import { z } from "zod";

const env = defineEnv({
  server: {
    // Transform string to number with default
    PORT: z.string().transform(Number).default("3000"),
    // Transform comma-separated string to array
    FEATURE_FLAGS: z.string().transform(s => s.split(",")),
    // Complex validation with refinement
    DATABASE_URL: z
      .string()
      .url()
      .refine(
        url => url.startsWith("postgresql://"),
        "Database URL must be a PostgreSQL connection string"
      ),
    // Conditional validation
    SKIP_AUTH: z.boolean().optional(),
    EMAIL: z.string().email().optional(),
    PASSWORD: z.string().min(1).optional(),
  },
  env: process.env,
  // Custom schema transformation for complex interdependent validation
  transform: (shape, isServer) =>
    z.object(shape).transform((env, ctx) => {
      if (env.SKIP_AUTH || !isServer) return { SKIP_AUTH: true } as const;
      if (!env.EMAIL || !env.PASSWORD) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: "EMAIL and PASSWORD are required if SKIP_AUTH is false",
        });
        return z.NEVER;
      }
      return {
        EMAIL: env.EMAIL,
        PASSWORD: env.PASSWORD,
      };
    }),
});

env.SKIP_AUTH;      
SKIP_AUTH?: true | undefined

Customization

Skipping validation

Custom error handling

Server context detection

Extending presets

Custom transformations and refinements

On this page