@marvalt/digivalt-core 0.2.13 → 0.2.16

package/docs/ENVIRONMENT.md

@@ -0,0 +1,51 @@
+# DigiVAlt environment variables
+
+This document is the handover reference for **DevOps** (Cloudflare, secrets) and **app developers** using `@marvalt/digivalt-core`. The **canonical list of variable lines** that `npx digivalt-init` installs lives in the package at [`bin/env-example-fragments.cjs`](../bin/env-example-fragments.cjs). The same content is committed as [`.env.example`](../.env.example) and [`.env.local.example`](../.env.local.example) for browsing in Git or the IDE; **when you change the fragments file, update those two files in the same change**.
+
+## Two-file model (developers)
+
+- **`.env.example`** — team-safe, public-style placeholders. Copy to **`.env`** if your tools only read `.env`.
+- **`.env.local.example`** — same idea for secrets. Copy to **`.env.local`** and fill real values. **Never commit** `.env` or `.env.local` with production secrets.
+- Vite exposes only variables whose names are prefixed with **`VITE_`** to the browser (except where Node-only scripts read `process.env` at build or in Pages Functions; see below).
+
+## `npx digivalt-init` and the managed block
+
+Run **`npx digivalt-init`** in the app root after first adding DigiVAlt or after upgrading `@marvalt/digivalt-core` when you want the latest scaffolded env template.
+
+The command **creates or updates** `.env.example` and `.env.local.example`. The DigiValt content is wrapped in markers (see [`bin/init.cjs`](../bin/init.cjs): `ENV_MANAGED_START` / `ENV_MANAGED_END`). **Lines you add outside that block are preserved**; the block itself is replaced when you rerun init so teams stay aligned with the package. If an old file has no markers, init **appends** the block and warns you to merge manually once.
+
+**Node / static generation aliases:** Generators and some scripts also accept un-prefixed names (e.g. `WORDPRESS_API_URL`, `WP_API_USERNAME`) as alternatives to `VITE_*` when running under Node. Prefer the `VITE_` names in app repos for consistency.
+
+**`VITE_IS_LOVABLE` (generators only):** Used in hosted Lovable/CI “fixture” flows to skip live API fetches. **Do not set this in local full-data development.** See [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and your app’s `DIGIVALT_SETUP.md`. It is **not** part of the managed example block; it is listed in `deploy-secrets` excluded keys (below).
+
+## Handover to DevOps (Cloudflare and secrets)
+
+### `node scripts/deploy-secrets.js`
+
+After `digivalt-init`, the app has [`scripts/deploy-secrets.js`](../template/scripts/deploy-secrets.js) (from the template). It reads **`.env`** and **`.env.local`**, then uploads only keys that pass an **allowlist** to Cloudflare Pages via Wrangler `pages secret bulk`.
+
+- **Allowlist (summary):** patterns include `CLOUDFLARE_*`, `CF_ACCESS_*`, `TURNSTILE_*`, `VITE_SEO_*`, and `VITE_`-prefixed keys for WordPress, Gravity Forms, Mautic, SuiteCRM, Supabase, Cloudflare worker URL, auth, Turnstile, Chatwoot, theme, and similar integrations (see the `allowedPatterns` array in the script).
+- **Excluded from bulk upload (set in the Pages UI or locally instead):** `NODE_ENV`, `VITE_IS_LOVABLE`, `VITE_LOCAL_DEVELOPMENT`, `VITE_AUTH_MODE`, `VITE_DEFAULT_MAX_ITEMS` — so environment-specific or non-secret toggles are not mass-synced.
+- **Empty values** are skipped. **`CLOUDFLARE_ACCOUNT_ID`** in env is used when invoking Wrangler; the **project name** comes from **`wrangler.toml`** in the app root.
+- **Turnstile:** `VITE_TURNSTILE_SITE_KEY` is for the browser; **`TURNSTILE_SECRET_KEY`** is server-only for Pages Functions (not a `VITE_` var). Both can appear in the allowlist path when set in your env files.
+
+### Wrangler and Pages
+
+Align **`name`** in `wrangler.toml` with your **Cloudflare Pages** project. Local Functions development may use **`.dev.vars.example`** (from the template) copied to `.dev.vars`.
+
+## Variable groups (what they’re for)
+
+| Area | Notes |
+|------|--------|
+| **WordPress / static gen** | `VITE_WORDPRESS_API_URL`, `VITE_AUTH_MODE`, `VITE_CLOUDFLARE_WORKER_URL`, `VITE_LOCAL_DEVELOPMENT`, `VITE_ENABLED_POST_TYPES`, `VITE_DEFAULT_MAX_ITEMS`, `VITE_USE_DSTYLER`, `VITE_FRONTEND_ID` / `VITE_FRONTEND_NAME` — used by hooks, generators, and `getIntegrationConfig` / `getAppEnvironmentConfig`. **`google_reviews`** in `VITE_ENABLED_POST_TYPES` is a pseudo-type (not a WordPress CPT): it opt-in enables build-time fetch of `public/google-reviews-data.json` via the `vibune-google-reviews` plugin. |
+| **Theme** | `VITE_THEME` — optional; see `loadTheme` in `config/themes`. |
+| **Integrations (URLs often public; secrets in `.env.local`)** | Mautic, SuiteCRM, Supabase, Chatwoot, Gravity Forms — see `getIntegrationConfig` in `src/config/integrations.ts`. `VITE_SUITECRM_TOKEN_URL` is optional for non-default OAuth token endpoints (`environment.ts`). |
+| **SEO** | `VITE_SEO_*` — see [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and `getSEOConfig`. |
+| **Performance** | `VITE_PERF_*` — optional toggles; see [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and `getPerformanceConfig`. |
+| **Secrets (typical in `.env.local`)** | WordPress app password, Cloudflare Access, Mautic API keys, GF keys, SuiteCRM creds, `VITE_FRONTEND_SECRET` / `VITE_WP_REFRESH_SECRET` (webhook), `VITE_TURNSTILE_SITE_KEY` + `TURNSTILE_SECRET_KEY`. |
+
+## Further reading
+
+- [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) — `VITE_SEO_*`, `VITE_PERF_*`, sitemap, Lovable / `VITE_IS_LOVABLE` behavior
+- [Template `DIGIVALT_SETUP.md`](../template/DIGIVALT_SETUP.md) — onboarding in a Vite app
+- [README.md](../README.md) — init workflow and `deploy-secrets` overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/digivalt-core",
-  "version": "0.2.13",
+  "version": "0.2.16",
   "description": "Core glue logic and shared context for DigiVAlt frontend applications",
   "license": "GPL-3.0-or-later",
   "main": "dist/index.cjs",
@@ -66,7 +66,8 @@
     "smoke:imports": "node ./scripts/smoke-imports.mjs",
     "smoke:init": "node ./scripts/smoke-init.cjs",
     "smoke:sitemap": "node ./scripts/test-sitemap-paths.cjs",
-    "smoke": "npm run smoke:imports && npm run smoke:init && npm run smoke:sitemap",
+    "smoke:google-reviews-gate": "node ./scripts/test-google-reviews-gate.cjs",
+    "smoke": "npm run smoke:imports && npm run smoke:init && npm run smoke:sitemap && npm run smoke:google-reviews-gate",
     "prepublishOnly": "npm run clean && npm run build && npm run smoke"
   },
   "devDependencies": {