Skip to content

Add Scarf analytics for documentation page view tracking #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
azaddhirajkumar merged 1 commit into from
Mar 9, 2026
Merged

Add Scarf analytics for documentation page view tracking #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ const config = {
onBrokenLinks: 'warn',
onBrokenMarkdownLinks: 'warn',

clientModules: [
'./src/clientModules/scarfAnalytics.js',
],

// Even if you don't use internationalization, you can use this field to set
// useful metadata like html lang. For example, if your site is Chinese, you
// may want to replace "en" with "zh-Hans".
Expand Down
24 changes: 24 additions & 0 deletions src/clientModules/scarfAnalytics.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
// Scarf pixel – SPA-aware tracking for the Docusaurus documentation site.
// This client module fires on the initial page load and on every subsequent
// in-app navigation so that each page view is recorded, even in a SPA where
// the full page is never reloaded.

const PIXEL_ID = '5ff443aa-dd19-43ab-9c9e-ad26252d0fb0';
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Hardcoding the PIXEL_ID can make it difficult to manage for different environments (e.g., development, staging, production) or if it needs to be updated. It's better to use an environment variable. Docusaurus supports this by prefixing environment variables with DOCUSAURUS_. You will need to set DOCUSAURUS_SCARF_PIXEL_ID in your build environment.

Suggested change
const PIXEL_ID = '5ff443aa-dd19-43ab-9c9e-ad26252d0fb0';
const PIXEL_ID = process.env.DOCUSAURUS_SCARF_PIXEL_ID;

Copy link
Copy Markdown
Contributor Author

@azaddhirajkumar azaddhirajkumar Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pixel ID is not a secret — it's sent to the browser as a visible query parameter on every page view. There's also only one environment (production). Hardcoding keeps it simple and avoids a silent failure if the env var is missing.


let lastHref = null;

function sendScarfPing() {
const currentHref = window.location.href;
if (currentHref === lastHref) return; // dedup: skip if same page
lastHref = currentHref;

const img = new Image();
img.referrerPolicy = 'no-referrer-when-downgrade';
img.src = `https://static.scarf.sh/a.png?x-pxid=${PIXEL_ID}`;
}

// Docusaurus client-module lifecycle hook – called after every route update
// (initial load + every SPA navigation).
export function onRouteDidUpdate() {
sendScarfPing();
}
Comment on lines +22 to +24
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

It's good practice to only enable analytics in the production environment to avoid sending tracking events during local development. You should also check if the PIXEL_ID is configured before attempting to send a ping. This can be done by checking process.env.NODE_ENV and the PIXEL_ID variable (which should be loaded from an environment variable as per my other comment).

Suggested change
export function onRouteDidUpdate() {
sendScarfPing();
}
export function onRouteDidUpdate() {
if (process.env.NODE_ENV === 'production' && PIXEL_ID) {
sendScarfPing();
}
}

Copy link
Copy Markdown
Contributor Author

@azaddhirajkumar azaddhirajkumar Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

onRouteDidUpdate only runs client-side, so this would only affect local dev. The few localhost pings during development are negligible noise compared to real traffic. Keeping it simple for now — happy to add a NODE_ENV check if the team prefers it.