diff --git a/docs/consultations/gemini-blueprint-css-build-2026-04-12.md b/docs/consultations/gemini-blueprint-css-build-2026-04-12.md new file mode 100644 index 0000000..bc4e5d8 --- /dev/null +++ b/docs/consultations/gemini-blueprint-css-build-2026-04-12.md @@ -0,0 +1,120 @@ +# Gemini Consultation: Blueprint CSS Module Build Failure — v1.1.0 Path Forward + +**Date:** April 12, 2026 +**From:** Michael (The Wizard) + Claude (Chronicler #84 — The Meridian) +**To:** Gemini (Architectural Partner) +**Re:** Blueprint beta-2026-01 breaks `yarn build:production` on Node 24 — dashboard badges blocked, need clean fix for v1.1.0 + +--- + +## Hey Gemini! 👋 + +We're building ModpackChecker — a commercial Blueprint extension for Pterodactyl Panel that we're selling on BuiltByBit. We're 52 hours from launch and hit a wall: the dashboard badge component (a React TSX file injected into Pterodactyl's frontend) can't be compiled because `yarn build:production` fails. We shipped v1.0.0 without the badges and listed them as "coming in v1.1.0," but we need your help planning the clean path forward. + +--- + +## The Situation + +**What ModpackChecker does:** +A Blueprint extension for Pterodactyl Panel 1.12.2 that monitors modpack versions across CurseForge, Modrinth, Technic, and FTB. It has three UI components: + +1. **Admin settings page** — PHP/Blade, works perfectly ✅ +2. **Console widget** — React TSX component on the server page, works perfectly ✅ +3. **Dashboard badges** — React TSX badges on server cards (orange dot = update available, green dot = up to date) — **BLOCKED** ❌ + +**The build error:** + +Running `yarn build:production` on a Pterodactyl 1.12.2 panel with Blueprint beta-2026-01 installed fails with 7 CSS module errors: + +``` +ERROR in ./resources/scripts/blueprint/ui/badge/styles.module.css +Module build failed (from ./node_modules/css-loader/dist/cjs.js): +Error: error:0308010C:digital envelope routines::unsupported +``` + +The same error repeats for 6 other CSS module files (button, dialog, inputs, console, files, activity). These are all Pterodactyl/Blueprint's own files — not ours. + +**Environment:** +- Node.js: v24.14.1 +- Pterodactyl: 1.12.2 +- Blueprint: beta-2026-01 +- webpack: 5.103.0 +- Build command: `cross-env NODE_ENV=production ./node_modules/.bin/webpack --mode production` +- No `--openssl-legacy-provider` flag in the build script + +**Root cause diagnosis:** +`error:0308010C:digital envelope routines::unsupported` is the classic Node.js 17+ OpenSSL 3.0 compatibility error. Node 24 uses OpenSSL 3.x which removed legacy digest support. Older versions of `css-loader` + `postcss-loader` use MD4 hashing internally, which is not supported in OpenSSL 3. + +**What we've confirmed:** +- The `UpdateBadge.tsx` injection into `ServerRow.tsx` is correct (we can see it in the source) +- The component simply can't be compiled into the bundle because the build fails before it gets there +- This is a pre-existing issue with Blueprint beta-2026-01 + Node 17+ — not caused by our code +- The console widget works because it uses a different injection path that doesn't require a fresh build + +**Our current build approach (build.sh excerpt):** +```bash +# Dashboard Badge Injection +cp "$EXT_DIR/views/dashboard/UpdateBadge.tsx" resources/scripts/components/dashboard/UpdateBadge.tsx + +# Inject into ServerRow.tsx +sed -i '1i import UpdateBadge from "@/components/dashboard/UpdateBadge";' resources/scripts/components/dashboard/ServerRow.tsx +sed -i 's|{server.name}

|{server.name}

