@runtime-env/vite-plugin 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Ernest
+
+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

@@ -0,0 +1,87 @@
+# @runtime-env/vite-plugin
+
+Zero-config Vite plugin for `runtime-env`.
+
+## Installation
+
+```sh
+npm install --save-dev @runtime-env/vite-plugin
+```
+
+## Setup
+
+Before using the plugin, ensure you have the following prerequisites in your project:
+
+1.  **Define your environment schema**
+    Create a `.runtimeenvschema.json` file in your project root to define the structure and validation of your environment variables:
+    ```json
+    {
+      "type": "object",
+      "properties": {
+        "API_URL": { "type": "string" }
+      },
+      "required": ["API_URL"]
+    }
+    ```
+2.  **Provide local environment variables**
+    Create a `.env` (or `.env.local`, `.env.development`, etc.) file to provide values for development:
+    ```env
+    API_URL=http://localhost:3000
+    ```
+3.  **Load the runtime environment**
+    Add a `<script>` tag to your `index.html` **before** your main entry point to load the generated environment variables:
+    ```html
+    <script src="/runtime-env.js"></script>
+    ```
+    > [!IMPORTANT]
+    > In production, you are responsible for generating `/runtime-env.js` and (optionally) interpolating files at startup (e.g., in your Docker entrypoint) using the `@runtime-env/cli`.
+
+## Usage
+
+Add the plugin to your `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import runtimeEnv from "@runtime-env/vite-plugin";
+
+export default defineConfig({
+  plugins: [runtimeEnv()],
+});
+```
+
+### Accessing Variables
+
+**In JavaScript/TypeScript:**
+
+```ts
+// Variables are available globally
+const apiUrl = runtimeEnv.API_URL;
+```
+
+**In `index.html` (Template Interpolation):**
+
+```html
+<!-- Use lodash-style templates -->
+<script src="https://maps.googleapis.com/maps/api/js?key=<%= runtimeEnv.GOOGLE_MAPS_API_KEY %>"></script>
+```
+
+That's it! The plugin automatically handles the following:
+
+- **Development**: Dynamically serves `/runtime-env.js` and watches for changes in `.env` files or your schema.
+- **Build**: Only runs `gen-ts` to ensure your type definitions are up-to-date. It **does not** generate `runtime-env.js` or interpolate `index.html`, ensuring your build artifacts remain generic and environment-agnostic.
+- **Preview**: Hooks into the Vite preview server to generate `/runtime-env.js` and perform HTML interpolation on the fly, allowing you to test your production build locally.
+- **Testing (Vitest)**: Automatically generates a temporary `runtime-env.js` and injects it into Vitest's `setupFiles`, providing `globalThis.runtimeEnv` during your tests.
+
+## Why runtime-env?
+
+Vite's built-in `import.meta.env` is **build-time**. This means environment variables are "baked into" your JavaScript bundles during the build process, requiring a full rebuild for every environment (e.g., staging, production, or per-customer deployments).
+
+`@runtime-env` enables the **"Build once, deploy anywhere"** philosophy. By loading environment variables from a separate `/runtime-env.js` file at runtime, you can:
+
+- Use the **exact same Docker image** or build artifact across all environments.
+- Update configuration in seconds without a CI/CD rebuild.
+- Ensure strict validation of environment variables via JSON Schema.
+
+## Advanced Usage
+
+For more details on the underlying mechanics and CLI options, refer to the [main documentation](https://github.com/runtime-env/runtime-env#runtime-env).

package/dist/build.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function buildPlugin(): Plugin;

package/dist/build.js

@@ -0,0 +1,13 @@
+import { isTypeScriptProject, runRuntimeEnvCommand } from "./utils.js";
+export function buildPlugin() {
+    return {
+        name: "runtime-env-build",
+        config(config, configEnv) {
+            if (configEnv.command === "build") {
+                if (isTypeScriptProject(config.root || process.cwd())) {
+                    runRuntimeEnvCommand("gen-ts", "src/runtime-env.d.ts");
+                }
+            }
+        },
+    };
+}

package/dist/dev.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function devPlugin(): Plugin;

package/dist/dev.js

@@ -0,0 +1,63 @@
+import { resolve } from "path";
+import { writeFileSync, readFileSync, rmSync, existsSync } from "fs";
+import { isTypeScriptProject, runRuntimeEnvCommand, getTempDir, getViteEnvFiles, } from "./utils.js";
+const schemaFile = ".runtimeenvschema.json";
+export function devPlugin() {
+    return {
+        name: "runtime-env-dev",
+        configureServer(server) {
+            if (server.config.mode === "test")
+                return;
+            const envDir = server.config.envDir || server.config.root;
+            const envFiles = getViteEnvFiles(server.config.mode, envDir);
+            const watchFiles = [schemaFile, ...envFiles];
+            function run() {
+                const devOutputDir = getTempDir("dev");
+                const devOutputPath = resolve(devOutputDir, "runtime-env.js");
+                runRuntimeEnvCommand("gen-js", devOutputPath, envFiles);
+                if (isTypeScriptProject(server.config.root)) {
+                    runRuntimeEnvCommand("gen-ts", "src/runtime-env.d.ts");
+                }
+            }
+            run();
+            server.middlewares.use((req, res, next) => {
+                const base = server.config.base || "/";
+                const path = req.url?.split("?")[0];
+                const targetPath = (base + "/runtime-env.js").replace(/\/+/g, "/");
+                if (path === targetPath) {
+                    const devOutputDir = getTempDir("dev");
+                    const devOutputPath = resolve(devOutputDir, "runtime-env.js");
+                    if (existsSync(devOutputPath)) {
+                        res.setHeader("Content-Type", "application/javascript");
+                        res.end(readFileSync(devOutputPath, "utf8"));
+                        return;
+                    }
+                }
+                next();
+            });
+            server.watcher.add(watchFiles);
+            server.watcher.on("change", (file) => {
+                if (watchFiles.includes(file)) {
+                    run();
+                }
+            });
+        },
+        transformIndexHtml(html, ctx) {
+            if (ctx.server && ctx.server.config.command === "serve") {
+                const envDir = ctx.server.config.envDir || ctx.server.config.root;
+                const envFiles = getViteEnvFiles(ctx.server.config.mode, envDir);
+                const tmpDir = getTempDir("dev-interpolate");
+                try {
+                    const htmlFile = resolve(tmpDir, "index.html");
+                    writeFileSync(htmlFile, html, "utf8");
+                    runRuntimeEnvCommand("interpolate", htmlFile, envFiles, htmlFile);
+                    html = readFileSync(htmlFile, "utf8");
+                    return html;
+                }
+                finally {
+                    rmSync(tmpDir, { recursive: true, force: true });
+                }
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export default function runtimeEnv(): Plugin[];

package/dist/index.js

@@ -0,0 +1,7 @@
+import { devPlugin } from "./dev.js";
+import { buildPlugin } from "./build.js";
+import { previewPlugin } from "./preview.js";
+import { vitestPlugin } from "./vitest.js";
+export default function runtimeEnv() {
+    return [devPlugin(), buildPlugin(), previewPlugin(), vitestPlugin()];
+}

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function previewPlugin(): Plugin;

package/dist/preview.js

@@ -0,0 +1,64 @@
+import { resolve } from "path";
+import { readFileSync, writeFileSync, existsSync, rmSync } from "fs";
+import { runRuntimeEnvCommand, getTempDir, getViteEnvFiles } from "./utils.js";
+export function previewPlugin() {
+    return {
+        name: "runtime-env-preview",
+        configurePreviewServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const base = server.config.base || "/";
+                const url = req.url?.split("?")[0] || "";
+                // Normalize path to be relative to base
+                let path = url;
+                if (url.startsWith(base)) {
+                    path = url.slice(base.length);
+                }
+                if (!path.startsWith("/")) {
+                    path = "/" + path;
+                }
+                path = path.replace(/\/+/g, "/");
+                const envDir = server.config.envDir || server.config.root;
+                const envFiles = getViteEnvFiles(server.config.mode, envDir);
+                // Serve runtime-env.js
+                if (path === "/runtime-env.js") {
+                    const tmpDir = getTempDir("preview-gen-js");
+                    const tmpPath = resolve(tmpDir, "runtime-env.js");
+                    try {
+                        runRuntimeEnvCommand("gen-js", tmpPath, envFiles);
+                        if (existsSync(tmpPath)) {
+                            const content = readFileSync(tmpPath, "utf8");
+                            res.setHeader("Content-Type", "application/javascript");
+                            res.end(content);
+                            return;
+                        }
+                    }
+                    finally {
+                        rmSync(tmpDir, { recursive: true, force: true });
+                    }
+                }
+                // Intercept index.html
+                if (path === "/" || path === "/index.html") {
+                    const outDir = server.config.build.outDir || "dist";
+                    const distIndexHtml = resolve(server.config.root, outDir, "index.html");
+                    if (existsSync(distIndexHtml)) {
+                        const tmpDir = getTempDir("preview-interpolate");
+                        try {
+                            const tmpHtmlPath = resolve(tmpDir, "index.html");
+                            const originalHtml = readFileSync(distIndexHtml, "utf8");
+                            writeFileSync(tmpHtmlPath, originalHtml, "utf8");
+                            runRuntimeEnvCommand("interpolate", tmpHtmlPath, envFiles, tmpHtmlPath);
+                            const interpolatedHtml = readFileSync(tmpHtmlPath, "utf8");
+                            res.setHeader("Content-Type", "text/html");
+                            res.end(interpolatedHtml);
+                            return;
+                        }
+                        finally {
+                            rmSync(tmpDir, { recursive: true, force: true });
+                        }
+                    }
+                }
+                next();
+            });
+        },
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export declare function isTypeScriptProject(root: string): boolean;
+export declare function getViteEnvFiles(mode: string, envDir: string): string[];
+export declare function getRuntimeEnvCommandLineArgs(command: string, outputFile: string, envFiles?: string[], inputFile?: string): string[];
+export declare function runRuntimeEnvCommand(command: string, outputFile: string, envFiles?: string[], inputFile?: string): void;
+export declare function getTempDir(subDir: string): string;

package/dist/utils.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync } from "fs";
+import { resolve } from "path";
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const schemaFile = ".runtimeenvschema.json";
+const globalVariableName = "runtimeEnv";
+export function isTypeScriptProject(root) {
+    return existsSync(resolve(root, "tsconfig.json"));
+}
+export function getViteEnvFiles(mode, envDir) {
+    const envFiles = [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`];
+    return envFiles
+        .map((file) => resolve(envDir, file))
+        .filter((file) => existsSync(file));
+}
+export function getRuntimeEnvCommandLineArgs(command, outputFile, envFiles = [], inputFile) {
+    let args = [
+        "--schema-file",
+        schemaFile,
+        "--global-variable-name",
+        globalVariableName,
+        command,
+    ];
+    if (command === "gen-ts") {
+        args.push("--output-file", outputFile);
+    }
+    else if (command === "gen-js") {
+        args.push(...envFiles.map((file) => ["--env-file", file]).flat());
+        args.push("--output-file", outputFile);
+    }
+    else if (command === "interpolate" && inputFile) {
+        args.push(...envFiles.map((file) => ["--env-file", file]).flat());
+        args.push("--input-file", inputFile, "--output-file", outputFile);
+    }
+    return args;
+}
+export function runRuntimeEnvCommand(command, outputFile, envFiles = [], inputFile) {
+    const args = getRuntimeEnvCommandLineArgs(command, outputFile, envFiles, inputFile);
+    let cliPath;
+    try {
+        cliPath = require.resolve("@runtime-env/cli/bin/runtime-env.js");
+    }
+    catch (e) {
+        // Fallback to local node_modules/.bin if require.resolve fails (e.g. during development or in some monorepo setups)
+        cliPath = resolve("node_modules", ".bin", "runtime-env");
+    }
+    spawnSync("node", [cliPath, ...args]);
+}
+export function getTempDir(subDir) {
+    const root = process.cwd();
+    const tempDir = resolve(root, "node_modules", ".runtime-env", subDir);
+    mkdirSync(tempDir, { recursive: true });
+    return tempDir;
+}

package/dist/vitest.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function vitestPlugin(): Plugin;

package/dist/vitest.js

@@ -0,0 +1,39 @@
+import { resolve } from "path";
+import { rmSync } from "fs";
+import { isTypeScriptProject, runRuntimeEnvCommand, getTempDir, getViteEnvFiles, } from "./utils.js";
+export function vitestPlugin() {
+    return {
+        name: "runtime-env-vitest",
+        config(config, configEnv) {
+            if (config.mode === "test") {
+                const root = config.root || process.cwd();
+                // Generate runtime-env.d.ts for Vitest type checking
+                if (isTypeScriptProject(root)) {
+                    runRuntimeEnvCommand("gen-ts", "src/runtime-env.d.ts");
+                }
+                const envDir = config.envDir || root;
+                const envFiles = getViteEnvFiles(config.mode, envDir);
+                // Generate runtime-env.js for Vitest runtime access
+                const vitestOutputDir = getTempDir("vitest");
+                const vitestOutputPath = resolve(vitestOutputDir, "runtime-env.js");
+                // Ensure directory is clean
+                rmSync(vitestOutputDir, { recursive: true, force: true });
+                getTempDir("vitest"); // Re-create it clean
+                runRuntimeEnvCommand("gen-js", vitestOutputPath, envFiles);
+                // Automatically inject setupFiles for Vitest
+                const vitestConfig = config.test || {};
+                const setupFiles = vitestConfig.setupFiles || [];
+                if (Array.isArray(setupFiles)) {
+                    setupFiles.push(vitestOutputPath);
+                }
+                else {
+                    vitestConfig.setupFiles = [setupFiles, vitestOutputPath];
+                }
+                config.test = {
+                    ...vitestConfig,
+                    setupFiles,
+                };
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@runtime-env/vite-plugin",
+  "version": "0.0.0",
+  "description": "Opinionated Vite plugin for runtime-env",
+  "license": "MIT",
+  "author": "Ernest",
+  "keywords": [
+    "vite",
+    "plugin",
+    "runtime-env"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "pack": "npm pack && node ../../scripts/rename-tgz.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runtime-env/runtime-env.git",
+    "directory": "packages/vite-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/runtime-env/runtime-env/issues"
+  },
+  "homepage": "https://github.com/runtime-env/runtime-env#readme",
+  "dependencies": {
+    "@runtime-env/cli": "^0.7.8"
+  },
+  "devDependencies": {
+    "vite": "7.3.0"
+  },
+  "type": "module"
+}