Deploy an Astro site with Universally

Deploying needs one thing beyond your usual setup: UNIVERSALLY_API_KEY has to be set in the environment where the build runs, not only where the server runs. The integration reads the key when your Astro config runs and compiles it into the server bundle. It never reaches the client bundle.

Before you start

• The site works locally. See Install the Astro integration.
• site in astro.config.mjs is your production domain, so hreflang links point at it.
• You have the 64 character API key from API Settings. See Find your API key.

Set the key for your host

Your .env file stays out of the repository, so the build machine needs the variable from somewhere else. .env.production and other mode files are not read.

• Node: set UNIVERSALLY_API_KEY in the shell, systemd unit, or container environment that runs the build, then start the server the adapter produced.
• Cloudflare: set it as a build environment variable in the Workers or Pages build settings. Where the runtime exposes waitUntil, the integration uses it, so reports and reloads finish after the response instead of being cut off.
• Vercel: add it under the project's environment variables, for every environment you build.
• Netlify: add it under the site's environment variables, available at build time.

Never put the key in a PUBLIC_ variable, in a client component, or in committed code. It can spend your project's words.

Deploy

1. Set the variable as above.
2. Run your usual build and deploy.
3. Open a page under a target prefix, such as https://example.com/fr/about. The built Node server loads its catalog on the first localized request, so that one request is slower.

A static build prints N new strings translated. Rebuild to include them. when it finds new text. Build and deploy again to ship those translations.

Make the push endpoint reachable

For dashboard edits to show straight away, https://{your domain}/_universally/revalidate has to accept POST requests from the internet. The integration answers it before Astro routing, so you add no page or route. If the endpoint is behind a firewall or login, polling still picks the edit up within revalidateSeconds. See Translation updates in Astro.

Static sites have no push endpoint. Rebuild and redeploy to publish dashboard edits.

Several instances

Each server instance keeps its own catalog in memory. A push reaches one instance, and the rest catch up by polling. Set revalidateSeconds to a delay you accept. See Astro integration options.

After regenerating the key

Regenerate on API Settings invalidates the old key immediately. Update UNIVERSALLY_API_KEY on your host and redeploy, or the next build fails and a running server's push endpoint returns 401.

Verify it worked

• The deployed page under /fr/ shows translated text after a reload.
• The page source has one <link rel="alternate" hreflang> per language, with your production domain.
• Edit a string on the Translations screen, then reload the page. The edit appears at once if the push reached you, or within revalidateSeconds if polling picked it up.