vite-plugin-typed-env 0.1.0 → 0.1.2

package/README.md

@@ -18,6 +18,12 @@ A Vite plugin that automatically generates TypeScript types and Zod schemas from
 npm install vite-plugin-typed-env -D
 ```
 
+If using Zod validation (default), also install zod:
+
+```bash
+npm install zod
+```
+
 ## Usage
 
 ### 1. Add to Vite config

package/dist/index.cjs

@@ -0,0 +1,367 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region \0rolldown/runtime.js
+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 __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+//#region src/parser.ts
+const ANNOTATION_RE = /^#\s*@(\w+)(?::\s*(.+))?$/;
+function parseAnnotations(lines) {
+	const ann = {};
+	for (const line of lines) {
+		const m = line.match(ANNOTATION_RE);
+		if (!m) continue;
+		const [, key, value] = m;
+		if (key === "optional") ann.optional = true;
+		else if (key === "type" && value) ann.type = value.trim();
+		else if (key === "default" && value) ann.default = value.trim();
+		else if (key === "desc" && value) ann.description = value.trim();
+	}
+	return ann;
+}
+function parseEnvFile(content) {
+	const lines = content.split("\n");
+	const entries = [];
+	const pendingComments = [];
+	for (let i = 0; i < lines.length; i++) {
+		const raw = lines[i].trim();
+		if (raw === "") {
+			pendingComments.length = 0;
+			continue;
+		}
+		if (raw.startsWith("#")) {
+			pendingComments.push(raw);
+			continue;
+		}
+		const eqIdx = raw.indexOf("=");
+		if (eqIdx === -1) continue;
+		const key = raw.slice(0, eqIdx).trim();
+		let value = raw.slice(eqIdx + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		const annotations = parseAnnotations(pendingComments);
+		const description = pendingComments.filter((l) => !ANNOTATION_RE.test(l)).map((l) => l.replace(/^#\s*/, "")).join(" ").trim();
+		entries.push({
+			key,
+			value,
+			annotations: {
+				...annotations,
+				description: description || void 0
+			},
+			comment: ""
+		});
+		pendingComments.length = 0;
+	}
+	return entries;
+}
+//#endregion
+//#region src/inferrer.ts
+function isBoolean(v) {
+	return [
+		"true",
+		"false",
+		"1",
+		"0",
+		"yes",
+		"no"
+	].includes(v.toLowerCase());
+}
+function isNumber(v) {
+	return v !== "" && !isNaN(Number(v));
+}
+function isUrl(v) {
+	try {
+		new URL(v);
+		return v.startsWith("http://") || v.startsWith("https://") || v.includes("://");
+	} catch {
+		return false;
+	}
+}
+function isNumberArray(v) {
+	if (!v.includes(",")) return false;
+	return v.split(",").every((s) => isNumber(s.trim()));
+}
+function isStringArray(v) {
+	return v.includes(",") && v.split(",").length > 1;
+}
+function inferFromAnnotation(ann) {
+	const enumMatch = ann.match(/^enum\((.+)\)$/);
+	if (enumMatch) {
+		const values = enumMatch[1].split(",").map((s) => s.trim());
+		return {
+			tsType: values.map((v) => `'${v}'`).join(" | "),
+			zodSchema: `z.enum([${values.map((v) => `'${v}'`).join(", ")}])`
+		};
+	}
+	if (ann === "number[]") return {
+		tsType: "number[]",
+		zodSchema: `z.string().transform(v => v.split(',').map(Number))`
+	};
+	if (ann === "string[]") return {
+		tsType: "string[]",
+		zodSchema: `z.string().transform(v => v.split(','))`
+	};
+	if (ann === "url") return {
+		tsType: "string",
+		zodSchema: `z.string().url()`
+	};
+	if (ann === "number") return {
+		tsType: "number",
+		zodSchema: `z.coerce.number()`
+	};
+	if (ann === "boolean") return {
+		tsType: "boolean",
+		zodSchema: `z.enum(['true','false','1','0']).transform(v => v === 'true' || v === '1')`
+	};
+	if (ann === "port") return {
+		tsType: "number",
+		zodSchema: `z.coerce.number().int().min(1).max(65535)`
+	};
+	if (ann === "email") return {
+		tsType: "string",
+		zodSchema: `z.string().email()`
+	};
+	return null;
+}
+function inferFromValue(value) {
+	if (value === "") return {
+		tsType: "string",
+		zodSchema: "z.string()"
+	};
+	if (isBoolean(value)) return {
+		tsType: "boolean",
+		zodSchema: `z.enum(['true','false','1','0','yes','no']).transform(v => ['true','1','yes'].includes(v.toLowerCase()))`
+	};
+	if (isNumber(value)) return {
+		tsType: "number",
+		zodSchema: Number.isInteger(Number(value)) ? "z.coerce.number().int()" : "z.coerce.number()"
+	};
+	if (isNumberArray(value)) return {
+		tsType: "number[]",
+		zodSchema: `z.string().transform(v => v.split(',').map(Number))`
+	};
+	if (isUrl(value)) return {
+		tsType: "string",
+		zodSchema: "z.string().url()"
+	};
+	if (isStringArray(value)) return {
+		tsType: "string[]",
+		zodSchema: `z.string().transform(v => v.split(',').map(s => s.trim()))`
+	};
+	return {
+		tsType: "string",
+		zodSchema: "z.string().min(1)"
+	};
+}
+function inferType(entry) {
+	const { value, annotations } = entry;
+	const isOptional = annotations.optional === true || value === "";
+	const base = (annotations.type ? inferFromAnnotation(annotations.type) : null) ?? inferFromValue(value);
+	let zodSchema = base.zodSchema;
+	if (annotations.default !== void 0) zodSchema = `${zodSchema}.default('${annotations.default}')`;
+	else if (isOptional) zodSchema = `${zodSchema}.optional()`;
+	return {
+		tsType: base.tsType,
+		zodSchema,
+		isOptional,
+		defaultValue: annotations.default
+	};
+}
+//#endregion
+//#region src/generator.ts
+function generateDts(items, options) {
+	const lines = [];
+	lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`);
+	lines.push(`// Re-run vite to regenerate this file.`);
+	lines.push(``);
+	if (options.augmentImportMeta) {
+		lines.push(`/// <reference types="vite/client" />`);
+		lines.push(``);
+		lines.push(`interface ImportMetaEnv {`);
+		for (const { entry, inferred } of items) {
+			if (entry.annotations.description) lines.push(`  /** ${entry.annotations.description} */`);
+			const opt = inferred.isOptional ? "?" : "";
+			lines.push(`  readonly ${entry.key}${opt}: ${inferred.tsType}`);
+		}
+		lines.push(`}`);
+		lines.push(``);
+		lines.push(`interface ImportMeta {`);
+		lines.push(`  readonly env: ImportMetaEnv`);
+		lines.push(`}`);
+	} else {
+		lines.push(`export interface Env {`);
+		for (const { entry, inferred } of items) {
+			if (entry.annotations.description) lines.push(`  /** ${entry.annotations.description} */`);
+			const opt = inferred.isOptional ? "?" : "";
+			lines.push(`  ${entry.key}${opt}: ${inferred.tsType}`);
+		}
+		lines.push(`}`);
+	}
+	return lines.join("\n");
+}
+function generateZodSchema(items) {
+	const lines = [];
+	lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`);
+	lines.push(`import { z } from 'zod'`);
+	lines.push(``);
+	lines.push(`export const envSchema = z.object({`);
+	for (const { entry, inferred } of items) {
+		if (entry.annotations.description) lines.push(`  // ${entry.annotations.description}`);
+		lines.push(`  ${entry.key}: ${inferred.zodSchema},`);
+	}
+	lines.push(`})`);
+	lines.push(``);
+	lines.push(`export type Env = z.infer<typeof envSchema>`);
+	return lines.join("\n");
+}
+function generateLoader(items, options) {
+	const lines = [];
+	lines.push(`// Auto-generated by vite-plugin-typed-env. DO NOT EDIT.`);
+	lines.push(``);
+	if (options.schema === "zod") {
+		lines.push(`import { envSchema } from './env.schema'`);
+		lines.push(``);
+		lines.push(`const _parsed = envSchema.safeParse(import.meta.env)`);
+		lines.push(``);
+		lines.push(`if (!_parsed.success) {`);
+		lines.push(`  const errors = _parsed.error.flatten().fieldErrors`);
+		lines.push(`  const msg = Object.entries(errors)`);
+		lines.push(`    .map(([k, v]) => \`  \${k}: \${(v as string[]).join(', ')}\`)`);
+		lines.push(`    .join('\\n')`);
+		lines.push(`  throw new Error(\`[env-ts] Invalid environment variables:\\n\${msg}\`)`);
+		lines.push(`}`);
+		lines.push(``);
+		lines.push(`export const env = _parsed.data`);
+		lines.push(`export default env`);
+	} else {
+		const required = items.filter(({ inferred }) => !inferred.isOptional);
+		lines.push(`const _raw = import.meta.env`);
+		lines.push(``);
+		if (required.length > 0) {
+			lines.push(`const _required = [${required.map(({ entry }) => `'${entry.key}'`).join(", ")}] as const`);
+			lines.push(`for (const key of _required) {`);
+			lines.push(`  if (!_raw[key]) throw new Error(\`[env-ts] Missing required env var: \${key}\`)`);
+			lines.push(`}`);
+			lines.push(``);
+		}
+		lines.push(`export const env = _raw as import('./env').Env`);
+		lines.push(`export default env`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/index.ts
+async function generateTypes(envDir, outputDir, options) {
+	const envFileNames = [
+		".env",
+		".env.local",
+		`.env.${process.env.NODE_ENV ?? "development"}`,
+		`.env.${process.env.NODE_ENV ?? "development"}.local`,
+		...options.envFiles
+	];
+	const entries = /* @__PURE__ */ new Map();
+	for (const fileName of envFileNames) {
+		const filePath = node_path.default.join(envDir, fileName);
+		if (!node_fs.default.existsSync(filePath)) continue;
+		const parsed = parseEnvFile(node_fs.default.readFileSync(filePath, "utf-8"));
+		for (const entry of parsed) entries.set(entry.key, entry);
+	}
+	if (entries.size === 0) {
+		console.warn("[env-ts] No .env files found or all are empty, skipping generation.");
+		return;
+	}
+	const items = Array.from(entries.values()).map((entry) => ({
+		entry,
+		inferred: inferType(entry)
+	}));
+	if (options.strict) {
+		const missing = items.filter(({ inferred }) => !inferred.isOptional && inferred.defaultValue === void 0).filter(({ entry }) => {
+			const v = process.env[entry.key];
+			return v === void 0 || v === "";
+		}).map(({ entry }) => entry.key);
+		if (missing.length > 0) {
+			const msg = `[env-ts] Missing required env variables: ${missing.join(", ")}`;
+			if (process.env.NODE_ENV === "production") throw new Error(msg);
+			else console.warn(msg);
+		}
+	}
+	node_fs.default.mkdirSync(outputDir, { recursive: true });
+	const genOptions = {
+		schema: options.schema,
+		augmentImportMeta: options.augmentImportMeta
+	};
+	const dtsContent = generateDts(items, genOptions);
+	writeIfChanged(node_path.default.join(outputDir, "env.d.ts"), dtsContent);
+	if (options.schema === "zod") {
+		const schemaContent = generateZodSchema(items);
+		writeIfChanged(node_path.default.join(outputDir, "env.schema.ts"), schemaContent);
+	}
+	const loaderContent = generateLoader(items, genOptions);
+	writeIfChanged(node_path.default.join(outputDir, "env.ts"), loaderContent);
+	console.log(`[env-ts] Generated ${items.length} env types → ${node_path.default.relative(process.cwd(), outputDir)}/`);
+}
+function writeIfChanged(filePath, content) {
+	if (node_fs.default.existsSync(filePath)) {
+		if (node_fs.default.readFileSync(filePath, "utf-8") === content) return;
+	}
+	node_fs.default.writeFileSync(filePath, content, "utf-8");
+}
+function envTs(userOptions = {}) {
+	const options = {
+		schema: "zod",
+		output: "src",
+		augmentImportMeta: true,
+		strict: true,
+		envFiles: [],
+		...userOptions
+	};
+	let config;
+	let outputDir;
+	return {
+		name: "vite-plugin-typed-env",
+		enforce: "pre",
+		configResolved(resolvedConfig) {
+			config = resolvedConfig;
+			outputDir = node_path.default.resolve(config.root, options.output);
+		},
+		async buildStart() {
+			await generateTypes(config.envDir === false ? config.root : config.envDir, outputDir, options);
+		},
+		async handleHotUpdate({ file, server }) {
+			if (!file) return;
+			const fileName = node_path.default.basename(file);
+			if (!(fileName.startsWith(".env") || options.envFiles.includes(file))) return;
+			console.log(`[env-ts] Detected change in ${fileName}, regenerating...`);
+			await generateTypes(config.envDir === false ? config.root : config.envDir, outputDir, options);
+			server.hot.send({ type: "full-reload" });
+		}
+	};
+}
+//#endregion
+exports.default = envTs;
+exports.generateTypes = generateTypes;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { Plugin } from "vite";
+
+//#region src/index.d.ts
+interface EnvTsOptions {
+  /**
+   * 生成 Zod schema 文件
+   * @default 'zod'
+   */
+  schema?: 'zod' | false;
+  /**
+   * 生成文件的输出目录（相对于项目根目录）
+   * @default 'src'
+   */
+  output?: string;
+  /**
+   * 是否扩展 Vite 的 ImportMetaEnv 类型
+   * 开启后 import.meta.env.YOUR_VAR 自动有类型
+   * @default true
+   */
+  augmentImportMeta?: boolean;
+  /**
+   * 缺失必填变量时是否让构建失败
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * 额外监听的 .env 文件（默认自动检测 .env, .env.local 等）
+   */
+  envFiles?: string[];
+}
+declare function generateTypes(envDir: string, outputDir: string, options: Required<EnvTsOptions>): Promise<void>;
+declare function envTs(userOptions?: EnvTsOptions): Plugin;
+//#endregion
+export { EnvTsOptions, envTs as default, generateTypes };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+import { Plugin } from "vite";
+
+//#region src/index.d.ts
+interface EnvTsOptions {
+  /**
+   * 生成 Zod schema 文件
+   * @default 'zod'
+   */
+  schema?: 'zod' | false;
+  /**
+   * 生成文件的输出目录（相对于项目根目录）
+   * @default 'src'
+   */
+  output?: string;
+  /**
+   * 是否扩展 Vite 的 ImportMetaEnv 类型
+   * 开启后 import.meta.env.YOUR_VAR 自动有类型
+   * @default true
+   */
+  augmentImportMeta?: boolean;
+  /**
+   * 缺失必填变量时是否让构建失败
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * 额外监听的 .env 文件（默认自动检测 .env, .env.local 等）
+   */
+  envFiles?: string[];
+}
+declare function generateTypes(envDir: string, outputDir: string, options: Required<EnvTsOptions>): Promise<void>;
+declare function envTs(userOptions?: EnvTsOptions): Plugin;
+//#endregion
+export { EnvTsOptions, envTs as default, generateTypes };
+//# sourceMappingURL=index.d.mts.map