DavidWells · parkerthierry276-code · Sep 26, 2022 · Sep 27, 2022 · Sep 27, 2022 · Oct 5, 2022
diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,15 @@
 # node / npm
 node_modules
 .size-snapshot.json
-package-lock.json
 *.log
 .netlify
+
+_misc
+
+# turbo cache
+.turbo
+# nx cache
+.nx
 # IDE stuff
 **/.idea
 
@@ -16,4 +22,7 @@ misc
 queues
 TODO.md
 types/
-misc.js
+misc.js
+
+### VisualStudioCode ###
+.vscode/*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,14 +7,27 @@ please read the [code of conduct](CODE_OF_CONDUCT.md).
 
 > Install node & npm on your system: [https://nodejs.org/en/download/](https://nodejs.org/en/download/)
 
+### Package Manager
+
+This project uses **pnpm** as the package manager. If you don't have pnpm installed, you can install it globally:
+
+```sh
+# Install pnpm globally
+npm install -g pnpm
+
+# Or using other methods:
+# curl -fsSL https://get.pnpm.io/install.sh | sh -
+# brew install pnpm (on macOS)
+```
+
 ### Install dependencies
 
 > Only required when setting up the project
 
 ```sh
 $ git clone https://github.com/davidwells/analytics
 $ cd analytics
-$ npm run setup
+$ pnpm run setup
 ```
 
 Because analytics has a large number of packages, we need to also [install watchman](https://facebook.github.io/watchman/docs/install.html) for better watching.
@@ -28,11 +41,11 @@ brew install watchman
 
 To run analytics locally follow these steps:
 
-1. Make sure you have run `npm run setup` to install all packages
-2. Run `npm run build` to ensure analytics packages are built
-3. Run watch mode `npm run watch` to have changes reflected live in the demo app.
-4. In a new terminal window, change directories into the [`/examples/demo`](https://github.com/DavidWells/analytics/tree/master/examples/demo) folder & install the demo apps dependencies `npm install`
-5. Finally, you can start the demo app with `npm start`
+1. Make sure you have run `pnpm run setup` to install all packages
+2. Run `pnpm run build` to ensure analytics packages are built
+3. Run watch mode `pnpm run watch` to have changes reflected live in the demo app.
+4. In a new terminal window, change directories into the [`/examples/demo`](https://github.com/DavidWells/analytics/tree/master/examples/demo) folder & install the demo apps dependencies `pnpm install`
+5. Finally, you can start the demo app with `pnpm start`
 
 If you have any questions please ping [@DavidWells](https://twitter.com/davidwells) on Twitter.
 
@@ -45,7 +58,7 @@ Installs and sets up all analytics package dependencies.
 #### Usage
 
 ```sh
-$ npm run setup
+$ pnpm run setup
 ```
 
 ### `watch`
@@ -55,7 +68,7 @@ Watches all `analytics` packages and builds them on change.
 #### Usage
 
 ```sh
-$ npm run watch
+$ pnpm run watch
 ```
 
 ### `clean`
@@ -65,7 +78,7 @@ Removes all of the `analytics` packages `dist` directories.
 #### Usage
 
 ```sh
-npm run clean
+pnpm run clean
 ```
 
 ### `reset`
@@ -75,7 +88,7 @@ Runs the `clean` script and removes all the `node_modules` from the `analytics`
 #### Usage
 
 ```sh
-npm run reset
+pnpm run reset
 ```
 
 ### `build`
@@ -85,7 +98,7 @@ Runs the `clean` script and builds the `analytics` packages.
 #### Usage
 
 ```sh
-npm run build
+pnpm run build
 ```
 
 ### `test`
@@ -95,7 +108,7 @@ Runs all the `analytics` packages tests.
 #### Usage
 
 ```sh
-npm run test
+pnpm run test
 ```
 
 ## Pull Requests
@@ -110,10 +123,16 @@ Analytics uses the [Forking Workflow](https://www.atlassian.com/git/tutorials/co
 2. Create a branch from `master`. If you're addressing a specific issue, prefix your branch name with the issue number.
 2. If you've added code that should be tested, add tests.
 3. If you've changed APIs, update the documentation.
-4. Run `npm run test` and ensure the test suite passes.
+4. Run `pnpm run test` and ensure the test suite passes.
 6. PR's must be rebased before merge (feel free to ask for help).
 7. PR should be reviewed by two maintainers prior to merging.
 
+## Troubleshooting
+
+`Publishing error`
+
+`Hard link is not allowed` means the node_modules folder is in the npm package. Delete those from /analytics-core/{client|server} dirs.
+
 ## License
 
 By contributing to `analytics`, you agree that your contributions will be licensed

diff --git a/README.md b/README.md
diff --git a/examples/README.md b/examples/README.md
@@ -1,9 +1,116 @@
 # Analytics Examples
 
-- [Kitchen sink demo](./demo)
-- [React example](./react)
-- [use-analytics react hooks with React Router v6](https://github.com/DavidWells/use-analytics-with-react-router-demo)
-- [HTML example](./vanilla-html)
-- [Preact example](./preact)
-- [Vue example](./vue)
-- [Track performance metrics example](./using-perfumejs)
+This directory contains comprehensive examples demonstrating how to use the Analytics library across different frameworks and scenarios. Each example includes complete setup instructions, live demos (where available), and detailed implementation guides.
+
+## 🚀 Framework Examples
+
+### [Kitchen Sink Demo](./demo)
+**Full-featured demo application with comprehensive analytics setup**
+- **Framework**: React with Vite
+- **Features**: Complete analytics implementation with multiple plugins, event tracking, user identification, and real-time analytics debugging
+- **Live Demo**: Available locally
+- **Best For**: Understanding all analytics features, testing plugin configurations, and development workflows
+- **Key Files**: `./src/utils/analytics/` contains various configuration examples
+- **Setup**: Requires building local packages first (`npm run setup && npm run build` from repo root)
+
+### [React Example](./react)
+**Production-ready React application with analytics integration**
+- **Framework**: React with routing
+- **Features**: Page view tracking, component-level analytics, React Router integration
+- **Live Demo**: [https://analytics-react-example.netlify.app/](https://analytics-react-example.netlify.app/)
+- **Best For**: React applications with client-side routing
+- **Key Files**: `./src/components/Layout` for analytics setup
+- **Setup**: Standard React app setup with `npm install && npm start`
+
+### [Next.js App Router Example](./nextjs-app-router)
+**Modern Next.js 13+ app router implementation**
+- **Framework**: Next.js with App Router
+- **Features**: Server-side rendering compatibility, automatic page tracking, React hooks integration
+- **Best For**: Next.js applications using the new app router pattern
+- **Key Files**: `/src/app/analytics.tsx` and `/src/app/layout.tsx`
+- **Setup**: `npm install && npm run dev`
+
+### [HTML/Vanilla JavaScript Example](./vanilla-html)
+**Simple browser-based implementation using CDN**
+- **Framework**: Plain HTML/JavaScript
+- **Features**: CDN-based loading, minimal setup, browser compatibility
+- **Live Demo**: [https://analytics-html-example.netlify.app/](https://analytics-html-example.netlify.app/)
+- **Best For**: Static websites, simple integrations, quick prototyping
+- **Key Features**: No build process required, works with any website
+- **Setup**: Open `index.html` in browser or serve statically
+
+### [Preact Example](./preact)
+**Lightweight Preact application with routing**
+- **Framework**: Preact with Preact Router
+- **Features**: Small bundle size, React-like development experience, automatic page tracking
+- **Live Demo**: [https://analytics-preact-example.netlify.app/](https://analytics-preact-example.netlify.app/)
+- **Best For**: Performance-conscious applications, smaller bundle requirements
+- **Key Files**: `/src/analytics.js` for setup
+- **Setup**: `npm install && npm run dev`
+
+### [Vue Example](./vue)
+**Vue.js application with Vue Router integration**
+- **Framework**: Vue.js with Vue Router
+- **Features**: Vue ecosystem integration, automatic page view tracking via router hooks
+- **Best For**: Vue.js applications with client-side routing
+- **Key Files**: `./src/main.js` & `./src/analytics.js`
+- **Router Integration**: Page views fired from `router.afterEach` events
+- **Setup**: `npm install && npm run serve`
+
+## 🔧 Specialized Examples
+
+### [Performance Tracking with Perfume.js](./using-perfumejs)
+**Advanced performance monitoring integration**
+- **Framework**: React with Perfume.js
+- **Features**: Core Web Vitals tracking, performance metrics, automatic performance event sending
+- **Live Demo**: [https://analytics-perfumejs-example.netlify.app/](https://analytics-perfumejs-example.netlify.app/)
+- **Best For**: Applications requiring detailed performance monitoring and optimization
+- **Video Tutorial**: [Watch the implementation video](https://www.youtube.com/watch?v=9DZAVpAubtQ)
+- **Key Integration**: Automatic performance metrics sent to analytics providers
+
+## 🌐 External Examples
+
+### [React Router v6 Hooks Example](https://github.com/DavidWells/use-analytics-with-react-router-demo)
+**Advanced React Router integration with analytics hooks**
+- **Framework**: React with React Router v6
+- **Features**: `use-analytics` React hooks, advanced routing patterns, hook-based analytics
+- **Best For**: Modern React applications using hooks pattern with React Router v6
+
+## 📋 Getting Started
+
+### Prerequisites
+- Node.js 18+ for framework examples
+- Modern browser for HTML example
+- For demo example: Build local packages first
+
+### Quick Start Guide
+
+1. **Choose your framework** from the examples above
+2. **Navigate to the example directory**: `cd examples/{example-name}`
+3. **Install dependencies**: `npm install` (except for HTML example)
+4. **Start development server**: `npm start` or `npm run dev`
+5. **Open browser** and start exploring analytics features
+
+### Development Workflow
+
+For the **demo example** specifically:
+1. Build all packages: `npm run setup && npm run build` (from repo root)
+2. Install demo dependencies: `cd examples/demo && npm install`
+3. For live plugin development: `npm run watch` (from repo root)
+4. Start demo: `npm start` (from demo directory)
+
+## 🎯 Use Cases
+
+- **Learning**: Start with the HTML example for simplicity
+- **React Development**: Use React or Next.js examples based on your setup
+- **Performance Monitoring**: Use the Perfume.js example for Core Web Vitals
+- **Production Setup**: The demo example shows comprehensive configuration options
+- **Small Bundles**: Preact example for size-conscious applications
+- **Vue Ecosystem**: Vue example for Vue.js applications
+
+## 📚 Additional Resources
+
+- [Analytics Documentation](../README.md)
+- [Plugin Documentation](../packages/)
+- [API Reference](../site/main/source/api.md)
+- [Writing Custom Plugins](../site/main/source/plugins/writing-plugins.md)
diff --git a/examples/demo/index.html b/examples/demo/index.html
@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="shortcut icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
+    <meta name="theme-color" content="#000000" />
+
+    <link rel="manifest" href="/manifest.json" />
+    <!-- <script src="/custom-ga.js" crossorigin="anonymous"></script>-->
+
+    <title>Analytics Demo</title>
+    <script src="https://browser.sentry-cdn.com/5.1.3/bundle.min.js" crossorigin="anonymous"></script>
+    <script>
+      if (window.location.origin !== 'http://localhost:3000') {
+        Sentry.init({
+          dsn: 'https://d455294009a14ff0bbe66516b96e65d6@sentry.io/1455338'
+        });
+      }
+    </script>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.jsx"></script>
+  </body>
+</html>
diff --git a/examples/demo/package.json b/examples/demo/package.json
@@ -2,12 +2,14 @@
   "name": "demo",
   "version": "0.1.0",
   "private": true,
+  "type": "module",
   "scripts": {
-    "start": "react-scripts start",
-    "build": "react-scripts build",
-    "test": "react-scripts test",
-    "serve": "cd build && http-server",
-    "deploy": "netlify deploy --dir build --prod"
+    "dev": "vite",
+    "start": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "serve": "vite preview",
+    "deploy": "netlify deploy --dir dist --prod --site b5accf61-3856-49a1-ac48-86bb06b57d4b"
   },
   "dependencies": {
     "@analytics/core": "file:../../packages/analytics-core",
@@ -24,7 +26,6 @@
     "@analytics/simple-analytics": "file:../../packages/analytics-plugin-simple-analytics",
     "@analytics/snowplow": "file:../../packages/analytics-plugin-snowplow",
     "@analytics/storage-utils": "file:../../packages/analytics-util-storage",
-    "@reach/router": "^1.2.1",
     "analytics": "file:../../packages/analytics",
     "analytics-plugin-do-not-track": "file:../../packages/analytics-plugin-do-not-track",
     "analytics-plugin-event-validation": "file:../../packages/analytics-plugin-event-validation",
@@ -35,13 +36,16 @@
     "analytics-utils": "file:../../packages/analytics-utils",
     "outdent": "^0.7.0",
     "perfume.js": "^5.0.2",
-    "react": "^16.7.0",
-    "react-dom": "^16.7.0",
-    "react-scripts": "2.1.3",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router-dom": "^6.28.0",
     "use-analytics": "file:../../packages/use-analytics"
   },
-  "eslintConfig": {
-    "extends": "react-app"
+  "devDependencies": {
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^5.4.11"
   },
   "browserslist": [
     ">0.2%",

diff --git a/examples/demo/public/index.html b/examples/demo/public/index.html
@@ -2,12 +2,12 @@
 <html lang="en">
   <head>
     <meta charset="utf-8" />
-    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico" />
+    <link rel="shortcut icon" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
     <meta name="theme-color" content="#000000" />
 
-    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
-    <!-- <script src="%PUBLIC_URL%/custom-ga.js" crossorigin="anonymous"></script>-->
+    <link rel="manifest" href="/manifest.json" />
+    <!-- <script src="/custom-ga.js" crossorigin="anonymous"></script>-->
 
     <title>Analytics Demo</title>
     <script src="https://browser.sentry-cdn.com/5.1.3/bundle.min.js" crossorigin="anonymous"></script>
@@ -22,5 +22,6 @@
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="root"></div>
+    <script type="module" src="/src/index.js"></script>
   </body>
 </html>
diff --git a/examples/demo/src/components/ForkMe/index.js → ...ples/demo/src/components/ForkMe/index.jsx b/examples/demo/src/components/ForkMe/index.js → ...ples/demo/src/components/ForkMe/index.jsx
diff --git a/examples/demo/src/components/Log/index.js → examples/demo/src/components/Log/index.jsx b/examples/demo/src/components/Log/index.js → examples/demo/src/components/Log/index.jsx