Envin

https://envin.turbostarter.dev/docs
Admin
Envin is a framework-agnostic, type-safe tool for validating and previewing environment variables...
Tokens:9,777
Snippets:29
Trust Score:7.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Envin Client Prefix Type Error Example

Source: https://envin.turbostarter.dev/docs/installation

Demonstrates a type error that occurs when a client-side environment variable is not prefixed correctly according to the `clientPrefix` defined in the envin configuration. This highlights envin's type safety features.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

export default defineEnv({
  clientPrefix: "PUBLIC_",
  client: {
    VITE_PUBLIC_API_URL: z.url(),
Type 'ZodURL' is not assignable to type '"VITE_PUBLIC_API_URL is not prefixed with PUBLIC_."'.
  },
  env: process.env,
});
```

--------------------------------

### Install envin Core Package

Source: https://envin.turbostarter.dev/docs/installation

Installs the core envin package using npm, yarn, or bun. This is the first step to using envin for environment variable management.

```bash
npm install envin
```

```bash
yarn add envin
```

```bash
bun add envin
```

--------------------------------

### Define Strict Environment Variables with Zod

Source: https://envin.turbostarter.dev/docs/installation

Provides an example of defining environment variables using `defineEnv` from 'envin' and Zod for validation. This configuration includes server and client variables, a client prefix, and the `envStrict` option to ensure all variables are explicitly accessed.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

export default defineEnv({
  server: {
    DATABASE_URL: z.url(),
    OPENAI_API_KEY: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
  clientPrefix: "NEXT_PUBLIC_",
  /**
   * Makes sure you explicitly access **all** environment variables
   * from `server` and `client` in your `envStrict`.
   */
  envStrict: {
Property 'DATABASE_URL' is missing in type '{ OPENAI_API_KEY: string | undefined; NEXT_PUBLIC_PUBLISHABLE_KEY: string | undefined; }' but required in type 'Record<"DATABASE_URL" | "OPENAI_API_KEY" | "NEXT_PUBLIC_PUBLISHABLE_KEY", string | number | boolean | undefined>'.
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
  },
});
```

--------------------------------

### Define Full Environment Schema with envin and Zod

Source: https://envin.turbostarter.dev/docs/installation

Defines a comprehensive environment schema using envin and Zod, including shared, server, and client-side variables with a specified client prefix. This example demonstrates how to configure NODE_ENV, DATABASE_URL, OPENAI_API_KEY, JWT_SECRET, and NEXT_PUBLIC_PUBLISHABLE_KEY.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

const env = defineEnv({
     
const env: { // This is a type definition, not executable code
    readonly NODE_ENV: "development" | "production" | "test";
    readonly DATABASE_URL: string;
    readonly OPENAI_API_KEY: string;
    readonly JWT_SECRET: string;
    readonly NEXT_PUBLIC_PUBLISHABLE_KEY: string;
    readonly _schema: FinalSchema<...>;
}


/** * Specify environment variables that can be accessed on both client and server. * You'll get a type error if you try to access a server-side env var on the client. */ shared: { NODE_ENV: z .enum(["development", "production", "test"])
 .default("development"), }, /** * Specify your server-side environment variables schema here. * This way you can ensure the app isn't built with invalid env vars. */ server: { DATABASE_URL: z.url(), OPENAI_API_KEY: z.string().min(1), JWT_SECRET: z.string().min(32), }, /** * The prefix that client-side variables must have. This is enforced both at * a type-level and at runtime. */ clientPrefix: "NEXT_PUBLIC_", /** * Specify your client-side environment variables schema here. * For them to be exposed to the client, prefix them with your framework's public prefix. */ client: { NEXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1), }, /** * What object holds the environment variables at runtime. * This is usually `process.env` or `import.meta.env`. */ env: process.env,
});

export default env;
```

--------------------------------

### Use Environment Variables in API Route

Source: https://envin.turbostarter.dev/docs/installation

Shows how to import and use environment variables with full type-safety and auto-completion within a Next.js API route. It includes an example of making a fetch request using an API key and checking the node environment.

```typescript
import env from "~/env.config";

