docs: clarify environment variable usage and add .env.production (#141)

nullcoder · claude · web-flow · commit 02aff3a8b277 · 2025-06-08T01:54:25.000-07:00
- Add .env.production with clear warnings about not putting secrets - Update documentation to explain build-time vs runtime variables - Emphasize that .env files are for NEXT_PUBLIC_* variables only - Clarify that secrets must use .dev.vars locally or wrangler secrets in production - Add warnings throughout docs to prevent accidental secret exposure This helps prevent developers from accidentally exposing secrets in the client bundle by putting them in .env or .env.production files. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.env.production b/.env.production
@@ -0,0 +1,8 @@
+# Production build-time environment variables
+# IMPORTANT: This file is used during the build process only
+# DO NOT put any secrets here - they would be exposed in the client bundle
+# Only NEXT_PUBLIC_* variables should go here as they are meant to be public
+# For secrets, use Cloudflare Workers secrets via 'wrangler secret put'
+
+# Turnstile site key for production
+NEXT_PUBLIC_TURNSTILE_SITE_KEY=0x4AAAAAABgaxmj8dZ-K1EyE
diff --git a/README.md b/README.md
@@ -155,12 +155,24 @@ bucket_name = "ghostpaste-bucket"
 NEXT_PUBLIC_APP_URL = "https://ghostpaste.dev"
 ```
 
-For local development secrets, create `.dev.vars`:
+For environment variables:
 
+**Build-time variables** (`.env` or `.env.production`):
+
+```bash
+# Only NEXT_PUBLIC_* variables - these are embedded in the client bundle
+NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_public_site_key
 ```
-# Any additional secrets go here
+
+**Runtime secrets** (`.dev.vars` for local, `wrangler secret put` for production):
+
+```bash
+# Never put these in .env files!
+TURNSTILE_SECRET_KEY=your_secret_key
 ```
 
+⚠️ **Important**: Never put secrets in `.env` or `.env.production` files as they become part of the client bundle!
+
 ### Deployment
 
 ```bash
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
@@ -24,14 +24,33 @@ This guide explains how to set up and run GhostPaste locally for development.
    ```
 
 3. **Set up local environment variables**
-   Create a `.dev.vars` file in the root directory:
+
+   GhostPaste uses different environment files for different purposes:
+
+   - **`.env`** - Build-time variables for local development (loaded by Next.js during build)
+   - **`.env.production`** - Build-time variables for production builds (PUBLIC variables only - NO SECRETS!)
+   - **`.dev.vars`** - Runtime secrets for local Wrangler development
+   - **Cloudflare Secrets** - Runtime secrets for production (via `wrangler secret put`)
+
+   Create these files as needed:
+
+   **`.env`** (for local build-time variables):
+
    ```bash
-   # Local development secrets
-   # Add any local development secrets here
-   # Example:
-   # API_SECRET=your-secret-here
+   # Public variables that are safe to expose in the client bundle
+   NEXT_PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA
    ```
 
+   **`.dev.vars`** (for local runtime secrets):
+
+   ```bash
+   # Runtime secrets - these are NOT exposed to the client
+   TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
+   # Add other local development secrets here
+   ```
+
+   **Important**: Never put secrets in `.env` or `.env.production` files as they are embedded in the client bundle during build!
+
 ## Development Workflows
 
 ### Standard Next.js Development
@@ -106,8 +125,9 @@ When using `npm run preview`, the following services are simulated locally:
 
 ### Environment Variables
 
-- Development environment uses `env.development` from `wrangler.toml`
-- Secrets loaded from `.dev.vars` file
+- Build-time variables (NEXT*PUBLIC*\*) loaded from `.env` during build
+- Runtime environment uses `env.development` from `wrangler.toml`
+- Runtime secrets loaded from `.dev.vars` file
 - `ENVIRONMENT=development` and `NEXT_PUBLIC_APP_URL=http://localhost:3000`
 
 ## Debugging
diff --git a/docs/TURNSTILE_SETUP.md b/docs/TURNSTILE_SETUP.md
@@ -47,14 +47,23 @@ TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
 
 #### Production (Cloudflare Workers)
 
-1. Update `wrangler.toml` with the public site key:
+1. For production builds, create `.env.production`:
+
+   ```bash
+   # IMPORTANT: Only put PUBLIC variables here - NO SECRETS!
+   NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here
+   ```
+
+   **Warning**: `.env.production` is used at build time and variables are embedded in the client bundle. Never put secret keys here!
+
+2. Alternatively, update `wrangler.toml` with the public site key:
 
    ```toml
    [vars]
    NEXT_PUBLIC_TURNSTILE_SITE_KEY = "your_site_key_here"
    ```
 
-2. Set the secret key as a Cloudflare secret:
+3. Set the secret key as a Cloudflare secret:
 
    ```bash
    wrangler secret put TURNSTILE_SECRET_KEY
