Project setup

1. Copy source into your project at a path of your choosing, e.g. ./authelia-src/.

2. Frontend (web portal): The web app lives in web/. It uses Vite with path aliases. Add the following to your tsconfig.json compilerOptions:

   {
     "paths": {
       "@root/*": ["./web/src/*"],
       "@i18n/*": ["./web/src/i18n/*"],
       "@constants/*": ["./web/src/constants/*"],
       "@utils/*": ["./web/src/utils/*"],
       "@themes/*": ["./web/src/themes/*"]
     }
   }
   

3. CSP nonce: Authelia reads a nonce from <meta property="csp-nonce" content="..."> in index.html. Ensure your HTML template injects this tag for MUI's emotion cache to work with strict CSPs.

4. Locale files: Place translation JSON files at <basePath>/locales/<lng>/<ns>.json. The base path is resolved via getBasePath() from @utils/BasePath. Set a <base> tag or configure the utility if Authelia is served under a subpath.

5. Email templates: After editing React email components under internal/templates/src/, regenerate HTML/TXT outputs by running:

   cd internal/templates/src
   npx ts-node index.tsx
   

   Output files land in internal/embed/notification/ and examples/templates/notifications/.

6. Theme env: No special environment variables are required for the frontend. The Go binary reads AUTHELIA_* environment variables documented in config.template.yml.

Public API

ThemeNameAuto / ThemeNameLight / ThemeNameDark / ThemeNameGrey / ThemeNameOled

import {
  ThemeNameAuto,
  ThemeNameLight,
  ThemeNameDark,
  ThemeNameGrey,
  ThemeNameOled,
} from "./web/src/themes/index";

// ThemeNameAuto: string = "auto"
// ThemeNameLight: string = "light"
// ThemeNameDark: string = "dark"
// ThemeNameGrey: string = "grey"
// ThemeNameOled: string = "oled"

Use these constants wherever you need to reference a valid Authelia theme name — in user preference storage, theme selectors, or MUI theme switching logic. Do not hardcode the string literals; always import these constants.

Light / Dark / Grey / Oled (MUI theme objects)

import { Light, Dark, Grey, Oled } from "./web/src/themes/index";
// Each is a MUI Theme object with an additional `custom` key:
// theme.custom.icon: CSSProperties["color"]
// theme.custom.loadingBar: CSSProperties["color"]

Pass these directly to MUI's ThemeProvider. The custom namespace is declared via module augmentation and provides app-specific color tokens for icons and loading bars beyond the standard MUI palette.

i18n initializer (default export from web/src/i18n/index.ts)

import i18n from "./web/src/i18n/index";
// i18n is a fully initialized i18next instance with:
// - HTTP backend loading from <basePath>/locales/{{lng}}/{{ns}}.json
// - Custom localStorage language detector
// - Cookie-based caching (key: "language", 1-year TTL)
// - Fallback chains per locale (e.g. "de-DE" -> "de" -> "en")
// - Default NS: "portal"

This instance is ready after module import. Use it directly with react-i18next's useTranslation hook or Trans component. Do not re-initialize it; the module runs i18n.init() on import.

Working examples

Scenario - Rendering the web portal in a custom React app

Embed Authelia's portal root into an existing React application shell, reusing its MUI cache setup with a CSP nonce.

import { StrictMode } from "react";
import createCache from "@emotion/cache";
import { CacheProvider } from "@emotion/react";
import { createRoot } from "react-dom/client";
// Adjust path to your copy of source
import App from "./authelia-src/web/src/App";
import "./authelia-src/web/src/i18n/index";

const nonce =
  document.head
    .querySelector("[property=csp-nonce][content]")
    ?.getAttribute("content") || undefined;

const muiCache = createCache({ key: "mui", nonce, prepend: true });

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <CacheProvider value={muiCache}>
      <App />
    </CacheProvider>
  </StrictMode>
);

Scenario - Switching themes using exported constants

Build a theme-switcher component that maps user preference strings to MUI theme objects using Authelia's exported constants and theme objects.

import { useMemo } from "react";
import { ThemeProvider } from "@mui/material/styles";
import {
  ThemeNameAuto,
  ThemeNameLight,
  ThemeNameDark,
  ThemeNameGrey,
  ThemeNameOled,
  Light,
  Dark,
  Grey,
  Oled,
} from "./authelia-src/web/src/themes/index";

type ThemeName =
  | typeof ThemeNameAuto
  | typeof ThemeNameLight
  | typeof ThemeNameDark
  | typeof ThemeNameGrey
  | typeof ThemeNameOled;

function resolveTheme(name: ThemeName, prefersDark: boolean) {
  switch (name) {
    case ThemeNameDark:  return Dark;
    case ThemeNameGrey:  return Grey;
    case ThemeNameOled:  return Oled;
    case ThemeNameLight: return Light;
    case ThemeNameAuto:  return prefersDark ? Dark : Light;
    default:             return Light;
  }
}

export function ThemedApp({ themeName, prefersDark }: { themeName: ThemeName; prefersDark: boolean }) {
  const theme = useMemo(() => resolveTheme(themeName, prefersDark), [themeName, prefersDark]);
  return <ThemeProvider theme={theme}><div>Content</div></ThemeProvider>;
}

