@marvalt/digivalt-core

Core DigiVAlt package for static data generation, runtime service wiring, and Cloudflare Pages bootstrap helpers.

Installation

npm install @marvalt/digivalt-core

Full handover docs: docs/README.md and docs/ENVIRONMENT.md. After install: node_modules/@marvalt/digivalt-core/docs/README.md.

In the DigiVAlt monorepo, digivalt-landing is the reference Vite app used to test this package with WordPress plugins and Cloudflare Pages.

Entry Points

Prefer explicit subpath imports so Node/build-time code does not pull browser runtime modules:

import { generateAllData } from '@marvalt/digivalt-core/generators';
import { getIntegrationConfig } from '@marvalt/digivalt-core/config';
import { loadWordPressData } from '@marvalt/digivalt-core/static';
import { gravityFormsService } from '@marvalt/digivalt-core/services';

The root package export remains as a thin compatibility layer for generator-focused consumers.

SEO and PageSpeed

• Subpath: import { DigiValtSeoHead, JsonLd, buildEventJsonLd, ... } from '@marvalt/digivalt-core/seo'
• Peer dependency: react-helmet-async (v2+). Wrap the app in HelmetProvider.
• Env: VITE_SEO_* only (VITE_SEO_SITE_URL, VITE_SEO_SITE_NAME, VITE_SEO_DEFAULT_TITLE, …). See docs/SEO-PERFORMANCE.md.
• Config: getSEOConfig() / getPerformanceConfig() in @marvalt/digivalt-core/config read the same VITE_* values.

Init Workflow

Run npx digivalt-init inside a Vite/Lovable app root. The command now validates the target folder, inspects existing DigiVAlt wiring, and patches safe cases automatically.

Useful flags:

• --target <path> to initialize a different app folder
• --dry-run to preview copied files without writing anything
• --force-template to overwrite DigiVAlt-managed template files intentionally

What init now does:

• copies missing template files into the app
• creates or updates .env.example and .env.local.example using a marker-wrapped DigiValt-managed block (safe to rerun; custom lines outside the block are preserved)
• adds or updates generate, build, and build:dev scripts when the app is still on plain Vite wiring
• refreshes scripts/generate.ts when it matches an older DigiVAlt-managed version
• warns instead of overwriting custom build logic or custom generator scripts
• reports stale legacy workarounds such as alias-link scripts and old root package generator imports

When to rerun it:

• after first installing DigiVAlt in a fresh app
• after upgrading @marvalt/digivalt-core when scaffolded build wiring changes
• before publishing a new app if you want a quick preflight of the DigiVAlt setup

Sitemap: Each build regenerates public/sitemap-paths.json from public/sitemap-static-paths.json (paths you add for SPA-only routes) plus WordPress menu and CPT links in wordpress-data.json. See docs/SEO-PERFORMANCE.md.

Google Reviews static data: Opt in by adding google_reviews to VITE_ENABLED_POST_TYPES (requires the vibune-google-reviews WordPress plugin). When enabled, generateAllData() fetches the plugin REST route and writes public/google-reviews-data.json. By default the endpoint is derived from WORDPRESS_API_URL / VITE_WORDPRESS_API_URL (/wp-json/vibune-google-reviews/v1/reviews). Override with GOOGLE_REVIEWS_API_URL / VITE_GOOGLE_REVIEWS_API_URL when needed. When google_reviews is not listed, generation is skipped (same optional pattern as Mautic/SuiteCRM).

AI builders (Cursor / Claude Code / Antigravity / Lovable):

• Tool-agnostic master prompt: docs/LOVABLE-MASTER-PROMPT.md
• Local-first human runbook: docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md

Developing this package

This repo uses .npmrc with legacy-peer-deps=true so react-helmet-async installs cleanly alongside React 19-compatible transitive deps during local builds. Consumers of the published package only need to satisfy peers (react, react-dom, react-helmet-async).

Cloudflare Secrets

Use node scripts/deploy-secrets.js after digivalt-init.

The helper now:

• uploads only DigiVAlt-related environment variables (including VITE_SEO_* and server-only TURNSTILE_SECRET_KEY when present)
• skips NODE_ENV, VITE_IS_LOVABLE, VITE_LOCAL_DEVELOPMENT, VITE_AUTH_MODE, and VITE_DEFAULT_MAX_ITEMS (set those locally or in the Pages dashboard instead of bulk upload)
• fails with a non-zero exit code when Wrangler or project detection fails