add docs

binjamil · May 19, 2024 · 0aa0d3c · 0aa0d3c
1 parent a7ca6a8
commit 0aa0d3c
Show file tree

Hide file tree

Showing 7 changed files with 117 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @mbinjamil/matomo-client
 
+## 0.3.0
+
+### Minor Changes
+
+- Add docs
+
 ## 0.2.0
 
 ### Minor Changes

diff --git a/README.md b/README.md
@@ -1,17 +1,116 @@
-@mbinjamil/matomo-client
+# Matomo client
 
-## Installation
+A framework-agnostic JavaScript client for [Matomo analytics](https://matomo.org/).
+
+### Installation
 
 ```
 npm install @mbinjamil/matomo-client
 ```
 
-## Features
+## Motivation
+
+The standard installation flow for Matomo is to add a script tag in your HTML, which automatically records a page view when loaded. This is not suitable for single-page applications, like React, Next.js and many others, where client-side routing takes place. Other Matomo JS libraries are outdated and archived.
+
+Heavily inspired by [fathom-client](https://github.com/derrickreimer/fathom-client), this library provides a simple interface to orchestrate Matomo calls. It features:
+
 
-- Injecting and loading Matomo script asynchronously
+- **Asynchronous script loading.** A `load` function that asynchronously injects the Matomo `<script>` tag (great for single-page app environments) and is idempotent (multiple calls to it have no side effects).
+- **`import`-able tracking functions.** Tracking functions (`trackPageview` and `trackEvent`) can be imported and safely called anywhere (even if the Matomo script has not yet finished loading).
 
 ## Usage
 
-Load script on mount and call tracking functions anywhere in the app
+The basic way to use this library to call `load` function when your app first loads (or mounts) and call any tracking functions wherever you want. Ideally you would call `trackPageView` whenever your app changes routes.
+
+Below I've described usage for two popular choices, but you can use it with any frontend library or framework by following the basic principles.
+
+### React Router (or Remix)
+
+Create a new component `<Matomo>`
+
+```jsx
+import { useLocation } from "react-router-dom";
+import { load, trackPageView } from "@mbinjamil/matomo-client";
+import { useEffect } from "react";
+
+export default function Matomo() {
+  const location = useLocation();
+
+  // Load script on mount
+  useEffect(() => {
+    load("https://mbinjamildev.matomo.cloud/", 1);
+  }, []);
+
+  // Track page view on route change
+  useEffect(() => {
+    trackPageView();
+  }, [location.pathname, location.search]);
+
+  return null;
+}
+```
+
+Then, add the component to the root route or layout
+
+```jsx
+import { NavLink, Outlet, useLocation } from "react-router-dom";
+import Matomo from "./Matomo";
+
+export default function Root() {
+  return (
+    <div>
+      <Matomo />
+      <Outlet />
+    </div>
+  );
+}
+```
+
+### Next.js
+
+Create a client component `<Matomo>`
+
+```jsx
+"use client"
+import { load, trackPageView } from "@mbinjamil/matomo-client";
+import { useEffect } from "react";
+import { usePathname, useSearchParams } from "next/navigation";
+
+export default function Matomo() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  // Load script on mount
+  useEffect(() => {
+    load("https://mbinjamildev.matomo.cloud/", 1);
+  }, []);
+
+  // Track page view on route change
+  useEffect(() => {
+    trackPageView();
+  }, [pathname, searchParams])
+
+  return null
+}
+```
+
+Then, add the client component to your root `layout.tsx` file:
+
+```tsx
+import Matomo from "./Matomo";
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head></head>
+      <body>
+        <Matomo />
+        <Page>{children}</Page>
+      </body>
+    </html>
+  );
+}
+```
+
+### [API Reference](docs/README.md)
 
-### [API Reference](docs/README.md)
diff --git a/docs/functions/load.md b/docs/functions/load.md
@@ -22,4 +22,4 @@ Site ID of the website you are tracking in Matomo
 
 ## Source
 
-[index.ts:13](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L13)
+[index.ts:13](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L13)
diff --git a/docs/functions/push.md b/docs/functions/push.md
@@ -28,4 +28,4 @@ push([ 'API_method_name', parameter_list ]);
 
 ## Source
 
-[index.ts:71](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L71)
+[index.ts:71](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L71)
diff --git a/docs/functions/trackEvent.md b/docs/functions/trackEvent.md
@@ -30,4 +30,4 @@ An optional numeric value
 
 ## Source
 
-[index.ts:53](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L53)
+[index.ts:53](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L53)
diff --git a/docs/functions/trackPageView.md b/docs/functions/trackPageView.md
@@ -19,4 +19,4 @@ A custom title that overrides the default HTML page title
 
 ## Source
 
-[index.ts:40](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L40)
+[index.ts:40](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L40)
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mbinjamil/matomo-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A thin wrapper around Matomo analytics",
   "keywords": [
     "matomo",
@@ -31,7 +31,7 @@
     "build": "pnpm build:types && pnpm build:js",
     "build:js": "node build.mjs",
     "build:types": "tsc --emitDeclarationOnly",
-    "release": "pnpm build && pnpm changeset publish",
+    "release": "pnpm run docs && pnpm build && pnpm changeset publish",
     "typecheck": "tsc --noEmit",
     "docs": "typedoc src/index.ts --readme none"
   },
Original file line number	Diff line number	Diff line change
Expand Up		@@ -22,4 +22,4 @@ Site ID of the website you are tracking in Matomo

		## Source

		[index.ts:13](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L13)
		[index.ts:13](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L13)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,4 +28,4 @@ push([ 'API_method_name', parameter_list ]);

		## Source

		[index.ts:71](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L71)
		[index.ts:71](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L71)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,4 +30,4 @@ An optional numeric value

		## Source

		[index.ts:53](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L53)
		[index.ts:53](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L53)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -19,4 +19,4 @@ A custom title that overrides the default HTML page title

		## Source

		[index.ts:40](https://github.com/binjamil/matomo-client/blob/ffe9db3ab8b729a706d4a5e6374173837f833606/src/index.ts#L40)
		[index.ts:40](https://github.com/binjamil/matomo-client/blob/a7ca6a85fbfefc0fecb6fccc11ed975b808ab0e5/src/index.ts#L40)