Scenario - Generating email notification templates

Invoke Authelia's template renderer to rebuild HTML and plain-text notification emails after modifying the React email components.

// scripts/build-emails.ts
import { render } from "react-email";
import * as React from "react";
import * as fs from "node:fs";
import Event from "./authelia-src/internal/templates/src/emails/Event";

const props = {
  title: "{{ .Title }}",
  displayName: "{{ .DisplayName }}",
  bodyPrefix: "{{ .BodyPrefix }}",
  bodyEvent: "{{ .BodyEvent }}",
  bodySuffix: "{{ .BodySuffix }}",
  remoteIP: "{{ .RemoteIP }}",
  detailsKey: "{{ $key }}",
  detailsValue: "{{ index $.Details $key }}",
  detailsPrefix: "{{- $keys := sortAlpha (keys .Details) }}{{- range $key := $keys }}",
  detailsSuffix: "{{ end }}",
};

(async () => {
  const html = await render(React.createElement(Event, props), { pretty: false, plainText: false });
  const txt  = await render(React.createElement(Event, props), { pretty: false, plainText: true });
  fs.writeFileSync("./out/Event.html", html);
  fs.writeFileSync("./out/Event.txt",  txt);
  console.log("Email templates written to ./out/");
})();

File walkthrough

• .buildkite/ - Buildkite CI pipeline YAML and shell step scripts for lint, tests, packaging, and deployment.
• .github/ - GitHub Actions workflows (CodeQL, SLSA provenance, Scorecard), issue templates, and probot config.
• api/ - OpenAPI 3.x specification for the Authelia REST API and a rendered HTML index.
• cmd/authelia/ - Main Go binary entry point (main.go).
• cmd/authelia-gen/ - Code generation tool that produces i18n indexes, JSON schemas, CLI docs, and locale files.
• cmd/authelia-scripts/ - Build and development helper scripts invoked via go run.
• cmd/authelia-suites/ - Integration test suite runner entry point.
• docs/ - Hugo-based documentation site source.
• examples/ - Reference configurations, Docker Compose stacks, and pre-built notification templates.
• experimental/ - Unstable or preview features under active development.
• internal/ - Core Go packages: handlers, middleware, storage backends, OIDC logic, and embedded assets including email templates.
• web/ - Vite + React + MUI frontend portal with i18next localization and theme system.
• config.template.yml - Annotated reference configuration covering every Authelia option.
• entrypoint.sh - Docker image entrypoint; handles config path resolution and signal forwarding.
• healthcheck.sh - Liveness probe script for Docker HEALTHCHECK directives.
• bootstrap.sh - Developer environment setup script.

Common pitfalls and fixes

• MUI emotion cache missing nonce: If your CSP blocks inline styles, the portal breaks silently. Fix: ensure <meta property="csp-nonce" content="<NONCE>"> is present before React mounts.
• i18n locale files not found (404): loadPath is constructed from getBasePath(). If Authelia is behind a subpath proxy, set the <base href="/subpath/"> tag or patch getBasePath() to return the correct prefix.
• ThemeNameAuto not resolving correctly: auto does not self-detect prefers-color-scheme; you must pass window.matchMedia('(prefers-color-scheme: dark)').matches into your resolver manually.
• Email template Go syntax in JSX: Props like detailsPrefix contain raw Go template syntax ({{- range ... }}). These are literal strings passed as props, not executed JavaScript — do not attempt to evaluate or sanitize them.
• react-email ESM/CJS conflict: react-email's render is ESM. Run the email build script with ts-node --esm or add "type": "module" to the template package's package.json.
• Go code generation must precede frontend build: web/src/i18n/index.ts is marked Code generated by go generate. Editing it directly is overwritten. Edit cmd/authelia-gen/templates/web_i18n_index.ts.tmpl and re-run go run ./cmd/authelia-gen locales.

Vibe-coding prompt template

I have dropped the Authelia source repository into ./authelia-src/ in my project.
I also have USAGE.md from the AVCP block describing the real exports and structure.

My project is a Node.js/TypeScript application using React and MUI.

Please help me integrate Authelia step by step:

1. Read USAGE.md and ./authelia-src/web/src/themes/index.ts to understand the
   exported theme constants (ThemeNameAuto, ThemeNameLight, etc.) and MUI theme
   objects (Light, Dark, Grey, Oled).

2. Wire the Authelia web portal (./authelia-src/web/src/index.tsx) into my
   existing React root, preserving the emotion cache + CSP nonce pattern.

3. Set up the tsconfig path aliases (@root, @i18n, @constants, @utils, @themes)
   so all internal imports resolve correctly.

4. Configure i18n by ensuring locale JSON files are served at the path expected
   by ./authelia-src/web/src/i18n/index.ts.

5. Show me how to build the email notification templates using
   ./authelia-src/internal/templates/src/index.tsx and write output to ./dist/emails/.

Use only real exports visible in USAGE.md. Do not invent new APIs.
Show every import path relative to my project root.

License and credit

Authelia is licensed under the Apache License 2.0. See source/LICENSE for the full license text.

Upstream project: https://github.com/authelia/authelia
Documentation: https://www.authelia.com/

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.