@pixelmatters/vite-plugin-validate-env 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixelmatters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @pixelmatters/vite-plugin-validate-env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@pixelmatters/vite-plugin-validate-env.svg)](https://www.npmjs.com/package/@pixelmatters/vite-plugin-validate-env)
+[![license](https://img.shields.io/npm/l/@pixelmatters/vite-plugin-validate-env.svg)](./LICENSE)
+
+Vite plugin for validating environment variables against a schema
+([Standard Schema](https://standardschema.dev)). A missing or malformed
+variable stops the dev server or the build before it starts, with a line per
+issue.
+
+## Install
+
+```bash
+pnpm add -D @pixelmatters/vite-plugin-validate-env
+```
+
+Requires Vite 6, 7 or 8 and Node `^20.19.0 || >=22.12.0`.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+// Import your favorite schema library (zod, valibot, arktype, etc.)
+import * as z from 'zod'
+
+import { validateEnv } from '@pixelmatters/vite-plugin-validate-env'
+
+// Define your environment variables schema (any standard schema library can be used)
+const envSchema = z.object({
+  VITE_API_URL: z.url(),
+  VITE_STRIPE_PUBLISHABLE_KEY: z.string().min(1),
+})
+
+export default defineConfig({
+  plugins: [
+    // ...
+    validateEnv(envSchema),
+  ],
+})
+```
+
+The schema must validate synchronously. It runs once Vite has resolved its
+config and receives what Vite's `loadEnv` returns for the current mode: the
+`.env*` files in your `envDir` and the process environment, filtered by
+`envPrefix` (`VITE_` by default). Whatever other plugins set for `root`,
+`envDir` or `envPrefix` is already applied.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vite';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * The schema must validate synchronously. On issues it prints a report and
+ * exits the process with code 1.
+ */
+export declare const validateEnv: (schema: StandardSchemaV1) => Plugin;

package/dist/index.js

@@ -0,0 +1,36 @@
+const pathLabel = (path) => path?.length ? path.map((s) => String(typeof s === 'object' ? s.key : s)).join('.') : 'root';
+/**
+ * The schema must validate synchronously. On issues it prints a report and
+ * exits the process with code 1.
+ */
+export const validateEnv = (schema) => {
+    return {
+        name: 'vite-plugin-validate-env',
+        configResolved: async (config) => {
+            const { loadEnv } = await import('vite');
+            const env = loadEnv(config.mode, config.envDir, config.envPrefix);
+            let issues;
+            try {
+                const result = schema['~standard'].validate(env);
+                if (result instanceof Promise) {
+                    throw new TypeError('Schema validation must be synchronous');
+                }
+                issues = result.issues;
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                throw new Error('Invalid environment variables', { cause: error });
+            }
+            if (issues) {
+                const { styleText } = await import('node:util');
+                console.log('========================================');
+                console.log('❌ Environment variables issues:');
+                issues.forEach((issue) => {
+                    console.log(`    ${styleText('cyan', pathLabel(issue.path))}:`, issue.message);
+                });
+                console.log('========================================\n');
+                process.exit(1);
+            }
+        },
+    };
+};

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@pixelmatters/vite-plugin-validate-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Vite plugin for validating environment variables against a schema (Standard Schema)",
+  "keywords": [
+    "environment",
+    "pixelmatters",
+    "plugin",
+    "schema",
+    "standard",
+    "tanstack-intent",
+    "validate",
+    "variables",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/Pixelmatters/devtools/tree/main/packages/vite-plugin-validate-env#readme",
+  "bugs": {
+    "url": "https://github.com/Pixelmatters/devtools/issues"
+  },
+  "license": "MIT",
+  "author": "Pixelmatters",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pixelmatters/devtools.git",
+    "directory": "packages/vite-plugin-validate-env"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "skills",
+    "!skills/_artifacts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@tanstack/intent": "^0.5.5",
+    "@types/node": "^26.6.6",
+    "tsrs": "0.20.1-ts7.1.0-beta",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "typecheck": "tsrs --noEmit",
+    "test": "vitest run",
+    "check:types": "rm -rf .attw && pnpm pack --pack-destination .attw && attw .attw/*.tgz --profile esm-only",
+    "check:dist": "pnpm run check:types",
+    "validate:skills": "intent validate"
+  }
 }

package/skills/validate-vite-env/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: validate-vite-env
+description: Add `@pixelmatters/vite-plugin-validate-env` to a Vite app so a missing or malformed `import.meta.env` value stops the dev server or build before it starts, checked against a Standard Schema (zod, valibot, ArkType). Use when the host depends on `@pixelmatters/vite-plugin-validate-env`, the user wants Vite env variables validated at startup, or the plugin exits with `Invalid environment variables` or an `Environment variables issues` report.
+metadata:
+  purpose: 'Wire the env-validation plugin into vite.config and write a schema that matches what Vite loads.'
+  type: core
+  library: '@pixelmatters/vite-plugin-validate-env'
+  library_version: '1.0.0'
+sources:
+  - 'Pixelmatters/devtools:packages/vite-plugin-validate-env/README.md'
+  - 'Pixelmatters/devtools:packages/vite-plugin-validate-env/src/index.ts'
+---
+
+The plugin runs in Vite's `configResolved` hook, so it covers `vite`, `vite build` and `vite preview`. It validates the env Vite itself loads: `root`, `envDir` and `envPrefix` are the final values after every plugin's `config` hook, and `envDir: false` loads no files. Your schema checks it, and on failure the plugin prints one line per issue and exits with code 1. It only checks: it does not change what `import.meta.env` contains.
+
+## Install
+
+```bash
+pnpm add -D @pixelmatters/vite-plugin-validate-env   # or: yarn add -D … / npm install -D …
+```
+
+ES modules only. Supported: Vite 6, 7 and 8. Node `^20.19.0 || >=22.12.0`. Bring your own schema library; anything that implements Standard Schema works.
+
+## Setup
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import * as z from 'zod'
+
+import { validateEnv } from '@pixelmatters/vite-plugin-validate-env'
+
+const envSchema = z.object({
+  VITE_API_URL: z.url(),
+  VITE_STRIPE_PUBLISHABLE_KEY: z.string().min(1),
+})
+
+export default defineConfig({ plugins: [validateEnv(envSchema)] })
+```
+
+`validateEnv` is a named export and takes the schema directly, not an options object.
+
+## What the schema receives
+
+The result of Vite's `loadEnv(mode, envDir, envPrefix)`: values from `.env`, `.env.local`, `.env.[mode]` and `.env.[mode].local` in `envDir` (default: the project root), plus matching variables from the process environment. Only names starting with `envPrefix` (default `VITE_`) are included, as strings.
+
+So a schema key without the prefix is always missing, and a number or boolean must be parsed from its string form (`z.coerce.number()`, or `z.enum(['true', 'false'])`).
+
+## Failure output
+
+```
+========================================
+❌ Environment variables issues:
+    VITE_API_URL: Invalid input: expected string, received undefined
+========================================
+```
+
+The process then exits with code 1. A schema that validates asynchronously throws `Invalid environment variables` instead, after logging `Schema validation must be synchronous`.
+
+## Common mistakes
+
+- **Validating an unprefixed variable.** `DATABASE_URL` never reaches the schema. Prefix it, or set `envPrefix` in the Vite config to include it, knowing that Vite then exposes it to client code.
+- **Using an async schema.** Validation must be synchronous; use the sync form of your library (zod's `parse`-style schemas are fine, async refinements are not).
+- **Expecting parsed values in `import.meta.env`.** `z.coerce.number()` validates the string but `import.meta.env.VITE_PORT` stays a string. Parse it again where it is used.
+- **Assuming shell-only variables are ignored.** They are validated too, as long as they carry the prefix and are set for the same command that runs Vite.
+- **Looking for it in the browser bundle.** The plugin runs in Node during config; nothing from it ships to the client.
+
+## Completion
+
+Run `vite build` with every required variable set and confirm it succeeds. Unset one and confirm the build prints that variable's issue and exits with a non-zero code. If a variable you set is reported as missing, check its prefix and which `.env*` file or `envDir` it lives in.