feat: add DEPLOYMENT_ENV variable for environment-specific website configuration (#335)

# Add DEPLOYMENT_ENV variable to improve environment handling

This PR introduces a new `DEPLOYMENT_ENV` environment variable to better manage differences between production and preview deployments:

- Added `DEPLOYMENT_ENV` to the CI workflow, automatically set to 'production' for main branch and 'preview' for pull requests
- Updated `astro.config.mjs` to validate environment variables based on deployment type:
  - Production deployments require `PLAUSIBLE_PROXY_URL` to be set
  - Preview deployments make `PLAUSIBLE_PROXY_URL` optional (falls back to default)
- Improved robots.txt configuration to use the new environment variable instead of `CF_PAGES_BRANCH`
- Enhanced documentation in `DEPLOYMENT.md` with details about the new environment variable and validation requirements

These changes make the deployment process more robust by ensuring all required environment variables are present before deployment and providing clearer error messages when configuration is incomplete.

Author: jumski

.github/workflows/ci.yml

@@ -152,6 +152,7 @@ jobs:
       NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      DEPLOYMENT_ENV: ${{ github.event_name == 'pull_request' && 'preview' || 'production' }}
       VITE_SUPABASE_URL: ${{ github.event_name == 'pull_request' && secrets.WEBSITE_PREVIEW_SUPABASE_URL || secrets.WEBSITE_PRODUCTION_SUPABASE_URL }}
       VITE_SUPABASE_ANON_KEY: ${{ github.event_name == 'pull_request' && secrets.WEBSITE_PREVIEW_SUPABASE_ANON_KEY || secrets.WEBSITE_PRODUCTION_SUPABASE_ANON_KEY }}
       PLAUSIBLE_PROXY_URL: ${{ secrets.WEBSITE_PLAUSIBLE_PROXY_URL }}

pkgs/website/DEPLOYMENT.md

@@ -1,108 +1,72 @@
 # Website Deployment
 
-This document describes the deployment configuration for the pgflow documentation website.
+The pgflow documentation website is deployed to **Cloudflare Pages** via GitHub Actions.
 
-## Deployment Target
-
-The website is deployed to **Cloudflare Pages** via GitHub Actions workflow.
-
-- **Production URL**: https://www.pgflow.dev
-- **Preview URLs**: https://pr-{number}.pgflow.pages.dev (for pull requests)
+- **Production**: https://www.pgflow.dev
+- **Preview**: https://pr-{number}.pgflow.pages.dev
 
 ## Required GitHub Secrets
 
-The following secrets must be configured in the GitHub repository (Settings → Secrets and variables → Actions).
-
-**Note**: Some secrets are namespaced (e.g., `WEBSITE_*`) at the GitHub level but are mapped to simpler names (e.g., `VITE_*`, `PLAUSIBLE_PROXY_URL`) when passed as environment variables to the build process.
-
-### Cloudflare Configuration
-
-- **`CLOUDFLARE_API_TOKEN`**
-  - **GitHub Secret Name**: `CLOUDFLARE_API_TOKEN`
-  - **Environment variable**: `CLOUDFLARE_API_TOKEN`
-  - API token for deploying to Cloudflare Pages
-
-- **`CLOUDFLARE_ACCOUNT_ID`**
-  - **GitHub Secret Name**: `CLOUDFLARE_ACCOUNT_ID`
-  - **Environment variable**: `CLOUDFLARE_ACCOUNT_ID`
-  - Cloudflare account ID
-
-### Supabase Configuration
-
-Website deployment requires Supabase configuration for both preview and production environments:
+Configure these in repository Settings → Secrets and variables → Actions.
 
-**Preview Environment:**
-- **`WEBSITE_PREVIEW_SUPABASE_URL`**
-  - **GitHub Secret Name**: `WEBSITE_PREVIEW_SUPABASE_URL`
-  - **Maps to environment variable**: `VITE_SUPABASE_URL` (in preview deployments)
-  - Supabase project URL for preview deployments
+### Cloudflare
+- `CLOUDFLARE_API_TOKEN` - API token for Cloudflare Pages deployment
+- `CLOUDFLARE_ACCOUNT_ID` - Cloudflare account ID
 
-- **`WEBSITE_PREVIEW_SUPABASE_ANON_KEY`**
-  - **GitHub Secret Name**: `WEBSITE_PREVIEW_SUPABASE_ANON_KEY`
-  - **Maps to environment variable**: `VITE_SUPABASE_ANON_KEY` (in preview deployments)
-  - Supabase anonymous key for preview deployments
+### Supabase
 
-**Production Environment:**
-- **`WEBSITE_PRODUCTION_SUPABASE_URL`**
-  - **GitHub Secret Name**: `WEBSITE_PRODUCTION_SUPABASE_URL`
-  - **Maps to environment variable**: `VITE_SUPABASE_URL` (in production deployments)
-  - Supabase project URL for production
+**Preview:**
+- `WEBSITE_PREVIEW_SUPABASE_URL` → `VITE_SUPABASE_URL`
+- `WEBSITE_PREVIEW_SUPABASE_ANON_KEY` → `VITE_SUPABASE_ANON_KEY`
 
-- **`WEBSITE_PRODUCTION_SUPABASE_ANON_KEY`**
-  - **GitHub Secret Name**: `WEBSITE_PRODUCTION_SUPABASE_ANON_KEY`
-  - **Maps to environment variable**: `VITE_SUPABASE_ANON_KEY` (in production deployments)
-  - Supabase anonymous key for production
+**Production:**
+- `WEBSITE_PRODUCTION_SUPABASE_URL` → `VITE_SUPABASE_URL`
+- `WEBSITE_PRODUCTION_SUPABASE_ANON_KEY` → `VITE_SUPABASE_ANON_KEY`
 
-### Analytics Configuration
+### Analytics
+- `WEBSITE_PLAUSIBLE_PROXY_URL` → `PLAUSIBLE_PROXY_URL` (required for production only)
+  - Cloudflare Workers proxy URL for Plausible Analytics
+  - Example: `https://your-worker.your-username.workers.dev`
+  - Proxies requests to avoid ad blockers
 
-- **`WEBSITE_PLAUSIBLE_PROXY_URL`** - Cloudflare Workers proxy URL for Plausible Analytics (website-specific)
-  - **GitHub Secret Name**: `WEBSITE_PLAUSIBLE_PROXY_URL`
-  - **Maps to environment variable**: `PLAUSIBLE_PROXY_URL` (used in `astro.config.mjs`)
-  - Example value: `https://your-worker-name.your-username.workers.dev`
-  - This proxies requests to Plausible to avoid ad blockers
-  - If this URL becomes invalid, Plausible tracking will stop working
-  - Note: This is separate from demo app analytics which uses its own proxy URL
+### Deployment Environment
+- `DEPLOYMENT_ENV` - Set automatically by workflow (`production` or `preview`)
+  - Controls robots.txt and validates production requirements
+  - Not set for build/test jobs (safe defaults apply)
 
 ## Deployment Workflow
 
-The deployment is handled by the `deploy-website` job in `.github/workflows/ci.yml`:
+The `deploy-website` job in `.github/workflows/ci.yml`:
 
-1. **Trigger**: Runs on push to `main` or when a pull request is opened/updated
-2. **Affected Check**: Only deploys if the website package is affected by changes (using Nx)
-3. **Build**: Builds the website with environment variables injected
-4. **Deploy**:
-   - Production: Deploys to main branch on Cloudflare Pages
-   - Preview: Deploys to PR-specific branch on Cloudflare Pages
+1. Triggers on push to `main` or PR updates
+2. Checks if website is affected (Nx)
+3. Sets `DEPLOYMENT_ENV` based on branch
+4. Builds with injected environment variables
+   - Production: Requires `PLAUSIBLE_PROXY_URL`, enables indexing
+   - Preview: Optional `PLAUSIBLE_PROXY_URL`, blocks indexing
+5. Deploys to Cloudflare Pages
 
 ## Local Development
 
-For local development, the Plausible proxy URL falls back to a hardcoded value in `astro.config.mjs` if the `PLAUSIBLE_PROXY_URL` environment variable is not set.
-
-To test with a specific proxy URL locally:
+No environment variables required. Optional overrides:
 
 ```bash
+# With custom proxy
 PLAUSIBLE_PROXY_URL=https://your-worker.your-username.workers.dev pnpm nx dev website
+
+# Test production behavior
+DEPLOYMENT_ENV=production PLAUSIBLE_PROXY_URL=https://your-worker.your-username.workers.dev pnpm nx dev website
 ```
 
 ## Troubleshooting
 
-### Plausible Analytics Not Tracking
-
-If Plausible stops tracking visitors:
-
-1. Check if the Cloudflare Workers proxy URL is accessible:
-   ```bash
-   curl -I https://your-worker-name.your-username.workers.dev/assets/script.hash.outbound-links.pageview-props.tagged-events.js
-   ```
-
-2. If the URL fails (DNS resolution error or 404), update the `WEBSITE_PLAUSIBLE_PROXY_URL` secret in GitHub with the correct URL
-
-3. The proxy URL may change if the Cloudflare Workers username changes
-
-4. After updating the secret, redeploy the website (push to `main` or re-run the workflow)
-
-### Deployment Fails
+**Analytics not tracking:**
+- Verify proxy URL: `curl -I https://your-worker.your-username.workers.dev/assets/script...js`
+- Update `WEBSITE_PLAUSIBLE_PROXY_URL` secret if needed
+- Redeploy website
 
-- Verify all required secrets are configured in GitHub
-- Check the GitHub Actions workflow logs for specific error messages
-- Ensure the Cloudflare API token has the necessary permissions (Account → Cloudflare Pages - Edit)
+**Build errors:**
+- `DEPLOYMENT_ENV must be either 'production' or 'preview'` - Invalid value in workflow
+- `PLAUSIBLE_PROXY_URL required for production` - Missing `WEBSITE_PLAUSIBLE_PROXY_URL` secret
+- Check workflow logs for details
+- Verify Cloudflare API token permissions

pkgs/website/astro.config.mjs

@@ -16,6 +16,21 @@ import { redirects } from './redirects.config.mjs';
 const GITHUB_REPO_URL = 'https://github.com/pgflow-dev/pgflow';
 const DISCORD_INVITE_URL = 'https://pgflow.dev/discord/';
 const EMAIL_URL = 'mailto:hello@pgflow.dev';
+
+// Environment detection
+const DEPLOYMENT_ENV = process.env.DEPLOYMENT_ENV; // 'production' or 'preview' (optional)
+const isProduction = DEPLOYMENT_ENV === 'production';
+
+// Validate DEPLOYMENT_ENV if set
+if (DEPLOYMENT_ENV && DEPLOYMENT_ENV !== 'production' && DEPLOYMENT_ENV !== 'preview') {
+  throw new Error(`DEPLOYMENT_ENV must be either "production" or "preview", got: "${DEPLOYMENT_ENV}"`);
+}
+
+// Require Plausible proxy URL only for production
+if (isProduction && !process.env.PLAUSIBLE_PROXY_URL) {
+  throw new Error('PLAUSIBLE_PROXY_URL environment variable is required for production deployments');
+}
+
 const PLAUSIBLE_PROXY = {
   url: process.env.PLAUSIBLE_PROXY_URL || 'https://wispy-pond-c6f8.jumski.workers.dev',
   eventPath: '/data/event',
@@ -64,17 +79,12 @@ export default defineConfig({
     starlight({
       favicon: '/favicons/favicon.ico',
       head: [
-        // prevent robots from indexing the preview branches
-        // it can be determined by checking the appropriate env variable
-        // CF_PAGES_BRANCH != 'main'
+        // prevent robots from indexing the preview deployments
         {
           tag: 'meta',
           attrs: {
             name: 'robots',
-            content:
-              process.env.CF_PAGES_BRANCH === 'main'
-                ? 'index,follow'
-                : 'noindex,nofollow',
+            content: isProduction ? 'index,follow' : 'noindex,nofollow',
           },
         },
         {
@@ -464,8 +474,8 @@ export default defineConfig({
       policy: [
         {
           userAgent: '*',
-          allow: process.env.CF_PAGES_BRANCH === 'main' ? '/' : '',
-          disallow: process.env.CF_PAGES_BRANCH === 'main' ? '' : '/',
+          allow: isProduction ? '/' : '',
+          disallow: isProduction ? '' : '/',
         },
       ],
     }),