@ctroenv/vite

Vite adapter for CtroEnv — validate environment variables at build time.

Installation

npm install @ctroenv/vite

Usage

// vite.config.ts
import { defineConfig } from "vite"
import { ctroenvPlugin } from "@ctroenv/vite"

export default defineConfig({
  plugins: [
    ctroenvPlugin({
      schema: "./src/env.ts",
    }),
  ],
})

With Inline Schema

ctroenvPlugin({
  schema: {
    API_URL: string().url(),
    PORT: number().port().default(3000),
  },
})

API

| Function | Description | |----------|-------------| | ctroenvPlugin(opts) | Vite plugin that validates env vars at build start | | viteSource() | EnvSource reading from import.meta.env (falls back to process.env) |

Plugin Options

interface CtroEnvPluginOptions {
  schema: string | SchemaDefinition   // Schema file path or inline definition
  failOnError?: boolean               // Fail build on validation error (default: true)
  maskWith?: string                   // Custom mask string for secret values
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | schema | string \| SchemaDefinition | — | Path to schema module or inline definition | | failOnError | boolean | true | When false, validation failures become warnings | | maskWith | string | "********" | Custom string for masking .secret() values |

viteSource

viteSource(): EnvSource

Creates an EnvSource that reads from import.meta.env with fallback to process.env for non-Vite environments.

import { defineEnv } from "@ctroenv/core"
import { viteSource } from "@ctroenv/vite"

const env = defineEnv(schema, {
  source: viteSource(),
})

Build Output

• Success: Logs ✓ CtroEnv: All environment variables valid
• Failure with failOnError: true (default): Emits a build error with ✗ CtroEnv: ... — stops the build
• Failure with failOnError: false: Emits a build warning with ✗ CtroEnv: ... — build continues

Documentation

Full documentation at ctroenv.vercel.app

License

MIT