Environment-Variablen

Nuxt-Themes laden ihre Runtime-Konfiguration aus einer .env-Datei im Theme-Root (_theme/{theme}/.env). Diese Seite listet alle Variablen, die das CMS auswertet — von API-Endpoint ueber Theme-Auswahl bis zu projektspezifischen PurgeCSS-Safelist-Erweiterungen.

Komplette .env am Beispiel

# _theme/vue-base/.env

# API & Site
NUXT_API_KEY=123456
NUXT_PUBLIC_API_BASE=http://newmeta.local/api
NUXT_PUBLIC_SITE_URL=http://newmeta.local
NUXT_PUBLIC_THEME=vue-base

# Optional: projektspezifische PurgeCSS-Safelist
NUXT_PURGECSS_SAFELIST_STANDARD=project-,custom-
NUXT_PURGECSS_SAFELIST_GREEDY=highlight-
NUXT_PURGECSS_SAFELIST_DEEP=cms-

Jede Variable ist unten einzeln erklaert.

API- und Site-Variablen

Variable	Sichtbarkeit	Pflicht	Zweck
NUXT_API_KEY	server-only	ja	Interner Key fuer Server-zu-Server-Calls aus Nuxt (z. B. SSR-Fetches an /api/*)
NUXT_PUBLIC_API_BASE	public	ja	Basis-URL der REST-API. Client- und Server-seitig sichtbar
NUXT_PUBLIC_SITE_URL	public	ja	Kanonische Site-URL fuer Open Graph, Sitemap, Schema.org
NUXT_PUBLIC_THEME	public	ja	Aktiver Theme-Name — steuert Theme-spezifische Asset-Aufloesungen

NUXT_API_KEY niemals PUBLIC machen

NUXT_API_KEY darf nicht mit NUXT_PUBLIC_ prefixed werden. Nuxt's Runtime-Config behandelt PUBLIC_*-Variablen als client-exposed — jeder Browser-Besucher koennte den Key auslesen. Der Key lebt korrekt unter runtimeConfig.apiKey (nicht unter runtimeConfig.public).

Wie Nuxt diese liest

nuxt.config.ts bindet sie im runtimeConfig ein:

runtimeConfig: {
    apiKey: process.env.NUXT_API_KEY,
    public: {
        apiBase: process.env.NUXT_PUBLIC_API_BASE,
        siteUrl: process.env.NUXT_PUBLIC_SITE_URL || '',
        theme:   process.env.NUXT_PUBLIC_THEME   || 'vue-base',
    }
}

Zugriff im Code:

const config = useRuntimeConfig()
const apiKey = config.apiKey              // nur server-seitig
const apiBase = config.public.apiBase     // client + server

Theme-Auswahl: NUXT_PUBLIC_THEME

NUXT_PUBLIC_THEME=vue-base        # oder projekt01, kunden-theme-name

Der Wert wird intern fuer projekt-spezifische Asset-Aufloesungen genutzt, z. B.:

• Admin-CSS: der compiled_css-Endpoint fuer Menu-Editor-Styles liest _theme/{theme}/public/css/menu.less
• Custom-Overrides: der vueRegistry-Rebuild bevorzugt _theme/{theme}/app/custom/{plugin}/widgets/.../template/index.vue vor der Plugin-Original-Datei

Fuer Dev/Build ist jedes Theme ein eigenstaendiges Nuxt-Projekt mit eigenem npm install — der NUXT_PUBLIC_THEME-Wert sollte mit dem Ordnernamen uebereinstimmen.

Projektspezifische PurgeCSS-Safelist

PurgeCSS entfernt im Production-Build alle CSS-Regeln, deren Klassen nicht im HTML/Template vorkommen. Dynamisch generierte Klassen (z. B. row_42, col_108, widget_217 aus dem Pagebuilder) haben im Theme ohnehin Default-Safelist-Eintraege. Projektspezifische Klassen koennen ohne Fork von nuxt.config.ts ergaenzt werden:

NUXT_PURGECSS_SAFELIST_STANDARD=ma-,project-,custom-
NUXT_PURGECSS_SAFELIST_GREEDY=highlight-
NUXT_PURGECSS_SAFELIST_DEEP=cms-

Jede Variable akzeptiert eine kommagetrennte Liste von Prefixen. Die nuxt.config.ts wandelt jeden Prefix zu einer ^prefix-RegExp und merged sie in den entsprechenden Bucket:

// nuxt.config.ts (Ausschnitt)
function extraSafelistFromEnv(envKey: string): RegExp[] {
    return (process.env[envKey] || '')
        .split(',')
        .map(s => s.trim())
        .filter(Boolean)
        .map(prefix => new RegExp('^' + prefix))
}

const projectExtraStandard = extraSafelistFromEnv('NUXT_PURGECSS_SAFELIST_STANDARD')
const projectExtraGreedy   = extraSafelistFromEnv('NUXT_PURGECSS_SAFELIST_GREEDY')
const projectExtraDeep     = extraSafelistFromEnv('NUXT_PURGECSS_SAFELIST_DEEP')

Die drei Buckets

PurgeCSS kennt drei Safelist-Typen mit unterschiedlichem Verhalten:

Bucket	ENV-Var	Verhalten	Wann nutzen
standard	NUXT_PURGECSS_SAFELIST_STANDARD	Exakter Klassennamen-Match (inkl. Prefix)	Einzelne Klassen: ma-button, project-card
greedy	NUXT_PURGECSS_SAFELIST_GREEDY	Match innerhalb zusammengesetzter Selektoren	Kombi-Klassen: .widget_217 .is-active, row_42 col-6
deep	NUXT_PURGECSS_SAFELIST_DEEP	Kind-Selektoren bleiben erhalten	Descendant: .cms-block > *, .cms-container .inner

Die internen Defaults legen z. B. ^row_/, ^col_/, ^widget_/ (Pagebuilder-Wrappers) in greedy ab, weil sie in Kombinationen auftreten. Details: Widgets › Custom-CSS-Konvention.

Entscheidungs-Hilfe

Klasse	Bucket
.ma-button (einzeln verwendet)	standard
.project-theme-dark (Toggle-Klasse auf body)	standard
.widget_217 .is-active (Wrapper-Kombi)	greedy
.highlight-red (mit :hover, [active]-Varianten)	greedy
.cms-block > * (Universal-Child-Styling)	deep
.cms-container .inner (feste Descendant-Kette)	deep

Beispiel-Szenario

Projekt legt eine eigene CSS-Datei project-styles.css an mit:

.ma-header { ... }
.ma-footer { ... }
.highlight-red { color: red; }
.highlight-red:hover { color: darkred; }
.cms-block > h2 { margin: 0; }

Passende .env-Eintraege:

NUXT_PURGECSS_SAFELIST_STANDARD=ma-
NUXT_PURGECSS_SAFELIST_GREEDY=highlight-
NUXT_PURGECSS_SAFELIST_DEEP=cms-

Ohne Safelist-Eintraege wuerden diese Klassen im Production-Build entfernt — Styles erscheinen in Dev, aber nicht in Prod. Typischer schwer-zu-debuggender Build-Fehler.

Nicht-Nuxt-Variablen

Das CMS-Backend (PHP) liest seine Konfiguration aus config.php und config.local.php, nicht aus der Theme-.env. Details: Konfiguration.

Einige Ueberschneidungen im Task Manager / Update Manager:

Thema	Wo konfiguriert?
DB-Credentials	config.local.php (PHP)
Update-Server	config.local.php (PHP)
CORS-Whitelist	Admin-UI /admin/api-keys → DB-Tabelle
2FA	Admin-UI pro User
Design-Tokens	Admin-UI /admin/design → DB-Spalte website.custom_less

Die Nuxt-.env ist nur fuer das Theme selbst relevant.

Haeufige Fehler

.env in _public/ oder Projekt-Root

Nuxt laedt .env ausschliesslich aus dem Theme-Root (_theme/{theme}/.env), nicht aus dem Projekt-Root. Wer die Datei im falschen Ordner ablegt, bekommt undefined fuer alle Env-Variablen.

NUXT_PUBLIC_API_BASE ohne Trailing-/api

Der Wert muss inklusive /api-Pfad sein: http://newmeta.local/api, nicht http://newmeta.local. Client-Code, der URLs wie ${apiBase}/pages zusammenbaut, bekommt sonst http://newmeta.local/pages — klassischer 404.

.env nach Aenderung nicht neu geladen

Nuxt laedt .env beim Server-Start — Aenderungen brauchen einen Dev-Server-Restart (Ctrl+C + npm run dev neu). Production-Builds brauchen einen neuen npm run build.

Safelist-Prefix mit Dash (ma-) vs. ohne (ma)

NUXT_PURGECSS_SAFELIST_STANDARD=ma matcht auch .mango, .maze, .mail. Wer nur Klassen mit Prefix ma- schuetzen will, muss den Bindestrich explizit mitgeben: ma-. Regex ist ^ma- — stringent.

Leerer ENV-Wert ueberschreibt Default

NUXT_PUBLIC_THEME= (leer) gibt in Nuxt einen leeren String, nicht den Fallback. Im nuxt.config.ts steht || 'vue-base' — der Fallback greift nur wenn die Variable komplett undefined ist, nicht bei leerem String. Entweder Zeile komplett weglassen oder einen validen Wert setzen.

Siehe auch

• Theme-Struktur — wo die .env im Theme-Ordner liegt
• Design-Tokens — website.custom_less via /admin/design
• Nuxt-Aliases — #extensions, #widgets/plugin-registry
• Deployment — Production-Build, Env-Vars fuer Production
• Getting Started › Konfiguration — Basis-Setup der .env
• Widgets › Custom-CSS-Konvention — PurgeCSS-Bucket-Details fuer Pagebuilder-Wrappers