export async function POST() {
  // ✅ Fully typed and validated
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    headers: {
      Authorization: `Bearer ${env.OPENAI_API_KEY}`, // string
    },
  });

  // ✅ Access shared variables anywhere
  if (env.NODE_ENV === "development") {
    console.log("Development mode");
  }

  return Response.json({ success: true });
}
```

--------------------------------

### Install Zod Schema Validator

Source: https://envin.turbostarter.dev/docs/installation

Installs the Zod library, a popular schema validator compatible with envin. Zod helps define and validate environment variable schemas.

```bash
npm install zod
```

```bash
yarn add zod
```

```bash
bun add zod
```

--------------------------------

### Validate Schema on Build (Next.js)

Source: https://envin.turbostarter.dev/docs/installation

Demonstrates how to import environment configuration in `next.config.ts` to validate your schema during the Next.js build process. This ensures that your environment variables are correctly set before deployment.

```typescript
import type { NextConfig } from "next";
import "./env.config";

const nextConfig: NextConfig = {
  // Your Next.js config
};

export default nextConfig;
```

--------------------------------

### Launch Live Preview with Envin CLI

Source: https://envin.turbostarter.dev/docs/live-preview

Launches the Envin CLI to start a local server for live previewing environment variables. The CLI reads configuration and environment files to display variables in real-time. It defaults to port 3000 but can be configured with a custom port.

```bash
npx @envin/cli dev
```

--------------------------------

### Define Separate Server and Client Schemas

Source: https://envin.turbostarter.dev/docs/installation

Splits environment variable schemas into separate files for server and client configurations. This approach enhances security by preventing sensitive server-side variable names from being exposed.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

export const env = defineEnv({
  server: {
    DATABASE_URL: z.url(),
    OPENAI_API_KEY: z.string().min(1),
  },
  env: process.env,
});
```

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

