Heatmaps and Session Replay for Astro, Hugo, Eleventy, and Other Static Sites

Short answer: add the script tag to the shared layout or base template, in the head, so it appears on every generated page. Do not add it to a single page file. With Astro's view transitions or any client-side page swapping, navigation still updates the URL and is recorded as page views. Static sites are usually content sites, so scroll depth and next-page clicks are the things to look at first.

Table of Contents

1. The Rule for Every Generator
2. Where to Put It
3. Astro Notes
4. Hosting Notes
5. What to Analyse on a Static Site
6. Key Takeaways

The Rule for Every Generator

The snippet is the same for any website (install on any website):

<script async src="YOUR_LOADER_URL"></script>

It must be on every page. On a static site generator, that means the shared layout, not an individual page. A tag in your homepage file tracks the homepage and nothing else.

Where to Put It

Exact paths depend on your theme. Find the template that outputs the <head> for all pages and add the tag there.

Exclude non-production builds. Wrap the tag in a condition on the build environment so local previews and staging do not send data. Most generators expose an environment variable for this (excluding internal traffic).

After deploying, view the source of two different pages and confirm the tag is in both.

Astro Notes

Islands. Astro ships static HTML and hydrates only the interactive components. The recorder does not care. It captures the DOM as rendered, whichever parts are interactive.

View transitions. With Astro's client-side router enabled, navigating between pages swaps the document without a full reload. The URL changes through the History API, which the SDK patches, so each navigation is a page view. The script in your layout stays loaded across transitions. Check a recording after enabling transitions to confirm pages appear separately in the timeline.

Scripts and bundling. Astro processes script tags by default. For an external third-party script, mark it so Astro leaves it alone and outputs it as written, as described in Astro's documentation for inline and external scripts.

Content collections. Each entry gets its own URL. Group them when analysing a template.

Hosting Notes

Static hosting adds a few things worth checking.

• Trailing slashes. Generators often write each page as a folder with an index file, and hosts may redirect one URL form to the other. Make sure your canonical tags and sitemap use the form that is actually served (the trailing-slash bug).
• Caching. After adding the tag, purge the CDN cache so cached pages include it.
• Content Security Policy. If your host sets one through headers, allow the ingest origin in script-src and connect-src (CSP guide).
• Preview deployments. Preview URLs should not carry the production tag.
• Consent. DeepSync defaults to consent-required mode. Wire your banner to the consent call or nothing will be recorded (consent setup).

What to Analyse on a Static Site

Static sites are mostly documentation, blogs, and marketing pages.

For documentation specifically:

• Copy button usage on code blocks tells you which examples are used.
• Search usage inside the docs shows what navigation fails to surface.
• Back-and-forth between two pages suggests information is split awkwardly.
• Exit after a long scroll may be success: the reader found the answer.

Track meaningful actions as events:

deepsync("track", "code_copied", { page: "quickstart" });

Static sites are fast by nature. Check that third-party embeds and large images have not undone that, using real-user load times on mobile.

Key Takeaways

• Put the tag in the shared layout, never a single page.
• Keep it out of local and preview builds.
• Check trailing-slash behaviour and purge the cache after deploying.
• On content sites, start with scroll depth and next clicks.

Conclusion

Static sites are simple to instrument: one line in one template. The interesting part is what you learn about how people read.

Start free · Install on any website