Options d'intégration Astro

Cette page répertorie chaque option que vous pouvez passer à universally({...}) dans astro.config.mjs, la variable d'environnement qui définit chacune d'elles et le format du point d'accès push.

Options

Une clé manquante génère une erreur : "définissez UNIVERSALLY_API_KEY dans .env ou passez apiKey dans les options d'intégration. La clé est la clé de site de 64 caractères de la page de configuration de votre projet."

D'où proviennent les valeurs

Chaque valeur est résolue dans cet ordre, la première correspondance l'emporte :

1. L'option dans universally({...})
2. L'environnement du processus
3. .env.local à la racine du projet Astro, à côté de astro.config.mjs
4. .env dans le même dossier

Une valeur vide est considérée comme manquante. .env.production et d'autres fichiers de mode ne sont pas lus. La lecture des fichiers nécessite Node 20.12 ou plus récent ; sur les versions plus anciennes de Node, ils sont ignorés sans erreur. La clé est résolue au moment de la compilation et intégrée dans le bundle serveur, jamais dans le bundle client, elle doit donc être présente là où la compilation s'exécute. Voir Déployer un site Astro avec Universally.

hreflang.format

Pour une source en anglais (US) avec le français (France) sous /fr/ et l'espagnol (Mexique) sous /es/, la page /fr/about s'affiche ainsi :

<!-- 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" />

La source vient en premier, puis les cibles dans l'ordre où Universally les renvoie, puis x-default. Les chaînes de requête et les ancres sont supprimées des URL. Voir balises hreflang.

Une fonction reçoit une ligne de langue, avec des champs tels que lang, variant, region et url, et renvoie la valeur. Elle ne s'exécute que lorsque la configuration s'exécute :

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

Exemples

// 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' })

Types et exportations

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 est typé par /// <reference types="@universally-sdk/astro/env" /> dans src/env.d.ts :

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

Point de terminaison push

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

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

Une barre oblique finale sur le chemin est acceptée.