@dotenvage/node 0.1.5

package/nextjs/README.md

@@ -0,0 +1,271 @@
+# Next.js Integration with dotenvage
+
+This directory contains utilities for integrating dotenvage with
+Next.js applications, ensuring that encrypted environment variables
+are properly loaded before Next.js processes them.
+
+## The Problem
+
+Next.js loads environment variables from `.env*` files using
+`@next/env` **before** your `next.config.mjs` runs. If your `.env`
+files contain encrypted values (like `ENC[AGE:...]`), Next.js will try
+to use those encrypted values directly, which won't work.
+
+Additionally, for `NEXT_PUBLIC_*` variables that need to be available
+in Edge Runtime (middleware), Next.js must inline them at build time.
+If the values are encrypted when Next.js reads them, they'll be
+inlined as encrypted strings, which is useless.
+
+## The Solution
+
+We leverage the fact that `@next/env` **does not overwrite** existing
+`process.env` values. By loading and decrypting environment variables
+**before** Next.js starts, we ensure:
+
+1. Encrypted values are decrypted and set in `process.env` first
+2. When `@next/env` runs, it sees existing values and preserves them
+3. Decrypted values are available for Next.js to inline into the build
+
+## Quick Start
+
+**For Edge Runtime (middleware) support (recommended):**
+
+Use the `dotenvage-next` bin script to start Next.js:
+
+```json
+{
+  "scripts": {
+    "dev": "dotenvage-next dev",
+    "build": "dotenvage-next build"
+  }
+}
+```
+
+And wrap your config:
+
+```javascript
+import { withDotenvage } from "@dotenvage/node/nextjs/config";
+
+export default withDotenvage({
+  // Your Next.js config
+});
+```
+
+**For server-side only (no Edge Runtime):**
+
+Use `loadEnv()` in your config file:
+
+```javascript
+import { loadEnv } from "@dotenvage/node/nextjs";
+
+loadEnv();
+
+export default {
+  // Your Next.js config
+};
+```
+
+## Files
+
+### `config.mjs`
+
+A configuration wrapper for API consistency. This is mainly for
+convenience when using the `dotenvage-next` wrapper script.
+
+**Note:** For Edge Runtime (middleware) support, you MUST use the
+`dotenvage-next` wrapper script. For server-side only (no Edge
+Runtime), you can use `loadEnv()` directly (see `loader.mjs` below).
+
+**Usage in `next.config.mjs`:**
+
+```javascript
+import { withDotenvage } from "@dotenvage/node/nextjs/config";
+import nextMDX from "@next/mdx";
+
+const nextConfig = {
+  // Your Next.js config
+};
+
+const withMDX = nextMDX({
+  // MDX options
+});
+
+export default withDotenvage(withMDX(nextConfig));
+```
+
+**Note:** When using `dotenvage-next` wrapper script, env vars are
+already loaded, so this wrapper is just a pass-through for
+consistency.
+
+### `loader.mjs` (For server-side only, no Edge Runtime)
+
+A standard loader for use in `next.config.mjs` when you don't use Edge
+Runtime (middleware). Use this when you only need server-side code to
+access encrypted environment variables.
+
+**Important:** This works for server-side code (API routes, server
+components) because `loadEnv()` runs in `next.config.mjs` and can
+decrypt values before server-side code accesses them. However, it does
+NOT work for Edge Runtime (middleware) because Next.js inlines
+`NEXT_PUBLIC_*` variables at build time, BEFORE `next.config.mjs`
+runs.
+
+For Edge Runtime support, you MUST use the `dotenvage-next` wrapper
+script.
+
+**Usage in `next.config.mjs` (server-side only):**
+
+```javascript
+import { loadEnv } from "@dotenvage/node/nextjs";
+
+// Load and decrypt environment variables
+loadEnv();
+
+export default {
+  // Your Next.js config
+};
+```
+
+**Note:** When using `loadEnv()` in the config file, `@next/env` will
+have already loaded encrypted values, but `loadEnv()` overwrites them
+with decrypted values, so server-side code sees the decrypted values.
+
+### `nextjs-preinit.mjs`
+
+A pre-initialization loader that must run **before** Next.js starts.
+This is critical for ensuring `NEXT_PUBLIC_*` variables are available
+in Edge Runtime.
+
+**Usage options:**
+
+1. **Via Node.js `-r` flag:**
+
+```json
+{
+  "scripts": {
+    "dev": "node -r @dotenvage/node/nextjs/preinit node_modules/.bin/next dev",
+    "build": "node -r @dotenvage/node/nextjs/preinit node_modules/.bin/next build"
+  }
+}
+```
+
+1. **Via wrapper script (recommended):**
+
+See `wrapper.mjs` below.
+
+### `nextjs-wrapper.mjs`
+
+A wrapper script that loads environment variables and then starts
+Next.js. This is the easiest way to ensure proper loading order.
+
+**The wrapper automatically:**
+
+- Detects your package manager (pnpm/npm/yarn) by checking for lock
+  files
+- Uses the correct package manager's `exec` command to run Next.js
+- Handles path resolution automatically for all package manager setups
+- Works reliably in monorepos and pnpm workspaces
+
+**Usage - Update your `package.json`:**
+
+```json
+{
+  "scripts": {
+    "dev": "dotenvage-next dev",
+    "build": "dotenvage-next build"
+  }
+}
+```
+
+That's it! No need to create local wrapper scripts - the
+`dotenvage-next` bin script handles everything automatically. The
+`dotenvage-next` command is installed when you install
+`@dotenvage/node`.
+
+## Complete Integration Example
+
+1. **Install dotenvage:**
+
+```bash
+npm install @dotenvage/node
+```
+
+2. **Encrypt your `.env` files:**
+
+```bash
+npx dotenvage encrypt .env.local
+```
+
+3. **Set your encryption key as an environment variable:**
+
+```bash
+export EKG_AGE_KEY=your-key-name
+# or
+export DOTENVAGE_AGE_KEY="your-age-key-string"
+# or
+export AGE_KEY="your-age-key-string"
+```
+
+4. **Create a wrapper script** (see `wrapper.mjs` example above, or
+   use the one in this directory)
+
+5. **Update your `next.config.mjs`** (optional, for additional
+   safety):
+
+```javascript
+import { loadEnv } from "@dotenvage/node/nextjs";
+
+// This is a backup - the preinit loader should have already loaded
+// but this ensures variables are available if preinit wasn't used
+loadEnv();
+
+export default {
+  // Your Next.js config
+  env: {
+    // Explicitly expose critical variables to ensure they're inlined
+    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:
+      process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY || "",
+  },
+};
+```
+
+## How It Works
+
+1. **Pre-init loader runs first** → Decrypts `.env` files → Sets
+   values in `process.env`
+2. **Next.js starts** → `@next/env` runs → Sees existing values →
+   Doesn't overwrite
+3. **Next.js builds** → Inlines `NEXT_PUBLIC_*` variables → Uses
+   decrypted values ✅
+4. **Edge Runtime** → Has access to decrypted `NEXT_PUBLIC_*`
+   variables ✅
+
+## Troubleshooting
+
+### Variables still encrypted in Edge Runtime
+
+- Make sure you're using the pre-init loader (not just the standard
+  loader)
+- Verify the wrapper script is being used in your `package.json`
+  scripts
+- Check that the encryption key is set correctly
+
+### Variables not loading
+
+- Check that your encryption key environment variable is set
+- Verify your `.env` files contain encrypted values (starting with
+  `ENC[AGE:`)
+- Check console output for error messages from the loader
+
+### Build fails
+
+- In production/Vercel, ensure the encryption key is set as an
+  environment variable
+- The pre-init loader will fail hard in production if it can't decrypt
+  files
+- Check Vercel environment variables section in your project settings
+
+## See Also
+
+- [dotenvage main documentation](../../README.md)
+- [Next.js environment variables documentation](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables)

