How to Handle the Deprecated `custom_js_domain` in plausible-hugo

Replace custom_js_domain with proxy_netlify = true in your Hugo configuration to eliminate deprecation warnings and leverage the more robust Netlify proxy method introduced in version 2.0.0.

The plausible-hugo module by divinerites simplifies adding Plausible Analytics to Hugo sites. Earlier versions relied on custom_js_domain to point to self-hosted Plausible instances, but this approach is now deprecated in favor of a proxy-based configuration that works across any static hosting provider.

Understanding the custom_js_domain Deprecation

custom_js_domain was originally designed to load the Plausible tracking script from a custom subdomain (e.g., stats.yourdomain.com). While functional, this method required manual DNS configuration and offered limited flexibility for modern static hosting environments.

Starting with version 2.0.0, the module maintainers deprecated this parameter to encourage the Netlify proxy method, which rewrites requests through your own domain path rather than relying on external script sources. This approach improves reliability and avoids ad-blocker interference.

Where the Deprecation Warning Originates

The warning you see in your build logs originates from layouts/partials/plausible_check.html at lines 11-15:

{{- if isset site.Params.plausible "custom_js_domain" }}
   {{- $_text := "plausible-hugo module : `custom_js_domain` %s is now deprecated. Use `proxy_netlify` instead and follow instruction for easy setup." }}
   {{- warnf $_text site.Params.plausible.custom_js_domain }}
{{- end }}

This check runs during every Hugo build, alerting you that the parameter exists in your configuration but is no longer the recommended approach.

Migrating from custom_js_domain to proxy_netlify

To handle the deprecation correctly, you must remove the old parameter and enable the proxy configuration. The module still reads custom_js_domain in layouts/partials/plausible_head.html (lines 10-13) and layouts/partials/plausible_csp.html (lines 3-5) for backward compatibility, but these branches are ignored once you activate the proxy.

Step 1: Remove the Deprecated Configuration

Locate your Hugo configuration file (typically config.toml or hugo.toml) and delete the custom_js_domain line:

# config.toml - OLD (Deprecated)

[params.plausible]
  enable = true
  domain = "example.com"
  custom_js_domain = "stats.mycustomdomain.org"   # ← Remove this line

Step 2: Enable the Netlify Proxy Method

Add proxy_netlify = true under the [params.plausible] section:

# config.toml - NEW (Recommended)

[params.plausible]
  enable = true
  domain = "example.com"
  proxy_netlify = true          # ← Recommended replacement

If you run a self-hosted Plausible instance rather than the SaaS version at plausible.io, you can combine the proxy with the selfhosted_domain parameter:

[params.plausible]
  enable = true
  domain = "example.com"
  selfhosted_domain = "plausible.mycompany.com"
  proxy_netlify = true

How the Proxy Rewrites the Script URL

When proxy_netlify is enabled, the logic in layouts/partials/plausible_head.html (lines 37-46) rewrites the script source to use local paths rather than external domains:

{{- if site.Params.plausible.proxy_netlify }}
    {{- $pio_http = "" }}
    {{- $pio_domain = "" }}
    {{- $pio_script = "script" }}
    {{- $pio_js = "/misc/js/" }}
    {{- $pio_data_api = "/misc/api/event" }}
{{- end }}

This transformation results in HTML output that loads the tracker from your own domain:

<link rel="preconnect" href="https://plausible.io">
<script defer data-domain="example.com"
        src="/misc/js/script.js"
        data-api="/misc/api/event"></script>

Because the script now loads from /misc/js/script.js on your own domain, the deprecated custom_js_domain becomes unnecessary. The proxy handles routing to Plausible's servers while presenting a first-party URL to visitors.

Summary

• custom_js_domain is deprecated in plausible-hugo version 2.0.0 and triggers a build warning via layouts/partials/plausible_check.html.
• The replacement is the proxy_netlify configuration, which rewrites script URLs to use first-party paths (/misc/js/script.js) rather than external domains.
• Migration requires removing custom_js_domain from your config and adding proxy_netlify = true under [params.plausible].
• Self-hosted instances can use selfhosted_domain combined with proxy_netlify for the same proxy benefits.

Frequently Asked Questions

What happens if I ignore the custom_js_domain deprecation warning?

Your site will continue to function as the module maintains backward compatibility in plausible_head.html and plausible_csp.html. However, you will see the warning during every Hugo build, and you miss the benefits of the proxy method, including better ad-blocker evasion and simplified configuration.

Can I use proxy_netlify if I don't host on Netlify?

Yes. Despite the name, the proxy_netlify setting works with any static hosting provider (Vercel, Cloudflare Pages, GitHub Pages, etc.). The parameter name reflects its origin, but the underlying logic simply rewrites URLs to use relative paths that work universally.

How do I migrate if I was pointing to a self-hosted Plausible instance?

Replace custom_js_domain with both selfhosted_domain and proxy_netlify in your configuration:

[params.plausible]
  enable = true
  domain = "example.com"
  selfhosted_domain = "plausible.mycompany.com"
  proxy_netlify = true

This preserves your custom server endpoint while adopting the proxy URL structure for script loading.

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