Umami tracker client for React, context and hooks only
- zero dependencies
- Double module export (CJS, ESM)
- Baked in Typescript typings
- Side effects free (
sideEffect: false) - Respect the user choice about privacy by default ("Ask to not track" option)
Works nicely with NextJS (12, 13 (Client side only))
This lib is still WIP, no package is out on NPM yet. There is some work left to do:
- README - API Paragraph
- Tests and coverage
- Release script
- CI integration for tests and coverage
- CI integration for releases
- Contribution guide (Nice to have)
I was trying to gather some analytics for my NextJS (v12 - pages folder) personal site, especially about the interactions with my resumee. I started thinking about Google Analitycs but I also wanted to keep this data for me, and granting the minimum privacy impact to the visitors.
Then I found Umami.is opting to self-host it on my home server (or better said, a Raspberry Pi 3), but I realized that umami provides it's own library. I didn't want to let some adblocker or something preventing me from using those service, and I needed something that better integrates with NextJS.
There is a react-umami (NPM/Repo) package by the user LucasSovre published that is quite similar to this one. It offers the same flexibility of not having any external js file loaded at runtime, but it's left to the user to bind with React (via effects)
This package is available via NPM. That one offers the very same hooks as this package does, but it still requires the external official umami js sdk to be loaded. The choice is acceptable when it comes to the abstraction for the SDK implementation, but it does not solve breaking changes issues in the SDK API changes.
@lbrdan/react-umami tries to combine and takes the best of both of these approaches, by using hooks and context to gather flexibility for React developers without the needs of an externally included SDK
@lbrdan/react-umami is available npm public repository. The releases are synced with the ones on GitHub.
To install it just use your favorite package manager: (WIP - Coming soon)
# NPM
npm i react-umami
# Yarn / Yarn Berry
yarn add react-umami
# PNPM
pnpm add react-umamiFirst, you'll need to setup UmamiProvider to let the hooks use a premade context (provided via React.Context)
You can use this in NextJS [pages/_app.tsx]:
import { AppProps } from "next/app";
import Head from "next/head";
import { UmamiProvider } from "@lbrdan/react-umami";
function App({ Component, pageProps, router, ...props }: AppProps) {
return (
<>
<Head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="author" content="LBRDan" />
<link rel="apple-touch-icon" href="apple-touch-icon.png" />
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
</Head>
<UmamiProvider
hostUrl={process.env.NEXT_PUBLIC_UMAMI_HOSTNAME} // Loaded via ENV
websiteId={process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID} // Loaded via ENV
getCurrentUrl={() => router.pathname}
domains={["my-domain.com", "localhost"]}
>
<Component {...pageProps} />
</UmamiProvider>
</>
);
}Or with plain React:
import React, { FC } from "react";
import { UmamiProvider, PageTracker } from "@lbrdan/react-umami";
const UMAMI_CONFIG = {
apiUrl: "https://my-umami-host.example.com/",
websiteId: "umami-id-for-mywebsite",
allowedDomains: ["my-website.com"], // or [window.location.hostname]
};
const App: FC<{}> = (props) => {
return (
<UmamiProvider
hostUrl={UMAMI_CONFIG.apiUrl}
websiteId={UMAMI_CONFIG.websiteId}
getCurrentUrl={() => window.location.pathname}
domains={UMAMI_CONFIG.allowedDomains}
>
<Component {...pageProps} />
</UmamiProvider>
);
};
export default App;Tip: You could use Next Router (or your router of choice eg. react-router) to ensure a consistent app wide pageview tracking together with the provided component PageTracker
With Next (v12)...
import { AppProps } from "next/app";
import Head from "next/head";
import { UmamiProvider, PageTracker } from "@lbrdan/react-umami";
function App({ Component, pageProps, router, ...props }: AppProps) {
return (
<>
<Head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="author" content="LBRDan" />
<link rel="apple-touch-icon" href="apple-touch-icon.png" />
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
</Head>
<UmamiProvider
hostUrl={process.env.NEXT_PUBLIC_UMAMI_HOSTNAME} // Loaded via ENV
websiteId={process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID} // Loaded via ENV
getCurrentUrl={() => router.pathname}
domains={["my-domain.com", "localhost"]}
>
<PageTracker pageUrl={router.asPath} />
<Component {...pageProps} />
</UmamiProvider>
</>
);
}... or plain React
import React, { FC } from "react";
import { UmamiProvider, PageTracker } from "@lbrdan/react-umami";
import { BrowserRouter, useLocation } from "react-router-dom";
const UMAMI_CONFIG = {
apiUrl: "https://my-umami-host.example.com/",
websiteId: "umami-id-for-mywebsite",
allowedDomains: ["my-website.com"], // or [window.location.hostname]
};
const App: FC<{}> = (props) => {
return (
<BrowserRouter>
<UmamiProvider
hostUrl={UMAMI_CONFIG.apiUrl}
websiteId={UMAMI_CONFIG.websiteId}
getCurrentUrl={() => window.location.pathname}
domains={UMAMI_CONFIG.allowedDomains}
>
<PageTrackerRR />
<Component {...pageProps} />
</UmamiProvider>
</BrowserRouter>
);
};
const PageTrackerRR: FC<{}> = () => {
const location = useLocation();
return <PageTracker pageUrl={location.pathname} />;
};
export default App;PRs are welcome
Small note: If editing the README, please conform to the standard-readme specification.
MIT License