package/nextjs/config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Next.js configuration wrapper that automatically loads encrypted environment variables
+ *
+ * @module @dotenvage/node/nextjs/config
+ */
+
+import type { NextConfig } from 'next'
+
+/**
+ * Wraps a Next.js configuration object to ensure dotenvage is loaded.
+ * Environment variables are automatically loaded when this module is imported.
+ *
+ * @param config - Next.js config object or function
+ * @returns The same config (pass-through wrapper)
+ */
+export function withDotenvage(
+  config: NextConfig | ((phase: string) => NextConfig),
+): NextConfig | ((phase: string) => NextConfig)
+
+/**
+ * Wraps a Next.js configuration function to ensure dotenvage is loaded.
+ * Useful when you need to access the build phase.
+ *
+ * @param configFn - Next.js config function
+ * @returns The same function (pass-through wrapper)
+ */
+export function withDotenvageConfig(
+  configFn: (
+    phase: string,
+    defaultConfig: NextConfig,
+  ) => NextConfig | Promise<NextConfig>,
+): (phase: string, defaultConfig: NextConfig) => NextConfig | Promise<NextConfig>

package/nextjs/config.mjs

@@ -0,0 +1,59 @@
+/**
+ * Next.js configuration wrapper for dotenvage integration.
+ *
+ * This wrapper can be used in two ways:
+ *
+ * 1. **With wrapper script (recommended for Edge Runtime):**
+ *    Use `dotenvage-next` bin script to start Next.js:
+ *      "dev": "dotenvage-next dev"
+ *      "build": "dotenvage-next build"
+ *    The wrapper script loads env vars BEFORE Next.js starts, ensuring
+ *    they're available everywhere including Edge Runtime.
+ *
+ * 2. **Without wrapper script (server-side only, no Edge Runtime):**
+ *    Use `loadEnv()` from `@dotenvage/node/nextjs` in your config file:
+ *      import { loadEnv } from '@dotenvage/node/nextjs'
+ *      loadEnv()
+ *    Note: This only works for server-side code, not Edge Runtime/middleware.
+ *
+ * Usage in next.config.mjs:
+ *   import { withDotenvage } from '@dotenvage/node/nextjs/config'
+ *   import nextMDX from '@next/mdx'
+ *
+ *   const nextConfig = {
+ *     // your config
+ *   }
+ *
+ *   export default withDotenvage(nextConfig)
+ *
+ * IMPORTANT: When using `dotenvage-next` wrapper script, env vars are
+ * already loaded, so this wrapper is just a pass-through for consistency.
+ * When NOT using the wrapper script, use `loadEnv()` directly in your config.
+ */
+
+/**
+ * Wraps a Next.js configuration object.
+ * This is mainly for convenience and API consistency.
+ * When using `dotenvage-next` wrapper script, env vars are already loaded.
+ *
+ * @param {import('next').NextConfig | ((phase: string) => import('next').NextConfig)} config - Next.js config object or function
+ * @returns {import('next').NextConfig | ((phase: string) => import('next').NextConfig)} The same config (pass-through)
+ */
+export function withDotenvage(config) {
+  // Pass-through wrapper for API consistency
+  // When using `dotenvage-next` wrapper script, env vars are already loaded
+  return config;
+}
+
+/**
+ * Wraps a Next.js configuration function to ensure dotenvage is loaded.
+ * Useful when you need to access the build phase.
+ *
+ * @param {(phase: string, defaultConfig: import('next').NextConfig) => import('next').NextConfig} configFn - Next.js config function
+ * @returns {(phase: string, defaultConfig: import('next').NextConfig) => import('next').NextConfig} The same function (pass-through)
+ */
+export function withDotenvageConfig(configFn) {
+  // Pass-through wrapper for API consistency
+  // When using `dotenvage-next` wrapper script, env vars are already loaded
+  return configFn;
+}

