Skip to main content

Hexo

Integrate Swetrix with your Hexo site to track page views, monitor errors, and capture custom events — all while staying privacy-friendly and GDPR-compliant.

Hexo is a fast, simple Node.js-powered static site generator. Since it produces plain HTML pages with no client-side routing, Swetrix tracks each page view automatically on every navigation.

Installation​

The recommended approach is to create a partial in your Hexo theme for the Swetrix tracking script and include it in your site's base layout.

1. Create a partial​

In your active theme's directory, create the file themes/<your-theme>/layout/_partial/swetrix-analytics.ejs with the following content:

<script src="https://swetrix.org/swetrix.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    swetrix.init('<%= theme.swetrix_project_id || "YOUR_PROJECT_ID" %>')
    swetrix.trackViews()
  })
</script>

<noscript>
  <img
    src="https://api.swetrix.com/log/noscript?pid=<%= theme.swetrix_project_id || 'YOUR_PROJECT_ID' %>"
    alt=""
    referrerpolicy="no-referrer-when-downgrade"
  />
</noscript>
caution

Replace YOUR_PROJECT_ID with your actual Project ID from the Swetrix dashboard, otherwise tracking won't work.

2. Include it in your layout​

Open your theme's main layout file — typically themes/<your-theme>/layout/layout.ejs. Add the partial just before the closing </body> tag:

    <%- partial('_partial/swetrix-analytics') %>
  </body>
</html>

If your theme uses a different template engine like Pug or Swig, the include syntax will differ:

Pug (layout.pug):

  include _partial/swetrix-analytics
  body

Swig / Nunjucks (layout.swig):

    {% include '_partial/swetrix-analytics.swig' %}
  </body>
</html>

3. Build and deploy​

Generate your site for production:

hexo generate

Or with the shorthand:

hexo g

The generated output in the public/ directory will include the tracking script on every page.

Using config variables (optional)​

To keep your Project ID out of the template and make it easy to manage, store it in your theme's _config.yml.

1. Add to your theme config (themes/<your-theme>/_config.yml):

swetrix_project_id: "YOUR_PROJECT_ID"

Alternatively, if you're using Hexo 5+ with theme configuration in the root _config.yml:

theme_config:
  swetrix_project_id: "YOUR_PROJECT_ID"

2. Update the partial to read from config:

The partial shown in step 1 already uses theme.swetrix_project_id as the primary value. If the config variable is set, it will be used automatically — no changes needed.

Disable tracking in development​

By default, Swetrix ignores traffic from localhost, so page views during hexo server won't be sent. If you want to avoid loading the script entirely during development, you can wrap the partial in a conditional.

EJS:

<% if (config.env === 'production' || !config.env) { %>
<script src="https://swetrix.org/swetrix.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    swetrix.init('<%= theme.swetrix_project_id || "YOUR_PROJECT_ID" %>')
    swetrix.trackViews()
  })
</script>

<noscript>
  <img
    src="https://api.swetrix.com/log/noscript?pid=<%= theme.swetrix_project_id || 'YOUR_PROJECT_ID' %>"
    alt=""
    referrerpolicy="no-referrer-when-downgrade"
  />
</noscript>
<% } %>

Then run your dev server with the environment variable:

NODE_ENV=development hexo server

And build for production with:

NODE_ENV=production hexo generate
tip

Since Swetrix ignores localhost traffic by default, the environment-based conditional is optional. It's useful if you want to avoid loading the script entirely during development.

Error tracking​

Enable automatic client-side error monitoring by adding trackErrors() alongside your existing initialisation:

<script src="https://swetrix.org/swetrix.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    swetrix.init('YOUR_PROJECT_ID')
    swetrix.trackViews()
    swetrix.trackErrors()
  })
</script>

Errors will appear in the Errors tab of your project dashboard. See the tracking script reference for options like sampleRate and callback.

Tracking custom events​

Custom events let you track specific user interactions — button clicks, form submissions, downloads, and more.

Inline event tracking​

<button onclick="swetrix.track({ ev: 'SIGNUP_CLICK' })">
  Sign up
</button>

Example: tracking form submissions​

<form id="contact-form" action="/thank-you">
  <input type="email" placeholder="you@example.com" required />
  <button type="submit">Subscribe</button>
</form>

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var form = document.getElementById('contact-form')
    if (!form || typeof swetrix === 'undefined') return

    form.addEventListener('submit', function () {
      swetrix.track({
        ev: 'NEWSLETTER_SIGNUP',
        meta: { source: 'footer' },
      })
    })
  })
</script>

Event naming rules​

Event names must:

  • Contain any characters (including spaces, unicode, etc.)
  • Be no longer than 256 characters

Using the Swetrix npm package​

Since Hexo runs on Node.js, you can also install the swetrix npm package if you want to use it in custom scripts or helper plugins:

npm install swetrix

Then use it in a client-side script bundled with your theme:

import * as Swetrix from 'swetrix'

Swetrix.init('YOUR_PROJECT_ID')
Swetrix.trackViews()

Check your installation​

After adding the tracking script, generate your site with hexo generate and deploy it. Visit your live website and navigate through a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.

Further reading​

Help us improve Swetrix

Was this page helpful to you?

Learn how to contribute•Report a problem with this content