Programmatic API

Installation

pnpm add -D @xlameiro/env-typegen

When to use the API instead of the CLI

• You need custom orchestration in build scripts.
• You want to merge env validation into an existing pipeline tool.
• You want plugin hooks controlled in code.
• You need to process dynamic env content streams before generation.

Importing

import {
  // Parsing and inference
  parseEnvFile,
  parseEnvFileContent,
  inferType,
  inferTypes,
  // Generators
  generateTypeScriptTypes,
  generateZodSchema,
  generateT3Env,
  generateDeclaration,
  // Pipelines and validation
  runGenerate,
  runValidationCommand,
  // Cloud sources and plugin system
  loadCloudSource,
  loadPlugins,
  applyContractPlugins,
  applySourcePlugins,
  applyReportPlugins,
} from "@xlameiro/env-typegen";

Architecture map

Layer	Key functions
Parse and infer	parseEnvFile, parseEnvFileContent, inferType, inferTypes
Generate artifacts	generateTypeScriptTypes, generateZodSchema, generateT3Env, generateDeclaration
Pipeline orchestration	runGenerate, runValidationCommand
Integrations	loadCloudSource, loadPlugins, plugin application helpers

Core functions

parseEnvFile(path)

Reads a .env.example file from disk and returns a ParsedEnvFile.

const parsed = parseEnvFile(".env.example");

parseEnvFileContent(content, filePath?)

Parses raw .env string content — useful in tests or streaming pipelines.

const parsed = parseEnvFileContent("DATABASE_URL=\nPORT=3000");

inferType(key, value, options?)

Infers an EnvVarType from a key+value pair using heuristics (key name patterns, value shape).

const type = inferType("PORT", "3000"); // → "number"
const type2 = inferType("DEBUG", "true"); // → "boolean"

inferTypes(parsed)

Runs inference for all variables in a ParsedEnvFile.

const typed = inferTypes(parsed);

generateTypeScriptTypes(parsed)

Produces a type Env = { ... } TypeScript declaration string.

const output = generateTypeScriptTypes(typed);

generateZodSchema(parsed)

Produces a Zod v4 z.object({ ... }) schema string split into server/client.

const output = generateZodSchema(typed);

generateT3Env(parsed)

Produces a @t3-oss/env-nextjs createEnv(...) call string.

const output = generateT3Env(typed);

generateDeclaration(parsed)

Produces a .d.ts file augmenting NodeJS.ProcessEnv.

const output = generateDeclaration(typed);

runGenerate(options)

Orchestrates the full pipeline: parse → infer → generate → write to disk.

await runGenerate({
  input: ".env.example",
  output: "env.generated.ts",
  generators: ["typescript", "zod"],
  format: true,
  dryRun: false,
  silent: false,
});

runValidationCommand({ command, argv })

Runs validation subcommands programmatically.

const exitCode = await runValidationCommand({
  command: "check",
  argv: ["--env", ".env", "--contract", "env.contract.ts", "--json"],
});

loadCloudSource({ provider, filePath })

Loads environment values from provider snapshot files.

const values = await loadCloudSource({
  provider: "aws",
  filePath: "aws-env.json",
});

loadPlugins({ pluginPaths, configPlugins })

Loads plugin references and lets you apply hook chains.

const plugins = await loadPlugins({
  pluginPaths: ["./plugins/report-plugin.mjs"],
});

const report = applyReportPlugins(baseReport, plugins);

Integration examples

Build step wrapper

await runGenerate({
  input: ".env.example",
  output: "src/env.generated.ts",
  generators: ["typescript", "zod", "declaration"],
  format: true,
  dryRun: false,
  silent: false,
});

CI validation gate

const exitCode = await runValidationCommand({
  command: "doctor",
  argv: [
    "--env",
    ".env",
    "--targets",
    ".env,.env.staging,.env.production",
    "--contract",
    "env.contract.ts",
    "--json",
  ],
});

if (exitCode !== 0) {
  process.exit(exitCode);
}

FAQ

Is the API stable for automation use?

Yes. The exported functions are intended for programmatic integration, not only CLI internals.

Should I call generators directly or use runGenerate?

Use runGenerate for standard pipelines, and direct generator calls when you need custom composition.