Adding Umami to React without tracking failing silently
With umami-react you add Umami to a React app as a component. Four places where nothing gets counted and no error message shows up.
Umami is a web analytics tool that works without cookies and that you can host yourself. It is added with a single script tag. In a React app I prefer to manage that tag in one place in the component tree, with configuration from props and without tracking during development.
For that I wrote umami-react, on npm as @danielgtmn/umami-react. The component renders nothing. It only appends the Umami script to document.head and sets the required attributes.
The simple case
pnpm add @danielgtmn/umami-react
import UmamiAnalytics from '@danielgtmn/umami-react';
export function App() {
return (
<>
<UmamiAnalytics
url="https://analytics.example.com"
websiteId="deine-website-id"
/>
{/* rest of the app */}
</>
);
}
That turns into <script defer src="https://analytics.example.com/script.js" data-website-id="…">. From then on Umami counts page views itself, including navigation inside a single-page app.
The tricky thing about analytics is that an error does not stand out. The page works, only the dashboard stays empty. I have run into four places like that.
1. Locally, nothing is counted on purpose
onlyInProduction defaults to true. If NODE_ENV equals development, the component does not load the script at all. That is intended, so your own test visits do not end up in the statistics. But it also means: in the dev server you see no request to Umami in the Network tab, and that is not a bug.
If you want to test tracking locally, set the prop to false temporarily, and ideally create a separate test website in Umami.
2. Without debug there is no error message
If url or websiteId is missing, the component loads nothing. But it only reports that in the console when debug is active. So while setting things up, it is worth switching debug on once:
<UmamiAnalytics url="…" websiteId="…" debug />
Then the console shows which configuration the component starts with, whether the script was loaded or why not. Switch it off again afterwards.
3. Environment variables often do not reach the browser
According to the README, the component can also read url and websiteId from UMAMI_URL and UMAMI_ID. In the code that is an access to process.env. Whether that returns anything in the browser depends on the bundler. Next.js only passes variables with the NEXT_PUBLIC_ prefix to the client, Vite only those with VITE_ through import.meta.env. A variable named UMAMI_ID is simply empty in the browser there, and then point 2 applies.
It is safer to pass the values as props yourself. In the Next.js App Router that belongs in a client component, more on that further down:
// Next.js
<UmamiAnalytics
url={process.env.NEXT_PUBLIC_UMAMI_URL}
websiteId={process.env.NEXT_PUBLIC_UMAMI_ID}
/>
// Vite
<UmamiAnalytics
url={import.meta.env.VITE_UMAMI_URL}
websiteId={import.meta.env.VITE_UMAMI_ID}
/>
The website ID is not a secret. It ends up in the browser anyway, in the bundle and as data-website-id on the script tag.
4. lazyLoad only counts visitors who do something
With lazyLoad the script only loads on the first mouse movement, the first scroll, click or key press. That keeps the script out of the initial page load. In exchange, anyone who opens the page, reads without scrolling and leaves again never shows up in the statistics. On short pages or on a phone in particular, that is not an edge case.
Since the script is loaded with defer anyway and is small, I leave lazyLoad off. If you switch it on, you should know that visitor numbers will look lower and the bounce rate better than they are.
Next.js with the App Router
The component uses useEffect, but the published package carries no 'use client' directive. Imported directly into a server layout such as app/layout.tsx, it makes Next.js complain. A small client component in between solves that:
// app/analytics.tsx
'use client';
import UmamiAnalytics from '@danielgtmn/umami-react';
export function Analytics() {
return (
<UmamiAnalytics
url={process.env.NEXT_PUBLIC_UMAMI_URL}
websiteId={process.env.NEXT_PUBLIC_UMAMI_ID}
/>
);
}
// app/layout.tsx
import { Analytics } from './analytics';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="de">
<body>
<Analytics />
{children}
</body>
</html>
);
}
Custom events
For clicks on buttons or submitted forms there is the useUmami hook. In the Next.js App Router the file with the button also needs 'use client' at the very top, because it uses a hook and onClick:
'use client';
import { useUmami } from '@danielgtmn/umami-react';
export function KontaktButton() {
const { track } = useUmami();
return (
<button onClick={() => track('kontakt-klick', { ort: 'header' })}>
Kontakt
</button>
);
}
track calls window.umami.track as soon as the script is loaded. Before that nothing happens, not even an error. So a click in the first milliseconds after loading, or with lazyLoad before the first interaction, is lost. For events like "form submitted" that is rarely a problem, for "page opened" it is. Umami counts that one itself anyway.
UTM parameters belong in the URL
Umami reads utm_source, utm_medium and the other UTM values from the requested URL. A link like https://example.com/?utm_source=newsletter&utm_medium=email is enough for the campaign to show up in the dashboard, without a line of code. I would always take this route first.
Checking it works
Open the built site, not the dev server, and look at the Network tab. You should see two requests: script.js from your Umami instance and then a POST to /api/send. If that one responds with an error, the reason is in the response body. If neither request shows up, switch debug on and read the console.
In Umami itself, the realtime view shows your own visit after a few seconds.
Common questions
- Why does Umami count nothing in the dev server?
- In umami-react, onlyInProduction defaults to true. If NODE_ENV equals development, the component does not load the script at all, so your own test visits do not end up in the statistics. If you want to test tracking locally, you set the prop to false temporarily.
- Why do UMAMI_URL and UMAMI_ID not reach the browser?
- umami-react reads both variables through process.env, and whether that returns anything in the browser depends on the bundler. Next.js only passes variables with the NEXT_PUBLIC_ prefix to the client, Vite only those with VITE_ through import.meta.env. It is safer to pass url and websiteId as props yourself.
- How do I add umami-react in the Next.js App Router?
- The umami-react package carries no 'use client' directive, so Next.js complains when you import the component directly into a server layout such as app/layout.tsx. Put a small client component with 'use client' in between and use that one in the layout.
- How do I check whether Umami tracking works?
- Open the built site, not the dev server, and look at the Network tab. You should see script.js from your Umami instance and then a POST to /api/send. If neither request shows up, switch on debug in umami-react and read the console.