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

> Stop using custom_js_domain in plausible-hugo. Update your Hugo config to proxy_netlify = true for better performance and to resolve deprecation warnings. Learn more now.

- Repository: [divinerites/plausible-hugo](https://github.com/divinerites/plausible-hugo)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) at lines 11-15:

```gotemplate
{{- 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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html) (lines 10-13) and [`layouts/partials/plausible_csp.html`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml) or [`hugo.toml`](https://github.com/divinerites/plausible-hugo/blob/main/hugo.toml)) and delete the `custom_js_domain` line:

```toml

# 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:

```toml

# 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:

```toml
[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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html) (lines 37-46) rewrites the script source to use local paths rather than external domains:

```gotemplate
{{- 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:

```html
<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`](https://github.com/divinerites/plausible-hugo/blob/main//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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main//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`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) and [`plausible_csp.html`](https://github.com/divinerites/plausible-hugo/blob/main/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:

```toml
[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.