Astro-Integrationsoptionen

Diese Seite listet jede Option auf, die Sie an universally({...}) in astro.config.mjs übergeben können, die Umgebungsvariable, die jede Option festlegt, und das Format des Push-Endpunkts.

Optionen

Ein fehlender Schlüssel löst aus: "setze UNIVERSALLY_API_KEY in .env oder übergib apiKey in den Integrationsoptionen. Der Schlüssel ist der 64 Zeichen lange Site-Schlüssel von deiner Projekt-Setup-Seite."

Woher Werte stammen

Jeder Wert wird in dieser Reihenfolge aufgelöst, der erste Treffer gewinnt:

1. Die Option in universally({...})
2. Die Prozessumgebung
3. .env.local im Astro-Projekt-Root, neben astro.config.mjs
4. .env im selben Ordner

Ein leerer Wert zählt als fehlend. .env.production und andere Modus-Dateien werden nicht gelesen. Das Lesen der Dateien erfordert Node 20.12 oder neuer; auf älteren Node-Versionen werden sie ohne Fehler übersprungen. Der Schlüssel wird zur Build-Zeit aufgelöst und in das Server-Bundle kompiliert, niemals in das Client-Bundle, daher muss er dort vorhanden sein, wo der Build ausgeführt wird. Siehe Stelle eine Astro-Website mit Universally bereit.

hreflang.format

Für eine Quelle von Englisch (US) mit Französisch (Frankreich) unter /fr/ und Spanisch (Mexiko) unter /es/ wird die Seite /fr/about wie folgt gerendert:

<!-- format: 'variant', the default -->
<link rel="alternate" hreflang="en-us" href="https://example.com/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about" />
<link rel="alternate" hreflang="es-419" href="https://example.com/es/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/about" />

<!-- format: 'lang' -->
<link rel="alternate" hreflang="en" href="https://example.com/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about" />
<link rel="alternate" hreflang="es" href="https://example.com/es/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/about" />

Die Quelle kommt zuerst, dann die Ziele in der Reihenfolge, in der Universally sie zurückgibt, dann x-default. Query-Strings und Hashes werden aus den URLs entfernt. Siehe hreflang-Tags.

Eine Funktion empfängt eine Sprachzeile mit Feldern wie lang, variant, region und url und gibt den Wert zurück. Sie wird nur ausgeführt, wenn die Konfiguration ausgeführt wird:

universally({
  hreflang: {
    format: (language) => language.variant.toUpperCase()
  }
})

Beispiele

// Check for dashboard edits every five minutes
universally({ revalidateSeconds: 300 })

// Place the switcher script yourself
universally({ switcher: false })

// Serve through language subdomains
universally({ mode: 'proxy' })

Typen und Exporte

import universally, {
  REVALIDATE_PATH,            // '/_universally/revalidate'
  DEFAULT_REVALIDATE_SECONDS, // 60
  DEFAULT_SCRIPTS_URL         // 'https://scripts.universally.com'
} from '@universally-sdk/astro';
import type {
  HreflangOptions,
  ResolvedHreflang,
  UniversallyMode,
  UniversallyOptions,
  ResolvedUniversallyOptions
} from '@universally-sdk/astro';
import { UniversallyHead } from '@universally-sdk/astro/components';

Astro.locals wird typisiert durch /// <reference types="@universally-sdk/astro/env" /> in src/env.d.ts:

declare namespace App {
  interface Locals {
    lang?: string;
    t: (source: string) => string;
    href: (path: string) => string;
  }
}

Push-Endpunkt

POST /_universally/revalidate
X-Universally-Signature: v1=<hex>
Content-Type: application/json

{ "siteId": "site_123", "cacheEpoch": 12, "langs": ["fr"], "ts": 1750000000 }

Ein abschließender Schrägstrich im Pfad wird akzeptiert.