GoodData server collector

Captures document requests that never execute the browser tracker, including search crawlers, AI agents, SEO tools, previews, and server-side automation.

This is the JavaScript integration package for websites tracked by GoodData. It sends signed request metadata to the existing GoodData API. It is not a separate backend and is never deployed as a third service.

Install

pnpm add @gooddata-fyp/server

Next.js

// middleware.ts
import { createGoodDataNextMiddleware } from "@gooddata-fyp/server/next";

export default createGoodDataNextMiddleware({
  projectId: process.env.GOODDATA_PROJECT_ID!,
  keyId: process.env.GOODDATA_SERVER_KEY_ID!,
  secret: process.env.GOODDATA_SERVER_SECRET!,
  // Optional: await the policy decision and return 403 when blocked.
  enforcePolicy: false,
});

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

Express

import { goodDataExpress } from "@gooddata-fyp/server/express";

app.use(goodDataExpress({
  projectId: process.env.GOODDATA_PROJECT_ID!,
  keyId: process.env.GOODDATA_SERVER_KEY_ID!,
  secret: process.env.GOODDATA_SERVER_SECRET!,
}));

Framework compatibility

The package runs on the server, not in browser bundles. Client-only sites should continue using the normal GoodData tracking script.

| Framework or platform | Server collector support | Integration path | | --- | --- | --- | | Next.js | Supported | @gooddata-fyp/server/next middleware | | Express | Supported | @gooddata-fyp/server/express middleware | | React SPA | Browser tracking only | Add the GoodData browser script | | Vue SPA | Browser tracking only | Add the GoodData browser script | | Nuxt | Supported through Nitro | Call the generic collector from server middleware | | Astro SSR | Supported | Call the generic collector from Astro middleware | | Angular SPA | Browser tracking only | Add the GoodData browser script | | Angular SSR | Supported when using Express | Use the Express middleware | | SolidJS SPA | Browser tracking only | Add the GoodData browser script | | SolidStart | Supported | Call the generic collector from server middleware | | Svelte SPA | Browser tracking only | Add the GoodData browser script | | SvelteKit | Supported | Call the generic collector from a server hook | | Remix / React Router SSR | Supported | Call the generic collector from the server request handler | | Gatsby static export | Browser tracking only | Add the GoodData browser script | | Shopify hosted store | Not through this npm package | Use the browser script; deeper support requires a Shopify App | | Webflow | Browser tracking only | Add the GoodData browser script |

Generic server runtimes

Nuxt, Astro, SolidStart, SvelteKit, Remix, and other server-rendered JavaScript frameworks can call the framework-neutral collector from their request middleware or server hook:

import {
  createServerCollector,
  forwardedClientIp,
} from "@gooddata-fyp/server";

const collect = createServerCollector({
  projectId: process.env.GOODDATA_PROJECT_ID!,
  keyId: process.env.GOODDATA_SERVER_KEY_ID!,
  secret: process.env.GOODDATA_SERVER_SECRET!,
  adapterName: "custom-node",
});

await collect({
  method: request.method,
  url: request.url,
  referrer: request.headers.get("referer"),
  userAgent: request.headers.get("user-agent") || "",
  clientIp: forwardedClientIp(Object.fromEntries(request.headers.entries())),
  headers: Object.fromEntries(request.headers.entries()),
});

Run collection without awaiting it when the framework provides a background lifecycle API such as waitUntil. Otherwise, keep the configured timeout low so analytics never delays the website response.

Static hosting cannot observe requests that never reach application code. Full crawler collection on those platforms requires CDN logs, an edge worker, a reverse proxy, or a platform-specific integration.

The secret is server-only. Never expose it in browser code or a public NEXT_PUBLIC_* environment variable.