Opções de integração com Astro

Esta página lista cada opção que você pode passar para universally({...}) em astro.config.mjs, a variável de ambiente que define cada uma e o formato do endpoint de push.

Opções

Uma chave ausente gera um erro: "defina UNIVERSALLY_API_KEY em .env ou passe apiKey nas opções de integração. A chave é a chave do site de 64 caracteres da página de Configuração do seu projeto."

De onde vêm os valores

Cada valor é resolvido nesta ordem, a primeira correspondência vence:

1. A opção em universally({...})
2. O ambiente do processo
3. .env.local na raiz do projeto Astro, ao lado de astro.config.mjs
4. .env na mesma pasta

Um valor vazio conta como ausente. .env.production e outros arquivos de modo não são lidos. A leitura dos arquivos requer Node 20.12 ou mais recente; em Node mais antigo, eles são ignorados sem erro. A chave é resolvida no momento da compilação e compilada no pacote do servidor, nunca no pacote do cliente, portanto, deve estar presente onde a compilação é executada. Veja Deploy de um site Astro com Universally.

hreflang.format

Para uma origem em inglês (EUA) com francês (França) em /fr/ e espanhol (México) em /es/, a página /fr/about é renderizada:

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

A origem vem primeiro, depois os destinos na ordem em que Universally os retorna, depois x-default. Strings de consulta e hashes são removidos das URLs. Veja tags hreflang.

Uma função recebe uma linha de idioma, com campos como lang, variant, region e url, e retorna o valor. Ela é executada apenas quando a configuração é executada:

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

Exemplos

// 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 e exportações

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

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

Endpoint de push

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

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

Uma barra final no caminho é aceita.