Opciones de integración de Astro

Esta página enumera cada opción que puedes pasar a universally({...}) en astro.config.mjs, la variable de entorno que establece cada una y el formato del endpoint de envío.

Opciones

Una clave faltante genera: "establece UNIVERSALLY_API_KEY en .env o pasa apiKey en las opciones de integración. La clave es la clave de sitio de 64 caracteres de la página de Configuración de tu proyecto."

De dónde provienen los valores

Cada valor se resuelve en este orden, la primera coincidencia gana:

1. La opción en universally({...})
2. El entorno del proceso
3. .env.local en la raíz del proyecto Astro, junto a astro.config.mjs
4. .env en la misma carpeta

Un valor vacío se considera faltante. No se leen .env.production y otros archivos de modo. La lectura de los archivos requiere Node 20.12 o más reciente; en Node más antiguo se omiten sin error. La clave se resuelve en el momento de la compilación y se compila en el paquete del servidor, nunca en el paquete del cliente, por lo que debe estar presente donde se ejecuta la compilación. Consulta Implementa un sitio Astro con Universally.

hreflang.format

Para un origen en inglés (EE. UU.) con francés (Francia) en /fr/ y español (México) en /es/, la página /fr/about se renderiza:

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

El origen va primero, luego los destinos en el orden en que Universally los devuelve, luego x-default. Las cadenas de consulta y los hashes se eliminan de las URL. Consulta etiquetas hreflang.

Una función recibe una fila de idioma, con campos como lang, variant, region y url, y devuelve el valor. Se ejecuta solo cuando se ejecuta la configuración:

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

Ejemplos

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

Tipos y exportaciones

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á tipificado por /// <reference types="@universally-sdk/astro/env" /> en src/env.d.ts:

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

Endpoint de inserción

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

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

Se acepta una barra inclinada al final de la ruta.