Skip to content

Report page requests for server-side collection with trackRequest - #35

Open
simpleanalytics-agent wants to merge 7 commits into
mainfrom
feat/server-side-collection
Open

simpleanalytics-agent wants to merge 7 commits into
mainfrom
feat/server-side-collection

Conversation

@simpleanalytics-agent

@simpleanalytics-agent simpleanalytics-agent commented Nov 18, 2026 •

Copy link
Copy Markdown

Summary

Closes #34

Part of the server-side collection design in simpleanalytics/ide-config#22 (§11). AI agents and most robots do not run the script. Next.js websites can now report page requests from proxy.ts (middleware.ts before Next.js 16) with a new trackRequest from @simpleanalytics/next/server. It is separate from trackPageview, and the package goes to 1.2.0.

  • Off by default. SIMPLE_ANALYTICS_SERVER_SIDE_COLLECTION=1 turns it on, or serverSideCollection per call. Both names become permanent once 1.2.0 is on npm.
  • Payload. It sends the flat v1 payload of the design to https://queue.simpleanalyticscdn.com/requests. The copied request headers go in the body; X-Forwarded-For and platform headers such as CF-Connecting-IP and True-Client-IP go on the request. There is no status or content type, because proxy code runs before the response.
  • Never in the way. It skips non-GET requests, assets by path, /_next/ and Pages Router data requests. It never sends cookies or authorization headers, gives up after 2 seconds, never retries and swallows errors.
  • Test mode. SIMPLE_ANALYTICS_TEST_MODE=1 (or testMode) adds test: true and prints the payload and the queue's reply on the server console.
  • README and a docs page (/docs/server-side-collection), labelled beta. Both start with a prompt for an AI agent that points at the guide for coding agents, then manual setup.

Tickets in this branch:

Merge last. Every push to main publishes to npm. Merge only once the queue's /requests route (simpleanalytics/queue#116) and the Traefik change (simpleanalytics/infrastructure#367) are live.

Accepted gaps: App Router client navigations and prefetches reach proxy.ts without any marker, so they are reported as page requests (the queue discards people). Next gives proxy code no socket address, so X-Forwarded-For is passed on exactly as Next hands it over.

Security implications

  • No security impact
  • Has security impact - described as: visitor addresses and request headers are sent to the queue. Cookies and authorization headers are never sent, query parameters outside an allowed list never leave the server, and addresses are printed only in test mode.

Testing

  • pnpm test: 13 node --test cases for payload building, on Node 22.11, 24.13 and 24.22. Type check, pnpm build:package, the docs build and Prettier pass.
  • End to end on Next 15.2.3 (Edge middleware.ts) and Next 16.4.6 (Node proxy.ts) against a local stand-in for the queue: blocked parameters dropped, cookies and authorization never sent, 404s reported, assets and POST skipped. The page answered in about 25 ms with the queue delayed 5 seconds or down.
  • An independent review repeated these probes and found nothing to fix.

Summary by CodeRabbit

  • New Features
    • Added beta server-side request collection for Next.js, with setup guidance for current and earlier Next.js versions.
    • Requests can be classified in reports without tracking visits from people; AI-agent requests appear in reports, while robot requests are hidden by default and excluded from usage.
    • Collection is disabled by default and can be enabled for production. Test mode provides diagnostic output without storing data.
  • Documentation
    • Added setup instructions, configuration details, and guidance on which requests are included or excluded.

trackRequest runs in proxy.ts (middleware.ts before Next.js 16) and sends
each GET page request to the queue's /requests route in the version 1
payload, so the queue can count AI agents and robots that never run the
script. Assets are skipped by path; copied request headers travel in the
body and address headers pass on under their own names. Cookies and
authorization headers are never sent.

It stays off until SIMPLE_ANALYTICS_SERVER_SIDE_COLLECTION (or the
serverSideCollection option) is on, gives up after 2 seconds, never
retries and never throws. Test mode (SIMPLE_ANALYTICS_TEST_MODE or
testMode) sends test: true and prints the queue's reply on the server
console.

Adds node --test coverage for the payload and bumps the package to 1.2.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Node.js 22 before 22.18 strips TypeScript types only with a flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The package adds trackRequest for opt-in server-side request reporting in Next.js. It builds filtered reports, sends eligible reports to a queue, and documents configuration, request handling, and test mode.

Changes: Next.js Server-Side Collection

