Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Express to Fondoo

terminalLive4 min readUpdated

This guide connects a Node.js Express site you already run to Fondoo without moving its hosting or changing its DNS. You add one Fondoo middleware line to your app. It reads a signed settings feed from Fondoo, so your AI agent can manage SEO tags, redirects and Fondoo features (analytics, forms, support chat, checkout) without further code changes.

What Fondoo can do with it

After installation, Fondoo can change the following within about two minutes:

  • Redirects, for example /old to /new with status 301 or 302.
  • SEO tags in your HTML: title, description, canonical, robots, Open Graph, Twitter cards, hreflang and JSON-LD schema, set per path.
  • Fondoo scripts: analytics, forms, the support widget and a checkout link, each switchable on or off.
  • Bypass paths, such as /api/* or /account/*, which Fondoo never touches. By default, /api/*, /wp-admin/* and /wp-login.php are bypassed. Analytics and SEO start switched on; forms, support and checkout start off.
  • Pause: turn everything off at once.

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

  • disconnect_site_proxy.
  • An update_site_proxy call that changes SEO on more than 20 paths.

SEO changes are stored as reversible fix records.

The middleware only rewrites HTML that meets all of these conditions:

  • It is a GET request with status 200.
  • It is sent in one piece with res.send() or res.end().
  • It is not already compressed.
  • It is 1 MiB or smaller.

Streamed responses, responses using res.write() or flushed headers, non-HTML responses, attachments and larger responses pass through unchanged. If the rewrite fails, your original output is sent.

Before you start

  • A Fondoo site and its site ID (a UUID).
  • An Express app that serves HTML for your public hostname.
  • Your public hostname, for example www.yourdomain.com.
  • A separate origin URL. This is a public HTTPS address that reaches your server directly, such as your host's app URL.
  • The Fondoo packages. @fondoo/express and @fondoo/site-edge are MIT-licensed but not yet published on npm. Copy or link them into your project from the Fondoo source.

There is no vendor cost.

Step by step: get your credentials

Express has no API key. Fondoo gives you a public verification key to check the signed settings feed. It is not secret, but pin it exactly.

  1. Ask your agent to register the site in middleware mode (see below) and copy publicKey from the response.
  2. Add the middleware before your routes and before compression(). Express runs middleware in the order it is loaded (Writing middleware). Fondoo needs to see the uncompressed HTML before anything sends it.
import express from 'express';
import { fondooMiddleware } from '@fondoo/express';

const app = express();
app.use(fondooMiddleware({
  endpoint: 'https://api.getfondoo.com',
  siteId: 'YOUR-SITE-UUID',
  hostname: 'www.yourdomain.com',
  publicKey: 'PUBLIC-BASE64-ED25519-KEY',
}));
// app.use(compression());  // after Fondoo
// your routes...
  1. If you compress at a reverse proxy or CDN instead of in Express, which Express recommends for busy production sites (performance best practices), nothing else is needed.
  2. Deploy as usual.

The middleware compares the request Host header with hostname. Requests for other hostnames pass straight through. If your app runs behind a proxy that rewrites Host, make sure the public hostname reaches Express.

Connect it in Fondoo

In the dashboard: the Connections page has no Express card. Use your agent or the REST API.

By asking your agent. For example:

"Connect my Express site www.yourdomain.com to Fondoo in middleware mode. The origin is https://my-app.onrender.com."

The agent can call connect_service({provider:"express", siteId}) for a signed 15-minute setup link, then:

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

The status connection_required is normal. It means "install the middleware". There is no API key, so add_connection_key and test_connection are not used.

REST: POST https://api.getfondoo.com/v1/ops/connect_site_proxy with Authorization: Bearer <your Fondoo key>.

To change settings, use update_site_proxy. Its settings object replaces the whole settings object, so read get_site_proxy_status first and send the merged result.

Test that it works

  1. get_site_proxy_status({siteId}) should show the site in middleware mode.
  2. Ask your agent to add a test redirect, for example /fondoo-test to /. After up to two minutes, curl -I https://www.yourdomain.com/fondoo-test should return status 301 or 302 with a Location header pointing to https://www.yourdomain.com/.
  3. Ask for a test title on one page, then check the page source.

Troubleshooting

  • Redirects work, but tags do not change. The response is probably compressed before Fondoo sees it. Move app.use(fondooMiddleware(...)) above compression(). Streamed templates and responses larger than 1 MiB are not rewritten.
  • Nothing happens. The Host header does not match hostname, the path is in bypass, or the feed could not be verified. The middleware fails open on a missing, slow (over 500 ms), tampered or expired feed. Check siteId, hostname and publicKey.
  • Changes are slow. The feed is cached for up to 60 seconds and expires within 120. Upstream caches add more delay.
  • Scripts blocked. Allow the Fondoo API origin, and challenges.cloudflare.com for forms, in your Content Security Policy.
  • "Site already connected". Use update_site_proxy.

Limits, data and security

  • No credentials are stored for Express. The public feed contains no origin URL or secrets.
  • Use one middleware instance per site and hostname.
  • Pause: pause_site_proxy({siteId}). Resume with update_site_proxy({siteId, paused:false}).
  • Disconnect: remove the middleware line, then call disconnect_site_proxy({siteId}). This is destructive, so agents need your approval. Your server and content are not touched.