package/nextjs/loader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Next.js environment variable loader using dotenvage
+ *
+ * @module @dotenvage/node/nextjs
+ */
+
+/**
+ * Loads environment variables from encrypted .env files
+ * This runs automatically when this module is imported
+ * Always loads from dotenvage in all environments (local, Vercel CI, production)
+ */
+export function loadEnv(): void
+
+/**
+ * Get all environment variables (for testing/debugging)
+ */
+export function getAllEnvVars(): Record<string, string>
+
+/**
+ * Get variable names (for testing/debugging)
+ */
+export function getEnvVarNames(): string[]

package/nextjs/loader.mjs

@@ -0,0 +1,117 @@
+/**
+ * Next.js environment variable loader using dotenvage
+ *
+ * This module loads encrypted .env files at runtime, making environment
+ * variables available to the Next.js application.
+ *
+ * It automatically loads encrypted .env files in all environments:
+ * - Local development (loads from .env, .env.local, etc.)
+ * - Vercel CI (loads from committed encrypted .env files)
+ * - Production builds (loads from committed encrypted .env files)
+ *
+ * For Vercel CI, you only need to set the encryption key as an environment variable:
+ * - EKG_AGE_KEY (for key name-based lookup: ekg/dr-rs-ekg)
+ * - DOTENVAGE_AGE_KEY or AGE_KEY (for direct key string)
+ *
+ * Encrypted .env files are committed to git and loaded at runtime.
+ * No need to sync environment variables to Vercel separately.
+ *
+ * Usage in next.config.mjs:
+ *   import { loadEnv } from '@dotenvage/node/nextjs'
+ *   loadEnv()
+ */
+import * as dotenvage from "../index.js";
+
+let loaded = false;
+
+/**
+ * Loads environment variables from encrypted .env files
+ * This runs automatically when this module is imported
+ * Always loads from dotenvage in all environments (local, Vercel CI, production)
+ */
+export function loadEnv() {
+  // Only load once
+  if (loaded) {
+    return;
+  }
+
+  try {
+    // Create loader and load environment variables from encrypted .env files
+    // This mutates process.env with decrypted values
+    // Works in all environments: local, Vercel CI, production
+    const loader = dotenvage.JsEnvLoader.new();
+    loader.load();
+
+    const variableNames = loader.getAllVariableNames();
+    const isProduction = process.env.NODE_ENV === "production";
+
+    if (!isProduction || process.env.VERCEL) {
+      console.log(
+        `✓ Loaded ${variableNames.length} environment variables from dotenvage`
+      );
+    }
+
+    loaded = true;
+  } catch (error) {
+    // Always show errors - we need to know if loading fails
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+    console.error(
+      "❌ Failed to load environment variables from dotenvage:",
+      errorMessage
+    );
+    console.error("");
+    console.error("  Make sure one of these is set:");
+    console.error(
+      "    - EKG_AGE_KEY (for key name-based lookup: ekg/dr-rs-ekg)"
+    );
+    console.error("    - DOTENVAGE_AGE_KEY (direct key string)");
+    console.error("    - AGE_KEY (direct key string)");
+    console.error(
+      "    - EKG_AGE_KEY_NAME in .env file (points to key file location)"
+    );
+    console.error("");
+
+    // In production/Vercel, fail hard - we need env vars to work
+    if (process.env.NODE_ENV === "production" || process.env.VERCEL) {
+      console.error(
+        "  This is a production build. Environment variables are required!"
+      );
+      process.exit(1);
+    }
+
+    // In development, warn but continue (might be missing key for testing)
+    console.warn(
+      "  Continuing in development mode, but some features may not work."
+    );
+
+    // Mark as loaded to prevent retry loops
+    loaded = true;
+  }
+}
+
+/**
+ * Get all environment variables (for testing/debugging)
+ */
+export function getAllEnvVars() {
+  try {
+    const loader = dotenvage.JsEnvLoader.new();
+    return loader.getAllVariables();
+  } catch (error) {
+    console.error("Error getting environment variables:", error);
+    return {};
+  }
+}
+
+/**
+ * Get variable names (for testing/debugging)
+ */
+export function getEnvVarNames() {
+  try {
+    const loader = dotenvage.JsEnvLoader.new();
+    return loader.getAllVariableNames();
+  } catch (error) {
+    console.error("Error getting variable names:", error);
+    return [];
+  }
+}