export const env = defineEnv({
  clientPrefix: "NEXT_PUBLIC_",
  client: {
    NEXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
  env: process.env,
});
```

--------------------------------

### Define Server-Only Environment Schema

Source: https://envin.turbostarter.dev/docs/installation

Defines an environment schema that only includes server-side variables and shared variables. This is useful when no client-side variables are needed, simplifying the configuration.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

export default defineEnv({
  server: {
    DATABASE_URL: z.url(),
    OPENAI_API_KEY: z.string().min(1),
  },
  shared: {
    NODE_ENV: z.enum(["development", "production", "test"]),
  },
  env: process.env,
});
```

--------------------------------

### Extend Envin Presets (Vercel Example)

Source: https://envin.turbostarter.dev/docs/customization

Extend the envin configuration with predefined presets, such as the Vercel preset. This allows you to easily include environment variables specific to deployment providers or common configurations.

```typescript
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;
```

--------------------------------

### Use Environment Variables in Client Component

Source: https://envin.turbostarter.dev/docs/installation

Illustrates how to safely access environment variables, specifically those prefixed with `NEXT_PUBLIC_`, within a React client component. It highlights which variables are accessible on the client-side and which would cause runtime errors.

```tsx
"use client";

import env from "~/env.config";

export function ClientComponent() {
  // ✅ Works on client
  const publishableKey = env.NEXT_PUBLIC_PUBLISHABLE_KEY;

  // ❌ This will throw a runtime error on the client
  // const apiKey = env.OPENAI_API_KEY;

  return <div>Client component</div>;
}
```

--------------------------------

### Create Custom Envin Preset (Stripe Example)

Source: https://envin.turbostarter.dev/docs/customization

Create your own envin presets by defining an object with environment variable schemas. These custom presets can be extended by other configurations, allowing for modular and reusable environment variable definitions.

```typescript
import { defineEnv } from "envin";
import * as 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;
```

--------------------------------

### Envin Configuration with Valibot

Source: https://envin.turbostarter.dev/docs/validators

Shows how to use Valibot with Envin for environment variable validation. This example configures server, shared, and client variables using Valibot's pipe, transform, and picklist functions for type safety and validation.

```TypeScript
import { defineEnv } from "envin";
import * as v from "valibot";

export default defineEnv({
  server: {
    DATABASE_URL: v.pipe(v.string(), v.url()),
    PORT: v.pipe(v.string(), v.transform(Number), v.number()),
    API_KEY: v.pipe(v.string(), v.minLength(1)),
  },
  shared: {
    NODE_ENV: v.picklist(["development", "production", "test"]),
  },
  client: {
    NEXT_PUBLIC_APP_URL: v.pipe(v.string(), v.url()),
  },
  clientPrefix: "NEXT_PUBLIC_",
  env: process.env,
});
```

--------------------------------

### Envin Configuration with Effect Schema

Source: https://envin.turbostarter.dev/docs/validators

Provides an example of configuring Envin with Effect Schema for environment variable validation. It sets up server, shared, and client variables using Effect Schema's composition capabilities for URL validation, number parsing, and literal types.

```TypeScript
import { defineEnv } from "envin";
import { Schema as S } from "@effect/schema";

export default defineEnv({
  server: {
    DATABASE_URL: S.String.pipe(
      S.filter(s => {
        try {
          new URL(s);
          return true;
        } catch {
          return false;
        }
      })
    ),
    PORT: S.NumberFromString,
    API_KEY: S.String.pipe(S.minLength(1)),
  },
  shared: {
    NODE_ENV: S.Literal("development", "production", "test"),
  },
  client: {
    NEXT_PUBLIC_APP_URL: S.String.pipe(
      S.filter(s => {
        try {
          new URL(s);
          return true;
        } catch {
          return false;
        }
      })
    ),
  },
  clientPrefix: "NEXT_PUBLIC_",
  env: process.env,
});
```

--------------------------------

### Access Environment Variables in Client Component

Source: https://envin.turbostarter.dev/docs/index

This example shows how to import and access environment variables within a React client component using the 'envin' configuration. It highlights the separation of client and server variables and the potential for errors if server variables are accessed on the client.

```javascript
"use client";

import env from "../../env.config";

export const Client = () => {
  return <div>{env.DATABASE_URL}</div>;
};
```

--------------------------------

### Integrate Envin with Storybook

Source: https://envin.turbostarter.dev/docs/recipes

Shows how to configure Storybook to use environment variables defined with Envin. This ensures that required environment variables are available within the Storybook build process.

```typescript
import env from "~/env.config";

const config: StorybookConfig = {
  // Other Storybook configuration...
  env: config => ({
    ...config,
    ...env,
  }),
};

export default config;
```

--------------------------------

### Validate process.env with Zod

Source: https://envin.turbostarter.dev/docs/comparisons

Demonstrates how to validate environment variables using Zod and infer the schema onto NodeJS.ProcessEnv for autocompletion. This approach provides type-safety for environment variables.

```typescript
import * as z from "zod"; 

const envVariables = z.object({
  DATABASE_URL: z.string(),
  CUSTOM_STUFF: z.string(),
});

envVariables.parse(process.env);

declare global {
  namespace NodeJS {
    interface ProcessEnv extends z.infer<typeof envVariables> {}
  }
}

const url = process.env.DATABASE_URL;
     
const url: string
```

--------------------------------

### Coerce Booleans with Envin and Zod

Source: https://envin.turbostarter.dev/docs/recipes

Demonstrates how to coerce string environment variables into boolean types using Envin and Zod. It shows custom transformation logic and Zod's built-in coercion methods for booleans.

```typescript
import { defineEnv } from "envin";
import * as z from "zod";

const env = defineEnv({
     
const env: { // ... schema definition ... } // ...

server: { COERCED_BOOLEAN: z .string() // Transform to boolean using preferred coercion logic .transform(s => s !== "false" && s !== "0"), // Alternatively, use Zod's built-in primitive coercion // https://zod.dev/?id=coercion-for-primitives NATIVE_COERCION: z.coerce.boolean(), ONLY_BOOLEAN: z .string() // Only allow "true" or "false" .refine(s => s === "true" || s === "false") // Transform to boolean .transform(s => s === "true"), // Alternatively, use Zod's new syntax for string boolean coercion // https://zod.dev/v4?id=stringbool STRING_BOOLEAN: z.stringbool(), }, // ... });
```

--------------------------------

### Coerce Numbers with Envin and Zod

Source: https://envin.turbostarter.dev/docs/recipes

Illustrates how to convert string environment variables to numbers using Envin and Zod. It covers custom parsing logic with `parseInt` and Zod's built-in number coercion.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

const env = defineEnv({
     
const env: { // ... schema definition ... } // ...

server: { SOME_NUMBER: z .string() // Transform to number .transform(s => parseInt(s, 10)) // Ensure transform worked correctly .pipe(z.number()), // Alternatively, use Zod's built-in primitive coercion // https://zod.dev/?id=coercion-for-primitives ZOD_NUMBER_COERCION: z.coerce.number(), }, // ... });
```

--------------------------------

### Define Environment Variables with Zod Schema

Source: https://envin.turbostarter.dev/docs/index

This snippet demonstrates how to define environment variables using the 'envin' package and the 'zod' schema validator. It shows how to specify shared, server, and client variables, including type safety and client prefix configuration.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

const env = ({
  shared: {
    NODE_ENV: z.enum(["development", "production"]),
  },
  server: {
    DATABASE_URL: z.url(),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.url(),
    NEXT_PUBLIC_APP_URL: z.url(),
  },
  clientPrefix: "NEXT_PUBLIC_",
});

env.DATABASE_URL;
        
type DATABASE_URL: string
```

--------------------------------

### Envin Configuration Mixing Validation Libraries

Source: https://envin.turbostarter.dev/docs/validators

Demonstrates the flexibility of Envin by mixing different Standard Schema-compliant validation libraries (Zod, Valibot, ArkType) within a single configuration. This allows for leveraging the strengths of various libraries for different environment variables.

```TypeScript
import { defineEnv } from "envin";
import * as z from "zod"; 
import * as v from "valibot";
import { type } from "arktype";

export default defineEnv({
  server: {
    // Using Zod
    DATABASE_URL: z.url(),
    // Using Valibot
    PORT: v.pipe(v.string(), v.transform(Number)),
    // Using ArkType
    API_KEY: type("string>0"),
  },
  shared: {
    NODE_ENV: z.enum(["development", "production", "test"]),
  },
  client: {
    NEXT_PUBLIC_APP_URL: v.pipe(v.string(), v.url()),
  },
  clientPrefix: "NEXT_PUBLIC_",
  env: process.env,
});
```

--------------------------------

### Nested Envin Presets

Source: https://envin.turbostarter.dev/docs/customization

Nest envin presets by using the `extends` property within a preset definition. This allows for recursive merging of types and runtime validation, enabling complex configurations with shared environment variables.

```typescript
import { defineEnv } from "envin";
import * as z from "zod";

const storage = {
  id: "storage",
  server: { STORAGE_URL: z.string().url() },
} as const;

const api = {
  id: "api",
  server: { API_URL: z.string().url() },
  extends: [storage],
} as const;

const env = defineEnv({
  server: { APP_SECRET: z.string().min(1) },
  extends: [api],
});

env.STORAGE_URL;
```

--------------------------------

### Detect Envin Server Context

Source: https://envin.turbostarter.dev/docs/customization

Configure envin to detect if it's running in a server context. This is determined by checking if the `window` object is undefined, which is a common pattern for differentiating client-side and server-side JavaScript environments.

```typescript
import { defineEnv } from "envin";

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

--------------------------------

### Envin Configuration with Zod

Source: https://envin.turbostarter.dev/docs/validators

Demonstrates how to configure Envin using Zod for schema validation. It defines server, shared, and client environment variables with Zod schemas for URL, number coercion, string length, and enum types.

```TypeScript
import { defineEnv } from "envin";
import * as z from "zod"; 

export default defineEnv({
  server: {
    DATABASE_URL: z.url(),
    PORT: z.coerce.number().default(3000),
    API_KEY: z.string().min(1),
  },
  shared: {
    NODE_ENV: z.enum(["development", "production", "test"]),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.url(),
  },
  clientPrefix: "NEXT_PUBLIC_",
  env: process.env,
});
```

--------------------------------

### Envin Configuration with ArkType

Source: https://envin.turbostarter.dev/docs/validators

Illustrates using ArkType with Envin for environment variable validation. This configuration defines server, shared, and client variables using ArkType's type syntax for validation, including string length and literal types.

```TypeScript
import { defineEnv } from "envin";
import { type } from "arktype";

export default defineEnv({
  server: {
    DATABASE_URL: type("string"),
    PORT: type("string").pipe(s => +s),
    API_KEY: type("string>0"),
  },
  shared: {
    NODE_ENV: type("'development'|'production'|'test'"),
  },
  client: {
    NEXT_PUBLIC_APP_URL: type("string"),
  },
  clientPrefix: "NEXT_PUBLIC_",
  env: process.env,
});
```

--------------------------------

### Define Custom Environment Variables with Envin and Zod

Source: https://envin.turbostarter.dev/docs/customization

This TypeScript code defines environment variables using Envin and Zod, showcasing custom transformations and refinements. It includes transforming strings to numbers, splitting strings into arrays, validating URLs, and implementing conditional validation logic for optional fields.

```typescript
import { defineEnv } from "envin";
import * as z from "zod"; 

const env = defineEnv({
  : {
    // 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.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

```

--------------------------------

### Custom Envin Error Handling

Source: https://envin.turbostarter.dev/docs/customization

Customize how envin handles validation errors and invalid access attempts. You can define functions for `onError` (when schema validation fails) and `onInvalidAccess` (when server variables are accessed on the client).

```typescript
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`
    );
  },
});
```

--------------------------------

### Skip Envin Validation

Source: https://envin.turbostarter.dev/docs/customization

Configure envin to skip validation based on a condition, such as an environment variable. This is useful in scenarios like Docker builds where not all environment variables might be present. Default values are still used when possible.

```typescript
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",
});
```
Tokens:
Raw