|' resources/scripts/components/dashboard/ServerRow.tsx +``` + +--- + +## What We're Trying to Do + +For v1.1.0 of ModpackChecker, we want dashboard badges to work. We need to pick the right approach and we'd love your input before we commit to one. + +We see three possible paths: + +**Path A: Fix the OpenSSL issue with NODE_OPTIONS** +Set `NODE_OPTIONS=--openssl-legacy-provider` before the build. This tells Node to use the legacy OpenSSL provider which supports MD4. Quick fix, but feels hacky and `--openssl-legacy-provider` may be removed in future Node versions. + +**Path B: Downgrade Node.js on the Dev Panel for builds** +Use Node 16 or 18 (which don't have the OpenSSL 3 issue) for the build step. Could use `nvm` to switch. The production panel server runs whatever Node version it has, but builds only need to happen once per release. Less hacky than Path A. + +**Path C: Update webpack/css-loader to OpenSSL 3-compatible versions** +Upgrade the offending packages in Pterodactyl's `package.json`. Risk: Pterodactyl 1.12.2 is a specific version and upgrading its dependencies could break other things. Also gets overwritten if someone reinstalls Pterodactyl. + +**Path D: Pre-build the bundle ourselves and ship it** +Build the compiled JS bundle on our dev machine (with a working Node version), then have our `build.sh` copy the pre-built bundle directly into `public/assets/` instead of injecting TSX and relying on `yarn build`. This sidesteps the build issue entirely. Risk: the pre-built bundle is tied to a specific Pterodactyl version and won't work if the panel's other assets change. + +**Path E: Wait for Blueprint to fix it** +Blueprint beta-2026-01 presumably has this issue affecting all extension developers. They'll likely fix it in a future release. We could hold dashboard badges until Blueprint ships a compatible version. Least work for us, but timeline unknown. + +--- + +## Specific Questions + +1. **Which path do you recommend for v1.1.0?** Given that we're a commercial product that panel admins will install on their servers (which we don't control), what's the most robust approach? + +2. **Is Path A (NODE_OPTIONS=--openssl-legacy-provider) actually safe?** We'd add it to our build.sh: `export NODE_OPTIONS=--openssl-legacy-provider`. Is this still supported in Node 24? Is it being removed? + +3. **Is Path D (pre-built bundle) viable for a Blueprint extension?** Has anyone shipped a Blueprint extension with a pre-compiled JS bundle rather than injecting TSX? What are the pitfalls? + +4. **Should our build.sh detect the Node version and warn?** If the panel has an incompatible Node version, should we fail fast with a helpful error message rather than silently injecting TSX that won't compile? + +5. **For BuiltByBit listing copy** — how should we describe the dashboard badges in the "Upcoming Features / v1.1.0" section? We want to be honest about the dependency (requires a working `yarn build`) without scaring off buyers who might not understand what that means. + +6. **Is there a pattern in the Blueprint ecosystem for React components that don't require a build step?** Could we implement the badges as vanilla JS / DOM manipulation instead of React TSX, bypassing the build entirely? + +--- + +## Context That Might Help + +- Our customers are Pterodactyl panel admins — technically savvy, but not necessarily Node/webpack experts +- ModpackChecker is our first commercial product; we want it to feel polished +- We have a Dev Panel (Ubuntu 24.04, Node v24.14.1) that we control — we can install whatever we need there +- Customer panels run whatever Pterodactyl version they have; we target 1.12.2 +- Blueprint beta-2026-01 is the current stable-ish Blueprint release +- We ship a `.blueprint` package file; installation is `blueprint -install modpackchecker` +- The console widget (which works) uses Blueprint's own component injection system, not direct TSX → ServerRow injection + +--- + +Thanks Gemini! This one's been a fun puzzle. We shipped v1.0.0 clean and the core product works great — just want to nail the badge feature right for v1.1.0. 🔥❄️ + +— Michael + Claude (Chronicler #84 — The Meridian) +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️