@mdn/fred 1.1.1 → 1.3.0

package/.env-dist

@@ -2,8 +2,8 @@
 CONTENT_ROOT=../content/files
 # https://github.com/mdn/translated-content
 CONTENT_TRANSLATED_ROOT=../translated-content/files
-# https://github.com/mdn/mdn-studio
-BLOG_ROOT=../mdn-studio/content/posts
+# https://github.com/mdn/blog
+BLOG_ROOT=../blog/content/posts
 # https://github.com/mdn/curriculum/
 CURRICULUM_ROOT=../curriculum
 # https://github.com/mdn/mdn-contributor-spotlight
@@ -29,4 +29,4 @@ RARI_URL="http://localhost:8083"
 REACT_APP_KUMA_HOST="localhost:3000"
 REACT_APP_FXA_SIGNIN_URL="/users/fxa/login/authenticate/"
 REACT_APP_FXA_SETTINGS_URL="https://accounts.stage.mozaws.net/settings/"
-REACT_APP_PLACEMENT_ENABLED="true"
+REACT_APP_PLACEMENT_ENABLED="true"

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [1.3.0](https://github.com/mdn/fred/compare/v1.2.0...v1.3.0) (2025-09-01)
+
+
+### Features
+
+* **package/bin:** add fred-ssr executable ([#678](https://github.com/mdn/fred/issues/678)) ([faa175d](https://github.com/mdn/fred/commit/faa175dbf31d5cc715bccbcb9673572e8323e340))
+* **server:** allow specifiying port from env var ([#679](https://github.com/mdn/fred/issues/679)) ([eea7274](https://github.com/mdn/fred/commit/eea72742ed07d3e2230cc33c30a2f3a1fcc9b4d3))
+
+
+### Bug Fixes
+
+* **env:** prefix runtime var fallback only once ([eea7274](https://github.com/mdn/fred/commit/eea72742ed07d3e2230cc33c30a2f3a1fcc9b4d3))
+* **server:** omit Playground server link in output ([eea7274](https://github.com/mdn/fred/commit/eea72742ed07d3e2230cc33c30a2f3a1fcc9b4d3))
+
+
+### Miscellaneous
+
+* **deps-dev:** bump @mdn/browser-compat-data from 7.1.0 to 7.1.1 ([#677](https://github.com/mdn/fred/issues/677)) ([2a90bc2](https://github.com/mdn/fred/commit/2a90bc213785c778481299ae6fad996d3c5fe890))
+* **deps-dev:** bump the dev group with 2 updates ([#660](https://github.com/mdn/fred/issues/660)) ([08c2d3d](https://github.com/mdn/fred/commit/08c2d3d465ad31dcac9f0722856822d5da8f833c))
+* rename {mdn-studio => blog} ([#681](https://github.com/mdn/fred/issues/681)) ([39ab241](https://github.com/mdn/fred/commit/39ab241bf912f0f395634029d9fd11b784f28be1))
+
+## [1.2.0](https://github.com/mdn/fred/compare/v1.1.1...v1.2.0) (2025-08-28)
+
+
+### Features
+
+* **env:** add runtime variables ([#642](https://github.com/mdn/fred/issues/642)) ([ab504ef](https://github.com/mdn/fred/commit/ab504effc762002df03d709e9ed605f58b6b2b22))
+
+
+### Bug Fixes
+
+* **npm:** js/styles/assets weren't being found ([#641](https://github.com/mdn/fred/issues/641)) ([1c4e02a](https://github.com/mdn/fred/commit/1c4e02a2ea20da72e8a43b9362c8a285f060af5c))
+
 ## [1.1.1](https://github.com/mdn/fred/compare/v1.1.0...v1.1.1) (2025-08-28)
 
 

package/README.md

@@ -26,6 +26,10 @@ MDN's next fr(ont)e(n)d.
 
 ## Development principles
 
+### Environment variables
+
+See [the environment variables README](./components/env/README.md).
+
 ### Inline JS
 
 We need to run some JS as soon as possible at page load, to avoid layout shifts and flashes.

package/build/env.js

@@ -1,3 +1,12 @@
 import path from "node:path";
-export const BUILD_OUT_ROOT =
-  process.env.BUILD_OUT_ROOT || path.join(import.meta.dirname, "..", "out");
+
+const defaultOut = path.join(import.meta.dirname, "..", "out");
+const nodeModule = defaultOut.endsWith(
+  path.join("node_modules", "@mdn", "fred", "out"),
+);
+
+export const RARI_BUILD_ROOT = process.env.BUILD_OUT_ROOT || defaultOut;
+
+// When running from an npm package, this needs to be the default output directory,
+// so we can load the pre-built assets
+export const FRED_BUILD_ROOT = nodeModule ? defaultOut : RARI_BUILD_ROOT;

package/build/render.js

@@ -2,27 +2,23 @@ import { readFile } from "node:fs/promises";
 
 import path from "node:path";
 
-// TODO: this should respect process.env.BUILD_OUT_ROOT at runtime
-// but when we package it into an npm package, it needs to be a relative path
-// based on the value of BUILD_OUT_ROOT at that point in time
-// https://github.com/mdn/fred/issues/594
-const BUILD_OUT_ROOT = path.resolve(import.meta.dirname, "..", "out");
+import { FRED_BUILD_ROOT } from "./env.js";
 
 const { render: distRender } = /** @type {import("../entry.ssr.js")} */ (
-  await import(path.resolve(BUILD_OUT_ROOT, "static", "ssr", "index.js"))
+  await import(path.resolve(FRED_BUILD_ROOT, "static", "ssr", "index.js"))
 );
 
 /** @type {import("@rspack/core").StatsCompilation} */
 const clientManifest = JSON.parse(
   await readFile(
-    path.join(BUILD_OUT_ROOT, "static", "client", "stats.json"),
+    path.join(FRED_BUILD_ROOT, "static", "client", "stats.json"),
     "utf8",
   ),
 );
 /** @type {import("@rspack/core").StatsCompilation} */
 const legacyManifest = JSON.parse(
   await readFile(
-    path.join(BUILD_OUT_ROOT, "static", "legacy", "stats.json"),
+    path.join(FRED_BUILD_ROOT, "static", "legacy", "stats.json"),
     "utf8",
   ),
 );

package/build/ssr.js

@@ -1,8 +1,9 @@
+#!/usr/bin/env node
 import { readFile, writeFile } from "node:fs/promises";
 
 import { fdir } from "fdir";
 
-import { BUILD_OUT_ROOT } from "./env.js";
+import { RARI_BUILD_ROOT } from "./env.js";
 import { render } from "./render.js";
 
 /**
@@ -59,7 +60,7 @@ async function findDocuments() {
     .withFullPaths()
     .withErrors()
     .filter((filePath) => filePath.endsWith("/index.json"))
-    .crawl(BUILD_OUT_ROOT);
+    .crawl(RARI_BUILD_ROOT);
   const docs = await api.withPromise();
   return docs;
 }

package/components/env/README.md

@@ -0,0 +1,28 @@
+# Environment Variables
+
+If a component or other part of Fred requires a variable set from the environment, you should define it in the [`./index.js`](./index.js) file, with a safe default value.
+
+## Defaults
+
+We set safe defaults for prod, unless the risk from doing - and having this set everywhere, across local dev etc. - outweighs the risk of it not being set on prod.
+
+E.g. we don't set `GLEAN_ENABLED` to the prod default, as we don't want to send telemetry pings for prod from other environments, and we'll notice in our telemetry if it's not set in prod.
+
+## Naming
+
+Within Fred, variables are unprefixed, however the environment variable name is prefixed with `FRED_` to avoid conflicts with other environment variables. For example, if you define a variable `MY_VAR` in Fred, the environment variable to set would be `FRED_MY_VAR`.
+
+## Secrets
+
+Rspack will bundle **all** environment variables prefixed with `FRED_` into the bundle, which is exposed client side.
+
+> [!WARNING]
+> **Never set secrets** through `FRED_` environment variables.
+>
+> As secrets can only be used in server-side components, you should simply set them through a non-`FRED_`-prefixed environment variable, and access them using the `process.env` object.
+
+## Build-time vs runtime
+
+By default, variables are baked into our bundle at build time. However, you can define variables as runtime environment variables, which can be changed when running a version of Fred built with `FRED_RUNTIME_ENV=true`.
+
+This is used in our npm package, so we can e.g. set `FRED_WRITER_MODE=true` in the `content` repo, without having to bake that into the npm package for all consumers.

package/components/env/index.js

@@ -1,15 +1,16 @@
-/**
- * @file Retrieves environment variables, setting defaults, for other areas of the app.
- *
- * We set safe defaults for prod, unless the risk from doing - and having this set
- * everywhere, across local dev etc. - outweighs the risk of it not being set on prod.
- */
+import { parseBool, parseInt, parseString } from "./utils.js";
 
 export const PLAYGROUND_BASE_HOST = parseString(
   "PLAYGROUND_BASE_HOST",
   "mdnplay.dev",
 );
-export const PLAYGROUND_LOCAL = parseBool("PLAYGROUND_LOCAL", false);
+export const PLAYGROUND_LOCAL = parseBool("PLAYGROUND_LOCAL", false, {
+  runtime: true,
+});
+export const PORT = parseInt("PORT", 3000, { runtime: true });
+export const PLAYGROUND_PORT = parseInt("PLAYGROUND_PORT", 3001, {
+  runtime: true,
+});
 
 export const FXA_SIGNIN_URL = parseString(
   "FXA_SIGNIN_URL",
@@ -33,7 +34,7 @@ export const GLEAN_DEBUG = parseBool("GLEAN_DEBUG", false);
  */
 export const ROBOTS_GLOBAL_ALLOW = parseBool("ROBOTS_GLOBAL_ALLOW", true);
 
-export const WRITER_MODE = parseBool("WRITER_MODE", false);
+export const WRITER_MODE = parseBool("WRITER_MODE", false, { runtime: true });
 
 export const BCD_BASE_URL = parseString(
   "BCD_BASE_URL",
@@ -44,25 +45,3 @@ export const OBSERVATORY_API_URL = parseString(
   "OBSERVATORY_API_URL",
   "https://observatory-api.mdn.mozilla.net",
 );
-
-/**
- * @param {string} name
- * @param {boolean} fallback
- */
-function parseBool(name, fallback) {
-  try {
-    return Boolean(
-      JSON.parse(process.env[`FRED_${name}`] || JSON.stringify(fallback)),
-    );
-  } catch {
-    return fallback;
-  }
-}
-
-/**
- * @param {string} name
- * @param {string} fallback
- */
-function parseString(name, fallback) {
-  return process.env[`FRED_${name}`] || fallback;
-}

package/components/env/runtime.js

@@ -0,0 +1,6 @@
+import { parseBool } from "./utils.js";
+
+/** @type {string[]} */
+export const runtimeVariables = [];
+/** Overriden to prod default (false) in rspack config, set to true so it works in dev server by default. */
+export const RUNTIME_ENV = parseBool("RUNTIME_ENV", true);

package/components/env/types.d.ts

@@ -0,0 +1,5 @@
+declare global {
+  var __MDNEnv: Record<string, string> | undefined;
+}
+
+export {};

package/components/env/utils.js

@@ -0,0 +1,56 @@
+import { RUNTIME_ENV, runtimeVariables } from "./runtime.js";
+
+/**
+ * @typedef {object} Options
+ * @property {boolean} [runtime] Allow setting this value at runtime
+ */
+
+/**
+ * @param {string} name
+ * @param {boolean} fallback
+ * @param {Options} [options]
+ */
+export function parseBool(name, fallback, options) {
+  try {
+    return Boolean(
+      JSON.parse(getEnv(name, options) || JSON.stringify(fallback)),
+    );
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {number} fallback
+ * @param {Options} [options]
+ */
+export function parseInt(name, fallback, options) {
+  const stringValue = getEnv(name, options);
+  const numberValue = stringValue ? Number.parseInt(stringValue, 10) : fallback;
+  return Number.isNaN(numberValue) ? fallback : numberValue;
+}
+
+/**
+ * @param {string} name
+ * @param {string} fallback
+ * @param {Options} [options]
+ */
+export function parseString(name, fallback, options) {
+  return getEnv(name, options) || fallback;
+}
+
+/**
+ * @param {string} name
+ * @param {Options} [options]
+ * @returns {string | undefined}
+ */
+function getEnv(name, options = {}) {
+  const { runtime } = { runtime: false, ...options };
+  const fullName = `FRED_${name}`;
+  if (runtime && RUNTIME_ENV) {
+    runtimeVariables.push(fullName);
+    return process.env[fullName] || getEnv(name);
+  }
+  return globalThis.__MDNEnv?.[fullName];
+}

package/components/outer-layout/server.js

@@ -5,6 +5,7 @@ import { unsafeHTML } from "lit/directives/unsafe-html.js";
 
 import inlineScript from "../../entry.inline.js?source&csp=true";
 import { ROBOTS_GLOBAL_ALLOW, WRITER_MODE } from "../env/index.js";
+import { RUNTIME_ENV, runtimeVariables } from "../env/runtime.js";
 import Favicon from "../favicon/pure.js";
 import { asyncLocalStorage } from "../server/async-local-storage.js";
 import { ServerComponent } from "../server/index.js";
@@ -68,6 +69,12 @@ export class OuterLayout extends ServerComponent {
         ? "learn"
         : undefined;
 
+    const env = Object.fromEntries(
+      Object.entries(process.env).filter(([key]) =>
+        runtimeVariables.includes(key),
+      ),
+    );
+
     // if you want to put some script inline, put it in entry.inline.js
     // and you'll get CSP generation: see the README
     return html`
@@ -86,6 +93,11 @@ export class OuterLayout extends ServerComponent {
             content="width=device-width, initial-scale=1.0"
           />
           <title>${context.pageTitle || "MDN"}</title>
+          ${RUNTIME_ENV
+            ? unsafeHTML(`<script>process = {
+  env: ${JSON.stringify(env)}
+};</script>`)
+            : nothing}
           ${unsafeHTML(`<script>${inlineScript}</script>`)}
           ${styles.map(
             (path) =>

package/components/play-runner/element.js

@@ -5,7 +5,12 @@ import { keyed } from "lit/directives/keyed.js";
 import { createRef, ref } from "lit/directives/ref.js";
 
 import { ThemeController } from "../color-theme/controller.js";
-import { PLAYGROUND_BASE_HOST, PLAYGROUND_LOCAL } from "../env/index.js";
+import {
+  PLAYGROUND_BASE_HOST,
+  PLAYGROUND_LOCAL,
+  PLAYGROUND_PORT,
+  PORT,
+} from "../env/index.js";
 import { compressAndBase64Encode } from "../playground/utils.js";
 
 import styles from "./element.css?lit";
@@ -101,7 +106,7 @@ export class MDNPlayRunner extends LitElement {
       const url = new URL(
         `${prefix}/runner.html`,
         PLAYGROUND_LOCAL
-          ? location.origin.replace("3000", "3001")
+          ? location.origin.replace(PORT.toString(), PLAYGROUND_PORT.toString())
           : `${location.protocol}//${this._subdomain}.${PLAYGROUND_BASE_HOST}`,
       );
       // pass the uuid for postMessage isolation