Astro integration options

This page lists every option you can pass to universally({...}) in astro.config.mjs, the environment variable that sets each one, and the format of the push endpoint.

Options

A missing key throws: "set UNIVERSALLY_API_KEY in .env or pass apiKey in the integration options. The key is the 64 character site key from your project Setup page."

Where values come from

Each value is resolved in this order, first match wins:

1. The option in universally({...})
2. The process environment
3. .env.local in the Astro project root, next to astro.config.mjs
4. .env in the same folder

An empty value counts as missing. .env.production and other mode files are not read. Reading the files needs Node 20.12 or newer; on older Node they are skipped without an error. The key is resolved at build time and compiled into the server bundle, never the client bundle, so it has to be present where the build runs. See Deploy an Astro site with Universally.

hreflang.format

For a source of English (US) with French (France) under /fr/ and Spanish (Mexico) under /es/, the page /fr/about renders:

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

The source comes first, then targets in the order Universally returns them, then x-default. Query strings and hashes are dropped from the URLs. See hreflang tags.

A function receives one language row, with fields such as lang, variant, region, and url, and returns the value. It runs only when the config runs:

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

Examples

// 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 and exports

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 is typed by /// <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 endpoint

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

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

A trailing slash on the path is accepted.