web/NPM Workspaces: ESbuild version cleanup (#14541)

* web: Check JS files. Add types.

* web: Fix issues surrounding Vite/ESBuild types.

* web: Clean up version constants. Tidy types

* web: Clean up docs, types.

* web: Clean up package paths.

* web: (ESLint) no-lonely-if

* web: Render slot before navbar.

* web: Fix line-height alignment.

* web: Truncate long headers.

* web: Clean up page header declarations. Add story. Update paths.

* web: Ignore out directory.

* web: Lint Lit.

* web: Use private alias.

* web: Fix implicit CJS mode.

* web: Update deps.

* web: await all imports.

web/packages/core/LICENSE.txt

@@ -0,0 +1,18 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Authentik Security, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

web/packages/core/README.md

@@ -0,0 +1,4 @@
+# `@goauthentik/core`
+
+This package contains utility scripts common to all TypeScript and JavaScript packages in the
+`@goauthentik` monorepo.

web/packages/core/environment/node.js

@@ -0,0 +1,66 @@
+/**
+ * @file Utility functions for working with environment variables.
+ */
+/// <reference types="../types/node.js" />
+
+//#region Constants
+
+/**
+ * The current Node.js environment, defaulting to "development" when not set.
+ *
+ * Note, this should only be used during the build process.
+ *
+ * If you need to check the environment at runtime, use `process.env.NODE_ENV` to
+ * ensure that module tree-shaking works correctly.
+ *
+ * @category Environment
+ * @runtime node
+ */
+export const NodeEnvironment = process.env.NODE_ENV || "development";
+
+/**
+ * A source environment variable, which can be a string, number, boolean, null, or undefined.
+ * @typedef {string | number | boolean | null | undefined} EnvironmentVariable
+ */
+
+/**
+ * A type helper for serializing environment variables.
+ *
+ * @category Environment
+ * @template {EnvironmentVariable} T
+ * @typedef {T extends string ? `"${T}"` : T} JSONify
+ */
+
+//#endregion
+
+//#region Utilities
+
+/**
+ * Given an object of environment variables, serializes them into a mapping of
+ * environment variable names to their respective runtime constants.
+ *
+ * This is useful for defining environment variables while bundling with ESBuild, Vite, etc.
+ *
+ * @category Environment
+ * @runtime node
+ *
+ * @template {Record<string, EnvironmentVariable>} EnvRecord
+ * @template {string} [Prefix='import.meta.env.']
+ *
+ * @param {EnvRecord} input
+ * @param {Prefix} [prefix='import.meta.env.']
+ *
+ * @returns {{[K in keyof EnvRecord as `${Prefix}${K}`]: JSONify<EnvRecord[K]>}}
+ */
+export function serializeEnvironmentVars(
+    input,
+    prefix = /** @type {Prefix} */ ("import.meta.env."),
+) {
+    const env = Object.fromEntries(
+        Object.entries(input).map(([key, value]) => [prefix + key, JSON.stringify(value ?? "")]),
+    );
+
+    return /** @type {any} */ (env);
+}
+
+//#endregion

web/packages/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * @file Dummy entry point for the `core` package.
+ *
+ * This exists to make TypeScript's module resolution more predictable.
+ *
+ * @internal
+ * @ignore
+ */
+
+export {};
+
+export default {};

web/packages/core/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@goauthentik/core",
+    "version": "1.0.0",
+    "description": "Core functionality for the authentik monorepo",
+    "license": "MIT",
+    "private": true,
+    "scripts": {
+        "build": "tsc -p .",
+        "prettier": "prettier --write .",
+        "prettier-check": "prettier --check ."
+    },
+    "main": "index.js",
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        "./*/browser": {
+            "types": "./out/*/browser.d.ts",
+            "import": "./*/browser.js"
+        },
+        "./*/node": {
+            "types": "./out/*/node.d.ts",
+            "import": "./*/node.js"
+        },
+        "./*": {
+            "types": "./out/*/index.d.ts",
+            "import": "./*/index.js"
+        },
+        ".": {
+            "import": "./index.js",
+            "types": "./out/index.d.ts"
+        }
+    },
+    "imports": {
+        "#*/browser": {
+            "types": "./out/*/browser.d.ts",
+            "import": "./*/browser.js"
+        },
+        "#*/node": {
+            "types": "./out/*/node.d.ts",
+            "import": "./*/node.js"
+        },
+        "#*": {
+            "types": "./out/*/index.d.ts",
+            "import": "./*/index.js"
+        }
+    },
+    "devDependencies": {
+        "@goauthentik/prettier-config": "^1.0.4",
+        "@goauthentik/tsconfig": "^1.0.4",
+        "@types/node": "^22.14.1",
+        "prettier": "^3.3.3",
+        "typescript": "^5.6.2"
+    },
+    "engines": {
+        "node": ">=20.11"
+    },
+    "types": "./out/index.d.ts",
+    "prettier": "@goauthentik/prettier-config"
+}

web/packages/core/paths/node.js

@@ -0,0 +1,49 @@
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const relativeDirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @typedef {'~authentik'} MonoRepoRoot
+ */
+
+/**
+ * The root of the authentik monorepo.
+ *
+ * @runtime node
+ */
+export const MonoRepoRoot = /** @type {MonoRepoRoot} */ (
+    resolve(relativeDirname, "..", "..", "..", "..")
+);
+
+/**
+ * Resolve a package name to its location in the monorepo to the single node_modules directory.
+ *
+ * @param {string} packageName
+ * @param {ImportMeta} [meta] The `import.meta` object of the module.
+ *
+ * @runtime node
+ * @returns {string} The resolved path to the package.
+ * @throws {Error} If the package cannot be resolved.
+ */
+export function resolvePackage(packageName, meta) {
+    const require = createRequire(meta ? meta.url : import.meta.url);
+
+    const relativePackageJSONPath = join(packageName, "package.json");
+
+    /** @type {string} */
+    let absolutePackageJSONPath;
+
+    try {
+        absolutePackageJSONPath = require.resolve(relativePackageJSONPath);
+    } catch (cause) {
+        const error = new Error(`🚫 Failed to resolve package "${packageName}"`);
+
+        error.cause = cause;
+
+        throw error;
+    }
+
+    return dirname(absolutePackageJSONPath);
+}

