How to Proxy Plausible Through Netlify: A Complete Guide for Hugo Sites

Proxying Plausible through Netlify requires setting proxy_netlify = true in your Hugo configuration and deploying redirect rules that rewrite local paths to Plausible's CDN endpoints with a 200 status code, effectively serving analytics scripts from your own domain to bypass ad-blockers.

When deploying a Hugo site on Netlify, the divinerites/plausible-hugo theme provides a built-in mechanism to proxy Plausible Analytics through your own domain. This technique prevents browsers and ad-blockers from blocking the plausible.io domain by serving the tracking script and event API through local paths that Netlify's edge network rewrites transparently.

Why Proxy Plausible Through Netlify?

Plausible's JavaScript and event-tracking endpoints normally load directly from https://plausible.io. Modern privacy tools and ad-blockers routinely block this domain, which completely prevents analytics data collection. By proxying Plausible through Netlify, you map local URLs (e.g., /misc/js/script.js) to Plausible's real endpoints while returning a 200 status code, making the browser treat these requests as same-origin.

Configuration Setup

Enabling the Proxy Flag

First, activate the Netlify proxy feature in your site's configuration file. This flag instructs the theme's partials to generate URLs pointing to your local proxy paths rather than the external Plausible domain.

# config.toml

[params.plausible]
enable        = true
domain        = "example.com"
proxy_netlify = true  # Activates the Netlify proxy mode

Netlify Redirect Rules

The core proxy logic resides in layouts/partials/plausible_redirects_netlify.html. This partial generates the necessary rewrite rules that map your local paths to Plausible's infrastructure:

• /misc/js/script.js proxies to the Plausible script (or the outbound-links variant if enabled)
• /misc/api/event proxies to the Plausible event collection API

Both rules use the 200 status code to mask the external redirect, ensuring the browser perceives the content as originating from your domain.

Implementation Methods

Dynamic Redirects via index.redir

The recommended approach uses Hugo's index.redir layout to generate the _redirects file dynamically during build time. Create or update layouts/_default/index.redir to include the Plausible partial:

# layouts/_default/index.redir

# Existing alias redirects (preserve these)

{{ range $p := site.Pages -}}
  {{ range .Aliases }}
    {{ . | printf "%-35s" }} {{ $p.RelPermalink }} 301!
  {{ end -}}
{{- end -}}

# Inject Plausible proxy rules

{{ partial "plausible_redirects_netlify.html" . }}

During the Hugo build, this renders to a _redirects file in your publish directory containing the three critical rewrite rules.

Static _redirects File

If you prefer not to use index.redir, create a static file at static/_redirects with the explicit rules:

# Netlify proxy for Plausible Analytics

/misc/js/script.js https://plausible.io/js/script.js 200
/misc/api/event   https://plausible.io/api/event 200

If you have enabled outbound_link = true in your configuration, use the outbound-links variant instead:

/misc/js/script.js https://plausible.io/js/script.outbound-links.js 200
/misc/api/event   https://plausible.io/api/event 200

Content Security Policy Support

When serving Plausible through a proxy, you may need to update your Content Security Policy (CSP) headers to allow the local proxy paths. The theme includes layouts/partials/plausible_csp.html to generate the necessary directives.

Add the partial to your Netlify headers configuration:

# layouts/index.headers (generates _headers file)

Content-Security-Policy: default-src 'self'; {{ partial "plausible_csp.html" . }}

This injects the correct script-src and connect-src values for /misc/js/script.js and /misc/api/event, ensuring the browser permits execution and event posting.

How the Proxy Works

Once configured, the plausible_head.html partial generates a script tag pointing to the local proxy path:

<script src="/misc/js/script.js" data-domain="example.com" defer></script>

When a visitor loads your page, Netlify's edge network intercepts the request for /misc/js/script.js and transparently rewrites it to https://plausible.io/js/script.js, returning the content with a 200 status. The browser executes the script as if it were a native site asset. Subsequent page view events sent to /misc/api/event undergo the same transparent rewriting to https://plausible.io/api/event.

Summary

• Enable the proxy by setting proxy_netlify = true in [params.plausible] within your config.toml.
• Deploy redirect rules using either the plausible_redirects_netlify.html partial in index.redir or a static static/_redirects file.
• Map three critical paths: the JavaScript script (with optional outbound-links variant) and the event API endpoint, both using the 200 rewrite status.
• Update CSP headers using plausible_csp.html if your site employs Content Security Policy headers.
• Bypass ad-blockers by serving Plausible assets from your own domain rather than the blocked plausible.io domain.

Frequently Asked Questions

What file contains the actual redirect rules for the Netlify proxy?

The redirect rules are defined in layouts/partials/plausible_redirects_netlify.html within the divinerites/plausible-hugo repository. This partial generates the specific rewrite syntax mapping /misc/js/script.js and /misc/api/event to the corresponding Plausible.io URLs with a 200 status code.

Do I need to modify the Plausible script tag in my templates when using the proxy?

No, the plausible_head.html partial automatically adjusts the script source when proxy_netlify = true is set. It generates <script src="/misc/js/script.js"> instead of pointing directly to plausible.io, requiring no manual template changes beyond including the standard partial.

Can I use the Netlify proxy if I need outbound link tracking?

Yes, the plausible_redirects_netlify.html partial detects the outbound_link configuration parameter. When enabled, it automatically proxies to https://plausible.io/js/script.outbound-links.js instead of the standard script file, maintaining full functionality while keeping the proxy benefits.

Will this proxy method work with other hosting providers besides Netlify?

No, the proxy_netlify configuration and the associated partials specifically generate Netlify redirect syntax for the _redirects file. Other hosting providers use different configuration formats (such as Vercel's vercel.json or Cloudflare Pages' _redirects with different syntax), which would require separate configuration approaches not covered by this theme's built-in Netlify support.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}