@mdn/fred 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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

@@ -2,7 +2,7 @@ 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 +59,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,9 +1,4 @@
-/**
- * @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, parseString } from "./utils.js";
 
 export const PLAYGROUND_BASE_HOST = parseString(
   "PLAYGROUND_BASE_HOST",
@@ -33,7 +28,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 +39,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,45 @@
+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 {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 };
+  name = `FRED_${name}`;
+  if (runtime && RUNTIME_ENV) {
+    runtimeVariables.push(name);
+    return process.env[name] || getEnv(name);
+  }
+  return globalThis.__MDNEnv?.[name];
+}

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) =>