web/packages/core/scripting/node.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import * as process from "node:process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Predicate to determine if a module was run directly, i.e. not imported.
+ *
+ * @param {ImportMeta} meta The `import.meta` object of the module.
+ *
+ * @return {boolean} Whether the module was run directly.
+ * @runtime node
+ */
+export function isMain(meta) {
+    // Are we not in a module context?
+    if (!meta) return false;
+
+    const relativeScriptPath = process.argv[1];
+
+    if (!relativeScriptPath) return false;
+
+    const require = createRequire(meta.url);
+    const absoluteScriptPath = require.resolve(relativeScriptPath);
+
+    const modulePath = fileURLToPath(meta.url);
+
+    const scriptExtension = path.extname(absoluteScriptPath);
+
+    if (scriptExtension) {
+        return modulePath === absoluteScriptPath;
+    }
+
+    const moduleExtension = path.extname(modulePath);
+
+    if (moduleExtension) {
+        return absoluteScriptPath === modulePath.slice(0, -moduleExtension.length);
+    }
+
+    // If both are without extension, compare them directly.
+    return modulePath === absoluteScriptPath;
+}

web/packages/core/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "@goauthentik/tsconfig",
+    "compilerOptions": {
+        "lib": ["DOM", "DOM.Iterable", "ESNext"],
+        "resolveJsonModule": true,
+        "baseUrl": ".",
+        "checkJs": true,
+        "allowJs": true,
+        "emitDeclarationOnly": true
+    }
+}

web/packages/core/types/node.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Global variables provided by Node.js
+ */
+
+declare module "module" {
+    global {
+        /**
+         * @deprecated This is not present in ESM files.
+         *
+         * ```js
+         * import { dirname } from "node:path";
+         * import { fileURLToPath } from "node:url";
+         *
+         * const relativeDirname = dirname(fileURLToPath(import.meta.url));
+         * ```
+         */
+        // eslint-disable-next-line no-var
+        var __dirname: string;
+    }
+}
+
+declare module "process" {
+    global {
+        namespace NodeJS {
+            interface ProcessEnv {
+                /**
+                 * The port used by the Docker Compose HTTP service.
+                 */
+                COMPOSE_PORT_HTTP?: string;
+
+                /**
+                 * The port used by the Docker Compose HTTPS service.
+                 */
+                COMPOSE_PORT_HTTPS?: string;
+
+                /**
+                 * An environment variable used to determine
+                 * whether Node.js is running in production mode.
+                 *
+                 * @see {@link https://nodejs.org/en/learn/getting-started/nodejs-the-difference-between-development-and-production | The difference between development and production}
+                 * @runtime node
+                 */
+                readonly NODE_ENV?: "development" | "production";
+                /**
+                 * @todo Determine where this is used and if it is needed,
+                 * give it a better name.
+                 * @deprecated
+                 * @runtime node
+                 */
+                readonly AK_API_BASE_PATH?: string;
+            }
+        }
+    }
+}

web/packages/core/version/index.js

@@ -0,0 +1,21 @@
+/**
+ * @file Utility functions for working with semantic versions.
+ *
+ * @runtime common
+ */
+
+/**
+ * Creates a URL to the release notes for the given version.
+ *
+ * @param {string} semver
+ * @returns {URL}
+ * @runtime common
+ */
+export function createReleaseNotesURL(semver) {
+    const segments = semver.split(".");
+    const versionFamily = segments.slice(0, -1).join(".");
+
+    const release = `${versionFamily}#fixed-in-${segments.join("")}`;
+
+    return new URL(`/docs/releases/${release}`, "https://goauthentik.io");
+}

web/packages/core/version/node.js

@@ -0,0 +1,54 @@
+/**
+ * @file Utility functions for working with semantic versions.
+ *
+ * @runtime node
+ */
+import { MonoRepoRoot } from "#paths/node";
+import { execSync } from "node:child_process";
+
+import PackageJSON from "../../../../package.json" with { type: "json" };
+
+/**
+ * The current version of authentik in SemVer format.
+ *
+ * @runtime node
+ */
+export const AuthentikVersion = /**@type {`${number}.${number}.${number}`} */ (PackageJSON.version);
+
+/**
+ * Reads the last commit hash from the current git repository.
+ *
+ * @runtime node
+ */
+export function readGitBuildHash() {
+    try {
+        const commit = execSync("git rev-parse HEAD", {
+            encoding: "utf8",
+            cwd: MonoRepoRoot,
+        })
+            .toString()
+            .trim();
+
+        return commit;
+    } catch (_error) {
+        console.debug("Git commit could not be read.");
+    }
+
+    return process.env.GIT_BUILD_HASH || "";
+}
+
+/**
+ * Reads the build identifier for the current environment.
+ *
+ * This must match the behavior defined in authentik's server-side `get_full_version` function.
+ *
+ * @runtime node
+ * @see {@link "authentik\_\_init\_\_.py"}
+ */
+export function readBuildIdentifier() {
+    const { GIT_BUILD_HASH } = process.env;
+
+    if (!GIT_BUILD_HASH) return AuthentikVersion;
+
+    return [AuthentikVersion, GIT_BUILD_HASH].join("+");
+}