Layer / File(s) Summary
Request payload construction
packages/analytics/src/server/request-payload.ts, packages/analytics/src/server/simple-analytics.ts, packages/analytics/test/*, packages/analytics/package.json, package.json
The report builder filters methods, paths, query parameters, and headers. Tests cover these rules. The package and root test scripts run the tests. Pageview tracking now imports the shared proxy-path matcher.
Request reporting API
packages/analytics/src/server/track-request.ts, packages/analytics/src/server/index.ts, packages/analytics/package.json
trackRequest applies configuration and environment checks, builds a report, and sends one request with a 2-second timeout. It suppresses failures and logs report details in test mode. The server entry point exports the API, and the package version changes to 1.2.0.
Next.js setup documentation
apps/docs/content/docs/meta.json, apps/docs/content/docs/server-side-collection.mdx, packages/analytics/README.md
The docs add a server-side collection guide and list it after events. The guide and README describe setup, request behavior, and test mode.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant NextProxy
  participant trackRequest
  participant buildRequestReport
  participant Queue
  NextProxy->>trackRequest: Pass request and options
  trackRequest->>buildRequestReport: Build eligible report
  buildRequestReport-->>trackRequest: Return report or undefined
  trackRequest->>Queue: POST report
Loading

Suggested reviewers: jeanmeijer

Merge Risk: Minimal · up to 06651

This adds an opt-in trackRequest that is off by default, skips ineligible requests, and never throws or blocks the response. No concrete defects were found in the changed code. Before merging, confirm that the queue's /requests route is live and that it honors test mode as the documentation promises.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: page requests are reported for server-side collection through the trackRequest API. The changeset adds trackRequest, the request payload builder, the proxy/middleware …
Linked Issues check Passed Issue #34 coding requirements, checked against the whole-PR diff summary and head source of packages/analytics/src/server/request-payload.ts and package.json:

1. Separate API: track-request.ts adds `…
Out of Scope Changes check Passed All changed files relate to issue #34 or to the PR's stated delivery work:
- track-request.ts, request-payload.ts, server/index.ts: the new trackRequest API.
- simple-analytics.ts: replaces the local …
Full details: Title check

Explanation

The title names the main change: page requests are reported for server-side collection through the trackRequest API. The changeset adds trackRequest, the request payload builder, the proxy/middleware reporting path, and the docs that describe them. The title is specific and matches the primary objective in PR #35 and issue #34.

Full details: Linked Issues check

Explanation

Issue #34 coding requirements, checked against the whole-PR diff summary and head source of packages/analytics/src/server/request-payload.ts and package.json:

  1. Separate API: track-request.ts adds trackRequest, exported from src/server/index.ts. It does not alter trackPageview.
  2. Opt-in, off by default: trackRequest returns without reporting unless serverSideCollection or SIMPLE_ANALYTICS_SERVER_SIDE_COLLECTION is set to 1 or true. The setting name is the one in the PR description.
  3. Payload and headers: buildRequestReport builds a version 1 nextjs payload with hostname, path and filtered query. It copies the agreed request headers into the body and sends X-Forwarded-For, CF-Connecting-IP and True-Client-IP as request headers. It sends no status or content type. Non-GET requests, asset extensions, /_next/ paths, PROXY_PATHS and x-nextjs-data requests are skipped. Requests to pages that return 404 are not filtered, so 404s are reported.
  4. Non-blocking behaviour: the summary states one POST with a 2-second timeout, no retries, errors swallowed, and the response body cancelled outside test mode. Cookies and Authorization are not in COPIED_HEADERS or ADDRESS_HEADERS, so they are never sent.

Test coverage: packages/analytics/test/request-payload.test.mjs covers the payload builder, including skipped paths, query filtering and headers.

Not verified: the Notes item about the src/middleware/index.ts build entry. The head file list shows no src/middleware directory. The tsup configuration was not inspected, so that build-entry note is unverified. It is a note, not a coding requirement in the What list. The timeout and error handling in track-request.ts were assessed from the summary, not from a full source read.

Full details: Out of Scope Changes check

Explanation

All changed files relate to issue #34 or to the PR's stated delivery work:

  • track-request.ts, request-payload.ts, server/index.ts: the new trackRequest API.
  • simple-analytics.ts: replaces the local proxy-path regex with the shared PROXY_PATHS constant. This supports the new payload builder and keeps trackPageview behaviour the same.
  • Tests (request-payload.test.mjs) and the test scripts in package.json files: supporting tests for the new code.
  • package.json version 1.2.0: the release step the PR states.
  • README and docs page (server-side-collection.mdx, meta.json): documentation for the new public API, which the PR describes.

No unrelated change was found in the summaries.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: QUIET
  • Plan: Team
  • Run ID: ff34f49f-8ccf-4320-8ba0-eeea52b214ef
Commits

Reviewing files that changed from the base of the PR and between b1ec6c6 and 06651e0.

Files selected for processing: 10

  • apps/docs/content/docs/meta.json
  • apps/docs/content/docs/server-side-collection.mdx
  • package.json
  • packages/analytics/README.md
  • packages/analytics/package.json
  • packages/analytics/src/server/index.ts
  • packages/analytics/src/server/request-payload.ts
  • packages/analytics/src/server/simple-analytics.ts
  • packages/analytics/src/server/track-request.ts
  • packages/analytics/test/request-payload.test.mjs

Included review availability: This review used your included allowance. 5 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 6 reviews per hour.

@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/simpleanalytics/next/@simpleanalytics/next@35

commit: 06651e0

Each options shape has one consumer, and the package exports functions,
not options types, like trackPageview and trackEvent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README and the documentation page start with a prompt that points the
coding agent at the server-side collection guide, then manual setup. The
README keeps a short quickstart and links the documentation page for what
it reports, the options and test mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@simpleanalytics-agent
simpleanalytics-agent marked this pull request as ready for review November 18, 2026 19:54

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Next.js websites cannot report page requests for server-side collection

1 participant