package/nextjs/preinit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pre-initialization environment variable loader for Next.js
+ *
+ * This module loads encrypted .env files BEFORE Next.js loads its own .env files.
+ * It must be loaded before Next.js starts (via -r flag, require hook, or wrapper script).
+ *
+ * @module @dotenvage/node/nextjs/preinit
+ */
+
+// This module has side effects (loads environment variables)
+// TypeScript declaration for importing the module
+declare const _default: void
+export default _default

package/nextjs/preinit.mjs

@@ -0,0 +1,106 @@
+/**
+ * Pre-initialization environment variable loader for Next.js
+ *
+ * This module loads encrypted .env files BEFORE Next.js loads its own .env files.
+ * It must be loaded before Next.js starts (via -r flag, require hook, or wrapper script).
+ *
+ * IMPORTANT: Next.js's @next/env does NOT overwrite existing process.env values.
+ * By loading encrypted env vars FIRST, we ensure:
+ * 1. Encrypted values are decrypted and set in process.env
+ * 2. When @next/env runs, it sees existing values and doesn't overwrite them
+ * 3. Decrypted values are preserved throughout the Next.js build/runtime
+ *
+ * This is critical for Edge Runtime (middleware) where NEXT_PUBLIC_* variables
+ * need to be inlined at build time.
+ *
+ * Usage:
+ *   - Via -r flag: node -r @dotenvage/node/nextjs/preinit node_modules/.bin/next dev
+ *   - Via wrapper script: See wrapper.mjs
+ */
+import * as dotenvage from "../index.js";
+
+let loaded = false;
+
+/**
+ * Loads environment variables from encrypted .env files
+ * This runs immediately when this module is imported
+ *
+ * Note: @next/env respects existing process.env values and won't overwrite them,
+ * so by loading first, our decrypted values take precedence over the encrypted .env files.
+ */
+function loadEnvPreinit() {
+  // Only load once
+  if (loaded) {
+    return;
+  }
+
+  try {
+    // Store which variables existed before loading (for debugging)
+    const existingVars = new Set(Object.keys(process.env));
+
+    // Create loader and load environment variables from encrypted .env files
+    // This mutates process.env with decrypted values
+    const loader = dotenvage.JsEnvLoader.new();
+    loader.load();
+
+    const variableNames = loader.getAllVariableNames();
+    const isProduction = process.env.NODE_ENV === "production";
+
+    // Check which variables we loaded that didn't exist before
+    const newlyLoadedVars = variableNames.filter(
+      (name) => !existingVars.has(name)
+    );
+    const overwrittenVars = variableNames.filter((name) =>
+      existingVars.has(name)
+    );
+
+    if (!isProduction || process.env.VERCEL) {
+      console.log(
+        `✓ Pre-initialized ${variableNames.length} environment variables from dotenvage`
+      );
+      if (
+        overwrittenVars.length > 0 &&
+        process.env.NODE_ENV === "development"
+      ) {
+        console.log(
+          `  Note: ${overwrittenVars.length} variables already existed and were preserved`
+        );
+      }
+    }
+
+    loaded = true;
+  } catch (error) {
+    // Always show errors - we need to know if loading fails
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+    console.error(
+      "❌ Failed to pre-initialize environment variables from dotenvage:",
+      errorMessage
+    );
+    console.error("");
+    console.error("  Make sure one of these is set:");
+    console.error(
+      "    - EKG_AGE_KEY (for key name-based lookup: ekg/dr-rs-ekg)"
+    );
+    console.error("    - DOTENVAGE_AGE_KEY (direct key string)");
+    console.error("    - AGE_KEY (direct key string)");
+    console.error("");
+
+    // In production/Vercel, fail hard - we need env vars to work
+    if (process.env.NODE_ENV === "production" || process.env.VERCEL) {
+      console.error(
+        "  This is a production build. Environment variables are required!"
+      );
+      process.exit(1);
+    }
+
+    // In development, warn but continue
+    console.warn(
+      "  Continuing in development mode, but some features may not work."
+    );
+    loaded = true;
+  }
+}
+
+// Auto-load when this module is imported
+loadEnvPreinit();