Connect Astro to Fondoo

What Fondoo can do with it

Once the middleware is installed, Fondoo can change the following on your live pages, within about two minutes of a change:

• SEO tags: page title, description, canonical URL, robots, Open Graph, Twitter cards, hreflang and JSON-LD schema, set per path.
• Redirects: for example /old to /new with status 301. Redirects apply only to GET and HEAD requests and keep the query string.
• Fondoo features: the analytics tag, Fondoo forms, the support widget and a checkout link. You can switch each one on or off.
• Pause: turn every change off at once.

Things that need your approval when an agent asks for them:

• Disconnecting (disconnect_site_proxy).
• Large SEO changes, meaning more than 20 page paths changed in one update_site_proxy call.

Smaller updates are ordinary writes and are recorded in the audit history. Every SEO change is stored as a fix record that can be undone.

What middleware mode does not do: DNS-level proxying, request budgets, bot rate limits, and hosting Fondoo pages on your domain. Those need Fondoo's edge proxy instead (see docs/connect-your-site.md).

Before you start

• A Fondoo site. You need its site ID (a UUID). Your agent can find it.
• An Astro project that renders pages on demand. Astro middleware runs on every request only for pages rendered on demand. For prerendered pages it runs once, at build time. On-demand rendering needs an adapter and either output: 'server' or export const prerender = false on the pages that should pick up live changes (Astro on-demand rendering). A fully static Astro site will only pick up Fondoo changes when you rebuild. Use the edge proxy if you want static pages to change without a rebuild.
• Your public hostname, for example www.yourdomain.com. This is the hostname visitors use.
• A separate origin URL. This is a public HTTPS address that reaches your host directly, such as your host's own deployment URL. Fondoo records it and rejects origins that loop back to the public hostname.
• The Fondoo packages. @fondoo/astro and its dependency @fondoo/site-edge are MIT-licensed but not yet published on npm. Copy or link them into your project from the Fondoo source until a release is published.

There is no vendor cost. Astro itself is free.

Step by step: get your credentials

There is no Astro account or API key. The only "credential" is a public verification key that Fondoo gives you. Your middleware uses it to check that the settings feed really came from Fondoo. It is not a secret, but you should pin it exactly.

1. Ask your agent to register the site in middleware mode (see the next section). The response includes publicKey (a base64 Ed25519 key), feedUrl, and a setup link (connectUrl).
2. Create or open src/middleware.ts. Astro requires a named onRequest export (Astro middleware).
3. Add the Fondoo middleware:

import { defineMiddleware } from 'astro:middleware';
import { fondooMiddleware } from '@fondoo/astro';

const options = {
  endpoint: 'https://api.getfondoo.com',
  siteId: 'YOUR-SITE-UUID',
  hostname: 'www.yourdomain.com',
  publicKey: 'PUBLIC-BASE64-ED25519-KEY',
};

export const onRequest = defineMiddleware(fondooMiddleware(options));

If you already have middleware, combine the two with sequence() from astro:middleware.

4. Deploy your site as usual.

The middleware only acts on requests whose hostname matches hostname. Other hostnames, such as preview URLs, pass through untouched.

Connect it in Fondoo

In the dashboard: the Connections page does not currently have an Astro card. Use your agent or the REST API for this step.

By asking your agent. For example:

"Connect my Astro site www.yourdomain.com to Fondoo in middleware mode. The origin is https://my-site.netlify.app. Give me the verification key."

The agent can call connect_service({provider:"astro", siteId}) to get a signed setup link, valid for 15 minutes, that shows these steps. It then registers the site with:

connect_site_proxy({siteId, hostname:"www.yourdomain.com", originUrl:"https://my-site.netlify.app", mode:"middleware"})

The result has status connection_required. That is expected: it means "install the adapter now", not an error. Astro has no API key, so add_connection_key and test_connection do not apply here.

REST equivalent: POST https://api.getfondoo.com/v1/ops/connect_site_proxy with Authorization: Bearer <your Fondoo key> and the same JSON body.

To change settings later, use update_site_proxy. Its settings object replaces the whole settings object. Read get_site_proxy_status({siteId}) first, merge your change, then send the complete object.

Test that it works

1. Call get_site_proxy_status({siteId}) and check that the site is registered with mode middleware.
2. Ask your agent to set a test title for one on-demand page with update_site_proxy.
3. Wait up to two minutes, then view the page source. The <title> should show the new value.
4. If you enabled analytics, the page should load /_f/t.js from the Fondoo API.

Troubleshooting

• Nothing changes on the page. The page is probably prerendered. Make it render on demand, or rebuild. Also check that the request hostname exactly matches hostname in your options.
• Changes appear late. The feed is cached for about 60 seconds and expires within 120 seconds. CDN or page caches in front of Astro can add more delay. Cap them to the feed lifetime if changes must appear within minutes.
• The middleware seems switched off. It fails open. If the feed is unreachable, slow (over 500 ms), oversized, tampered with or expired, your normal page is served. Check publicKey, siteId and hostname for typos.
• "Hostname is already connected" or "Site already connected". Each site and hostname can be registered once. Use update_site_proxy to change an existing registration.
• "Platform hostnames are reserved". You used a Fondoo hostname. Use your own domain.
• Scripts are blocked. Your Content Security Policy must allow the Fondoo API origin, and challenges.cloudflare.com if you use forms.

Limits, data and security

• No credentials are stored for Astro. The public feed at /site-edge/SITE_ID/HOSTNAME.json contains no origin URL and no secrets.
• Use one middleware client per site and hostname. Do not share its cache across tenants.
• Pause: pause_site_proxy({siteId}) turns the changes off within the feed lifetime. Resume with update_site_proxy({siteId, paused:false}).
• Disconnect: remove the middleware from your code, then call disconnect_site_proxy({siteId}). This is destructive, so agents need your approval. No content, domain or hosting is deleted.

Official links

• Astro middleware: https://docs.astro.build/en/guides/middleware/
• Astro on-demand rendering: https://docs.astro.build/en/guides/on-demand-rendering/
• Fondoo guide (in this repository): docs/connect-your-site.md, section "Framework integration"