nuxt-visitors 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024-present Hugo Richard
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,121 @@
+# Nuxt Active Users
+
+<!-- automd:badges color=black license provider=shields name=nuxt-visitors -->
+
+[![npm version](https://img.shields.io/npm/v/nuxt-visitors?color=black)](https://npmjs.com/package/nuxt-visitors)
+[![npm downloads](https://img.shields.io/npm/dm/nuxt-visitors?color=black)](https://npm.chart.dev/nuxt-visitors)
+[![license](https://img.shields.io/github/license/HugoRCD/nuxt-visitors?color=black)](https://github.com/HugoRCD/nuxt-visitors/blob/main/LICENSE)
+
+<!-- /automd -->
+
+Add live visitor counting to your Nuxt website in seconds. WebSocket-based, type-safe, and completely automatic.
+
+## Features ⚡️
+
+- 🔄 Real-time updates via WebSocket
+- 🪄 Zero configuration needed
+- 🛠 Automatic connection management
+- 📊 Type-safe composable
+- 🧹 Auto cleanup on unmount
+
+## Installation
+
+Install the module to your Nuxt application with one command:
+
+```bash
+npx nuxi module add nuxt-visitors
+```
+
+<!-- automd:pm-install name="nuxt-visitors" -->
+
+```sh
+# ✨ Auto-detect
+npx nypm install nuxt-visitors
+
+# npm
+npm install nuxt-visitors
+
+# yarn
+yarn add nuxt-visitors
+
+# pnpm
+pnpm install nuxt-visitors
+
+# bun
+bun install nuxt-visitors
+
+# deno
+deno install nuxt-visitors
+```
+
+<!-- /automd -->
+
+## Usage
+
+```vue
+<script setup lang="ts">
+const { visitors } = useVisitors()
+</script>
+
+<template>
+  <div>Active users: {{ visitors }}</div>
+</template>
+```
+
+That's it! The module handles everything else automatically:
+- WebSocket connection management
+- Real-time updates
+- Reconnection logic
+- Error handling
+
+### Advanced usage
+
+The composable provides additional features:
+```ts
+const {
+visitors,     // Ref<number> - Current visitor count
+isConnected,  // Ref<boolean> - Connection status
+isLoading,    // Ref<boolean> - Loading state
+error,        // Ref<string | null> - Error message if any
+reconnect     // () => void - Manual reconnection
+} = useVisitors()
+```
+
+<!-- automd:fetch url="gh:hugorcd/markdown/main/src/contributions.md" -->
+
+## Contributing
+To start contributing, you can follow these steps:
+
+1. First raise an issue to discuss the changes you would like to make.
+2. Fork the repository.
+3. Create a branch using conventional commits and the issue number as the branch name. For example, `feat/123` or `fix/456`.
+4. Make changes following the local development steps.
+5. Commit your changes following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+6. If your changes affect the code, run tests using `bun run test`.
+7. Create a pull request following the [Pull Request Template](https://github.com/HugoRCD/markdown/blob/main/src/pull_request_template.md).
+   - To be merged, the pull request must pass the tests/workflow and have at least one approval.
+   - If your changes affect the documentation, make sure to update it.
+   - If your changes affect the code, make sure to update the tests.
+8. Wait for the maintainers to review your pull request.
+9. Once approved, the pull request will be merged in the next release !
+
+<!-- /automd -->
+
+<!-- automd:contributors license=Apache author=HugoRCD github=HugoRCD/nuxt-visitors -->
+
+Published under the [APACHE](https://github.com/HugoRCD/nuxt-visitors/blob/main/LICENSE) license.
+Made by [@HugoRCD](https://github.com/HugoRCD) and [community](https://github.com/HugoRCD/nuxt-visitors/graphs/contributors) 💛
+<br><br>
+<a href="https://github.com/HugoRCD/nuxt-visitors/graphs/contributors">
+<img src="https://contrib.rocks/image?repo=HugoRCD/nuxt-visitors" />
+</a>
+
+<!-- /automd -->
+
+<!-- automd:with-automd lastUpdate -->
+
+---
+
+_🤖 auto updated with [automd](https://automd.unjs.io) (last updated: Tue Jan 28 2025)_
+
+<!-- /automd -->

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,5 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare const _default: _nuxt_schema.NuxtModule<_nuxt_schema.ModuleOptions, _nuxt_schema.ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.d.ts

@@ -0,0 +1,5 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare const _default: _nuxt_schema.NuxtModule<_nuxt_schema.ModuleOptions, _nuxt_schema.ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-visitors",
+  "configKey": "visitors",
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,18 @@
+import { defineNuxtModule, createResolver, addImportsDir, addServerHandler } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-visitors",
+    configKey: "visitors"
+  },
+  setup(_options, _nuxt) {
+    const resolver = createResolver(import.meta.url);
+    addImportsDir(resolver.resolve("runtime/composables"));
+    addServerHandler({
+      route: "/api/_visitors_/ws",
+      handler: resolver.resolve("./runtime/server/api/visitors.ts")
+    });
+  }
+});
+
+export { module as default };

package/dist/runtime/composables/useVisitors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Composable for tracking real-time website visitors count via WebSocket
+ *
+ * Features:
+ * - Real-time visitors count updates
+ * - Automatic WebSocket connection management
+ * - Connection status tracking
+ * - Error handling
+ * - Automatic cleanup on component unmount
+ *
+ * @returns {Object} An object containing:
+ *  - visitors: Ref<number> - Current number of visitors
+ *  - isLoading: Ref<boolean> - Loading state indicator
+ *  - error: Ref<string | null> - Error message if any
+ *  - isConnected: Ref<boolean> - WebSocket connection status
+ *  - reconnect: () => void - Function to manually reconnect
+ */
+export declare function useVisitors(): {
+    visitors: any;
+    isLoading: any;
+    error: any;
+    isConnected: any;
+    reconnect: () => void;
+};

package/dist/runtime/composables/useVisitors.js

@@ -0,0 +1,99 @@
+export function useVisitors() {
+  const visitors = useState("visitors", () => 0);
+  const isLoading = ref(true);
+  const error = ref(null);
+  const wsRef = ref(null);
+  const isConnected = ref(false);
+  const isMounted = ref(true);
+  const RECONNECTION_DELAY = 5e3;
+  const WS_NORMAL_CLOSURE = 1e3;
+  const getWebSocketUrl = () => {
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const baseUrl = window.location.host.replace(/^(http|https):\/\//, "");
+    return `${protocol}//${baseUrl}/api/_visitors_/ws`;
+  };
+  const cleanup = () => {
+    if (wsRef.value) {
+      wsRef.value.close();
+      wsRef.value = null;
+    }
+    isConnected.value = false;
+    isLoading.value = false;
+  };
+  const handleMessage = (event) => {
+    if (!isMounted.value) return;
+    try {
+      const visitorCount = parseInt(event.data, 10);
+      if (!isNaN(visitorCount) && visitorCount >= 0) {
+        visitors.value = visitorCount;
+      } else {
+        throw new Error("Invalid visitor count received");
+      }
+    } catch (err) {
+      console.error("Failed to parse visitors WebSocket data:", err);
+      error.value = "Invalid data received";
+    }
+  };
+  const handleClose = (event) => {
+    console.log("Visitors WebSocket closed:", event.code, event.reason);
+    isConnected.value = false;
+    wsRef.value = null;
+    if (isMounted.value && event.code !== WS_NORMAL_CLOSURE) {
+      error.value = "Connection lost";
+      setTimeout(() => reconnect(), RECONNECTION_DELAY);
+    }
+  };
+  const initWebSocket = () => {
+    if (!isMounted.value) return;
+    cleanup();
+    try {
+      const ws = new WebSocket(getWebSocketUrl());
+      wsRef.value = ws;
+      ws.onopen = () => {
+        if (!isMounted.value) {
+          ws.close();
+          return;
+        }
+        console.log("Stats WebSocket connected");
+        isConnected.value = true;
+        isLoading.value = false;
+        error.value = null;
+      };
+      ws.onmessage = handleMessage;
+      ws.onclose = handleClose;
+      ws.onerror = (event) => {
+        if (!isMounted.value) return;
+        console.error("Visitors WebSocket error:", event);
+        error.value = "Connection error";
+      };
+    } catch (err) {
+      if (!isMounted.value) return;
+      console.error("Failed to initialize Visitors WebSocket:", err);
+      error.value = "Failed to initialize connection";
+      isLoading.value = false;
+    }
+  };
+  const reconnect = () => {
+    if (!isMounted.value) return;
+    error.value = null;
+    isLoading.value = true;
+    initWebSocket();
+  };
+  onMounted(() => {
+    if (import.meta.client) {
+      isMounted.value = true;
+      initWebSocket();
+    }
+  });
+  onBeforeUnmount(() => {
+    isMounted.value = false;
+    cleanup();
+  });
+  return {
+    visitors,
+    isLoading,
+    error,
+    isConnected,
+    reconnect
+  };
+}

package/dist/runtime/server/api/visitors.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/api/visitors.js

@@ -0,0 +1,54 @@
+class StatsWebSocketManager {
+  static instance;
+  connectedPeers = /* @__PURE__ */ new Set();
+  constructor() {
+  }
+  static getInstance() {
+    if (!this.instance) {
+      this.instance = new StatsWebSocketManager();
+    }
+    return this.instance;
+  }
+  addPeer(peer) {
+    this.connectedPeers.add(peer);
+    this.logConnectionStats();
+  }
+  removePeer(peer) {
+    this.connectedPeers.delete(peer);
+    this.logConnectionStats();
+  }
+  getActiveVisitors() {
+    return this.connectedPeers.size;
+  }
+  updateActiveVisitors(visitors) {
+    this.connectedPeers.forEach((peer) => {
+      peer.send(JSON.stringify(visitors));
+    });
+  }
+  logConnectionStats() {
+    console.log(`Active visitors connections: ${this.connectedPeers.size}`);
+  }
+}
+const wsManager = StatsWebSocketManager.getInstance();
+export default defineWebSocketHandler({
+  open(peer) {
+    try {
+      wsManager.addPeer(peer);
+      const visitors = wsManager.getActiveVisitors();
+      wsManager.updateActiveVisitors(visitors);
+    } catch (error) {
+      console.error("Visitors WebSocket open error:", error);
+      peer.close(1011, error instanceof Error ? error.message : "Unknown error");
+    }
+  },
+  close(peer) {
+    wsManager.removePeer(peer);
+    const visitors = wsManager.getActiveVisitors();
+    wsManager.updateActiveVisitors(visitors);
+    console.log("Visitors WebSocket disconnected:", peer.id);
+  },
+  error(peer, error) {
+    wsManager.removePeer(peer);
+    console.error("Visitors WebSocket error:", error);
+  }
+});

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "nuxt-visitors",
+  "version": "1.0.0",
+  "description": "My new Nuxt module",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/HugoRCD/nuxt-visitors/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HugoRCD/nuxt-visitors.git"
+  },
+  "funding": "https://github.com/sponsors/HugoRCD",
+  "author": "HugoRCD",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.15.3"
+  },
+  "devDependencies": {
+    "@hrcd/eslint-config": "^2.1.1",
+    "@nuxt/devtools": "^1.7.0",
+    "@nuxt/eslint-config": "^0.7.5",
+    "@nuxt/module-builder": "^0.8.4",
+    "@nuxt/schema": "^3.15.3",
+    "@nuxt/test-utils": "^3.15.4",
+    "@types/node": "latest",
+    "changelogen": "^0.5.7",
+    "eslint": "^9.19.0",
+    "nuxt": "3.15.2",
+    "typescript": "5.6.3",
+    "vitest": "^3.0.4",
+    "vue-tsc": "^2.2.0",
+    "automd": "^0.3.12"
+  },
+  "packageManager": "pnpm@8.6.5+sha1.a074a371066567dcdeb19a1d1bd9a78cf3c9faa3"
+}