Skip to content
NuxtBase logo NuxtBase Docs

Analytics Setup

Analytics is optional in NuxtBase and defaults to disabled.

That is a good default. Buyers should not be forced to wire analytics before they can install, customize, or validate the product.

Default: Analytics Disabled

Section titled “Default: Analytics Disabled”

The baseline env value is:

Terminal window
NUXT_PUBLIC_ANALYTICS_PROVIDER=none

With this setting, no analytics provider is loaded.

Supported Providers

Section titled “Supported Providers”

NuxtBase currently supports these values:

  • ga4
  • umami
  • plausible
  • none

The provider selection is parsed in shared/config/analytics.ts, and only the selected provider is added to the @nuxt/scripts registry.

GA4 Setup

Section titled “GA4 Setup”
Terminal window
NUXT_PUBLIC_ANALYTICS_PROVIDER=ga4
NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Use this when you want standard Google Analytics 4 tracking.

How to Get the GA4 Measurement ID

Section titled “How to Get the GA4 Measurement ID”

Official Google Analytics references:

Practical setup steps:

  1. Sign in to Google Analytics.
  2. Create a GA4 account or use an existing one.
  3. Create a GA4 property for your site if you do not already have one.
  4. In Admin, open Data Streams and create a Web stream for your site.
  5. Open that web stream and copy the Measurement ID that starts with G-.
  6. Paste it into NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID.
  7. Restart the app and verify that the Google Analytics script loads.

Umami Setup

Section titled “Umami Setup”
Terminal window
NUXT_PUBLIC_ANALYTICS_PROVIDER=umami
NUXT_PUBLIC_SCRIPTS_UMAMI_ANALYTICS_WEBSITE_ID=your-website-id
NUXT_UMAMI_HOST=https://your-umami-instance.com
NUXT_UMAMI_DOMAINS=app.example.com,staging.example.com

NUXT_UMAMI_HOST and NUXT_UMAMI_DOMAINS are optional, but helpful when you run your own Umami instance or want to scope domains explicitly.

How to Get the Umami Website ID and Script URL

Section titled “How to Get the Umami Website ID and Script URL”

Official Umami references:

Practical setup steps:

  1. Sign in to Umami Cloud or your self-hosted Umami instance.
  2. Open Websites and click Add website.
  3. Enter the site name and domain, then save.
  4. Open the website settings and go to the Tracking code section.
  5. Copy the data-website-id value from the tracking snippet into NUXT_PUBLIC_SCRIPTS_UMAMI_ANALYTICS_WEBSITE_ID.
  6. Copy the tracker host from the script URL into NUXT_UMAMI_HOST if you are not using the default hosted setup.
  7. If you only want the tracker to run on specific domains, copy those hostnames into NUXT_UMAMI_DOMAINS.
  8. Restart the app and verify that the Umami script loads.

In other words:

  • NUXT_PUBLIC_SCRIPTS_UMAMI_ANALYTICS_WEBSITE_ID maps to Umami’s data-website-id
  • NUXT_UMAMI_HOST maps to the tracker host used by the script
  • NUXT_UMAMI_DOMAINS maps to Umami’s optional data-domains setting

Plausible Setup

Section titled “Plausible Setup”

There are two supported patterns.

Current Plausible Script ID

Section titled “Current Plausible Script ID”
Terminal window
NUXT_PUBLIC_ANALYTICS_PROVIDER=plausible
NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_SCRIPT_ID=your-script-id
NUXT_PLAUSIBLE_HOST=https://your-plausible-instance.com

Legacy Domain-Based Config

Section titled “Legacy Domain-Based Config”
Terminal window
NUXT_PUBLIC_ANALYTICS_PROVIDER=plausible
NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_DOMAIN=example.com
NUXT_PLAUSIBLE_HOST=https://your-plausible-instance.com

The template supports either script-id based setup or the older domain-based fallback.

How to Get the Plausible Script ID or Domain

Section titled “How to Get the Plausible Script ID or Domain”

Official Plausible references:

Practical setup steps:

  1. Sign in to Plausible and add your site.
  2. In the site setup flow, enter the domain you want Plausible to track.
  3. Open the site’s Settings, then go to the Site Installation area in General.
  4. Copy the installation snippet that Plausible generates for that site.
  5. If your snippet uses a personalized script such as https://plausible.io/js/pa-XXXXX.js, copy the pa-XXXXX part into NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_SCRIPT_ID.
  6. If you prefer the older domain-based setup, put the tracked domain into NUXT_PUBLIC_SCRIPTS_PLAUSIBLE_ANALYTICS_DOMAIN instead.
  7. If you are self-hosting Plausible or using a custom Plausible host, put that base URL into NUXT_PLAUSIBLE_HOST.
  8. Restart the app and verify that the Plausible script loads.

For this template:

  • use the script ID path when Plausible gives you a personalized pa-XXXXX.js snippet
  • use the domain fallback only when that better matches your existing Plausible setup

Runtime Behavior

Section titled “Runtime Behavior”

Analytics loading is centralized in Nuxt config, not scattered through components.

That matters because:

  • only one provider is loaded at runtime
  • the app can stay clean when analytics is off
  • provider mismatches are easier to debug

There is also a small client plugin that warns when the selected provider does not appear to have the required script configuration.

Section titled “Recommended Setup Sequence”
  1. keep analytics on none during initial local setup
  2. choose one provider only
  3. add the provider-specific env vars
  4. restart the app
  5. confirm the browser loads the expected tracking script

What to Check in the Browser

Section titled “What to Check in the Browser”

After enabling analytics, verify:

  1. the correct script appears in the page
  2. the browser console does not show provider mismatch warnings
  3. your analytics dashboard receives a pageview or test event