@seo-core-app-ai/seo-metadata-automation

Server-side SEO deployment middleware for Node.js. Apply title tags, meta descriptions, canonical URLs, and on-page SEO changes directly in your server response — before the HTML reaches the browser or crawler.

Part of SEO Core App — the SEO automation platform for technical audits and controlled SEO deployments.

What it does

When you publish an SEO deployment from the SEO Core App dashboard, this package applies it to your Node.js server in real time — no rebuild, no redeployment, no CMS edit required.

• Title tags — override <title> per URL without touching your codebase
• Meta descriptions — update description and Open Graph tags server-side
• Canonical URLs — set or correct canonical links across any page
• Real-time sync — changes propagate within 30 seconds via background polling, or instantly via push webhook
• Crawler-visible — changes are in the HTML before it leaves your server, fully visible to Google and other crawlers without JavaScript execution

Supported frameworks

| Framework | Integration | |-----------|-------------| | Next.js (App Router, self-hosted) | Custom server via @seo-core-app-ai/node-deploy/nextjs/server | | Next.js (App Router, managed/serverless) | withSeoDeployMetadata() in generateMetadata() | | Express | Middleware — one app.use() call | | Fastify | Plugin — one app.register() call | | Generic Node.js | HTTP handler via @seo-core-app-ai/node-deploy/http |

Quick start

1. Install

npm install @seo-core-app-ai/seo-metadata-automation

2. Set environment variables

Get your Project ID and Deploy Token from Projects → Deploy Script → Node.js in the SEO Core App dashboard.

SEO_DEPLOY_PROJECT_ID=your_project_id
SEO_DEPLOY_TOKEN=your_deploy_token

# Override the API base URL when your app should talk to SEO Core through
# an internal/private network address instead of the public site URL
SEO_DEPLOY_API_ORIGIN=https://seo.realidad-digital.com/api

# App-level toggle for self-hosted Next.js custom server setups
SEO_DEPLOY_HTML_PATCHING=1

Notes:

• SEO_DEPLOY_PROJECT_ID and SEO_DEPLOY_TOKEN are required for every integration.
• SEO_DEPLOY_API_ORIGIN should be set when your app should reach the SEO Core API directly instead of deriving it from your public site URL.
• SEO_DEPLOY_HTML_PATCHING should be set for self-hosted Next.js custom server setups where you want to explicitly control final HTML patching.
• NEXT_PUBLIC_SITE_URL is still useful for public URL resolution and webhook registration, but it is no longer presented as part of the core four-variable setup.

3. Integrate

Next.js (App Router, self-hosted / Docker / VPS)

Create server.ts:

import { SeoDeployClient } from "@seo-core-app-ai/seo-metadata-automation";
import { createNextjsServer } from "@seo-core-app-ai/seo-metadata-automation/nextjs/server";

async function main() {
  const port = parseInt(process.env.PORT ?? "3000", 10);
  const client = new SeoDeployClient({
    projectId: parseInt(process.env.SEO_DEPLOY_PROJECT_ID!, 10),
    token: process.env.SEO_DEPLOY_TOKEN!,
  });
  await client.initialize();

  const server = await createNextjsServer(client, { port });
  server.listen(port, () => {
    console.log(`> Ready on http://localhost:${port}`);
  });
}

main().catch(console.error);

Update package.json:

{
  "scripts": {
    "start": "NODE_ENV=production node server.ts"
  }
}

This path patches the final HTML response server-side, so deployed metadata wins without duplicate tags and without per-page metadata changes.

Next.js (App Router, Vercel / managed / serverless)

Create lib/seo-deploy-client.ts:

import { SeoDeployClient } from "@seo-core-app-ai/seo-metadata-automation";

declare global { var _seoDeployClient: SeoDeployClient | undefined; }

if (!global._seoDeployClient) {
  global._seoDeployClient = new SeoDeployClient({
    projectId: parseInt(process.env.SEO_DEPLOY_PROJECT_ID!, 10),
    token: process.env.SEO_DEPLOY_TOKEN!,
  });
  global._seoDeployClient.initialize().catch(console.error);
}

export const seoDeployClient = global._seoDeployClient;

Add one line to middleware.ts to forward the current pathname:

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const res = NextResponse.next();
  res.headers.set("x-seo-core-pathname", req.nextUrl.pathname);
  return res;
}

export const config = { matcher: ["/((?!_next|favicon.ico).*)"] };

Use withSeoDeployMetadata() in your root layout:

// app/layout.tsx
import type { Metadata } from "next";
import { headers } from "next/headers";
import { withSeoDeployMetadata } from "@seo-core-app-ai/seo-metadata-automation/nextjs";
import { seoDeployClient } from "@/lib/seo-deploy-client";

export async function generateMetadata(): Promise<Metadata> {
  const pathname = (await headers()).get("x-seo-core-pathname") ?? "/";
  const siteUrl = (process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000").replace(/\/$/, "");
  return withSeoDeployMetadata(seoDeployClient, `${siteUrl}${pathname}`, {
    title: { template: "%s | My Site", default: "My Site" },
    description: "Default description",
  });
}

This path uses Next.js's native metadata pipeline, so deployed title, description, canonical, and matching social metadata stay aligned without duplicate tags.

Environment variable reference

| Variable | Required | Purpose | |----------|----------|---------| | SEO_DEPLOY_PROJECT_ID | Yes | SEO Core project ID used to fetch active deployments. | | SEO_DEPLOY_TOKEN | Yes | Deploy token used to authenticate deployment fetches and push sync. | | SEO_DEPLOY_API_ORIGIN | Recommended | Override the SEO Core API base URL, especially useful in Docker/internal networking. | | SEO_DEPLOY_HTML_PATCHING | Recommended for self-hosted Next.js | App-level toggle for custom server wrappers that enable or disable final HTML patching. | | NEXT_PUBLIC_SITE_URL | Optional | Public site origin, used for full URL resolution and webhook registration when needed. |

Express

import express from "express";
import { SeoDeployClient } from "@seo-core-app-ai/seo-metadata-automation";
import { createExpressMiddleware } from "@seo-core-app-ai/seo-metadata-automation/express";

const client = new SeoDeployClient({
  projectId: parseInt(process.env.SEO_DEPLOY_PROJECT_ID!),
  token: process.env.SEO_DEPLOY_TOKEN!,
});
await client.initialize();

const app = express();
app.use(createExpressMiddleware(client));

Fastify

import Fastify from "fastify";
import { SeoDeployClient } from "@seo-core-app-ai/seo-metadata-automation";
import { seoDeployPlugin } from "@seo-core-app-ai/seo-metadata-automation/fastify";

const client = new SeoDeployClient({
  projectId: parseInt(process.env.SEO_DEPLOY_PROJECT_ID!),
  token: process.env.SEO_DEPLOY_TOKEN!,
});
await client.initialize();

const app = Fastify();
await app.register(seoDeployPlugin, { client });

Configuration options

new SeoDeployClient({
  projectId: 123,                    // Required. Your project ID.
  token: "your_token",               // Required. Keep in environment variables.
  apiOrigin: "https://...",          // Optional. Override API base URL (useful in Docker).
  pollIntervalMs: 30_000,            // Optional. Background poll interval. Default: 30s.
  heartbeatIntervalMs: 60_000,       // Optional. Cache freshness check interval. Default: 60s.
  webhookPath: "/seo-core/sync",     // Optional. Push sync webhook path.
  publicUrl: "https://your-site.com",// Optional. Auto-registers push sync webhook on startup.
  deploymentTypes: ["title", "description"], // Optional. Limit which element types apply.
  onError: (err) => console.error(err),      // Optional. Error handler.
});

How updates reach your server

The client uses two mechanisms in parallel — no configuration required:

• Polling — fetches the latest deployments every 30 seconds in the background. Works out of the box with no infrastructure requirements.
• Push sync (optional) — the dashboard notifies your server the moment a deployment is saved, delivering changes in under 3 seconds. Requires your server to be publicly reachable via HTTPS.

Either way, changes are applied to the next incoming request after the cache updates — no restart needed.

Links

• SEO Core App — SEO automation platform
• Features — what SEO Core App does
• Pricing — plans and pricing
• Node.js integration docs — full documentation

License

MIT